@phuc1403/musketeer 0.4.0 → 0.6.0

package/template/.claude/hooks/block-unsafe-adr-title.cjs

@@ -1,70 +1,72 @@
-#!/usr/bin/env node
-// PreToolUse guard: block an `adr new` title that adr-tools' own script cannot
-// handle safely.
-//
-// adr-new builds the ADR file with `sed -e "s|TITLE|$title|"`, substituting the
-// title in unescaped and using `|` as the delimiter. Two failure modes follow,
-// verified directly against /usr/bin/adr-new:
-//   - `|` in the title breaks sed's own syntax: it exits 1, but only after
-//     creating a zero-byte ADR file that already burned that number.
-//   - `&` in a sed replacement means "the whole match" — it does NOT error.
-//     "Use Kafka & Queues" silently becomes the title "Use Kafka TITLE Queues",
-//     written straight into the file and the generated index.
-// A title starting with `-` is a third case: adr-new parses its own flags with
-// getopts, so without a `--` separator the title is read as an unknown option
-// and the ADR is silently never created (clean failure, still worth catching
-// early with a clearer reason than adr-tools' own "no title given").
-//
-// Blocking, not warning: `|` wastes an ADR number and `&` corrupts data with no
-// error at all, so there is nothing later in the pipeline that will catch it.
-
-let raw = "";
-process.stdin.on("data", (chunk) => (raw += chunk));
-process.stdin.on("end", () => {
-  let input;
-  try {
-    input = JSON.parse(raw || "{}");
-  } catch {
-    process.exit(0); // unparseable payload — fail open, don't block legit work
-  }
-
-  const command = (input && input.tool_input && input.tool_input.command) || "";
-  if (!/\badr\s+new\b/.test(command)) process.exit(0);
-
-  // The skill always places `--` immediately before a quoted title. Extract
-  // that argument; anything else about the command's shape is not this hook's
-  // concern.
-  const afterDashDash = command.match(/--\s+(["'])((?:(?!\1).)*)\1/);
-  const title = afterDashDash ? afterDashDash[2] : null;
-
-  let reason = null;
-  if (!afterDashDash) {
-    reason =
-      "no `--` before the title (or no quoted title found after it). Without `--`, " +
-      "adr-new's getopts can read a title starting with `-` as a flag and silently " +
-      "create nothing. Always: adr new [-s STEM]... -- \"Title\".";
-  } else if (title.includes("|")) {
-    reason =
-      "the title contains `|`. adr-new substitutes it into `sed -e \"s|TITLE|$title|\"`, " +
-      "using `|` as sed's own delimiter — this breaks sed's syntax and exits non-zero, " +
-      "but only after creating a zero-byte ADR file that already consumed that number.";
-  } else if (title.includes("&")) {
-    reason =
-      "the title contains `&`. In a sed replacement `&` means \"the whole match\", so " +
-      "adr-new writes it as literal text into the title (e.g. \"Use Kafka & Queues\" " +
-      "becomes \"Use Kafka TITLE Queues\") and exits 0 — nothing else will catch this.";
-  }
-
-  if (reason) {
-    process.stdout.write(
-      JSON.stringify({
-        hookSpecificOutput: {
-          hookEventName: "PreToolUse",
-          permissionDecision: "deny",
-          permissionDecisionReason: `Refusing this \`adr new\` call: ${reason} Rename the title and retry.`,
-        },
-      })
-    );
-  }
-  process.exit(0);
-});
+#!/usr/bin/env node
+// PreToolUse guard: block an `adr new` title that adr-tools' own script cannot
+// handle safely.
+//
+// adr-new builds the ADR file with `sed -e "s|TITLE|$title|"`, substituting the
+// title in unescaped and using `|` as the delimiter. Two failure modes follow,
+// verified directly against /usr/bin/adr-new:
+//   - `|` in the title breaks sed's own syntax: it exits 1, but only after
+//     creating a zero-byte ADR file that already burned that number.
+//   - `&` in a sed replacement means "the whole match" — it does NOT error.
+//     "Use Kafka & Queues" silently becomes the title "Use Kafka TITLE Queues",
+//     written straight into the file and the generated index.
+// A title starting with `-` is a third case: adr-new parses its own flags with
+// getopts, so without a `--` separator the title is read as an unknown option
+// and the ADR is silently never created (clean failure, still worth catching
+// early with a clearer reason than adr-tools' own "no title given").
+//
+// Blocking, not warning: `|` wastes an ADR number and `&` corrupts data with no
+// error at all, so there is nothing later in the pipeline that will catch it.
+
+const { invokesAdr } = require("./lib/adr/command-scan.cjs");
+
+let raw = "";
+process.stdin.on("data", (chunk) => (raw += chunk));
+process.stdin.on("end", () => {
+  let input;
+  try {
+    input = JSON.parse(raw || "{}");
+  } catch {
+    process.exit(0); // unparseable payload — fail open, don't block legit work
+  }
+
+  const command = (input && input.tool_input && input.tool_input.command) || "";
+  if (!invokesAdr(command, "new")) process.exit(0);
+
+  // The skill always places `--` immediately before a quoted title. Extract
+  // that argument; anything else about the command's shape is not this hook's
+  // concern.
+  const afterDashDash = command.match(/--\s+(["'])((?:(?!\1).)*)\1/);
+  const title = afterDashDash ? afterDashDash[2] : null;
+
+  let reason = null;
+  if (!afterDashDash) {
+    reason =
+      "no `--` before the title (or no quoted title found after it). Without `--`, " +
+      "adr-new's getopts can read a title starting with `-` as a flag and silently " +
+      "create nothing. Always: adr new [-s STEM]... -- \"Title\".";
+  } else if (title.includes("|")) {
+    reason =
+      "the title contains `|`. adr-new substitutes it into `sed -e \"s|TITLE|$title|\"`, " +
+      "using `|` as sed's own delimiter — this breaks sed's syntax and exits non-zero, " +
+      "but only after creating a zero-byte ADR file that already consumed that number.";
+  } else if (title.includes("&")) {
+    reason =
+      "the title contains `&`. In a sed replacement `&` means \"the whole match\", so " +
+      "adr-new writes it as literal text into the title (e.g. \"Use Kafka & Queues\" " +
+      "becomes \"Use Kafka TITLE Queues\") and exits 0 — nothing else will catch this.";
+  }
+
+  if (reason) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: `Refusing this \`adr new\` call: ${reason} Rename the title and retry.`,
+        },
+      })
+    );
+  }
+  process.exit(0);
+});

package/template/.claude/hooks/init-adr-dir.cjs

@@ -1,110 +1,153 @@
-#!/usr/bin/env node
-// PreToolUse guard: set up `.adr-dir` before the first `adr new` in a project,
-// so the agent never has to pick between `adr init` and a hand-written file.
-//
-// Two setup paths, and picking the wrong one is destructive:
-//   - fresh (no `.adr-dir`, no numbered ADRs yet): `adr init docs/adr` is safe —
-//     it creates docs/adr/, writes `.adr-dir`, and adds a baseline ADR.
-//   - migration (numbered ADRs already exist, but no `.adr-dir`): `adr init`
-//     would ALSO add that baseline ADR, burning the next real number. The fix
-//     is a plain `.adr-dir` file with no tool call: `printf 'docs/adr\n' > .adr-dir`.
-// Already initialized: nothing to do, both paths are a no-op.
-//
-// Runs the setup itself (as a side effect) before allowing `adr new` through,
-// and denies a *direct* `adr init` call whenever running it would be wrong —
-// already initialized, or migration state — since either would burn a number.
-// Anything it does is echoed to stdout so it stays visible in the transcript.
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const ADR_DIR = 'docs/adr';
-const ADR_DIR_FILE = path.join(root, '.adr-dir');
-const ADR_FILE = /^\d+-.*\.md$/;
-
-function allow(message) {
-  if (message) process.stdout.write(message + '\n');
-  process.exit(0);
-}
-
-function deny(reason) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'deny',
-        permissionDecisionReason: reason,
-      },
-    })
-  );
-  process.exit(0);
-}
-
-function isInitialized() {
-  try {
-    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() !== '';
-  } catch {
-    return false;
-  }
-}
-
-function hasNumberedAdrs() {
-  try {
-    return fs.readdirSync(path.join(root, ADR_DIR)).some((f) => ADR_FILE.test(f));
-  } catch {
-    return false; // directory doesn't exist yet -> nothing to migrate
-  }
-}
-
-function runAdrInit() {
-  const shell = process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash';
-  return spawnSync(shell, ['-c', `adr init ${ADR_DIR}`], { cwd: root, encoding: 'utf8' });
-}
-
-function main() {
-  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
-  const command = payload?.tool_input?.command || '';
-  const isInit = /\badr\s+init\b/.test(command);
-  const isNew = /\badr\s+new\b/.test(command);
-  if (!isInit && !isNew) return allow();
-
-  if (isInitialized()) {
-    if (isInit) {
-      return deny(
-        '.adr-dir already exists — do not run `adr init` again, it would add a duplicate ' +
-          'baseline ADR and burn the next number. Run `adr new` directly.'
-      );
-    }
-    return allow(); // adr new, already set up: nothing to do
-  }
-
-  if (hasNumberedAdrs()) {
-    // Migration: numbered ADRs exist but `.adr-dir` does not. `adr init` would
-    // still add a baseline ADR here, so it is never the right command.
-    if (isInit) {
-      return deny(
-        'Numbered ADRs already exist without `.adr-dir` — this is a migration, not a fresh ' +
-          'project. `adr init` would add a duplicate baseline ADR and burn the next number. ' +
-          'Run `adr new` directly; `.adr-dir` is set up automatically.'
-      );
-    }
-    fs.writeFileSync(ADR_DIR_FILE, `${ADR_DIR}\n`);
-    return allow(`Migration detected: wrote .adr-dir (${ADR_DIR}) by hand, no baseline ADR added.`);
-  }
-
-  // Fresh project.
-  if (isInit) return allow(); // the agent's own `adr init` call is correct here — let it run
-  const res = runAdrInit();
-  if (res.error || res.status !== 0) {
-    return allow(`Could not run \`adr init ${ADR_DIR}\` (${res.error?.message || res.stderr}); letting the original command run and fail with its own error.`);
-  }
-  return allow(`Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).`);
-}
-
-try {
-  main();
-} catch {
-  allow(); // fail open
-}
+#!/usr/bin/env node
+// PreToolUse guard: set up `.adr-dir` before the first `adr new` in a project,
+// so the agent never has to pick between `adr init` and a hand-written file.
+//
+// Two setup paths, and picking the wrong one is destructive:
+//   - fresh (no `.adr-dir`, no numbered ADRs yet): `adr init docs/adr` is safe —
+//     it creates docs/adr/, writes `.adr-dir`, and adds a baseline ADR.
+//   - migration (numbered ADRs already exist, but no `.adr-dir`): `adr init`
+//     would ALSO add that baseline ADR, burning the next real number. The fix
+//     is a plain `.adr-dir` file with no tool call: `printf 'docs/adr\n' > .adr-dir`.
+// Already initialized: nothing to do, both paths are a no-op.
+//
+// Runs the setup itself (as a side effect) before allowing `adr new` through,
+// and denies a *direct* `adr init` call whenever running it would be wrong —
+// already initialized, or migration state — since either would burn a number.
+// Anything it does is echoed to stdout so it stays visible in the transcript.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { invokesAdr } = require('./lib/adr/command-scan.cjs');
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const ADR_DIR = 'docs/adr';
+const ADR_DIR_FILE = path.join(root, '.adr-dir');
+const ADR_FILE = /^\d+-.*\.md$/;
+
+function allow(message) {
+  if (message) process.stdout.write(message + '\n');
+  process.exit(0);
+}
+
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    })
+  );
+  process.exit(0);
+}
+
+function readAdrDir() {
+  try {
+    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function isInitialized() {
+  try {
+    return fs.readFileSync(ADR_DIR_FILE, 'utf8').trim() !== '';
+  } catch {
+    return false;
+  }
+}
+
+function hasNumberedAdrs() {
+  try {
+    return fs.readdirSync(path.join(root, ADR_DIR)).some((f) => ADR_FILE.test(f));
+  } catch {
+    return false; // directory doesn't exist yet -> nothing to migrate
+  }
+}
+
+function runAdrInit() {
+  const shell = process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash';
+  return spawnSync(shell, ['-c', `adr init ${ADR_DIR}`], { cwd: root, encoding: 'utf8' });
+}
+
+// Where adr-tools itself thinks the ADRs go. `_adr_dir` is the resolver every
+// adr subcommand uses, so asking it directly is the only honest answer.
+function resolvedAdrDir() {
+  const shell = process.env.CLAUDE_CODE_GIT_BASH_PATH || 'bash';
+  const res = spawnSync(shell, ['-c', '_adr_dir'], { cwd: root, encoding: 'utf8' });
+  if (res.error || res.status !== 0) return null;
+  const out = (res.stdout || '').trim();
+  return out || null;
+}
+
+// adr-tools resolves the directory with an unquoted `[` test, so a path holding
+// a space splits into too many arguments, the search loop is skipped, and the
+// script falls through to its `doc/adr` default. It prints the wrong answer on
+// stdout and exits 0, so the ADR lands in a directory nothing else looks at and
+// nothing reports a problem. Refuse the call instead of losing the record.
+function denyOnDirMismatch() {
+  const declared = readAdrDir();
+  const resolved = resolvedAdrDir();
+  if (!declared || !resolved || declared === resolved) return;
+
+  deny(
+    `adr-tools resolves the ADR directory to "${resolved}", but .adr-dir says "${declared}". ` +
+      `The new ADR would be written to "${resolved}", where the index hook never looks. ` +
+      (/\s/.test(root)
+        ? `This project's path contains a space (${root}), which is the known cause: ` +
+          "adr-tools' `_adr_dir` leaves its path test unquoted. "
+        : '') +
+      'Fix the quoting in adr-tools\' `_adr_dir`, or move the project to a path with no spaces.'
+  );
+}
+
+function main() {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const command = payload?.tool_input?.command || '';
+  const isInit = invokesAdr(command, 'init');
+  const isNew = invokesAdr(command, 'new');
+  if (!isInit && !isNew) return allow();
+
+  if (isInitialized()) {
+    if (isInit) {
+      return deny(
+        '.adr-dir already exists — do not run `adr init` again, it would add a duplicate ' +
+          'baseline ADR and burn the next number. Run `adr new` directly.'
+      );
+    }
+    denyOnDirMismatch(); // exits when adr-tools would write somewhere else
+    return allow(); // adr new, already set up: nothing to do
+  }
+
+  if (hasNumberedAdrs()) {
+    // Migration: numbered ADRs exist but `.adr-dir` does not. `adr init` would
+    // still add a baseline ADR here, so it is never the right command.
+    if (isInit) {
+      return deny(
+        'Numbered ADRs already exist without `.adr-dir` — this is a migration, not a fresh ' +
+          'project. `adr init` would add a duplicate baseline ADR and burn the next number. ' +
+          'Run `adr new` directly; `.adr-dir` is set up automatically.'
+      );
+    }
+    fs.writeFileSync(ADR_DIR_FILE, `${ADR_DIR}\n`);
+    denyOnDirMismatch();
+    return allow(`Migration detected: wrote .adr-dir (${ADR_DIR}) by hand, no baseline ADR added.`);
+  }
+
+  // Fresh project.
+  if (isInit) return allow(); // the agent's own `adr init` call is correct here — let it run
+  const res = runAdrInit();
+  if (res.error || res.status !== 0) {
+    return allow(`Could not run \`adr init ${ADR_DIR}\` (${res.error?.message || res.stderr}); letting the original command run and fail with its own error.`);
+  }
+  denyOnDirMismatch();
+  return allow(`Fresh project: ran \`adr init ${ADR_DIR}\` (creates the baseline ADR).`);
+}
+
+try {
+  main();
+} catch {
+  allow(); // fail open
+}

package/template/.claude/hooks/inject-adr-env.cjs

@@ -1,82 +1,83 @@
-#!/usr/bin/env node
-// PreToolUse guard: inject the env vars every `adr new` call needs, so the
-// agent can write a bare `adr new -- "Title"` and get a correct command.
-//
-//   VISUAL=true EDITOR=true  — without them an ambient EDITOR opens an
-//     interactive editor and hangs the session (adr-new always shells out to
-//     $VISUAL/$EDITOR to "edit" the new file).
-//   ADR_TEMPLATE=...adr-template.md — points adr-new at this skill's template
-//     instead of adr-tools' own bundled default.
-//
-// Uses PreToolUse's `updatedInput` (not just allow/deny) to rewrite the
-// command before it runs. Only fills in vars that are missing — an assignment
-// the agent already wrote (any value, even a deliberately different template)
-// is left alone. Silent no-op if all three are already present.
-//
-// Safety: a title that happens to contain the literal text "adr new" could
-// make the matching regex fire inside a quoted string. Guarded by counting
-// quote characters before each match — an odd count means "inside an open
-// string", and that occurrence is left untouched rather than risk corrupting
-// the title.
-
-const fs = require('fs');
-
-const DEFAULTS = [
-  ['ADR_TEMPLATE', '.claude/skills/adr-writer/references/adr-template.md'],
-  ['VISUAL', 'true'],
-  ['EDITOR', 'true'],
-];
-
-// boundary/start, leading whitespace, any existing KEY=value prefix, `adr new`.
-const ADR_NEW_RE = /(^|[;&|\n])([ \t]*)((?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)[ \t]+)*)(adr[ \t]+new\b)/g;
-
-function existingVars(prefix) {
-  const names = new Set();
-  const re = /([A-Za-z_][A-Za-z0-9_]*)=/g;
-  let m;
-  while ((m = re.exec(prefix))) names.add(m[1]);
-  return names;
-}
-
-function isInsideQuotes(command, index) {
-  const before = command.slice(0, index);
-  const dq = (before.match(/"/g) || []).length;
-  const sq = (before.match(/'/g) || []).length;
-  return dq % 2 === 1 || sq % 2 === 1;
-}
-
-function main() {
-  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
-  const command = payload?.tool_input?.command || '';
-  if (!/\badr\s+new\b/.test(command)) return;
-
-  let changed = false;
-  const updated = command.replace(ADR_NEW_RE, (whole, boundary, ws, existingPrefix, adrNew, offset) => {
-    if (isInsideQuotes(command, offset)) return whole;
-    const present = existingVars(existingPrefix);
-    const missing = DEFAULTS.filter(([name]) => !present.has(name));
-    if (missing.length === 0) return whole;
-    changed = true;
-    const injected = missing.map(([name, value]) => `${name}=${value}`).join(' ');
-    return `${boundary}${ws}${injected} ${existingPrefix}${adrNew}`;
-  });
-  if (!changed) return;
-
-  process.stdout.write(
-    JSON.stringify({
-      systemMessage: 'Added missing VISUAL/EDITOR/ADR_TEMPLATE env vars before `adr new`.',
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'allow',
-        updatedInput: { command: updated },
-      },
-    })
-  );
-}
-
-try {
-  main();
-} catch {
-  /* fail open: leave the command untouched */
-}
-process.exit(0);
+#!/usr/bin/env node
+// PreToolUse guard: inject the env vars every `adr new` call needs, so the
+// agent can write a bare `adr new -- "Title"` and get a correct command.
+//
+//   VISUAL=true EDITOR=true  — without them an ambient EDITOR opens an
+//     interactive editor and hangs the session (adr-new always shells out to
+//     $VISUAL/$EDITOR to "edit" the new file).
+//   ADR_TEMPLATE=...adr-template.md — points adr-new at this skill's template
+//     instead of adr-tools' own bundled default.
+//
+// Uses PreToolUse's `updatedInput` (not just allow/deny) to rewrite the
+// command before it runs. Only fills in vars that are missing — an assignment
+// the agent already wrote (any value, even a deliberately different template)
+// is left alone. Silent no-op if all three are already present.
+//
+// Safety: a title that happens to contain the literal text "adr new" could
+// make the matching regex fire inside a quoted string. Guarded by counting
+// quote characters before each match — an odd count means "inside an open
+// string", and that occurrence is left untouched rather than risk corrupting
+// the title.
+
+const fs = require('fs');
+const {
+  invocationRe,
+  isInsideQuotes,
+  isInsideHeredoc,
+  invokesAdr,
+} = require('./lib/adr/command-scan.cjs');
+
+const DEFAULTS = [
+  ['ADR_TEMPLATE', '.claude/skills/adr-writer/references/adr-template.md'],
+  ['VISUAL', 'true'],
+  ['EDITOR', 'true'],
+];
+
+function existingVars(prefix) {
+  const names = new Set();
+  const re = /([A-Za-z_][A-Za-z0-9_]*)=/g;
+  let m;
+  while ((m = re.exec(prefix))) names.add(m[1]);
+  return names;
+}
+
+function main() {
+  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const command = payload?.tool_input?.command || '';
+  if (!invokesAdr(command, 'new')) return;
+
+  let changed = false;
+  const updated = command.replace(invocationRe('new'), (whole, boundary, ws, existingPrefix, adrNew, offset) => {
+    // Both guards, for the same reason the deny hooks use them: a heredoc body
+    // is documentation being written, and injecting env vars into it would
+    // rewrite the file's contents rather than the command.
+    // `offset` is the boundary character; step past it to the word `adr`.
+    const at = offset + boundary.length + ws.length + existingPrefix.length;
+    if (isInsideQuotes(command, at) || isInsideHeredoc(command, at)) return whole;
+    const present = existingVars(existingPrefix);
+    const missing = DEFAULTS.filter(([name]) => !present.has(name));
+    if (missing.length === 0) return whole;
+    changed = true;
+    const injected = missing.map(([name, value]) => `${name}=${value}`).join(' ');
+    return `${boundary}${ws}${injected} ${existingPrefix}${adrNew}`;
+  });
+  if (!changed) return;
+
+  process.stdout.write(
+    JSON.stringify({
+      systemMessage: 'Added missing VISUAL/EDITOR/ADR_TEMPLATE env vars before `adr new`.',
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: { command: updated },
+      },
+    })
+  );
+}
+
+try {
+  main();
+} catch {
+  /* fail open: leave the command untouched */
+}
+process.exit(0);