From 0098242fb8451125196421b056d5b6f1247090ed Mon Sep 17 00:00:00 2001 From: Jarvis Date: Sun, 5 Apr 2026 12:09:37 -0500 Subject: [PATCH] docs: scaffold install-ux-hardening mission + archive cli-unification - Archive cli-unification-20260404 MISSION-MANIFEST + TASKS to docs/archive/missions/ - Add install-ux-hardening-20260405 mission docs (M01 done, M02 in-progress, M03 blocked) - Append Session 2 notes to scratchpad with M01 completion summary + follow-ups Mission scope: close post-cli-unification audit gaps (uninstall, wizard remediation, unified first-run). M01 shipped in #429. Refs: #425, #426, #427 Co-Authored-By: Claude Opus 4.6 --- docs/MISSION-MANIFEST.md | 91 ++++++--------- docs/TASKS.md | 108 +++++------------- .../MISSION-MANIFEST.md | 72 ++++++++++++ .../cli-unification-20260404/TASKS.md | 90 +++++++++++++++ .../install-ux-hardening-20260405.md | 32 ++++++ 5 files changed, 261 insertions(+), 132 deletions(-) create mode 100644 docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md create mode 100644 docs/archive/missions/cli-unification-20260404/TASKS.md diff --git a/docs/MISSION-MANIFEST.md b/docs/MISSION-MANIFEST.md index 859c046..78df74b 100644 --- a/docs/MISSION-MANIFEST.md +++ b/docs/MISSION-MANIFEST.md @@ -1,72 +1,57 @@ -# Mission Manifest — CLI Unification & E2E First-Run +# Mission Manifest — Install UX Hardening > Persistent document tracking full mission scope, status, and session history. > Updated by the orchestrator at each phase transition and milestone completion. ## Mission -**ID:** cli-unification-20260404 -**Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients. -**Phase:** Complete -**Current Milestone:** — -**Progress:** 8 / 8 milestones -**Status:** completed +**ID:** install-ux-hardening-20260405 +**Statement:** Close the remaining gaps in the Mosaic Stack first-run and teardown experience uncovered by the post-`cli-unification` audit. A user MUST be able to cleanly uninstall the stack; the wizard MUST make security-sensitive surfaces visible (hooks, password entry); and CI/headless installs MUST NOT hang on interactive prompts. The longer-term goal is a single cohesive first-run flow that collapses `mosaic wizard` and `mosaic gateway install` into one state-bridged experience. +**Phase:** Execution +**Current Milestone:** IUH-M02 +**Progress:** 1 / 3 milestones +**Status:** active **Last Updated:** 2026-04-05 -**Release:** [`mosaic-v0.0.24`](https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.0.24) (`@mosaicstack/mosaic@0.0.24`, alpha — stays in 0.0.x until GA) +**Parent Mission:** [cli-unification-20260404](./archive/missions/cli-unification-20260404/MISSION-MANIFEST.md) (complete) + +## Context + +Post-merge audit of `cli-unification-20260404` (AC-1, AC-6) validated that the first-run wizard covers first user, password, admin tokens, gateway instance config, skills, and SOUL.md/USER.md init. The audit surfaced six gaps, grouped into three tracks of independent value. ## Success Criteria -- [x] AC-1: Fresh machine `bash <(curl …install.sh)` → single command lands on a working authenticated gateway with a usable admin token; no secondary manual wizards required -- [x] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability -- [x] AC-3: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`, `mosaic telemetry` each expose at least one working subcommand that exercises the underlying package -- [x] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible -- [x] AC-5: `mosaic telemetry` uses the published `@mosaicstack/telemetry-client-js` (from the Gitea npm registry); local OTEL stays for wide-event logging / post-mortems; remote upload is opt-in and disabled by default -- [x] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends -- [x] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs -- [x] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes +- [x] AC-1: `mosaic uninstall` (top-level) cleanly reverses every mutation made by `tools/install.sh` — framework data, npm CLI, nested stack deps, runtime asset injections in `~/.claude/`, npmrc scope mapping, PATH edits. Dry-run supported. `--keep-data` preserves memory + user files + gateway DB. (PR #429) +- [x] AC-2: `curl … | bash -s -- --uninstall` works without requiring a functioning CLI. (PR #429) +- [ ] AC-3: Password entry in `bootstrapFirstUser` is masked (no plaintext echo); confirm prompt added. +- [ ] AC-4: Wizard has an explicit hooks stage that previews which hooks will be installed, asks for confirmation, and records the user's choice. `mosaic config hooks list|enable|disable` surface exists. +- [ ] AC-5: `runConfigWizard` and `bootstrapFirstUser` accept a headless path (env vars + `--yes`) so `tools/install.sh --yes` + `MOSAIC_ASSUME_YES=1` completes end-to-end in CI without TTY. +- [ ] AC-6: `mosaic wizard` and `mosaic gateway install` are collapsed into a single cohesive entry point with shared state (no two-phase handoff via the 10-minute session file). +- [ ] AC-7: All milestones ship as merged PRs with green CI, closed issues, updated release notes. ## Milestones -| # | ID | Name | Status | Branch | Issue | Started | Completed | -| --- | ------ | ------------------------------------------------------------------------ | ------ | ----------------------------------- | --------------------------------- | ---------- | ---------- | -| 1 | cu-m01 | Kill legacy @mosaicstack/cli package | done | chore/remove-cli-package-duplicate | #398 | 2026-04-04 | 2026-04-04 | -| 2 | cu-m02 | Archive stale mission state + scaffold new mission | done | docs/mission-cli-unification | #399 | 2026-04-04 | 2026-04-04 | -| 3 | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths) | done | feat/gateway-token-recovery | #411, #414 | 2026-04-05 | 2026-04-05 | -| 4 | cu-m04 | Alphabetize + group `mosaic --help` output | done | feat/help-sort + feat/mosaic-config | #402, #408 | 2026-04-05 | 2026-04-05 | -| 5 | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | done | feat/mosaic-\*-cli (x9) | #403–#407, #410, #412, #413, #415 | 2026-04-05 | 2026-04-05 | -| 6 | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload | done | feat/mosaic-telemetry | #417 | 2026-04-05 | 2026-04-05 | -| 7 | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI) | done | feat/mosaic-first-run-ux | #418 | 2026-04-05 | 2026-04-05 | -| 8 | cu-m08 | Docs refresh + release tag | done | docs/cli-unification-release-v0.1.0 | #419 | 2026-04-05 | 2026-04-05 | +| # | ID | Name | Status | Branch | Issue | Started | Completed | +| --- | ------- | --------------------------------------------------------- | ----------- | ----------------------- | ----- | ---------- | ---------- | +| 1 | IUH-M01 | `mosaic uninstall` — top-level teardown + shell wrapper | done | feat/mosaic-uninstall | #425 | 2026-04-05 | 2026-04-05 | +| 2 | IUH-M02 | Wizard remediation — hooks visibility, pwd mask, headless | in-progress | feat/wizard-remediation | #426 | 2026-04-05 | — | +| 3 | IUH-M03 | Unified first-run wizard (collapse wizard + gateway) | blocked | feat/unified-first-run | #427 | — | — | -## Deployment +## Subagent Delegation Plan -| Target | URL | Method | -| -------------------- | --------- | ----------------------------------------------- | -| Local tier (default) | localhost | `mosaic gateway install` — pglite + local queue | -| Team tier | any host | `mosaic gateway install` — PG + Valkey | -| Docker Compose (dev) | localhost | `docker compose up` for PG/Valkey/OTEL/Jaeger | +| Milestone | Recommended Tier | Rationale | +| --------- | ---------------- | ---------------------------------------------------------------------- | +| IUH-M01 | sonnet | Standard feature work — new command surface mirroring existing install | +| IUH-M02 | sonnet | Small surgical fixes across 3-4 files | +| IUH-M03 | opus | Architectural refactor; state machine design decisions | -## Coordination +## Risks -- **Primary Agent:** claude-opus-4-6[1m] -- **Sibling Agents:** sonnet (standard implementation), haiku (status/explore/verify), codex (coding-heavy tasks) -- **Shared Contracts:** `docs/PRD.md` (existing v0.1.0 PRD — still the long-term target), this manifest, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md` +- **Reversal completeness** — runtime asset linking creates `.mosaic-bak-*` backups; uninstall must honor them vs. when to delete. Ambiguity without an install manifest. +- **npm global nested deps** — `npm uninstall -g @mosaicstack/mosaic` removes nested `@mosaicstack/*`, but ownership conflicts with explicitly installed peer packages (`@mosaicstack/gateway`, `@mosaicstack/memory`) need test coverage. +- **Headless bootstrap** — admin password via env var is a credential on disk; needs clear documentation that `MOSAIC_ADMIN_PASSWORD` is intended for CI-only and should be rotated post-install. -## Token Budget +## Out of Scope -| Metric | Value | -| ------ | ------ | -| Budget | TBD | -| Used | ~80K | -| Mode | normal | - -## Session History - -| Session | Runtime | Started | Duration | Ended Reason | Last Task | -| ------- | --------------- | ---------- | -------- | ---------------- | ------------------------------------------------------------ | -| 1 | claude-opus-4-6 | 2026-04-04 | ~4h | context-budget | cu-m01 + cu-m02 merged (#398, #399); open questions resolved | -| 2 | claude-opus-4-6 | 2026-04-05 | ~6h | mission-complete | cu-m03..cu-m08 all merged; mosaic-v0.1.0 released | - -## Scratchpad - -Path: `docs/scratchpads/cli-unification-20260404.md` +- `mosaicstack.dev/install.sh` vanity URL (blocked on marketing site work) +- Uninstall for the `@mosaicstack/gateway` database contents — delegated to `mosaic gateway uninstall` semantics already in place +- Signature/checksum verification of install scripts diff --git a/docs/TASKS.md b/docs/TASKS.md index 716b427..364651b 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -1,90 +1,40 @@ -# Tasks — CLI Unification & E2E First-Run +# Tasks — Install UX Hardening > Single-writer: orchestrator only. Workers read but never modify. > -> **Mission:** cli-unification-20260404 +> **Mission:** install-ux-hardening-20260405 > **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |` > **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa` -> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `glm-5` | `—` (auto) +> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `—` (auto) -## Milestone 1 — Kill legacy @mosaicstack/cli (done) +## Milestone 1 — `mosaic uninstall` (IUH-M01) -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | ----------------------------------------------------------------- | ----- | ----- | ---------------------------------- | ---------- | -------- | --------------------------- | -| CU-01-01 | done | Delete packages/cli directory; update workspace + docs references | #398 | opus | chore/remove-cli-package-duplicate | — | 5K | Merged c39433c3. 6685 LOC−. | +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| --------- | ------ | ------------------------------------------------------------------------------------------------------------------- | ----- | ------ | --------------------- | ---------- | -------- | ------------------------------------------------------ | +| IUH-01-01 | done | Design install manifest schema (`~/.config/mosaic/.install-manifest.json`) — what install writes on first success | #425 | sonnet | feat/mosaic-uninstall | — | 8K | v1 schema in `install-manifest.ts` | +| IUH-01-02 | done | `mosaic uninstall` TS command: `--framework`, `--cli`, `--gateway`, `--all`, `--keep-data`, `--yes`, `--dry-run` | #425 | sonnet | feat/mosaic-uninstall | IUH-01-01 | 25K | `uninstall.ts` | +| IUH-01-03 | done | Reverse runtime asset linking in `~/.claude/` — restore `.mosaic-bak-*` if present, remove managed copies otherwise | #425 | sonnet | feat/mosaic-uninstall | IUH-01-02 | 12K | file list hardcoded from mosaic-link-runtime-assets | +| IUH-01-04 | done | Reverse npmrc scope mapping and PATH edits made by `tools/install.sh` | #425 | sonnet | feat/mosaic-uninstall | IUH-01-02 | 8K | npmrc reversed; no PATH edits found in v0.0.24 install | +| IUH-01-05 | done | Shell fallback: `tools/install.sh --uninstall` path for users without a working CLI | #425 | sonnet | feat/mosaic-uninstall | IUH-01-02 | 10K | | +| IUH-01-06 | done | Vitest coverage: dry-run output, `--all`, `--keep-data`, partial state, missing manifest | #425 | sonnet | feat/mosaic-uninstall | IUH-01-05 | 15K | 14 new tests, 170 total | +| IUH-01-07 | done | Code review (independent) + remediation | #425 | sonnet | feat/mosaic-uninstall | IUH-01-06 | 5K | | +| IUH-01-08 | done | PR open, CI green, review, merge to `main`, close issue | #425 | sonnet | feat/mosaic-uninstall | IUH-01-07 | 3K | PR #429, merge 25cada77 | -## Milestone 2 — Archive stale mission + scaffold new mission (done) +## Milestone 2 — Wizard Remediation (IUH-M02) -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- | -| CU-02-01 | done | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | #399 | opus | docs/mission-cli-unification | CU-01-01 | 3K | Harness + storage missions done. | -| CU-02-02 | done | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad | #399 | opus | docs/mission-cli-unification | CU-02-01 | 5K | This file + manifest + scratchpad | -| CU-02-03 | done | PR review, merge, branch cleanup | #399 | opus | docs/mission-cli-unification | CU-02-02 | 2K | Merged as 6f15a84c | +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| --------- | ----------- | -------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------- | ---------- | -------- | ----- | +| IUH-02-01 | in-progress | Password masking: replace plaintext `rl.question` in `bootstrapFirstUser` with masked TTY read + confirmation | #426 | sonnet | feat/wizard-remediation | IUH-01-08 | 8K | | +| IUH-02-02 | not-started | Hooks preview stage in wizard: show `framework/runtime/claude/hooks-config.json` entries + confirm prompt | #426 | sonnet | feat/wizard-remediation | IUH-02-01 | 12K | | +| IUH-02-03 | not-started | `mosaic config hooks list\|enable\|disable` subcommands | #426 | sonnet | feat/wizard-remediation | IUH-02-02 | 15K | | +| IUH-02-04 | not-started | Headless path: env-var driven `runConfigWizard` + `bootstrapFirstUser` (`MOSAIC_ASSUME_YES`, `MOSAIC_ADMIN_*`) | #426 | sonnet | feat/wizard-remediation | IUH-02-03 | 12K | | +| IUH-02-05 | not-started | Tests + code review + PR merge | #426 | sonnet | feat/wizard-remediation | IUH-02-04 | 10K | | -## Milestone 3 — Gateway bootstrap token recovery +## Milestone 3 — Unified First-Run Wizard (IUH-M03) -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- | -| CU-03-01 | done | Implementation plan for BetterAuth-cookie recovery flow (decision locked 2026-04-04) | — | opus | — | CU-02-03 | 4K | Design locked; plan-only task | -| CU-03-02 | done | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | — | sonnet | — | CU-03-01 | 12K | | -| CU-03-03 | done | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session | — | sonnet | — | CU-03-02 | 10K | | -| CU-03-04 | done | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API | — | sonnet | — | CU-03-03 | 8K | | -| CU-03-05 | done | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01 | — | sonnet | — | CU-03-03 | 10K | | -| CU-03-06 | done | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path | — | sonnet | — | CU-03-05 | 8K | | -| CU-03-07 | done | Tests: integration tests for each recovery path (happy + error) | — | sonnet | — | CU-03-06 | 10K | | -| CU-03-08 | done | Code review + remediation | — | haiku | — | CU-03-07 | 4K | | - -## Milestone 4 — `mosaic --help` alphabetize + grouping - -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------------------- | -| CU-04-01 | done | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup | — | sonnet | — | CU-02-03 | 3K | | -| CU-04-02 | done | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output | — | sonnet | — | CU-04-01 | 5K | | -| CU-04-03 | done | Verify help snapshots render readably; update any docs with stale output | — | haiku | — | CU-04-02 | 3K | | -| CU-04-04 | done | Top-level `mosaic config` command — `show`, `get `, `set `, `edit`, `path` — wraps packages/mosaic/src/config/config-service.ts (framework/agent config; distinct from `mosaic gateway config`) | — | sonnet | — | CU-02-03 | 10K | New scope (decision 2026-04-04) | -| CU-04-05 | done | Tests + code review for CU-04-04 | — | haiku | — | CU-04-04 | 4K | | - -## Milestone 5 — Sub-package CLI surface - -> Pattern: each sub-package exports `registerCommand(program: Command)` co-located with the library code (proven by `@mosaicstack/quality-rails`). Wire into `packages/mosaic/src/cli.ts`. - -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | --------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------- | -| CU-05-01 | done | `mosaic forge` — subcommands: `run`, `status`, `resume`, `personas list` | — | sonnet | — | CU-02-03 | 18K | User priority | -| CU-05-02 | done | `mosaic storage` — subcommands: `status`, `tier show`, `tier switch`, `export`, `import`, `migrate` | — | sonnet | — | CU-02-03 | 15K | | -| CU-05-03 | done | `mosaic queue` — subcommands: `list`, `stats`, `pause/resume`, `jobs tail`, `drain` | — | sonnet | — | CU-02-03 | 12K | | -| CU-05-04 | done | `mosaic memory` — subcommands: `search`, `stats`, `insights list`, `preferences list` | — | sonnet | — | CU-02-03 | 12K | | -| CU-05-05 | done | `mosaic brain` — subcommands: `projects list/create`, `missions list`, `tasks list`, `conversations list` | — | sonnet | — | CU-02-03 | 15K | | -| CU-05-06 | done | `mosaic auth` — subcommands: `users list/create/delete`, `sso list`, `sso test`, `sessions list` | — | sonnet | — | CU-03-03 | 15K | needs gateway login | -| CU-05-07 | done | `mosaic log` — subcommands: `tail`, `search`, `export`, `level ` | — | sonnet | — | CU-02-03 | 10K | | -| CU-05-08 | done | `mosaic macp` — subcommands: `tasks list`, `submit`, `gate`, `events tail` | — | sonnet | — | CU-02-03 | 12K | | -| CU-05-09 | done | Wire all eight `registerCommand` calls into packages/mosaic/src/cli.ts | — | haiku | — | CU-05-01…8 | 3K | | -| CU-05-10 | done | Integration test: `mosaic --help` exits 0 for every new command | — | haiku | — | CU-05-09 | 5K | | - -## Milestone 6 — `mosaic telemetry` - -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | ------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ---------------------------------------------- | -| CU-06-01 | done | Add `@mosaicstack/telemetry-client-js` as dependency of `@mosaicstack/mosaic` from Gitea registry | — | sonnet | — | CU-02-03 | 3K | | -| CU-06-02 | done | `mosaic telemetry local` — status, tail, Jaeger link (wraps existing apps/gateway/src/tracing.ts) | — | sonnet | — | CU-06-01 | 8K | | -| CU-06-03 | done | `mosaic telemetry` — status, opt-in, opt-out, test, upload (uses telemetry-client-js) | — | sonnet | — | CU-06-01 | 12K | Dry-run mode when server endpoint not yet live | -| CU-06-04 | done | Persistent consent state in mosaic config; disabled by default | — | sonnet | — | CU-06-03 | 5K | | -| CU-06-05 | done | Tests + code review | — | haiku | — | CU-06-04 | 5K | | - -## Milestone 7 — Unified first-run UX - -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- | -| CU-07-01 | done | tools/install.sh: after npm install, hand off to `mosaic wizard` then `mosaic gateway install` | — | sonnet | — | CU-03-06 | 10K | | -| CU-07-02 | done | `mosaic wizard` and `mosaic gateway install` coordination: shared state, no duplicate prompts | — | sonnet | — | CU-07-01 | 12K | | -| CU-07-03 | done | Post-install verification step: "gateway healthy, tui connects, admin token on file" | — | sonnet | — | CU-07-02 | 8K | | -| CU-07-04 | done | End-to-end test on a clean container from scratch | — | haiku | — | CU-07-03 | 8K | | - -## Milestone 8 — Docs + release - -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ------ | ---------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- | -| CU-08-01 | done | Update README.md with new command tree, install flow, and feature list | — | sonnet | — | CU-07-04 | 8K | | -| CU-08-02 | done | Update docs/guides/user-guide.md with all new sub-package commands | — | sonnet | — | CU-08-01 | 10K | | -| CU-08-03 | done | Version bump `@mosaicstack/mosaic`, publish to Gitea registry | — | opus | — | CU-08-02 | 3K | | -| CU-08-04 | done | Release notes, tag `v0.1.0-rc.N`, publish release on Gitea | — | opus | — | CU-08-03 | 3K | | +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| --------- | ------- | ----------------------------------------------------------------------------------------------------------- | ----- | ----- | ---------------------- | ---------- | -------- | ----- | +| IUH-03-01 | blocked | Design doc: unified state machine; decide whether `mosaic gateway install` becomes an internal wizard stage | — | opus | feat/unified-first-run | IUH-02-05 | 10K | | +| IUH-03-02 | blocked | Refactor `runWizard` to invoke gateway install as a stage; drop the 10-minute session-file bridge | — | opus | feat/unified-first-run | IUH-03-01 | 25K | | +| IUH-03-03 | blocked | Preserve backward-compat: `mosaic gateway install` still works as a standalone entry point | — | opus | feat/unified-first-run | IUH-03-02 | 10K | | +| IUH-03-04 | blocked | Tests + code review + PR merge | — | opus | feat/unified-first-run | IUH-03-03 | 12K | | diff --git a/docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md b/docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md new file mode 100644 index 0000000..859c046 --- /dev/null +++ b/docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md @@ -0,0 +1,72 @@ +# Mission Manifest — CLI Unification & E2E First-Run + +> Persistent document tracking full mission scope, status, and session history. +> Updated by the orchestrator at each phase transition and milestone completion. + +## Mission + +**ID:** cli-unification-20260404 +**Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients. +**Phase:** Complete +**Current Milestone:** — +**Progress:** 8 / 8 milestones +**Status:** completed +**Last Updated:** 2026-04-05 +**Release:** [`mosaic-v0.0.24`](https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.0.24) (`@mosaicstack/mosaic@0.0.24`, alpha — stays in 0.0.x until GA) + +## Success Criteria + +- [x] AC-1: Fresh machine `bash <(curl …install.sh)` → single command lands on a working authenticated gateway with a usable admin token; no secondary manual wizards required +- [x] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability +- [x] AC-3: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`, `mosaic telemetry` each expose at least one working subcommand that exercises the underlying package +- [x] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible +- [x] AC-5: `mosaic telemetry` uses the published `@mosaicstack/telemetry-client-js` (from the Gitea npm registry); local OTEL stays for wide-event logging / post-mortems; remote upload is opt-in and disabled by default +- [x] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends +- [x] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs +- [x] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes + +## Milestones + +| # | ID | Name | Status | Branch | Issue | Started | Completed | +| --- | ------ | ------------------------------------------------------------------------ | ------ | ----------------------------------- | --------------------------------- | ---------- | ---------- | +| 1 | cu-m01 | Kill legacy @mosaicstack/cli package | done | chore/remove-cli-package-duplicate | #398 | 2026-04-04 | 2026-04-04 | +| 2 | cu-m02 | Archive stale mission state + scaffold new mission | done | docs/mission-cli-unification | #399 | 2026-04-04 | 2026-04-04 | +| 3 | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths) | done | feat/gateway-token-recovery | #411, #414 | 2026-04-05 | 2026-04-05 | +| 4 | cu-m04 | Alphabetize + group `mosaic --help` output | done | feat/help-sort + feat/mosaic-config | #402, #408 | 2026-04-05 | 2026-04-05 | +| 5 | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | done | feat/mosaic-\*-cli (x9) | #403–#407, #410, #412, #413, #415 | 2026-04-05 | 2026-04-05 | +| 6 | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload | done | feat/mosaic-telemetry | #417 | 2026-04-05 | 2026-04-05 | +| 7 | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI) | done | feat/mosaic-first-run-ux | #418 | 2026-04-05 | 2026-04-05 | +| 8 | cu-m08 | Docs refresh + release tag | done | docs/cli-unification-release-v0.1.0 | #419 | 2026-04-05 | 2026-04-05 | + +## Deployment + +| Target | URL | Method | +| -------------------- | --------- | ----------------------------------------------- | +| Local tier (default) | localhost | `mosaic gateway install` — pglite + local queue | +| Team tier | any host | `mosaic gateway install` — PG + Valkey | +| Docker Compose (dev) | localhost | `docker compose up` for PG/Valkey/OTEL/Jaeger | + +## Coordination + +- **Primary Agent:** claude-opus-4-6[1m] +- **Sibling Agents:** sonnet (standard implementation), haiku (status/explore/verify), codex (coding-heavy tasks) +- **Shared Contracts:** `docs/PRD.md` (existing v0.1.0 PRD — still the long-term target), this manifest, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md` + +## Token Budget + +| Metric | Value | +| ------ | ------ | +| Budget | TBD | +| Used | ~80K | +| Mode | normal | + +## Session History + +| Session | Runtime | Started | Duration | Ended Reason | Last Task | +| ------- | --------------- | ---------- | -------- | ---------------- | ------------------------------------------------------------ | +| 1 | claude-opus-4-6 | 2026-04-04 | ~4h | context-budget | cu-m01 + cu-m02 merged (#398, #399); open questions resolved | +| 2 | claude-opus-4-6 | 2026-04-05 | ~6h | mission-complete | cu-m03..cu-m08 all merged; mosaic-v0.1.0 released | + +## Scratchpad + +Path: `docs/scratchpads/cli-unification-20260404.md` diff --git a/docs/archive/missions/cli-unification-20260404/TASKS.md b/docs/archive/missions/cli-unification-20260404/TASKS.md new file mode 100644 index 0000000..716b427 --- /dev/null +++ b/docs/archive/missions/cli-unification-20260404/TASKS.md @@ -0,0 +1,90 @@ +# Tasks — CLI Unification & E2E First-Run + +> Single-writer: orchestrator only. Workers read but never modify. +> +> **Mission:** cli-unification-20260404 +> **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |` +> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa` +> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `glm-5` | `—` (auto) + +## Milestone 1 — Kill legacy @mosaicstack/cli (done) + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ----------------------------------------------------------------- | ----- | ----- | ---------------------------------- | ---------- | -------- | --------------------------- | +| CU-01-01 | done | Delete packages/cli directory; update workspace + docs references | #398 | opus | chore/remove-cli-package-duplicate | — | 5K | Merged c39433c3. 6685 LOC−. | + +## Milestone 2 — Archive stale mission + scaffold new mission (done) + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- | +| CU-02-01 | done | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | #399 | opus | docs/mission-cli-unification | CU-01-01 | 3K | Harness + storage missions done. | +| CU-02-02 | done | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad | #399 | opus | docs/mission-cli-unification | CU-02-01 | 5K | This file + manifest + scratchpad | +| CU-02-03 | done | PR review, merge, branch cleanup | #399 | opus | docs/mission-cli-unification | CU-02-02 | 2K | Merged as 6f15a84c | + +## Milestone 3 — Gateway bootstrap token recovery + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- | +| CU-03-01 | done | Implementation plan for BetterAuth-cookie recovery flow (decision locked 2026-04-04) | — | opus | — | CU-02-03 | 4K | Design locked; plan-only task | +| CU-03-02 | done | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | — | sonnet | — | CU-03-01 | 12K | | +| CU-03-03 | done | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session | — | sonnet | — | CU-03-02 | 10K | | +| CU-03-04 | done | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API | — | sonnet | — | CU-03-03 | 8K | | +| CU-03-05 | done | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01 | — | sonnet | — | CU-03-03 | 10K | | +| CU-03-06 | done | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path | — | sonnet | — | CU-03-05 | 8K | | +| CU-03-07 | done | Tests: integration tests for each recovery path (happy + error) | — | sonnet | — | CU-03-06 | 10K | | +| CU-03-08 | done | Code review + remediation | — | haiku | — | CU-03-07 | 4K | | + +## Milestone 4 — `mosaic --help` alphabetize + grouping + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------------------- | +| CU-04-01 | done | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup | — | sonnet | — | CU-02-03 | 3K | | +| CU-04-02 | done | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output | — | sonnet | — | CU-04-01 | 5K | | +| CU-04-03 | done | Verify help snapshots render readably; update any docs with stale output | — | haiku | — | CU-04-02 | 3K | | +| CU-04-04 | done | Top-level `mosaic config` command — `show`, `get `, `set `, `edit`, `path` — wraps packages/mosaic/src/config/config-service.ts (framework/agent config; distinct from `mosaic gateway config`) | — | sonnet | — | CU-02-03 | 10K | New scope (decision 2026-04-04) | +| CU-04-05 | done | Tests + code review for CU-04-04 | — | haiku | — | CU-04-04 | 4K | | + +## Milestone 5 — Sub-package CLI surface + +> Pattern: each sub-package exports `registerCommand(program: Command)` co-located with the library code (proven by `@mosaicstack/quality-rails`). Wire into `packages/mosaic/src/cli.ts`. + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | --------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------- | +| CU-05-01 | done | `mosaic forge` — subcommands: `run`, `status`, `resume`, `personas list` | — | sonnet | — | CU-02-03 | 18K | User priority | +| CU-05-02 | done | `mosaic storage` — subcommands: `status`, `tier show`, `tier switch`, `export`, `import`, `migrate` | — | sonnet | — | CU-02-03 | 15K | | +| CU-05-03 | done | `mosaic queue` — subcommands: `list`, `stats`, `pause/resume`, `jobs tail`, `drain` | — | sonnet | — | CU-02-03 | 12K | | +| CU-05-04 | done | `mosaic memory` — subcommands: `search`, `stats`, `insights list`, `preferences list` | — | sonnet | — | CU-02-03 | 12K | | +| CU-05-05 | done | `mosaic brain` — subcommands: `projects list/create`, `missions list`, `tasks list`, `conversations list` | — | sonnet | — | CU-02-03 | 15K | | +| CU-05-06 | done | `mosaic auth` — subcommands: `users list/create/delete`, `sso list`, `sso test`, `sessions list` | — | sonnet | — | CU-03-03 | 15K | needs gateway login | +| CU-05-07 | done | `mosaic log` — subcommands: `tail`, `search`, `export`, `level ` | — | sonnet | — | CU-02-03 | 10K | | +| CU-05-08 | done | `mosaic macp` — subcommands: `tasks list`, `submit`, `gate`, `events tail` | — | sonnet | — | CU-02-03 | 12K | | +| CU-05-09 | done | Wire all eight `registerCommand` calls into packages/mosaic/src/cli.ts | — | haiku | — | CU-05-01…8 | 3K | | +| CU-05-10 | done | Integration test: `mosaic --help` exits 0 for every new command | — | haiku | — | CU-05-09 | 5K | | + +## Milestone 6 — `mosaic telemetry` + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ---------------------------------------------- | +| CU-06-01 | done | Add `@mosaicstack/telemetry-client-js` as dependency of `@mosaicstack/mosaic` from Gitea registry | — | sonnet | — | CU-02-03 | 3K | | +| CU-06-02 | done | `mosaic telemetry local` — status, tail, Jaeger link (wraps existing apps/gateway/src/tracing.ts) | — | sonnet | — | CU-06-01 | 8K | | +| CU-06-03 | done | `mosaic telemetry` — status, opt-in, opt-out, test, upload (uses telemetry-client-js) | — | sonnet | — | CU-06-01 | 12K | Dry-run mode when server endpoint not yet live | +| CU-06-04 | done | Persistent consent state in mosaic config; disabled by default | — | sonnet | — | CU-06-03 | 5K | | +| CU-06-05 | done | Tests + code review | — | haiku | — | CU-06-04 | 5K | | + +## Milestone 7 — Unified first-run UX + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- | +| CU-07-01 | done | tools/install.sh: after npm install, hand off to `mosaic wizard` then `mosaic gateway install` | — | sonnet | — | CU-03-06 | 10K | | +| CU-07-02 | done | `mosaic wizard` and `mosaic gateway install` coordination: shared state, no duplicate prompts | — | sonnet | — | CU-07-01 | 12K | | +| CU-07-03 | done | Post-install verification step: "gateway healthy, tui connects, admin token on file" | — | sonnet | — | CU-07-02 | 8K | | +| CU-07-04 | done | End-to-end test on a clean container from scratch | — | haiku | — | CU-07-03 | 8K | | + +## Milestone 8 — Docs + release + +| id | status | description | issue | agent | branch | depends_on | estimate | notes | +| -------- | ------ | ---------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- | +| CU-08-01 | done | Update README.md with new command tree, install flow, and feature list | — | sonnet | — | CU-07-04 | 8K | | +| CU-08-02 | done | Update docs/guides/user-guide.md with all new sub-package commands | — | sonnet | — | CU-08-01 | 10K | | +| CU-08-03 | done | Version bump `@mosaicstack/mosaic`, publish to Gitea registry | — | opus | — | CU-08-02 | 3K | | +| CU-08-04 | done | Release notes, tag `v0.1.0-rc.N`, publish release on Gitea | — | opus | — | CU-08-03 | 3K | | diff --git a/docs/scratchpads/install-ux-hardening-20260405.md b/docs/scratchpads/install-ux-hardening-20260405.md index a4fd797..f8fe08a 100644 --- a/docs/scratchpads/install-ux-hardening-20260405.md +++ b/docs/scratchpads/install-ux-hardening-20260405.md @@ -67,3 +67,35 @@ ASSUMPTION: No PATH modifications in current install.sh (v0.0.24). Framework v0/v1→v2 migration cleaned old PATH entries but current install does not add new ones. ASSUMPTION: `--uninstall` in install.sh handles framework + cli + npmrc only; gateway teardown deferred to `mosaic gateway uninstall`. ASSUMPTION: Pi settings.json edits (skills paths) added by framework/install.sh are NOT reversed in this iteration — too risky to touch user Pi config without manifest evidence. Noted as follow-up. + +--- + +## Session 2 — 2026-04-05 (orchestrator resume) + +### IUH-M01 completion summary + +- **PR:** #429 merged as `25cada77` +- **CI:** green (Woodpecker) +- **Issue:** #425 closed +- **Files:** +1205 lines across 4 new + 2 modified + 1 docs +- **Tests:** 14 new, 170 total passing + +### Follow-ups captured from worker report + +1. **Pi settings.json reversal deferred** — worker flagged as too risky without manifest evidence. Future IUH task should add manifest entries for Pi settings mutations. Not blocking M02/M03. +2. **Pre-existing `cli-smoke.spec.ts` failure** — `@mosaicstack/brain` package entry resolution fails in Vitest. Unrelated to IUH-M01. Worth a separate issue later. +3. **`pr-create.sh` wrapper bug with multiline bodies** — wrapper evals body args as shell when they contain newlines/paths. Worker fell back to Gitea REST API. Same class of bug I hit earlier with `issue-create.sh`. Worth a tooling-team issue to fix both wrappers. + +### Mission doc sync + +cli-unification docs that were archived before the M01 subagent ran did not travel into the M01 PR (they were local, stashed before pull). Re-applying now: + +- `docs/archive/missions/cli-unification-20260404/` (the old manifest + tasks) +- `docs/MISSION-MANIFEST.md` (new install-ux-hardening content) +- `docs/TASKS.md` (new install-ux-hardening content) + +Committing as `docs: scaffold install-ux-hardening mission + archive cli-unification`. + +### Next action + +Delegate IUH-M02 to a sonnet subagent in an isolated worktree.