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>
48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
# 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:
|
|
|
|
1. 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 running `mosaic gateway
|
|
config` afterward.
|
|
2. When install crashes mid-way (e.g. daemon fails to become healthy), the
|
|
next run of `mosaic gateway install` prompts "Reinstall? [y/N]". Saying N
|
|
aborts, leaving the user with a half-configured install and no clear path
|
|
forward. There is no resume path.
|
|
3. 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 of `LOG_FILE` and print
|
|
the last ~30 non-empty lines before returning.
|
|
- Keep `mosaic gateway config` as-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.
|