Jammy/TrueGrowth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial TrueGrowth source import

Browse Source
This commit is contained in:
Jammy
2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
openspec/changes/add-desktop-runtime-readiness/design.md Normal file
View File

@@ -0,0 +1,101 @@
## 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.

28
openspec/changes/add-desktop-runtime-readiness/proposal.md Normal file
View File

@@ -0,0 +1,28 @@
# Change: Add commercial desktop runtime onboarding
## Why
TrueGrowth desktop delivery must work on a fresh customer computer without exposing raw developer setup work. Local AI features currently depend on Git, Python, ffmpeg, ComfyUI, Hugging Face downloads, model caches, and feature-specific sidecars, but the product only exposes partial readiness and coarse task progress. Customers need a single Model Center surface that can diagnose, initialize, download, and recover local runtime dependencies with clear guidance.
## What Changes
- Expand the desktop runtime readiness contract into a product-wide onboarding and initialization layer surfaced in Model Center.
- Add Windows/macOS first-run checks for OS, architecture, writable runtime directories, disk space, network reachability, Git, Python 3.10+, ffmpeg, ComfyUI, Hugging Face tooling/cache, local model assets, FunClip/ASR, digital-human, voice, and publishing dependencies.
- Add guided dependency resolution: use bundled/runtime-managed dependencies where available, offer safe automatic installers when supported, and provide clear manual steps when administrator permission or external installers are required.
- Add Hugging Face mirror/source selection and realtime model download progress with bytes, percent, speed, ETA, resumable cache awareness, and failure recovery.
- Move customer runtime installs and model caches out of the packaged app directory into a writable per-user TrueGrowth runtime directory by default.
- Surface all initialization tasks through the existing task center and Model Center readiness panels with customer-facing copy, not raw command output.
## Impact
- Affected specs:
- `desktop-runtime-readiness`
- `runtime-model-discovery`
- Affected code:
- `scripts/truegrowth-local-api.mjs`
- `apps/web/src/workbench/local-runtime-client.ts`
- `apps/web/src/workbench/WorkbenchShell.tsx`
- `apps/web/src/workbench/workbench.scss`
- desktop packaging config under `apps/electron/`
- future runtime bootstrap/download helper modules under `scripts/`
## Notes
- This change does not promise every customer computer can run every local model. It promises that TrueGrowth will detect constraints, initialize what is safely automatable, and guide unresolved prerequisites in a commercial-grade flow.
- Destructive cleanup of caches, system package installation, and administrator-level changes require explicit user action.

93
openspec/changes/add-desktop-runtime-readiness/specs/desktop-runtime-readiness/spec.md Normal file
View File

@@ -0,0 +1,93 @@
## ADDED Requirements
### Requirement: Product-Level Runtime Readiness Summary
The system SHALL expose a product-level local runtime readiness summary for desktop delivery.
#### Scenario: Fresh customer computer opens Model Center
- **GIVEN** TrueGrowth is running on a desktop computer for the first time
- **WHEN** the user opens Model Center
- **THEN** the Local API SHALL report readiness for system prerequisites, network sources, ComfyUI image generation, model downloads, AI clipping, digital-human, voice, and publishing dependencies
- **AND** every dependency SHALL include status, source, platform support, path or configuration summary, next action, and customer-safe detail text
- **AND** the UI SHALL not show raw stack traces, raw command output, or developer-only copy
#### Scenario: Runtime uses a writable customer directory
- **GIVEN** the app is running from a packaged desktop install
- **WHEN** the readiness summary resolves runtime paths
- **THEN** managed runtimes, model caches, logs, and downloaded model files SHALL default to a writable per-user TrueGrowth runtime directory
- **AND** the packaged application directory SHALL not be used as the default write target
### Requirement: Guided Dependency Initialization
The system SHALL guide or perform dependency initialization for customer machines.
#### Scenario: Dependency can be installed safely by TrueGrowth
- **GIVEN** a missing dependency can be installed inside the managed runtime directory without administrator privileges
- **WHEN** the user starts initialization
- **THEN** the system SHALL create a runtime task
- **AND** install or prepare the dependency in the managed directory
- **AND** update readiness and task progress until the dependency is ready or failed
#### Scenario: Dependency requires external action
- **GIVEN** a missing dependency requires administrator permission, a system installer, GPU driver setup, or another action TrueGrowth cannot safely automate
- **WHEN** the user views the readiness item
- **THEN** the system SHALL show OS-specific guidance and a retry/detect action
- **AND** the system SHALL not silently modify protected system locations
#### Scenario: Git or Python is missing
- **GIVEN** ComfyUI or another runtime needs Git or Python 3.10+
- **WHEN** the system checks prerequisites
- **THEN** the readiness summary SHALL report whether a bundled, managed, configured, or system Git/Python is available
- **AND** if no valid option exists, the UI SHALL offer automatic managed setup when supported or exact Windows/macOS installation guidance otherwise
### Requirement: Hugging Face Source Selection and Download Progress
The system SHALL support Hugging Face source selection and realtime model download progress.
#### Scenario: User chooses a download source
- **GIVEN** the user needs to download a Hugging Face-hosted model
- **WHEN** the user opens Model Center download settings
- **THEN** the UI SHALL allow official, configured mirror, or custom endpoint selection
- **AND** the selected endpoint SHALL be stored in local runtime settings
- **AND** model download tasks SHALL use that endpoint for Hugging Face downloads
#### Scenario: Single-file model download runs
- **GIVEN** the user starts a single-file model download such as a ComfyUI checkpoint
- **WHEN** the download is in progress
- **THEN** the runtime task SHALL expose downloaded bytes, total bytes when known, percent, speed, ETA, stage text, and target path
- **AND** Model Center and task center SHALL display the realtime progress
#### Scenario: Snapshot model download runs
- **GIVEN** the user starts a multi-file Hugging Face snapshot download such as Qwen-Image
- **WHEN** file or aggregate progress is available
- **THEN** the runtime task SHALL expose file-level or aggregate progress
- **AND** when only cache/stage progress is available, the UI SHALL clearly label the progress as stage progress instead of an exact byte percentage
#### Scenario: Download is interrupted
- **GIVEN** a model download fails or the app exits before completion
- **WHEN** the user returns to Model Center
- **THEN** the system SHALL detect partial cache state where possible
- **AND** offer retry/resume or explicit cache cleanup guidance without deleting data automatically
### Requirement: Model Center Initialization Surface
Model Center SHALL be the primary discovery and initialization surface for local runtime readiness.
#### Scenario: User prepares a fresh desktop environment
- **WHEN** the user opens Model Center
- **THEN** the page SHALL show grouped readiness for system prerequisites, ComfyUI/image models, AI clipping, digital-human/voice, publishing, and network sources
- **AND** each group SHALL show readiness, progress, primary action, secondary guidance, and whether related product features are usable
- **AND** actions SHALL create or link to runtime tasks in the existing task center
#### Scenario: A heavy runtime is available but stopped
- **GIVEN** ComfyUI, FunClip, or another heavy local service is installed but not running
- **WHEN** Model Center renders the readiness group
- **THEN** the UI SHALL show it as installed but stopped
- **AND** the system SHALL not auto-start it on app boot
- **AND** the start action SHALL perform resource checks before launching
### Requirement: Feature Readiness Degradation
Feature pages that depend on local runtimes SHALL degrade through the shared readiness model.
#### Scenario: User opens a feature before initialization is complete
- **GIVEN** a feature depends on an unavailable runtime resource
- **WHEN** the user opens that feature
- **THEN** the feature page SHALL show concise setup status and a Model Center action
- **AND** the feature SHALL preserve usable non-runtime controls where possible
- **AND** failures SHALL be expressed as setup guidance rather than raw runtime errors

23
openspec/changes/add-desktop-runtime-readiness/specs/runtime-model-discovery/spec.md Normal file
View File

@@ -0,0 +1,23 @@
## MODIFIED Requirements
### Requirement: Runtime Model Discovery Includes Local Readiness
The system SHALL include local runtime readiness and model acquisition state when exposing runtime-discovered local models.
#### Scenario: Local image model is downloaded but runtime is stopped
- **GIVEN** a ComfyUI model file is present in the managed model directory
- **AND** ComfyUI is installed but not running
- **WHEN** runtime model discovery builds local image model entries
- **THEN** the model SHALL remain discoverable as installed
- **AND** its readiness metadata SHALL indicate that the runtime must be started before generation
#### Scenario: Local model is still downloading
- **GIVEN** a model download task is running or resumable
- **WHEN** Model Center requests model assets
- **THEN** the model asset SHALL include download status and progress metadata
- **AND** final generation selectors SHALL not treat the model as runnable until installation/discovery is complete
#### Scenario: Download source changes
- **GIVEN** the user changes the Hugging Face endpoint or mirror in Model Center
- **WHEN** runtime model discovery or model download preflight runs
- **THEN** the selected source SHALL be reflected in model asset metadata and future download tasks
- **AND** already installed models SHALL remain usable without requiring re-download

42
openspec/changes/add-desktop-runtime-readiness/tasks.md Normal file
View File

@@ -0,0 +1,42 @@
## 1. Runtime Contract
- [x] 1.1 Define a shared readiness resource schema for system prerequisites, network sources, runtime installs, model assets, services, and feature groups.
- [x] 1.2 Add Local API endpoints for product-level readiness summary, dependency actions, mirror settings, and runtime diagnostics.
- [x] 1.3 Persist runtime settings for managed directory, ComfyUI path, Hugging Face endpoint, mirror choice, and dependency resolution state.
- [x] 1.4 Detect packaged desktop vs local development paths and default production runtime writes to the per-user TrueGrowth directory.
- [x] 1.5 Add platform/architecture detection for Windows, macOS Intel, macOS Apple Silicon, and unsupported environments.
## 2. Dependency Detection and Initialization
- [x] 2.1 Detect Git, Python 3.10+, ffmpeg, Hugging Face tooling, ComfyUI, ComfyUI custom nodes, FunClip/ASR requirements, digital-human/voice model packages, and publishing runtime dependencies.
- [ ] 2.2 Implement managed installation actions where safe: managed runtime directories, Python venv/package setup, ComfyUI clone/update, app-managed custom nodes, and bundled ffmpeg detection.
- [ ] 2.3 Add external-action guidance for prerequisites that cannot be safely installed automatically, including Windows/macOS Git/Python, GPU driver/CUDA/MPS notes, and permission issues.
- [ ] 2.4 Add resource preflight for disk, memory, network reachability, writable directories, and heavy-runtime start eligibility.
- [ ] 2.5 Prevent app boot from auto-starting heavy runtimes; start only from explicit user action with readiness checks.
## 3. Hugging Face Downloads
- [x] 3.1 Add Hugging Face endpoint/mirror selection and preflight checks in the Local API.
- [x] 3.2 Replace single-file model downloads with streaming byte progress updates.
- [ ] 3.3 Add snapshot download helper or structured wrapper that reports file/aggregate progress where possible.
- [ ] 3.4 Persist download progress, target paths, cache status, partial/incomplete state, retry/resume information, and errors.
- [x] 3.5 Update ComfyUI model download preflight to include selected endpoint, target directory, disk requirements, and resumable cache state.
## 4. Model Center UI
- [x] 4.1 Add a Model Center environment panel grouped by system prerequisites, network/mirrors, ComfyUI/image models, AI clipping, digital-human/voice, and publishing.
- [x] 4.2 Display readiness state, source, version/path, progress, next action, and safe guidance for each group.
- [x] 4.3 Add mirror/source selection UI with official/mirror/custom endpoint options.
- [x] 4.4 Show realtime model download progress in Model Center and ensure tasks link to the existing global task center.
- [ ] 4.5 Keep feature-specific setup callouts aligned with shared readiness and route unresolved setup actions back to Model Center.
- [x] 4.6 Preserve the `/image` golden page visual standard, light/dark themes, orange primary actions, compact desktop density, and no topbar reintroduction.
## 5. Runtime Model Discovery and Feature Integration
- [x] 5.1 Include local model download/readiness metadata in model assets and runtime-discovered local image entries.
- [ ] 5.2 Ensure downloaded-but-stopped local image models are discoverable but clearly marked as requiring runtime start.
- [ ] 5.3 Ensure downloading or incomplete models do not appear as runnable final selector choices.
- [ ] 5.4 Update AI clipping, digital-human, voice, publishing, and ComfyUI feature pages to consume shared readiness status instead of local one-off error copy.
## 6. Verification
- [ ] 6.1 Add unit tests for readiness normalization, platform detection, mirror setting persistence, and download progress math.
- [ ] 6.2 Add Local API verifier coverage for fresh-machine simulations: missing Git/Python, managed runtime path, mirror selection, model download progress, interrupted download, and installed-but-stopped ComfyUI.
- [ ] 6.3 Add frontend tests or focused component checks for Model Center readiness rendering and progress states.
- [x] 6.4 Run `node --check scripts/truegrowth-local-api.mjs`.
- [x] 6.5 Run `pnpm exec tsc -p apps/web/tsconfig.app.json --noEmit` or the closest available project typecheck.
- [x] 6.6 Browser-verify Model Center against the `/image` golden UI standard with screenshots, console checks, and one primary readiness/download interaction.