@khanhcan148/mk 0.1.16 → 0.1.18

package/src/lib/copy.js

@@ -1,331 +1,335 @@
-import { join, relative } from 'node:path';
-import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import fsExtra from 'fs-extra';
-import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
-
-/**
- * Check if a path should be filtered out during copy.
- * @param {string} filePath
- * @returns {boolean} true if the file should be excluded
- */
-function shouldFilter(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  for (const pattern of COPY_FILTER_PATTERNS) {
-    if (normalized.includes(pattern)) return true;
-  }
-  return false;
-}
-
-/**
- * Collect all file paths recursively in a directory.
- * @param {string} dir
- * @returns {string[]}
- */
-function collectFiles(dir) {
-  const results = [];
-  function walk(current) {
-    let entries;
-    try {
-      entries = fsExtra.readdirSync(current);
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const fullPath = join(current, entry);
-      try {
-        // Use lstatSync (does not follow symlinks) to detect and skip symlinks.
-        // Symlinks inside the bundled .claude/ could otherwise redirect writes
-        // to arbitrary locations on the user's filesystem.
-        const lstat = lstatSync(fullPath);
-        if (lstat.isSymbolicLink()) continue;
-        if (lstat.isDirectory()) {
-          walk(fullPath);
-        } else {
-          results.push(fullPath);
-        }
-      } catch {
-        // skip inaccessible files
-      }
-    }
-  }
-  walk(dir);
-  return results;
-}
-
-/**
- * Collect all kit-managed files currently on disk under targetDir (.claude/).
- * Only walks KIT_SUBDIRS (agents/, skills/, workflows/).
- * Returns relative paths in the form `.claude/agents/foo.md`.
- * Applies shouldFilter to exclude filtered patterns.
- *
- * @param {string} targetDir - Absolute path to target .claude/
- * @returns {string[]} relative paths (relative to project root, e.g. `.claude/agents/foo.md`)
- */
-export function collectDiskFiles(targetDir) {
-  const results = [];
-  for (const subdir of KIT_SUBDIRS) {
-    const subdirAbs = join(targetDir, subdir);
-    if (!existsSync(subdirAbs)) continue;
-    const files = collectFiles(subdirAbs);
-    for (const absPath of files) {
-      if (shouldFilter(absPath)) continue;
-      const relFromSubdir = relative(subdirAbs, absPath);
-      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
-      results.push(relPath);
-    }
-  }
-  return results;
-}
-
-/**
- * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
- * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).
- *
- * @param {string} sourceDir - Absolute path to source .claude/
- * @param {string} targetDir - Absolute path to target .claude/
- * @param {{ dryRun: boolean }} options
- * @returns {Array<{ relativePath: string, absolutePath: string, sourceAbsPath: string, size: number }>}
- * @remarks Naming convention: `absolutePath` is the destination (under targetDir),
- *       `sourceAbsPath` is the source (under sourceDir). The asymmetry is intentional —
- *       renaming would break consumers (update.js). See DEBT-016.
- */
-export function copyKitFiles(sourceDir, targetDir, options = {}) {
-  const { dryRun = false } = options;
-  const fileList = [];
-  const warnings = [];
-
-  for (const subdir of KIT_SUBDIRS) {
-    const srcSubdir = join(sourceDir, subdir);
-    if (!existsSync(srcSubdir)) continue;
-
-    // Collect files in this subdir
-    const files = collectFiles(srcSubdir);
-
-    for (const absPath of files) {
-      if (shouldFilter(absPath)) continue;
-
-      const relFromSubdir = relative(srcSubdir, absPath);
-      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
-      const destAbs = join(targetDir, subdir, relFromSubdir);
-
-      // Windows path length check
-      if (destAbs.length > WINDOWS_PATH_WARN_LENGTH) {
-        warnings.push(`Warning: Long path (${destAbs.length} chars): ${destAbs}`);
-      }
-
-      let size = 0;
-      try {
-        size = statSync(absPath).size;
-      } catch {
-        // ignore
-      }
-
-      fileList.push({ relativePath: relPath, absolutePath: destAbs, sourceAbsPath: absPath, size });
-    }
-  }
-
-  // Print warnings
-  for (const w of warnings) {
-    process.stderr.write(w + '\n');
-  }
-
-  if (dryRun) {
-    return fileList;
-  }
-
-  // Actually copy each subdir using fs-extra
-  for (const subdir of KIT_SUBDIRS) {
-    const srcSubdir = join(sourceDir, subdir);
-    if (!existsSync(srcSubdir)) continue;
-    const destSubdir = join(targetDir, subdir);
-
-    fsExtra.copySync(srcSubdir, destSubdir, {
-      overwrite: true,
-      filter: (src) => {
-        if (shouldFilter(src)) return false;
-        try {
-          // Skip symlinks — prevents traversal to paths outside destSubdir
-          if (lstatSync(src).isSymbolicLink()) return false;
-        } catch {
-          return false;
-        }
-        return true;
-      }
-    });
-  }
-
-  return fileList;
-}
-
-/**
- * Create a timestamped backup of a file.
- * @param {string} filePath - Absolute path to the file to back up
- * @returns {string|null} Backup path, or null if source doesn't exist
- */
-function backupFile(filePath) {
-  if (!existsSync(filePath)) return null;
-  const now = new Date();
-  const ts = [
-    now.getFullYear(), String(now.getMonth() + 1).padStart(2, '0'),
-    String(now.getDate()).padStart(2, '0'), '-',
-    String(now.getHours()).padStart(2, '0'), String(now.getMinutes()).padStart(2, '0')
-  ].join('');
-  const backupPath = `${filePath}.${ts}.bak`;
-  copyFileSync(filePath, backupPath);
-  return backupPath;
-}
-
-/**
- * Returns true if siblingHooks already has an entry for the given event+matcher.
- * @param {object|null} siblingHooks - Parsed hooks from settings.local.json, or null
- * @param {string} event - Hook event name (e.g. 'PostToolUse')
- * @param {string} matcher - Hook matcher (e.g. '*', 'Task')
- */
-function isInSibling(siblingHooks, event, matcher) {
-  return !!siblingHooks?.[event]?.some(s => (s.matcher || '*') === matcher);
-}
-
-/**
- * Filter kitEntries removing any whose event+matcher already exists in siblingHooks.
- * Emits a stderr info message per skipped entry.
- * @param {object[]} kitEntries - Hook entries from kit source
- * @param {object|null} siblingHooks - Parsed hooks from settings.local.json, or null
- * @param {string} event - Hook event name
- * @returns {object[]} Entries not present in sibling
- */
-function dedupeAgainstSibling(kitEntries, siblingHooks, event) {
-  if (!siblingHooks?.[event]) return kitEntries;
-  return kitEntries.filter(ke => {
-    const m = ke.matcher || '*';
-    if (isInSibling(siblingHooks, event, m)) {
-      process.stderr.write(`mk: hook ${event}[${m}] skipped (exists in settings.local.json)\n`);
-      return false;
-    }
-    return true;
-  });
-}
-
-/**
- * Merge kit's settings.json into user's existing settings.json.
- * Strategy: merge "hooks" key from kit source; preserve all other user keys.
- * When a matcher already exists, the kit's hooks REPLACE the user's hooks for
- * that matcher — this ensures updated hook commands propagate on update instead
- * of accumulating stale duplicates.
- * If user has no settings.json, create one with hooks only.
- * If kit source has no settings.json, do nothing.
- * A timestamped backup is created before any write to an existing file.
- *
- * @param {string} sourceDir - Absolute path to source .claude/
- * @param {string} targetDir - Absolute path to target .claude/
- * @param {{ dryRun: boolean }} options
- * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[], backup?: string }}
- */
-export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
-  const { dryRun = false } = options;
-  const srcPath = join(sourceDir, 'settings.json');
-  const destPath = join(targetDir, 'settings.json');
-
-  if (!existsSync(srcPath)) return { action: 'skipped' };
-
-  let kitSettings;
-  try {
-    kitSettings = JSON.parse(readFileSync(srcPath, 'utf-8'));
-  } catch {
-    return { action: 'skipped' };
-  }
-
-  // Read settings.local.json once for sibling dedup guard.
-  // Applies to both the 'created' and 'merged' paths — Claude Code loads hooks from
-  // all settings files simultaneously; if a user already has a hook in settings.local.json,
-  // writing the same event+matcher to settings.json would cause both to fire.
-  let siblingHooks = null;
-  try {
-    const siblingPath = join(targetDir, 'settings.local.json');
-    siblingHooks = JSON.parse(readFileSync(siblingPath, 'utf-8')).hooks || null;
-  } catch {
-    // Missing or malformed sibling — proceed as if no sibling exists.
-  }
-
-  // No existing user settings — create with hooks only (not permissions or other keys).
-  // Copying the full kit settings.json would duplicate permissions.deny entries when both
-  // global (~/.claude/settings.json) and project (.claude/settings.json) are initialised.
-  if (!existsSync(destPath)) {
-    if (!dryRun) {
-      const hooksOnly = {};
-      if (kitSettings.hooks) {
-        for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
-          const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
-          if (deduped.length > 0) hooksOnly[event] = deduped;
-        }
-      }
-      mkdirSync(targetDir, { recursive: true });
-      const payload = Object.keys(hooksOnly).length > 0 ? { hooks: hooksOnly } : {};
-      writeFileSync(destPath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
-    }
-    return { action: 'created' };
-  }
-
-  // Existing user settings — merge hooks only, preserve everything else
-  let userSettings;
-  try {
-    userSettings = JSON.parse(readFileSync(destPath, 'utf-8'));
-  } catch {
-    // Malformed user settings — skip to avoid data loss
-    return { action: 'skipped' };
-  }
-
-  const merged = [];
-
-  // Merge hooks: kit entries are added or replaced by matcher; user-only matchers preserved.
-  // Replace strategy: when the kit ships an updated hook command for an existing matcher,
-  // the old command is replaced instead of appended — preventing stale duplicates.
-  if (kitSettings.hooks) {
-    if (!userSettings.hooks) userSettings.hooks = {};
-    for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
-      if (!userSettings.hooks[event]) {
-        const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
-        if (deduped.length > 0) {
-          userSettings.hooks[event] = deduped;
-          merged.push(event);
-        }
-      } else {
-        for (const kitEntry of kitEntries) {
-          const kitMatcher = kitEntry.matcher || '*';
-          // Dedup guard: skip if sibling already has this event+matcher
-          if (isInSibling(siblingHooks, event, kitMatcher)) {
-            process.stderr.write(`mk: hook ${event}[${kitMatcher}] skipped (exists in settings.local.json)\n`);
-            continue;
-          }
-          const idx = userSettings.hooks[event].findIndex(
-            e => (e.matcher || '*') === kitMatcher
-          );
-          if (idx === -1) {
-            // New matcher — add it
-            userSettings.hooks[event].push(kitEntry);
-            merged.push(`${event}[${kitMatcher}]:added`);
-          } else {
-            // Existing matcher — replace with kit version if hooks differ
-            const userEntry = userSettings.hooks[event][idx];
-            const userCmds = (userEntry.hooks || []).map(h => h.command).sort();
-            const kitCmds = (kitEntry.hooks || []).map(h => h.command).sort();
-            const same = userCmds.length === kitCmds.length &&
-              userCmds.every((c, i) => c === kitCmds[i]);
-            if (!same) {
-              userSettings.hooks[event][idx] = kitEntry;
-              merged.push(`${event}[${kitMatcher}]:replaced`);
-            }
-          }
-        }
-      }
-    }
-  }
-
-  if (merged.length === 0) return { action: 'skipped' };
-
-  if (!dryRun) {
-    const backup = backupFile(destPath);
-    writeFileSync(destPath, JSON.stringify(userSettings, null, 2) + '\n', 'utf-8');
-    return { action: 'merged', merged, backup };
-  }
-  return { action: 'merged', merged };
-}
+import { join, relative } from 'node:path';
+import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import fsExtra from 'fs-extra';
+import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, KIT_INTERNAL_SKILLS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
+
+/**
+ * Check if a path should be filtered out during copy.
+ * @param {string} filePath
+ * @returns {boolean} true if the file should be excluded
+ */
+function shouldFilter(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const pattern of COPY_FILTER_PATTERNS) {
+    if (normalized.includes(pattern)) return true;
+  }
+  // Exclude internal skills — see KIT_INTERNAL_SKILLS JSDoc in constants.js.
+  for (const skillName of KIT_INTERNAL_SKILLS) {
+    if (normalized.includes(`/skills/${skillName}/`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Collect all file paths recursively in a directory.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function collectFiles(dir) {
+  const results = [];
+  function walk(current) {
+    let entries;
+    try {
+      entries = fsExtra.readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(current, entry);
+      try {
+        // Use lstatSync (does not follow symlinks) to detect and skip symlinks.
+        // Symlinks inside the bundled .claude/ could otherwise redirect writes
+        // to arbitrary locations on the user's filesystem.
+        const lstat = lstatSync(fullPath);
+        if (lstat.isSymbolicLink()) continue;
+        if (lstat.isDirectory()) {
+          walk(fullPath);
+        } else {
+          results.push(fullPath);
+        }
+      } catch {
+        // skip inaccessible files
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+/**
+ * Collect all kit-managed files currently on disk under targetDir (.claude/).
+ * Only walks KIT_SUBDIRS (agents/, skills/, workflows/).
+ * Returns relative paths in the form `.claude/agents/foo.md`.
+ * Applies shouldFilter to exclude filtered patterns.
+ *
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @returns {string[]} relative paths (relative to project root, e.g. `.claude/agents/foo.md`)
+ */
+export function collectDiskFiles(targetDir) {
+  const results = [];
+  for (const subdir of KIT_SUBDIRS) {
+    const subdirAbs = join(targetDir, subdir);
+    if (!existsSync(subdirAbs)) continue;
+    const files = collectFiles(subdirAbs);
+    for (const absPath of files) {
+      if (shouldFilter(absPath)) continue;
+      const relFromSubdir = relative(subdirAbs, absPath);
+      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
+ * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).
+ *
+ * @param {string} sourceDir - Absolute path to source .claude/
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @param {{ dryRun: boolean }} options
+ * @returns {Array<{ relativePath: string, absolutePath: string, sourceAbsPath: string, size: number }>}
+ * @remarks Naming convention: `absolutePath` is the destination (under targetDir),
+ *       `sourceAbsPath` is the source (under sourceDir). The asymmetry is intentional —
+ *       renaming would break consumers (update.js). See DEBT-016.
+ */
+export function copyKitFiles(sourceDir, targetDir, options = {}) {
+  const { dryRun = false } = options;
+  const fileList = [];
+  const warnings = [];
+
+  for (const subdir of KIT_SUBDIRS) {
+    const srcSubdir = join(sourceDir, subdir);
+    if (!existsSync(srcSubdir)) continue;
+
+    // Collect files in this subdir
+    const files = collectFiles(srcSubdir);
+
+    for (const absPath of files) {
+      if (shouldFilter(absPath)) continue;
+
+      const relFromSubdir = relative(srcSubdir, absPath);
+      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
+      const destAbs = join(targetDir, subdir, relFromSubdir);
+
+      // Windows path length check
+      if (destAbs.length > WINDOWS_PATH_WARN_LENGTH) {
+        warnings.push(`Warning: Long path (${destAbs.length} chars): ${destAbs}`);
+      }
+
+      let size = 0;
+      try {
+        size = statSync(absPath).size;
+      } catch {
+        // ignore
+      }
+
+      fileList.push({ relativePath: relPath, absolutePath: destAbs, sourceAbsPath: absPath, size });
+    }
+  }
+
+  // Print warnings
+  for (const w of warnings) {
+    process.stderr.write(w + '\n');
+  }
+
+  if (dryRun) {
+    return fileList;
+  }
+
+  // Actually copy each subdir using fs-extra
+  for (const subdir of KIT_SUBDIRS) {
+    const srcSubdir = join(sourceDir, subdir);
+    if (!existsSync(srcSubdir)) continue;
+    const destSubdir = join(targetDir, subdir);
+
+    fsExtra.copySync(srcSubdir, destSubdir, {
+      overwrite: true,
+      filter: (src) => {
+        if (shouldFilter(src)) return false;
+        try {
+          // Skip symlinks — prevents traversal to paths outside destSubdir
+          if (lstatSync(src).isSymbolicLink()) return false;
+        } catch {
+          return false;
+        }
+        return true;
+      }
+    });
+  }
+
+  return fileList;
+}
+
+/**
+ * Create a timestamped backup of a file.
+ * @param {string} filePath - Absolute path to the file to back up
+ * @returns {string|null} Backup path, or null if source doesn't exist
+ */
+function backupFile(filePath) {
+  if (!existsSync(filePath)) return null;
+  const now = new Date();
+  const ts = [
+    now.getFullYear(), String(now.getMonth() + 1).padStart(2, '0'),
+    String(now.getDate()).padStart(2, '0'), '-',
+    String(now.getHours()).padStart(2, '0'), String(now.getMinutes()).padStart(2, '0')
+  ].join('');
+  const backupPath = `${filePath}.${ts}.bak`;
+  copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Returns true if siblingHooks already has an entry for the given event+matcher.
+ * @param {object|null} siblingHooks - Parsed hooks from settings.local.json, or null
+ * @param {string} event - Hook event name (e.g. 'PostToolUse')
+ * @param {string} matcher - Hook matcher (e.g. '*', 'Task')
+ */
+function isInSibling(siblingHooks, event, matcher) {
+  return !!siblingHooks?.[event]?.some(s => (s.matcher || '*') === matcher);
+}
+
+/**
+ * Filter kitEntries removing any whose event+matcher already exists in siblingHooks.
+ * Emits a stderr info message per skipped entry.
+ * @param {object[]} kitEntries - Hook entries from kit source
+ * @param {object|null} siblingHooks - Parsed hooks from settings.local.json, or null
+ * @param {string} event - Hook event name
+ * @returns {object[]} Entries not present in sibling
+ */
+function dedupeAgainstSibling(kitEntries, siblingHooks, event) {
+  if (!siblingHooks?.[event]) return kitEntries;
+  return kitEntries.filter(ke => {
+    const m = ke.matcher || '*';
+    if (isInSibling(siblingHooks, event, m)) {
+      process.stderr.write(`mk: hook ${event}[${m}] skipped (exists in settings.local.json)\n`);
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Merge kit's settings.json into user's existing settings.json.
+ * Strategy: merge "hooks" key from kit source; preserve all other user keys.
+ * When a matcher already exists, the kit's hooks REPLACE the user's hooks for
+ * that matcher — this ensures updated hook commands propagate on update instead
+ * of accumulating stale duplicates.
+ * If user has no settings.json, create one with hooks only.
+ * If kit source has no settings.json, do nothing.
+ * A timestamped backup is created before any write to an existing file.
+ *
+ * @param {string} sourceDir - Absolute path to source .claude/
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @param {{ dryRun: boolean }} options
+ * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[], backup?: string }}
+ */
+export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
+  const { dryRun = false } = options;
+  const srcPath = join(sourceDir, 'settings.json');
+  const destPath = join(targetDir, 'settings.json');
+
+  if (!existsSync(srcPath)) return { action: 'skipped' };
+
+  let kitSettings;
+  try {
+    kitSettings = JSON.parse(readFileSync(srcPath, 'utf-8'));
+  } catch {
+    return { action: 'skipped' };
+  }
+
+  // Read settings.local.json once for sibling dedup guard.
+  // Applies to both the 'created' and 'merged' paths — Claude Code loads hooks from
+  // all settings files simultaneously; if a user already has a hook in settings.local.json,
+  // writing the same event+matcher to settings.json would cause both to fire.
+  let siblingHooks = null;
+  try {
+    const siblingPath = join(targetDir, 'settings.local.json');
+    siblingHooks = JSON.parse(readFileSync(siblingPath, 'utf-8')).hooks || null;
+  } catch {
+    // Missing or malformed sibling — proceed as if no sibling exists.
+  }
+
+  // No existing user settings — create with hooks only (not permissions or other keys).
+  // Copying the full kit settings.json would duplicate permissions.deny entries when both
+  // global (~/.claude/settings.json) and project (.claude/settings.json) are initialised.
+  if (!existsSync(destPath)) {
+    if (!dryRun) {
+      const hooksOnly = {};
+      if (kitSettings.hooks) {
+        for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
+          const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
+          if (deduped.length > 0) hooksOnly[event] = deduped;
+        }
+      }
+      mkdirSync(targetDir, { recursive: true });
+      const payload = Object.keys(hooksOnly).length > 0 ? { hooks: hooksOnly } : {};
+      writeFileSync(destPath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+    }
+    return { action: 'created' };
+  }
+
+  // Existing user settings — merge hooks only, preserve everything else
+  let userSettings;
+  try {
+    userSettings = JSON.parse(readFileSync(destPath, 'utf-8'));
+  } catch {
+    // Malformed user settings — skip to avoid data loss
+    return { action: 'skipped' };
+  }
+
+  const merged = [];
+
+  // Merge hooks: kit entries are added or replaced by matcher; user-only matchers preserved.
+  // Replace strategy: when the kit ships an updated hook command for an existing matcher,
+  // the old command is replaced instead of appended — preventing stale duplicates.
+  if (kitSettings.hooks) {
+    if (!userSettings.hooks) userSettings.hooks = {};
+    for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
+      if (!userSettings.hooks[event]) {
+        const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
+        if (deduped.length > 0) {
+          userSettings.hooks[event] = deduped;
+          merged.push(event);
+        }
+      } else {
+        for (const kitEntry of kitEntries) {
+          const kitMatcher = kitEntry.matcher || '*';
+          // Dedup guard: skip if sibling already has this event+matcher
+          if (isInSibling(siblingHooks, event, kitMatcher)) {
+            process.stderr.write(`mk: hook ${event}[${kitMatcher}] skipped (exists in settings.local.json)\n`);
+            continue;
+          }
+          const idx = userSettings.hooks[event].findIndex(
+            e => (e.matcher || '*') === kitMatcher
+          );
+          if (idx === -1) {
+            // New matcher — add it
+            userSettings.hooks[event].push(kitEntry);
+            merged.push(`${event}[${kitMatcher}]:added`);
+          } else {
+            // Existing matcher — replace with kit version if hooks differ
+            const userEntry = userSettings.hooks[event][idx];
+            const userCmds = (userEntry.hooks || []).map(h => h.command).sort();
+            const kitCmds = (kitEntry.hooks || []).map(h => h.command).sort();
+            const same = userCmds.length === kitCmds.length &&
+              userCmds.every((c, i) => c === kitCmds[i]);
+            if (!same) {
+              userSettings.hooks[event][idx] = kitEntry;
+              merged.push(`${event}[${kitMatcher}]:replaced`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (merged.length === 0) return { action: 'skipped' };
+
+  if (!dryRun) {
+    const backup = backupFile(destPath);
+    writeFileSync(destPath, JSON.stringify(userSettings, null, 2) + '\n', 'utf-8');
+    return { action: 'merged', merged, backup };
+  }
+  return { action: 'merged', merged };
+}