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

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.