claude-code-arcane 2.16.0 → 2.17.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [2.17.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.16.0...v2.17.0) (2026-10-16)
+
+
+### Bug Fixes
+
+* **update:** narrow the old Bash(gh *) allow in existing installs ([4b033be](https://github.com/SebastianLuser/claude-code-arcane/commit/4b033befa1c3f68e84855cbf9e430f21be836293))
+
+
+### Features
+
+* **cli:** add arcane doctor to check that an install works ([cd36de9](https://github.com/SebastianLuser/claude-code-arcane/commit/cd36de93baad06f6e5e47151eb2902fc6d6d1651))
+
 # [2.16.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.15.0...v2.16.0) (2026-10-16)
 
 

package/README.md

@@ -149,6 +149,7 @@ Installs worktree-isolation scripts into `~/.claude/scripts/` and adds a `Sessio
 ```bash
 npx claude-code-arcane list                          # List all profiles and skills
 npx claude-code-arcane status                        # Show current installation
+npx claude-code-arcane doctor                        # Check that hooks, settings and content work
 npx claude-code-arcane update                        # Check for updates
 npx claude-code-arcane clean --force                 # Remove Arcane entirely from project
 ```

package/dist/cli.js

@@ -2940,6 +2940,13 @@ function syncUnhashedFiles(root, claudeDir, merged, dryRun) {
           dirty = true;
         }
       }
+      const allow = settings.permissions?.allow;
+      if (Array.isArray(allow) && allow.includes("Bash(gh *)")) {
+        const narrowed = merged.permissions.allow.filter((r) => r.startsWith("Bash(gh ") && !allow.includes(r));
+        settings.permissions.allow = allow.flatMap((r) => r === "Bash(gh *)" ? narrowed : [r]);
+        changed.push("settings.json (Bash(gh *) narrowed)");
+        dirty = true;
+      }
       if (dirty && !dryRun) {
         fs15.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
 `, "utf-8");
@@ -3368,12 +3375,296 @@ function removeHookFromSettings() {
   writeSettings(settings);
 }
 
-// src/update-check.ts
+// src/commands/doctor.ts
 import fs18 from "fs";
 import path21 from "path";
+import { spawnSync as spawnSync2 } from "child_process";
 import chalk11 from "chalk";
+var DANGEROUS_ALLOWS = /* @__PURE__ */ new Set([
+  "Bash",
+  "Bash(*)",
+  "Bash(gh *)",
+  "Bash(git *)",
+  "Bash(git push*)",
+  "Bash(git reset*)",
+  "Bash(rm *)",
+  "Bash(sudo *)",
+  "Bash(bash *)",
+  "Bash(sh *)",
+  "Bash(eval *)"
+]);
+var SECRET_PATTERNS = [
+  ["Anthropic key", /sk-ant-[A-Za-z0-9_-]{20,}/],
+  ["OpenAI key", /sk-(?:proj-)?[A-Za-z0-9]{32,}/],
+  ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{22,})/],
+  ["Slack token", /\bxox[abpr]-[A-Za-z0-9-]{10,}/],
+  ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
+  ["Google API key", /\bAIza[0-9A-Za-z_-]{35}/],
+  ["Stripe live key", /\b[sr]k_live_[0-9A-Za-z]{20,}/],
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/]
+];
+var SECRET_KEY = /(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|ACCESS_?KEY)$/i;
+var defaultProbes = {
+  findBash,
+  checkSyntax(bash, file) {
+    const result = spawnSync2(bash, ["-n", file.replace(/\\/g, "/")], { encoding: "utf-8" });
+    if (result.error) return result.error.message;
+    return result.status === 0 ? null : (result.stderr || "syntax error").trim();
+  },
+  findPython() {
+    for (const py of ["python3", "python", "py"]) {
+      const result = spawnSync2(py, ["--version"], { encoding: "utf-8" });
+      if (!result.error && result.status === 0) return py;
+    }
+    return null;
+  }
+};
+function findBash() {
+  if (process.platform !== "win32") {
+    return spawnSync2("bash", ["--version"]).error ? null : "bash";
+  }
+  const override = process.env.CLAUDE_CODE_GIT_BASH_PATH;
+  if (override && fs18.existsSync(override)) return override;
+  const systemRoot = (process.env.SystemRoot ?? "C:\\Windows").toLowerCase();
+  for (const dir of (process.env.PATH ?? "").split(path21.delimiter)) {
+    const lower = dir.toLowerCase();
+    if (!dir || lower.startsWith(systemRoot) || lower.includes("windowsapps")) continue;
+    const candidate = path21.join(dir, "bash.exe");
+    if (fs18.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+function readJson(file) {
+  try {
+    return { value: JSON.parse(fs18.readFileSync(file, "utf-8")) };
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+function commandsOf(settings) {
+  const commands = [];
+  const hooks = settings.hooks ?? {};
+  for (const groups of Object.values(hooks)) {
+    for (const group of Array.isArray(groups) ? groups : []) {
+      for (const entry of group.hooks ?? []) {
+        if (typeof entry.command === "string") commands.push(entry.command);
+      }
+    }
+  }
+  const status = settings.statusLine;
+  if (typeof status?.command === "string") commands.push(status.command);
+  return commands;
+}
+function scriptsOf(command) {
+  const scripts = [...command.matchAll(/\.claude\/((?:hooks\/)?[\w.-]+\.(?:sh|py))/g)].map((m) => m[1]);
+  const python = command.match(/run-py\.sh"?\s+([\w.-]+\.py)/);
+  if (python) scripts.push(`hooks/${python[1]}`);
+  return scripts;
+}
+function checkSettings(claudeDir, cli) {
+  const file = path21.join(claudeDir, "settings.json");
+  if (!fs18.existsSync(file)) {
+    return {
+      check: { name: "settings.json", verdict: "fail", detail: "missing", fix: `Run \`${cli} update --here --force\`.` }
+    };
+  }
+  const { value, error } = readJson(file);
+  if (error || typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {
+      check: {
+        name: "settings.json",
+        verdict: "fail",
+        detail: `not valid JSON: ${error ?? "not an object"}`,
+        fix: "Fix the syntax by hand, or restore it from .claude.bak/."
+      }
+    };
+  }
+  return { check: { name: "settings.json", verdict: "ok", detail: "valid JSON" }, settings: value };
+}
+function checkHooks(claudeDir, settings, probes, cli) {
+  const commands = commandsOf(settings);
+  const scripts = [...new Set(commands.flatMap(scriptsOf))];
+  const checks = [];
+  const missing = scripts.filter((s) => !fs18.existsSync(path21.join(claudeDir, s)));
+  checks.push(
+    missing.length ? {
+      name: "hook scripts",
+      verdict: "fail",
+      detail: `settings.json runs files that are not there: ${missing.join(", ")}`,
+      fix: `If Arcane ships them, \`${cli} update --here\` restores them; otherwise remove those hooks from settings.json.`
+    } : { name: "hook scripts", verdict: "ok", detail: `${scripts.length} scripts found` }
+  );
+  const relative = commands.filter((c) => /^bash \.claude\/hooks\//.test(c));
+  if (relative.length) {
+    checks.push({
+      name: "hook paths",
+      verdict: "warn",
+      detail: `${relative.length} hooks use a relative path, which fails inside a worktree`,
+      fix: `Run \`${cli} update --here\`: it rewrites them with $CLAUDE_PROJECT_DIR.`
+    });
+  }
+  const bash = probes.findBash();
+  if (!bash) {
+    checks.push({
+      name: "bash",
+      verdict: "fail",
+      detail: "not found: no hook can run",
+      fix: process.platform === "win32" ? "Install Git for Windows, or set CLAUDE_CODE_GIT_BASH_PATH." : "Install bash."
+    });
+    return checks;
+  }
+  const broken = scripts.filter((s) => s.endsWith(".sh") && !missing.includes(s)).map((s) => [s, probes.checkSyntax(bash, path21.join(claudeDir, s))]).filter(([, error]) => error);
+  checks.push(
+    broken.length ? {
+      name: "hook syntax",
+      verdict: "fail",
+      detail: broken.map(([s, error]) => `${s}: ${error}`).join("; "),
+      fix: `Run \`${cli} update --here --force\` to restore the shipped version.`
+    } : { name: "hook syntax", verdict: "ok", detail: `bash parses every script (${bash})` }
+  );
+  return checks;
+}
+function checkPython(probes) {
+  const python = probes.findPython();
+  return python ? { name: "python", verdict: "ok", detail: `${python} starts` } : {
+    name: "python",
+    verdict: "warn",
+    detail: "no working Python: the guard and the session watch do nothing",
+    fix: "Install Python 3.9+ and make sure `python --version` works in Git Bash."
+  };
+}
+function checkContent(claudeDir, manifest, cli) {
+  const missing = [
+    ...(manifest.installed_skills ?? []).filter((s) => !fs18.existsSync(path21.join(claudeDir, "skills", s, "SKILL.md"))).map((s) => `skill ${s}`),
+    ...(manifest.installed_rules ?? []).filter((r) => !fs18.existsSync(path21.join(claudeDir, "rules", `${r}.md`))).map((r) => `rule ${r}`)
+  ];
+  if (!missing.length) {
+    return { name: "installed content", verdict: "ok", detail: "every skill and rule in the manifest is on disk" };
+  }
+  const shown = missing.slice(0, 5).join(", ") + (missing.length > 5 ? ` and ${missing.length - 5} more` : "");
+  return {
+    name: "installed content",
+    verdict: "fail",
+    detail: `missing from disk: ${shown}`,
+    fix: `Run \`${cli} update --here\` to restore them.`
+  };
+}
+function checkPermissions(claudeDir, settings, cli) {
+  const found = [];
+  for (const [file, data] of [
+    ["settings.json", settings],
+    ["settings.local.json", readJson(path21.join(claudeDir, "settings.local.json")).value]
+  ]) {
+    const permissions = data?.permissions;
+    const allow = Array.isArray(permissions?.allow) ? permissions.allow : [];
+    for (const rule of allow) {
+      if (typeof rule === "string" && DANGEROUS_ALLOWS.has(rule.trim())) found.push(`${file}: ${rule}`);
+    }
+    if (permissions?.defaultMode === "bypassPermissions") found.push(`${file}: defaultMode bypassPermissions`);
+  }
+  return found.length ? {
+    name: "permissions",
+    verdict: "warn",
+    detail: `rules that skip every confirmation: ${found.join(", ")}`,
+    fix: found.some((f) => f.endsWith("Bash(gh *)")) ? `Run \`${cli} update --here\` to narrow the old \`Bash(gh *)\`; narrow any other by hand, unless you mean it.` : "Narrow them by hand (e.g. `Bash(npm test*)` instead of `Bash(*)`), unless you mean it."
+  } : { name: "permissions", verdict: "ok", detail: "no allow rule covers a whole tool or a destructive command" };
+}
+function* strings(value, key = "") {
+  if (typeof value === "string") yield [key, value];
+  else if (Array.isArray(value)) for (const item of value) yield* strings(item, key);
+  else if (value && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) yield* strings(v, k);
+  }
+}
+function secretsIn(value) {
+  const found = /* @__PURE__ */ new Set();
+  for (const [key, text] of strings(value)) {
+    for (const [label, pattern] of SECRET_PATTERNS) if (pattern.test(text)) found.add(label);
+    if (SECRET_KEY.test(key) && text.length >= 8 && !/\$\{?[A-Za-z_]/.test(text)) found.add(`literal ${key}`);
+  }
+  return [...found];
+}
+function checkSecrets(target, claudeDir) {
+  const committed = [];
+  const local = [];
+  for (const [file, bucket] of [
+    [path21.join(claudeDir, "settings.json"), committed],
+    [path21.join(target, ".mcp.json"), committed],
+    [path21.join(claudeDir, "settings.local.json"), local]
+  ]) {
+    const { value } = readJson(file);
+    for (const label of secretsIn(value)) bucket.push(`${path21.relative(target, file).replace(/\\/g, "/")} (${label})`);
+  }
+  if (committed.length) {
+    return {
+      name: "secrets",
+      verdict: "fail",
+      detail: `credentials in files that get committed: ${committed.join(", ")}`,
+      fix: "Move them to environment variables and reference them as ${VAR}; rotate any that were pushed."
+    };
+  }
+  if (local.length) {
+    return {
+      name: "secrets",
+      verdict: "warn",
+      detail: `credentials in settings.local.json: ${local.join(", ")}`,
+      fix: "It is not committed, but an environment variable keeps it out of backups and shares."
+    };
+  }
+  return { name: "secrets", verdict: "ok", detail: "no credentials found in settings or .mcp.json" };
+}
+function diagnose(target, probes = defaultProbes) {
+  const claudeDir = path21.join(target, ".claude");
+  const cli = cliInvocation();
+  const manifest = readManifest(target);
+  if (!manifest) {
+    return [
+      {
+        name: "installation",
+        verdict: "fail",
+        detail: "no .claude/arcane-manifest.json",
+        fix: `Run \`${cli} install <profile>\`.`
+      }
+    ];
+  }
+  const checks = [
+    { name: "installation", verdict: "ok", detail: `Arcane ${manifest.arcane_version}, ${manifest.profiles.join(" + ")}` }
+  ];
+  const { check, settings } = checkSettings(claudeDir, cli);
+  checks.push(check);
+  if (settings) checks.push(...checkHooks(claudeDir, settings, probes, cli));
+  checks.push(checkPython(probes), checkContent(claudeDir, manifest, cli));
+  if (settings) checks.push(checkPermissions(claudeDir, settings, cli));
+  checks.push(checkSecrets(target, claudeDir));
+  return checks;
+}
+var ICONS = { ok: chalk11.green("\u2713"), warn: chalk11.yellow("!"), fail: chalk11.red("\u2717") };
+async function doctorCommand(opts = {}) {
+  const target = path21.resolve(opts.target ?? process.cwd());
+  const checks = diagnose(target);
+  console.log(chalk11.bold(`
+=== Arcane Doctor: ${target} ===
+`));
+  for (const check of checks) {
+    console.log(`  ${ICONS[check.verdict]} ${chalk11.bold(check.name)}: ${check.detail}`);
+    if (check.fix && check.verdict !== "ok") console.log(chalk11.dim(`      fix: ${check.fix}`));
+  }
+  const fails = checks.filter((c) => c.verdict === "fail").length;
+  const warns = checks.filter((c) => c.verdict === "warn").length;
+  console.log(
+    `
+  ${fails ? chalk11.red(`${fails} failed`) : chalk11.green("nothing failed")}${warns ? chalk11.yellow(`, ${warns} warnings`) : ""}
+`
+  );
+  if (fails) process.exitCode = 1;
+}
+
+// src/update-check.ts
+import fs19 from "fs";
+import path22 from "path";
+import chalk12 from "chalk";
 function checkFile() {
-  return path21.join(arcaneHome(), "last-check.json");
+  return path22.join(arcaneHome(), "last-check.json");
 }
 var CHECK_INTERVAL_MS = 4 * 60 * 60 * 1e3;
 var GITHUB_OWNER2 = "SebastianLuser";
@@ -3443,23 +3734,23 @@ async function checkForUpdates(opts = {}) {
 function printUpdateNotice(result) {
   if (result.cli_update_available) {
     console.log(
-      chalk11.yellow(
+      chalk12.yellow(
         `
   Arcane CLI update: ${result.cli_version} \u2192 ${result.latest_cli_version}`
       )
     );
     const how = isGloballyInstalled() ? `  Run: npm install -g ${PACKAGE_NAME3}@latest` : `  You are on an older CLI. Latest: ${PACKAGE_NAME3}@${result.latest_cli_version}`;
-    console.log(chalk11.dim(how));
+    console.log(chalk12.dim(how));
   }
   if (result.content_update_available ?? true) {
     console.log(
-      chalk11.yellow(
+      chalk12.yellow(
         `
   Arcane content update: ${result.local_version} \u2192 ${result.remote_sha}`
       )
     );
     console.log(
-      chalk11.dim(`  Run: ${cliInvocation()} update (--dry-run to preview)`)
+      chalk12.dim(`  Run: ${cliInvocation()} update (--dry-run to preview)`)
     );
   }
   console.log("");
@@ -3502,8 +3793,8 @@ async function getLatestNpmVersion() {
 function readCachedCheck() {
   try {
     const file = checkFile();
-    if (!fs18.existsSync(file)) return null;
-    return JSON.parse(fs18.readFileSync(file, "utf-8"));
+    if (!fs19.existsSync(file)) return null;
+    return JSON.parse(fs19.readFileSync(file, "utf-8"));
   } catch {
     return null;
   }
@@ -3511,11 +3802,11 @@ function readCachedCheck() {
 function writeCachedCheck(result) {
   try {
     const file = checkFile();
-    const dir = path21.dirname(file);
-    if (!fs18.existsSync(dir)) {
-      fs18.mkdirSync(dir, { recursive: true });
+    const dir = path22.dirname(file);
+    if (!fs19.existsSync(dir)) {
+      fs19.mkdirSync(dir, { recursive: true });
     }
-    fs18.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
+    fs19.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
   } catch {
   }
 }
@@ -3552,6 +3843,9 @@ program.command("list").description("List all available profiles and skills.").a
 program.command("status").description("Show current Arcane installation status.").action(async () => {
   await statusCommand();
 });
+program.command("doctor").description("Check that this project's Arcane install works: hooks, settings, content, permissions, secrets.").option("-t, --target <dir>", "Project directory", process.cwd()).action(async (opts) => {
+  await doctorCommand(opts);
+});
 program.command("update").description(
   "Update everything: the global npm package + all registered Arcane installations."
 ).option("-q, --quiet", "Quiet mode for hook usage").option("-n, --dry-run", "Show what would change without applying").option("-f, --force", "Overwrite even locally modified files").option("--here", "Update only the current repo (legacy per-repo behavior)").option("--no-self-update", "Skip updating the global npm package").option("--source <source>", "Content source: auto, github, or bundled", "auto").action(async (opts) => {

package/docs/USER-GUIDE.md

@@ -141,6 +141,23 @@ npx claude-code-arcane status
 
 Shows installed profiles, skill count, rules, agents, installation date, and worktree info.
 
+### `npx claude-code-arcane doctor` — Check that the install works
+
+```bash
+npx claude-code-arcane doctor
+npx claude-code-arcane doctor --target ../other-project
+```
+
+Read-only. Each check prints ✓, `!` (warning) or ✗ (failure) with a fix:
+
+- **Hooks:** every script `settings.json` runs exists and parses with bash; hooks still wired with a relative path, which fails inside a worktree.
+- **Settings:** `settings.json` is valid JSON.
+- **Content:** every skill and rule in the manifest is on disk.
+- **Python:** one starts, since the guard and the session watch need it.
+- **Permissions and secrets:** allow rules that skip every confirmation (`Bash(*)`, `Bash(gh *)`, `bypassPermissions`), and credentials in `settings.json`, `settings.local.json` or `.mcp.json`.
+
+It exits with code 1 when a check fails.
+
 ### `npx claude-code-arcane update` — Check for updates
 
 ```bash

package/package.json

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