arcane-cli 0.24.1 → 0.26.0

package/dist/assets/.claude/commands/spell-scry.md

@@ -0,0 +1,13 @@
+---
+description: Use PROACTIVELY when naming anything new (a spell, a field, a product, an internal concept) before committing to it — clears a candidate name against both the outside world and this repository itself.
+---
+
+# Scry
+
+Invoke the Arcane `spell-scry` spell workflow.
+
+See the full prompt at `.github/prompts/spell-scry.prompt.md` for the complete workflow definition.
+
+---
+
+@.github/prompts/spell-scry.prompt.md

package/dist/assets/.github/prompts/spell-scry.prompt.md

@@ -0,0 +1,123 @@
+---
+name: Spell — Scry
+description: Clear a candidate name before it ships — four outward checks (who coined it, estate still trading, same-audience giants, first-association salience) plus a mandatory inward repo-local collision pass. Use when naming anything new (a spell, a field, a product, an internal concept) before committing to it.
+argument-hint: '<candidate name or term>'
+agent: agent
+---
+
+## Executive Summary
+
+- This spell clears a candidate name before it ships, checking both the outside world and this
+  repository itself.
+- The inward pass runs first and is mandatory, not optional — a real naming decision (ARC-028's
+  `workspace`) was nearly settled on a clean external read alone, until a single `grep -ri` found the
+  word already load-bearing inside the repository in two other senses.
+- Both passes classify hits with the same taxonomy (same-space / adjacent / out-of-space) and combine
+  into one verdict: pass / pass-with-disclosure / kill.
+- `spell ward` is the opposite direction of this same concern — it finds what leaked **in**; this spell
+  clears what's about to go **out**. They do not call each other; ward's denylist scanning and scry's
+  single-candidate classification are different operations on the same underlying grep primitive.
+
+---
+
+Clear the candidate name given in the prompt argument.
+
+## Step 1 — Resolve the candidate
+
+Take the term verbatim from the argument. If none was given, ask for it — do not guess a name to check.
+
+## Step 2 — Inward pass (mandatory, run first)
+
+Grep this repository for the candidate term before doing any outward research:
+
+- **Prose**: markdown, comments, documentation.
+- **Identifiers**: variable, function, type, and class names — weight these **above** prose, since
+  consumers already depend on code identifiers in a way they never depend on a sentence mentioning a
+  word.
+- **Config keys and schema fields**: `.arcane.json` fields, YAML/JSON config keys, any validated schema.
+
+Use word-boundary matching (the same principle `spell ward`'s denylist scan uses, expressed here as a
+`grep -w` / IDE-search equivalent over the codebase) — a bare substring match on a short candidate term
+will drown in false positives from unrelated words that merely contain it.
+
+**Classify each internal hit with the same taxonomy the outward checks use below:**
+
+- **Same-space**: the term is already load-bearing for a closely related concept (a config field, a
+  directory name, a class doing adjacent work) — a genuine internal collision.
+- **Adjacent**: the term appears near the concept but for something distinguishable enough that a
+  reader would not confuse the two once told them apart.
+- **Out-of-space**: incidental — a comment, an unrelated variable, coincidental substring overlap.
+
+**Why this runs first:** a same-space internal collision is often cheaper to find than the outward
+research below, and finding one early can save the effort of a full outward pass on a name that was
+already going to be killed. This is not a formality — the ARC-028 `workspace` incident is the concrete
+case: a clean external read had nearly settled the decision before a single `grep -ri` found the word
+already meaning something else in two other places inside this exact repository.
+
+## Step 3 — Outward pass: the four checks
+
+Research the candidate term against the outside world:
+
+1. **Who coined it** — search for the term's origin and earliest known usage in the relevant space
+   (software, apps, AI, games — whichever applies to this candidate).
+2. **Is an estate/trademark holder still trading** — distinguish an actively-used, enforced brand from
+   an abandoned or long-defunct one. A defunct mark carries much less collision risk than a live one.
+3. **Same-audience giants** — do major, well-known players who share this candidate's actual target
+   audience already use this name saliently? A collision with a giant outside the target audience
+   matters far less than one inside it.
+4. **First-association salience per market** — for someone in the target market, what does this term
+   bring to mind *first*? If the first association is something else entirely, that is a real cost even
+   without a formal trademark conflict.
+
+Classify each outward finding with the **same** same-space / adjacent / out-of-space taxonomy as the
+inward pass — never a separate scheme. Cite sources for every outward claim; do not assert a name's
+history or salience from unverified general knowledge alone.
+
+## Step 4 — Combine into one verdict
+
+A name that clears outward but collides inward is not a clean pass, and the reverse is equally true —
+combine both passes into a single verdict, not two separate reports:
+
+- **pass** — no same-space finding, inward or outward; adjacent/out-of-space findings, if any, are
+  noted but do not block.
+- **pass-with-disclosure** — a same-space finding exists but is distant, low-traffic, or otherwise minor
+  enough that proceeding is reasonable with the collision stated explicitly, not discovered later.
+- **kill** — a genuine, blocking same-space collision, inward or outward. Do not soften this to
+  pass-with-disclosure merely because the outward research took effort to produce.
+
+## Step 5 — Report
+
+```markdown
+## Scry verdict: <candidate> — PASS | PASS-WITH-DISCLOSURE | KILL
+
+### Inward pass
+| Hit | Location | Classification |
+|---|---|---|
+| <term usage> | <file:line> | same-space / adjacent / out-of-space |
+
+### Outward pass
+| Check | Finding | Classification | Source |
+|---|---|---|---|
+| Who coined it | ... | ... | <url or citation> |
+| Estate still trading | ... | ... | <url or citation> |
+| Same-audience giants | ... | ... | <url or citation> |
+| First-association salience | ... | ... | <url or citation> |
+
+### Verdict rationale
+<why this combination of inward + outward findings produced this verdict>
+```
+
+## Related Spells
+
+- `spell ward` — the opposite direction: finds third-party identifiers that already leaked into the
+  repo, rather than clearing a candidate before it ships out.
+
+## Rules
+
+- **Never skip the inward pass.** It is not optional, and it runs before the outward pass, not after.
+- **Never assert an outward finding without a source.** "Based on general knowledge" is not a citation.
+- **Never use a separate classification scheme for inward vs. outward findings.** Same-space / adjacent
+  / out-of-space applies to both, so a reader can compare them directly.
+- **Never round pass-with-disclosure up to pass, or down to kill, to avoid stating a nuanced verdict.**
+- This spell classifies and reports. It does not rename, alias, or otherwise resolve a collision it
+  finds — that decision belongs to whoever asked for the name cleared.

package/dist/index.js

@@ -6,7 +6,7 @@ const require = __createRequire(import.meta.url);
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 import { fileURLToPath } from "url";
-import { dirname as dirname4, join as join12 } from "path";
+import { dirname as dirname4, join as join14 } from "path";
 
 // src/commands/init.ts
 import { select as select2, confirm, input as input2 } from "@inquirer/prompts";
@@ -551,7 +551,9 @@ var COMPONENTS = [
       ".github/prompts/spell-generate-bot-icons.prompt.md",
       ".claude/commands/spell-generate-bot-icons.md",
       ".github/prompts/spell-make-discoverable.prompt.md",
-      ".claude/commands/spell-make-discoverable.md"
+      ".claude/commands/spell-make-discoverable.md",
+      ".github/prompts/spell-scry.prompt.md",
+      ".claude/commands/spell-scry.md"
     ]
   },
   {
@@ -3858,8 +3860,8 @@ async function checkVSCodeExtension(id, label) {
   ];
   for (const dir of extDirs) {
     try {
-      const { readdir: readdir5 } = await import("fs/promises");
-      const entries = await readdir5(dir);
+      const { readdir: readdir7 } = await import("fs/promises");
+      const entries = await readdir7(dir);
       const prefix = id.toLowerCase() + "-";
       const found = entries.some(
         (e) => e.toLowerCase() === id.toLowerCase() || e.toLowerCase().startsWith(prefix)
@@ -4194,6 +4196,215 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   }
 }
 
+// src/modules/ward.ts
+import { readdir as readdir6, readFile as readFile8 } from "fs/promises";
+import { join as join13, relative as relative2 } from "path";
+
+// src/modules/denylist-scan.ts
+import { readFile as readFile7, readdir as readdir5 } from "fs/promises";
+import { join as join12, relative } from "path";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createDenylistRules(tokens, labelPrefix) {
+  return tokens.map((token, index) => ({
+    label: `${labelPrefix}-${index + 1}`,
+    pattern: new RegExp(
+      `(?:^|[^A-Za-z0-9])${escapeRegExp(token)}(?=$|[^A-Za-z0-9])`,
+      "i"
+    )
+  }));
+}
+var SKIP_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "coverage",
+  ".vitest"
+]);
+var DEFAULT_SCANNABLE_EXTENSIONS = [".md", ".ts", ".js", ".json", ".yml", ".yaml"];
+async function collectScannableFiles(root, repoRoot = root, extensions = DEFAULT_SCANNABLE_EXTENSIONS) {
+  const collected = [];
+  let entries;
+  try {
+    entries = await readdir5(root, { withFileTypes: true });
+  } catch {
+    return collected;
+  }
+  for (const entry of entries) {
+    const absolutePath = join12(root, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(entry.name)) continue;
+      collected.push(...await collectScannableFiles(absolutePath, repoRoot, extensions));
+    } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+      const displayPath = relative(repoRoot, absolutePath).replace(/\\/g, "/");
+      collected.push([absolutePath, displayPath]);
+    }
+  }
+  return collected;
+}
+
+// src/modules/ward.ts
+async function scanFileAllRules(absolutePath, displayPath, rules) {
+  const findings = [];
+  let content;
+  try {
+    content = await readFile8(absolutePath, "utf8");
+  } catch {
+    return findings;
+  }
+  const lines = content.split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    const searchable = lines[index].replace(/\{[A-Z][A-Z0-9_]*\}/g, "");
+    for (const rule of rules) {
+      if (rule.pattern.test(searchable)) {
+        findings.push({ file: displayPath, line: index + 1, rule: rule.label });
+      }
+    }
+  }
+  return findings;
+}
+var VENDOR_IDENTIFIER_PROTECTION_LIST = [
+  "claude",
+  "gpt-4",
+  "gpt-3.5",
+  "gemini",
+  "llama",
+  "mistral",
+  "copilot",
+  "anthropic",
+  "openai"
+];
+var GREP_PROOF_EXTENSIONS = [".gif", ".png", ".jpg", ".jpeg", ".mp4", ".mov", ".mp3", ".wav"];
+var WARD_TEXT_EXTENSIONS = [
+  ".md",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".json",
+  ".yml",
+  ".yaml",
+  ".txt",
+  ".mdx"
+];
+function applyExclusions(findings, fileLines, exclusions) {
+  if (exclusions.length === 0) return findings;
+  return findings.filter((finding) => {
+    const applicable = exclusions.filter((e) => e.rule === finding.rule);
+    if (applicable.length === 0) return true;
+    const lines = fileLines.get(finding.file);
+    const lineText = lines?.[finding.line - 1] ?? "";
+    return !applicable.some((e) => lineText.includes(e.context));
+  });
+}
+async function scanFilenames(root, rules, repoRoot = root) {
+  const findings = [];
+  let entries;
+  try {
+    entries = await readdir6(root, { withFileTypes: true });
+  } catch {
+    return findings;
+  }
+  for (const entry of entries) {
+    const absolutePath = join13(root, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRECTORIES.has(entry.name)) continue;
+      findings.push(...await scanFilenames(absolutePath, rules, repoRoot));
+      continue;
+    }
+    const displayPath = relative2(repoRoot, absolutePath).replace(/\\/g, "/");
+    for (const rule of rules) {
+      if (rule.pattern.test(entry.name)) {
+        findings.push({ file: displayPath, line: 0, rule: rule.label });
+        break;
+      }
+    }
+  }
+  return findings;
+}
+async function flagGrepProofMedia(root, repoRoot = root) {
+  const files = await collectScannableFiles(root, repoRoot, GREP_PROOF_EXTENSIONS);
+  return files.map(([, displayPath]) => ({
+    file: displayPath,
+    reason: "binary media format -- text extraction is unreliable; review manually for embedded identifiers"
+  }));
+}
+async function runWard(repoRoot, options = {}) {
+  const userTerms = options.terms ?? [];
+  const exclusions = options.exclusions ?? [];
+  const extensions = [...WARD_TEXT_EXTENSIONS, ...options.binaryExtensions ?? []];
+  const userRules = createDenylistRules(userTerms, "ward-term");
+  const vendorRules = createDenylistRules([...VENDOR_IDENTIFIER_PROTECTION_LIST], "ward-vendor");
+  const allRules = [...userRules, ...vendorRules];
+  const contentFiles = await collectScannableFiles(repoRoot, repoRoot, extensions);
+  const fileLines = /* @__PURE__ */ new Map();
+  const contentFindings = [];
+  for (const [absolutePath, displayPath] of contentFiles) {
+    const findings2 = await scanFileAllRules(absolutePath, displayPath, allRules);
+    if (findings2.length > 0) {
+      try {
+        fileLines.set(displayPath, (await readFile8(absolutePath, "utf8")).split("\n"));
+      } catch {
+      }
+    }
+    contentFindings.push(...findings2);
+  }
+  const filenameFindings = await scanFilenames(repoRoot, allRules);
+  const combined = [...contentFindings, ...filenameFindings];
+  const excluded = applyExclusions(combined, fileLines, exclusions);
+  const vendorLabels = new Set(vendorRules.map((r) => r.label));
+  const findings = excluded.map((f) => ({
+    ...f,
+    category: vendorLabels.has(f.rule) ? "protected-vendor-identifier" : "leak"
+  }));
+  const mediaFlags = await flagGrepProofMedia(repoRoot);
+  return { findings, mediaFlags };
+}
+
+// src/commands/ward.ts
+function parseTerms(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((t) => t.trim()).filter(Boolean);
+}
+async function runWardCli(targetDir, options = {}, exclusions = []) {
+  const terms = parseTerms(options.terms);
+  const report = await runWard(targetDir, { terms, exclusions });
+  console.log("\nspell ward \u2014 scanning for leaked identifiers\n");
+  const leaks = report.findings.filter((f) => f.category === "leak");
+  const protectedHits = report.findings.filter((f) => f.category === "protected-vendor-identifier");
+  if (leaks.length === 0 && protectedHits.length === 0) {
+    console.log("  \u2713 No denylisted terms found.");
+  }
+  for (const finding of leaks) {
+    const where = finding.line === 0 ? `${finding.file} (filename)` : `${finding.file}:${finding.line}`;
+    console.log(`  \u2717 [leak] ${where} \u2014 rule: ${finding.rule}`);
+  }
+  for (const finding of protectedHits) {
+    const where = finding.line === 0 ? `${finding.file} (filename)` : `${finding.file}:${finding.line}`;
+    console.log(
+      `  \u26A0 [protected-vendor-identifier] ${where} \u2014 rule: ${finding.rule} \u2014 verify before any automated rename touches this line`
+    );
+  }
+  if (report.mediaFlags.length > 0) {
+    console.log("\n  Grep-proof media flagged for manual review:");
+    for (const flag of report.mediaFlags) {
+      console.log(`    ? ${flag.file} \u2014 ${flag.reason}`);
+    }
+  }
+  console.log();
+  if (options.gate && leaks.length > 0) {
+    console.log(`  ${leaks.length} leak(s) found. Failing (--gate mode).
+`);
+    process.exitCode = 1;
+    return;
+  }
+  if (leaks.length > 0) {
+    console.log(`  ${leaks.length} leak(s) found. Run with --gate to fail CI on this.
+`);
+  }
+}
+
 // src/commands/unblock-push.ts
 import { basename as basename2, resolve as resolve2 } from "path";
 import { input as input4 } from "@inquirer/prompts";
@@ -4296,7 +4507,7 @@ Name did not match ("${typed.trim()}" \u2260 "${repoName}"). Nothing changed.`);
 import { realpathSync } from "fs";
 var require3 = createRequire2(import.meta.url);
 var pkg = require3("../package.json");
-var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join12(dirname4(fileURLToPath(import.meta.url)), "assets");
+var ASSETS_DIR = process.env["ARCANE_ASSETS_DIR"] ?? join14(dirname4(fileURLToPath(import.meta.url)), "assets");
 var program = new Command();
 program.name("spell").description("Arcane framework CLI \u2014 scaffold and manage governance files").version(pkg.version).action(async () => {
   if (program.args.length > 0) {
@@ -4362,6 +4573,9 @@ program.command("unblock-push").description("Lift this repository's push block (
 program.command("doctor").description("Check your environment for Arcane prerequisites").option("--fix", "Automatically create missing session continuity files").action(async (opts) => {
   await runDoctor(process.cwd(), { fix: opts.fix }, ASSETS_DIR);
 });
+program.command("ward").description("Scan the repo for leaked third-party identifiers and trademarks (T18)").option("--terms <terms>", "Comma-separated denylist terms, in addition to the built-in vendor-identifier list").option("--gate", "Exit non-zero if any leak is found (for CI)").action(async (opts) => {
+  await runWardCli(process.cwd(), opts);
+});
 var agentsCommand = program.command("agents").description("Manage the portable agent system (init, sync, list)");
 agentsCommand.command("init").description(
   "Interactive agent roster setup \u2014 choose profile, naming strategy, and install definitions"