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.
|