@luanpdd/kit-mcp 1.20.0 → 1.21.0

package/src/core/reverse-sync.js

@@ -1,372 +1,372 @@
-// Reverse-sync — bring edits made directly in an IDE's layout back into the
-// canonical kit/.
-//
-// Workflow:
-//   detect(target)          → list candidates: files modified or added in the IDE
-//                             that don't exist (or differ from) the canonical
-//   apply(target, strategy) → for each candidate, apply: skip | overwrite | merge | rename
-//
-// We are conservative on purpose: detection is read-only, application requires
-// an explicit strategy, and we never touch files we generated ourselves
-// (those carry STUB_MARKER and the boilerplate footer).
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { getTarget } from './registry.js';
-import { listKit, resolveKitRoot } from './kit.js';
-
-const STUB_MARKER     = '<!-- kit-mcp:reference -->';
-const STUB_FOOTER     = 'Edit the source file in the kit, not this stub.';
-const STUB_GENERATED  = 'Generated by kit-mcp at';
-const STUB_CANONICAL  = 'Canonical source:';
-
-// --- detect ---
-
-export async function detectReverse(targetId, opts = {}) {
-  const target      = getTarget(targetId);
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const kitRoot     = resolveKitRoot(opts.kitRoot);
-  // PERF-03: accept a pre-loaded kit; reduces sync+reverse-sync from 2 walks to 1.
-  const kit         = opts.kit ?? await listKit(kitRoot);
-
-  const candidates = [];
-
-  // PERF-16-03: parallelize the 5 scans. Each scan reads a distinct subdirectory
-  // of the IDE layout (.claude/agents, .claude/commands, .claude/skills,
-  // .claude/framework, .claude/hooks) — there is no I/O contention between them.
-  //
-  // Each scan continues to push into the shared `candidates` array. This is safe
-  // under the single-threaded JS event loop: `Array.prototype.push` is a
-  // synchronous operation that completes between awaits, so concurrent scans
-  // never produce a torn write. The trade-off is that candidate ordering is no
-  // longer deterministic across categories — existing reverse-sync tests use
-  // `.find` / `.some` / `.filter` and never index `candidates[N]`, so this is a
-  // safe widening of the contract.
-  //
-  // Error semantics: `Promise.all` rejects on the first rejection — identical to
-  // the previous sequential `await` chain (which also propagated the first error
-  // and aborted the rest). Fail-fast is preserved.
-  const pending = [];
-
-  if (target.agents)   pending.push(scanCapability(candidates, 'agent',   target.agents,   projectRoot, kit.agents,   kitRoot));
-  if (target.commands) pending.push(scanCapability(candidates, 'command', target.commands, projectRoot, kit.commands, kitRoot));
-  if (target.skills)   pending.push(scanSkills    (candidates,            target.skills,   projectRoot, [...kit.skills, ...kit.skillsExtras], kitRoot));
-  for (const cap of ['framework', 'hooks']) {
-    const spec = target[cap];
-    if (!spec || spec.mode !== 'mirror-tree') continue;
-    pending.push(scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot));
-  }
-
-  await Promise.all(pending);
-
-  return { target: targetId, projectRoot, kitRoot, candidates };
-}
-
-async function scanCapability(candidates, kind, capCfg, projectRoot, kitItems, kitRoot) {
-  const dir = path.join(projectRoot, capCfg.path);
-  let entries;
-  try { entries = await fs.readdir(dir, { withFileTypes: true }); }
-  catch { return; }
-
-  for (const e of entries) {
-    if (!e.isFile()) continue;
-    const ext = capCfg.extension || '.md';
-    if (!e.name.endsWith(ext)) continue;
-    const name = e.name.slice(0, -ext.length);
-    const destPath = path.join(dir, e.name);
-    const destContent = await fs.readFile(destPath, 'utf8');
-
-    if (isCleanStub(destContent)) continue;  // we generated it, not edited
-
-    const kitItem = kitItems.find(x => x.name === name);
-    if (!kitItem) {
-      candidates.push({
-        kind, name, target: capCfg.path, destPath,
-        kitPath: path.join(kitRoot, kindToFolder(kind), `${name}.md`),
-        reason: 'new-in-ide',
-        diffSummary: `+${destContent.length} bytes (no kit source)`,
-      });
-      continue;
-    }
-
-    const stripped = stripStubBoilerplate(destContent);
-    if (normalize(stripped) === normalize(kitItem.content)) continue;  // same as canonical
-
-    candidates.push({
-      kind, name, target: capCfg.path, destPath,
-      kitPath: kitItem.absPath,
-      reason: 'modified-in-ide',
-      diffSummary: summarizeDiff(kitItem.content, stripped),
-    });
-  }
-}
-
-async function scanSkills(candidates, capCfg, projectRoot, kitSkills, kitRoot) {
-  const dir = path.join(projectRoot, capCfg.path);
-  let entries;
-  try { entries = await fs.readdir(dir, { withFileTypes: true }); }
-  catch { return; }
-
-  for (const e of entries) {
-    if (!e.isDirectory()) continue;
-    const skillName = e.name;
-    const skillFile = path.join(dir, skillName, 'SKILL.md');
-    let destContent;
-    try { destContent = await fs.readFile(skillFile, 'utf8'); }
-    catch { continue; }
-
-    if (isCleanStub(destContent)) continue;
-
-    const kitItem = kitSkills.find(x => x.name === skillName);
-    if (!kitItem) {
-      candidates.push({
-        kind: 'skill', name: skillName, target: capCfg.path, destPath: skillFile,
-        kitPath: path.join(kitRoot, 'skills', skillName, 'SKILL.md'),
-        reason: 'new-in-ide',
-        diffSummary: `+${destContent.length} bytes (no kit source)`,
-      });
-      continue;
-    }
-
-    const stripped = stripStubBoilerplate(destContent);
-    if (normalize(stripped) === normalize(kitItem.skillContent)) continue;
-
-    candidates.push({
-      kind: 'skill', name: skillName, target: capCfg.path, destPath: skillFile,
-      kitPath: kitItem.absPath,
-      reason: 'modified-in-ide',
-      diffSummary: summarizeDiff(kitItem.skillContent, stripped),
-    });
-  }
-}
-
-async function scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot) {
-  const dstRoot = path.join(projectRoot, spec.path);
-  const srcRoot = path.join(kitRoot, spec.source);
-  const files = await walkRel(dstRoot);
-  for (const rel of files) {
-    if (rel === '.kit-mcp-managed' || path.basename(rel) === '.kit-mcp-managed') continue;
-    const dstPath = path.join(dstRoot, rel);
-    const srcPath = path.join(srcRoot, rel);
-    let dstBuf, srcBuf;
-    try { dstBuf = await fs.readFile(dstPath); } catch { continue; }
-    try { srcBuf = await fs.readFile(srcPath); } catch { srcBuf = null; }
-    if (!srcBuf) {
-      candidates.push({
-        kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
-        reason: 'new-in-ide',
-        diffSummary: `+${dstBuf.length} bytes (no kit source)`,
-      });
-      continue;
-    }
-    if (dstBuf.equals(srcBuf)) continue;
-    candidates.push({
-      kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
-      reason: 'modified-in-ide',
-      diffSummary: `${dstBuf.length} bytes vs ${srcBuf.length} canonical (${dstBuf.length - srcBuf.length >= 0 ? '+' : ''}${dstBuf.length - srcBuf.length})`,
-    });
-  }
-}
-
-async function walkRel(root) {
-  const out = [];
-  async function visit(current, prefix) {
-    let entries;
-    try { entries = await fs.readdir(current, { withFileTypes: true }); }
-    catch { return; }
-    for (const e of entries) {
-      const abs = path.join(current, e.name);
-      const rel = prefix ? `${prefix}/${e.name}` : e.name;
-      if (e.isDirectory()) await visit(abs, rel);
-      else if (e.isFile()) out.push(rel);
-    }
-  }
-  await visit(root, '');
-  return out;
-}
-
-// --- apply ---
-
-export async function applyReverse(targetId, opts = {}) {
-  const strategy = opts.strategy ?? 'skip';
-  const onProgress = opts.onProgress ?? (() => {});
-  const { candidates } = await detectReverse(targetId, opts);
-  const results = [];
-
-  for (let i = 0; i < candidates.length; i++) {
-    const c = candidates[i];
-    if (opts.only && !opts.only.includes(`${c.kind}/${c.name}`)) {
-      results.push({ ...c, action: 'skipped (filter)' });
-      onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
-      continue;
-    }
-
-    const action = await applyOne(c, strategy, opts);
-    results.push({ ...c, action });
-    onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
-  }
-
-  return { target: targetId, strategy, results };
-}
-
-async function applyOne(c, strategy, opts) {
-  const dryRun = !!opts.dryRun;
-  const isMirrorTree = c.kind === 'framework' || c.kind === 'hooks';
-
-  // Mirror-tree files don't have stub boilerplate — copy bytes verbatim.
-  if (isMirrorTree) {
-    return applyMirrorTreeOne(c, strategy, dryRun);
-  }
-
-  const destContent = await fs.readFile(c.destPath, 'utf8');
-  const stripped = stripStubBoilerplate(destContent);
-
-  switch (strategy) {
-    case 'skip':
-      return 'skipped';
-
-    case 'overwrite': {
-      if (!dryRun) {
-        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
-        await fs.writeFile(c.kitPath, stripped, 'utf8');
-      }
-      return dryRun ? 'overwrite (dry-run)' : 'overwritten';
-    }
-
-    case 'merge': {
-      let merged = stripped;
-      if (c.reason === 'modified-in-ide') {
-        try {
-          const canonical = await fs.readFile(c.kitPath, 'utf8');
-          merged = mergeFrontmatter(canonical, stripped);
-        } catch { /* canonical missing → just take stripped */ }
-      }
-      if (!dryRun) {
-        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
-        await fs.writeFile(c.kitPath, merged, 'utf8');
-      }
-      return dryRun ? 'merge (dry-run)' : 'merged';
-    }
-
-    case 'rename': {
-      const base = c.kitPath.replace(/\.md$/, '');
-      const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '');
-      const out = `${base}-from-${tag || 'ide'}.md`;
-      if (!dryRun) {
-        await fs.mkdir(path.dirname(out), { recursive: true });
-        await fs.writeFile(out, stripped, 'utf8');
-      }
-      return dryRun ? `rename → ${out} (dry-run)` : `renamed → ${out}`;
-    }
-
-    default:
-      return `unknown strategy: ${strategy}`;
-  }
-}
-
-async function applyMirrorTreeOne(c, strategy, dryRun) {
-  switch (strategy) {
-    case 'skip':
-      return 'skipped';
-
-    case 'overwrite':
-    case 'merge': {
-      // For framework/hooks files there's no frontmatter to preserve,
-      // so 'merge' degenerates to overwrite. Returning a verb that
-      // signals the degradation.
-      const verb = strategy === 'merge' ? 'merged (overwrite, no frontmatter)' : 'overwritten';
-      if (!dryRun) {
-        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
-        await fs.copyFile(c.destPath, c.kitPath);
-      }
-      return dryRun ? `${strategy} (dry-run)` : verb;
-    }
-
-    case 'rename': {
-      // Write to kit/<source>/<rel>.from-<tag> preserving extension after the tag.
-      const ext = path.extname(c.kitPath);
-      const stem = c.kitPath.slice(0, c.kitPath.length - ext.length);
-      const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '') || 'ide';
-      const out = `${stem}.from-${tag}${ext}`;
-      if (!dryRun) {
-        await fs.mkdir(path.dirname(out), { recursive: true });
-        await fs.copyFile(c.destPath, out);
-      }
-      return dryRun ? `rename → ${out} (dry-run)` : `renamed → ${out}`;
-    }
-
-    default:
-      return `unknown strategy: ${strategy}`;
-  }
-}
-
-// --- helpers ---
-
-function isCleanStub(content) {
-  // A "clean" stub has all four markers. If the user removed any (likely by editing),
-  // we treat it as user content.
-  return content.includes(STUB_MARKER) &&
-         content.includes(STUB_CANONICAL) &&
-         content.includes(STUB_GENERATED) &&
-         content.includes(STUB_FOOTER);
-}
-
-function stripStubBoilerplate(content) {
-  // Remove the kit-mcp boilerplate so we can compare against the canonical.
-  // This handles partially-edited stubs (user kept some markers but added body).
-  if (!content.includes(STUB_MARKER)) return content;
-
-  const lines = content.split(/\r?\n/);
-  const filtered = [];
-  let inBoilerplate = false;
-  for (const line of lines) {
-    if (line.includes(STUB_MARKER)) { inBoilerplate = true; continue; }
-    if (inBoilerplate) {
-      // Boilerplate ends after we've consumed the auto-generated header block
-      if (/^>\s*Edit the source file/.test(line)) { inBoilerplate = false; continue; }
-      // Also skip the "# name", "> Canonical source:", description and timestamp lines
-      if (/^#\s+\S+\s*$/.test(line) ||
-          /^>\s*Canonical source:/.test(line) ||
-          /^>\s*Generated by kit-mcp at/.test(line) ||
-          /^>\s*\S/.test(line) ||
-          line.trim() === '') {
-        continue;
-      }
-      // First non-boilerplate line — flush and stop skipping
-      inBoilerplate = false;
-    }
-    filtered.push(line);
-  }
-  return filtered.join('\n').replace(/^\s+/, '');  // drop leading blank lines
-}
-
-function normalize(content) {
-  return content.replace(/\s+/g, ' ').trim();
-}
-
-function summarizeDiff(canonical, edited) {
-  const cLines = canonical.split(/\r?\n/).length;
-  const eLines = edited.split(/\r?\n/).length;
-  const delta  = eLines - cLines;
-  const pct    = canonical.length === 0 ? 100 : Math.round((edited.length - canonical.length) / canonical.length * 100);
-  return `${eLines} lines (${delta >= 0 ? '+' : ''}${delta}); ${pct >= 0 ? '+' : ''}${pct}% size`;
-}
-
-function mergeFrontmatter(canonical, edited) {
-  // Take the canonical frontmatter (has the formal metadata like tools, color, hooks)
-  // and append the edited body (everything after the first --- block, or the whole
-  // edited content if it has no frontmatter).
-  const fmMatch = canonical.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/);
-  if (!fmMatch) return edited;
-
-  const editedBody = edited.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
-  const body = editedBody ? editedBody[1] : edited;
-  return fmMatch[1] + body;
-}
-
-function kindToFolder(kind) {
-  if (kind === 'agent')   return 'agents';
-  if (kind === 'command') return 'commands';
-  if (kind === 'skill')   return 'skills';
-  return kind;
-}
+// Reverse-sync — bring edits made directly in an IDE's layout back into the
+// canonical kit/.
+//
+// Workflow:
+//   detect(target)          → list candidates: files modified or added in the IDE
+//                             that don't exist (or differ from) the canonical
+//   apply(target, strategy) → for each candidate, apply: skip | overwrite | merge | rename
+//
+// We are conservative on purpose: detection is read-only, application requires
+// an explicit strategy, and we never touch files we generated ourselves
+// (those carry STUB_MARKER and the boilerplate footer).
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { getTarget } from './registry.js';
+import { listKit, resolveKitRoot } from './kit.js';
+
+const STUB_MARKER     = '<!-- kit-mcp:reference -->';
+const STUB_FOOTER     = 'Edit the source file in the kit, not this stub.';
+const STUB_GENERATED  = 'Generated by kit-mcp at';
+const STUB_CANONICAL  = 'Canonical source:';
+
+// --- detect ---
+
+export async function detectReverse(targetId, opts = {}) {
+  const target      = getTarget(targetId);
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const kitRoot     = resolveKitRoot(opts.kitRoot);
+  // PERF-03: accept a pre-loaded kit; reduces sync+reverse-sync from 2 walks to 1.
+  const kit         = opts.kit ?? await listKit(kitRoot);
+
+  const candidates = [];
+
+  // PERF-16-03: parallelize the 5 scans. Each scan reads a distinct subdirectory
+  // of the IDE layout (.claude/agents, .claude/commands, .claude/skills,
+  // .claude/framework, .claude/hooks) — there is no I/O contention between them.
+  //
+  // Each scan continues to push into the shared `candidates` array. This is safe
+  // under the single-threaded JS event loop: `Array.prototype.push` is a
+  // synchronous operation that completes between awaits, so concurrent scans
+  // never produce a torn write. The trade-off is that candidate ordering is no
+  // longer deterministic across categories — existing reverse-sync tests use
+  // `.find` / `.some` / `.filter` and never index `candidates[N]`, so this is a
+  // safe widening of the contract.
+  //
+  // Error semantics: `Promise.all` rejects on the first rejection — identical to
+  // the previous sequential `await` chain (which also propagated the first error
+  // and aborted the rest). Fail-fast is preserved.
+  const pending = [];
+
+  if (target.agents)   pending.push(scanCapability(candidates, 'agent',   target.agents,   projectRoot, kit.agents,   kitRoot));
+  if (target.commands) pending.push(scanCapability(candidates, 'command', target.commands, projectRoot, kit.commands, kitRoot));
+  if (target.skills)   pending.push(scanSkills    (candidates,            target.skills,   projectRoot, [...kit.skills, ...kit.skillsExtras], kitRoot));
+  for (const cap of ['framework', 'hooks']) {
+    const spec = target[cap];
+    if (!spec || spec.mode !== 'mirror-tree') continue;
+    pending.push(scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot));
+  }
+
+  await Promise.all(pending);
+
+  return { target: targetId, projectRoot, kitRoot, candidates };
+}
+
+async function scanCapability(candidates, kind, capCfg, projectRoot, kitItems, kitRoot) {
+  const dir = path.join(projectRoot, capCfg.path);
+  let entries;
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const ext = capCfg.extension || '.md';
+    if (!e.name.endsWith(ext)) continue;
+    const name = e.name.slice(0, -ext.length);
+    const destPath = path.join(dir, e.name);
+    const destContent = await fs.readFile(destPath, 'utf8');
+
+    if (isCleanStub(destContent)) continue;  // we generated it, not edited
+
+    const kitItem = kitItems.find(x => x.name === name);
+    if (!kitItem) {
+      candidates.push({
+        kind, name, target: capCfg.path, destPath,
+        kitPath: path.join(kitRoot, kindToFolder(kind), `${name}.md`),
+        reason: 'new-in-ide',
+        diffSummary: `+${destContent.length} bytes (no kit source)`,
+      });
+      continue;
+    }
+
+    const stripped = stripStubBoilerplate(destContent);
+    if (normalize(stripped) === normalize(kitItem.content)) continue;  // same as canonical
+
+    candidates.push({
+      kind, name, target: capCfg.path, destPath,
+      kitPath: kitItem.absPath,
+      reason: 'modified-in-ide',
+      diffSummary: summarizeDiff(kitItem.content, stripped),
+    });
+  }
+}
+
+async function scanSkills(candidates, capCfg, projectRoot, kitSkills, kitRoot) {
+  const dir = path.join(projectRoot, capCfg.path);
+  let entries;
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const skillName = e.name;
+    const skillFile = path.join(dir, skillName, 'SKILL.md');
+    let destContent;
+    try { destContent = await fs.readFile(skillFile, 'utf8'); }
+    catch { continue; }
+
+    if (isCleanStub(destContent)) continue;
+
+    const kitItem = kitSkills.find(x => x.name === skillName);
+    if (!kitItem) {
+      candidates.push({
+        kind: 'skill', name: skillName, target: capCfg.path, destPath: skillFile,
+        kitPath: path.join(kitRoot, 'skills', skillName, 'SKILL.md'),
+        reason: 'new-in-ide',
+        diffSummary: `+${destContent.length} bytes (no kit source)`,
+      });
+      continue;
+    }
+
+    const stripped = stripStubBoilerplate(destContent);
+    if (normalize(stripped) === normalize(kitItem.skillContent)) continue;
+
+    candidates.push({
+      kind: 'skill', name: skillName, target: capCfg.path, destPath: skillFile,
+      kitPath: kitItem.absPath,
+      reason: 'modified-in-ide',
+      diffSummary: summarizeDiff(kitItem.skillContent, stripped),
+    });
+  }
+}
+
+async function scanMirrorTree(candidates, cap, spec, projectRoot, kitRoot) {
+  const dstRoot = path.join(projectRoot, spec.path);
+  const srcRoot = path.join(kitRoot, spec.source);
+  const files = await walkRel(dstRoot);
+  for (const rel of files) {
+    if (rel === '.kit-mcp-managed' || path.basename(rel) === '.kit-mcp-managed') continue;
+    const dstPath = path.join(dstRoot, rel);
+    const srcPath = path.join(srcRoot, rel);
+    let dstBuf, srcBuf;
+    try { dstBuf = await fs.readFile(dstPath); } catch { continue; }
+    try { srcBuf = await fs.readFile(srcPath); } catch { srcBuf = null; }
+    if (!srcBuf) {
+      candidates.push({
+        kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
+        reason: 'new-in-ide',
+        diffSummary: `+${dstBuf.length} bytes (no kit source)`,
+      });
+      continue;
+    }
+    if (dstBuf.equals(srcBuf)) continue;
+    candidates.push({
+      kind: cap, name: rel, target: spec.path, destPath: dstPath, kitPath: srcPath,
+      reason: 'modified-in-ide',
+      diffSummary: `${dstBuf.length} bytes vs ${srcBuf.length} canonical (${dstBuf.length - srcBuf.length >= 0 ? '+' : ''}${dstBuf.length - srcBuf.length})`,
+    });
+  }
+}
+
+async function walkRel(root) {
+  const out = [];
+  async function visit(current, prefix) {
+    let entries;
+    try { entries = await fs.readdir(current, { withFileTypes: true }); }
+    catch { return; }
+    for (const e of entries) {
+      const abs = path.join(current, e.name);
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) await visit(abs, rel);
+      else if (e.isFile()) out.push(rel);
+    }
+  }
+  await visit(root, '');
+  return out;
+}
+
+// --- apply ---
+
+export async function applyReverse(targetId, opts = {}) {
+  const strategy = opts.strategy ?? 'skip';
+  const onProgress = opts.onProgress ?? (() => {});
+  const { candidates } = await detectReverse(targetId, opts);
+  const results = [];
+
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
+    if (opts.only && !opts.only.includes(`${c.kind}/${c.name}`)) {
+      results.push({ ...c, action: 'skipped (filter)' });
+      onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
+      continue;
+    }
+
+    const action = await applyOne(c, strategy, opts);
+    results.push({ ...c, action });
+    onProgress({ phase: c.kind, current: i + 1, total: candidates.length, label: c.name });
+  }
+
+  return { target: targetId, strategy, results };
+}
+
+async function applyOne(c, strategy, opts) {
+  const dryRun = !!opts.dryRun;
+  const isMirrorTree = c.kind === 'framework' || c.kind === 'hooks';
+
+  // Mirror-tree files don't have stub boilerplate — copy bytes verbatim.
+  if (isMirrorTree) {
+    return applyMirrorTreeOne(c, strategy, dryRun);
+  }
+
+  const destContent = await fs.readFile(c.destPath, 'utf8');
+  const stripped = stripStubBoilerplate(destContent);
+
+  switch (strategy) {
+    case 'skip':
+      return 'skipped';
+
+    case 'overwrite': {
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
+        await fs.writeFile(c.kitPath, stripped, 'utf8');
+      }
+      return dryRun ? 'overwrite (dry-run)' : 'overwritten';
+    }
+
+    case 'merge': {
+      let merged = stripped;
+      if (c.reason === 'modified-in-ide') {
+        try {
+          const canonical = await fs.readFile(c.kitPath, 'utf8');
+          merged = mergeFrontmatter(canonical, stripped);
+        } catch { /* canonical missing → just take stripped */ }
+      }
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
+        await fs.writeFile(c.kitPath, merged, 'utf8');
+      }
+      return dryRun ? 'merge (dry-run)' : 'merged';
+    }
+
+    case 'rename': {
+      const base = c.kitPath.replace(/\.md$/, '');
+      const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '');
+      const out = `${base}-from-${tag || 'ide'}.md`;
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(out), { recursive: true });
+        await fs.writeFile(out, stripped, 'utf8');
+      }
+      return dryRun ? `rename → ${out} (dry-run)` : `renamed → ${out}`;
+    }
+
+    default:
+      return `unknown strategy: ${strategy}`;
+  }
+}
+
+async function applyMirrorTreeOne(c, strategy, dryRun) {
+  switch (strategy) {
+    case 'skip':
+      return 'skipped';
+
+    case 'overwrite':
+    case 'merge': {
+      // For framework/hooks files there's no frontmatter to preserve,
+      // so 'merge' degenerates to overwrite. Returning a verb that
+      // signals the degradation.
+      const verb = strategy === 'merge' ? 'merged (overwrite, no frontmatter)' : 'overwritten';
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(c.kitPath), { recursive: true });
+        await fs.copyFile(c.destPath, c.kitPath);
+      }
+      return dryRun ? `${strategy} (dry-run)` : verb;
+    }
+
+    case 'rename': {
+      // Write to kit/<source>/<rel>.from-<tag> preserving extension after the tag.
+      const ext = path.extname(c.kitPath);
+      const stem = c.kitPath.slice(0, c.kitPath.length - ext.length);
+      const tag = path.basename(path.dirname(path.dirname(c.destPath))).replace(/^\./, '') || 'ide';
+      const out = `${stem}.from-${tag}${ext}`;
+      if (!dryRun) {
+        await fs.mkdir(path.dirname(out), { recursive: true });
+        await fs.copyFile(c.destPath, out);
+      }
+      return dryRun ? `rename → ${out} (dry-run)` : `renamed → ${out}`;
+    }
+
+    default:
+      return `unknown strategy: ${strategy}`;
+  }
+}
+
+// --- helpers ---
+
+function isCleanStub(content) {
+  // A "clean" stub has all four markers. If the user removed any (likely by editing),
+  // we treat it as user content.
+  return content.includes(STUB_MARKER) &&
+         content.includes(STUB_CANONICAL) &&
+         content.includes(STUB_GENERATED) &&
+         content.includes(STUB_FOOTER);
+}
+
+function stripStubBoilerplate(content) {
+  // Remove the kit-mcp boilerplate so we can compare against the canonical.
+  // This handles partially-edited stubs (user kept some markers but added body).
+  if (!content.includes(STUB_MARKER)) return content;
+
+  const lines = content.split(/\r?\n/);
+  const filtered = [];
+  let inBoilerplate = false;
+  for (const line of lines) {
+    if (line.includes(STUB_MARKER)) { inBoilerplate = true; continue; }
+    if (inBoilerplate) {
+      // Boilerplate ends after we've consumed the auto-generated header block
+      if (/^>\s*Edit the source file/.test(line)) { inBoilerplate = false; continue; }
+      // Also skip the "# name", "> Canonical source:", description and timestamp lines
+      if (/^#\s+\S+\s*$/.test(line) ||
+          /^>\s*Canonical source:/.test(line) ||
+          /^>\s*Generated by kit-mcp at/.test(line) ||
+          /^>\s*\S/.test(line) ||
+          line.trim() === '') {
+        continue;
+      }
+      // First non-boilerplate line — flush and stop skipping
+      inBoilerplate = false;
+    }
+    filtered.push(line);
+  }
+  return filtered.join('\n').replace(/^\s+/, '');  // drop leading blank lines
+}
+
+function normalize(content) {
+  return content.replace(/\s+/g, ' ').trim();
+}
+
+function summarizeDiff(canonical, edited) {
+  const cLines = canonical.split(/\r?\n/).length;
+  const eLines = edited.split(/\r?\n/).length;
+  const delta  = eLines - cLines;
+  const pct    = canonical.length === 0 ? 100 : Math.round((edited.length - canonical.length) / canonical.length * 100);
+  return `${eLines} lines (${delta >= 0 ? '+' : ''}${delta}); ${pct >= 0 ? '+' : ''}${pct}% size`;
+}
+
+function mergeFrontmatter(canonical, edited) {
+  // Take the canonical frontmatter (has the formal metadata like tools, color, hooks)
+  // and append the edited body (everything after the first --- block, or the whole
+  // edited content if it has no frontmatter).
+  const fmMatch = canonical.match(/^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/);
+  if (!fmMatch) return edited;
+
+  const editedBody = edited.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+  const body = editedBody ? editedBody[1] : edited;
+  return fmMatch[1] + body;
+}
+
+function kindToFolder(kind) {
+  if (kind === 'agent')   return 'agents';
+  if (kind === 'command') return 'commands';
+  if (kind === 'skill')   return 'skills';
+  return kind;
+}