arcane-cli 0.38.3 → 1.0.0

package/dist/index.js

@@ -508,148 +508,234 @@ var COMPONENTS = [
   // ─── Spells ────────────────────────────────────────────────────────────────
   // Split from the former monolithic `spell-prompts` + `claude-commands` pair
   // so a profile can select spells by capability (see ARC-0NN). Grouping lives
-  // here and only here -- every spell file stays flat and unrenamed on disk.
+  // here and only here -- every spell file stays flat on disk; the one
+  // sanctioned relocation is ARC-045's canonical move (CS-03).
   //
-  // Each component carries BOTH client formats of the same spell: the Copilot
-  // prompt (.github/prompts/*.prompt.md) and the Claude Code wrapper
-  // (.claude/commands/*.md). They are never independently selectable -- every
-  // profile that wanted one always wanted the other -- and pairing them here
-  // makes it structurally impossible for the two formats of one spell to drift
+  // Each component carries, per spell, the canonical source and ALL THREE
+  // generated client shims (ARC-045 / CS-03): the client-neutral source
+  // (.arcane/spells/*.md, always listed first), the Copilot prompt shim
+  // (.github/prompts/*.prompt.md), the Claude Code command stub
+  // (.claude/commands/*.md), and the Codex skill (.agents/skills/*/SKILL.md,
+  // CS-01). They are never independently selectable -- every profile that
+  // wanted one always wanted the others -- and pairing them here makes it
+  // structurally impossible for a spell's source and its shims to drift
   // apart across profiles.
   {
     name: "spells-session",
     description: "Session lifecycle \u2014 open, close, commit, status, version",
     files: [
+      ".arcane/spells/spell-open-session.md",
       ".github/prompts/spell-open-session.prompt.md",
       ".claude/commands/spell-open-session.md",
+      ".agents/skills/spell-open-session/SKILL.md",
+      ".arcane/spells/spell-close-session.md",
       ".github/prompts/spell-close-session.prompt.md",
       ".claude/commands/spell-close-session.md",
+      ".agents/skills/spell-close-session/SKILL.md",
+      ".arcane/spells/spell-commit-work.md",
       ".github/prompts/spell-commit-work.prompt.md",
       ".claude/commands/spell-commit-work.md",
+      ".agents/skills/spell-commit-work/SKILL.md",
+      ".arcane/spells/spell-status.md",
       ".github/prompts/spell-status.prompt.md",
       ".claude/commands/spell-status.md",
+      ".agents/skills/spell-status/SKILL.md",
+      ".arcane/spells/spell-arcane-version.md",
       ".github/prompts/spell-arcane-version.prompt.md",
-      ".claude/commands/spell-arcane-version.md"
+      ".claude/commands/spell-arcane-version.md",
+      ".agents/skills/spell-arcane-version/SKILL.md"
     ]
   },
   {
     name: "spells-capture",
     description: "Idea, todo, feedback and explanation capture",
     files: [
+      ".arcane/spells/spell-save-idea.md",
       ".github/prompts/spell-save-idea.prompt.md",
       ".claude/commands/spell-save-idea.md",
+      ".agents/skills/spell-save-idea/SKILL.md",
+      ".arcane/spells/spell-todo.md",
       ".github/prompts/spell-todo.prompt.md",
       ".claude/commands/spell-todo.md",
+      ".agents/skills/spell-todo/SKILL.md",
+      ".arcane/spells/spell-feedback.md",
       ".github/prompts/spell-feedback.prompt.md",
       ".claude/commands/spell-feedback.md",
+      ".agents/skills/spell-feedback/SKILL.md",
+      ".arcane/spells/spell-suggest-feature.md",
       ".github/prompts/spell-suggest-feature.prompt.md",
       ".claude/commands/spell-suggest-feature.md",
+      ".agents/skills/spell-suggest-feature/SKILL.md",
+      ".arcane/spells/spell-document.md",
       ".github/prompts/spell-document.prompt.md",
       ".claude/commands/spell-document.md",
+      ".agents/skills/spell-document/SKILL.md",
+      ".arcane/spells/spell-verification-ledger.md",
       ".github/prompts/spell-verification-ledger.prompt.md",
       ".claude/commands/spell-verification-ledger.md",
+      ".agents/skills/spell-verification-ledger/SKILL.md",
+      ".arcane/spells/spell-brainstorm.md",
       ".github/prompts/spell-brainstorm.prompt.md",
       ".claude/commands/spell-brainstorm.md",
+      ".agents/skills/spell-brainstorm/SKILL.md",
+      ".arcane/spells/spell-explain-concept.md",
       ".github/prompts/spell-explain-concept.prompt.md",
-      ".claude/commands/spell-explain-concept.md"
+      ".claude/commands/spell-explain-concept.md",
+      ".agents/skills/spell-explain-concept/SKILL.md"
     ]
   },
   {
     name: "spells-delivery",
     description: "Pull-request lifecycle \u2014 open a PR, sync a stale one, respond to review feedback",
     files: [
+      ".arcane/spells/spell-create-pull-request.md",
       ".github/prompts/spell-create-pull-request.prompt.md",
       ".claude/commands/spell-create-pull-request.md",
+      ".agents/skills/spell-create-pull-request/SKILL.md",
+      ".arcane/spells/spell-sync-pull-request.md",
       ".github/prompts/spell-sync-pull-request.prompt.md",
       ".claude/commands/spell-sync-pull-request.md",
+      ".agents/skills/spell-sync-pull-request/SKILL.md",
+      ".arcane/spells/spell-address-review.md",
       ".github/prompts/spell-address-review.prompt.md",
-      ".claude/commands/spell-address-review.md"
+      ".claude/commands/spell-address-review.md",
+      ".agents/skills/spell-address-review/SKILL.md"
     ]
   },
   {
     name: "spells-review",
     description: "Adversarial code review \u2014 requires source and tests, so excluded from docs-only profiles",
     files: [
+      ".arcane/spells/spell-review.md",
       ".github/prompts/spell-review.prompt.md",
       ".claude/commands/spell-review.md",
+      ".agents/skills/spell-review/SKILL.md",
+      ".arcane/spells/spell-review-batch.md",
       ".github/prompts/spell-review-batch.prompt.md",
-      ".claude/commands/spell-review-batch.md"
+      ".claude/commands/spell-review-batch.md",
+      ".agents/skills/spell-review-batch/SKILL.md"
     ]
   },
   {
     name: "spells-planning",
     description: "PRD, architecture, scoping and product review",
     files: [
+      ".arcane/spells/spell-plan.md",
       ".github/prompts/spell-plan.prompt.md",
       ".claude/commands/spell-plan.md",
+      ".agents/skills/spell-plan/SKILL.md",
+      ".arcane/spells/spell-architect.md",
       ".github/prompts/spell-architect.prompt.md",
       ".claude/commands/spell-architect.md",
+      ".agents/skills/spell-architect/SKILL.md",
+      ".arcane/spells/spell-scope.md",
       ".github/prompts/spell-scope.prompt.md",
       ".claude/commands/spell-scope.md",
+      ".agents/skills/spell-scope/SKILL.md",
+      ".arcane/spells/spell-product-review.md",
       ".github/prompts/spell-product-review.prompt.md",
-      ".claude/commands/spell-product-review.md"
+      ".claude/commands/spell-product-review.md",
+      ".agents/skills/spell-product-review/SKILL.md"
     ]
   },
   {
     name: "spells-build",
     description: "Code and product delivery \u2014 implementation, tests, stack experts, release, deployment, asset tooling",
     files: [
+      ".arcane/spells/spell-implement.md",
       ".github/prompts/spell-implement.prompt.md",
       ".claude/commands/spell-implement.md",
+      ".agents/skills/spell-implement/SKILL.md",
+      ".arcane/spells/spell-test.md",
       ".github/prompts/spell-test.prompt.md",
       ".claude/commands/spell-test.md",
+      ".agents/skills/spell-test/SKILL.md",
+      ".arcane/spells/spell-full-cycle.md",
       ".github/prompts/spell-full-cycle.prompt.md",
       ".claude/commands/spell-full-cycle.md",
+      ".agents/skills/spell-full-cycle/SKILL.md",
+      ".arcane/spells/spell-bug.md",
       ".github/prompts/spell-bug.prompt.md",
       ".claude/commands/spell-bug.md",
+      ".agents/skills/spell-bug/SKILL.md",
+      ".arcane/spells/spell-bump.md",
       ".github/prompts/spell-bump.prompt.md",
       ".claude/commands/spell-bump.md",
+      ".agents/skills/spell-bump/SKILL.md",
+      ".arcane/spells/spell-dotnet-expert.md",
       ".github/prompts/spell-dotnet-expert.prompt.md",
       ".claude/commands/spell-dotnet-expert.md",
+      ".agents/skills/spell-dotnet-expert/SKILL.md",
+      ".arcane/spells/spell-security-review.md",
       ".github/prompts/spell-security-review.prompt.md",
       ".claude/commands/spell-security-review.md",
+      ".agents/skills/spell-security-review/SKILL.md",
+      ".arcane/spells/spell-ship.md",
       ".github/prompts/spell-ship.prompt.md",
       ".claude/commands/spell-ship.md",
+      ".agents/skills/spell-ship/SKILL.md",
+      ".arcane/spells/spell-enchant.md",
       ".github/prompts/spell-enchant.prompt.md",
       ".claude/commands/spell-enchant.md",
+      ".agents/skills/spell-enchant/SKILL.md",
+      ".arcane/spells/spell-generate-bot-icons.md",
       ".github/prompts/spell-generate-bot-icons.prompt.md",
       ".claude/commands/spell-generate-bot-icons.md",
+      ".agents/skills/spell-generate-bot-icons/SKILL.md",
+      ".arcane/spells/spell-make-discoverable.md",
       ".github/prompts/spell-make-discoverable.prompt.md",
       ".claude/commands/spell-make-discoverable.md",
+      ".agents/skills/spell-make-discoverable/SKILL.md",
+      ".arcane/spells/spell-scry.md",
       ".github/prompts/spell-scry.prompt.md",
       ".claude/commands/spell-scry.md",
+      ".agents/skills/spell-scry/SKILL.md",
+      ".arcane/spells/spell-eas-store-deploy.md",
       ".github/prompts/spell-eas-store-deploy.prompt.md",
       ".claude/commands/spell-eas-store-deploy.md",
+      ".agents/skills/spell-eas-store-deploy/SKILL.md",
+      ".arcane/spells/spell-compliance.md",
       ".github/prompts/spell-compliance.prompt.md",
-      ".claude/commands/spell-compliance.md"
+      ".claude/commands/spell-compliance.md",
+      ".agents/skills/spell-compliance/SKILL.md"
     ]
   },
   {
     name: "spells-docs",
     description: "Documentation and records workflows \u2014 adopt an existing document tree",
     files: [
+      ".arcane/spells/spell-adopt-docs.md",
       ".github/prompts/spell-adopt-docs.prompt.md",
-      ".claude/commands/spell-adopt-docs.md"
+      ".claude/commands/spell-adopt-docs.md",
+      ".agents/skills/spell-adopt-docs/SKILL.md"
     ]
   },
   {
     name: "spells-venture",
     description: "Hub-only venture management",
     files: [
+      ".arcane/spells/spell-summon-venture.md",
       ".github/prompts/spell-summon-venture.prompt.md",
       ".claude/commands/spell-summon-venture.md",
+      ".agents/skills/spell-summon-venture/SKILL.md",
+      ".arcane/spells/spell-manifest.md",
       ".github/prompts/spell-manifest.prompt.md",
-      ".claude/commands/spell-manifest.md"
+      ".claude/commands/spell-manifest.md",
+      ".agents/skills/spell-manifest/SKILL.md"
     ]
   },
   {
     name: "spells-meta",
     description: "Arcane-about-Arcane \u2014 presentation and documentation drift detection",
     files: [
+      ".arcane/spells/spell-present-arcane.md",
       ".github/prompts/spell-present-arcane.prompt.md",
       ".claude/commands/spell-present-arcane.md",
+      ".agents/skills/spell-present-arcane/SKILL.md",
+      ".arcane/spells/spell-check-drift.md",
       ".github/prompts/spell-check-drift.prompt.md",
-      ".claude/commands/spell-check-drift.md"
+      ".claude/commands/spell-check-drift.md",
+      ".agents/skills/spell-check-drift/SKILL.md"
     ]
   },
   // Templates
@@ -2640,13 +2726,9 @@ function isSpellComponent(name) {
 function categorizeComponents(components) {
   const groups = [];
   const spellFiles = components.filter((c) => isSpellComponent(c.name)).flatMap((c) => c.files);
-  const promptCount = spellFiles.filter((f) => f.startsWith(".github/prompts/")).length;
-  if (promptCount > 0) {
-    groups.push({ icon: "\u2728", label: "Copilot Spells", count: promptCount });
-  }
-  const claudeCount = spellFiles.filter((f) => f.startsWith(".claude/commands/")).length;
-  if (claudeCount > 0) {
-    groups.push({ icon: "\u26A1", label: "Claude Spells", count: claudeCount });
+  const spellCount = spellFiles.filter((f) => f.startsWith(".arcane/spells/")).length;
+  if (spellCount > 0) {
+    groups.push({ icon: "\u2728", label: "Spells (Copilot, Claude Code, Codex)", count: spellCount });
   }
   const governance = components.filter(
     (c) => !isSpellComponent(c.name) && c.name !== "venture-template" && c.name !== "agent-definitions" && c.files.some((f) => f.startsWith(".arcane/governance/"))
@@ -3493,6 +3575,18 @@ async function fetchPublishedFile(version, relativeAssetPath) {
   }
 }
 
+// src/modules/spell-compiler.ts
+import { parse as parseYaml2 } from "yaml";
+var CLIENT_SHIM_PATH_PATTERNS = [
+  /^\.github\/prompts\/spell-[a-z0-9-]+\.prompt\.md$/,
+  /^\.claude\/commands\/spell-[a-z0-9-]+\.md$/,
+  /^\.agents\/skills\/spell-[a-z0-9-]+\/SKILL\.md$/
+];
+function isClientShimPath(path4) {
+  const normalized = path4.replace(/\\/g, "/").replace(/^\.\//, "");
+  return CLIENT_SHIM_PATH_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
 // src/commands/update.ts
 function migrateLegacyComponents(components) {
   const out = [];
@@ -3530,6 +3624,23 @@ async function resolveOrphan(targetDir, file, recordedHash, prune) {
   console.log(`  Pruned orphaned file: ${file}`);
   return "pruned";
 }
+async function findMissingTrackedFiles(targetDir, components) {
+  const missing = [];
+  for (const installed of components) {
+    let component;
+    try {
+      component = getComponent(installed.name);
+    } catch {
+      continue;
+    }
+    if (component.initOnly || component.skipExisting) continue;
+    for (const file of installed.files) {
+      if (!component.files.includes(file)) continue;
+      if (!await fileExists(join8(targetDir, file))) missing.push(file);
+    }
+  }
+  return missing;
+}
 async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   let manifest;
   try {
@@ -3572,9 +3683,17 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     process.exit(1);
     return;
   }
+  let sameVersionRestore = false;
   if (manifest.version === packageVersion && manifest.components.length > 0) {
-    console.log("Already up to date.");
-    return;
+    const missing = await findMissingTrackedFiles(targetDir, manifest.components);
+    if (missing.length === 0) {
+      console.log("Already up to date.");
+      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.`
+    );
   }
   if (manifest.components.length === 0) {
     console.log("No components installed. Nothing to update.");
@@ -3583,6 +3702,7 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
   let fileCount = 0;
   const updatedComponents = [];
   const conflictedFiles = [];
+  const customizedShims = [];
   const orphanReport = [];
   const componentsToUpdate = migrateLegacyComponents(manifest.components);
   for (const installed of componentsToUpdate) {
@@ -3615,49 +3735,66 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
       const srcPath = join8(assetsDir, component.sourceOverrides?.[file] ?? file);
       const targetExists = await fileExists(join8(targetDir, file));
       const preserveExisting = Boolean(component.skipExisting) && targetExists;
+      const recordedHash = installed.fileHashes?.[file];
       if (component.initOnly && !targetExists) {
         console.log(
           `  ! Missing: ${file} \u2014 not added automatically, because doing so would change how Git treats existing files. Run "spell add ${component.name}" if you want it.`
         );
         continue;
       }
+      if (sameVersionRestore) {
+        const tracked = installed.files.includes(file);
+        const restorable = tracked && !targetExists && !component.skipExisting;
+        if (!restorable) {
+          if (tracked) {
+            updatedFiles.push(file);
+            if (recordedHash !== void 0) fileHashes[file] = recordedHash;
+          }
+          continue;
+        }
+      }
+      const editedByOperator = recordedHash !== void 0 && targetExists && !preserveExisting && await hashFile(join8(targetDir, file)) !== recordedHash;
       if (preserveExisting) {
         console.log(`  ${options.dryRun ? "[dry-run] Would preserve" : "Preserved"}: ${file}`);
+      } else if (editedByOperator && isClientShimPath(file)) {
+        customizedShims.push(file);
+        fileHashes[file] = recordedHash;
+        console.log(
+          `  ${options.dryRun ? "[dry-run] Would keep" : "Kept"} customized (not merged): ${file}`
+        );
       } else if (options.dryRun) {
-        console.log(`  [dry-run] Would update: ${file}`);
+        console.log(`  [dry-run] Would ${sameVersionRestore ? "restore missing" : "update"}: ${file}`);
         fileCount++;
       } else {
-        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;
+        if (editedByOperator) {
+          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.`
+            );
+            fileHashes[file] = recordedHash;
+            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(srcPath);
+            if (result.hasConflict) {
+              conflictedFiles.push(file);
+              console.log(`  \u26A0 Merge conflict in ${file} \u2014 resolve the <<<<<<< markers before committing.`);
             } 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;
+              console.log(`  Merged your edits into: ${file}`);
             }
+            handled = true;
           }
         }
         if (!handled) {
           fileHashes[file] = await copyFile(srcPath, targetDir, file, { force: true });
+          if (sameVersionRestore) console.log(`  Restored missing: ${file}`);
         }
         fileCount++;
       }
@@ -3710,6 +3847,15 @@ ${verb} ${orphansToReport.length} orphaned file(s) (tracked before this update,
       console.log("  Run `spell update --prune` to remove the ones that are safe to delete.");
     }
   }
+  if (customizedShims.length > 0) {
+    const verb = options.dryRun ? "[dry-run] Would keep" : "Kept";
+    console.log(
+      `
+! ${verb} ${customizedShims.length} customized client file(s) untouched (ARC-045): an edited Copilot prompt, Claude command or Codex skill is never merged into the new generated shim, because a shim carries no prose of its own to merge into.
+` + customizedShims.map((f) => `    ${f}`).join("\n") + `
+  Each keeps working in its client as-is. To converge: move your edits into the canonical spell (.arcane/spells/<id>.md \u2014 later updates merge edits there), delete the customized file, commit, and run \`spell update\` again \u2014 it restores the generated shim at the current version.`
+    );
+  }
   if (options.dryRun) {
     console.log(
       `