arcane-cli 1.10.2 → 1.11.0

package/README.md

@@ -221,7 +221,7 @@ spell add agent-policies   # or install any component à la carte
 spell add spells-build compliance-standards   # or several, in order
 ```
 
-`spell add` takes one or more names. It checks each component's files before writing any of them: if one already exists, it prints one line naming the file and `--force`, exits 1, and writes nothing from that component. With several names it stops at the first failure and says which were added and which were not attempted; a name that is already installed is skipped. A component that keeps your own file (`.mcp.json`) leaves an existing one alone and creates a missing one. `--dry-run` lists each file as identical, differing or missing, or as one that would be kept or refused, and writes nothing.
+`spell add` takes one or more names. It checks each component's files before writing any of them: if one already exists, it prints one line naming the file and `--force`, exits 1, and writes nothing from that component. With several names it stops at the first failure and says which were added and which were not attempted; a name that is already installed is skipped. A component that keeps your own file (`.gitattributes`, for example) leaves an existing one alone and creates a missing one. `--dry-run` lists each file as identical, differing or missing, or as one that would be kept or refused, and writes nothing.
 
 ### What `spell update` installs
 

package/dist/assets/.arcane/governance/git-conventions.md

@@ -486,8 +486,14 @@ reported in output so a human sees it happened. The known-issues rows below (`MC
 `MCP create_pull_request`) are concrete instances of this general rule, not special cases of their own.
 **Consumer hardening:** set a per-server `"timeout"` (milliseconds) in `.mcp.json` so a hang aborts on a
 predictable schedule instead of running to the client's own default idle limit (as long as 30 minutes).
+In Claude Code the value goes inside each server's entry under `mcpServers` — `"timeout": 30000` is 30
+seconds — and must be 1000 or more; a smaller value is ignored (Claude Code MCP docs, checked 2026-10-02;
+other clients have their own keys, so check theirs before copying this one). `spell doctor` warns on an
+entry without one and never edits the file: `.mcp.json` is yours. Arcane ships no example `.mcp.json` —
+the `mcp-config-template` scaffold was retired on 2026-10-02 because a root `.mcp.json` is live
+configuration that clients execute, not documentation, and its placeholder server failed on every session start.
 Origin: a real ops session lost roughly an hour to two consecutive 30-minute MCP hangs before the
-documented `az` fallback was used (2026-08-14). **Enforcement: explicitly advisory prose (ARC-023) — this fail-fast behavior and the `.mcp.json` timeout hardening both depend on the acting agent actually following them; no check in this repo verifies an agent stopped retrying a downed MCP server or that a given `.mcp.json` entry sets a timeout.**
+documented `az` fallback was used (2026-08-14). **Enforcement: explicitly advisory prose (ARC-023) for the fail-fast behavior — no check in this repo verifies an agent stopped retrying a downed MCP server. The timeout hardening has an advisory check: `spell doctor`'s "MCP config (per-server timeout, I12)" row warns on a `.mcp.json` entry without a `"timeout"` (exit code unchanged) and edits nothing.**
 
 **Known issues:**
 

package/dist/index.js

@@ -579,15 +579,10 @@ var COMPONENTS = [
     skipExisting: true,
     initOnly: true
   },
-  // Optional MCP config scaffold (BC-22/I12). skipExisting: a repo's own
-  // .mcp.json is user-owned server config Arcane must never overwrite.
-  // Not initOnly -- useful to retrofit via `spell add` on an existing repo too.
-  {
-    name: "mcp-config-template",
-    description: "Example .mcp.json with a per-server timeout, companion to the MCP fail-fast rule",
-    files: [".mcp.json"],
-    skipExisting: true
-  },
+  // NOTE: the `mcp-config-template` component (`.mcp.json`, BC-22/I12) was
+  // retired on 2026-10-02 -- see REGISTRY_RETIREMENTS. A root .mcp.json is
+  // live MCP config that clients execute, and the `full` profile's "*" put
+  // its example server in every full-profile repo (#328).
   {
     name: "records-conventions",
     description: "Supersession, tombstone, and retention conventions for records repositories",
@@ -937,6 +932,13 @@ var REGISTRY_RETIREMENTS = [
     successors: [],
     reason: "`.github/agents/*.agent.md` files are rendered per roster by `spell agents init` / `spell agents sync` (ARC-047), which a fixed-path component cannot do"
   },
+  {
+    name: "mcp-config-template",
+    kind: "component",
+    successors: [],
+    userOwned: true,
+    reason: "retired 2026-10-02 (#328): a root .mcp.json is live MCP config that clients execute, and the `full` profile installed its example server everywhere; set per-server timeouts in your own .mcp.json, which `spell doctor` checks"
+  },
   {
     name: "spell-prompts",
     kind: "component",
@@ -4803,7 +4805,8 @@ function formatRegistryChanges(changes) {
     lines.push("  Renamed or retired, still tracked here:");
     for (const entry of changes.retired) {
       const successor = entry.successors.length > 0 ? entry.successors.join(", ") : "no successor";
-      lines.push(`    ${entry.name} (${entry.kind}) \u2192 ${successor}: ${entry.reason}`);
+      const ownership = entry.userOwned ? " (user-owned: a copy you edited is released from tracking, never deleted)" : "";
+      lines.push(`    ${entry.name} (${entry.kind}) \u2192 ${successor}: ${entry.reason}${ownership}`);
     }
     lines.push(
       "    Nothing is deleted because of this list: their files go through the orphan handling above, which removes an untouched one only under `spell update --prune`."
@@ -5058,6 +5061,17 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
+async function isReleasableUserOwnedFile(targetDir, file, recordedHash) {
+  try {
+    validateTargetPath(targetDir, file);
+  } catch {
+    return false;
+  }
+  const filePath = join10(targetDir, file);
+  if (!await fileExists(filePath)) return false;
+  if (recordedHash === void 0) return true;
+  return !await fileMatchesHash(filePath, recordedHash);
+}
 async function retainReportedOrphan(targetDir, file, recordedHash, into) {
   try {
     validateTargetPath(targetDir, file);
@@ -5332,14 +5346,36 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     } catch (err) {
       if (err instanceof ComponentNotFoundError) {
         console.log(`  ! ${installed.name} not in registry \u2014 skipping.`);
+        const userOwned = REGISTRY_RETIREMENTS.some(
+          (r) => r.kind === "component" && r.name === installed.name && r.userOwned === true
+        );
+        const stillTracked = [];
         for (const file of installed.files) {
+          const recordedHash = installed.fileHashes?.[file];
+          if (userOwned && await isReleasableUserOwnedFile(targetDir, file, recordedHash)) {
+            console.log(
+              `  ${options.dryRun ? "[dry-run] Would release" : "Released"}: ${file} \u2014 yours (edited since Arcane wrote it, or never written by Arcane), no longer tracked. Delete it yourself if you do not want it.`
+            );
+            continue;
+          }
           const status = await resolveOrphan(
             targetDir,
             file,
-            installed.fileHashes?.[file],
+            recordedHash,
             Boolean(options.prune) && !options.dryRun
           );
           orphanReport.push({ file, status });
+          if (status === "reported") stillTracked.push(file);
+        }
+        if (userOwned && !options.dryRun) {
+          if (stillTracked.length === 0) continue;
+          const fileHashes2 = {};
+          for (const file of stillTracked) {
+            const hash = installed.fileHashes?.[file];
+            if (hash !== void 0) fileHashes2[file] = hash;
+          }
+          updatedComponents.push({ ...installed, files: stillTracked, fileHashes: fileHashes2 });
+          continue;
         }
         if (options.prune && !options.dryRun && installed.files.every((f) => orphanReport.find((o) => o.file === f)?.status !== "reported")) {
           continue;
@@ -6837,6 +6873,7 @@ async function checkGovernancePlaceholders(targetDir) {
   };
 }
 var UNOWNED_EXAMPLE_SCOPE = "@example/";
+var RETIRED_SCAFFOLD_PLACEHOLDER = "<your-mcp-server-package>";
 async function checkComponentRequires(targetDir) {
   const name = "Component prerequisites";
   let manifest;
@@ -6927,11 +6964,14 @@ async function checkMcpConfig(targetDir) {
     return { name, passed: true, blocking: false, message: "no MCP servers configured" };
   }
   const exampleHits = [];
+  const placeholderHits = [];
   for (const n of serverNames) {
     const args = servers[n]?.args;
     if (!Array.isArray(args)) continue;
     for (const a of args) {
-      if (typeof a === "string" && a.startsWith(UNOWNED_EXAMPLE_SCOPE)) exampleHits.push(`${n} (${a})`);
+      if (typeof a !== "string") continue;
+      if (a.startsWith(UNOWNED_EXAMPLE_SCOPE)) exampleHits.push(`${n} (${a})`);
+      if (a === RETIRED_SCAFFOLD_PLACEHOLDER) placeholderHits.push(n);
     }
   }
   if (exampleHits.length > 0) {
@@ -6942,13 +6982,21 @@ async function checkMcpConfig(targetDir) {
       message: `.mcp.json runs a package under the ${UNOWNED_EXAMPLE_SCOPE} scope nobody here owns: ${exampleHits.join(", ")}. The old \`spell init\` scaffold shipped it as a placeholder, and \`npx -y\` would run whoever publishes it. Replace the entry with your own MCP server package, or remove it; the file is yours, so doctor does not edit it`
     };
   }
+  if (placeholderHits.length > 0) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `.mcp.json still holds the placeholder server from the retired mcp-config-template scaffold: ${placeholderHits.join(", ")} (${RETIRED_SCAFFOLD_PLACEHOLDER}). Clients load this file as live MCP config, so the placeholder fails on every session start. Delete the file if you run no MCP servers, or replace the entry with a real server package; the file is yours, so doctor does not edit it. An untouched scaffold is removed by \`spell update --prune\``
+    };
+  }
   const missingTimeout = serverNames.filter((n) => typeof servers[n]?.timeout !== "number");
   if (missingTimeout.length > 0) {
     return {
       name,
       passed: false,
       blocking: false,
-      message: `server(s) missing a "timeout": ${missingTimeout.join(", ")} \u2014 a hang runs to the client's own default idle limit (up to 30 min) instead of a predictable one`
+      message: `server(s) missing a "timeout": ${missingTimeout.join(", ")} \u2014 add "timeout": 30000 (milliseconds; Claude Code ignores a value below 1000) to each entry under mcpServers, so a stuck tool call ends after 30 s instead of running to the client's own idle limit (as long as 30 minutes)`
     };
   }
   return {