@christang/keel 5.1.1 → 5.2.0

package/plugins/keel/scripts/pretooluse-guard.js

@@ -1,156 +1,156 @@
-#!/usr/bin/env node
-"use strict";
-
-// Keel plugin PreToolUse write guard: deterministic denial of out-of-Touch
-// file edits while an explicit keel/guard.json manifest is active. Absence of
-// the manifest allows everything silently; a present-but-untrusted manifest
-// fails closed. The hook never writes state, never spawns the keel CLI, and
-// always exits 0 — denial is expressed only through hook output. Paths that
-// resolve outside the repository root are not product writes and pass through.
-
-const crypto = require("crypto");
-const fs = require("fs");
-const path = require("path");
-
-const MANIFEST_SCHEMA = "keel-write-guard/v1";
-const FILE_EDIT_TOOLS = new Map([
-  ["Edit", "file_path"],
-  ["Write", "file_path"],
-  ["NotebookEdit", "notebook_path"],
-]);
-
-function readStdin() {
-  try {
-    return fs.readFileSync(0, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-function deny(reason) {
-  process.stdout.write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        permissionDecision: "deny",
-        permissionDecisionReason: reason,
-      },
-    })}\n`
-  );
-}
-
-function sha256(buffer) {
-  return crypto.createHash("sha256").update(buffer).digest("hex");
-}
-
-function manifestShapeValid(manifest) {
-  return (
-    manifest
-    && manifest.schema === MANIFEST_SCHEMA
-    && typeof manifest.change === "string"
-    && manifest.change !== ""
-    && typeof manifest.task === "string"
-    && manifest.task !== ""
-    && Array.isArray(manifest.touch)
-    && manifest.touch.length > 0
-    && manifest.touch.every((item) => typeof item === "string" && item !== "")
-    && Array.isArray(manifest.authority)
-    && manifest.authority.length > 0
-    && manifest.authority.every(
-      (item) =>
-        item
-        && typeof item.path === "string"
-        && /^[0-9a-f]{64}$/.test(String(item.sha256 || ""))
-    )
-  );
-}
-
-function globPattern(value) {
-  const escaped = value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-  return new RegExp(
-    `^${escaped
-      .replace(/\*\*/g, "\u0000")
-      .replace(/\*/g, "[^/]*")
-      .replace(/\u0000/g, ".*")}$`
-  );
-}
-
-function pathAllowed(candidate, touch) {
-  return touch.some((entry) => {
-    const normalized = entry.replace(/\\/g, "/").replace(/^\.\//, "");
-    if (normalized.endsWith("/")) return candidate.startsWith(normalized);
-    if (normalized.includes("*")) return globPattern(normalized).test(candidate);
-    return candidate === normalized;
-  });
-}
-
-function main() {
-  let event = {};
-  try {
-    event = JSON.parse(readStdin() || "{}");
-  } catch {
-    event = {};
-  }
-  const repo =
-    typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
-  const manifestPath = path.join(repo, "keel", "guard.json");
-  if (!fs.existsSync(manifestPath)) return 0;
-
-  const pathField = FILE_EDIT_TOOLS.get(event.tool_name);
-  if (!pathField) return 0;
-
-  let manifest = null;
-  try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-  } catch {
-    manifest = null;
-  }
-  if (!manifestShapeValid(manifest)) {
-    deny(
-      "Keel write guard: keel/guard.json is present but invalid, so file "
-        + "edits fail closed. Run `keel guard clear`, then `keel gate "
-        + "task-start` and `keel guard start` to reauthorize."
-    );
-    return 0;
-  }
-  const pointer = `${manifest.change}#${manifest.task}`;
-
-  for (const entry of manifest.authority) {
-    const file = path.join(repo, entry.path);
-    let fresh = null;
-    try {
-      fresh = sha256(fs.readFileSync(file));
-    } catch {
-      fresh = null;
-    }
-    if (fresh !== entry.sha256) {
-      deny(
-        `Keel write guard: task authority drift detected for ${pointer} `
-          + `(${entry.path} changed since guard start), so file edits fail `
-          + "closed. Re-run `keel gate task-start` and `keel guard start` to "
-          + "reauthorize, or `keel guard clear` to stop enforcement."
-      );
-      return 0;
-    }
-  }
-
-  const target = event.tool_input ? event.tool_input[pathField] : null;
-  if (typeof target !== "string" || !target) return 0;
-  const relative = path.relative(repo, path.resolve(repo, target));
-  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-    return 0;
-  }
-  const candidate = relative.replace(/\\/g, "/");
-  if (pathAllowed(candidate, manifest.touch)) return 0;
-
-  deny(
-    `Keel write guard: ${candidate} is outside Touch for ${pointer}. `
-      + `Touch allows: ${manifest.touch.join(", ")}. Stop and report an `
-      + "Out-of-scope Need, update the task authority and reauthorize via "
-      + "`keel gate task-start` and `keel guard start`, or run "
-      + "`keel guard clear` to stop enforcement."
-  );
-  return 0;
-}
-
-process.exit(main());
+#!/usr/bin/env node
+"use strict";
+
+// Keel plugin PreToolUse write guard: deterministic denial of out-of-Touch
+// file edits while an explicit keel/guard.json manifest is active. Absence of
+// the manifest allows everything silently; a present-but-untrusted manifest
+// fails closed. The hook never writes state, never spawns the keel CLI, and
+// always exits 0 — denial is expressed only through hook output. Paths that
+// resolve outside the repository root are not product writes and pass through.
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const MANIFEST_SCHEMA = "keel-write-guard/v1";
+const FILE_EDIT_TOOLS = new Map([
+  ["Edit", "file_path"],
+  ["Write", "file_path"],
+  ["NotebookEdit", "notebook_path"],
+]);
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function deny(reason) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
+    })}\n`
+  );
+}
+
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function manifestShapeValid(manifest) {
+  return (
+    manifest
+    && manifest.schema === MANIFEST_SCHEMA
+    && typeof manifest.change === "string"
+    && manifest.change !== ""
+    && typeof manifest.task === "string"
+    && manifest.task !== ""
+    && Array.isArray(manifest.touch)
+    && manifest.touch.length > 0
+    && manifest.touch.every((item) => typeof item === "string" && item !== "")
+    && Array.isArray(manifest.authority)
+    && manifest.authority.length > 0
+    && manifest.authority.every(
+      (item) =>
+        item
+        && typeof item.path === "string"
+        && /^[0-9a-f]{64}$/.test(String(item.sha256 || ""))
+    )
+  );
+}
+
+function globPattern(value) {
+  const escaped = value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(
+    `^${escaped
+      .replace(/\*\*/g, "\u0000")
+      .replace(/\*/g, "[^/]*")
+      .replace(/\u0000/g, ".*")}$`
+  );
+}
+
+function pathAllowed(candidate, touch) {
+  return touch.some((entry) => {
+    const normalized = entry.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (normalized.endsWith("/")) return candidate.startsWith(normalized);
+    if (normalized.includes("*")) return globPattern(normalized).test(candidate);
+    return candidate === normalized;
+  });
+}
+
+function main() {
+  let event = {};
+  try {
+    event = JSON.parse(readStdin() || "{}");
+  } catch {
+    event = {};
+  }
+  const repo =
+    typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
+  const manifestPath = path.join(repo, "keel", "guard.json");
+  if (!fs.existsSync(manifestPath)) return 0;
+
+  const pathField = FILE_EDIT_TOOLS.get(event.tool_name);
+  if (!pathField) return 0;
+
+  let manifest = null;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    manifest = null;
+  }
+  if (!manifestShapeValid(manifest)) {
+    deny(
+      "Keel write guard: keel/guard.json is present but invalid, so file "
+        + "edits fail closed. Run `keel guard clear`, then `keel gate "
+        + "task-start` and `keel guard start` to reauthorize."
+    );
+    return 0;
+  }
+  const pointer = `${manifest.change}#${manifest.task}`;
+
+  for (const entry of manifest.authority) {
+    const file = path.join(repo, entry.path);
+    let fresh = null;
+    try {
+      fresh = sha256(fs.readFileSync(file));
+    } catch {
+      fresh = null;
+    }
+    if (fresh !== entry.sha256) {
+      deny(
+        `Keel write guard: task authority drift detected for ${pointer} `
+          + `(${entry.path} changed since guard start), so file edits fail `
+          + "closed. Re-run `keel gate task-start` and `keel guard start` to "
+          + "reauthorize, or `keel guard clear` to stop enforcement."
+      );
+      return 0;
+    }
+  }
+
+  const target = event.tool_input ? event.tool_input[pathField] : null;
+  if (typeof target !== "string" || !target) return 0;
+  const relative = path.relative(repo, path.resolve(repo, target));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return 0;
+  }
+  const candidate = relative.replace(/\\/g, "/");
+  if (pathAllowed(candidate, manifest.touch)) return 0;
+
+  deny(
+    `Keel write guard: ${candidate} is outside Touch for ${pointer}. `
+      + `Touch allows: ${manifest.touch.join(", ")}. Stop and report an `
+      + "Out-of-scope Need, update the task authority and reauthorize via "
+      + "`keel gate task-start` and `keel guard start`, or run "
+      + "`keel guard clear` to stop enforcement."
+  );
+  return 0;
+}
+
+process.exit(main());

package/plugins/keel/scripts/session-start.js

@@ -1,182 +1,182 @@
-#!/usr/bin/env node
-"use strict";
-
-// Keel plugin SessionStart projection: disposable context only.
-// OpenSpec and Git stay the durable authority; this script never writes
-// state, selects an ambiguous owner, records a fingerprint, creates a goal,
-// or blocks the session. It always exits 0.
-//
-// The projection is source-aware: a compact start reinjects the recomputed
-// task pointer (selection, recorded Contract fingerprint, next command) that
-// a summary is most likely to lose, a resume start reinjects the selection,
-// and startup, clear, or any unknown source falls back to the generic view.
-
-const fs = require("fs");
-const path = require("path");
-const { spawnSync } = require("child_process");
-
-const TIMEOUT_MS = Number(process.env.KEEL_HOOK_TIMEOUT_MS || 8000) || 8000;
-const MAX_REASONS = 3;
-const MAX_REASON_LENGTH = 300;
-
-function readStdin() {
-  try {
-    return fs.readFileSync(0, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-function emit(context) {
-  process.stdout.write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext: context,
-      },
-    })}\n`
-  );
-}
-
-function runKeel(cwd, args) {
-  const cli = (process.env.KEEL_CLI || "keel").trim();
-  return spawnSync(`${cli} ${args.join(" ")}`, {
-    cwd,
-    shell: true,
-    encoding: "utf8",
-    timeout: TIMEOUT_MS,
-  });
-}
-
-function fallback(reason) {
-  emit(
-    `Keel hook fallback: ${reason} Run \`keel context\` manually; `
-      + "OpenSpec and Git remain the durable authority."
-  );
-}
-
-function main() {
-  let event = {};
-  try {
-    event = JSON.parse(readStdin() || "{}");
-  } catch {
-    event = {};
-  }
-  const cwd =
-    typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
-
-  if (!fs.existsSync(path.join(cwd, "openspec"))) {
-    return 0;
-  }
-
-  const version = runKeel(cwd, ["--version"]);
-  const versionMatch = String(version.stdout || "").match(/(\d+)\.\d+\.\d+/);
-  if (
-    version.error
-    || version.status !== 0
-    || !versionMatch
-    || Number(versionMatch[1]) < 3
-  ) {
-    fallback(
-      "the keel CLI is missing or incompatible with this plugin; install "
-        + "@christang/keel (npm install -g @christang/keel)."
-    );
-    return 0;
-  }
-
-  const result = runKeel(cwd, ["context", "--json"]);
-  if (result.error || result.status !== 0 || !String(result.stdout || "").trim()) {
-    fallback("`keel context --json` failed or timed out.");
-    return 0;
-  }
-  let context;
-  try {
-    context = JSON.parse(result.stdout);
-  } catch {
-    fallback("keel produced malformed context output.");
-    return 0;
-  }
-
-  const source = typeof event.source === "string" ? event.source : "";
-  const reinject = source === "compact" || source === "resume";
-  const header = source === "compact"
-    ? "Keel post-compaction reinjection (disposable; recomputed from OpenSpec and Git):"
-    : source === "resume"
-      ? "Keel resume reinjection (disposable; recomputed from OpenSpec and Git):"
-      : "Keel session projection (disposable; OpenSpec and Git are the durable authority):";
-
-  const lines = [header];
-  if (context.status === "ready" && context.selection) {
-    const task = context.selection.task ? `#${context.selection.task}` : "";
-    lines.push(
-      `- context ready: ${context.selection.change}${task} `
-        + `(${context.selection.source}); next action: `
-        + `${context.nextAction ? context.nextAction.kind : "unknown"}.`
-    );
-    if (reinject) {
-      const recorded = recordedContract(cwd, context.selection);
-      if (recorded) {
-        lines.push(
-          `- recorded Contract fingerprint: ${recorded} (recorded, not `
-            + "verified; gates recompile and compare before any write)."
-        );
-      }
-      lines.push(
-        "- next: re-run `keel context --json`, then `keel gate task-start` "
-          + "before continuing implementation; nothing was selected or "
-          + "recorded by this projection."
-      );
-    } else {
-      if (Array.isArray(context.read) && context.read.length > 0) {
-        lines.push(`- read first: ${context.read.slice(0, 5).join(", ")}.`);
-      }
-      lines.push(
-        "- run `keel gate task-start` before implementation; this projection "
-          + "selects nothing and records nothing."
-      );
-    }
-  } else {
-    lines.push(`- context status: ${context.status || "unknown"}.`);
-    for (const reason of (context.reasons || []).slice(0, MAX_REASONS)) {
-      lines.push(`- reason: ${String(reason).slice(0, MAX_REASON_LENGTH)}`);
-    }
-    lines.push(
-      "- next: run `keel context` and select an owner explicitly; this hook "
-        + "does not guess among candidates."
-    );
-  }
-  emit(lines.join("\n"));
-  return 0;
-}
-
-function recordedContract(repo, selection) {
-  if (!selection || !selection.change || !selection.task) return null;
-  const tasksPath = path.join(
-    repo,
-    "openspec",
-    "changes",
-    selection.change,
-    "tasks.md"
-  );
-  let content = "";
-  try {
-    content = fs.readFileSync(tasksPath, "utf8");
-  } catch {
-    return null;
-  }
-  const wanted = String(selection.task);
-  let inTask = false;
-  for (const line of content.split(/\r?\n/)) {
-    const heading = line.match(/^\s*-\s+\[[ xX]\]\s+(\d+(?:\.\d+)+)\s+/);
-    if (heading) {
-      inTask = heading[1] === wanted;
-      continue;
-    }
-    if (!inTask) continue;
-    const contract = line.match(/^\s*-\s*Contract:\s*(sha256:[0-9a-f]{64})\b/);
-    if (contract) return contract[1];
-  }
-  return null;
-}
-
-process.exit(main());
+#!/usr/bin/env node
+"use strict";
+
+// Keel plugin SessionStart projection: disposable context only.
+// OpenSpec and Git stay the durable authority; this script never writes
+// state, selects an ambiguous owner, records a fingerprint, creates a goal,
+// or blocks the session. It always exits 0.
+//
+// The projection is source-aware: a compact start reinjects the recomputed
+// task pointer (selection, recorded Contract fingerprint, next command) that
+// a summary is most likely to lose, a resume start reinjects the selection,
+// and startup, clear, or any unknown source falls back to the generic view.
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const TIMEOUT_MS = Number(process.env.KEEL_HOOK_TIMEOUT_MS || 8000) || 8000;
+const MAX_REASONS = 3;
+const MAX_REASON_LENGTH = 300;
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function emit(context) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: context,
+      },
+    })}\n`
+  );
+}
+
+function runKeel(cwd, args) {
+  const cli = (process.env.KEEL_CLI || "keel").trim();
+  return spawnSync(`${cli} ${args.join(" ")}`, {
+    cwd,
+    shell: true,
+    encoding: "utf8",
+    timeout: TIMEOUT_MS,
+  });
+}
+
+function fallback(reason) {
+  emit(
+    `Keel hook fallback: ${reason} Run \`keel context\` manually; `
+      + "OpenSpec and Git remain the durable authority."
+  );
+}
+
+function main() {
+  let event = {};
+  try {
+    event = JSON.parse(readStdin() || "{}");
+  } catch {
+    event = {};
+  }
+  const cwd =
+    typeof event.cwd === "string" && event.cwd ? event.cwd : process.cwd();
+
+  if (!fs.existsSync(path.join(cwd, "openspec"))) {
+    return 0;
+  }
+
+  const version = runKeel(cwd, ["--version"]);
+  const versionMatch = String(version.stdout || "").match(/(\d+)\.\d+\.\d+/);
+  if (
+    version.error
+    || version.status !== 0
+    || !versionMatch
+    || Number(versionMatch[1]) < 3
+  ) {
+    fallback(
+      "the keel CLI is missing or incompatible with this plugin; install "
+        + "@christang/keel (npm install -g @christang/keel)."
+    );
+    return 0;
+  }
+
+  const result = runKeel(cwd, ["context", "--json"]);
+  if (result.error || result.status !== 0 || !String(result.stdout || "").trim()) {
+    fallback("`keel context --json` failed or timed out.");
+    return 0;
+  }
+  let context;
+  try {
+    context = JSON.parse(result.stdout);
+  } catch {
+    fallback("keel produced malformed context output.");
+    return 0;
+  }
+
+  const source = typeof event.source === "string" ? event.source : "";
+  const reinject = source === "compact" || source === "resume";
+  const header = source === "compact"
+    ? "Keel post-compaction reinjection (disposable; recomputed from OpenSpec and Git):"
+    : source === "resume"
+      ? "Keel resume reinjection (disposable; recomputed from OpenSpec and Git):"
+      : "Keel session projection (disposable; OpenSpec and Git are the durable authority):";
+
+  const lines = [header];
+  if (context.status === "ready" && context.selection) {
+    const task = context.selection.task ? `#${context.selection.task}` : "";
+    lines.push(
+      `- context ready: ${context.selection.change}${task} `
+        + `(${context.selection.source}); next action: `
+        + `${context.nextAction ? context.nextAction.kind : "unknown"}.`
+    );
+    if (reinject) {
+      const recorded = recordedContract(cwd, context.selection);
+      if (recorded) {
+        lines.push(
+          `- recorded Contract fingerprint: ${recorded} (recorded, not `
+            + "verified; gates recompile and compare before any write)."
+        );
+      }
+      lines.push(
+        "- next: re-run `keel context --json`, then `keel gate task-start` "
+          + "before continuing implementation; nothing was selected or "
+          + "recorded by this projection."
+      );
+    } else {
+      if (Array.isArray(context.read) && context.read.length > 0) {
+        lines.push(`- read first: ${context.read.slice(0, 5).join(", ")}.`);
+      }
+      lines.push(
+        "- run `keel gate task-start` before implementation; this projection "
+          + "selects nothing and records nothing."
+      );
+    }
+  } else {
+    lines.push(`- context status: ${context.status || "unknown"}.`);
+    for (const reason of (context.reasons || []).slice(0, MAX_REASONS)) {
+      lines.push(`- reason: ${String(reason).slice(0, MAX_REASON_LENGTH)}`);
+    }
+    lines.push(
+      "- next: run `keel context` and select an owner explicitly; this hook "
+        + "does not guess among candidates."
+    );
+  }
+  emit(lines.join("\n"));
+  return 0;
+}
+
+function recordedContract(repo, selection) {
+  if (!selection || !selection.change || !selection.task) return null;
+  const tasksPath = path.join(
+    repo,
+    "openspec",
+    "changes",
+    selection.change,
+    "tasks.md"
+  );
+  let content = "";
+  try {
+    content = fs.readFileSync(tasksPath, "utf8");
+  } catch {
+    return null;
+  }
+  const wanted = String(selection.task);
+  let inTask = false;
+  for (const line of content.split(/\r?\n/)) {
+    const heading = line.match(/^\s*-\s+\[[ xX]\]\s+(\d+(?:\.\d+)+)\s+/);
+    if (heading) {
+      inTask = heading[1] === wanted;
+      continue;
+    }
+    if (!inTask) continue;
+    const contract = line.match(/^\s*-\s*Contract:\s*(sha256:[0-9a-f]{64})\b/);
+    if (contract) return contract[1];
+  }
+  return null;
+}
+
+process.exit(main());