feat(mosaic): unified first-run UX wizard -> gateway install -> verify #418

2026-04-05T07:25:56Z

jason.woltje commented

2026-04-05 07:25:56 +00:00

Implements M7 (CU-07-01 through CU-07-04) of the CLI unification mission.

CU-07-01 install.sh handoff

Adds --yes and --no-auto-launch flags to tools/install.sh. On first install with an interactive TTY, automatically launches mosaic wizard followed by mosaic gateway install before the summary. Non-interactive or --no-auto-launch prints guidance text only. MOSAIC_ASSUME_YES=1 env var equivalent to --yes.

CU-07-02 wizard / gateway install coordination

Wizard writes a transient session state file to $XDG_RUNTIME_DIR/mosaic-install-state.json (0600 perms) at completion, containing wizardCompletedAt and mosaicHome. Gateway install reads this on startup; if fresh (under 10 min), announces the resumed session and applies mosaicHome for custom-home installs. State is cleared on successful gateway install. The transient file is the only bridge -- no permanent coupling.

CU-07-03 post-install verification

New packages/mosaic/src/commands/gateway/verify.ts exports runPostInstallVerification(host, port) which runs three checks: gateway /health endpoint (3 retries with 1s backoff, retries non-OK responses to handle startup races), admin token on file (reads meta.json), and /api/bootstrap/status reachability. Prints a checkmark summary with recovery hints on failure. Called at the tail of runInstall. Also registered as mosaic gateway verify standalone subcommand.

CU-07-04 e2e test harness

New tools/e2e-install-test.sh runs the full install flow in a clean node:22-alpine Docker container. Skips gracefully if Docker is unavailable. The gateway verify step self-reports as EXPECTED-SKIP when the installed CLI version pre-dates the verify command (expected until next publish).

Quality gates

typecheck: pass
lint: pass
format:check: pass
test: 125/125 pass
e2e: PASS (gateway verify step SKIP with explanation -- verify command not yet in published 0.0.21)

Implements M7 (CU-07-01 through CU-07-04) of the CLI unification mission. **CU-07-01 install.sh handoff** Adds --yes and --no-auto-launch flags to tools/install.sh. On first install with an interactive TTY, automatically launches mosaic wizard followed by mosaic gateway install before the summary. Non-interactive or --no-auto-launch prints guidance text only. MOSAIC_ASSUME_YES=1 env var equivalent to --yes. **CU-07-02 wizard / gateway install coordination** Wizard writes a transient session state file to $XDG_RUNTIME_DIR/mosaic-install-state.json (0600 perms) at completion, containing wizardCompletedAt and mosaicHome. Gateway install reads this on startup; if fresh (under 10 min), announces the resumed session and applies mosaicHome for custom-home installs. State is cleared on successful gateway install. The transient file is the only bridge -- no permanent coupling. **CU-07-03 post-install verification** New packages/mosaic/src/commands/gateway/verify.ts exports runPostInstallVerification(host, port) which runs three checks: gateway /health endpoint (3 retries with 1s backoff, retries non-OK responses to handle startup races), admin token on file (reads meta.json), and /api/bootstrap/status reachability. Prints a checkmark summary with recovery hints on failure. Called at the tail of runInstall. Also registered as mosaic gateway verify standalone subcommand. **CU-07-04 e2e test harness** New tools/e2e-install-test.sh runs the full install flow in a clean node:22-alpine Docker container. Skips gracefully if Docker is unavailable. The gateway verify step self-reports as EXPECTED-SKIP when the installed CLI version pre-dates the verify command (expected until next publish). **Quality gates** - typecheck: pass - lint: pass - format:check: pass - test: 125/125 pass - e2e: PASS (gateway verify step SKIP with explanation -- verify command not yet in published 0.0.21)

jason.woltje added 1 commit 2026-04-05 07:25:56 +00:00

feat(mosaic): unified first-run UX wizard -> gateway install -> verify (CU-07-01..04)

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

e99a4921ed

- CU-07-01: install.sh gains --yes/--no-auto-launch flags; on first install
  with a TTY, auto-launches mosaic wizard then mosaic gateway install before
  the summary. Non-interactive / --no-auto-launch falls back to guidance text.
- CU-07-02: wizard writes transient session state to $XDG_RUNTIME_DIR/
  mosaic-install-state.json on completion; gateway install reads it on startup,
  announces the resume, and applies mosaicHome for custom-home installs.
  State is cleared on successful gateway install.
- CU-07-03: new packages/mosaic/src/commands/gateway/verify.ts exports
  runPostInstallVerification() (3 checks: gateway /health, admin token on file,
  /api/bootstrap/status). Called at end of runInstall. Registered as
  mosaic gateway verify subcommand. fetchWithRetry retries non-OK responses
  to handle startup races.
- CU-07-04: tools/e2e-install-test.sh — Docker-based e2e harness that runs
  the full install.sh -> wizard -> gateway install -> verify flow in a clean
  node:22-alpine container. Skips gracefully if Docker is unavailable.
  Gateway verify step skips with explanation when the published CLI pre-dates
  the new command (expected until next release).

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

jason.woltje merged commit 872c124581 into main

2026-04-05 07:29:18 +00:00

jason.woltje referenced this issue from a commit

2026-04-05 07:29:20 +00:00

feat(mosaic): unified first-run UX wizard -> gateway install -> verify (#418)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#418