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

2026-04-05T03:09:21Z

jason.woltje commented

2026-04-05 03:09:21 +00:00

Summary

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

Admin token was silently saved to meta.json and never shown — no way to retrieve it short of reading the file.
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.
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

jason.woltje referenced this issue from a commit

2026-04-05 03:19:10 +00:00

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#393