feat: unified first-run flow — merge wizard + gateway install (IUH-M03) #433

2026-04-05T18:36:14Z

jason.woltje commented

2026-04-05 18:36:14 +00:00

Summary

Collapse mosaic wizard and mosaic gateway install into a single cohesive first-run flow; gateway config + admin bootstrap now run as terminal stages of runWizard.
Drop the fragile 10-minute $XDG_RUNTIME_DIR/mosaic-install-state.json session-file bridge — state lives in WizardState (new gateway?: slice).
Extract gatewayConfigStage + gatewayBootstrapStage as first-class stages with full spec coverage; mosaic gateway install becomes a thin wrapper.
Port override is honored even on resume; conflicting saved ports force regeneration so .env and meta.json cannot drift.
Honor state.hooks.accepted === false end-to-end: finalize sets MOSAIC_SKIP_CLAUDE_HOOKS=1, and mosaic-link-runtime-assets cleans up previously-installed hooks only when a stable "mosaic-managed": true marker (or byte-equality for legacy installs) identifies the file as ours.
Headless rerun of an already-bootstrapped gateway with no local token cache is now a successful no-op (no more false install failures).
tools/install.sh calls mosaic wizard only — the legacy follow-up mosaic gateway install auto-launch is removed.

Test plan

pnpm typecheck (turbo, all packages)
pnpm lint (turbo, all packages)
pnpm format:check
pnpm --filter @mosaicstack/mosaic test — 24 files, 219 tests passing (includes 10 new stage spec tests + 3 unified-wizard integration tests)
New gatewayConfigStage spec — fresh install / decline-rerun / corrupt partial / MOSAIC_STORAGE_TIER=team / BETTER_AUTH_SECRET preservation / port-override regeneration
New gatewayBootstrapStage spec — fresh bootstrap / already-exists short-circuit / headless already-bootstrapped no-op / missing env vars / status failure / setup POST failure
New unified-wizard.test.ts — default runWizard invokes both gateway stages / skips bootstrap when config not ready / respects skipGateway: true
Four rounds of Codex code review applied; fifth attempt blocked by upstream quota (documented in scratchpad Session 4 remediation log)

Closes mosaicstack/mosaic-stack#427.

Co-Authored-By: Claude Opus 4.6 [email protected]

## Summary - Collapse `mosaic wizard` and `mosaic gateway install` into a single cohesive first-run flow; gateway config + admin bootstrap now run as terminal stages of `runWizard`. - Drop the fragile 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json` session-file bridge — state lives in `WizardState` (new `gateway?:` slice). - Extract `gatewayConfigStage` + `gatewayBootstrapStage` as first-class stages with full spec coverage; `mosaic gateway install` becomes a thin wrapper. - Port override is honored even on resume; conflicting saved ports force regeneration so `.env` and `meta.json` cannot drift. - Honor `state.hooks.accepted === false` end-to-end: finalize sets `MOSAIC_SKIP_CLAUDE_HOOKS=1`, and `mosaic-link-runtime-assets` cleans up previously-installed hooks only when a stable `"mosaic-managed": true` marker (or byte-equality for legacy installs) identifies the file as ours. - Headless rerun of an already-bootstrapped gateway with no local token cache is now a successful no-op (no more false install failures). - `tools/install.sh` calls `mosaic wizard` only — the legacy follow-up `mosaic gateway install` auto-launch is removed. ## Test plan - [x] `pnpm typecheck` (turbo, all packages) - [x] `pnpm lint` (turbo, all packages) - [x] `pnpm format:check` - [x] `pnpm --filter @mosaicstack/mosaic test` — 24 files, 219 tests passing (includes 10 new stage spec tests + 3 unified-wizard integration tests) - [x] New `gatewayConfigStage` spec — fresh install / decline-rerun / corrupt partial / MOSAIC_STORAGE_TIER=team / BETTER_AUTH_SECRET preservation / port-override regeneration - [x] New `gatewayBootstrapStage` spec — fresh bootstrap / already-exists short-circuit / headless already-bootstrapped no-op / missing env vars / status failure / setup POST failure - [x] New `unified-wizard.test.ts` — default `runWizard` invokes both gateway stages / skips bootstrap when config not ready / respects `skipGateway: true` - [x] Four rounds of Codex code review applied; fifth attempt blocked by upstream quota (documented in scratchpad Session 4 remediation log) Closes mosaicstack/mosaic-stack#427. Co-Authored-By: Claude Opus 4.6 <[email protected]>

jason.woltje force-pushed feat/unified-first-run from ec89675f97 to f3d5ef8d7d

2026-04-05 19:09:03 +00:00

Compare

jason.woltje merged commit 732f8a49cf into main

2026-04-05 19:13:03 +00:00

jason.woltje referenced this issue from a commit

2026-04-05 19:13:04 +00:00

feat: unified first-run flow — merge wizard + gateway install (IUH-M03) (#433)

jason.woltje referenced this issue from a commit

2026-04-05 19:16:03 +00:00

docs: close out install-ux-hardening mission (all 3 milestones done)

jason.woltje referenced this pull request