mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 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 added 1 commit 2026-04-05 03:09:22 +00:00
fix(mosaic): resumable gateway install + prominent admin token
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details
ebf9517dd0 
The `mosaic gateway install` command had three UX problems:

1. Admin API token was silently saved to meta.json and never shown to
   the user — no way to retrieve it without reading the file.
2. If install crashed mid-way (e.g. daemon health-check failure), the
   next run 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 separate command to see the actual error.

Changes:

- **Prominent admin token banner** printed immediately after bootstrap
  creates the first admin user. Clear "save now, won't be shown again"
  warning.
- **Resumable install state machine.** Detects partial installs from
  meta.json + .env + mosaic.config.json + daemon state, and picks up
  where a prior attempt stopped instead of prompting. Fully set up
  installs now offer "re-run config wizard" with explicit warnings
  about what it does (regenerates .env, clears admin token, may change
  backend storage).
- **Inline log tail on health failure.** Last 30 non-empty lines of
  gateway.log printed automatically when the daemon fails to become
  healthy, so the user sees the underlying error without running a
  second command.
- **Corrupt-state detection.** If exactly one of .env / mosaic.config.json
  exists (from an interrupted prior install), refuses to guess and
  directs the user to `mosaic gateway uninstall`.
- **BETTER_AUTH_SECRET preservation** across config regeneration so
  existing Better Auth sessions aren't silently invalidated.
- **Admin token dropped on any config regeneration** (the wizard may
  point at a different backend; the old token is unverifiable).
- **Daemon stopped before config rewrite** so the live process never
  serves stale config.
- Bump `@mosaic/mosaic` 0.0.19 → 0.0.20.

Known follow-ups (noted in review):
- `--port 14242` as an explicit override cannot be distinguished from
  commander's default value; requires plumbing an `explicit` flag.
- No automated test coverage for the new state branches; requires
  mocking fs/readline/fetch/spawn.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
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#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?