diff --git a/docs/MISSION-MANIFEST.md b/docs/MISSION-MANIFEST.md index 5b98a99..e2e50ca 100644 --- a/docs/MISSION-MANIFEST.md +++ b/docs/MISSION-MANIFEST.md @@ -8,10 +8,10 @@ **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:** Execution -**Current Milestone:** cu-m03 / cu-m04 / cu-m05 (parallel-eligible) -**Progress:** 2 / 8 milestones +**Current Milestone:** cu-m06 / cu-m07 (parallel-eligible); cu-m08 gated on both +**Progress:** 5 / 8 milestones **Status:** active -**Last Updated:** 2026-04-04 +**Last Updated:** 2026-04-05 ## Success Criteria @@ -26,16 +26,16 @@ ## 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) | not-started | — | — | — | — | -| 4 | cu-m04 | Alphabetize + group `mosaic --help` output | not-started | — | — | — | — | -| 5 | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | not-started | — | — | — | — | -| 6 | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload | not-started | — | — | — | — | -| 7 | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI) | not-started | — | — | — | — | -| 8 | cu-m08 | Docs refresh + release tag | not-started | — | — | — | — | +| # | 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 | in-progress | feat/mosaic-telemetry (worktree) | — | 2026-04-05 | — | +| 7 | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI) | in-progress | feat/mosaic-first-run (worktree) | — | 2026-04-05 | — | +| 8 | cu-m08 | Docs refresh + release tag | not-started | — | — | — | — | ## Deployment @@ -61,9 +61,10 @@ ## Session History -| Session | Runtime | Started | Duration | Ended Reason | Last Task | -| ------- | --------------- | ---------- | --------- | ------------ | ------------------------------------------------------------ | -| 1 | claude-opus-4-6 | 2026-04-04 | in-flight | — | cu-m01 + cu-m02 merged (#398, #399); open questions resolved | +| 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 | in-flight | — | cu-m03/04/05 merged; cu-m06 + cu-m07 dispatched in worktrees | ## Scratchpad diff --git a/docs/TASKS.md b/docs/TASKS.md index 54542fc..df39fad 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -23,43 +23,43 @@ ## Milestone 3 — Gateway bootstrap token recovery -| id | status | description | issue | agent | branch | depends_on | estimate | notes | -| -------- | ----------- | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- | -| CU-03-01 | not-started | 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 | not-started | 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 | not-started | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session | — | sonnet | — | CU-03-02 | 10K | | -| CU-03-04 | not-started | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API | — | sonnet | — | CU-03-03 | 8K | | -| CU-03-05 | not-started | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01 | — | sonnet | — | CU-03-03 | 10K | | -| CU-03-06 | not-started | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path | — | sonnet | — | CU-03-05 | 8K | | -| CU-03-07 | not-started | Tests: integration tests for each recovery path (happy + error) | — | sonnet | — | CU-03-06 | 10K | | -| CU-03-08 | not-started | Code review + remediation | — | haiku | — | CU-03-07 | 4K | | +| 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 | not-started | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup | — | sonnet | — | CU-02-03 | 3K | | -| CU-04-02 | not-started | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output | — | sonnet | — | CU-04-01 | 5K | | -| CU-04-03 | not-started | Verify help snapshots render readably; update any docs with stale output | — | haiku | — | CU-04-02 | 3K | | -| CU-04-04 | not-started | 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 | not-started | Tests + code review for CU-04-04 | — | haiku | — | CU-04-04 | 4K | | +| 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 | not-started | `mosaic forge` — subcommands: `run`, `status`, `resume`, `personas list` | — | sonnet | — | CU-02-03 | 18K | User priority | -| CU-05-02 | not-started | `mosaic storage` — subcommands: `status`, `tier show`, `tier switch`, `export`, `import`, `migrate` | — | sonnet | — | CU-02-03 | 15K | | -| CU-05-03 | not-started | `mosaic queue` — subcommands: `list`, `stats`, `pause/resume`, `jobs tail`, `drain` | — | sonnet | — | CU-02-03 | 12K | | -| CU-05-04 | not-started | `mosaic memory` — subcommands: `search`, `stats`, `insights list`, `preferences list` | — | sonnet | — | CU-02-03 | 12K | | -| CU-05-05 | not-started | `mosaic brain` — subcommands: `projects list/create`, `missions list`, `tasks list`, `conversations list` | — | sonnet | — | CU-02-03 | 15K | | -| CU-05-06 | not-started | `mosaic auth` — subcommands: `users list/create/delete`, `sso list`, `sso test`, `sessions list` | — | sonnet | — | CU-03-03 | 15K | needs gateway login | -| CU-05-07 | not-started | `mosaic log` — subcommands: `tail`, `search`, `export`, `level ` | — | sonnet | — | CU-02-03 | 10K | | -| CU-05-08 | not-started | `mosaic macp` — subcommands: `tasks list`, `submit`, `gate`, `events tail` | — | sonnet | — | CU-02-03 | 12K | | -| CU-05-09 | not-started | Wire all eight `registerCommand` calls into packages/mosaic/src/cli.ts | — | haiku | — | CU-05-01…8 | 3K | | -| CU-05-10 | not-started | Integration test: `mosaic --help` exits 0 for every new command | — | haiku | — | CU-05-09 | 5K | | +| 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` diff --git a/docs/scratchpads/cli-unification-20260404.md b/docs/scratchpads/cli-unification-20260404.md index 71fd0c2..b920cf2 100644 --- a/docs/scratchpads/cli-unification-20260404.md +++ b/docs/scratchpads/cli-unification-20260404.md @@ -154,6 +154,43 @@ No code changes to `apps/`, `packages/mosaic/`, or any other runtime package. Se - **pr-create.sh wrapper bug:** Discovered during M1 — `~/.config/mosaic/tools/git/pr-create.sh` line 158 uses `eval "$CMD"`, which shell-evaluates any backticks / `$(…)` / `${…}` in PR bodies. Workaround: strip backticks from PR bodies (use bold / italic / plain text instead), or use `tea pr create` directly. Captured in openbrain as gotcha. Should be fixed upstream in Mosaic tools repo at some point, but out of scope for this mission. - **Mosaic coord / orchestrator session lock drift:** `.mosaic/orchestrator/session.lock` gets re-written every session launch and shows up as a dirty working tree on branch switch. Not blocking — just noise to ignore. +## Session 2 Log (2026-04-05) + +**Session 2 agent:** claude-opus-4-6[1m] +**Mode:** parallel orchestration across worktrees + +### Wave 1 — M3 (gateway token recovery) + +- CU-03-01 plan landed as PR #401 → `docs/plans/gateway-token-recovery.md`. Confirmed no server changes needed — AdminGuard already accepts BetterAuth cookies, `POST /api/admin/tokens` is the existing mint endpoint. +- CU-03-02..07 implemented as PR #411: `mosaic gateway login` (interactive BetterAuth sign-in, session persisted), `mosaic gateway config rotate-token`, `mosaic gateway config recover-token`, fix for `bootstrapFirstUser` "user exists, no token" dead-end, 22 new unit tests. New files: `commands/gateway/login.ts`, `commands/gateway/token-ops.ts`. +- CU-03-08 independent code review surfaced 2 BLOCKER findings (session.json world-readable, password echoed during prompt) + 3 important findings (trimmed password, cross-gateway token persistence, unsafe `--password` flag). Remediated in PR #414: `saveSession` writes mode 0o600, new `promptSecret()` uses TTY raw mode, persistence target now matches `--gateway` host, `--password` marked UNSAFE with warning. + +### Wave 2 — M4 (help ergonomics + mosaic config) + +- CU-04-01..03 landed as PR #402: `configureHelp({ sortSubcommands: true })` on root + gateway subgroup, plus an `addHelpText('after', …)` grouped-reference section (Commander 13 has no native command-group API). +- CU-04-04/05 landed as PR #408: top-level `mosaic config` with `show|get|set|edit|path`, extends `config/config-service.ts` with `readAll`, `getValue`, `setValue`, `getConfigPath`, `isInitialized` + `ConfigSection`/`ResolvedConfig` types. Additive only. + +### Wave 3 — M5 (sub-package CLI surface, 8 commands + integration) + +Parallel-dispatched in isolated worktrees. All merged: + +- PR #403 `mosaic brain`, PR #404 `mosaic queue`, PR #405 `mosaic storage`, PR #406 `mosaic memory`, PR #407 `mosaic log`, PR #410 `mosaic macp`, PR #412 `mosaic forge`, PR #413 `mosaic auth`. +- Every package exports `registerCommand(parent: Command)` co-located with library code, following `@mosaicstack/quality-rails` pattern. Each wired into `packages/mosaic/src/cli.ts` with alphabetized `register…Command(program)` calls. +- PR #415 landed CU-05-10 integration smoke test (`packages/mosaic/src/cli-smoke.spec.ts`, 19 tests covering all 9 registrars) PLUS a pre-existing exports bug fix in `packages/macp/package.json` (`default` pointed at `./src/index.ts` instead of `./dist/index.js`, breaking ERR_MODULE_NOT_FOUND when compiled mosaic CLI tried to load macp at runtime). Caught by empirical `node packages/mosaic/dist/cli.js --help` test before merge. + +### New gotchas captured in Session 2 + +- **`pr-create.sh` "Remote repository required" failure:** wrapper can't detect origin in multi-remote contexts. Fallback used throughout: direct Gitea API `curl -X POST …/api/v1/repos/mosaicstack/mosaic-stack/pulls` with body JSON. +- **`publish` workflow killed on post-merge pushes:** pipelines 735, 742, 747, 750, 758, 767 all show the Docker build step killed after `ci` workflow succeeded. Pre-existing infrastructure issue (observed on #714/#715 pre-mission). The `ci` workflow is the authoritative gate; `publish` killing is noise. +- **macp exports.default misaligned:** latent bug from original monorepo consolidation — every other package already pointed at `dist/`. Only exposed when compiled CLI started loading macp at runtime. +- **Commander 13 grouping:** no native command-group API; workaround is `addHelpText('after', groupedReferenceString)` + alphabetized flat list via `sortSubcommands: true`. + +### Wave 4 — M6 + M7 (in-flight) + +- M6 `mosaic telemetry` dispatched to full-milestone subagent in isolated worktree. Full scope: CU-06-01..05 including `@mosaicstack/telemetry-client-js` dependency, local OTEL wrapper (`telemetry local {status,tail,jaeger}`), opt-in remote path with dry-run default, persistent consent state in config service, tests, codex review. +- M7 first-run UX dispatched to full-milestone subagent in isolated worktree. Full scope: CU-07-01..04 including `install.sh` `--yes`/`--no-auto-launch` flags + wizard handoff, wizard/gateway-install coordination via transient `$XDG_RUNTIME_DIR/mosaic-install-state.json`, `runPostInstallVerification` exposed as `mosaic gateway verify`, Docker-based `tools/e2e-install-test.sh`. +- M8 (docs + release) gated on M6+M7 landing; will be single-orchestrator PR after both merge. + ## Verification Evidence ### CU-01-01 (PR #398)