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

IUH-M01: mosaic uninstall — top-level teardown + shell wrapper #428

New Issue
Open
opened 2026-04-05 16:48:33 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-04-05 16:48:33 +00:00
Owner
Copy Link

Mission: install-ux-hardening-20260405
Milestone: IUH-M01
Branch: feat/mosaic-uninstall
Agent tier: sonnet

Problem

Post-cli-unification audit: only mosaic gateway uninstall exists. A user who installs the Mosaic Stack via tools/install.sh has no clean reversal path for framework data, npm CLI, nested stack dependencies, runtime asset injections in ~/.claude/, npmrc scope mapping, or PATH edits.

Scope

Implement top-level mosaic uninstall with flags:

  • --framework — remove ~/.config/mosaic/ (honor --keep-data for SOUL.md, USER.md, TOOLS.md, memory/, sources/)
  • --cli — npm uninstall -g @mosaicstack/mosaic (takes nested stack deps with it)
  • --gateway — delegate to existing mosaic gateway uninstall
  • --all — all three + preserved user files + runtime asset reversal
  • --keep-data — never touch memory/, SOUL.md, gateway DB/storage
  • --yes — skip confirmation
  • --dry-run — list what would be removed, change nothing
  • (default, no flags) — interactive, prompt per category

Must also:

  1. Reverse runtime asset linking in ~/.claude/ — restore .mosaic-bak-* backups if present, remove managed copies otherwise
  2. Reverse npmrc scope mapping (@mosaicstack:registry=...) added by tools/install.sh
  3. Reverse PATH edits made by tools/install.sh in .bashrc/.zshrc/.profile
  4. Shell fallback: bash <(curl ... tools/install.sh) --uninstall path for users without a working CLI

Design prerequisite

Install manifest: ~/.config/mosaic/.install-manifest.json written by tools/install.sh on first successful install. Records every file/dir/shell-profile mutation. Uninstall uses this as the authoritative reversal spec. Missing manifest → fall back to heuristic mode with explicit warning.

Success Criteria

  • mosaic uninstall --dry-run lists every mutation without touching disk
  • mosaic uninstall --all --yes on a freshly-installed machine leaves no Mosaic trace (~/.config/mosaic/ gone, ~/.npm-global/lib/node_modules/@mosaicstack/mosaic gone, ~/.claude/settings.json restored or removed, ~/.npmrc scope line gone)
  • mosaic uninstall --framework --keep-data preserves SOUL/USER/TOOLS/memory
  • Shell fallback works from a broken-CLI state
  • Vitest coverage for dry-run, --all, --keep-data, partial state, missing manifest
  • Independent code review completed
  • PR merged to main, CI green, this issue closed

Files to touch

  • packages/mosaic/src/commands/uninstall.ts (new)
  • packages/mosaic/src/commands/uninstall.spec.ts (new)
  • packages/mosaic/src/cli.ts (register command)
  • tools/install.sh (write manifest on success, add --uninstall path)
  • packages/mosaic/src/runtime/asset-linker.ts or similar (reversal helpers — may need factoring out of mosaic-link-runtime-assets shell script)
**Mission:** install-ux-hardening-20260405 **Milestone:** IUH-M01 **Branch:** feat/mosaic-uninstall **Agent tier:** sonnet ## Problem Post-cli-unification audit: only `mosaic gateway uninstall` exists. A user who installs the Mosaic Stack via `tools/install.sh` has no clean reversal path for framework data, npm CLI, nested stack dependencies, runtime asset injections in `~/.claude/`, npmrc scope mapping, or PATH edits. ## Scope Implement top-level `mosaic uninstall` with flags: - `--framework` — remove `~/.config/mosaic/` (honor `--keep-data` for SOUL.md, USER.md, TOOLS.md, memory/, sources/) - `--cli` — `npm uninstall -g @mosaicstack/mosaic` (takes nested stack deps with it) - `--gateway` — delegate to existing `mosaic gateway uninstall` - `--all` — all three + preserved user files + runtime asset reversal - `--keep-data` — never touch memory/, SOUL.md, gateway DB/storage - `--yes` — skip confirmation - `--dry-run` — list what would be removed, change nothing - (default, no flags) — interactive, prompt per category Must also: 1. Reverse runtime asset linking in `~/.claude/` — restore `.mosaic-bak-*` backups if present, remove managed copies otherwise 2. Reverse npmrc scope mapping (`@mosaicstack:registry=...`) added by `tools/install.sh` 3. Reverse PATH edits made by `tools/install.sh` in `.bashrc`/`.zshrc`/`.profile` 4. Shell fallback: `bash <(curl ... tools/install.sh) --uninstall` path for users without a working CLI ## Design prerequisite Install manifest: `~/.config/mosaic/.install-manifest.json` written by `tools/install.sh` on first successful install. Records every file/dir/shell-profile mutation. Uninstall uses this as the authoritative reversal spec. Missing manifest → fall back to heuristic mode with explicit warning. ## Success Criteria - [ ] `mosaic uninstall --dry-run` lists every mutation without touching disk - [ ] `mosaic uninstall --all --yes` on a freshly-installed machine leaves no Mosaic trace (`~/.config/mosaic/` gone, `~/.npm-global/lib/node_modules/@mosaicstack/mosaic` gone, `~/.claude/settings.json` restored or removed, `~/.npmrc` scope line gone) - [ ] `mosaic uninstall --framework --keep-data` preserves SOUL/USER/TOOLS/memory - [ ] Shell fallback works from a broken-CLI state - [ ] Vitest coverage for dry-run, --all, --keep-data, partial state, missing manifest - [ ] Independent code review completed - [ ] PR merged to main, CI green, this issue closed ## Files to touch - `packages/mosaic/src/commands/uninstall.ts` (new) - `packages/mosaic/src/commands/uninstall.spec.ts` (new) - `packages/mosaic/src/cli.ts` (register command) - `tools/install.sh` (write manifest on success, add `--uninstall` path) - `packages/mosaic/src/runtime/asset-linker.ts` or similar (reversal helpers — may need factoring out of `mosaic-link-runtime-assets` shell script)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#428
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?