mandrel 2.59.0 → 2.61.0

package/lib/cli/uninstall.js

@@ -1,53 +1,10 @@
 // lib/cli/uninstall.js
 /**
- * `mandrel uninstall` subcommand.
- *
- * Reverses a recorded install by consuming the install ledger written by the
- * consent-first bootstrap (`.agents/.install-manifest.json`, Story #3524).
- * Each ledger entry is a mutation-manifest record
- * (`{ phaseGroup, target, action, reversible }`); uninstall walks the
- * reversible entries and undoes exactly the mutation the install applied,
- * keyed off the entry's `target` path.
- *
- * Design goals
- * ------------
- * - **Preserve pre-existing user content.** Reversal is marker-based, not
- *   blunt file deletion: the CLAUDE.md import block is stripped (not the file
- *   removed) so a CLAUDE.md the operator authored before install survives;
- *   the `.claude/settings.json` sync hook is spliced out without touching
- *   other hooks; the `.gitignore` entries are removed without disturbing the
- *   operator's own ignore rules; only the framework's own npm scripts are
- *   removed from `package.json`. A file is deleted outright only when
- *   stripping the framework block leaves it empty / framework-only (the
- *   install created it from nothing).
- * - **GitHub-side state is never touched by default.** The `github-admin`
- *   ledger entries carry `reversible: false`; they are surfaced as a manual
- *   rollback checklist and are only acted on when the operator opts in with
- *   `--include-github` (which, for now, still only enumerates them — remote
- *   admin reversal is out of scope for this Story and would require the same
- *   `gh` plumbing the bootstrap uses).
- * - **Idempotent.** Re-running after a successful uninstall is a no-op: the
- *   ledger is removed last, and every reversal step is a no-op when the
- *   marker is already absent.
- *
- * Output contract
- * ---------------
- *   reversed file → "✔  reverted <target>   <detail>"
- *   skipped       → "•  skipped  <target>   <reason>"
- *   manual (gh)   → "!  manual   <target>   <detail>"
- *   final         → "✅  Uninstalled (<n> reversed, <m> manual follow-ups)"
- *                  | "❌  No install ledger found — nothing to uninstall."
- *
- * All output goes to process.stdout (never console.log — the repo enforces a
- * no-console rule). Exit code 0 on success (including the no-ledger case,
- * which is a benign no-op), 1 only on an unrecoverable error.
- *
- * Injectable seams (used by tests so no real filesystem is touched):
- *   - `projectRoot`  — overrides the resolved consumer root.
- *   - `fsImpl`       — replaces the `node:fs` surface.
- *   - `write`        — replaces process.stdout.write.
- *   - `exit`         — replaces process.exit.
- *   - `includeGithub`— forces the --include-github behaviour.
+ * `mandrel uninstall`: reverse the reversible entries of the install ledger
+ * (`.agents/.install-manifest.json`). Reversal is marker-based so
+ * operator-authored content survives; a file is deleted only when the install
+ * created it. `github-admin` entries (`reversible: false`) are only listed as
+ * manual follow-ups. Idempotent: the ledger is removed last.
  *
  * @module cli/uninstall
  */
@@ -74,16 +31,7 @@ import {
   QUALITY_NPM_SCRIPTS,
 } from '../../.agents/scripts/lib/bootstrap/quality-bootstrap.js';
 
-// ---------------------------------------------------------------------------
-// Project-root resolution
-// ---------------------------------------------------------------------------
-
 /**
- * Resolve the consumer project root — the directory that holds `.agents/`.
- * `mandrel uninstall` runs from the consumer's checkout, so the install
- * ledger and every target path are anchored at `process.cwd()`. This mirrors
- * how `lib/cli/sync.js` and the doctor checks anchor consumer-facing paths.
- *
  * @param {() => string} [cwd=process.cwd]
  * @returns {string}
  */
@@ -91,17 +39,10 @@ function resolveProjectRoot(cwd = () => process.cwd()) {
   return cwd();
 }
 
-// ---------------------------------------------------------------------------
-// npm-script removal set
-// ---------------------------------------------------------------------------
-
 /**
- * The exact `package.json` scripts the bootstrap seeds. Reversal removes a
- * script key only when its value still equals the framework-seeded command —
- * an operator who overwrote the value keeps their version. `prepare` is
- * special: the bootstrap may *append* the sync command to an existing
- * `prepare`, so reversal strips the framework fragment rather than deleting
- * the whole key. Mirrors `ensurePackageJson` / `ensureQualityNpmScripts`.
+ * Scripts the bootstrap seeds; one is removed only while its value still
+ * equals the seeded command. `prepare` is handled separately because the
+ * sync command may have been appended to an existing value.
  *
  * @type {Readonly<Record<string, string>>}
  */
@@ -111,10 +52,6 @@ const FRAMEWORK_NPM_SCRIPTS = Object.freeze({
   ...QUALITY_NPM_SCRIPTS,
 });
 
-// ---------------------------------------------------------------------------
-// Pure reversal helpers (filesystem effects via the injected fsImpl)
-// ---------------------------------------------------------------------------
-
 /**
  * @typedef {object} ReversalOutcome
  * @property {'reverted'|'skipped'|'manual'} kind
@@ -123,15 +60,9 @@ const FRAMEWORK_NPM_SCRIPTS = Object.freeze({
  */
 
 /**
- * Strip the framework system-prompt import block from a `CLAUDE.md`. The file
- * is removed only when it is byte-identical to the install-authored template
- * (`SYSTEM_PROMPT_CLAUDE_MD`). Any other file — including one whose only
- * operator content is markdown headings — is preserved with just the framework
- * block excised.
- *
- * Using a byte-equality check rather than a "non-`#` meaningful lines"
- * heuristic prevents data loss when an operator's pre-install `CLAUDE.md`
- * consists entirely of markdown headings (all lines start with `#`).
+ * Strip the system-prompt import block from `CLAUDE.md`. The file is deleted
+ * only when byte-identical to the install template — a heading-only heuristic
+ * would delete an operator's all-headings file.
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -147,9 +78,6 @@ function revertClaudeMd(projectRoot, fsImpl) {
   if (!original.includes(SYSTEM_PROMPT_IMPORT)) {
     return { kind: 'skipped', target: rel, detail: 'import already absent' };
   }
-  // Delete only when the file is exactly the install-authored template — i.e.
-  // the install created it from nothing. Operator-authored content (even an
-  // all-headings file) must survive.
   if (original.trim() === SYSTEM_PROMPT_CLAUDE_MD.trim()) {
     fsImpl.rmSync(target, { force: true });
     return {
@@ -158,8 +86,7 @@ function revertClaudeMd(projectRoot, fsImpl) {
       detail: 'removed install-created CLAUDE.md',
     };
   }
-  // Remove the full block first (heading + import), then fall back to the
-  // bare import line so a hand-edited block without the heading still clears.
+  // Full block first, then the bare import line for a hand-edited block.
   let next = original.includes(SYSTEM_PROMPT_BLOCK)
     ? original.replace(SYSTEM_PROMPT_BLOCK, '')
     : original;
@@ -169,7 +96,6 @@ function revertClaudeMd(projectRoot, fsImpl) {
       .filter((line) => line.trim() !== SYSTEM_PROMPT_IMPORT)
       .join('\n');
   }
-  // Collapse any run of 3+ blank lines the splice may have produced.
   next = next.replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
   fsImpl.writeFileSync(
     target,
@@ -184,10 +110,8 @@ function revertClaudeMd(projectRoot, fsImpl) {
 }
 
 /**
- * Splice the framework UserPromptSubmit sync hook **and** the plugin
- * enablement keys (Story #3576) out of `.claude/settings.json`, leaving every
- * other hook and setting intact. When the settings file is left with no hooks
- * and no other keys, it is removed.
+ * Splice the sync hook and any legacy plugin-enablement keys out of
+ * `.claude/settings.json`, keeping everything else; delete the file if empty.
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -207,9 +131,6 @@ function revertClaudeSettings(projectRoot, fsImpl) {
 
   let mutated = false;
 
-  // 1. Strip any legacy plugin-enablement keys (#3576). The flat-command
-  //    projection no longer writes these, but a consumer upgraded from a
-  //    #3576 install may still carry them — clean them up on uninstall.
   if (
     settings.enabledPlugins &&
     settings.enabledPlugins['mandrel@mandrel'] !== undefined
@@ -228,7 +149,6 @@ function revertClaudeSettings(projectRoot, fsImpl) {
     mutated = true;
   }
 
-  // 2. Splice out the UserPromptSubmit sync hook.
   if (Array.isArray(groups)) {
     const kept = groups
       .map((group) => ({
@@ -273,11 +193,8 @@ function revertClaudeSettings(projectRoot, fsImpl) {
 }
 
 /**
- * Remove the generated Claude Code command projection: the flat
- * `.claude/commands/` tree. The tree is generated from `.agents/workflows/`, so
- * it is safe to remove wholesale (it is gitignored and never hand-edited). Any
- * legacy #3576 plugin projection (`.claude/plugins/mandrel/` +
- * `.claude/.claude-plugin/`) left by an older install is also removed.
+ * Remove the generated (gitignored, never hand-edited) `.claude/commands/`
+ * tree plus any legacy plugin projection.
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -287,7 +204,6 @@ function revertClaudeCommands(projectRoot, fsImpl) {
   const rel = '.claude/commands';
   const targets = [
     path.join(projectRoot, '.claude', 'commands'),
-    // Legacy #3576 plugin projection — clean it up too if present.
     path.join(projectRoot, '.claude', 'plugins', 'mandrel'),
     path.join(projectRoot, '.claude', '.claude-plugin'),
   ];
@@ -310,13 +226,9 @@ function revertClaudeCommands(projectRoot, fsImpl) {
 }
 
 /**
- * Remove the two `.gitignore` blocks the install appended (the
- * `.claude/commands/` and `.mcp.json` entries), preserving every other line
- * the operator authored. When the file is left empty it is removed.
- *
- * The `.mcp.json` ignore block is intentionally retained when a real
- * `.mcp.json` exists at the project root: that file may carry secrets and
- * removing the ignore entry would expose it on the next `git add .`.
+ * Remove the install's `.gitignore` blocks, keeping operator lines. The
+ * `.mcp.json` block is kept while a real `.mcp.json` exists — it may carry
+ * secrets and would otherwise be exposed to `git add .`.
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -333,8 +245,6 @@ function revertGitignore(projectRoot, fsImpl) {
   let next = original;
   for (const [key, def] of Object.entries(GITIGNORE_BLOCKS)) {
     if (next.includes(def.block)) {
-      // Retain the .mcp.json ignore entry when a real .mcp.json is present —
-      // removing it would expose a potentially secret-bearing file to git.
       if (key === 'mcp' && mcpJsonExists) {
         continue;
       }
@@ -361,10 +271,6 @@ function revertGitignore(projectRoot, fsImpl) {
 }
 
 /**
- * Remove the framework-seeded npm scripts (and the appended `prepare`
- * fragment) from `package.json`, leaving every operator-authored script and
- * field intact. A script whose value the operator overwrote is preserved.
- *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
  * @returns {ReversalOutcome}
@@ -386,11 +292,8 @@ function revertPackageJson(projectRoot, fsImpl) {
       removed.push(name);
     }
   }
-  // `prepare` may be the bare sync command (delete it) or an operator command
-  // with the sync fragment appended via ` && ` (strip just the fragment).
-  // When stripping leaves an empty string, delete the key rather than writing
-  // `"prepare": ""`.  Only push 'prepare' onto `removed` when the value
-  // actually changed (i.e. the fragment was present and was stripped).
+  // `prepare` is either the bare sync command or an operator command with it
+  // appended via ` && `; strip just the fragment, never write `""`.
   const prepare = pkg.scripts.prepare;
   if (typeof prepare === 'string' && prepare.includes(SYNC_COMMAND)) {
     if (prepare === SYNC_COMMAND) {
@@ -426,24 +329,9 @@ function revertPackageJson(projectRoot, fsImpl) {
 }
 
 /**
- * Remove an install-created `.agentrc.json` — but never one the install did
- * not create (Story #3895, data-loss fix for `docs/install-bootstrap-review.md`
- * Finding B.2).
- *
- * The ledger now records the **live** outcome of the `agentrc` bootstrap phase
- * as `executedAction` (schema v2). `ensureAgentrc` returns `seeded` when it
- * wrote the file from the starter and `already-present` when it left a
- * pre-existing, operator-authored file untouched. Reversal is gated on that:
- *
- * - `executedAction === 'already-present'` → the operator owned this file
- *   before the install ran; the install created nothing, so deleting it would
- *   be data loss. Skip.
- * - `executedAction === 'seeded'` (or any other create-class outcome) → the
- *   install authored the file from nothing; deleting it returns the project to
- *   the pre-install state.
- * - `executedAction` absent (legacy v1 ledger / no hint) → cannot happen for a
- *   v2 ledger written by this framework, but if encountered we fail **safe**
- *   and skip rather than risk deleting operator content.
+ * Delete `.agentrc.json` only when the ledger's `executedAction` is `seeded`
+ * (the install wrote it). `already-present`, a missing hint, or anything else
+ * fails safe and preserves the operator's file.
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -456,9 +344,6 @@ function revertAgentrc(projectRoot, fsImpl, executedAction) {
   if (!fsImpl.existsSync(target)) {
     return { kind: 'skipped', target: rel, detail: 'file absent' };
   }
-  // Only delete a file the install actually created. Any non-`seeded` outcome
-  // (pre-existing `already-present`, a missing hint, or an unexpected value)
-  // is treated as "not install-created" → preserve the operator's file.
   if (executedAction !== 'seeded') {
     return {
       kind: 'skipped',
@@ -475,14 +360,9 @@ function revertAgentrc(projectRoot, fsImpl, executedAction) {
 }
 
 /**
- * Reverse the `.husky/pre-commit` quality hook. The file is removed only when
- * it is byte-identical to the install-authored template (`DOWNSTREAM_PRE_COMMIT`).
- * Any other hook — including one whose only non-framework lines are a shebang
- * or comments — is preserved with just the quality-preview line stripped.
- *
- * Using a byte-equality check rather than a "non-`#` meaningful lines"
- * heuristic prevents data loss when an operator's pre-install hook consists
- * entirely of a shebang line and/or comments (all lines start with `#`).
+ * Strip the quality-preview line from `.husky/pre-commit`; delete the file
+ * only when byte-identical to the install template (an operator hook of only
+ * a shebang and comments must survive).
  *
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
@@ -498,9 +378,6 @@ function revertPreCommitHook(projectRoot, fsImpl) {
   if (!original.includes(PRE_COMMIT_MARKER)) {
     return { kind: 'skipped', target: rel, detail: 'quality line absent' };
   }
-  // Delete only when the file is exactly the install-authored template — i.e.
-  // the install created it from nothing. Operator-authored content (even an
-  // all-comments hook) must survive.
   if (original.trim() === DOWNSTREAM_PRE_COMMIT.trim()) {
     fsImpl.rmSync(target, { force: true });
     return {
@@ -521,19 +398,9 @@ function revertPreCommitHook(projectRoot, fsImpl) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Dispatch table — ledger target → reversal helper
-// ---------------------------------------------------------------------------
-
 /**
- * Map a reversible ledger entry's `target` to the helper that undoes it.
- * Targets that map to the same file (e.g. both `repo-config` and
- * `quality-gates` touch `package.json`) are deduped by the caller so each
- * file is reverted once.
- *
- * Handlers take `(root, fsImpl)`; `.agentrc.json` additionally takes the
- * recorded `executedAction` (the third arg, ignored by the others) so it can
- * preserve a pre-existing file the install did not create (Story #3895).
+ * Ledger target → reversal helper. Only `revertAgentrc` reads the third
+ * `executedAction` argument.
  *
  * @type {Readonly<Record<string, (root: string, fsImpl: typeof fs, executedAction?: string) => ReversalOutcome>>}
  */
@@ -547,23 +414,10 @@ const REVERSAL_BY_TARGET = Object.freeze({
   '.husky/pre-commit': revertPreCommitHook,
 });
 
-// ---------------------------------------------------------------------------
-// Planner (pure over the ledger; effects deferred to the helpers)
-// ---------------------------------------------------------------------------
-
 /**
- * Partition a ledger's entries into the reversible local-file reversals to
- * run, the remote (`github-admin`) entries to surface as manual follow-ups,
- * and the set of unique file targets to revert (deduped).
- *
- * Pure — derives entirely from the ledger record, with no filesystem access.
- *
- * The returned `executedActionByTarget` map carries the per-target
- * `executedAction` recorded in the ledger (schema v2, Story #3895). When more
- * than one entry shares a target (e.g. the repo-config `create` and
- * quality-gates `merge` entries for `.agentrc.json`), the first defined
- * `executedAction` wins — they resolve to the same bootstrap phase outcome, so
- * the choice is unambiguous.
+ * Partition ledger entries into deduped file targets and manual follow-ups.
+ * Pure. For a target shared by several entries, the first defined
+ * `executedAction` wins (they record the same phase outcome).
  *
  * @param {{ entries: Array<import('../../.agents/scripts/lib/bootstrap/manifest.js').MutationManifestEntry & { executedAction?: string }> }} ledger
  * @returns {{ fileTargets: string[], manual: import('../../.agents/scripts/lib/bootstrap/manifest.js').MutationManifestEntry[], executedActionByTarget: Record<string, string> }}
@@ -579,8 +433,7 @@ export function planUninstall(ledger) {
       continue;
     }
     if (!REVERSAL_BY_TARGET[entry.target]) {
-      // A reversible entry with no known handler is surfaced as manual so the
-      // operator is never silently left with an un-reverted mutation.
+      // Never silently leave a mutation un-reverted.
       manual.push(entry);
       continue;
     }
@@ -598,10 +451,6 @@ export function planUninstall(ledger) {
   return { fileTargets, manual, executedActionByTarget };
 }
 
-// ---------------------------------------------------------------------------
-// Formatting
-// ---------------------------------------------------------------------------
-
 const TARGET_COL = 22;
 
 function pad(value, width) {
@@ -625,13 +474,7 @@ function formatOutcome(outcome) {
   return `${icon}  ${label} ${pad(outcome.target, TARGET_COL)}  ${outcome.detail}\n`;
 }
 
-// ---------------------------------------------------------------------------
-// Runner (exported for testing)
-// ---------------------------------------------------------------------------
-
 /**
- * Execute the uninstall against a project root.
- *
  * @param {{
  *   projectRoot?: string,
  *   cwd?: () => string,
@@ -670,8 +513,7 @@ export function runUninstall({
 
   if (!ledger) {
     write('❌  No install ledger found — nothing to uninstall.\n');
-    // A missing ledger is a benign no-op (never installed, or already
-    // uninstalled), so this is success, not an error.
+    // Never installed or already uninstalled: a benign no-op.
     exit(0);
     return {
       revertedCount: 0,
@@ -696,7 +538,6 @@ export function runUninstall({
 
   const { fileTargets, manual, executedActionByTarget } = planUninstall(ledger);
 
-  // --- Dry run — show what would be reversed without touching anything. ---
   if (dryRun) {
     write('mandrel uninstall — planned reversal (dry run)\n');
     for (const target of fileTargets) {
@@ -734,22 +575,14 @@ export function runUninstall({
   for (const target of fileTargets) {
     let outcome;
     try {
-      // The third arg carries the recorded `executedAction` for the target
-      // (schema v2). Only `revertAgentrc` consults it; the other handlers
-      // ignore extra arguments. This is how uninstall avoids deleting a
-      // pre-existing `.agentrc.json` the install did not create (Story #3895).
       outcome = REVERSAL_BY_TARGET[target](
         root,
         fsImpl,
         executedActionByTarget[target],
       );
     } catch (err) {
-      // An operator-edited file that contains invalid JSON (or any other
-      // unexpected throw from the reversal helper) must not abort the whole
-      // uninstall and leave earlier targets reverted while later ones are not.
-      // Emit a `skipped` outcome so the operator knows they must revert this
-      // target by hand, and leave the install ledger intact so a re-run after
-      // the file is fixed can resume cleanly.
+      // One corrupt operator file must not abort a half-done uninstall;
+      // report it and keep the ledger so a re-run can resume.
       outcome = {
         kind: 'skipped',
         target,
@@ -761,9 +594,7 @@ export function runUninstall({
     write(formatOutcome(outcome));
   }
 
-  // GitHub-admin (and any unhandled reversible) entries are manual follow-ups.
-  // They are NEVER acted on automatically; --include-github only annotates
-  // that the operator acknowledged them (remote reversal stays out of scope).
+  // Never acted on automatically; --include-github only acknowledges them.
   let manualCount = 0;
   for (const entry of manual) {
     manualCount += 1;
@@ -775,10 +606,7 @@ export function runUninstall({
     );
   }
 
-  // Remove the ledger last so a re-run is a clean no-op and a partial failure
-  // mid-reversal still leaves the ledger for a resume. When any target was
-  // skipped due to a parse error, leave the ledger in place so the operator
-  // can fix the corrupt file and re-run to complete the uninstall.
+  // Ledger goes last, and stays when any target failed, so a re-run resumes.
   const lp = ledgerPath(root);
   if (fsImpl.existsSync(lp) && parseErrorCount === 0) {
     fsImpl.rmSync(lp, { force: true });
@@ -809,16 +637,9 @@ export function runUninstall({
   return { revertedCount, manualCount, ledgerFound: true, parseErrorCount };
 }
 
-// ---------------------------------------------------------------------------
-// Subcommand entry point (called by bin/mandrel.js)
-// ---------------------------------------------------------------------------
-
 /**
- * Default export consumed by `bin/mandrel.js`.
- *
- * Supported flags:
- *   --include-github   Acknowledge GitHub-side manual follow-ups.
- *   --dry-run          Show what would be reversed without touching anything.
+ * Flags: `--include-github` (acknowledge GitHub-side follow-ups),
+ * `--dry-run`.
  *
  * @param {string[]} argv
  * @returns {Promise<void>}