arcane-cli 1.1.1 → 1.2.0

package/README.md

@@ -231,7 +231,24 @@ spell update --user     # after upgrading the CLI
 spell uninstall --user  # removes only what it wrote; an edited client file is kept and named
 ```
 
-Codex, VS Code Copilot and Claude Code each discover the user tier from their own home-directory locations (`~/.agents/skills` and `~/.claude/commands`), so no VS Code setting is needed. Claude Code runs a personal command over a project command of the same name, so in a repository that still carries its own spells `/spell-*` runs the user tier's copy. Governance stays per repository — only spell delivery moves up a level.
+Codex, VS Code Copilot and Claude Code each discover the user tier from their own home-directory locations (`~/.agents/skills` and `~/.claude/commands`), so no VS Code setting is needed. Governance stays per repository — only spell delivery moves up a level.
+
+**Then let a repository stop carrying its own copies.** `spell init` offers this when the machine already has a tier, and an existing repository opts in by setting one field:
+
+```jsonc
+// .arcane.json
+{ "spell_scope": "user" }   // absent, or "repo", means this repository carries its own spells
+```
+
+```bash
+spell update          # lists the spell files this repository no longer manages — deletes nothing
+spell update --prune  # removes the untouched ones; anything you edited is kept and named
+spell doctor          # fails loudly if the user tier it now depends on is missing
+```
+
+This is what removes the duplication: with the repository's own copies gone, one workspace holding ten Arcane projects shows one set of `/spell-*` entries, not ten. It is also what makes the answer predictable — while both tiers own a command name, which copy a client runs is not something you can read off the docs.
+
+**Shared, team and cloud repositories should stay `repo`.** The field is committed and inherited by every clone, so opting in tells *everyone* who clones that repository to get their spells from a machine-wide install they may not have. Reverse it by setting the field back and running `spell update`, which reinstalls every spell file.
 
 ---
 

package/dist/assets/.arcane/governance/portable-bootstrap.md

@@ -52,7 +52,7 @@ Paste this entire file into any AI client (Claude web, ChatGPT, etc.) to give it
 ## Where Documents Live
 
 - **Framework-managed standards:** `.arcane/governance/`. Spells reference this single installed layer; **do not create a duplicate root `governance/` tree. Enforcement: explicitly advisory prose (ARC-023) — no check scans a repo for a duplicate root-level `governance/` directory.**
-- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier.
+- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier. A repository may then opt out of carrying its own copies entirely with `spell_scope: "user"` in `.arcane.json` (ARC-045 decision 4) — `spell update --prune` removes what it no longer manages, keeping anything you edited, and `spell doctor` fails loudly if the tier it now depends on is missing.
 - **Project-owned orientation and continuity:** `README.md`, `project.md`, `TODO.md`, `DECISIONS.md`, `ai-context/`, and `journal/`. Arcane creates missing files once and preserves existing content.
 - **Project/domain documents:** use explicit descriptive paths such as `docs/`, `security/`, `infrastructure/`, or a configured business root. These add project context alongside framework standards.
 - **Overrides survive `arcane update`:** editing a managed `.arcane/governance/` standard no longer risks silent loss. Additive project documents were always safe; a hand-edit to a shipped standard now is too. **Enforcement: executable check (ARC-038, shipped BC-31)** — `spell update` compares each file's on-disk content against its recorded hash at install time: unchanged, it refreshes normally; edited, it fetches the exact previously-installed published version as a three-way merge base against your edit and the new vendor content, auto-merging non-overlapping changes and leaving standard conflict markers only on genuine collisions. If the prior published version can't be fetched, your edit is left untouched with a warning rather than replaced.

package/dist/index.js

@@ -20,6 +20,7 @@ import {
   readdir,
   readFile,
   rm,
+  rmdir,
   writeFile
 } from "fs/promises";
 import { createHash } from "crypto";
@@ -89,6 +90,20 @@ async function removeWithin(targetDir, relativePath) {
   validateTargetPath(targetDir, relativePath);
   await rm(path.resolve(targetDir, relativePath), { force: true });
 }
+async function removeEmptyAncestors(targetDir, relativePath) {
+  validateTargetPath(targetDir, relativePath);
+  const base = path.resolve(targetDir);
+  let dir = path.dirname(path.resolve(targetDir, relativePath));
+  while (dir !== base && dir.startsWith(base + path.sep)) {
+    try {
+      if ((await readdir(dir)).length > 0) return;
+      await rmdir(dir);
+    } catch {
+      return;
+    }
+    dir = path.dirname(dir);
+  }
+}
 async function copyDirectory(srcDir, targetDir, relativeDir, opts = {}) {
   validateTargetPath(targetDir, relativeDir);
   const copiedFiles = [];
@@ -201,6 +216,9 @@ function validateTrackingFields(manifest, filePath) {
   if (manifest.scope !== void 0 && !VALID_INSTALL_SCOPES.includes(manifest.scope)) {
     throw new ManifestInvalidFieldError(filePath, "scope", manifest.scope);
   }
+  if (manifest.spell_scope !== void 0 && !VALID_INSTALL_SCOPES.includes(manifest.spell_scope)) {
+    throw new ManifestInvalidFieldError(filePath, "spell_scope", manifest.spell_scope);
+  }
   if (manifest.fanout !== void 0 && !isValidFanoutRecord(manifest.fanout)) {
     throw new ManifestInvalidFieldError(filePath, "fanout", manifest.fanout);
   }
@@ -866,7 +884,7 @@ function listProfiles() {
 }
 
 // src/modules/user-tier.ts
-import { lstat, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm as rm2, rmdir, writeFile as writeFile3 } from "fs/promises";
+import { lstat, mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rm as rm2, rmdir as rmdir2, writeFile as writeFile3 } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join, resolve } from "path";
 
@@ -999,6 +1017,14 @@ function componentForScope(component, scope) {
   }
   return { name: component.name, description: component.description, files, sourceOverrides };
 }
+function componentForSpellScope(component, spellScope) {
+  if (spellScope === "repo") return component;
+  if (!SPELL_COMPONENT_NAMES.includes(component.name)) return component;
+  return { ...component, files: [] };
+}
+function effectiveSpellScope(manifest) {
+  return manifest.spell_scope ?? "repo";
+}
 function spellIdsInStore(components) {
   const ids = /* @__PURE__ */ new Set();
   for (const component of components) {
@@ -1076,7 +1102,7 @@ function perSpellDirectory(homeDir, relativePath) {
 async function removeDirectoryIfEmpty(dir) {
   try {
     const entries = await readdir2(dir);
-    if (entries.length === 0) await rmdir(dir);
+    if (entries.length === 0) await rmdir2(dir);
   } catch {
   }
 }
@@ -3274,16 +3300,35 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     profile = await select2({
       message: "Select an installation profile:\n",
       choices: profiles.map((p) => {
-        const profileComponents = getProfile(p.id);
+        const profileComponents2 = getProfile(p.id);
         return {
           value: p.id,
           name: `${PROFILE_ICONS[p.id] ?? "\u{1F4CB}"}  ${p.displayName} \u2014 ${p.description}`,
-          description: buildProfileDescription(profileComponents, p.id)
+          description: buildProfileDescription(profileComponents2, p.id)
         };
       })
     });
   }
-  const components = getProfile(profile);
+  const profileComponents = getProfile(profile);
+  let spell_scope;
+  if (!options.profile && !options.dryRun) {
+    let storeVersion;
+    try {
+      storeVersion = (await readManifest(userTierRoot())).version;
+    } catch {
+    }
+    if (storeVersion !== void 0) {
+      console.log();
+      const useTier = await confirm({
+        message: `This machine has an Arcane user tier (v${storeVersion}). Use it for this repository's spells instead of installing copies here?`,
+        default: false
+      });
+      spell_scope = useTier ? "user" : "repo";
+    }
+  }
+  const components = profileComponents.map(
+    (component) => componentForSpellScope(component, spell_scope ?? "repo")
+  );
   const groups = categorizeComponents(components);
   console.log();
   printSection(`\u{1F4E6} Profile: ${profile}`);
@@ -3470,6 +3515,7 @@ async function runInit(options, targetDir, assetsDir, packageVersion) {
     profile,
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     components: installedComponents,
+    ...spell_scope ? { spell_scope } : {},
     ...role ? { role } : {},
     ...tracking_mode ? { tracking_mode, external_provider } : {},
     ...subject_root !== void 0 ? { subject_root } : {},
@@ -4155,26 +4201,57 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
     return "reported";
   }
   await removeWithin(targetDir, file);
+  await removeEmptyAncestors(targetDir, file);
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
-async function findMissingTrackedFiles(targetDir, components, scope = "repo") {
+function findReadoptedSpellComponents(components, scope = "repo", spellScope = "repo") {
+  if (scope !== "repo" || spellScope !== "repo") return /* @__PURE__ */ new Set();
+  return new Set(
+    components.filter((c) => SPELL_COMPONENT_NAMES.includes(c.name) && c.files.length === 0).map((c) => c.name)
+  );
+}
+async function findMissingTrackedFiles(targetDir, components, scope = "repo", spellScope = "repo", readopted = /* @__PURE__ */ new Set()) {
   const missing = [];
   for (const installed of components) {
     let component;
     try {
-      component = componentForScope(getComponent(installed.name), scope);
+      component = componentForSpellScope(
+        componentForScope(getComponent(installed.name), scope),
+        scope === "repo" ? spellScope : "repo"
+      );
     } catch {
       continue;
     }
     if (component.initOnly || component.skipExisting) continue;
-    for (const file of installed.files) {
+    const candidates = readopted.has(installed.name) ? component.files : installed.files;
+    for (const file of candidates) {
       if (!component.files.includes(file)) continue;
       if (!await fileExists(join9(targetDir, file))) missing.push(file);
     }
   }
   return missing;
 }
+function findUnmanagedTrackedFiles(components, scope = "repo", spellScope = "repo") {
+  const unmanaged = [];
+  for (const installed of components) {
+    let component;
+    try {
+      component = componentForSpellScope(
+        componentForScope(getComponent(installed.name), scope),
+        scope === "repo" ? spellScope : "repo"
+      );
+    } catch {
+      unmanaged.push(...installed.files);
+      continue;
+    }
+    const shipped = new Set(component.files);
+    for (const file of installed.files) {
+      if (!shipped.has(file)) unmanaged.push(file);
+    }
+  }
+  return unmanaged;
+}
 async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -4196,6 +4273,8 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     return;
   }
   const scope = resolvedScope.scope;
+  const spellScope = effectiveSpellScope(manifest);
+  const readopted = findReadoptedSpellComponents(manifest.components, scope, spellScope);
   const homeDir = dirname4(targetDir);
   if (scope === "repo") {
     console.warn(
@@ -4229,8 +4308,9 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   }
   let sameVersionRestore = false;
   if (manifest.version === packageVersion && manifest.components.length > 0) {
-    const missing = await findMissingTrackedFiles(targetDir, manifest.components, scope);
-    if (missing.length === 0) {
+    const missing = await findMissingTrackedFiles(targetDir, manifest.components, scope, spellScope, readopted);
+    const unmanaged = findUnmanagedTrackedFiles(manifest.components, scope, spellScope);
+    if (missing.length === 0 && unmanaged.length === 0) {
       console.log("Already up to date.");
       if (scope === "user") {
         const fanout = await syncUserTierFanout({
@@ -4249,9 +4329,16 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       return;
     }
     sameVersionRestore = true;
-    console.log(
-      `${options.dryRun ? "[dry-run] " : ""}Already at v${packageVersion}, but ${missing.length} tracked file${missing.length === 1 ? " is" : "s are"} missing \u2014 restoring.`
-    );
+    const prefix = options.dryRun ? "[dry-run] " : "";
+    if (missing.length > 0) {
+      console.log(
+        `${prefix}Already at v${packageVersion}, but ${missing.length} tracked file${missing.length === 1 ? " is" : "s are"} missing \u2014 restoring.`
+      );
+    } else {
+      console.log(
+        `${prefix}Already at v${packageVersion}, but ${unmanaged.length} tracked file${unmanaged.length === 1 ? " is" : "s are"} no longer managed here \u2014 reviewing.`
+      );
+    }
   }
   if (manifest.components.length === 0) {
     console.log("No components installed. Nothing to update.");
@@ -4266,7 +4353,10 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   for (const installed of componentsToUpdate) {
     let component;
     try {
-      component = componentForScope(getComponent(installed.name), scope);
+      component = componentForSpellScope(
+        componentForScope(getComponent(installed.name), scope),
+        scope === "repo" ? spellScope : "repo"
+      );
     } catch (err) {
       if (err instanceof ComponentNotFoundError) {
         console.log(`  ! ${installed.name} not in registry \u2014 skipping.`);
@@ -4301,7 +4391,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
         continue;
       }
       if (sameVersionRestore) {
-        const tracked = installed.files.includes(file);
+        const tracked = installed.files.includes(file) || readopted.has(installed.name);
         const restorable = tracked && !targetExists && !component.skipExisting;
         if (!restorable) {
           if (tracked) {
@@ -4378,13 +4468,24 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     for (const file of installed.files) {
       if (updatedFiles.includes(file)) continue;
+      const recordedHash = installed.fileHashes?.[file];
       const status = await resolveOrphan(
         targetDir,
         file,
-        installed.fileHashes?.[file],
+        recordedHash,
         Boolean(options.prune) && !options.dryRun
       );
       orphanReport.push({ file, status });
+      if (status === "reported") {
+        try {
+          validateTargetPath(targetDir, file);
+          if (await fileExists(join9(targetDir, file))) {
+            updatedFiles.push(file);
+            if (recordedHash !== void 0) fileHashes[file] = recordedHash;
+          }
+        } catch {
+        }
+      }
     }
     updatedComponents.push({
       ...installed,
@@ -4404,6 +4505,11 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
       const marker = status === "pruned" ? "pruned" : options.prune ? "kept (see reason above)" : "not removed";
       console.log(`    ${file} \u2014 ${marker}`);
     }
+    if (scope === "repo" && spellScope === "user") {
+      console.log(
+        '  This repository takes its spells from the user tier (spell_scope: "user"), so the files above are no longer managed here \u2014 every client reads ~/.arcane instead.'
+      );
+    }
     if (!options.prune) {
       console.log("  Run `spell update --prune` to remove the ones that are safe to delete.");
     }
@@ -4670,12 +4776,18 @@ async function runStatus(targetDir, packageVersion, options = {}) {
       );
     }
   } else {
-    console.log("  Scope: repo");
+    const spellScope = effectiveSpellScope(manifest);
+    console.log(spellScope === "user" ? "  Scope: repo (spells: user tier)" : "  Scope: repo");
+    const store = userTierRoot();
     try {
-      const store = userTierRoot();
       const userManifest = await readManifest(store);
       console.log(`  User tier: v${userManifest.version} at ${store} (spell status --user)`);
     } catch {
+      if (spellScope === "user") {
+        console.log(
+          `  ! User tier: not installed at ${store} \u2014 this repository expects it for every spell. Run \`spell init --user\` (\`spell doctor\` explains).`
+        );
+      }
     }
   }
   console.log("");
@@ -4881,7 +4993,7 @@ async function uninstallUserTier(options, storeRoot, manifest) {
 }
 
 // src/commands/doctor.ts
-import { access as access4, readFile as readFile10, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
+import { access as access4, readdir as readdir7, readFile as readFile10, mkdir as mkdir7, copyFile as fsCopyFile } from "fs/promises";
 import { join as join13, dirname as dirname8 } from "path";
 import { execFile as execFile3 } from "child_process";
 import { promisify as promisify2 } from "util";
@@ -5221,8 +5333,8 @@ async function checkVSCodeExtension(id, label) {
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir9 } = await import("fs/promises");
-      const entries = await readdir9(dir);
+      const { readdir: readdir10 } = await import("fs/promises");
+      const entries = await readdir10(dir);
       const prefix = id.toLowerCase() + "-";
       const found = entries.some(
         (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
@@ -5646,6 +5758,66 @@ async function checkPlatformBranchPolicy(targetDir) {
     message: "remote is neither GitHub nor Azure DevOps \u2014 platform policy verification not available for this provider"
   };
 }
+async function checkSpellScope(targetDir, homeDir = resolveHomeDir()) {
+  const name = "Spell scope (ARC-045)";
+  let manifest;
+  try {
+    manifest = await readManifest(targetDir);
+  } catch {
+    return { name, passed: true, blocking: false, message: "no .arcane.json \u2014 nothing to check" };
+  }
+  if (effectiveSpellScope(manifest) === "repo") {
+    return {
+      name,
+      passed: true,
+      blocking: false,
+      message: "repo \u2014 this repository carries its own spells (the default)"
+    };
+  }
+  const storeRoot = userTierRoot(homeDir);
+  let store;
+  try {
+    store = await readManifest(storeRoot);
+  } catch (err) {
+    return {
+      name,
+      passed: false,
+      message: `this repository takes its spells from the user tier (spell_scope: "user"), but ${storeRoot} ${err instanceof ManifestNotFoundError ? "is not installed" : `could not be read (${err instanceof Error ? err.message : String(err)})`} \u2014 no client can reach a spell here. Run \`spell init --user\`, or set spell_scope back to "repo" and run \`spell update\`.`
+    };
+  }
+  let spellCount = 0;
+  let probed = false;
+  const probe = "spell-status.md";
+  try {
+    const entries = await readdir7(join13(storeRoot, USER_TIER_SPELLS_DIR));
+    const spells = entries.filter((e) => e.startsWith("spell-") && e.endsWith(".md"));
+    spellCount = spells.length;
+    probed = spells.includes(probe);
+  } catch {
+  }
+  if (spellCount === 0 || !probed) {
+    return {
+      name,
+      passed: false,
+      message: `the user tier at ${storeRoot} holds ${spellCount} spell(s)${spellCount > 0 && !probed ? ` and not ${probe}` : ""} \u2014 this repository expects it to supply every spell. Run \`spell update --user\`.`
+    };
+  }
+  const majorMinor = (v) => v.split(".").slice(0, 2).join(".");
+  if (typeof manifest.version === "string" && majorMinor(store.version) !== majorMinor(manifest.version)) {
+    return {
+      name,
+      passed: false,
+      blocking: false,
+      message: `this repository is at v${manifest.version} but the user tier it uses is at v${store.version} \u2014 run \`spell update --user\` (and \`spell update\` here) to bring them together.`
+    };
+  }
+  return {
+    name,
+    passed: true,
+    blocking: false,
+    message: `user \u2014 ${spellCount} spell(s) from ${storeRoot} (v${store.version}), ${probe} present`
+  };
+}
 async function runDoctor(targetDir, options = {}, assetsDir) {
   console.log("\nspell doctor \u2014 checking your Arcane environment\n");
   if (options.leaks) {
@@ -5671,7 +5843,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
     checkPlatformBranchPolicy(targetDir),
     checkDelegations(targetDir),
     checkMcpConfig(targetDir),
-    checkUserTier(resolveHomeDir(), options.packageVersion)
+    checkUserTier(resolveHomeDir(), options.packageVersion),
+    checkSpellScope(targetDir)
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);
@@ -5719,7 +5892,7 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
 import { readFile as readFile12 } from "fs/promises";
 
 // src/modules/ward.ts
-import { readdir as readdir7, readFile as readFile11 } from "fs/promises";
+import { readdir as readdir8, readFile as readFile11 } from "fs/promises";
 import { join as join14, relative as relative2 } from "path";
 async function scanFileAllRules(absolutePath, displayPath, rules) {
   const findings = [];
@@ -5778,7 +5951,7 @@ async function scanFilenames(root, rules, repoRoot = root) {
   const findings = [];
   let entries;
   try {
-    entries = await readdir7(root, { withFileTypes: true });
+    entries = await readdir8(root, { withFileTypes: true });
   } catch {
     return findings;
   }
@@ -6000,7 +6173,7 @@ import { access as access5 } from "fs/promises";
 import { join as join17 } from "path";
 
 // src/modules/show-report/generate.ts
-import { mkdir as mkdir8, readdir as readdir8, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
+import { mkdir as mkdir8, readdir as readdir9, readFile as readFile14, writeFile as writeFile11 } from "fs/promises";
 import { basename as basename3, dirname as dirname9, isAbsolute, join as join16, relative as relative3, resolve as resolve4 } from "path";
 
 // src/modules/show-report/model.ts
@@ -6567,7 +6740,7 @@ async function discoverPrograms(rootDir) {
   const plansDir = join16(rootDir, "docs", "plans");
   let entries;
   try {
-    entries = (await readdir8(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
+    entries = (await readdir9(plansDir, { withFileTypes: true })).filter((e) => e.isDirectory());
   } catch (error) {
     if (error.code === "ENOENT") return { programs: [], skipped: [] };
     throw error;