mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

docs: mission cli-unification-20260404 complete
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
ci/woodpecker/push/ci Pipeline was successful
Details

Browse Source 
Close out the mission book-keeping:
- MISSION-MANIFEST: status=completed, 8/8 milestones, all 8 AC checked,
  release link added
- TASKS: mark CU-06-01..05, CU-07-01..04, CU-08-01..04 done
- scratchpad: append Wave 4/5 outcomes, mission summary

Release: mosaic-v0.1.0 (@mosaicstack/mosaic@0.1.0)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jarvis
2026-04-05 02:48:52 -05:00
parent b9d464de61
commit df6f7306d3
3 changed files with 62 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/MISSION-MANIFEST.md
View File

@@ -7,35 +7,36 @@
**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-m06 / cu-m07 (parallel-eligible); cu-m08 gated on both
**Progress:** 5 / 8 milestones
**Status:** active
**Phase:** Complete
**Current Milestone:** —
**Progress:** 8 / 8 milestones
**Status:** completed
**Last Updated:** 2026-04-05
**Release:** [`mosaic-v0.1.0`](https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.1.0) (`@mosaicstack/mosaic@0.1.0`)
## Success Criteria
- [ ] 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
- [ ] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability
- [ ] 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
- [ ] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible
- [ ] 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
- [ ] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends
- [ ] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs
- [ ] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes
- [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 | 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 | — | — | — | — |
| # | 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
@@ -61,10 +62,10 @@
## 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 | in-flight | — | cu-m03/04/05 merged; cu-m06 + cu-m07 dispatched in worktrees |
| 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

38
docs/TASKS.md
View File

@@ -63,28 +63,28 @@
## Milestone 6 — `mosaic telemetry`
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| -------- | ----------- | ------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ---------------------------------------------- |
| CU-06-01 | not-started | Add `@mosaicstack/telemetry-client-js` as dependency of `@mosaicstack/mosaic` from Gitea registry | — | sonnet | — | CU-02-03 | 3K | |
| CU-06-02 | not-started | `mosaic telemetry local` — status, tail, Jaeger link (wraps existing apps/gateway/src/tracing.ts) | — | sonnet | — | CU-06-01 | 8K | |
| CU-06-03 | not-started | `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 | not-started | Persistent consent state in mosaic config; disabled by default | — | sonnet | — | CU-06-03 | 5K | |
| CU-06-05 | not-started | Tests + code review | — | haiku | — | CU-06-04 | 5K | |
| 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 | not-started | tools/install.sh: after npm install, hand off to `mosaic wizard` then `mosaic gateway install` | — | sonnet | — | CU-03-06 | 10K | |
| CU-07-02 | not-started | `mosaic wizard` and `mosaic gateway install` coordination: shared state, no duplicate prompts | — | sonnet | — | CU-07-01 | 12K | |
| CU-07-03 | not-started | Post-install verification step: "gateway healthy, tui connects, admin token on file" | — | sonnet | — | CU-07-02 | 8K | |
| CU-07-04 | not-started | End-to-end test on a clean container from scratch | — | haiku | — | CU-07-03 | 8K | |
| 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 | not-started | Update README.md with new command tree, install flow, and feature list | — | sonnet | — | CU-07-04 | 8K | |
| CU-08-02 | not-started | Update docs/guides/user-guide.md with all new sub-package commands | — | sonnet | — | CU-08-01 | 10K | |
| CU-08-03 | not-started | Version bump `@mosaicstack/mosaic`, publish to Gitea registry | — | opus | — | CU-08-02 | 3K | |
| CU-08-04 | not-started | 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 |
| -------- | ------ | ---------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
| 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 | |

20
docs/scratchpads/cli-unification-20260404.md
View File

@@ -185,11 +185,23 @@ Parallel-dispatched in isolated worktrees. All merged:
- **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)
### Wave 4 — M6 + M7 (parallel)
- 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.
- M6 `mosaic telemetry` landed as PR #417 (merge `a531029c`). Full scope CU-06-01..05: `@mosaicstack/telemetry-client-js` shim, `telemetry local {status,tail,jaeger}`, top-level `telemetry {status,opt-in,opt-out,test,upload}` with dry-run default, persistent consent state. New files: `packages/mosaic/src/commands/telemetry.ts`, `src/telemetry/client-shim.ts`, `src/telemetry/consent-store.ts`, plus `telemetry.spec.ts`.
- M7 unified first-run UX landed as PR #418 (merge `872c1245`). Full scope CU-07-01..04: `install.sh` `--yes`/`--no-auto-launch` flags + auto-handoff to wizard + gateway install, wizard/gateway-install coordination via transient state file, `mosaic gateway verify` post-install healthcheck, Docker-based `tools/e2e-install-test.sh`.
### Wave 5 — M8 (release)
- PR #419 (merge `b9d464de`) — CLI unification release v0.1.0. Single cohesive docs + release PR:
- README.md: unified command tree, new install UX, `mosaic gateway` and `mosaic config` sections, removed stale `@mosaicstack/cli` refs.
- docs/guides/user-guide.md: new "Sub-package Commands" + "Telemetry" sections covering all 11 top-level commands.
- `packages/mosaic/package.json`: bumped 0.0.21 → 0.1.0 (CI publishes on merge).
- Git tag: `mosaic-v0.1.0` (scoped to avoid collision with existing `v0.1.0` repo tag) — pushed to origin on merge sha.
- Gitea release: https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.1.0 — "@mosaicstack/mosaic v0.1.0 — CLI Unification".
### Mission outcome
All 8 milestones, all 8 success criteria, merged to main, green CI on every PR, released. Two sessions total (~10h combined). No rollbacks, no blocked milestones, no escalations required.
## Verification Evidence