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

IUH-M03: Unified first-run wizard (collapse wizard + gateway install) #427

New Issue
Closed
opened 2026-04-05 16:47:34 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-04-05 16:47:34 +00:00
Owner
Copy Link

Mission: install-ux-hardening-20260405
Milestone: IUH-M03
Branch: feat/unified-first-run
Agent tier: opus
Depends on: IUH-M02

Problem

mosaic wizard and mosaic gateway install are today two separate flows bridged by a 10-minute session file at $XDG_RUNTIME_DIR/mosaic-install-state.json (see packages/mosaic/src/wizard.ts:17-34 and packages/mosaic/src/commands/gateway/install.ts:25-56). Works, but:

  • User perceives two wizards
  • Session file TTL is fragile (user goes to lunch, loses context)
  • State is not shared — each flow re-prompts for things the other already knows
  • tools/install.sh auto-launches them sequentially, which amplifies the two-phase feel

Scope

Collapse both into a single cohesive first-run flow with shared in-memory state.

  • Design doc: unified WizardState that includes gateway config + admin bootstrap; decide whether gateway install becomes a stage inside runWizard or whether a new top-level orchestrator wraps both
  • Refactor runWizard to invoke gateway install as the final stage(s); drop the session-file bridge
  • Preserve backward-compat: mosaic gateway install must still work as a standalone entry point for users who already went through mosaic wizard
  • Update tools/install.sh auto-launch to invoke the single unified entry point

Success Criteria

  • tools/install.sh on a fresh machine runs one cohesive wizard from welcome through admin user creation
  • Session file bridge is removed
  • mosaic gateway install standalone still works (idempotent resume)
  • No regressions in existing gateway install tests
  • Vitest coverage for the unified flow
  • Independent code review completed
  • PR merged to main, CI green, issue closed

Files to touch

  • packages/mosaic/src/wizard.ts — add gateway stages
  • packages/mosaic/src/stages/gateway-config.ts (new) — extracted from runConfigWizard
  • packages/mosaic/src/stages/gateway-bootstrap.ts (new) — extracted from bootstrapFirstUser
  • packages/mosaic/src/commands/gateway/install.ts — become a thin standalone wrapper
  • tools/install.sh — single auto-launch call
  • packages/mosaic/src/types.ts — extend WizardState
**Mission:** install-ux-hardening-20260405 **Milestone:** IUH-M03 **Branch:** feat/unified-first-run **Agent tier:** opus **Depends on:** IUH-M02 ## Problem `mosaic wizard` and `mosaic gateway install` are today two separate flows bridged by a 10-minute session file at `$XDG_RUNTIME_DIR/mosaic-install-state.json` (see `packages/mosaic/src/wizard.ts:17-34` and `packages/mosaic/src/commands/gateway/install.ts:25-56`). Works, but: - User perceives two wizards - Session file TTL is fragile (user goes to lunch, loses context) - State is not shared — each flow re-prompts for things the other already knows - `tools/install.sh` auto-launches them sequentially, which amplifies the two-phase feel ## Scope Collapse both into a single cohesive first-run flow with shared in-memory state. - [ ] Design doc: unified `WizardState` that includes gateway config + admin bootstrap; decide whether gateway install becomes a stage inside `runWizard` or whether a new top-level orchestrator wraps both - [ ] Refactor `runWizard` to invoke gateway install as the final stage(s); drop the session-file bridge - [ ] Preserve backward-compat: `mosaic gateway install` must still work as a standalone entry point for users who already went through `mosaic wizard` - [ ] Update `tools/install.sh` auto-launch to invoke the single unified entry point ## Success Criteria - [ ] `tools/install.sh` on a fresh machine runs one cohesive wizard from welcome through admin user creation - [ ] Session file bridge is removed - [ ] `mosaic gateway install` standalone still works (idempotent resume) - [ ] No regressions in existing gateway install tests - [ ] Vitest coverage for the unified flow - [ ] Independent code review completed - [ ] PR merged to main, CI green, issue closed ## Files to touch - `packages/mosaic/src/wizard.ts` — add gateway stages - `packages/mosaic/src/stages/gateway-config.ts` (new) — extracted from `runConfigWizard` - `packages/mosaic/src/stages/gateway-bootstrap.ts` (new) — extracted from `bootstrapFirstUser` - `packages/mosaic/src/commands/gateway/install.ts` — become a thin standalone wrapper - `tools/install.sh` — single auto-launch call - `packages/mosaic/src/types.ts` — extend `WizardState`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
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#427
Delete Branch "%!s()"

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?