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

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.