@dalzoubi/dev-agents-sync 2.0.24 → 2.0.26

package/src/settings.mjs

@@ -8,7 +8,8 @@
  *
  * Invariants enforced here:
  *   - Additive: every existing setting and every consumer-authored hook is
- *     preserved untouched. We only append our own registrations.
+ *     preserved untouched. We only append our own registrations — and remove
+ *     our own registrations for RETIRED_HOOK_SCRIPTS, never anyone else's.
  *   - Idempotent (§9): a second merge adds no duplicates. Identity is the
  *     installed command path, so re-running is a no-op.
  *   - Tagged (§4): each injected hook entry carries `HOOK_TAG: true` so it is
@@ -106,17 +107,25 @@ function readSettings(absPath) {
   }
 }
 
+/**
+ * The command strings carried by one CLI-managed settings entry, in order, or []
+ * when the entry is absent, malformed, or consumer-authored.
+ *
+ * The HOOK_TAG check lives here rather than at each call site because EVERY read
+ * path — the idempotence check and the retirement prune alike — must ignore a
+ * consumer-authored entry pointing at the very same command: that is
+ * consumer-owned state and must survive untouched (spec risk 6).
+ */
+function managedCommandsIn(entry) {
+  if (!entry || entry[HOOK_TAG] !== true) return [];
+  const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
+  return hookList.filter((h) => h && typeof h.command === 'string').map((h) => h.command);
+}
+
 /** True if `event` already has a CLI-managed entry whose command targets `command`. */
 function hasManagedCommand(eventEntries, command) {
   if (!Array.isArray(eventEntries)) return false;
-  for (const entry of eventEntries) {
-    if (!entry || entry[HOOK_TAG] !== true) continue;
-    const hookList = Array.isArray(entry.hooks) ? entry.hooks : [];
-    for (const h of hookList) {
-      if (h && typeof h.command === 'string' && h.command === command) return true;
-    }
-  }
-  return false;
+  return eventEntries.some((entry) => managedCommandsIn(entry).includes(command));
 }
 
 /**
@@ -131,48 +140,174 @@ function buildManagedEntry({ matcher, command }) {
   };
 }
 
+/** True if `command` is on the retired list (exact match, never a prefix/substring). */
+function isRetiredCommand(command) {
+  return RETIRED_HOOK_SCRIPTS.some((h) => h.command === command);
+}
+
 /**
- * Computes the merged settings object additively. Pure — does not touch disk.
- * Returns { settings, changed }. Fails loud (ESETTINGS_PARSE) if the consumer's
- * `hooks` sub-tree has the wrong internal shape, BEFORE any merge — so no write
- * happens and the file stays byte-identical.
+ * True for a single `hooks[]` element that invokes a retired command.
+ *
+ * Shared by the two halves of the prune — the one that REPORTS what was removed
+ * (via `retiredCommandsIn`, which applies `isRetiredCommand` to the same
+ * `command`/shape guards `managedCommandsIn` enforces) and the one that DOES the
+ * removing. Those two must agree exactly or the prune would report a command it
+ * left in place, so the predicate is named once rather than spelled out twice.
+ */
+function isRetiredHook(hook) {
+  return Boolean(hook) && typeof hook.command === 'string' && isRetiredCommand(hook.command);
+}
+
+/** The retired commands carried by a single CLI-managed settings entry, or [] if none. */
+function retiredCommandsIn(entry) {
+  return managedCommandsIn(entry).filter(isRetiredCommand);
+}
+
+/**
+ * Removes managed registrations for retired hooks from `hooks` IN PLACE, across
+ * every event bucket.
+ *
+ * Returns two deliberately different views of the same prune:
+ *   - `commands` — the distinct retired commands removed (deduped, first-seen
+ *     order, so the result is deterministic §9). Callers answer "was X
+ *     de-registered?" from this.
+ *   - `count` — how many registrations were actually removed. One command can be
+ *     registered under several event buckets (a pre-retirement CLI, or a
+ *     hand-edit), so this is >= `commands.length`. It is the number a consumer
+ *     must read on their terminal: reporting the deduped length there would
+ *     under-count a real, multi-bucket edit to consumer-owned state (§6).
+ *
+ * Scans all buckets rather than only the ones named in RETIRED_HOOK_SCRIPTS: a
+ * pre-retirement CLI may have registered the command under a different event,
+ * and a stale registration pointing at a script that no longer ships fails
+ * every session with no detection (§5).
+ *
+ * The prune is HOOK-granular, not entry-granular: it filters `entry.hooks` down
+ * to its non-retired commands and drops the entry only once that array empties.
+ * `buildManagedEntry` only ever emits one command per entry, so the CLI cannot
+ * produce a multi-command entry itself — but a multi-command `hooks[]` is
+ * idiomatic Claude Code settings shape, and a consumer hand-adding their own
+ * command into our tagged entry produces exactly that. Dropping the whole entry
+ * would delete their command permanently (nothing managed re-adds it), breaking
+ * the module invariant above — and would equally un-register a still-shipped
+ * managed command sharing the entry, which `appendMissingEntries` has already
+ * seen as present and so will not re-add.
+ *
+ * Entries are REPLACED, never mutated, so the objects and arrays inside the
+ * consumer's parsed settings are never written through.
+ */
+function pruneRetiredEntries(hooks) {
+  const pruned = [];
+  for (const [event, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries)) continue;
+    let changed = false;
+    const kept = [];
+    for (const entry of entries) {
+      const retired = retiredCommandsIn(entry);
+      if (retired.length === 0) {
+        // Untagged (consumer-authored) or carrying nothing retired — untouched.
+        kept.push(entry);
+        continue;
+      }
+      pruned.push(...retired);
+      changed = true;
+      // `retired` being non-empty means managedCommandsIn found commands, which
+      // it only does for a tagged entry whose `hooks` is an array — so this is
+      // reachable only when `entry.hooks` is safe to filter.
+      const survivors = entry.hooks.filter((h) => !isRetiredHook(h));
+      // Only drop the entry outright once nothing of it is left.
+      if (survivors.length > 0) kept.push({ ...entry, hooks: survivors });
+    }
+    if (!changed) continue;
+    if (kept.length > 0) {
+      hooks[event] = kept;
+    } else {
+      // Drop the now-empty event bucket so we don't leave a dangling key.
+      delete hooks[event];
+    }
+  }
+  return { commands: [...new Set(pruned)], count: pruned.length };
+}
+
+/**
+ * Appends a managed entry for every registration in `hookScripts` not already
+ * wired, mutating the caller's `hooks` copy IN PLACE, and returns true when at
+ * least one was added.
+ *
+ * Event arrays are REPLACED, never mutated, so the arrays inside the consumer's
+ * parsed settings are never written through.
+ */
+function appendMissingEntries(hooks, hookScripts) {
+  let added = false;
+  for (const { event, matcher, command } of hookScripts) {
+    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+    // Already wired — idempotent no-op for this registration (§9).
+    if (hasManagedCommand(existing, command)) continue;
+    hooks[event] = [...existing, buildManagedEntry({ matcher, command })];
+    added = true;
+  }
+  return added;
+}
+
+/**
+ * Assigns `hooks` onto `settings` IN PLACE, dropping the key outright when no
+ * bucket survived, so neither write path can leave a dangling `"hooks": {}`
+ * behind. Both the merge and the removal path empty buckets and so must treat
+ * that end state identically; callers pass a shallow clone they own.
+ */
+function assignHooks(settings, hooks) {
+  if (Object.keys(hooks).length > 0) {
+    settings.hooks = hooks;
+  } else {
+    delete settings.hooks;
+  }
+}
+
+/**
+ * Computes the merged settings object: the additive pass, then a prune of
+ * managed registrations for retired hooks. Pure — does not touch disk.
+ * Returns { settings, changed, prunedRetired, prunedRetiredCount }. Fails loud (ESETTINGS_PARSE) if
+ * the consumer's `hooks` sub-tree has the wrong internal shape, BEFORE any merge
+ * or prune — so no write happens and the file stays byte-identical.
  */
 function computeMerge(current, hookScripts, absPath) {
   // Validate the internal shape of the consumer's hooks before merging so a
   // wrong-shape value is never silently corrupted or discarded (§5/§12).
   assertHooksShape(current.hooks, absPath);
 
-  // Shallow clone so we never mutate the caller's object; hooks is the only
-  // sub-tree we touch and we clone it per-event below before appending.
+  // Shallow clone so we never mutate the caller's object; `hooks` is the only
+  // sub-tree we touch, and both passes below replace event arrays rather than
+  // writing through to the consumer's own arrays.
   const next = { ...current };
   const hooks = { ...(next.hooks ?? {}) };
-  let changed = false;
 
-  for (const { event, matcher, command } of hookScripts) {
-    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
-    if (hasManagedCommand(existing, command)) {
-      // Already wired — idempotent no-op for this registration.
-      hooks[event] = existing;
-      continue;
-    }
-    hooks[event] = [...existing, buildManagedEntry({ matcher, command })];
-    changed = true;
-  }
+  const added = appendMissingEntries(hooks, hookScripts);
+  // Merge-then-prune: retirement is subtractive and runs AFTER the additive
+  // pass, so a command that is both shipped and retired cannot survive by
+  // being re-added in the same run.
+  const { commands: prunedRetired, count: prunedRetiredCount } = pruneRetiredEntries(hooks);
 
-  if (changed) {
-    next.hooks = hooks;
-  }
-  return { settings: next, changed };
+  const changed = added || prunedRetiredCount > 0;
+  if (changed) assignHooks(next, hooks);
+  return { settings: next, changed, prunedRetired, prunedRetiredCount };
 }
 
 /**
- * Idempotent, additive merge of the given hook registrations into the
- * consumer's `.claude/settings.json`.
+ * Idempotent merge of the given hook registrations into the consumer's
+ * `.claude/settings.json`: additive for shipped hooks, then a prune of managed
+ * registrations for retired ones (RETIRED_HOOK_SCRIPTS).
  *
  * @param {string} consumerCwd
  * @param {{ event: string, matcher: string, command: string }[]} hookScripts
  * @param {{ dryRun?: boolean }} [opts]
- * @returns {{ merged: boolean, dryRun: boolean, settingsPath: string }}
+ * @returns {{ merged: boolean, dryRun: boolean, settingsPath: string, prunedRetired: string[], prunedRetiredCount: number }}
+ *   `merged` is true when EITHER the additive pass or the prune changed the
+ *   settings. `prunedRetired` lists the DISTINCT retired commands this call
+ *   removed and is always an array — empty when nothing was pruned — so a caller
+ *   can tell "no retired entries existed" apart from "retirement isn't
+ *   supported". `prunedRetiredCount` is how many registrations were removed to
+ *   get there: >= `prunedRetired.length`, since one command can be registered
+ *   under several event buckets. Report the COUNT to users; match on the LIST.
  * @throws {SettingsParseError} with .code === 'ESETTINGS_PARSE' on malformed settings.json
  */
 export function mergeHookSettings(consumerCwd, hookScripts, opts = {}) {
@@ -182,20 +317,24 @@ export function mergeHookSettings(consumerCwd, hookScripts, opts = {}) {
   // Parse first — a malformed file fails loud BEFORE any write so the consumer's
   // file is never clobbered (§5/§12).
   const current = readSettings(absPath);
-  const { settings, changed } = computeMerge(current, hookScripts, absPath);
+  const { settings, changed, prunedRetired, prunedRetiredCount } = computeMerge(
+    current,
+    hookScripts,
+    absPath,
+  );
 
   if (dryRun) {
-    return { merged: changed, dryRun: true, settingsPath: absPath };
+    return { merged: changed, dryRun: true, settingsPath: absPath, prunedRetired, prunedRetiredCount };
   }
 
   if (!changed) {
     // Nothing to do — leave the file byte-identical (idempotent §9).
-    return { merged: false, dryRun: false, settingsPath: absPath };
+    return { merged: false, dryRun: false, settingsPath: absPath, prunedRetired, prunedRetiredCount };
   }
 
   mkdirSync(path.dirname(absPath), { recursive: true });
   writeFileSync(absPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-  return { merged: true, dryRun: false, settingsPath: absPath };
+  return { merged: true, dryRun: false, settingsPath: absPath, prunedRetired, prunedRetiredCount };
 }
 
 /**
@@ -230,11 +369,10 @@ export function removeHookSettings(consumerCwd, opts = {}) {
     }
     const kept = entries.filter((entry) => !(entry && entry[HOOK_TAG] === true));
     if (kept.length !== entries.length) changed = true;
+    // An emptied bucket is simply not carried over, so we don't leave a dangling
+    // key; `changed` is already true in that case via the length check above.
     if (kept.length > 0) {
       nextHooks[event] = kept;
-    } else {
-      // Drop the now-empty event bucket so we don't leave dangling keys.
-      changed = changed || entries.length > 0;
     }
   }
 
@@ -243,11 +381,7 @@ export function removeHookSettings(consumerCwd, opts = {}) {
   }
 
   const next = { ...current };
-  if (Object.keys(nextHooks).length > 0) {
-    next.hooks = nextHooks;
-  } else {
-    delete next.hooks;
-  }
+  assignHooks(next, nextHooks);
 
   if (dryRun) {
     return { removed: true, dryRun: true, settingsPath: absPath };
@@ -263,7 +397,30 @@ export function removeHookSettings(consumerCwd, opts = {}) {
  */
 export const DEFAULT_HOOK_SCRIPTS = [
   { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
-  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/rules-injector.sh' },
   { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
   { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
 ];
+
+/**
+ * Hook registrations the toolkit once shipped and has since retired.
+ *
+ * On every `init`/`update`, `mergeHookSettings` removes any CLI-managed entry
+ * whose command appears here. Without it, deleting a hook script would leave a
+ * live registration pointing at a file that no longer exists — a per-session
+ * failure with no detection and no recovery path (§5).
+ *
+ * APPEND-ONLY, and deliberately separate from DEFAULT_HOOK_SCRIPTS. A consumer
+ * may upgrade from any older version, so this list has to name every command
+ * the CLI has ever registered and no longer ships — removing an entry once
+ * published would strand that registration in every consumer who had not yet
+ * updated past it. Being additive is also what makes the change §8-compatible:
+ * an older CLI reading newer content simply does not prune rather than erroring.
+ * Reversing a retirement is done by moving the entry back to
+ * DEFAULT_HOOK_SCRIPTS, not by silently dropping it from here.
+ */
+export const RETIRED_HOOK_SCRIPTS = [
+  // Retired by docs/specs/260724-opus5-native-overlap/ (S1): Claude Code loads
+  // `.claude/rules/*.md` natively as project instructions, which is strictly
+  // broader than this hook's fixed injection list.
+  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/rules-injector.sh' },
+];