Initial TrueGrowth source import

openspec/changes/add-commercial-desktop-packaging/design.md

@@ -0,0 +1,54 @@
+## Context
+The repository has a React/Vite web renderer, an Electron shell, a Local API started from the Electron main process, and a Model Center readiness flow for customer runtime initialization. Development launch currently loads `http://127.0.0.1:7200`; commercial packages need to load built static renderer files and run from a read-only application directory.
+
+## Goals
+- Produce branded macOS and Windows desktop packages without developer setup on the customer machine.
+- Bundle the Electron main/preload files, web build output, Local API script, lightweight assets, and package metadata needed at runtime.
+- Preserve managed per-user runtime directories for writable state, downloaded models, logs, caches, and optional runtimes.
+- Make missing heavy dependencies actionable in Model Center instead of requiring technical installation during app install.
+- Provide one documented build flow that the product owner can repeat.
+
+## Non-Goals
+- Shipping GPU drivers, CUDA, system Python, Git, or every local AI model inside the installer.
+- Silent administrator-level system mutation.
+- Code signing certificates, Apple notarization credentials, or Windows EV/OV certificate procurement.
+- Guaranteeing that macOS can produce a fully signed Windows installer locally.
+
+## Packaging Strategy
+- Use Electron Builder as the desktop packager because the project already uses Electron and needs macOS/Windows installer targets, app metadata, files staging, and signing hooks.
+- Stage a production Electron app directory under `dist/desktop/app` containing:
+  - `apps/electron/main.mjs`
+  - `apps/electron/preload.cjs`
+  - `apps/electron/assets/*`
+  - `dist/apps/web/**`
+  - `scripts/truegrowth-local-api.mjs`
+  - runtime helper scripts that are required by Local API in packaged mode
+  - a minimal package manifest used by Electron Builder
+- Electron main resolves `VITE_DEV_SERVER_URL` in development and `dist/apps/web/index.html` in packaged production.
+- The Local API receives packaged-mode environment variables so it can default writable runtime state to Electron `userData` instead of project-local paths.
+
+## Runtime Boundary
+- Built-in app shell functionality must work after install with no terminal, Node.js, pnpm, Vite, or developer environment on the customer computer.
+- Heavy optional features rely on the existing Model Center readiness model:
+  - If a managed runtime is bundled or can be installed into the per-user runtime directory, the app may start a guided install task.
+  - If a dependency requires system permissions or external setup, Model Center must show customer-safe OS-specific guidance.
+  - Large models are downloaded after install into the managed runtime/model directories.
+
+## Release Artifacts
+- macOS:
+  - local developer artifact: `.dmg` or `.zip`
+  - commercial artifact: signed and notarized `.dmg`
+- Windows:
+  - local/CI artifact: `.exe` NSIS installer and optional portable build
+  - commercial artifact: Authenticode-signed installer
+- Unsigned artifacts are acceptable for internal testing only and must be labeled as such in docs/output.
+
+## Verification
+- Build web renderer successfully.
+- Build desktop package target successfully on the host platform.
+- Inspect packaged artifact metadata for TrueGrowth name, app id, version, and icon presence.
+- Launch the packaged app where the host allows it and verify:
+  - renderer loads from file assets, not dev server
+  - Local API responds on `127.0.0.1:48177/local-api/health`
+  - Model Center shows runtime readiness/setup guidance
+- For Windows packages, verify on Windows or CI rather than relying only on macOS cross-build output.

openspec/changes/add-commercial-desktop-packaging/proposal.md

@@ -0,0 +1,26 @@
+# Change: Add commercial desktop packaging flow
+
+## Why
+TrueGrowth desktop already runs in development, but customer delivery needs a repeatable commercial packaging flow for macOS and Windows. Customers should receive a branded installer/app bundle that starts the renderer and Local API without developer setup, while heavy local AI dependencies are either bundled/managed or initialized through Model Center.
+
+## What Changes
+- Add a production Electron packaging pipeline for macOS and Windows installers with TrueGrowth branding, icons, app identifiers, packaged renderer assets, and local preload/main assets.
+- Add release scripts that build the web renderer, stage Electron runtime files, generate package metadata, and invoke the desktop packager per target platform.
+- Keep Local API and product-critical desktop services bundled with the app; route optional heavyweight runtimes, model downloads, and environment setup through Model Center readiness actions.
+- Document the internal build process, customer installation expectations, runtime directory behavior, and code-signing/notarization requirements.
+- Add verification steps for packaged startup, Local API health, Model Center runtime guidance, and macOS/Windows artifact presence.
+
+## Impact
+- Affected specs:
+  - `desktop-packaging`
+  - `desktop-runtime-readiness`
+- Affected code:
+  - `package.json`
+  - `apps/electron/`
+  - `scripts/`
+  - `docs/`
+  - packaging config such as Electron Builder metadata
+
+## Notes
+- macOS artifacts can be built on macOS. Windows commercial installers should be built on Windows or CI; cross-building from macOS is not a reliable signing-ready release path.
+- This change does not bundle large AI model files by default. Model Center remains the customer-facing path for downloading or connecting heavyweight local models and runtimes.

openspec/changes/add-commercial-desktop-packaging/specs/desktop-packaging/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Branded Desktop Release Artifacts
+The system SHALL provide branded desktop release artifacts for macOS and Windows customers.
+
+#### Scenario: macOS package is built
+- **WHEN** the desktop packaging flow runs on macOS for the macOS target
+- **THEN** it SHALL produce a TrueGrowth-branded app artifact such as DMG or ZIP
+- **AND** the artifact SHALL use TrueGrowth product name, app identifier, version, and icon metadata
+- **AND** the app SHALL not require Node.js, pnpm, Vite, or a repo checkout on the customer machine
+
+#### Scenario: Windows package is built
+- **WHEN** the desktop packaging flow runs on Windows or a Windows CI runner
+- **THEN** it SHALL produce a TrueGrowth-branded Windows installer artifact
+- **AND** the artifact SHALL use TrueGrowth product name, app identifier, version, and icon metadata
+- **AND** the app SHALL not require Node.js, pnpm, Vite, or a repo checkout on the customer machine
+
+### Requirement: Packaged Renderer and Local API Startup
+The packaged desktop app SHALL start from bundled application assets.
+
+#### Scenario: Packaged app starts
+- **GIVEN** the app is launched from a packaged install
+- **WHEN** Electron creates the main window
+- **THEN** it SHALL load the built renderer from bundled files
+- **AND** it SHALL start the Local API from bundled scripts
+- **AND** it SHALL set packaged-mode runtime paths so writable state is stored outside the read-only app directory
+
+#### Scenario: Development app starts
+- **GIVEN** the app is launched by the development command
+- **WHEN** a dev server URL is provided
+- **THEN** Electron MAY load the renderer from the dev server
+- **AND** development behavior SHALL remain available for local debugging
+
+### Requirement: Model Center Owns Optional Runtime Setup
+The packaged app SHALL route optional heavy runtime setup through Model Center.
+
+#### Scenario: Heavy dependency is not bundled
+- **GIVEN** a customer opens a feature that needs ComfyUI, FunClip, model files, or another heavy local runtime
+- **WHEN** the dependency is missing
+- **THEN** the app SHALL show a customer-safe setup state that links to Model Center
+- **AND** Model Center SHALL offer managed install/download actions or OS-specific guidance
+- **AND** the customer SHALL not need technical staff to run repo commands manually
+
+### Requirement: Release Documentation
+The project SHALL document repeatable commercial desktop packaging.
+
+#### Scenario: Product owner needs to build a release
+- **WHEN** the product owner follows the desktop packaging documentation
+- **THEN** the docs SHALL explain prerequisites, commands, output directories, target-platform limits, runtime dependency policy, and signing/notarization steps
+- **AND** the docs SHALL distinguish unsigned internal-test artifacts from commercial signed artifacts

openspec/changes/add-commercial-desktop-packaging/tasks.md

@@ -0,0 +1,22 @@
+## 1. Packaging Setup
+- [x] 1.1 Add Electron Builder and packaging metadata for macOS and Windows targets.
+- [x] 1.2 Add app staging script that copies the production renderer, Electron main/preload, assets, Local API, and required helper scripts into a packageable app directory.
+- [x] 1.3 Add package scripts for macOS, Windows, current host, and all desktop targets.
+- [x] 1.4 Ensure packaged Electron loads local renderer files and sets packaged-mode runtime environment.
+
+## 2. Runtime Integration
+- [x] 2.1 Confirm Local API starts from the packaged app without requiring pnpm, Vite, or a repo checkout.
+- [x] 2.2 Confirm writable runtime paths use customer user-data locations in packaged mode.
+- [x] 2.3 Keep heavyweight dependency setup routed through Model Center readiness actions.
+
+## 3. Documentation
+- [x] 3.1 Document customer artifact expectations for macOS and Windows.
+- [x] 3.2 Document repeatable local/CI build commands, prerequisites, and output paths.
+- [x] 3.3 Document signing/notarization requirements and unsigned internal-test limitations.
+
+## 4. Verification
+- [x] 4.1 Run syntax checks for packaging scripts and Electron main/preload files.
+- [x] 4.2 Run the web production build.
+- [x] 4.3 Build the macOS package on this macOS host.
+- [x] 4.4 Attempt or document Windows package build constraints; build on Windows/CI when available.
+- [x] 4.5 Smoke-check packaged startup and Local API health where possible.