7e95107ed5
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>
2.0 KiB
2.0 KiB
Gateway Install UX Fixes — 2026-04-04
Context
User hit two publish-drift bugs on mosaic gateway install (fixed in #386 and
#389). On top of those, the install UX itself has three concrete problems:
- Admin API token is generated by the bootstrap step and saved to
~/.config/mosaic/gateway/meta.json, but never shown to the user. There is no way to retrieve it without reading the file or runningmosaic gateway configafterward. - When install crashes mid-way (e.g. daemon fails to become healthy), the
next run of
mosaic gateway installprompts "Reinstall? [y/N]". Saying N aborts, leaving the user with a half-configured install and no clear path forward. There is no resume path. - Health-check failure only prints "Check logs: mosaic gateway logs" — forcing the user to run another command to see the actual error.
Goal
Make mosaic gateway install a single end-to-end, resumable command that shows
the admin token on creation and surfaces errors inline.
Plan
install.ts: detect partial state (meta exists, no admin token, daemon not running) and skip already-completed phases instead of aborting.install.ts: add a prominent "Admin API Token" banner printed right after bootstrap succeeds. Include copy-now warning.install.ts: on health-check timeout, read the tail ofLOG_FILEand print the last ~30 non-empty lines before returning.- Keep
mosaic gateway configas-is (view/edit env vars); this is not the setup wizard. - No new commands. No new flags yet.
Out of scope
- Readline/stdin piping fragility (pre-existing, not related to user complaint).
- Refactor to a phased state machine (overkill for three targeted fixes).
Verification
- Typecheck, lint, format (mandatory gates).
- Manual end-to-end: fresh install → confirm token displayed.
- Manual resume: delete daemon.pid mid-install → re-run → confirm it resumes.
- Manual failure: point ENV_FILE port to a used port → re-run → confirm log tail is printed.