@khanhcan148/mk 0.1.15 → 0.1.16

package/src/commands/update.js

@@ -1,426 +1,436 @@
-import chalk from 'chalk';
-import { createInterface } from 'node:readline';
-import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
-import { join, dirname, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
-import { computeChecksum } from '../lib/checksum.js';
-import { copyKitFiles, collectDiskFiles, mergeSettingsJson } from '../lib/copy.js';
-import { resolveSourceDir, resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
-import { resolveTokenOrLogin } from '../lib/auth.js';
-import { writeToken, readStoredToken } from '../lib/config.js';
-import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
-import { fetchLatestRelease, compareVersions } from '../lib/releases.js';
-import { isEmptyDir } from '../lib/fs-utils.js';
-
-// ---------------------------------------------------------------------------
-// Security: strip terminal escape sequences from untrusted content
-// ---------------------------------------------------------------------------
-
-/**
- * Strip terminal escape sequences from a string to prevent terminal injection
- * when printing content sourced from the GitHub API (e.g. release notes).
- *
- * Removes:
- *   - CSI sequences: ESC [ ... <letter>  (e.g. color codes, cursor movement, screen clear)
- *   - OSC sequences: ESC ] ... BEL/ST    (e.g. window title manipulation)
- *   - Fe two-character sequences: ESC <char> (e.g. ESC c = RIS terminal reset, ESC P = DCS)
- *   - Raw C0 control characters (0x00-0x08, 0x0b, 0x0c, 0x0e-0x1f) excluding
- *     printable whitespace (\t, \n, \r which are 0x09, 0x0a, 0x0d)
- *
- * @param {string} str
- * @returns {string}
- */
-function stripTerminalEscapes(str) {
-  return str
-    .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')         // CSI sequences
-    .replace(/\x1b\].*?(\x07|\x1b\\)/gs, '')         // OSC sequences (dotAll for multiline)
-    .replace(/\x1b[^[\]]/g, '')                       // Fe two-char sequences (ESC c, ESC P, etc.)
-    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');  // raw control chars (preserve \t \n \r)
-}
-
-// ---------------------------------------------------------------------------
-// Prompt helper
-// ---------------------------------------------------------------------------
-
-/**
- * Prompt the user with a yes/no question and return true for yes, false for no.
- * Reads from stdin; defaults to "no" on empty/non-y input.
- *
- * @param {string} question
- * @returns {Promise<boolean>}
- */
-async function defaultPromptUser(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase() === 'y');
-    });
-  });
-}
-
-/**
- * Run the update command.
- *
- * @param {{
- *   sourceDir?: string,
- *   targetDir?: string,
- *   manifestPath?: string,
- *   force?: boolean,
- *   version?: string  - Kit version to store in manifest (defaults to pkg.version when omitted)
- * }} params
- * @returns {Promise<{ updated: string[], added: string[], removed: string[], conflicts: string[], unchanged: string[], upToDate: boolean }>}
- */
-export async function runUpdate(params = {}) {
-  const {
-    sourceDir = resolveSourceDir(),
-    targetDir = resolveTargetDir({ global: false }),
-    manifestPath = resolveManifestPath({ global: false }),
-    force = false,
-    version: explicitVersion
-  } = params;
-
-  // Read existing manifest
-  let manifest;
-  try {
-    manifest = readManifest(manifestPath);
-  } catch (err) {
-    throw new Error(`Not installed (no manifest found). Run 'mk init' first. (${err.message})`);
-  }
-
-  // Derive project root from manifest scope (global: homedir, project: dirname(manifestPath))
-  const projectRoot = deriveProjectRoot(manifest, manifestPath);
-  const claudeRoot = resolve(join(projectRoot, '.claude'));
-  const sourceFileList = copyKitFiles(sourceDir, targetDir, { dryRun: true });
-  // Fix 11-12 (performance): Build a Map for O(1) lookups in applyCopy.
-  // Previously sourceFileList.find() in applyCopy was O(n) per call, causing O(n²)
-  // behaviour when many files need updating. The Map is built once in O(n).
-  const sourceFileMap = new Map(sourceFileList.map(e => [e.relativePath, e]));
-  const sourceFiles = {};
-  for (const entry of sourceFileList) {
-    const checksum = computeChecksum(entry.sourceAbsPath);
-    sourceFiles[entry.relativePath] = { checksum, size: entry.size };
-  }
-
-  // Get disk checksums for files currently in manifest
-  const diskChecksums = {};
-  for (const relPath of Object.keys(manifest.files)) {
-    // relPath is like '.claude/agents/foo.md' — relative to project root
-    const absPath = join(projectRoot, relPath);
-    // Bounds check: manifest keys must not escape .claude/ subtree
-    try {
-      assertSafePath(absPath, claudeRoot, `manifest key "${relPath}"`);
-    } catch {
-      process.stderr.write(`Warning: Skipping unsafe path in manifest: ${relPath}\n`);
-      continue;
-    }
-    if (existsSync(absPath)) {
-      diskChecksums[relPath] = computeChecksum(absPath);
-    }
-  }
-
-  // Three-way diff
-  const diff = diffManifest(manifest, sourceFiles, diskChecksums);
-
-  const upToDate =
-    diff.updated.length === 0 &&
-    diff.added.length === 0 &&
-    diff.removed.length === 0 &&
-    diff.conflicts.length === 0;
-
-  // Read package version (fileURLToPath handles Windows drive-letter prefix correctly)
-  const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
-
-  if (upToDate) {
-    // Files are unchanged but we may still need to record the release version.
-    // Without this, manifest.version stays at the old value and the next `mk update`
-    // will always report "Update available" even though nothing changed on disk.
-    if (explicitVersion && explicitVersion !== manifest.version) {
-      updateManifest(manifestPath, manifest.files, explicitVersion);
-    }
-    return { ...diff, upToDate: true };
-  }
-
-  const newFiles = { ...manifest.files };
-
-  /**
-   * Copy a source file entry to its destination.
-   * Fix 11-12: Uses O(1) Map lookup instead of O(n) Array.find to eliminate O(n²) worst case.
-   * @param {string} relPath
-   */
-  function applyCopy(relPath) {
-    const entry = sourceFileMap.get(relPath);
-    if (!entry) return;
-    const destAbs = join(projectRoot, relPath);
-    // Bounds check: destination must stay inside .claude/ subtree
-    assertSafePath(destAbs, claudeRoot, `copy destination for "${relPath}"`);
-    mkdirSync(dirname(destAbs), { recursive: true });
-    copyFileSync(entry.sourceAbsPath, destAbs);
-    // Reuse source checksum — copy is bit-for-bit identical, no need to re-hash
-    newFiles[relPath] = { checksum: sourceFiles[relPath].checksum, size: entry.size };
-  }
-
-  // Apply safe updates
-  for (const relPath of diff.updated) {
-    applyCopy(relPath);
-  }
-
-  // Handle conflicts
-  const skippedConflicts = [];
-  for (const relPath of diff.conflicts) {
-    if (force) {
-      applyCopy(relPath);
-    } else {
-      skippedConflicts.push(relPath);
-    }
-  }
-
-  // Add new files
-  for (const relPath of diff.added) {
-    applyCopy(relPath);
-  }
-
-  // Remove deleted kit files
-  for (const relPath of diff.removed) {
-    const absPath = join(projectRoot, relPath);
-    // Bounds check: removal must stay inside .claude/ subtree
-    try {
-      assertSafePath(absPath, claudeRoot, `removal target "${relPath}"`);
-    } catch (err) {
-      process.stderr.write(`Warning: Skipping unsafe removal path: ${err.message}\n`);
-      continue;
-    }
-    try {
-      unlinkSync(absPath);
-    } catch {
-      // Already missing — skip
-    }
-    delete newFiles[relPath];
-  }
-
-  // Orphan cleanup: files on disk (in kit subdirs) that are not in the new source
-  const diskFiles = collectDiskFiles(targetDir);
-  const orphans = [];
-  const orphanParentDirs = new Set();
-  for (const relPath of diskFiles) {
-    if (relPath in sourceFiles) continue; // present in new source — keep
-    const absPath = join(projectRoot, relPath);
-    try {
-      assertSafePath(absPath, claudeRoot, `orphan "${relPath}"`);
-    } catch (err) {
-      process.stderr.write(`Warning: Skipping unsafe orphan path: ${err.message}\n`);
-      continue;
-    }
-    try {
-      unlinkSync(absPath);
-      orphans.push(relPath);
-      orphanParentDirs.add(dirname(absPath));
-    } catch {
-      // Already missing — skip
-    }
-  }
-
-  // Clean up empty directories bottom-up after orphan deletion
-  const resolvedTarget = resolve(targetDir);
-  const sortedOrphanDirs = [...orphanParentDirs].sort((a, b) => {
-    return b.split(/[/\\]/).length - a.split(/[/\\]/).length;
-  });
-  for (const dir of sortedOrphanDirs) {
-    if (isEmptyDir(dir)) {
-      try {
-        rmdirSync(dir);
-        let current = dirname(dir);
-        let prev = dir;
-        while (current !== prev && isEmptyDir(current)) {
-          const resolvedCurrent = resolve(current);
-          if (resolvedCurrent === resolvedTarget || !resolvedCurrent.startsWith(resolvedTarget + sep)) {
-            break;
-          }
-          try {
-            rmdirSync(current);
-          } catch {
-            break;
-          }
-          prev = current;
-          current = dirname(current);
-        }
-      } catch {
-        // Non-empty or permission error — skip
-      }
-    }
-  }
-
-  // Merge settings.json hooks — additive merge, never overwrites user keys
-  mergeSettingsJson(sourceDir, targetDir);
-
-  // Update manifest with new file map.
-  // Use explicitVersion when provided (e.g. release.version from updateAction);
-  // fall back to pkg.version for direct runUpdate calls or main-branch fallback downloads.
-  updateManifest(manifestPath, newFiles, explicitVersion ?? pkg.version);
-
-  return {
-    updated: diff.updated,
-    added: diff.added,
-    removed: diff.removed,
-    conflicts: skippedConflicts,
-    unchanged: diff.unchanged,
-    orphans,
-    upToDate: false
-  };
-}
-
-/**
- * CLI action handler for 'mk update'.
- * Checks GitHub Releases for a newer version, prompts the user, then downloads
- * and applies a three-way diff. Falls back to the main-branch tarball if no
- * release information is available.
- *
- * @param {{ force: boolean, global: boolean }} options
- * @param {object} [deps] - Injected dependencies (for testing)
- */
-export async function updateAction(options = {}, deps = {}) {
-  const {
-    resolveTokenOrLogin: resolveAndLogin = resolveTokenOrLogin,
-    downloadAndExtractKit: download = downloadAndExtractKit,
-    cleanupTempDir: cleanup = cleanupTempDir,
-    writeToken: storeToken = writeToken,
-    readStoredToken: readToken = readStoredToken,
-    fetchLatestRelease: fetchRelease = fetchLatestRelease,
-    compareVersions: cmpVersions = compareVersions,
-    promptUser = defaultPromptUser,
-    // Injectable for tests — allows overriding resolved paths without touching CWD
-    manifestPath: injectedManifestPath
-  } = deps;
-
-  // Read local package version (used as fallback when manifest has no version)
-  const pkg = JSON.parse(
-    readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')
-  );
-
-  const targetDir = resolveTargetDir(options);
-  const manifestPath = injectedManifestPath ?? resolveManifestPath(options);
-
-  let tempDir = null;
-  try {
-    process.stdout.write('Authenticating with GitHub...\n');
-    const token = await resolveAndLogin({
-      readStored: readToken,
-      writeStored: storeToken,
-      display: ({ userCode, verificationUri, expiresIn }) => {
-        process.stdout.write('\n');
-        process.stdout.write(chalk.bold('To authenticate, visit:  ') + chalk.cyan(verificationUri) + '\n');
-        process.stdout.write(chalk.bold('And enter the code:      ') + chalk.yellow(userCode) + '\n');
-        process.stdout.write(`(Code expires in ${Math.round(expiresIn / 60)} minutes)\n\n`);
-        process.stdout.write('Waiting for authorization...\n');
-      }
-    });
-
-    // --- Version check via GitHub Releases API ---
-    process.stdout.write('Checking for updates...\n');
-    const release = await fetchRelease(token);
-
-    // Read installed version from manifest (more accurate than pkg.version which reflects
-    // the CLI package, not the downloaded kit files). Fall back to pkg.version if no manifest.
-    let installedVersion = pkg.version;
-    if (existsSync(manifestPath)) {
-      try {
-        const existingManifest = readManifest(manifestPath);
-        if (existingManifest?.version) installedVersion = existingManifest.version;
-      } catch {
-        // Manifest unreadable — proceed with pkg.version fallback
-      }
-    }
-
-    let downloadUrl; // undefined = use default (main branch)
-    let releaseVersion; // set when downloading from a specific release tarball
-
-    if (!release.available) {
-      // No release found or API error — warn and fall back to main branch
-      process.stdout.write(
-        chalk.yellow(`Warning: Could not check latest release (${release.reason}). Falling back to main branch.\n`)
-      );
-    } else {
-      const { needsUpdate, local, remote } = cmpVersions(installedVersion, release.version);
-
-      if (!needsUpdate) {
-        process.stdout.write(chalk.green(`Already up to date (v${local}).\n`));
-        return;
-      }
-
-      // Show version diff
-      process.stdout.write(
-        chalk.cyan(`Update available: v${local} -> v${remote}\n`)
-      );
-
-      // Show release notes (if any), truncated to 500 chars.
-      // S4: Strip terminal escape sequences before printing to prevent injection via
-      // crafted GitHub release bodies (CSI/OSC sequences can clear screen, set window titles, etc.).
-      const body = release.body;
-      if (body && body.trim().length > 0) {
-        const rawNotes = body.length > 500 ? body.slice(0, 500) + '...' : body;
-        const notes = stripTerminalEscapes(rawNotes);
-        process.stdout.write('\nRelease notes:\n');
-        process.stdout.write(notes + '\n\n');
-      }
-
-      // Prompt user
-      const confirmed = await promptUser(`Update to v${remote}? [y/N] `);
-      if (!confirmed) {
-        process.stdout.write('Update cancelled.\n');
-        return;
-      }
-
-      downloadUrl = release.tarballUrl;
-      releaseVersion = release.version;
-    }
-
-    // --- Download and apply ---
-    process.stdout.write('Downloading latest kit from GitHub...\n');
-    tempDir = await download(token, downloadUrl !== undefined ? { url: downloadUrl } : {});
-    const sourceDir = join(tempDir, '.claude');
-
-    // Pass releaseVersion so runUpdate stores it in the manifest.
-    // When falling back to main branch (no release), releaseVersion is undefined and
-    // runUpdate falls back to pkg.version — which is the correct behaviour for that path.
-    const result = await runUpdate({ sourceDir, targetDir, manifestPath, force: options.force, version: releaseVersion });
-
-    if (result.upToDate) {
-      process.stdout.write(chalk.green('Already up to date.\n'));
-    } else {
-      if (result.updated.length > 0) {
-        process.stdout.write(chalk.green(`Updated: ${result.updated.length} files\n`));
-      }
-      if (result.added.length > 0) {
-        process.stdout.write(chalk.green(`Added: ${result.added.length} new files\n`));
-      }
-      if (result.removed.length > 0) {
-        process.stdout.write(chalk.yellow(`Removed: ${result.removed.length} files\n`));
-        for (const f of result.removed) {
-          process.stdout.write(`  Removed: ${f}\n`);
-        }
-      }
-      if (result.orphans && result.orphans.length > 0) {
-        process.stdout.write(chalk.yellow(`Cleaned: ${result.orphans.length} orphan files\n`));
-        for (const f of result.orphans) {
-          process.stdout.write(`  Cleaned: ${f}\n`);
-        }
-      }
-      if (result.conflicts.length > 0) {
-        process.stdout.write(
-          chalk.yellow(`Skipped: ${result.conflicts.length} user-modified files (use --force to overwrite)\n`)
-        );
-        for (const f of result.conflicts) {
-          process.stdout.write(`  ${f}\n`);
-        }
-      }
-    }
-  } catch (err) {
-    process.stderr.write(chalk.red(`Error: ${err.message}\n`));
-    process.exit(1);
-  } finally {
-    if (tempDir) {
-      cleanup(tempDir);
-    }
-  }
-}
+import chalk from 'chalk';
+import { createInterface } from 'node:readline';
+import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
+import { computeChecksum } from '../lib/checksum.js';
+import { copyKitFiles, collectDiskFiles, mergeSettingsJson } from '../lib/copy.js';
+import { resolveSourceDir, resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
+import { resolveTokenOrLogin } from '../lib/auth.js';
+import { writeToken, readStoredToken } from '../lib/config.js';
+import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
+import { fetchLatestRelease, compareVersions } from '../lib/releases.js';
+import { isEmptyDir } from '../lib/fs-utils.js';
+
+// ---------------------------------------------------------------------------
+// Security: strip terminal escape sequences from untrusted content
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip terminal escape sequences from a string to prevent terminal injection
+ * when printing content sourced from the GitHub API (e.g. release notes).
+ *
+ * Removes:
+ *   - CSI sequences: ESC [ ... <letter>  (e.g. color codes, cursor movement, screen clear)
+ *   - OSC sequences: ESC ] ... BEL/ST    (e.g. window title manipulation)
+ *   - Fe two-character sequences: ESC <char> (e.g. ESC c = RIS terminal reset, ESC P = DCS)
+ *   - Raw C0 control characters (0x00-0x08, 0x0b, 0x0c, 0x0e-0x1f) excluding
+ *     printable whitespace (\t, \n, \r which are 0x09, 0x0a, 0x0d)
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function stripTerminalEscapes(str) {
+  return str
+    .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')         // CSI sequences
+    .replace(/\x1b\].*?(\x07|\x1b\\)/gs, '')         // OSC sequences (dotAll for multiline)
+    .replace(/\x1b[^[\]]/g, '')                       // Fe two-char sequences (ESC c, ESC P, etc.)
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');  // raw control chars (preserve \t \n \r)
+}
+
+// ---------------------------------------------------------------------------
+// Prompt helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Prompt the user with a yes/no question and return true for yes, false for no.
+ * Reads from stdin; defaults to "no" on empty/non-y input.
+ *
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+async function defaultPromptUser(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+/**
+ * Run the update command.
+ *
+ * @param {{
+ *   sourceDir?: string,
+ *   targetDir?: string,
+ *   manifestPath?: string,
+ *   force?: boolean,
+ *   version?: string  - Kit version to store in manifest (defaults to pkg.version when omitted)
+ * }} params
+ * @returns {Promise<{ updated: string[], added: string[], removed: string[], conflicts: string[], unchanged: string[], upToDate: boolean }>}
+ */
+export async function runUpdate(params = {}) {
+  const {
+    sourceDir = resolveSourceDir(),
+    targetDir = resolveTargetDir({ global: false }),
+    manifestPath = resolveManifestPath({ global: false }),
+    force = false,
+    version: explicitVersion
+  } = params;
+
+  // Read existing manifest
+  let manifest;
+  try {
+    manifest = readManifest(manifestPath);
+  } catch (err) {
+    throw new Error(`Not installed (no manifest found). Run 'mk init' first. (${err.message})`);
+  }
+
+  // Derive project root from manifest scope (global: homedir, project: dirname(manifestPath))
+  const projectRoot = deriveProjectRoot(manifest, manifestPath);
+  const claudeRoot = resolve(join(projectRoot, '.claude'));
+  const sourceFileList = copyKitFiles(sourceDir, targetDir, { dryRun: true });
+  // Fix 11-12 (performance): Build a Map for O(1) lookups in applyCopy.
+  // Previously sourceFileList.find() in applyCopy was O(n) per call, causing O(n²)
+  // behaviour when many files need updating. The Map is built once in O(n).
+  const sourceFileMap = new Map(sourceFileList.map(e => [e.relativePath, e]));
+  const sourceFiles = {};
+  for (const entry of sourceFileList) {
+    const checksum = computeChecksum(entry.sourceAbsPath);
+    sourceFiles[entry.relativePath] = { checksum, size: entry.size };
+  }
+
+  // Get disk checksums for files currently in manifest
+  const diskChecksums = {};
+  for (const relPath of Object.keys(manifest.files)) {
+    // relPath is like '.claude/agents/foo.md' — relative to project root
+    const absPath = join(projectRoot, relPath);
+    // Bounds check: manifest keys must not escape .claude/ subtree
+    try {
+      assertSafePath(absPath, claudeRoot, `manifest key "${relPath}"`);
+    } catch {
+      process.stderr.write(`Warning: Skipping unsafe path in manifest: ${relPath}\n`);
+      continue;
+    }
+    if (existsSync(absPath)) {
+      diskChecksums[relPath] = computeChecksum(absPath);
+    }
+  }
+
+  // Three-way diff
+  const diff = diffManifest(manifest, sourceFiles, diskChecksums);
+
+  const upToDate =
+    diff.updated.length === 0 &&
+    diff.added.length === 0 &&
+    diff.removed.length === 0 &&
+    diff.conflicts.length === 0;
+
+  // Read package version (fileURLToPath handles Windows drive-letter prefix correctly)
+  const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+
+  if (upToDate) {
+    // Always merge settings.json hooks even when kit files are unchanged.
+    // A user who installed before hooks were added (or whose settings.json was
+    // edited/reset) would otherwise never receive hook updates via `mk update`.
+    mergeSettingsJson(sourceDir, targetDir);
+    // Files are unchanged but we may still need to record the release version.
+    // Without this, manifest.version stays at the old value and the next `mk update`
+    // will always report "Update available" even though nothing changed on disk.
+    if (explicitVersion && explicitVersion !== manifest.version) {
+      updateManifest(manifestPath, manifest.files, explicitVersion);
+    }
+    return { ...diff, upToDate: true };
+  }
+
+  const newFiles = { ...manifest.files };
+
+  /**
+   * Copy a source file entry to its destination.
+   * Fix 11-12: Uses O(1) Map lookup instead of O(n) Array.find to eliminate O(n²) worst case.
+   * @param {string} relPath
+   */
+  function applyCopy(relPath) {
+    const entry = sourceFileMap.get(relPath);
+    if (!entry) return;
+    const destAbs = join(projectRoot, relPath);
+    // Bounds check: destination must stay inside .claude/ subtree
+    assertSafePath(destAbs, claudeRoot, `copy destination for "${relPath}"`);
+    mkdirSync(dirname(destAbs), { recursive: true });
+    copyFileSync(entry.sourceAbsPath, destAbs);
+    // Reuse source checksum — copy is bit-for-bit identical, no need to re-hash
+    newFiles[relPath] = { checksum: sourceFiles[relPath].checksum, size: entry.size };
+  }
+
+  // Apply safe updates
+  for (const relPath of diff.updated) {
+    applyCopy(relPath);
+  }
+
+  // Handle conflicts
+  const skippedConflicts = [];
+  for (const relPath of diff.conflicts) {
+    if (force) {
+      applyCopy(relPath);
+    } else {
+      skippedConflicts.push(relPath);
+    }
+  }
+
+  // Add new files
+  for (const relPath of diff.added) {
+    applyCopy(relPath);
+  }
+
+  // Remove deleted kit files
+  for (const relPath of diff.removed) {
+    const absPath = join(projectRoot, relPath);
+    // Bounds check: removal must stay inside .claude/ subtree
+    try {
+      assertSafePath(absPath, claudeRoot, `removal target "${relPath}"`);
+    } catch (err) {
+      process.stderr.write(`Warning: Skipping unsafe removal path: ${err.message}\n`);
+      continue;
+    }
+    try {
+      unlinkSync(absPath);
+    } catch {
+      // Already missing — skip
+    }
+    delete newFiles[relPath];
+  }
+
+  // Orphan cleanup: files on disk (in kit subdirs) that are not in the new source
+  const diskFiles = collectDiskFiles(targetDir);
+  const orphans = [];
+  const orphanParentDirs = new Set();
+  for (const relPath of diskFiles) {
+    if (relPath in sourceFiles) continue; // present in new source — keep
+    const absPath = join(projectRoot, relPath);
+    try {
+      assertSafePath(absPath, claudeRoot, `orphan "${relPath}"`);
+    } catch (err) {
+      process.stderr.write(`Warning: Skipping unsafe orphan path: ${err.message}\n`);
+      continue;
+    }
+    try {
+      unlinkSync(absPath);
+      orphans.push(relPath);
+      orphanParentDirs.add(dirname(absPath));
+    } catch {
+      // Already missing — skip
+    }
+  }
+
+  // Clean up empty directories bottom-up after orphan deletion
+  const resolvedTarget = resolve(targetDir);
+  const sortedOrphanDirs = [...orphanParentDirs].sort((a, b) => {
+    return b.split(/[/\\]/).length - a.split(/[/\\]/).length;
+  });
+  for (const dir of sortedOrphanDirs) {
+    if (isEmptyDir(dir)) {
+      try {
+        rmdirSync(dir);
+        let current = dirname(dir);
+        let prev = dir;
+        while (current !== prev && isEmptyDir(current)) {
+          const resolvedCurrent = resolve(current);
+          if (resolvedCurrent === resolvedTarget || !resolvedCurrent.startsWith(resolvedTarget + sep)) {
+            break;
+          }
+          try {
+            rmdirSync(current);
+          } catch {
+            break;
+          }
+          prev = current;
+          current = dirname(current);
+        }
+      } catch {
+        // Non-empty or permission error — skip
+      }
+    }
+  }
+
+  // Merge settings.json hooks — additive merge, never overwrites user keys
+  mergeSettingsJson(sourceDir, targetDir);
+
+  // Update manifest with new file map.
+  // Use explicitVersion when provided (e.g. release.version from updateAction);
+  // fall back to pkg.version for direct runUpdate calls or main-branch fallback downloads.
+  updateManifest(manifestPath, newFiles, explicitVersion ?? pkg.version);
+
+  return {
+    updated: diff.updated,
+    added: diff.added,
+    removed: diff.removed,
+    conflicts: skippedConflicts,
+    unchanged: diff.unchanged,
+    orphans,
+    upToDate: false
+  };
+}
+
+/**
+ * CLI action handler for 'mk update'.
+ * Checks GitHub Releases for a newer version, prompts the user, then downloads
+ * and applies a three-way diff. Falls back to the main-branch tarball if no
+ * release information is available.
+ *
+ * @param {{ force: boolean, global: boolean }} options
+ * @param {object} [deps] - Injected dependencies (for testing)
+ */
+export async function updateAction(options = {}, deps = {}) {
+  const {
+    resolveTokenOrLogin: resolveAndLogin = resolveTokenOrLogin,
+    downloadAndExtractKit: download = downloadAndExtractKit,
+    cleanupTempDir: cleanup = cleanupTempDir,
+    writeToken: storeToken = writeToken,
+    readStoredToken: readToken = readStoredToken,
+    fetchLatestRelease: fetchRelease = fetchLatestRelease,
+    compareVersions: cmpVersions = compareVersions,
+    promptUser = defaultPromptUser,
+    // Injectable for tests — allows overriding resolved paths without touching CWD
+    manifestPath: injectedManifestPath,
+    targetDir: injectedTargetDir
+  } = deps;
+
+  // Read local package version (used as fallback when manifest has no version)
+  const pkg = JSON.parse(
+    readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')
+  );
+
+  const targetDir = injectedTargetDir ?? resolveTargetDir(options);
+  const manifestPath = injectedManifestPath ?? resolveManifestPath(options);
+
+  let tempDir = null;
+  try {
+    process.stdout.write('Authenticating with GitHub...\n');
+    const token = await resolveAndLogin({
+      readStored: readToken,
+      writeStored: storeToken,
+      display: ({ userCode, verificationUri, expiresIn }) => {
+        process.stdout.write('\n');
+        process.stdout.write(chalk.bold('To authenticate, visit:  ') + chalk.cyan(verificationUri) + '\n');
+        process.stdout.write(chalk.bold('And enter the code:      ') + chalk.yellow(userCode) + '\n');
+        process.stdout.write(`(Code expires in ${Math.round(expiresIn / 60)} minutes)\n\n`);
+        process.stdout.write('Waiting for authorization...\n');
+      }
+    });
+
+    // --- Version check via GitHub Releases API ---
+    process.stdout.write('Checking for updates...\n');
+    const release = await fetchRelease(token);
+
+    // Read installed version from manifest (more accurate than pkg.version which reflects
+    // the CLI package, not the downloaded kit files). Fall back to pkg.version if no manifest.
+    let installedVersion = pkg.version;
+    if (existsSync(manifestPath)) {
+      try {
+        const existingManifest = readManifest(manifestPath);
+        if (existingManifest?.version) installedVersion = existingManifest.version;
+      } catch {
+        // Manifest unreadable — proceed with pkg.version fallback
+      }
+    }
+
+    let downloadUrl; // undefined = use default (main branch)
+    let releaseVersion; // set when downloading from a specific release tarball
+
+    if (!release.available) {
+      // No release found or API error — warn and fall back to main branch
+      process.stdout.write(
+        chalk.yellow(`Warning: Could not check latest release (${release.reason}). Falling back to main branch.\n`)
+      );
+    } else {
+      const { needsUpdate, local, remote } = cmpVersions(installedVersion, release.version);
+
+      if (!needsUpdate) {
+        process.stdout.write(chalk.green(`Already up to date (v${local}).\n`));
+        // Still merge settings.json hooks from the bundled local source.
+        // The installed settings.json may be missing hooks if it was created
+        // before hooks were added to the kit or if it was manually edited.
+        // resolveSourceDir() points to the CLI package's own .claude/ — no download needed.
+        mergeSettingsJson(resolveSourceDir(), targetDir);
+        return;
+      }
+
+      // Show version diff
+      process.stdout.write(
+        chalk.cyan(`Update available: v${local} -> v${remote}\n`)
+      );
+
+      // Show release notes (if any), truncated to 500 chars.
+      // S4: Strip terminal escape sequences before printing to prevent injection via
+      // crafted GitHub release bodies (CSI/OSC sequences can clear screen, set window titles, etc.).
+      const body = release.body;
+      if (body && body.trim().length > 0) {
+        const rawNotes = body.length > 500 ? body.slice(0, 500) + '...' : body;
+        const notes = stripTerminalEscapes(rawNotes);
+        process.stdout.write('\nRelease notes:\n');
+        process.stdout.write(notes + '\n\n');
+      }
+
+      // Prompt user
+      const confirmed = await promptUser(`Update to v${remote}? [y/N] `);
+      if (!confirmed) {
+        process.stdout.write('Update cancelled.\n');
+        return;
+      }
+
+      downloadUrl = release.tarballUrl;
+      releaseVersion = release.version;
+    }
+
+    // --- Download and apply ---
+    process.stdout.write('Downloading latest kit from GitHub...\n');
+    tempDir = await download(token, downloadUrl !== undefined ? { url: downloadUrl } : {});
+    const sourceDir = join(tempDir, '.claude');
+
+    // Pass releaseVersion so runUpdate stores it in the manifest.
+    // When falling back to main branch (no release), releaseVersion is undefined and
+    // runUpdate falls back to pkg.version — which is the correct behaviour for that path.
+    const result = await runUpdate({ sourceDir, targetDir, manifestPath, force: options.force, version: releaseVersion });
+
+    if (result.upToDate) {
+      process.stdout.write(chalk.green('Already up to date.\n'));
+    } else {
+      if (result.updated.length > 0) {
+        process.stdout.write(chalk.green(`Updated: ${result.updated.length} files\n`));
+      }
+      if (result.added.length > 0) {
+        process.stdout.write(chalk.green(`Added: ${result.added.length} new files\n`));
+      }
+      if (result.removed.length > 0) {
+        process.stdout.write(chalk.yellow(`Removed: ${result.removed.length} files\n`));
+        for (const f of result.removed) {
+          process.stdout.write(`  Removed: ${f}\n`);
+        }
+      }
+      if (result.orphans && result.orphans.length > 0) {
+        process.stdout.write(chalk.yellow(`Cleaned: ${result.orphans.length} orphan files\n`));
+        for (const f of result.orphans) {
+          process.stdout.write(`  Cleaned: ${f}\n`);
+        }
+      }
+      if (result.conflicts.length > 0) {
+        process.stdout.write(
+          chalk.yellow(`Skipped: ${result.conflicts.length} user-modified files (use --force to overwrite)\n`)
+        );
+        for (const f of result.conflicts) {
+          process.stdout.write(`  ${f}\n`);
+        }
+      }
+    }
+  } catch (err) {
+    process.stderr.write(chalk.red(`Error: ${err.message}\n`));
+    process.exit(1);
+  } finally {
+    if (tempDir) {
+      cleanup(tempDir);
+    }
+  }
+}