karajan-code 4.37.0 → 4.39.0

package/src/harden/sentinel/sentinel-discard.mjs

@@ -0,0 +1,125 @@
+// The Sentinel's discard guard (KJC-BUG-0238/0241/0242, moved here by KJC-TSK-0916,
+// ADR 0014). An agent does not discard changes it did not make. Copied byte for
+// byte into .karajan/harness; `root` is the project root, injected.
+import { spawnSync } from "node:child_process";
+import { isAbsolute, relative, resolve } from "node:path";
+import process from "node:process";
+import { headIndex, shortOpts } from "./sentinel-shell.mjs";
+
+export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch", "clean"];
+
+/**
+ * What a git command would discard, per simple command (a word list).
+ * null = discards nothing (or is not git); {stash} = drops saved work;
+ * {unknown} = cannot be read with certainty; {clean} = untracked files;
+ * {paths} = working-tree changes (":/" = the whole tree, whatever the cwd).
+ * @param {string[]} words
+ * @param {string} root
+ */
+export const discardOf = (words, root) => {
+  let i = headIndex(words, ["git"]); // /usr/bin/git is git
+  // A $variable in command position beside a discard verb ($g checkout) cannot be read.
+  if (words[i]?.startsWith("$") && words.some((w) => DISCARD_VERBS.includes(w))) return { unknown: true };
+  if (words[i]?.split("/").at(-1) !== "git") return null;
+  let cwd = root;
+  for (i++; i < words.length && words[i].startsWith("-"); i++) {
+    if (words[i] === "-C") cwd = resolve(cwd, words[++i] || ".");
+    else if (words[i] === "-c") i++;
+    else if (!["--no-pager", "-P", "--paginate", "-p", "--no-optional-locks"].includes(words[i])) return words.some((w) => DISCARD_VERBS.includes(w)) ? { unknown: true } : null;
+  }
+  const sub = words[i];
+  const args = [];
+  for (let j = i + 1; j < words.length; j++) {
+    // Options that take a value: the value is not a flag (-e -n excludes "-n").
+    // Dropping clean's excludes only makes its probe list MORE files.
+    if (["-s", "--source", "-e", "--exclude"].includes(words[j]) || (sub === "clean" && /^-[a-zA-Z]*e$/.test(words[j]))) j++;
+    else args.push(words[j]);
+  }
+  const has = (...f) => f.some((x) => args.includes(x));
+  const dd = args.indexOf("--");
+  const pos = (dd < 0 ? args : args.slice(0, dd)).filter((a) => !a.startsWith("-"));
+  const after = dd < 0 ? [] : args.slice(dd + 1);
+  const ALL = { cwd, paths: [":/"] };
+  if (sub === "stash") return has("drop", "clear") ? { cwd, stash: true } : null;
+  if (sub === "reset") return has("--hard") ? ALL : null;
+  // Every clean but a dry run (-n in a short cluster BEFORE "--"): clean.requireForce=false deletes without -f.
+  const opts = dd < 0 ? args : args.slice(0, dd);
+  // Interactive clean decides at the prompt: nothing to probe, fail-closed.
+  if (sub === "clean" && opts.some((a) => a === "--interactive" || shortOpts(a).includes("i"))) return { unknown: true };
+  if (sub === "clean") return opts.some((a) => a === "--dry-run" || shortOpts(a).includes("n")) ? null : { cwd, clean: [opts, args.slice(opts.length)] };
+  if (sub === "switch") return has("--discard-changes", "-f", "--force") ? ALL : null;
+  if (sub === "restore") return has("--staged", "-S") && !has("--worktree", "-W") ? null : { cwd, paths: [...pos, ...after] };
+  if (sub !== "checkout") return null;
+  if (has("-f", "--force")) return ALL;
+  if (has("-b", "-B", "--orphan") || !(pos.length || after.length)) return null;
+  if (after.length) return { cwd, paths: after };
+  const isRef = spawnSync("git", ["-C", cwd, "rev-parse", "--verify", "--quiet", `${pos[0]}^{commit}`]).status === 0;
+  if (!isRef) return { cwd, paths: pos };
+  return pos.length > 1 ? { cwd, paths: pos.slice(1) } : null;
+};
+
+/**
+ * KJC-BUG-0261: the tracked files an `rm` or `git rm` removes, relative to root.
+ * Removing a file is the session touching it, so its state is noted before it
+ * goes and restoring it later is not taken for someone else's change.
+ * @param {string[]} words
+ * @param {string} root
+ * @param {string} cwd where relative paths resolve (the session's cwd)
+ * @returns {string[]}
+ */
+export const removedFiles = (words, root, cwd = process.cwd()) => {
+  const i = headIndex(words, ["rm", "git"]);
+  const head = words[i]?.split("/").at(-1);
+  const isGitRm = head === "git" && words[i + 1] === "rm";
+  if (head !== "rm" && !isGitRm) return [];
+  const args = words.slice(i + (isGitRm ? 2 : 1));
+  const dd = args.indexOf("--");
+  const named = dd < 0 ? args.filter((a) => !a.startsWith("-")) : [...args.slice(0, dd).filter((a) => !a.startsWith("-")), ...args.slice(dd + 1)];
+  const rels = named.map((p) => relative(root, resolve(cwd, p))).filter((r) => r && !r.startsWith("..") && !isAbsolute(r));
+  if (rels.length === 0) return [];
+  // ls-files expands a directory (rm -r dir) into the tracked files it holds.
+  const r = spawnSync("git", ["-C", root, "ls-files", "-z", "--", ...rels], { encoding: "utf8" });
+  return r.status === 0 ? String(r.stdout).split("\0").filter(Boolean) : [];
+};
+
+/**
+ * Files the discard would lose that the session did not own: dirty now and not
+ * clean at first touch. Anything unreadable, or another repo, is foreign.
+ * @param {object} d what discardOf returned
+ * @param {Record<string, string>} touch the session's first_touch ledger
+ * @param {string} root
+ * @returns {string[]}
+ */
+export const foreignLost = (d, touch, root) => {
+  if (d.stash) return ["git stash"];
+  if (d.unknown) return ["(comando no verificable: ejecutalo como git simple)"];
+  const top = spawnSync("git", ["-C", d.cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const sameRepo = top.status === 0 && resolve(String(top.stdout).trim()) === resolve(root);
+  const own = (f) => sameRepo && Object.hasOwn(touch, f) && touch[f] === "clean";
+  if (d.clean) {
+    // Ask git what it would remove: -n wins over -f, so the same flags (-ff included) are kept,
+    // minus -q (it silences the listing) and every exclude (dropping one only lists MORE).
+    // -n FIRST: after "--" it is a pathspec. LC_ALL=C: lines are parsed.
+    const [opts, rest] = d.clean;
+    const loud = opts.map((a) => (a.startsWith("--") ? a : `-${shortOpts(a).replaceAll("q", "")}`)).filter((a) => a !== "-" && a !== "--quiet" && !a.startsWith("--exclude"));
+    const r = spawnSync("git", ["-C", d.cwd, "clean", "-n", ...loud, ...rest], { encoding: "utf8", env: { ...process.env, LC_ALL: "C" } });
+    if (r.status !== 0) return ["(git clean -n fallo)"];
+    return String(r.stdout).split("\n").filter((l) => l.startsWith("Would remove ")).map((l) => relative(root, resolve(d.cwd, l.slice(13)))).filter((f) => !own(f));
+  }
+  // Fail-closed: a path git does not know (misparsed, $VAR, substitution) cannot
+  // be proven safe; git would refuse to check it out anyway.
+  if (spawnSync("git", ["-C", d.cwd, "ls-files", "--error-unmatch", "--", ...d.paths]).status !== 0) {
+    // KJC-BUG-0261: what the session removed with git rm left the index, and it is still its own.
+    return d.paths.map((p) => relative(root, resolve(d.cwd, p))).every(own) ? [] : [`(ruta no resoluble: ${d.paths.join(" ")})`];
+  }
+  const r = spawnSync("git", ["-C", d.cwd, "status", "--porcelain", "-z", "--untracked-files=no", "--", ...d.paths], { encoding: "utf8" });
+  if (r.status !== 0) return ["(git status fallo)"];
+  const files = [];
+  const parts = String(r.stdout).split("\0");
+  for (let k = 0; k < parts.length; k++) {
+    if (parts[k].length < 4) continue;
+    files.push(parts[k].slice(3));
+    if ("RC".includes(parts[k][0])) k++;
+  }
+  return files.filter((f) => !own(f));
+};

package/src/harden/sentinel/sentinel-reminders.mjs

@@ -0,0 +1,57 @@
+// The method's reminders (KJC-TSK-0917, ADR 0014). An agent reads its rules at
+// the start and loses them when the context is compacted; a hook does not forget.
+// These are reminders, not gates: never a block. Each comes AFTER the action that
+// precedes the one its rule is about (git add before a commit, gh pr create before
+// a merge), from PostToolUse: a PreToolUse reminder would need permissionDecision
+// "allow", which skips the user's permission prompt. Copied byte for byte into
+// .karajan/harness.
+import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+
+/** The git or gh subcommand of a simple command, or null: "git commit" -> ["git", "commit"]. */
+const verbOf = (words) => {
+  const i = headIndex(words, ["git", "gh"]);
+  const tool = (words[i] || "").split("/").at(-1);
+  if (tool !== "git" && tool !== "gh") return null;
+  let j = i + 1;
+  while (j < words.length && words[j].startsWith("-")) j += ["-C", "-c", "-R", "--repo"].includes(words[j]) ? 2 : 1;
+  return [tool, words[j] || "", words[j + 1] || ""];
+};
+
+const REMINDERS = [
+  {
+    id: "commit",
+    when: (verbs) => verbs.some(([t, a]) => t === "git" && a === "add"),
+    say: "kj, antes de commitear: cabecera de 100 caracteres como máximo con el sujeto en minúscula, líneas del cuerpo de 100 como máximo y sin atribución a IA. Valida el mensaje con npx commitlint --edit <fichero> y stagea por nombre (nunca git add -A).",
+  },
+  {
+    id: "gh-account",
+    when: (verbs) => verbs.some(([t]) => t === "gh") && !verbs.some(([t, a, b]) => t === "gh" && a === "auth" && b === "switch"),
+    say: "kj: gh sin cuenta explícita. La cuenta activa puede haberla cambiado otra sesión; antepón gh auth switch --user <cuenta-del-proyecto> && en el mismo comando.",
+  },
+  {
+    id: "merge",
+    when: (verbs) => verbs.some(([t, a, b]) => t === "gh" && a === "pr" && b === "create"),
+    say: "kj, PR abierta; antes de mergearla: si la card no está terminada, pártela ahora (lo hecho en su card, el resto en una nueva). Tras el merge, muévela con sus commits.",
+  },
+  {
+    id: "sync-main",
+    when: (verbs, segs) => segs.some((w) => w.includes("main")) && verbs.some(([t, a]) => t === "git" && ["checkout", "switch", "pull"].includes(a)),
+    say: "kj: tras sincronizar main, crea ya la rama de la siguiente tarea desde origin/main. En main nunca se commitea.",
+  },
+];
+
+/**
+ * The reminders due after a Bash command ran, minus those already shown within
+ * the last `every` actions.
+ * @param {string} cmd
+ * @param {{seen?: Record<string, number>, step?: number, every?: number}} [opts]
+ *   seen: action number at which each reminder was last shown; step: this action's number.
+ * @returns {{id: string, say: string}[]}
+ */
+export const remindersFor = (cmd, { seen = {}, step = 0, every = 25 } = {}) => {
+  const segs = shellSegments(cmd);
+  const verbs = segs.map(verbOf).filter(Boolean);
+  return REMINDERS.filter((r) => r.when(verbs, segs))
+    .filter((r) => !Object.hasOwn(seen, r.id) || step - seen[r.id] > every)
+    .map(({ id, say }) => ({ id, say }));
+};

package/src/harden/sentinel/sentinel-shell.mjs

@@ -0,0 +1,110 @@
+// The Sentinel's shell reader (KJC-TSK-0915, ADR 0014). A real module with no
+// dependencies: kj harden copies it byte for byte into .karajan/harness as
+// sentinel-shell.mjs, so the hooks stay autonomous and this code is unit-tested.
+// It reads command TEXT; whatever it cannot read with certainty, the guards that
+// use it treat as unknowable and deny.
+
+/**
+ * Simple commands as word lists, quote-aware: an operator or blank inside
+ * quotes belongs to the word ('user;work.txt' is one path).
+ * @param {string} cmd
+ * @returns {string[][]}
+ */
+export const shellSegments = (cmd) => {
+  const segs = [[]];
+  let word = null;
+  let quote = null;
+  let escaped = false;
+  const end = () => {
+    if (word !== null) segs.at(-1).push(word);
+    word = null;
+  };
+  for (const ch of String(cmd)) {
+    // A backslash keeps the next char literal (an escaped blank joins the word),
+    // except inside single quotes.
+    if (escaped) { word += ch; escaped = false; continue; }
+    if (ch === "\\" && quote !== "'") { escaped = true; word ??= ""; continue; }
+    if (quote) {
+      if (ch === quote) quote = null;
+      else word += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; word ??= ""; continue; }
+    // >| and >& are redirections, not a pipe or a fork.
+    if ((ch === "|" || ch === "&") && word?.endsWith(">")) { word += ch; continue; }
+    // x>file: end "x" and start the redirection word ">" (the target follows in it).
+    if (ch === ">" && word !== null && !/^\d*>?$/.test(word)) { end(); word = ">"; continue; }
+    // ( ) { } and backticks also cut: what runs inside $( ), a subshell or a group
+    // is a command of its own. A backtick leaves "$" in the word it interrupts, as
+    // $( does: that word is no longer readable.
+    if (ch === "`") word = (word ?? "") + "$";
+    if (";&|(){}\n`".includes(ch)) { end(); segs.push([]); continue; }
+    if (ch.trim() === "") { end(); continue; }
+    word = (word ?? "") + ch;
+  }
+  end();
+  return segs.filter((s) => s.length);
+};
+
+const WRAPPERS = new Set(["command", "exec", "sudo", "doas", "nice", "nohup", "time", "env"]);
+
+/**
+ * Index of the command word. Skips NAME=value assignments AND wrappers (env,
+ * sudo, command...) in any interleaving: env MODE=prod tee -> tee. After a
+ * wrapper with options (sudo -u root, env -i FOO=1) the command is the first of
+ * `heads`; none found means there is no command to read.
+ * @param {string[]} words
+ * @param {string[]} heads
+ */
+export const headIndex = (words, heads) => {
+  let i = 0;
+  while (i < words.length && (/^[A-Za-z_]\w*=/.test(words[i]) || WRAPPERS.has(words[i].split("/").at(-1)))) i++;
+  if (!words[i]?.startsWith("-")) return i;
+  const k = words.slice(i).findIndex((x) => heads.includes(x.split("/").at(-1)));
+  return k < 0 ? words.length : i + k;
+};
+
+/**
+ * KJC-BUG-0243: blank the quoted text that cannot run: single-quoted spans, and
+ * double-quoted spans with no $ or backtick. What remains is what the shell can
+ * still expand or execute, so operator and substitution checks read only that.
+ * @param {string} cmd
+ */
+export const stripInertQuotes = (cmd) => {
+  let out = "";
+  for (let i = 0; i < cmd.length; i++) {
+    const q = cmd[i];
+    if (q !== "'" && q !== '"') { out += q; continue; }
+    let j = i + 1;
+    while (j < cmd.length && cmd[j] !== q) j += q === '"' && cmd[j] === "\\" ? 2 : 1;
+    if (j >= cmd.length) return out + cmd.slice(i); // unclosed: left as is, for the caller to deny
+    const body = cmd.slice(i + 1, j);
+    out += q === "'" || !/[$`]/.test(body) ? q + q : q + body + q;
+    i = j;
+  }
+  return out;
+};
+
+// Options whose value is prose, never a path (gh, git, kj).
+const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position"]);
+const QUOTED_OPTION_VALUE = /(^|\s)(--?[a-z]+)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
+
+/** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
+export const stripTextOptionValues = (cmd) => cmd.replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
+
+/**
+ * KJC-BUG-0245: the values of the named options, read by the shell reader, so a
+ * `;`, `&&` or `|` right after a path ends the word instead of joining it.
+ * Covers `--opt value` and `--opt=value`.
+ * @param {string} cmd
+ * @param {string[]} names
+ * @returns {string[]}
+ */
+export const optionValues = (cmd, names) => shellSegments(cmd).flatMap((words) => words.flatMap((w, i) => {
+  if (names.includes(w) && i + 1 < words.length) return [words[i + 1]];
+  const eq = w.indexOf("=");
+  return eq > 0 && names.includes(w.slice(0, eq)) ? [w.slice(eq + 1)] : [];
+}));
+
+/** Short flags of a cluster stop at "e": the rest is -e's value (-fen = -f -e n). */
+export const shortOpts = (a) => (/^-[a-zA-Z]/.test(a) ? a.slice(1).split("e")[0] : "");

package/src/harden/sentinel/sessionstart.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// kj sentinel SessionStart hook (KJC-TSK-0918, ADR 0014), managed by `kj harden`.
+// A compaction takes exactly what the agent needs most: the rules it read at the
+// start. After a compaction or a resume, this gives them back, short, with the
+// state of the session. A new session gets nothing: CLAUDE.md already brings them.
+// Copied byte for byte into .karajan/harness; never fails a session (exit 0).
+import process from "node:process";
+import { CARD, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+
+const RULES = [
+  "1. Karajan gobierna y se le obedece: no cambies políticas, configuración de gates ni exclusiones para pasar un gate. Si uno parece injusto, díselo a tu usuario o usa kj report-issue.",
+  "2. Card antes de código; rama desde origin/main; nunca se commitea en main.",
+  "3. kj rag query antes de tocar código que no has consultado en esta sesión.",
+  "4. El test que falla va primero; la suite nunca se deja en rojo.",
+  "5. kj review --staged antes de cada commit: el veredicto va atado al diff exacto.",
+  "6. PR atómica: unas 150 líneas, 200 como máximo; mídela con kj pr-size y parte antes, no en el gate.",
+  "7. Conventional Commits, cabecera de 100 caracteres como máximo y sin atribución a IA.",
+  "8. Card sin terminar con PR mergeada: pártela antes de mergear; tras el merge, muévela con sus commits.",
+  "9. Dentro del repo se escribe solo con Edit/Write; los escapes KJ_ALLOW_* son de tu usuario, no tuyos.",
+];
+
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", source } = JSON.parse(raw || "{}");
+    if (source !== "compact" && source !== "resume") process.exit(0);
+    const branch = branchOf() || "?";
+    const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
+    const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
+    const state = `Estado: rama ${branch}, card ${card}${pending.length ? `; cards mergeadas sin mover: ${pending.join(", ")}` : ""}.`;
+    const context = ["Karajan (reglas que la compactación se lleva):", ...RULES, state].join("\n");
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }));
+  } catch { /* never fails a session */ }
+  process.exit(0);
+});