arcane-cli 0.31.0 → 0.32.0

package/dist/index.js

@@ -16,11 +16,17 @@ import chalk2 from "chalk";
 // src/modules/copier.ts
 import {
   mkdir,
-  copyFile as fsCopyFile,
   access,
-  readdir
+  readdir,
+  readFile,
+  writeFile
 } from "fs/promises";
+import { createHash } from "crypto";
 import path from "path";
+async function hashFile(filePath) {
+  const content = await readFile(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
 function validateTargetPath(targetDir, relativePath) {
   const resolvedBase = path.resolve(targetDir);
   const resolvedFull = path.resolve(targetDir, relativePath);
@@ -50,7 +56,10 @@ async function copyFile(srcPath, targetDir, relativePath, opts = {}) {
       `Destination already exists: "${relativePath}". Use --force to overwrite.`
     );
   }
-  await fsCopyFile(srcPath, destPath);
+  const content = await readFile(srcPath);
+  const hash = createHash("sha256").update(content).digest("hex");
+  await writeFile(destPath, content);
+  return hash;
 }
 async function copyDirectory(srcDir, targetDir, relativeDir, opts = {}) {
   validateTargetPath(targetDir, relativeDir);
@@ -63,15 +72,15 @@ async function copyDirectory(srcDir, targetDir, relativeDir, opts = {}) {
       const subFiles = await copyDirectory(srcEntryPath, targetDir, relEntryPath, opts);
       copiedFiles.push(...subFiles);
     } else {
-      await copyFile(srcEntryPath, targetDir, relEntryPath, opts);
-      copiedFiles.push(relEntryPath);
+      const hash = await copyFile(srcEntryPath, targetDir, relEntryPath, opts);
+      copiedFiles.push({ path: relEntryPath, hash });
     }
   }
   return copiedFiles;
 }
 
 // src/modules/manifest.ts
-import { readFile, writeFile } from "fs/promises";
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
 var ManifestNotFoundError = class extends Error {
   constructor(manifestPath2) {
@@ -154,7 +163,7 @@ async function readManifest(targetDir) {
   const filePath = manifestPath(targetDir);
   let content;
   try {
-    content = await readFile(filePath, "utf-8");
+    content = await readFile2(filePath, "utf-8");
   } catch (err) {
     if (err.code === "ENOENT") {
       throw new ManifestNotFoundError(filePath);
@@ -180,7 +189,7 @@ async function resolveSecretsScanExcludePrefixes(targetDir) {
   } catch {
   }
   try {
-    const raw = await readFile(path2.join(targetDir, "src", "assets", ".arcane.json"), "utf-8");
+    const raw = await readFile2(path2.join(targetDir, "src", "assets", ".arcane.json"), "utf-8");
     const parsed = JSON.parse(raw);
     if (isRecord(parsed) && parsed["selfHosted"] === true && parsed["tracking_mode"] === "internal") {
       const prefixes = parsed["secretsScanExcludePrefixes"];
@@ -192,7 +201,7 @@ async function resolveSecretsScanExcludePrefixes(targetDir) {
 }
 async function writeManifest(targetDir, manifest) {
   const filePath = manifestPath(targetDir);
-  await writeFile(filePath, JSON.stringify(manifest, null, 2), "utf-8");
+  await writeFile2(filePath, JSON.stringify(manifest, null, 2), "utf-8");
 }
 function addComponent(manifest, component) {
   return {
@@ -866,7 +875,7 @@ function printWarning(message) {
 
 // src/modules/agents.ts
 import { select, checkbox, Separator } from "@inquirer/prompts";
-import { mkdir as mkdir3, writeFile as writeFile4, copyFile as copyFile2 } from "fs/promises";
+import { mkdir as mkdir3, writeFile as writeFile5, copyFile as copyFile2 } from "fs/promises";
 import { join as join3 } from "path";
 import { stringify } from "yaml";
 
@@ -1102,7 +1111,7 @@ async function applyNamingStrategy(strategy, roleIds) {
 }
 
 // src/modules/agent-loader.ts
-import { readFile as readFile2, readdir as readdir2, access as access2 } from "fs/promises";
+import { readFile as readFile3, readdir as readdir2, access as access2 } from "fs/promises";
 import { join } from "path";
 import { parse } from "yaml";
 
@@ -1295,7 +1304,7 @@ async function loadAgentDefinition(agentsDir, id) {
   const filePath = join(agentsDir, `${id}.yaml`);
   let content;
   try {
-    content = await readFile2(filePath, "utf8");
+    content = await readFile3(filePath, "utf8");
   } catch {
     throw new AgentDefinitionNotFoundError(id, agentsDir);
   }
@@ -1305,7 +1314,7 @@ async function loadRoster(targetDir) {
   const rosterPath = join(targetDir, ".arcane", "agents.yaml");
   let content;
   try {
-    content = await readFile2(rosterPath, "utf8");
+    content = await readFile3(rosterPath, "utf8");
   } catch {
     throw new AgentRosterNotFoundError();
   }
@@ -1324,12 +1333,12 @@ function projectAgentsDir(targetDir) {
 }
 
 // src/modules/agent-generator.ts
-import { writeFile as writeFile3, mkdir as mkdir2 } from "fs/promises";
+import { writeFile as writeFile4, mkdir as mkdir2 } from "fs/promises";
 import { join as join2 } from "path";
 import { homedir } from "os";
 
 // src/modules/merger.ts
-import { readFile as readFile3, writeFile as writeFile2, rm } from "fs/promises";
+import { readFile as readFile4, writeFile as writeFile3, rm } from "fs/promises";
 import path3 from "path";
 var MARKER_START = "<!-- arcane:start -->";
 var MARKER_END = "<!-- arcane:end -->";
@@ -1344,7 +1353,7 @@ async function mergeIntoFile(targetDir, relativePath, content, opts = {}) {
   const destPath = path3.resolve(targetDir, relativePath);
   let existing;
   try {
-    existing = await readFile3(destPath, "utf8");
+    existing = await readFile4(destPath, "utf8");
   } catch (err) {
     const e = err;
     if (e.code === "ENOENT") {
@@ -1360,7 +1369,7 @@ ${content}
 ${MARKER_END}
 `;
     if (!opts.dryRun) {
-      await writeFile2(destPath, newContent, "utf8");
+      await writeFile3(destPath, newContent, "utf8");
     }
     return true;
   }
@@ -1385,7 +1394,7 @@ ${MARKER_END}
 ${content}
 ${afterMarker}`;
     if (!opts.dryRun) {
-      await writeFile2(destPath, updated, "utf8");
+      await writeFile3(destPath, updated, "utf8");
     }
     return true;
   }
@@ -1395,7 +1404,7 @@ ${content}
 ${MARKER_END}
 `;
   if (!opts.dryRun) {
-    await writeFile2(destPath, appended, "utf8");
+    await writeFile3(destPath, appended, "utf8");
   }
   return true;
 }
@@ -1403,7 +1412,7 @@ async function stripMarkerSection(targetDir, relativePath, opts = {}) {
   const destPath = path3.resolve(targetDir, relativePath);
   let existing;
   try {
-    existing = await readFile3(destPath, "utf8");
+    existing = await readFile4(destPath, "utf8");
   } catch {
     return false;
   }
@@ -1417,7 +1426,7 @@ async function stripMarkerSection(targetDir, relativePath, opts = {}) {
     if (stripped.length === 0) {
       await rm(destPath, { force: true });
     } else {
-      await writeFile2(destPath, stripped + "\n", "utf8");
+      await writeFile3(destPath, stripped + "\n", "utf8");
     }
   }
   return true;
@@ -1571,17 +1580,17 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       try {
         if (!options.dryRun) {
           await mkdir2(workspaceDir, { recursive: true });
-          await writeFile3(
+          await writeFile4(
             join2(workspaceDir, "IDENTITY.md"),
             renderIdentity(def, displayName),
             "utf8"
           );
-          await writeFile3(
+          await writeFile4(
             join2(workspaceDir, "SOUL.md"),
             renderSoul(def, displayName),
             "utf8"
           );
-          await writeFile3(
+          await writeFile4(
             join2(workspaceDir, "TOOLS.md"),
             renderTools(def, displayName),
             "utf8"
@@ -1610,7 +1619,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
     const generatedDir = join2(targetDir, ".arcane", "generated");
     if (!options.dryRun) {
       await mkdir2(generatedDir, { recursive: true });
-      await writeFile3(
+      await writeFile4(
         join2(generatedDir, "openclaw-roster.json"),
         JSON.stringify(patch, null, 2) + "\n",
         "utf8"
@@ -1632,7 +1641,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       const slug = displayName.toLowerCase().replace(/\s+/g, "-");
       const fileName = `${slug}.agent.md`;
       if (!options.dryRun) {
-        await writeFile3(
+        await writeFile4(
           join2(agentsDir, fileName),
           renderCopilotAgent(def, displayName),
           "utf8"
@@ -1777,7 +1786,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   const arcaneDir = join3(targetDir, ".arcane", "agents");
   if (!options.dryRun) {
     await mkdir3(arcaneDir, { recursive: true });
-    await writeFile4(
+    await writeFile5(
       join3(targetDir, ".arcane", "agents.yaml"),
       stringify(roster),
       "utf8"
@@ -1921,7 +1930,7 @@ async function runAgentsList(targetDir) {
 }
 
 // src/modules/push-safety.ts
-import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile5, chmod, access as access3, rm as rm2, readdir as readdir3 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile6, chmod, access as access3, rm as rm2, readdir as readdir3 } from "fs/promises";
 import { constants } from "fs";
 import { join as join4, resolve, dirname, basename } from "path";
 
@@ -2261,7 +2270,7 @@ async function installHook(cwd, hookName, body) {
     return { status: "already-ours" };
   }
   await mkdir4(join4(root, ARCANE_HOOKS_DIR), { recursive: true });
-  await writeFile5(hookPath, body, "utf-8");
+  await writeFile6(hookPath, body, "utf-8");
   await chmod(hookPath, 493);
   await runGit(cwd, ["config", "--local", "core.hooksPath", await hooksPathValue(cwd)]);
   return { status: "installed", path: hookPath };
@@ -2296,7 +2305,7 @@ async function hookFileMatches(cwd, hookName, body) {
   const hookPath = await hookFilePath(cwd, hookName);
   if (!await fileExists(hookPath)) return false;
   try {
-    if (await readFile4(hookPath, "utf-8") !== body) return false;
+    if (await readFile5(hookPath, "utf-8") !== body) return false;
   } catch {
     return false;
   }
@@ -2755,13 +2764,14 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
   let fileCount = 0;
   for (const component of components) {
     const installedFiles = [];
+    const fileHashes = {};
     for (const file of component.files) {
       const srcPath = join5(assetsDir, component.sourceOverrides?.[file] ?? file);
       if (options.dryRun) {
         printDryRun(`Would copy: ${file}`);
       } else {
         try {
-          await copyFile(srcPath, targetDir, file, { force: options.force });
+          fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: options.force });
         } catch (err) {
           if (component.skipExisting && err instanceof Error && err.message.includes("already exists")) {
             continue;
@@ -2778,7 +2788,10 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
         printDryRun(`Would copy directory: ${dir}/`);
       } else {
         const copied = await copyDirectory(srcDirPath, targetDir, dir, { force: options.force });
-        installedFiles.push(...copied);
+        for (const { path: copiedPath, hash } of copied) {
+          installedFiles.push(copiedPath);
+          fileHashes[copiedPath] = hash;
+        }
         fileCount += copied.length;
       }
     }
@@ -2786,7 +2799,8 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
       installedComponents.push({
         name: component.name,
         files: installedFiles,
-        installedVersion: packageVersion
+        installedVersion: packageVersion,
+        fileHashes
       });
     }
   }
@@ -3067,12 +3081,13 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   }
   let fileCount = 0;
   const installedFiles = [];
+  const fileHashes = {};
   for (const file of component.files) {
     const srcPath = join6(assetsDir, component.sourceOverrides?.[file] ?? file);
     if (options.dryRun) {
       console.log(`  [dry-run] Would copy: ${file}`);
     } else {
-      await copyFile(srcPath, targetDir, file, { force: options.force });
+      fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: options.force });
     }
     installedFiles.push(file);
     fileCount++;
@@ -3083,7 +3098,10 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
       console.log(`  [dry-run] Would copy directory: ${dir}/`);
     } else {
       const copied = await copyDirectory(srcDirPath, targetDir, dir, { force: options.force });
-      installedFiles.push(...copied);
+      for (const { path: copiedPath, hash } of copied) {
+        installedFiles.push(copiedPath);
+        fileHashes[copiedPath] = hash;
+      }
       fileCount += copied.length;
     }
   }
@@ -3097,7 +3115,8 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
   const newComponent = {
     name,
     files: installedFiles,
-    installedVersion: packageVersion
+    installedVersion: packageVersion,
+    fileHashes
   };
   const updated = addComponent(manifest, newComponent);
   await writeManifest(targetDir, updated);
@@ -3109,10 +3128,11 @@ async function runAdd(name, options, targetDir, assetsDir, packageVersion) {
 
 // src/commands/update.ts
 import { join as join8 } from "path";
+import { readFile as readFile6, writeFile as writeFile8, rm as rm3 } from "fs/promises";
 
 // src/modules/hub.ts
 import { confirm as confirm2, select as select3, input as input3 } from "@inquirer/prompts";
-import { readdir as readdir4, writeFile as writeFile6 } from "fs/promises";
+import { readdir as readdir4, writeFile as writeFile7 } from "fs/promises";
 import { join as join7 } from "path";
 var MANIFEST_RETROFITS = [
   {
@@ -3292,12 +3312,154 @@ async function offerRegistryScaffold(targetDir, businessRoot) {
     updated: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
     ventures
   };
-  await writeFile6(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
+  await writeFile7(registryPath, JSON.stringify(registry, null, 2) + "\n", "utf-8");
   console.log(
     `  \u2713 Scaffolded ${businessRoot}/registry.json with ${Object.keys(ventures).length} venture(s).`
   );
 }
 
+// src/modules/merge3.ts
+var CONFLICT_START = "<<<<<<< yours (edited)";
+var CONFLICT_MID = "=======";
+var CONFLICT_END = ">>>>>>> incoming (vendor update)";
+function computeLcsDiff(base, other) {
+  const n = base.length;
+  const m = other.length;
+  const dp = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = base[i2] === other[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  let pendingBaseStart = 0;
+  let pendingOtherStart = 0;
+  const flushReplace = (baseEnd, otherEnd) => {
+    if (baseEnd > pendingBaseStart || otherEnd > pendingOtherStart) {
+      ops.push({
+        type: "replace",
+        baseStart: pendingBaseStart,
+        baseEnd,
+        otherStart: pendingOtherStart,
+        otherEnd
+      });
+    }
+  };
+  while (i < n && j < m) {
+    if (base[i] === other[j]) {
+      flushReplace(i, j);
+      const eqBaseStart = i;
+      const eqOtherStart = j;
+      while (i < n && j < m && base[i] === other[j]) {
+        i++;
+        j++;
+      }
+      ops.push({ type: "equal", baseStart: eqBaseStart, baseEnd: i, otherStart: eqOtherStart, otherEnd: j });
+      pendingBaseStart = i;
+      pendingOtherStart = j;
+    } else if (dp[i + 1][j] >= dp[i][j + 1]) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  flushReplace(n, m);
+  return ops;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  return a.every((line, idx) => line === b[idx]);
+}
+var MAX_LINES_FOR_LCS = 4e3;
+function splitLines(text) {
+  return text.split("\n");
+}
+function merge3(base, ours, theirs) {
+  const baseLines = splitLines(base);
+  const oursLines = splitLines(ours);
+  const theirsLines = splitLines(theirs);
+  if (baseLines.length > MAX_LINES_FOR_LCS || oursLines.length > MAX_LINES_FOR_LCS || theirsLines.length > MAX_LINES_FOR_LCS) {
+    return {
+      content: [CONFLICT_START, ours, CONFLICT_MID, theirs, CONFLICT_END].join("\n"),
+      hasConflict: true
+    };
+  }
+  const oursOps = computeLcsDiff(baseLines, oursLines).filter((op) => op.type === "replace");
+  const theirsOps = computeLcsDiff(baseLines, theirsLines).filter((op) => op.type === "replace");
+  if (oursOps.length === 0 && theirsOps.length === 0) {
+    return { content: base, hasConflict: false };
+  }
+  const intervals = [
+    ...oursOps.map((op) => ({
+      baseStart: op.baseStart,
+      baseEnd: op.baseEnd,
+      source: "ours",
+      lines: oursLines.slice(op.otherStart, op.otherEnd)
+    })),
+    ...theirsOps.map((op) => ({
+      baseStart: op.baseStart,
+      baseEnd: op.baseEnd,
+      source: "theirs",
+      lines: theirsLines.slice(op.otherStart, op.otherEnd)
+    }))
+  ].sort((a, b) => a.baseStart - b.baseStart || a.baseEnd - b.baseEnd);
+  const groups = [];
+  let groupMaxEnd = -1;
+  for (const iv of intervals) {
+    const current = groups[groups.length - 1];
+    if (current && iv.baseStart < groupMaxEnd) {
+      current.push(iv);
+      groupMaxEnd = Math.max(groupMaxEnd, iv.baseEnd);
+    } else {
+      groups.push([iv]);
+      groupMaxEnd = iv.baseEnd;
+    }
+  }
+  const resultLines = [];
+  let hasConflict = false;
+  let basePos = 0;
+  for (const group of groups) {
+    const groupStart = Math.min(...group.map((g) => g.baseStart));
+    const groupEnd = Math.max(...group.map((g) => g.baseEnd));
+    resultLines.push(...baseLines.slice(basePos, groupStart));
+    const oursInGroup = group.filter((g) => g.source === "ours");
+    const theirsInGroup = group.filter((g) => g.source === "theirs");
+    if (oursInGroup.length > 0 && theirsInGroup.length === 0) {
+      for (const g of oursInGroup) resultLines.push(...g.lines);
+    } else if (theirsInGroup.length > 0 && oursInGroup.length === 0) {
+      for (const g of theirsInGroup) resultLines.push(...g.lines);
+    } else {
+      const oursGroupLines = oursInGroup.flatMap((g) => g.lines);
+      const theirsGroupLines = theirsInGroup.flatMap((g) => g.lines);
+      if (arraysEqual(oursGroupLines, theirsGroupLines)) {
+        resultLines.push(...oursGroupLines);
+      } else {
+        hasConflict = true;
+        resultLines.push(CONFLICT_START, ...oursGroupLines, CONFLICT_MID, ...theirsGroupLines, CONFLICT_END);
+      }
+    }
+    basePos = groupEnd;
+  }
+  resultLines.push(...baseLines.slice(basePos));
+  return { content: resultLines.join("\n"), hasConflict };
+}
+
+// src/modules/npm-registry.ts
+var NPM_PACKAGE_NAME = "arcane-cli";
+async function fetchPublishedFile(version, relativeAssetPath) {
+  const normalized = relativeAssetPath.replace(/\\/g, "/").replace(/^\/+/, "");
+  const url = `https://unpkg.com/${NPM_PACKAGE_NAME}@${version}/dist/assets/${normalized}`;
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return void 0;
+    return await response.text();
+  } catch {
+    return void 0;
+  }
+}
+
 // src/commands/update.ts
 function migrateLegacyComponents(components) {
   const out = [];
@@ -3318,6 +3480,23 @@ function migrateLegacyComponents(components) {
   }
   return out;
 }
+async function resolveOrphan(targetDir, file, recordedHash, prune) {
+  const filePath = join8(targetDir, file);
+  if (!await fileExists(filePath)) return "not-found";
+  if (!prune) return "reported";
+  if (recordedHash === void 0) {
+    console.log(`  ! Orphaned, not pruned (no recorded hash to verify it's untouched): ${file}`);
+    return "reported";
+  }
+  const currentHash = await hashFile(filePath);
+  if (currentHash !== recordedHash) {
+    console.log(`  ! Orphaned but edited since install \u2014 not pruning: ${file}`);
+    return "reported";
+  }
+  await rm3(filePath, { force: true });
+  console.log(`  Pruned orphaned file: ${file}`);
+  return "pruned";
+}
 async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -3370,6 +3549,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   }
   let fileCount = 0;
   const updatedComponents = [];
+  const conflictedFiles = [];
+  const orphanReport = [];
   const componentsToUpdate = migrateLegacyComponents(manifest.components);
   for (const installed of componentsToUpdate) {
     let component;
@@ -3378,12 +3559,25 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     } catch (err) {
       if (err instanceof ComponentNotFoundError) {
         console.log(`  ! ${installed.name} not in registry \u2014 skipping.`);
+        for (const file of installed.files) {
+          const status = await resolveOrphan(
+            targetDir,
+            file,
+            installed.fileHashes?.[file],
+            Boolean(options.prune) && !options.dryRun
+          );
+          orphanReport.push({ file, status });
+        }
+        if (options.prune && !options.dryRun && installed.files.every((f) => orphanReport.find((o) => o.file === f)?.status !== "reported")) {
+          continue;
+        }
         updatedComponents.push(installed);
         continue;
       }
       throw err;
     }
     const updatedFiles = [];
+    const fileHashes = {};
     for (const file of component.files) {
       const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
       const targetExists = await fileExists(join8(targetDir, file));
@@ -3400,7 +3594,38 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         console.log(`  [dry-run] Would update: ${file}`);
         fileCount++;
       } else {
-        await copyFile(srcPath, targetDir, file, { force: true });
+        const recordedHash = installed.fileHashes?.[file];
+        let handled = false;
+        if (recordedHash !== void 0 && targetExists) {
+          const currentHash = await hashFile(join8(targetDir, file));
+          if (currentHash !== recordedHash) {
+            const oldVendorContent = await fetchPublishedFile(installed.installedVersion, file);
+            if (oldVendorContent === void 0) {
+              console.log(
+                `  ! Could not fetch the previously published version of ${file} to merge your edits \u2014 left your version untouched. Update it manually if you want the latest.`
+              );
+              handled = true;
+            } else {
+              const [currentContent, newContent] = await Promise.all([
+                readFile6(join8(targetDir, file), "utf-8"),
+                readFile6(srcPath, "utf-8")
+              ]);
+              const result = merge3(oldVendorContent, currentContent, newContent);
+              await writeFile8(join8(targetDir, file), result.content, "utf-8");
+              fileHashes[file] = await hashFile(join8(targetDir, file));
+              if (result.hasConflict) {
+                conflictedFiles.push(file);
+                console.log(`  \u26A0 Merge conflict in ${file} \u2014 resolve the <<<<<<< markers before committing.`);
+              } else {
+                console.log(`  Merged your edits into: ${file}`);
+              }
+              handled = true;
+            }
+          }
+        }
+        if (!handled) {
+          fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: true });
+        }
         fileCount++;
       }
       if (!preserveExisting || installed.files.includes(file)) {
@@ -3413,16 +3638,45 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         console.log(`  [dry-run] Would update directory: ${dir}/`);
       } else {
         const copied = await copyDirectory(srcDirPath, targetDir, dir, { force: true });
-        updatedFiles.push(...copied);
+        for (const { path: copiedPath, hash } of copied) {
+          updatedFiles.push(copiedPath);
+          fileHashes[copiedPath] = hash;
+        }
         fileCount += copied.length;
       }
     }
+    for (const file of installed.files) {
+      if (updatedFiles.includes(file)) continue;
+      const status = await resolveOrphan(
+        targetDir,
+        file,
+        installed.fileHashes?.[file],
+        Boolean(options.prune) && !options.dryRun
+      );
+      orphanReport.push({ file, status });
+    }
     updatedComponents.push({
       ...installed,
       files: updatedFiles,
-      installedVersion: packageVersion
+      installedVersion: packageVersion,
+      fileHashes
     });
   }
+  const orphansToReport = orphanReport.filter((o) => o.status !== "not-found");
+  if (orphansToReport.length > 0) {
+    const verb = options.dryRun ? "[dry-run] Found" : "Found";
+    console.log(
+      `
+${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update, no longer part of any current component):`
+    );
+    for (const { file, status } of orphansToReport) {
+      const marker = status === "pruned" ? "pruned" : options.prune ? "kept (see reason above)" : "not removed";
+      console.log(`    ${file} \u2014 ${marker}`);
+    }
+    if (!options.prune) {
+      console.log("  Run `spell update --prune` to remove the ones that are safe to delete.");
+    }
+  }
   if (options.dryRun) {
     console.log(
       `
@@ -3457,13 +3711,21 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     `
 \u2713 Updated ${fileCount} files.`
   );
+  if (conflictedFiles.length > 0) {
+    console.log(
+      `
+\u26A0 ${conflictedFiles.length} file(s) have unresolved merge conflicts:
+` + conflictedFiles.map((f) => `    ${f}`).join("\n") + `
+  Search for "<<<<<<< yours" and resolve before committing.`
+    );
+  }
   if (manifest.role !== "hub" && updated.role === "hub") {
     await offerRegistryScaffold(targetDir, updated.business_root ?? "ventures");
   }
 }
 
 // src/modules/version-check.ts
-import { readFile as readFile5, writeFile as writeFile7, mkdir as mkdir5 } from "fs/promises";
+import { readFile as readFile7, writeFile as writeFile9, mkdir as mkdir5 } from "fs/promises";
 import { dirname as dirname2, join as join9 } from "path";
 import { homedir as homedir2 } from "os";
 import { createRequire } from "module";
@@ -3482,7 +3744,7 @@ var DEFAULT_CACHE_PATH = join9(homedir2(), ".arcane", "version-cache.json");
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 async function readCache(cachePath) {
   try {
-    const content = await readFile5(cachePath, "utf-8");
+    const content = await readFile7(cachePath, "utf-8");
     const parsed = JSON.parse(content);
     if (typeof parsed.latest !== "string" || typeof parsed.checkedAt !== "string") {
       return null;
@@ -3495,7 +3757,7 @@ async function readCache(cachePath) {
 async function writeCache(cachePath, latest) {
   await mkdir5(dirname2(cachePath), { recursive: true });
   const entry = { latest, checkedAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await writeFile7(cachePath, JSON.stringify(entry, null, 2), "utf-8");
+  await writeFile9(cachePath, JSON.stringify(entry, null, 2), "utf-8");
 }
 async function getLatestVersion(feedUrl) {
   const normalizedBase = feedUrl.endsWith("/") ? feedUrl : feedUrl + "/";
@@ -3654,7 +3916,7 @@ async function runStatus(targetDir, packageVersion) {
 }
 
 // src/commands/uninstall.ts
-import { rm as rm3 } from "fs/promises";
+import { rm as rm4 } from "fs/promises";
 import { join as join10 } from "path";
 import { confirm as confirm3 } from "@inquirer/prompts";
 async function runUninstall(options, targetDir) {
@@ -3720,22 +3982,22 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
     for (const file of component.files) {
       const filePath = join10(targetDir, file);
       try {
-        await rm3(filePath, { force: true });
+        await rm4(filePath, { force: true });
         removed++;
       } catch {
       }
     }
   }
-  await rm3(join10(targetDir, ".arcane.json"), { force: true });
+  await rm4(join10(targetDir, ".arcane.json"), { force: true });
   const agentDirs = [
     ".github/agents",
     ".arcane/agents",
     ".arcane/generated"
   ];
   for (const dir of agentDirs) {
-    await rm3(join10(targetDir, dir), { recursive: true, force: true });
+    await rm4(join10(targetDir, dir), { recursive: true, force: true });
   }
-  await rm3(join10(targetDir, ".arcane/agents.yaml"), { force: true });
+  await rm4(join10(targetDir, ".arcane/agents.yaml"), { force: true });
   const markerFiles = [
     "CLAUDE.md",
     "AGENTS.md",
@@ -3753,7 +4015,7 @@ Run \`spell unblock-push\` first (interactive), then uninstall.`
 }
 
 // src/commands/doctor.ts
-import { access as access4, readFile as readFile7, mkdir as mkdir6, copyFile as fsCopyFile2 } from "fs/promises";
+import { access as access4, readFile as readFile9, mkdir as mkdir6, copyFile as fsCopyFile } from "fs/promises";
 import { join as join12, dirname as dirname3 } from "path";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify2 } from "util";
@@ -3824,7 +4086,7 @@ function evaluateIncidentGate(records) {
 }
 
 // src/modules/denylist-scan.ts
-import { readFile as readFile6, readdir as readdir5 } from "fs/promises";
+import { readFile as readFile8, readdir as readdir5 } from "fs/promises";
 import { join as join11, relative } from "path";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -3842,7 +4104,7 @@ async function scanFile(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile6(absolutePath, "utf8");
+    content = await readFile8(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -4129,7 +4391,7 @@ async function checkArcaneManifest(targetDir) {
   } catch {
     const selfHostedManifestPath = join12(targetDir, "src", "assets", ".arcane.json");
     try {
-      const raw = await readFile7(selfHostedManifestPath, "utf8");
+      const raw = await readFile9(selfHostedManifestPath, "utf8");
       const manifest = JSON.parse(raw);
       if (isRecord3(manifest) && manifest["selfHosted"] === true && manifest["tracking_mode"] === "internal") {
         return {
@@ -4148,7 +4410,7 @@ async function checkArcaneManifest(targetDir) {
     };
   }
   try {
-    const raw = await readFile7(manifestPath2, "utf8");
+    const raw = await readFile9(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
     if (!isRecord3(manifest) || typeof manifest["version"] !== "string" || !manifest["version"] || !Array.isArray(manifest["components"])) {
       return {
@@ -4257,7 +4519,7 @@ async function fixSessionContinuity(targetDir, assetsDir) {
     } catch {
       const srcPath = join12(assetsDir, file);
       await mkdir6(dirname3(destPath), { recursive: true });
-      await fsCopyFile2(srcPath, destPath);
+      await fsCopyFile(srcPath, destPath);
       created.push(file);
     }
   }
@@ -4319,7 +4581,7 @@ async function checkMcpConfig(targetDir) {
   const filePath = join12(targetDir, ".mcp.json");
   let raw;
   try {
-    raw = await readFile7(filePath, "utf8");
+    raw = await readFile9(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no .mcp.json \u2014 nothing to check" };
   }
@@ -4375,7 +4637,7 @@ async function checkDelegations(targetDir) {
   const filePath = join12(targetDir, ".arcane", "delegations.json");
   let raw;
   try {
-    raw = await readFile7(filePath, "utf8");
+    raw = await readFile9(filePath, "utf8");
   } catch {
     return { name, passed: true, blocking: false, message: "no delegations recorded" };
   }
@@ -4523,13 +4785,13 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 }
 
 // src/modules/ward.ts
-import { readdir as readdir6, readFile as readFile8 } from "fs/promises";
+import { readdir as readdir6, readFile as readFile10 } from "fs/promises";
 import { join as join13, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
   let content;
   try {
-    content = await readFile8(absolutePath, "utf8");
+    content = await readFile10(absolutePath, "utf8");
   } catch {
     return findings;
   }
@@ -4624,7 +4886,7 @@ async function runWard(repoRoot, options = {}) {
     const findings2 = await scanFileAllRules(absolutePath, displayPath, allRules);
     if (findings2.length > 0) {
       try {
-        fileLines.set(displayPath, (await readFile8(absolutePath, "utf8")).split("\n"));
+        fileLines.set(displayPath, (await readFile10(absolutePath, "utf8")).split("\n"));
       } catch {
       }
     }
@@ -4833,9 +5095,12 @@ program.command("add <component>").description("Add a component to an existing A
     );
   }
 );
-program.command("update").description("Update installed components to the current package version").option("--dry-run", "Preview what would be updated without making changes").action(async (opts) => {
+program.command("update").description("Update installed components to the current package version").option("--dry-run", "Preview what would be updated without making changes").option(
+  "--prune",
+  "Also delete orphaned managed files (tracked before this update, no longer part of any current component). Hash-checked: an edited file is reported, never silently deleted"
+).action(async (opts) => {
   await runUpdate(
-    { dryRun: opts.dryRun },
+    { dryRun: opts.dryRun, prune: opts.prune },
     process.cwd(),
     ASSETS_DIR,
     pkg.version