# Plan 1: Release Tool (Node.js CLI)

## Overview

A Node.js CLI tool for automating the release process of Open Core Business Suite:
- Version bumping across all components
- Changelog generation from git commits
- ZIP packaging (full + differential updates)
- Upload to website API
- GitHub releases

**Location:** `/Volumes/Storage/Projects/CZ/OpenCoreBusinessSuite/release-tool/`

---

## System Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           CZ App Studio Ecosystem                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐    │
│  │   Release Tool   │────▶│  Website (API)   │◀────│ Customer Backend │    │
│  │    (Node.js)     │     │    (Laravel)     │     │    (Laravel)     │    │
│  └──────────────────┘     └──────────────────┘     └──────────────────┘    │
│          │                        │                        │               │
│          │                        │                        │               │
│          ▼                        ▼                        ▼               │
│  ┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐    │
│  │  GitHub Releases │     │   File Storage   │     │   Mobile Apps    │    │
│  │   (Backup/CI)    │     │ (Downloads/ZIPs) │     │    (Flutter)     │    │
│  └──────────────────┘     └──────────────────┘     └──────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Components Managed

| Component         | Repository                     | Versioning Files               |
| ----------------- | ------------------------------ | ------------------------------ |
| Backend (Laravel) | open_core_bs_backend           | `config/variables.php`         |
| 44 Modules        | (within backend)               | `Modules/*/module.json`        |
| Employee App      | apps/open_core_employee_app    | `pubspec.yaml` + build configs |
| Connect App       | apps/open_core_connect         | `pubspec.yaml` + build configs |
| Field Sales App   | apps/open_core_field_sales_app | `pubspec.yaml` + build configs |
| Attendance Device | apps/OpenCoreAttendance        | `app/build.gradle.kts`         |

---

## Directory Structure

```
release-tool/
├── package.json
├── bin/
│   └── release-cli.js              # CLI entry point
├── src/
│   ├── index.js
│   ├── commands/
│   │   ├── status.js               # Show current versions
│   │   ├── version.js              # Version bumping
│   │   ├── changelog.js            # Changelog generation
│   │   ├── package.js              # ZIP packaging (full + update)
│   │   ├── release.js              # Full release workflow
│   │   └── upload.js               # Upload to website API
│   ├── parsers/
│   │   ├── git-log.js              # Parse git commits
│   │   ├── module-json.js          # Parse module.json
│   │   ├── pubspec.js              # Parse Flutter pubspec.yaml
│   │   └── gradle.js               # Parse Android build.gradle
│   ├── generators/
│   │   ├── changelog.js            # Generate CHANGELOG.md
│   │   ├── release-notes.js        # GitHub release notes
│   │   └── update-manifest.js      # Generate update manifest JSON
│   ├── packagers/
│   │   ├── backend-full.js         # Full installation ZIP
│   │   ├── backend-update.js       # Update-only ZIP (changed files)
│   │   ├── addon.js                # Addon module ZIPs
│   │   └── mobile.js               # Mobile app builds
│   ├── uploaders/
│   │   └── website-api.js          # Upload to czappstudio.com API
│   └── utils/
│       ├── git.js
│       ├── file.js
│       └── config.js
├── templates/
│   ├── changelog.md.hbs
│   └── release-notes.md.hbs
└── release.config.js
```

---

## CLI Commands

### Status

```bash
npx release-cli status                    # All components
npx release-cli status --component=backend
```

### Version Bumping

```bash
npx release-cli version bump --type=patch
npx release-cli version bump-module Payroll --type=minor
npx release-cli version bump-changed --type=patch    # Auto-detect changed modules
npx release-cli version bump-app employee --type=minor
```

### Changelog

```bash
npx release-cli changelog generate --since=v5.0.1
npx release-cli changelog generate --module=Payroll
```

### Packaging

```bash
# Full installation packages
npx release-cli package --type=core          # Main app + *Core modules (non-SaaS)
npx release-cli package --type=saas          # Main app + *Core modules + MultiTenancyCore
npx release-cli package --addon=Payroll      # Single addon
npx release-cli package --addon=MultiTenancyCore  # SaaS upgrade addon ($50)

# UPDATE packages (differential - changed files only)
npx release-cli package:update --from=v5.0.0 --to=v5.0.1
npx release-cli package:update --addon=Payroll --from=1.0.2 --to=1.0.3

# Mobile builds
npx release-cli package --app=employee --platform=android
```

### Upload to Website

```bash
npx release-cli upload --file=releases/opencorebs-v5.0.1.zip --product=1
npx release-cli upload --file=releases/payroll-addon-v1.0.3.zip --product=15
```

### Full Release Workflow

```bash
npx release-cli release --dry-run           # Preview
npx release-cli release                     # Interactive
```

---

## Update Package Structure

### CORE APP Update (Main Product)

Contains only core framework + core modules. No addon modules included.

```
opencorebs-update-v5.0.0-to-v5.0.1.zip
├── UPDATE_MANIFEST.json
├── files/
│   ├── app/                      # Core Laravel app changes
│   │   └── Services/
│   │       └── SomeService.php
│   ├── Modules/                  # ONLY *Core MODULES (suffix = Core)
│   │   ├── SystemCore/
│   │   ├── AccountingCore/
│   │   ├── PMCore/
│   │   ├── CRMCore/
│   │   └── WMSInventoryCore/
│   │   # NOTE: MultiTenancyCore included only in SaaS package
│   ├── config/
│   │   └── variables.php
│   └── resources/
├── migrations/
│   └── 2025_01_08_xxx.php
├── CHANGELOG.md
└── UPDATE.md
```

### ADDON Update (Each addon separately)

Each addon has its own version and update package.

```
payroll-addon-update-v1.0.2-to-v1.0.3.zip
├── UPDATE_MANIFEST.json
├── files/
│   └── Modules/
│       └── Payroll/              # ONLY this addon's files
│           ├── App/
│           ├── Database/
│           ├── resources/
│           └── module.json       # Updated version
├── migrations/
│   └── 2025_01_08_payroll_xxx.php
├── CHANGELOG.md
└── UPDATE.md
```

### UPDATE_MANIFEST.json (Core App Example)

```json
{
  "product_type": "core",
  "from_version": "5.0.0",
  "to_version": "5.0.1",
  "release_date": "2025-01-08",
  "files": {
    "added": ["app/Services/NewService.php"],
    "modified": ["config/variables.php", "Modules/HRCore/App/..."],
    "deleted": []
  },
  "migrations": ["2025_01_08_123456_add_column.php"],
  "requires_composer_update": false,
  "requires_npm_install": false,
  "post_update_commands": ["php artisan migrate", "php artisan optimize:clear"]
}
```

### UPDATE_MANIFEST.json (Addon Example)

```json
{
  "product_type": "addon",
  "addon_uid": "payroll",
  "addon_name": "Payroll",
  "from_version": "1.0.2",
  "to_version": "1.0.3",
  "release_date": "2025-01-08",
  "requires_core_version": ">=5.0.0",
  "files": {
    "added": [],
    "modified": ["Modules/Payroll/App/Services/PayrollService.php"],
    "deleted": []
  },
  "migrations": ["2025_01_08_payroll_fix.php"],
  "post_update_commands": ["php artisan module:migrate Payroll"]
}
```

---

## Mobile App Releases

### Overview

Mobile apps are distributed as **source code only**. Customers receive:

- Full source code ZIP when they purchase
- Email notification when new versions are released
- Download link to updated source code

### Release Tool Commands for Mobile Apps

```bash
# Bump mobile app version
npx release-cli version bump-app employee --type=minor

# Generate changelog for mobile app
npx release-cli changelog generate --app=employee

# Create source code package
npx release-cli package --app=employee
# Output: releases/open-core-employee-app-v5.1.0-source.zip

# Upload to website
npx release-cli upload --app=employee --version=5.1.0
```

### Mobile App Package Contents

```
open-core-employee-app-v5.1.0-source.zip
├── lib/                    # Dart source code
├── android/                # Android project
├── ios/                    # iOS project
├── pubspec.yaml           # Dependencies (version updated)
├── CHANGELOG.md           # Version changelog
├── README.md              # Setup instructions
└── .env.example           # Environment template
```

---

## Implementation Phases

### Phase 1: Core Infrastructure

1. Create release-tool directory structure
2. Set up package.json with dependencies (Commander, Inquirer, Chalk, Ora, Archiver)
3. Create CLI entry point
4. Implement configuration loader (release.config.js)

### Phase 2: Version Parsers

1. Implement module.json parser
2. Implement pubspec.yaml parser (Flutter apps)
3. Implement build.gradle.kts parser (Kotlin app)
4. Implement config/variables.php parser (main version)

### Phase 3: Git & Changelog

1. Implement git log parser (conventional commits)
2. Implement changelog generator (Handlebars templates)
3. Implement release notes generator
4. Implement status command

### Phase 4: Packaging

1. Implement full package creation (core + saas)
2. Implement differential update package creation
3. Implement addon package creation
4. Generate UPDATE_MANIFEST.json
5. Implement mobile app source code packaging

### Phase 5: Upload & Integration

1. Implement website API uploader
2. Implement GitHub release creation (gh CLI)
3. Create interactive release workflow command
4. Implement dry-run mode

---

## Files to Create

```
/Volumes/Storage/Projects/CZ/OpenCoreBusinessSuite/release-tool/
├── package.json
├── bin/release-cli.js
├── src/
│   ├── index.js
│   ├── commands/
│   │   ├── status.js
│   │   ├── version.js
│   │   ├── changelog.js
│   │   ├── package.js
│   │   ├── release.js
│   │   └── upload.js
│   ├── parsers/
│   │   ├── git-log.js
│   │   ├── module-json.js
│   │   ├── pubspec.js
│   │   └── gradle.js
│   ├── generators/
│   │   ├── changelog.js
│   │   ├── release-notes.js
│   │   └── update-manifest.js
│   ├── packagers/
│   │   ├── backend-full.js
│   │   ├── backend-update.js
│   │   ├── addon.js
│   │   └── mobile.js
│   ├── uploaders/
│   │   └── website-api.js
│   └── utils/
│       ├── git.js
│       ├── file.js
│       └── config.js
├── templates/
│   ├── changelog.md.hbs
│   └── release-notes.md.hbs
└── release.config.js
```

---

## Verification

### Test Commands

```bash
# Status
npx release-cli status
npx release-cli status --component=backend

# Version bumping
npx release-cli version bump --type=patch --dry-run

# Changelog
npx release-cli changelog generate --since=v5.0.0

# Packaging
npx release-cli package --type=core --dry-run
npx release-cli package:update --from=v5.0.0 --to=v5.0.1 --dry-run

# Full release
npx release-cli release --dry-run
```

### Verification Checklist

- [ ] Status command shows all component versions
- [ ] Version bump updates correct files
- [ ] Changelog includes all commits since last tag
- [ ] Full package includes correct files (no .git, node_modules, etc.)
- [ ] Update package only includes changed files
- [ ] UPDATE_MANIFEST.json is valid JSON with correct structure
- [ ] Upload to website API succeeds with valid credentials
- [ ] Dry-run mode doesn't make any changes