TrueGrowth/openspec/changes/add-desktop-runtime-readiness/design.md

Context

TrueGrowth desktop already has a local API boundary, task center, Model Center, ComfyUI integration, FunClip-related readiness, social publishing bridge, and local persistence split between Electron userData and .truegrowth-runtime. Commercial delivery needs a first-run experience that treats these as one runtime estate instead of feature-by-feature setup fragments.

Goals

• Provide one product-level runtime readiness summary in Model Center.
• Make first-run setup safe for Windows and macOS customers.
• Download Hugging Face model assets with realtime progress and resumable status.
• Prefer bundled or per-user managed dependencies over asking users to install developer tools manually.
• Keep heavy runtimes stopped until the user starts or initializes the feature, avoiding machine-wide freezes.
• Give manual guidance when automation cannot legally or safely complete the step.

Non-Goals

• Silent administrator-level system modification.
• Guaranteed GPU support on every machine.
• Bundling every model in the desktop installer.
• Replacing ComfyUI, FunClip, social-auto-upload, or Agent-Reach internals.
• Exposing raw install logs, stack traces, command lines, or foreign-brand setup pages to customers.

Runtime Directory Strategy

• The packaged application directory is treated as read-only.
• Customer runtime state defaults to a per-user TrueGrowth directory:
  • macOS: Electron app.getPath('userData') or ~/Library/Application Support/TrueGrowth
  • Windows: %APPDATA%/TrueGrowth
• Runtime installs live under this directory, for example:
  • runtimes/ComfyUI
  • runtimes/python
  • runtimes/ffmpeg
  • models/comfyui
  • cache/huggingface
  • logs/runtime
• Development builds may keep using project-local paths, but the setup summary must explicitly report whether it is using development paths or customer runtime paths.

Dependency Resolution Strategy

Each dependency is represented as a readiness resource with:

• id, label, category, platforms
• status: ready, missing, needs_action, installing, downloading, failed, external, unsupported
• source: bundled, managed, system, configured, download, manual, development
• canAutoInstall, requiresAdmin, requiresRestart, requiresNetwork, licenseRequired
• version, path, sizeBytes, requiredBytes, availableBytes
• progress with bytes, percent, speed, ETA, stage, and task id when applicable
• actions such as install, download, openGuide, chooseMirror, configurePath, retry, clearPartial

Safe automation:

• Install or update dependencies only inside the managed runtime directory.
• Install Python packages into a managed venv or embedded Python when present.
• Clone or update ComfyUI only inside the managed ComfyUI directory.
• Download model files into ComfyUI model directories or managed model cache.
• Use bundled ffmpeg when present; otherwise guide the user or install managed ffmpeg only if the package is available in the app bundle or approved download source.

Manual guidance:

• If Git or Python is absent and no bundled/managed installer is available, show OS-specific install steps.
• If Windows requires Visual C++ runtime, long path support, or GPU driver/CUDA setup, report it as a guided prerequisite.
• If macOS blocks unsigned binaries or quarantine attributes, show customer-safe recovery steps and only remove quarantine for app-managed runtime files when allowed.

Mirror and Network Strategy

• Provide a runtime source selector with options such as:
  • Hugging Face official
  • configured mirror endpoint
  • custom endpoint
• Store the selected endpoint in local runtime settings.
• Apply the endpoint to Hugging Face CLI/API downloads through HF_ENDPOINT.
• Disable Xet by default when it improves compatibility for large downloads, while keeping the setting visible in diagnostics.
• Preflight network access to GitHub, Hugging Face endpoint, and selected mirror with customer-facing status.

Hugging Face Download Progress

• Single-file downloads should stream response bytes and patch the runtime task with:
  • downloaded bytes
  • total bytes when known
  • percent
  • speed
  • ETA
  • target path
• Snapshot downloads should prefer a controllable download helper over opaque child-process output when possible. The helper should emit structured progress events for files and total bytes.
• If the Hugging Face CLI is used as a fallback, parse progress output when possible; otherwise report stage progress and cache status.
• Incomplete downloads must be resumable when the underlying cache supports it, and the UI must show whether cache cleanup or retry is recommended.

Model Center UX

• Add a first-run environment panel in Model Center before model cards.
• Group readiness by:
  • System prerequisites
  • Local image / ComfyUI
  • AI clipping / FunClip / ASR
  • Digital human / voice
  • Publishing / browser automation
  • Network and mirrors
• Every group shows readiness, progress, next action, and whether other features can still be used.
• Primary actions use TrueGrowth orange and feed into task center.
• The lower-left global task status remains the global progress entry; no fixed topbar is introduced.

Safety and Resource Controls

• Do not auto-start heavy services at app boot.
• Before starting ComfyUI/FunClip/ASR, check memory/disk/GPU basics and show expected resource use.
• Allow one runtime initialization task per dependency group at a time.
• Cancellation should stop downloads where possible and leave resumable cache state.
• Logs stay available in diagnostics but are summarized before being shown to users.

Risks

• Cross-platform dependency installation is fragile. Mitigation: prefer managed/bundled dependencies and degrade to exact guidance.
• Hugging Face snapshot progress is harder than single-file progress. Mitigation: implement a structured helper for official downloads, with CLI parsing as fallback.
• Large local models can exhaust customer disks. Mitigation: preflight every model, show target path and required space, and keep partial-cache cleanup explicit.
• Heavy AI runtimes can freeze weak machines. Mitigation: no automatic heavy service start on boot, readiness/resource checks before launch, and clear unsupported states.