55 lines
3.6 KiB
Markdown
55 lines
3.6 KiB
Markdown
## 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.
|