feat: mosaic uninstall (IUH-M01) (#429)

docs/scratchpads/install-ux-hardening-20260405.md

@@ -0,0 +1,69 @@
+# Install UX Hardening — IUH-M01 Session Notes
+
+## Session: 2026-04-05 (agent-ad6b6696)
+
+### Plan
+
+**Manifest schema decision:**
+
+- Version 1 JSON at `~/.config/mosaic/.install-manifest.json` (mode 0600)
+- Written by `tools/install.sh` after successful install
+- Fields: version, installedAt, cliVersion, frameworkVersion, mutations{directories, npmGlobalPackages, npmrcLines, shellProfileEdits, runtimeAssetCopies}
+- Uninstall reads it; if missing → heuristic mode (warn user)
+
+**File list:**
+
+- NEW: `packages/mosaic/src/runtime/install-manifest.ts` — read/write helpers + types
+- NEW: `packages/mosaic/src/runtime/install-manifest.spec.ts` — unit tests
+- NEW: `packages/mosaic/src/commands/uninstall.ts` — command implementation
+- NEW: `packages/mosaic/src/commands/uninstall.spec.ts` — unit tests
+- MOD: `packages/mosaic/src/cli.ts` — register `uninstall` command
+- MOD: `tools/install.sh` — write manifest on success + add `--uninstall` path
+
+**Runtime asset list (from mosaic-link-runtime-assets / framework/install.sh):**
+
+- `~/.claude/CLAUDE.md` (source: `$MOSAIC_HOME/runtime/claude/CLAUDE.md`)
+- `~/.claude/settings.json` (source: `$MOSAIC_HOME/runtime/claude/settings.json`)
+- `~/.claude/hooks-config.json` (source: `$MOSAIC_HOME/runtime/claude/hooks-config.json`)
+- `~/.claude/context7-integration.md` (source: `$MOSAIC_HOME/runtime/claude/context7-integration.md`)
+- `~/.config/opencode/AGENTS.md` (source: `$MOSAIC_HOME/runtime/opencode/AGENTS.md`)
+- `~/.codex/instructions.md` (source: `$MOSAIC_HOME/runtime/codex/instructions.md`)
+
+**Reversal logic:**
+
+1. If `.mosaic-bak-<stamp>` exists for a file → restore it
+2. Else if managed copy exists → remove it
+3. Never touch files not in the known list
+
+**npmrc reversal:**
+
+- Only remove line `@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/`
+- If manifest has the line, use that as authoritative; else check heuristically
+
+**PATH reversal:**
+
+- Check install.sh: it does NOT add PATH entries to shell profiles (framework/install.sh migration removes old `$MOSAIC_HOME/bin` PATH entries in v0/v1→v2 migration, but new install does NOT add PATH)
+- ASSUMPTION: No PATH edits in current install (v0.0.24+). Shell profiles not modified by current install.
+- The `$PREFIX/bin` is mentioned in a warning but NOT added to shell profiles by install.sh.
+- shellProfileEdits array will be empty for new installs; heuristic mode also skips it.
+
+**Test strategy:**
+
+- Unit test manifest read/write with temp dir mocking
+- Unit test command registration
+- Unit test dry-run flag (no actual fs mutations)
+- Unit test --keep-data skips protected paths
+- Unit test heuristic mode warning
+
+**Implementation order:**
+
+1. install-manifest.ts helpers
+2. install-manifest.spec.ts tests
+3. uninstall.ts command
+4. uninstall.spec.ts tests
+5. cli.ts registration
+6. tools/install.sh manifest writing + --uninstall path
+
+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.