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

fix(mosaic): resumable gateway install + prominent admin token #393

Merged
jason.woltje merged 1 commits from fix/gateway-install-ux into main 2026-04-05 03:19:08 +00:00
Conversation 0 Commits 1 Files Changed 3 +305 -68
jason.woltje commented 2026-04-05 03:09:21 +00:00
Owner
Copy Link

Summary

mosaic gateway install had three UX problems the user called out:

  1. Admin token was silently saved to meta.json and never shown — no way to retrieve it short of reading the file.
  2. If install crashed mid-way (e.g. the PGlite bug fixed in #389), re-running prompted Reinstall? [y/N] and aborted on N, leaving a half-configured install with no resume path.
  3. Health-check failures only pointed at mosaic gateway logs — user had to run a second command to see the actual error.

Changes

  • Prominent admin token banner printed immediately after bootstrap.
  • Resumable install state machine detects partial installs (meta + .env + mosaic.config.json + daemon state) and picks up where a prior attempt stopped.
  • Inline log tail on health failure — last 30 non-empty lines of gateway.log printed automatically.
  • Corrupt-state detection — if exactly one of .env / mosaic.config.json exists, refuses to guess and directs the user to mosaic gateway uninstall.
  • BETTER_AUTH_SECRET preservation across config regeneration so Better Auth sessions aren't silently invalidated.
  • Admin token dropped on any config regeneration (the wizard can change backends; the old token is unverifiable).
  • Daemon stopped before config rewrite so the live process never serves stale config.
  • @mosaic/mosaic 0.0.19 → 0.0.20.

Went through four rounds of Codex code review; all blockers addressed.

Known follow-ups

  • --port 14242 as an explicit override can't be distinguished from commander's default value. Requires plumbing an explicit flag from the parent command. Extremely rare in practice.
  • No automated test coverage for the new state branches. Adding it requires mocking fs/readline/fetch/spawn and is scoped for a separate PR.

Test plan

  • pnpm typecheck passes
  • pnpm lint passes
  • pnpm format:check passes
  • pnpm --filter @mosaic/mosaic test — 78 tests pass
  • Four rounds of independent Codex code review — no remaining blockers
  • Manual: fresh install → admin token shown in banner
  • Manual: kill daemon mid-install → re-run → resumes from health check / bootstrap
  • Manual: point gateway at a used port → re-run → log tail printed
## Summary `mosaic gateway install` had three UX problems the user called out: 1. Admin token was silently saved to `meta.json` and never shown — no way to retrieve it short of reading the file. 2. If install crashed mid-way (e.g. the PGlite bug fixed in #389), re-running prompted `Reinstall? [y/N]` and aborted on N, leaving a half-configured install with no resume path. 3. Health-check failures only pointed at `mosaic gateway logs` — user had to run a second command to see the actual error. ## Changes - **Prominent admin token banner** printed immediately after bootstrap. - **Resumable install state machine** detects partial installs (meta + .env + mosaic.config.json + daemon state) and picks up where a prior attempt stopped. - **Inline log tail** on health failure — last 30 non-empty lines of `gateway.log` printed automatically. - **Corrupt-state detection** — if exactly one of `.env` / `mosaic.config.json` exists, refuses to guess and directs the user to `mosaic gateway uninstall`. - **`BETTER_AUTH_SECRET` preservation** across config regeneration so Better Auth sessions aren't silently invalidated. - **Admin token dropped on any config regeneration** (the wizard can change backends; the old token is unverifiable). - **Daemon stopped before config rewrite** so the live process never serves stale config. - `@mosaic/mosaic` 0.0.19 → 0.0.20. Went through four rounds of Codex code review; all blockers addressed. ## Known follow-ups - `--port 14242` as an explicit override can't be distinguished from commander's default value. Requires plumbing an `explicit` flag from the parent command. Extremely rare in practice. - No automated test coverage for the new state branches. Adding it requires mocking fs/readline/fetch/spawn and is scoped for a separate PR. ## Test plan - [x] `pnpm typecheck` passes - [x] `pnpm lint` passes - [x] `pnpm format:check` passes - [x] `pnpm --filter @mosaic/mosaic test` — 78 tests pass - [x] Four rounds of independent Codex code review — no remaining blockers - [ ] Manual: fresh install → admin token shown in banner - [ ] Manual: kill daemon mid-install → re-run → resumes from health check / bootstrap - [ ] Manual: point gateway at a used port → re-run → log tail printed
jason.woltje force-pushed fix/gateway-install-ux from ebf9517dd0 to 7e95107ed5 2026-04-05 03:14:53 +00:00 Compare
jason.woltje merged commit 621ab260c0 into main 2026-04-05 03:19:08 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
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#393
Delete Branch "fix/gateway-install-ux"

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?