mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

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

Merged
jason.woltje merged 1 commits from feat/unified-first-run into main 2026-04-05 19:13:03 +00:00
Conversation 0 Commits 1 Files Changed 14 +1730 -640
jason.woltje commented 2026-04-05 18:36:14 +00:00
Owner
Copy Link

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 noreply@anthropic.com

## 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 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-04-05 18:36:14 +00:00
feat: unified first-run flow — merge wizard + gateway install (IUH-M03)
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details
ec89675f97 
Collapse `mosaic wizard` and `mosaic gateway install` into a single cohesive
first-run experience. Gateway config and admin bootstrap now run as terminal
stages of `runWizard`, sharing `WizardState` with the framework stages and
eliminating the fragile 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json`
session-file bridge.

- Extract `gatewayConfigStage` and `gatewayBootstrapStage` as first-class
  wizard stages with full spec coverage (headless + interactive paths).
- `mosaic gateway install` becomes a thin wrapper that invokes the same
  two stages — the CLI entry point is preserved for operators who only
  need to (re)configure the daemon.
- Honor explicit `--port` override even on resume: when the override
  differs from the saved GATEWAY_PORT, force a config regeneration so
  `.env` and `meta.json` cannot drift.
- Honor `state.hooks.accepted === false` in the finalize stage and in
  `mosaic-link-runtime-assets`: declined hooks are now actually opted-out,
  with a stable `mosaic-managed: true` marker in the template so cleanup
  survives template updates without touching user-owned configs.
- Headless rerun of an already-bootstrapped gateway with no local token
  cache is a successful no-op (no more false-positive install failures).
- `tools/install.sh` calls `mosaic wizard` only — the follow-up
  `mosaic gateway install` auto-launch is removed.

Closes mosaicstack/mosaic-stack#427.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#433
Delete Branch "feat/unified-first-run"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?