@alecsibilia/luca 13.0.0-alpha.1

package/dist/chunks/hook.mjs

@@ -0,0 +1,696 @@
+import { defineCommand } from 'citty';
+import { c as coarsePhaseOf, a as classifyWritePath, A as AUDIT_PATH_PATTERN, W as WAVE_FILE_RE } from '../shared/luca.CRmaAfXR.mjs';
+import { l as loadCurrentState, r as resolveActiveSlug } from '../shared/luca.CrXzXueR.mjs';
+import 'node:fs';
+import 'node:fs/promises';
+import 'node:path';
+import { S as STEP_ARTIFACTS } from '../shared/luca.B3Mimc0P.mjs';
+import { p as phasePathFor } from '../shared/luca.TSMg1t7I.mjs';
+import 'node:crypto';
+import 'node:module';
+import 'node:url';
+import 'node:child_process';
+import { parse } from 'shell-quote';
+import 'zod';
+import 'node:os';
+
+const STAGE_TOOL_MATRIX = {
+  IDLE: {
+    "code-write": true,
+    "planning-write-general": true,
+    "planning-write-audit": true,
+    "bash-readonly": true,
+    "bash-mutate": true,
+    "bash-commit": true,
+    "luca-write": true
+  },
+  PLANNING: {
+    "code-write": false,
+    "planning-write-general": true,
+    "planning-write-audit": true,
+    "bash-readonly": true,
+    "bash-mutate": false,
+    "bash-commit": false,
+    "luca-write": true
+  },
+  EXECUTING: {
+    "code-write": true,
+    "planning-write-general": true,
+    "planning-write-audit": true,
+    "bash-readonly": true,
+    "bash-mutate": true,
+    "bash-commit": false,
+    "luca-write": true
+  },
+  REVIEWING: {
+    "code-write": false,
+    // General .luca/ writes blocked — reviewers must write via the
+    // audit MCP tool, which lands at .luca/phases/<slug>/audits/<reviewer>.md
+    "planning-write-general": false,
+    "planning-write-audit": true,
+    "bash-readonly": true,
+    "bash-mutate": false,
+    "bash-commit": false,
+    "luca-write": true
+  },
+  FINALIZING: {
+    "code-write": false,
+    "planning-write-general": true,
+    "planning-write-audit": true,
+    "bash-readonly": true,
+    "bash-mutate": false,
+    "bash-commit": true,
+    "luca-write": true
+  }
+};
+
+function isToolAllowed({
+  phase,
+  category
+}) {
+  return STAGE_TOOL_MATRIX[phase][category];
+}
+
+const READONLY_COMMANDS = /* @__PURE__ */ new Set([
+  "ls",
+  "cat",
+  "grep",
+  "find",
+  "pwd",
+  "head",
+  "tail",
+  "wc",
+  "basename",
+  "dirname",
+  "type",
+  "which",
+  "echo",
+  "printf",
+  "true",
+  "false"
+]);
+const GIT_READONLY_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "status",
+  "log",
+  "diff",
+  "show",
+  "branch",
+  "remote",
+  "rev-parse",
+  "rev-list",
+  "config",
+  "describe",
+  "blame"
+]);
+const GIT_COMMIT_SUBCOMMANDS = /* @__PURE__ */ new Set(["commit", "push", "tag"]);
+const GIT_MUTATE_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "add",
+  "mv",
+  "rm",
+  "checkout",
+  "reset",
+  "restore",
+  "switch",
+  "stash",
+  "merge",
+  "rebase",
+  "cherry-pick",
+  "apply",
+  "clean",
+  "fetch",
+  "pull",
+  "clone",
+  "init",
+  "gc",
+  "prune"
+]);
+const GH_READONLY_PATTERNS = [
+  ["pr", "view"],
+  ["pr", "list"],
+  ["pr", "checks"],
+  ["pr", "status"],
+  ["pr", "diff"],
+  ["issue", "view"],
+  ["issue", "list"],
+  ["repo", "view"],
+  ["release", "list"],
+  ["release", "view"],
+  ["api", "GET"]
+];
+const GH_COMMIT_PATTERNS = [
+  ["pr", "create"],
+  ["pr", "merge"],
+  ["pr", "close"],
+  ["pr", "comment"],
+  ["issue", "create"],
+  ["issue", "close"],
+  ["issue", "comment"],
+  ["release", "create"]
+];
+const MUTATE_COMMANDS = /* @__PURE__ */ new Set([
+  "cp",
+  "mv",
+  "rm",
+  "mkdir",
+  "rmdir",
+  "touch",
+  "ln",
+  "install",
+  "unlink",
+  "chmod",
+  "chown",
+  "sed",
+  "awk",
+  // can have -i side effects via gsub('foo', val, file) — conservative
+  "patch",
+  "tar",
+  "unzip",
+  "zip"
+]);
+const PKG_MUTATE_PATTERNS = [
+  ["bun", "install"],
+  ["bun", "add"],
+  ["bun", "remove"],
+  ["bun", "update"],
+  ["bun", "run", "build"],
+  ["bunx"],
+  // generic — could mutate via build
+  ["npm", "install"],
+  ["npm", "i"],
+  ["npm", "run", "build"],
+  ["yarn", "install"],
+  ["yarn", "add"],
+  ["pnpm", "install"],
+  ["pnpm", "add"]
+];
+const ALWAYS_DENIED_COMMANDS = /* @__PURE__ */ new Set(["eval", "source", "."]);
+const LUCA_READ_VERBS = /* @__PURE__ */ new Set([
+  "read",
+  "current",
+  "list",
+  "guard",
+  "filter-stale",
+  "detect-convergence",
+  "regression-check"
+]);
+const LUCA_NOUN_VERBS = {
+  state: /* @__PURE__ */ new Set(["read", "advance"]),
+  phase: /* @__PURE__ */ new Set(["current"]),
+  roadmap: /* @__PURE__ */ new Set(["read", "create"]),
+  preferences: /* @__PURE__ */ new Set(["read", "write"]),
+  todo: /* @__PURE__ */ new Set(["add", "list", "update"]),
+  "pr-review": /* @__PURE__ */ new Set([
+    "filter-stale",
+    "detect-convergence",
+    "regression-check"
+  ]),
+  repo: /* @__PURE__ */ new Set(["cleanup-apply"]),
+  checks: /* @__PURE__ */ new Set(["run"]),
+  branch: /* @__PURE__ */ new Set(["guard"]),
+  workflow: /* @__PURE__ */ new Set(["reset"]),
+  confidence: /* @__PURE__ */ new Set(["log"])
+};
+function classifyLucaCommand(rest) {
+  const noun = rest.find((t) => !t.startsWith("-"));
+  if (!noun) return void 0;
+  const verbs = LUCA_NOUN_VERBS[noun];
+  if (!verbs) return void 0;
+  const afterNoun = rest.slice(rest.indexOf(noun) + 1);
+  const verb = afterNoun.find((t) => !t.startsWith("-"));
+  if (!verb || !verbs.has(verb)) {
+    return "luca-write";
+  }
+  return LUCA_READ_VERBS.has(verb) ? "bash-readonly" : "luca-write";
+}
+const SEVERITY = {
+  "bash-readonly": 0,
+  // `luca-write` and `bash-mutate` share a tier: both are "mutating" but
+  // neither escalates past a commit. In a mixed pipeline `maxCategory`
+  // keeps the first-seen at equal severity — acceptable, mixed
+  // `luca`+mutate command strings are not a real pattern.
+  "luca-write": 1,
+  "bash-mutate": 1,
+  "bash-commit": 2,
+  denied: 3
+};
+function maxCategory(a, b) {
+  return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+function splitIntoSubcommands(entries) {
+  const subcommands = [];
+  let current = { tokens: [] };
+  let i = 0;
+  while (i < entries.length) {
+    const t = entries[i];
+    if (typeof t === "string") {
+      current.tokens.push(t);
+      i++;
+      continue;
+    }
+    if ("op" in t) {
+      const op = String(t.op);
+      if (op === ">" || op === ">>" || op === "&>") {
+        const target = entries[i + 1];
+        current.redirect = {
+          op,
+          target: typeof target === "string" ? target : void 0
+        };
+        i += 2;
+        continue;
+      }
+      if (op === ";" || op === "&&" || op === "||" || op === "|") {
+        current.follower = op;
+        subcommands.push(current);
+        current = { tokens: [] };
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (typeof t === "object" && "pattern" in t) {
+      current.tokens.push(t.pattern);
+    }
+    i++;
+  }
+  subcommands.push(current);
+  return subcommands;
+}
+function classifySubcommand(sub) {
+  const tokens = sub.tokens;
+  if (tokens.length === 0) {
+    return { category: "bash-readonly", targetPaths: [] };
+  }
+  const cmd = tokens[0];
+  const rest = tokens.slice(1);
+  if (ALWAYS_DENIED_COMMANDS.has(cmd)) {
+    return {
+      category: "denied",
+      reason: `'${cmd}' is always denied`,
+      targetPaths: []
+    };
+  }
+  const targetsFromRedirect = sub.redirect?.target ? [sub.redirect.target] : [];
+  if (cmd === "git" && rest.length > 0) {
+    const sub1 = rest[0];
+    if (GIT_COMMIT_SUBCOMMANDS.has(sub1)) {
+      return {
+        category: "bash-commit",
+        targetPaths: targetsFromRedirect
+      };
+    }
+    if (GIT_MUTATE_SUBCOMMANDS.has(sub1)) {
+      const target = lastNonFlag(rest);
+      return {
+        category: "bash-mutate",
+        targetPaths: [
+          ...targetsFromRedirect,
+          ...target ? [target] : []
+        ]
+      };
+    }
+    if (GIT_READONLY_SUBCOMMANDS.has(sub1)) {
+      return {
+        category: sub.redirect ? "bash-mutate" : "bash-readonly",
+        targetPaths: targetsFromRedirect
+      };
+    }
+    return { category: "bash-mutate", targetPaths: targetsFromRedirect };
+  }
+  if (cmd === "gh" && rest.length >= 2) {
+    const pair = [rest[0], rest[1]];
+    if (GH_COMMIT_PATTERNS.some((p) => p[0] === pair[0] && p[1] === pair[1])) {
+      return { category: "bash-commit", targetPaths: targetsFromRedirect };
+    }
+    if (GH_READONLY_PATTERNS.some(
+      (p) => p[0] === pair[0] && p[1] === pair[1]
+    )) {
+      return {
+        category: sub.redirect ? "bash-mutate" : "bash-readonly",
+        targetPaths: targetsFromRedirect
+      };
+    }
+    return { category: "bash-mutate", targetPaths: targetsFromRedirect };
+  }
+  if (cmd === "luca") {
+    const lucaCategory = classifyLucaCommand(rest);
+    if (lucaCategory) {
+      if (sub.redirect) {
+        return {
+          category: "bash-mutate",
+          targetPaths: targetsFromRedirect
+        };
+      }
+      return { category: lucaCategory, targetPaths: [] };
+    }
+  }
+  if (cmd === "bunx" && tokens.includes("tsc") && tokens.includes("--noEmit")) {
+    return {
+      category: sub.redirect ? "bash-mutate" : "bash-readonly",
+      targetPaths: targetsFromRedirect
+    };
+  }
+  for (const pattern of PKG_MUTATE_PATTERNS) {
+    if (matchesPrefix(tokens, pattern)) {
+      return {
+        category: "bash-mutate",
+        targetPaths: targetsFromRedirect
+      };
+    }
+  }
+  if (MUTATE_COMMANDS.has(cmd)) {
+    const lastArg = cmd === "cp" || cmd === "mv" || cmd === "ln" ? lastNonFlag(rest) : void 0;
+    const sedTarget = cmd === "sed" && rest.includes("-i") ? rest[rest.length - 1] : void 0;
+    const additionalTargets = [lastArg, sedTarget].filter(
+      (x) => Boolean(x)
+    );
+    return {
+      category: "bash-mutate",
+      targetPaths: [...targetsFromRedirect, ...additionalTargets]
+    };
+  }
+  if (READONLY_COMMANDS.has(cmd)) {
+    return {
+      category: sub.redirect ? "bash-mutate" : "bash-readonly",
+      targetPaths: targetsFromRedirect
+    };
+  }
+  return {
+    category: "bash-mutate",
+    targetPaths: targetsFromRedirect
+  };
+}
+function lastNonFlag(args) {
+  for (let i = args.length - 1; i >= 0; i -= 1) {
+    if (!args[i].startsWith("-")) return args[i];
+  }
+  return void 0;
+}
+function matchesPrefix(tokens, pattern) {
+  for (let i = 0; i < pattern.length; i += 1) {
+    if (tokens[i] !== pattern[i]) return false;
+  }
+  return true;
+}
+function detectPipeToShell(subcommands) {
+  for (let i = 0; i < subcommands.length; i += 1) {
+    const sub = subcommands[i];
+    if (sub.follower !== "|") continue;
+    const next = subcommands[i + 1];
+    if (!next) continue;
+    const nextCmd = next.tokens[0];
+    if (nextCmd === "sh" || nextCmd === "bash") {
+      const upstreamCmd = sub.tokens[0];
+      if (upstreamCmd === "curl" || upstreamCmd === "wget" || upstreamCmd === "base64" && sub.tokens.includes("-d") || upstreamCmd === "echo" && subcommands.slice(0, i + 1).some(
+        (s) => s.tokens.some(
+          (t) => /^[A-Za-z0-9+/=]{16,}$/.test(t)
+        )
+      )) {
+        return `pipe-to-${nextCmd} pattern (${upstreamCmd} | \u2026 | ${nextCmd})`;
+      }
+      return `pipe-to-${nextCmd} pattern (${upstreamCmd ?? "?"} | \u2026 | ${nextCmd})`;
+    }
+  }
+  return void 0;
+}
+function classifyBashCommand(cmd) {
+  const trimmed = cmd.trim();
+  if (!trimmed) {
+    return { category: "bash-readonly", targetPaths: [] };
+  }
+  let entries;
+  try {
+    entries = parse(trimmed);
+  } catch {
+    return {
+      category: "bash-mutate",
+      reason: "command could not be parsed; treating as mutating (conservative)",
+      targetPaths: []
+    };
+  }
+  if (entries.length === 0) {
+    return {
+      category: "bash-mutate",
+      reason: "command parsed to empty (malformed)",
+      targetPaths: []
+    };
+  }
+  const subcommands = splitIntoSubcommands(entries);
+  const pipeToShellReason = detectPipeToShell(subcommands);
+  if (pipeToShellReason) {
+    return {
+      category: "denied",
+      reason: pipeToShellReason,
+      targetPaths: []
+    };
+  }
+  let category = "bash-readonly";
+  let reason;
+  const targetPaths = [];
+  for (const sub of subcommands) {
+    const r = classifySubcommand(sub);
+    category = maxCategory(category, r.category);
+    if (r.category === "denied" && !reason) reason = r.reason;
+    for (const p of r.targetPaths) {
+      if (!targetPaths.includes(p)) targetPaths.push(p);
+    }
+  }
+  return { category, reason, targetPaths };
+}
+
+async function handleStageGateHook(opts) {
+  const log = opts.log ?? (() => {
+  });
+  if (!opts.stdin.trim()) {
+    log("stage-gate: empty stdin \u2014 allowing");
+    return { exitCode: 0, decision: "allow" };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(opts.stdin);
+  } catch (err) {
+    log(
+      `stage-gate: could not parse stdin as JSON \u2014 allowing (${err.message})`
+    );
+    return { exitCode: 0, decision: "allow" };
+  }
+  const toolName = parsed.tool_name ?? parsed.toolName;
+  const toolInput = parsed.tool_input ?? parsed.toolInput;
+  const cwd = opts.cwd ?? process.cwd();
+  const homedir = opts.homedir ?? process.env.HOME;
+  const state = await loadCurrentState({ cwd });
+  const phase = coarsePhaseOf(state.pipelineStep);
+  if (phase === "IDLE") {
+    log(
+      `stage-gate: pipelineStep=idle (phase=IDLE) \u2014 allowing ${toolName ?? "(unknown tool)"}`
+    );
+    return { exitCode: 0, toolName, toolInput, decision: "allow" };
+  }
+  let category;
+  let pathBlockReason;
+  if (toolName === "Edit" || toolName === "Write" || toolName === "NotebookEdit") {
+    const targetPath = toolInput?.file_path;
+    if (!targetPath) {
+      log(`stage-gate: ${toolName} without file_path \u2014 allowing`);
+      return { exitCode: 0, toolName, toolInput, decision: "allow" };
+    }
+    const pc = classifyWritePath(targetPath, { homedir });
+    if (pc.class === "denied") {
+      pathBlockReason = `${toolName} to '${targetPath}' is always denied: ${pc.reason ?? "forbidden path"}`;
+    } else if (pc.class === "planning-general" || pc.class === "planning-audit") {
+      const gate = artifactPathGate(targetPath, state.pipelineStep, state);
+      if (gate.kind === "block") {
+        const msg = `stage-gate BLOCK: ${toolName} ${gate.reason} (pipelineStep=${state.pipelineStep})`;
+        log(msg);
+        return {
+          exitCode: 2,
+          toolName,
+          toolInput,
+          decision: "block",
+          reason: msg
+        };
+      }
+      log(
+        `stage-gate: ${toolName} to '${targetPath}' is the legal artifact for pipelineStep=${state.pipelineStep} \u2014 allowing`
+      );
+      return { exitCode: 0, toolName, toolInput, decision: "allow" };
+    } else {
+      category = pathClassToToolCategory(pc.class);
+    }
+  } else if (toolName === "Bash") {
+    const command = toolInput?.command ?? "";
+    const bashResult = classifyBashCommand(command);
+    if (bashResult.category === "denied") {
+      pathBlockReason = `Bash command is always denied: ${bashResult.reason ?? "forbidden command"}`;
+    } else {
+      for (const target of bashResult.targetPaths) {
+        const pc = classifyWritePath(target, { homedir });
+        if (pc.class === "denied") {
+          pathBlockReason = `Bash writes to denied path '${target}': ${pc.reason ?? "forbidden path"}`;
+          break;
+        }
+      }
+      if (!pathBlockReason) {
+        category = bashCategoryToToolCategory(bashResult.category);
+      }
+    }
+  } else {
+    log(
+      `stage-gate: ${toolName ?? "(unknown)"} is not write-class \u2014 allowing`
+    );
+    return { exitCode: 0, toolName, toolInput, decision: "allow" };
+  }
+  if (pathBlockReason) {
+    const msg = `stage-gate BLOCK: ${pathBlockReason}`;
+    log(msg);
+    return {
+      exitCode: 2,
+      toolName,
+      toolInput,
+      decision: "block",
+      reason: msg
+    };
+  }
+  if (!category) {
+    log("stage-gate: could not classify tool \u2014 allowing");
+    return { exitCode: 0, toolName, toolInput, decision: "allow" };
+  }
+  const allowed = isToolAllowed({ phase, category });
+  if (!allowed) {
+    const msg = `stage-gate BLOCK: ${toolName} (category=${category}) is not allowed in phase=${phase} (pipelineStep=${state.pipelineStep})`;
+    log(msg);
+    return {
+      exitCode: 2,
+      toolName,
+      toolInput,
+      decision: "block",
+      reason: msg
+    };
+  }
+  log(
+    `stage-gate: ${toolName} (category=${category}) allowed in phase=${phase}`
+  );
+  return { exitCode: 0, toolName, toolInput, decision: "allow" };
+}
+const FIXED_PHASE_FILE_ARTIFACTS = /* @__PURE__ */ new Set([
+  "research",
+  "context",
+  "plan",
+  "plan-review",
+  "verify",
+  "learn",
+  "confidence",
+  "execute/summary",
+  "execute/progress"
+]);
+function artifactPathGate(targetPath, pipelineStep, state) {
+  const legalArtifacts = STEP_ARTIFACTS[pipelineStep];
+  if (legalArtifacts.length === 0) {
+    return {
+      kind: "block",
+      reason: `write to '${targetPath}' is not permitted in pipelineStep='${pipelineStep}' \u2014 this step produces no freeform .luca/ artifact (structured mutations go through the 'luca' CLI)`
+    };
+  }
+  const resolved = resolveActiveSlug(state);
+  if (!resolved.ok) {
+    return {
+      kind: "block",
+      reason: `write to '${targetPath}' cannot be validated \u2014 ${resolved.error} (no active phase slug, so no legal artifact path can be computed)`
+    };
+  }
+  const { slug } = resolved;
+  const legalPaths = [];
+  for (const artifact of legalArtifacts) {
+    if (artifact === "audits/*") {
+      if (AUDIT_PATH_PATTERN.test(targetPath) && targetPath.startsWith(`.luca/phases/${slug}/audits/`)) {
+        return { kind: "allow" };
+      }
+      continue;
+    }
+    if (artifact === "execute/wave") {
+      const waveDir = `.luca/phases/${slug}/execute/waves/`;
+      if (targetPath.startsWith(waveDir)) {
+        const filename = targetPath.slice(waveDir.length);
+        if (WAVE_FILE_RE.test(filename)) {
+          return { kind: "allow" };
+        }
+      }
+      continue;
+    }
+    if (FIXED_PHASE_FILE_ARTIFACTS.has(artifact)) {
+      legalPaths.push(phasePathFor(slug, artifact));
+    }
+  }
+  if (legalPaths.includes(targetPath)) {
+    return { kind: "allow" };
+  }
+  return {
+    kind: "block",
+    reason: `write to '${targetPath}' is not the legal artifact for pipelineStep='${pipelineStep}'. Allowed for this step: ${describeLegalArtifacts(legalArtifacts, legalPaths, slug)}`
+  };
+}
+function describeLegalArtifacts(legalArtifacts, fixedPaths, slug) {
+  const parts = [...fixedPaths];
+  for (const a of legalArtifacts) {
+    if (a === "audits/*") {
+      parts.push(`.luca/phases/${slug}/audits/<reviewer>.md`);
+    } else if (a === "execute/wave") {
+      parts.push(`.luca/phases/${slug}/execute/waves/NN.md`);
+    }
+  }
+  return parts.length > 0 ? parts.join(", ") : "(none)";
+}
+function pathClassToToolCategory(c) {
+  switch (c) {
+    case "code":
+      return "code-write";
+    case "planning-general":
+      return "planning-write-general";
+    case "planning-audit":
+      return "planning-write-audit";
+    case "denied":
+      throw new Error("pathClassToToolCategory called with denied");
+  }
+}
+function bashCategoryToToolCategory(c) {
+  switch (c) {
+    case "bash-readonly":
+      return "bash-readonly";
+    case "bash-mutate":
+      return "bash-mutate";
+    case "bash-commit":
+      return "bash-commit";
+    case "luca-write":
+      return "luca-write";
+    case "denied":
+      throw new Error("bashCategoryToToolCategory called with denied");
+  }
+}
+
+const stageGateCommand = defineCommand({
+  meta: {
+    name: "stage-gate",
+    description: "PreToolUse stage-gate handler \u2014 parses stdin, checks phase rules, exits non-zero to block"
+  },
+  async run() {
+    const stdin = await Bun.stdin.text();
+    const result = await handleStageGateHook({
+      stdin,
+      log: (msg) => {
+        console.error(msg);
+      }
+    });
+    process.exit(result.exitCode);
+  }
+});
+const hookCommand = defineCommand({
+  meta: {
+    name: "hook",
+    description: "Hook handlers invoked by .claude/hooks/*.sh wrappers (not for direct user invocation)"
+  },
+  subCommands: {
+    "stage-gate": stageGateCommand
+  }
+});
+
+export { hookCommand };