claude-code-arcane 2.9.1 → 2.9.3

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.9.3](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.2...v2.9.3) (2026-09-07)
+
+
+### Bug Fixes
+
+* **update:** resolve the content version once per run, never fabricate it ([ef78ecf](https://github.com/SebastianLuser/claude-code-arcane/commit/ef78ecf6c5ab17f1a51ea6ae27ef9fa161594798))
+
+## [2.9.2](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.1...v2.9.2) (2026-09-07)
+
+
+### Bug Fixes
+
+* **update:** only remove content the manifest owns ([d6eec05](https://github.com/SebastianLuser/claude-code-arcane/commit/d6eec05475bb491c8853078d9920c7dc4544e7b3))
+
 ## [2.9.1](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.0...v2.9.1) (2026-09-04)
 
 

package/dist/cli.js

@@ -742,6 +742,7 @@ function computeContentHashes(claudeDir) {
   const skillsDir = path7.join(claudeDir, "skills");
   if (fs6.existsSync(skillsDir)) {
     for (const entry of fs6.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (entry.name.startsWith("_")) continue;
       if (entry.isDirectory()) {
         const dirHash = hashDirectory(path7.join(skillsDir, entry.name));
         const combined = createHash("sha256").update(JSON.stringify(dirHash)).digest("hex");
@@ -1438,22 +1439,18 @@ var GitHubContentSource = class {
       fs9.rmSync(tmpDir, { recursive: true, force: true });
     }
   }
-  async isAvailable() {
-    try {
-      const response = await fetch(
-        `https://api.github.com/repos/${this.owner}/${this.repo}/commits/${this.branch}`,
-        {
-          method: "HEAD",
-          headers: { "User-Agent": "arcane-cli" },
-          signal: AbortSignal.timeout(5e3)
-        }
-      );
-      return response.ok;
-    } catch {
-      return false;
-    }
-  }
-  async getVersion() {
+  /**
+   * The head commit of the branch, or null when GitHub cannot answer.
+   *
+   * One request, memoized, shared by isAvailable() and getVersion(). It used to be
+   * two - a HEAD to answer "is it reachable?" and a GET to read the sha - against an
+   * endpoint that allows 60 requests an hour unauthenticated. That doubled the cost of
+   * every resolution and, worse, opened a window between the two calls: the HEAD spent
+   * the last request of the hour, the GET came back 403, and the caller had already
+   * committed to the github source. That window is where the fabricated versions came
+   * from.
+   */
+  async resolveVersion() {
     if (this.resolvedVersion) return this.resolvedVersion;
     try {
       const response = await fetch(
@@ -1466,17 +1463,36 @@ var GitHubContentSource = class {
           signal: AbortSignal.timeout(1e4)
         }
       );
-      if (!response.ok) {
-        throw new Error(`GitHub API returned ${response.status}`);
-      }
+      if (!response.ok) return null;
       const data = await response.json();
       this.resolvedVersion = data.sha.substring(0, 12);
       return this.resolvedVersion;
     } catch {
-      this.resolvedVersion = `github-${Date.now()}`;
-      return this.resolvedVersion;
+      return null;
     }
   }
+  async isAvailable() {
+    return await this.resolveVersion() !== null;
+  }
+  /**
+   * Throws when the version cannot be read, rather than inventing one.
+   *
+   * It used to answer `github-${Date.now()}` on any failure, and that string went on to
+   * be an identity: it stamped `source_version` in the manifest, named a cache directory,
+   * and made the install permanently un-diffable against any real version - it never
+   * matched again, so every later run reported an update and no run ever settled. A
+   * transient 403 became durable state on disk. Callers that cannot proceed without a
+   * version now fall back to the cache, which knows a real one.
+   */
+  async getVersion() {
+    const version = await this.resolveVersion();
+    if (!version) {
+      throw new Error(
+        "Could not read the content version from GitHub (offline, or the unauthenticated API rate limit is exhausted - it resets hourly)."
+      );
+    }
+    return version;
+  }
   async downloadAndExtract(destDir) {
     const tarballUrl = `https://api.github.com/repos/${this.owner}/${this.repo}/tarball/${this.branch}`;
     const response = await fetch(tarballUrl, {
@@ -1547,7 +1563,9 @@ async function resolveContentSource(opts = {}) {
       return github;
     }
     if (preference === "github") {
-      throw new Error("GitHub source requested but not available. Check your internet connection.");
+      throw new Error(
+        "GitHub source requested but not available. Check your internet connection, or wait for the unauthenticated API rate limit to reset (hourly)."
+      );
     }
     const cached = findLatestCache();
     if (cached) {
@@ -2315,6 +2333,7 @@ function safeVersion() {
 }
 
 // src/commands/update.ts
+var TRASH_DIR = ".arcane-trash";
 async function updateCommand(opts) {
   if (opts.here) {
     await updateTarget(process.cwd(), opts);
@@ -2355,6 +2374,10 @@ async function updateCommand(opts) {
 Updating ${targets.length} installation${targets.length === 1 ? "" : "s"}...`)
     );
   }
+  const sharedSource = await resolveContentSource({
+    source: opts.source ?? "auto",
+    quiet: opts.quiet
+  });
   const results = [];
   for (const target of targets) {
     if (!opts.quiet) {
@@ -2362,7 +2385,7 @@ Updating ${targets.length} installation${targets.length === 1 ? "" : "s"}...`)
 \u2022 ${target}`));
     }
     try {
-      results.push(await updateTarget(target, opts));
+      results.push(await updateTarget(target, opts, sharedSource));
     } catch (err) {
       if (!opts.quiet) {
         console.log(chalk7.red(`  Update failed: ${err.message}`));
@@ -2380,7 +2403,7 @@ Updating ${targets.length} installation${targets.length === 1 ? "" : "s"}...`)
     printGeneralSummary(results, opts.dryRun ?? false);
   }
 }
-async function updateTarget(target, opts) {
+async function updateTarget(target, opts, sharedSource) {
   const manifest = readManifest(target);
   if (!manifest) {
     if (!opts.quiet) {
@@ -2388,7 +2411,7 @@ async function updateTarget(target, opts) {
     }
     return { target, status: "no-manifest", updated: 0, skipped: 0, removed: 0 };
   }
-  const contentSource = await resolveContentSource({
+  const contentSource = sharedSource ?? await resolveContentSource({
     source: opts.source ?? "auto",
     quiet: opts.quiet
   });
@@ -2444,7 +2467,9 @@ Update available: ${chalk7.red(installedVersion)} -> ${chalk7.green(currentVersi
   const items = computeUpdatePlan(
     manifest.content_hashes ?? null,
     installedHashes,
-    sourceHashes
+    sourceHashes,
+    makeOwnershipCheck(manifest),
+    granularAgentDivisions(merged.agents)
   );
   const updates = items.filter((i) => i.action === "update" || i.action === "add" || i.action === "conflict");
   const skipped = items.filter((i) => i.action === "skip-customized" || i.action === "skip-unchanged");
@@ -2459,7 +2484,7 @@ Update available: ${chalk7.red(installedVersion)} -> ${chalk7.green(currentVersi
         arcane_version: currentVersion,
         source_version: currentVersion,
         updated_at: (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
-        content_hashes: installedHashes,
+        content_hashes: stripForeign(installedHashes, items),
         installed_skills: merged.skills,
         installed_rules: allRules,
         installed_agents: merged.agents,
@@ -2500,7 +2525,7 @@ Refreshed ${unhashed.length} file(s); no other changes to apply.`) : chalk7.gree
     arcane_version: currentVersion,
     source_version: currentVersion,
     updated_at: (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
-    content_hashes: newHashes,
+    content_hashes: stripForeign(newHashes, items),
     installed_skills: merged.skills,
     installed_rules: allRules,
     installed_agents: merged.agents,
@@ -2530,7 +2555,56 @@ function printGeneralSummary(results, isDryRun) {
 ${prefix}Done. ${results.length} installation${results.length === 1 ? "" : "s"} processed:`));
   console.log(`  ${chalk7.green(updated)} ${isDryRun ? "would change" : "updated"}, ${chalk7.dim(unchanged + " unchanged")}`);
 }
-function computeUpdatePlan(manifestHashes, installedHashes, sourceHashes) {
+function makeOwnershipCheck(manifest) {
+  const hashes = manifest.content_hashes;
+  if (hashes) {
+    return (type, name) => name in (hashes[type] ?? {});
+  }
+  const skills = new Set(manifest.installed_skills ?? []);
+  const rules = new Set(
+    (manifest.installed_rules ?? []).map((r) => r.endsWith(".md") ? r : `${r}.md`)
+  );
+  const agents = new Set(
+    (manifest.installed_agents ?? []).map((a) => parseAgentEntry(a).division)
+  );
+  return (type, name) => {
+    switch (type) {
+      case "skills":
+        return skills.has(name);
+      case "rules":
+        return rules.has(name);
+      case "agents":
+        return agents.has(name);
+      case "hooks":
+        return true;
+    }
+  };
+}
+function granularAgentDivisions(entries) {
+  const whole = /* @__PURE__ */ new Set();
+  const partial = /* @__PURE__ */ new Set();
+  for (const raw of entries) {
+    const { division, agent } = parseAgentEntry(raw);
+    (agent ? partial : whole).add(division);
+  }
+  for (const division of whole) partial.delete(division);
+  return partial;
+}
+function stripForeign(hashes, items) {
+  const stripped = {
+    skills: { ...hashes.skills },
+    rules: { ...hashes.rules },
+    agents: { ...hashes.agents },
+    hooks: { ...hashes.hooks }
+  };
+  for (const item of items) {
+    if (item.action !== "keep-foreign") continue;
+    const bucket = `${item.type}s`;
+    delete stripped[bucket][item.name];
+  }
+  return stripped;
+}
+function computeUpdatePlan(manifestHashes, installedHashes, sourceHashes, owned, exemptAgentDivisions = /* @__PURE__ */ new Set()) {
   const items = [];
   for (const contentType of ["skills", "rules", "agents", "hooks"]) {
     const itemType = contentType === "skills" ? "skill" : contentType === "rules" ? "rule" : contentType === "agents" ? "agent" : "hook";
@@ -2543,10 +2617,11 @@ function computeUpdatePlan(manifestHashes, installedHashes, sourceHashes) {
       ...Object.keys(source)
     ]);
     for (const key of allKeys) {
+      if (contentType === "agents" && exemptAgentDivisions.has(key)) continue;
       const mHash = manifest[key] ?? null;
       const iHash = installed[key] ?? null;
       const sHash = source[key] ?? null;
-      const action = resolveAction(mHash, iHash, sHash);
+      const action = resolveAction(mHash, iHash, sHash, owned(contentType, key));
       if (action) {
         items.push({ type: itemType, name: key, action });
       }
@@ -2554,12 +2629,13 @@ function computeUpdatePlan(manifestHashes, installedHashes, sourceHashes) {
   }
   return items;
 }
-function resolveAction(manifestHash, installedHash, sourceHash) {
+function resolveAction(manifestHash, installedHash, sourceHash, owned) {
   if (!sourceHash && !installedHash) return null;
   if (sourceHash && !installedHash) return "add";
-  if (!sourceHash && installedHash) return "remove";
+  if (!sourceHash && installedHash) return owned ? "remove" : "keep-foreign";
   if (!manifestHash) {
     if (installedHash === sourceHash) return "skip-unchanged";
+    if (!owned) return "conflict";
     return "update";
   }
   if (manifestHash === installedHash && installedHash === sourceHash) return "skip-unchanged";
@@ -2575,6 +2651,7 @@ function printUpdateSummary(items, isDryRun) {
   const conflicts = items.filter((i) => i.action === "conflict");
   const customized = items.filter((i) => i.action === "skip-customized");
   const removed = items.filter((i) => i.action === "remove");
+  const foreign = items.filter((i) => i.action === "keep-foreign");
   if (updates.length > 0) {
     console.log(`
 ${prefix}${chalk7.cyan("Will update:")}`);
@@ -2591,14 +2668,23 @@ ${prefix}${chalk7.cyan("Will add:")}`);
   }
   if (removed.length > 0) {
     console.log(`
-${prefix}${chalk7.cyan("Will remove:")}`);
+${prefix}${chalk7.cyan("Will remove")} ${chalk7.dim(`(moved to .claude/${TRASH_DIR}/)`)}:`);
     for (const item of removed) {
       console.log(`  ${chalk7.red("-")} ${item.type}: ${item.name}`);
     }
   }
-  if (conflicts.length > 0) {
+  if (foreign.length > 0) {
     console.log(`
-${prefix}${chalk7.yellow("Conflicts (will backup + update):")}`);
+${chalk7.cyan("Left alone")} ${chalk7.dim("(not installed by Arcane)")}:`);
+    for (const item of foreign) {
+      console.log(`  ${chalk7.dim("=")} ${item.type}: ${item.name}`);
+    }
+  }
+  if (conflicts.length > 0) {
+    console.log(
+      `
+${prefix}${chalk7.yellow("Conflicts (will update)")} ${chalk7.dim(`(old copy to .claude/${TRASH_DIR}/)`)}:`
+    );
     for (const item of conflicts) {
       console.log(`  ${chalk7.yellow("!")} ${item.type}: ${item.name}`);
     }
@@ -2613,6 +2699,7 @@ ${prefix}${chalk7.dim("Skipped (locally customized):")}`);
 }
 function applyUpdates(items, root, claudeDir, merged, force) {
   for (const item of items) {
+    if (item.action === "keep-foreign") continue;
     if (item.action === "skip-unchanged" || item.action === "skip-customized") {
       if (item.action === "skip-customized" && force) {
         applyItem(item, root, claudeDir);
@@ -2620,7 +2707,7 @@ function applyUpdates(items, root, claudeDir, merged, force) {
       continue;
     }
     if (item.action === "conflict") {
-      backupItem(item, claudeDir);
+      quarantineItem(item, claudeDir);
       applyItem(item, root, claudeDir);
       continue;
     }
@@ -2629,7 +2716,7 @@ function applyUpdates(items, root, claudeDir, merged, force) {
       continue;
     }
     if (item.action === "remove") {
-      removeItem(item, claudeDir);
+      quarantineItem(item, claudeDir);
     }
   }
 }
@@ -2650,6 +2737,29 @@ function syncUnhashedFiles(root, claudeDir, merged, dryRun) {
       label: `output-styles/${style}.md`
     });
   }
+  for (const raw of merged.agents) {
+    const { division, agent } = parseAgentEntry(raw);
+    if (!agent) continue;
+    targets.push({
+      src: path17.join(root, "agents", division, `${agent}.md`),
+      dst: path17.join(claudeDir, "agents", division, `${agent}.md`),
+      label: `agents/${division}/${agent}.md`
+    });
+  }
+  if (merged.rules.gamedev.length > 0) {
+    const templatesSrc = path17.join(root, "templates", "gamedev");
+    if (fs14.existsSync(templatesSrc)) {
+      for (const rel of fs14.readdirSync(templatesSrc, { recursive: true })) {
+        const src = path17.join(templatesSrc, rel);
+        if (!fs14.statSync(src).isFile()) continue;
+        targets.push({
+          src,
+          dst: path17.join(claudeDir, "skills", "_templates", rel),
+          label: `skills/_templates/${String(rel).split(path17.sep).join("/")}`
+        });
+      }
+    }
+  }
   const changed = [];
   for (const t of targets) {
     if (!fs14.existsSync(t.src)) continue;
@@ -2702,20 +2812,15 @@ function applyItem(item, root, claudeDir) {
     fs14.copyFileSync(src, dst);
   }
 }
-function backupItem(item, claudeDir) {
+function quarantineItem(item, claudeDir) {
   const installed = getInstalledPath(item, claudeDir);
   if (!fs14.existsSync(installed)) return;
-  const backupPath = installed + ".bak";
-  if (fs14.existsSync(backupPath)) {
-    fs14.rmSync(backupPath, { recursive: true, force: true });
-  }
-  fs14.renameSync(installed, backupPath);
-}
-function removeItem(item, claudeDir) {
-  const installed = getInstalledPath(item, claudeDir);
-  if (fs14.existsSync(installed)) {
-    fs14.rmSync(installed, { recursive: true, force: true });
+  const quarantine = path17.join(claudeDir, TRASH_DIR, `${item.type}s`, item.name);
+  ensureDir(path17.dirname(quarantine));
+  if (fs14.existsSync(quarantine)) {
+    fs14.rmSync(quarantine, { recursive: true, force: true });
   }
+  fs14.renameSync(installed, quarantine);
 }
 function getSourcePath(item, root) {
   switch (item.type) {

package/docs/USER-GUIDE.md

@@ -146,10 +146,26 @@ Shows installed profiles, skill count, rules, agents, installation date, and wor
 ```bash
 npx claude-code-arcane update
 
+# Only this repo, instead of every registered installation
+npx claude-code-arcane update --here
+
+# Preview
+npx claude-code-arcane update --dry-run
+
 # Quiet mode (for hooks — fails silently)
 npx claude-code-arcane update --quiet
 ```
 
+**What it will and will not touch.** Arcane only updates or removes content its own
+manifest records having installed. A skill or agent you wrote by hand in `.claude/`
+is reported as `Left alone (not installed by Arcane)` and never modified — including
+under `--force`, which only exists to overwrite *Arcane's* files that you edited
+locally. Files you edited that Arcane does own are skipped as `customized`.
+
+When a skill really does leave the profile, it is moved to `.claude/.arcane-trash/`
+rather than deleted, so a wrong call is recoverable. The trash sits outside
+`.claude/skills/`, so a removed skill stops loading immediately.
+
 ### `npx claude-code-arcane clean` — Remove Arcane from a project
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {