Make cache:prepare self-contained in fresh worktrees

[habdelra]

Summary

Resolves CS-10560: cache:prepare now works in a completely fresh worktree with zero running services.

• Auto-provision build artifacts: Host dist, boxel-ui dist, and boxel-icons dist are automatically symlinked from the root repo (fast) or built from source (fallback) when missing in a worktree. Uses fs.symlinkSync for cross-platform compatibility.

• Managed icon server lifecycle: Always starts our own icon server process instead of hoping an externally-detected server stays alive. Falls back to the existing dev server if port 4206 is already taken (with EADDRINUSE retry for slow-starting external servers).

• Indexing progress bar: Pre-allocates the worker-manager port and polls its /_indexing-status JSON endpoint every 2s. Shows an in-place single-line progress bar that updates as each realm is indexed. File counts come from the invalidation graph so they're precise. The reporter tracks seen realms to show how many remain:

    indexing: waiting for status 3s
    indexing base: discovering files... 8s (2 realms remaining)
    indexing base [===============>              ] 105/153 files (69%) 50s (2 realms remaining)
       ↓ (line switches in-place when realm finishes)
    indexing software-factory [============>         ] 113/204 files (55%) 155s (1 realm remaining)
       ↓
    indexing test [=======================>      ] 10/12 files (83%) 230s
    indexing complete: 12/12 files in 235.0s
  

• Graceful pg unavailability: databaseExists() returns false instead of throwing when postgres isn't running yet.

• Stale context validation: Validates both hostURL and matrixURL in cached support.json, discarding stale contexts.

Test plan

• cache:prepare succeeds in a fresh worktree with no services running (pg, synapse, host, icons all auto-started)
• cache:prepare succeeds alongside a running mise run dev-all without disrupting dev services
• Host app at localhost:4200 remains fully functional during and after cache:prepare
• Progress bar updates live during indexing (verified by polling /_indexing-status endpoint directly: base 0→150/153, software-factory 4→198/204, test 0→10/12)
• totalFiles from the invalidation graph is precise
• Remaining realm count decrements as realms complete (2 → 1 → 0)
• Playwright tests pass with the updated harness

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

Updates the software-factory cache:prepare flow to be self-contained in fresh git worktrees by auto-provisioning required build artifacts, taking direct ownership of the icon server lifecycle, and adding indexing progress reporting during template builds.

Changes:

• Auto-build or (attempt to) symlink missing host/boxel-ui/boxel-icons dist artifacts to avoid manual setup in new worktrees.
• Always start a managed icon server process (with intended fallback to an already-running dev server) and ensure icon dist exists before serving.
• Add stderr progress bar for indexing by polling boxel_index, plus make databaseExists() tolerant of Postgres being down and validate cached support context URLs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
packages/software-factory/src/harness/support-services.ts	Adds dist auto-provisioning and managed icon server startup/stop logic.
packages/software-factory/src/harness/database.ts	Makes DB existence checks resilient and adds indexing progress reporter + file counting.
packages/software-factory/src/cli/cache-realm.ts	Validates cached support.json context by probing hostURL and matrixURL.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.