@coldtea/abide 0.0.1

package/src/lib/calibration.ts

@@ -0,0 +1,35 @@
+import type { CalibrationVerdict, Thresholds } from "@coldtea/abide-schema";
+import { median } from "./ui.js";
+
+export const MIN_CALIBRATION_STATES = 5;
+/** Below this a "no" is confident. A rule whose median sits above it and whose max never reaches CLEAR_YES is dead. */
+const CONFIDENT_NO = 0.25;
+const CLEAR_YES = 0.7;
+const NOISY_FIRE_RATE = 0.6;
+
+export type CalibrationSummary = {
+  hunks: number;
+  median: number;
+  min: number;
+  max: number;
+  fired: number;
+  verdict: CalibrationVerdict;
+};
+
+/** Decisive rules answer near 0 or near 1 on real hunks. Weak ones sit in the middle. Noisy ones fire on most. */
+export const summarizeCalibration = (
+  probabilities: readonly number[],
+  thresholds: Thresholds,
+): CalibrationSummary => {
+  const n = probabilities.length;
+  const med = median(probabilities) ?? 0;
+  const min = n === 0 ? 0 : Math.min(...probabilities);
+  const max = n === 0 ? 0 : Math.max(...probabilities);
+  const fired = probabilities.filter((p) => p >= thresholds.act).length;
+  let verdict: CalibrationVerdict;
+  if (n < MIN_CALIBRATION_STATES) verdict = "skipped";
+  else if (fired / n >= NOISY_FIRE_RATE) verdict = "noisy";
+  else if (max < CLEAR_YES && med >= CONFIDENT_NO) verdict = "weak";
+  else verdict = "decisive";
+  return { hunks: n, median: med, min, max, fired, verdict };
+};

package/src/lib/checkRunner.ts

@@ -0,0 +1,124 @@
+import type { CheckPhase, Rule, Thresholds, Usage, Verdict } from "@coldtea/abide-schema";
+import type { FileDiff } from "./git.js";
+import { checkWithModel, isModelRule, type ModelRule } from "./jev.js";
+import { ruleAppliesTo } from "./scope.js";
+
+export type CheckRequest = {
+  phase: CheckPhase;
+  /** The change, one entry per touched file, paths repo-relative. */
+  fileDiffs: readonly FileDiff[];
+  task?: string;
+  rules: readonly Rule[];
+  thresholds: Thresholds;
+  timeoutMs: number;
+  /** Transient gateway failures to retry. Hooks leave it at zero. */
+  retries?: number;
+};
+
+export type CheckOutcome = {
+  verdicts: Verdict[];
+  modelRules: ModelRule[];
+  /** How many model calls the check took: one per distinct set of in-scope files. */
+  calls: number;
+  usage: Usage;
+  modelLatencyMs: number;
+};
+
+/** Only model rules run. A lint-shaped rule is the linter's to enforce, and abide only reports it. */
+const runsInPhase = (rule: Rule, phase: CheckPhase): boolean =>
+  rule.status === "active" && rule.check.type === "model" && rule.when === phase;
+
+/** Rules that are active, belong to this phase, and apply to at least one touched file. */
+export const selectRules = (
+  rules: readonly Rule[],
+  phase: CheckPhase,
+  files: readonly string[],
+): Rule[] =>
+  rules.filter((rule) => runsInPhase(rule, phase) && files.some((f) => ruleAppliesTo(rule, f)));
+
+const renderFiles = (fileDiffs: readonly FileDiff[]): string =>
+  fileDiffs.map((f) => `--- a/${f.file}\n+++ b/${f.file}\n${f.text}`).join("\n");
+
+/** Rules grouped by the files each one applies to, so no rule ever sees a file outside its scope. */
+export const groupByScope = (
+  rules: readonly ModelRule[],
+  fileDiffs: readonly FileDiff[],
+): { rules: ModelRule[]; fileDiffs: FileDiff[] }[] => {
+  const groups = new Map<string, { rules: ModelRule[]; fileDiffs: FileDiff[] }>();
+  for (const rule of rules) {
+    const inScope = fileDiffs.filter((f) => ruleAppliesTo(rule, f.file));
+    if (inScope.length === 0) continue;
+    const key = inScope.map((f) => f.file).join("\n");
+    const group = groups.get(key) ?? { rules: [], fileDiffs: inScope };
+    group.rules.push(rule);
+    groups.set(key, group);
+  }
+  return [...groups.values()];
+};
+
+const addUsage = (a: Usage, b: Usage): Usage => ({
+  inputTokens: (a.inputTokens ?? 0) + (b.inputTokens ?? 0),
+  outputTokens: (a.outputTokens ?? 0) + (b.outputTokens ?? 0),
+  costUsd: (a.costUsd ?? 0) + (b.costUsd ?? 0),
+});
+
+/** One verdict per rule: the loudest. */
+export const loudestVerdicts = (verdicts: readonly Verdict[]): Verdict[] => {
+  const best = new Map<string, Verdict>();
+  for (const v of verdicts) {
+    const have = best.get(v.ruleId);
+    if (have === undefined || v.probability > have.probability) best.set(v.ruleId, v);
+  }
+  return [...best.values()];
+};
+
+export const mergeOutcomes = (outcomes: readonly CheckOutcome[]): CheckOutcome => {
+  const modelRules: ModelRule[] = [];
+  for (const o of outcomes) {
+    for (const rule of o.modelRules) if (!modelRules.includes(rule)) modelRules.push(rule);
+  }
+  return {
+    verdicts: loudestVerdicts(outcomes.flatMap((o) => o.verdicts)),
+    modelRules,
+    calls: outcomes.reduce((sum, o) => sum + o.calls, 0),
+    usage: outcomes.reduce<Usage>((sum, o) => addUsage(sum, o.usage), {}),
+    modelLatencyMs: Math.max(0, ...outcomes.map((o) => o.modelLatencyMs)),
+  };
+};
+
+export const runCheck = async (request: CheckRequest): Promise<CheckOutcome> => {
+  const files = request.fileDiffs.map((f) => f.file);
+  const modelRules = selectRules(request.rules, request.phase, files).filter(isModelRule);
+
+  const groups = groupByScope(modelRules, request.fileDiffs);
+  if (groups.length === 0) {
+    return { verdicts: [], modelRules, calls: 0, usage: {}, modelLatencyMs: 0 };
+  }
+
+  const started = performance.now();
+  const results = await Promise.all(
+    groups.map((group) =>
+      checkWithModel(
+        group.rules,
+        {
+          ...(request.task === undefined ? {} : { task: request.task }),
+          ...(request.phase === "edit" &&
+          group.fileDiffs.length === 1 &&
+          group.fileDiffs[0] !== undefined
+            ? { file: group.fileDiffs[0].file, diff: group.fileDiffs[0].text }
+            : { files: group.fileDiffs.map((f) => f.file), diff: renderFiles(group.fileDiffs) }),
+        },
+        request.thresholds,
+        request.timeoutMs,
+        request.retries ?? 0,
+      ),
+    ),
+  );
+  return {
+    verdicts: results.flatMap((r) => r.verdicts),
+    modelRules,
+    calls: groups.length,
+    usage: results.reduce<Usage>((sum, r) => addUsage(sum, r.usage), {}),
+    modelLatencyMs: Math.round(performance.now() - started),
+  };
+};

package/src/lib/claude.ts

@@ -0,0 +1,35 @@
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { globalAbideDir } from "./paths.js";
+import { discoverGlobalSources } from "./sources.js";
+
+export const claudeAvailable = (): boolean =>
+  spawnSync("claude", ["--version"], { encoding: "utf8" }).status === 0;
+
+/** Runs one headless Claude Code turn in the repo and streams its output. */
+export const runClaude = (root: string, prompt: string): Promise<number> =>
+  new Promise((resolve) => {
+    const extraDirs = [
+      globalAbideDir(),
+      ...discoverGlobalSources().map((s) => path.dirname(s.absolute)),
+    ];
+    const child = spawn(
+      "claude",
+      [
+        "-p",
+        prompt,
+        "--permission-mode",
+        "acceptEdits",
+        "--allowedTools",
+        "Bash(node *)",
+        "Bash(abide *)",
+        "--add-dir",
+        ...extraDirs,
+        "--output-format",
+        "text",
+      ],
+      { cwd: root, stdio: "inherit" },
+    );
+    child.on("exit", (code) => resolve(code ?? 1));
+    child.on("error", () => resolve(1));
+  });

package/src/lib/compilePrompt.ts

@@ -0,0 +1,67 @@
+import type { Rubric } from "@coldtea/abide-schema";
+import { binScriptPath } from "./packageRoot.js";
+import { globalRubricPath, rubricPath } from "./paths.js";
+import { describeStaleness, type SourceCandidate, type Staleness } from "./sources.js";
+
+export type CompileTarget = {
+  which: "project" | "global";
+  root: string;
+  candidates: SourceCandidate[];
+  staleness: Staleness;
+  lintConfigs: string[];
+};
+
+export type TuneStats = {
+  rule: string;
+  status: string;
+  median: number | undefined;
+  fired: number;
+  checks: number;
+};
+
+const sourceLine = (c: SourceCandidate): string =>
+  `${c.path} (rules apply to ${c.scope}${c.required ? "" : "; include only if it carries imperative rules"})`;
+
+const targetBlock = (t: CompileTarget): string => {
+  const file = t.which === "project" ? rubricPath(t.root) : globalRubricPath();
+  const lines = [
+    `${t.which === "project" ? "Project" : "Global"} rubric: ${file} (${describeStaleness(t.staleness)})`,
+    `  repo root: ${t.root}`,
+    ...t.candidates.map((c) => `  source: ${sourceLine(c)}`),
+  ];
+  if (t.lintConfigs.length > 0)
+    lines.push(`  lint config to read for overlaps: ${t.lintConfigs.join(", ")}`);
+  return lines.join("\n");
+};
+
+/** The text SessionStart hands the agent, and what `abide compile` sends headless. */
+export const compilePrompt = (
+  skillPath: string,
+  targets: readonly CompileTarget[],
+  tune?: { rubric: Rubric; stats: TuneStats[] },
+): string => {
+  const head =
+    tune === undefined
+      ? "Abide is installed here and its rubric is missing or out of date. Compile it before you start on the user's request."
+      : "Abide is installed here. Some rules in its rubric never fire or fire on everything. Rewrite those rules before you start on the user's request.";
+  const parts = [
+    head,
+    `Read ${skillPath} and follow it to the end. Do not skip the validate and calibrate steps.`,
+    `Run the abide CLI as: node "${binScriptPath()}" <command>`,
+    ...targets.map(targetBlock),
+  ];
+  if (tune !== undefined) {
+    parts.push(
+      "Calibration and firing statistics per rule (median violation probability across recent real hunks, how often it fired, how many checks it saw):",
+      ...tune.stats.map(
+        (s) =>
+          `  ${s.rule}: status ${s.status}, median ${s.median === undefined ? "n/a" : s.median.toFixed(2)}, fired ${s.fired} of ${s.checks}`,
+      ),
+      "A rule stuck between 0.3 and 0.7 is underspecified: split it, name the concrete shape it should catch, or add a criteria example. A rule that fires on most hunks is too broad: narrow its scope or its wording. Keep every other rule exactly as it is.",
+    );
+  }
+  parts.push(
+    "When you are done, tell the user in two or three plain sentences how many rules were compiled into which buckets and which rules, if any, came out weak or noisy. Then continue with their request.",
+  );
+  return parts.join("\n\n");
+};

package/src/lib/constants.ts

@@ -0,0 +1,39 @@
+/** Jev, called directly with a TypeSafe key, or through the Vercel AI Gateway with a gateway key. */
+export const TYPESAFE_MODEL_ID = "jev-latest";
+export const GATEWAY_MODEL_ID = "typesafe-ai/jev";
+export const TYPESAFE_KEY_ENV = "TYPESAFE_AI_API_KEY";
+export const GATEWAY_KEY_ENV = "AI_GATEWAY_API_KEY";
+
+/** List price observed 2026-09-17: $0.042 per million input tokens, output free. */
+export const JEV_USD_PER_INPUT_TOKEN = 0.042 / 1_000_000;
+
+export const EDIT_CHECK_TIMEOUT_MS = 8_000;
+export const TURN_CHECK_TIMEOUT_MS = 15_000;
+export const STDIN_TIMEOUT_MS = 2_000;
+
+/** Largest diff sent as state. Beyond this the diff is cut and marked. */
+export const MAX_STATE_CHARS = 24_000;
+export const MAX_TASK_CHARS = 600;
+
+/** How many times one rule may block the same file within one turn before it only flags. */
+export const MAX_BLOCKS_PER_RULE_PER_TURN = 2;
+/** How many Stop checks one turn gets: the first, plus one re-check after a repair. */
+export const MAX_STOP_CHECKS_PER_TURN = 2;
+
+export const SESSION_STATE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** How long a single git call may run before it is killed. Well under every hook budget. */
+export const GIT_TIMEOUT_MS = 5_000;
+/** How long turn-start may spend snapshotting the working tree with git, all calls together. */
+export const TURN_START_TIMEOUT_MS = 5_000;
+/** How long Stop may spend on its own snapshot and the diff against the baseline. */
+export const STOP_GIT_TIMEOUT_MS = 8_000;
+
+/** How long computing one diff may take. Past this the check is skipped and logged rather than the hook held. */
+export const DIFF_TIMEOUT_MS = 2_000;
+/** Largest before-plus-after text a diff is attempted on at all. */
+export const MAX_DIFF_INPUT_CHARS = 1_000_000;
+/** Past this a file counts as unreadable. */
+export const MAX_FILE_READ_BYTES = 16 * 1024 * 1024;
+/** How long Stop's per-file fallback may spend on all of its diffs together. */
+export const STOP_FALLBACK_DIFF_TIMEOUT_MS = 6_000;

package/src/lib/coverage.ts

@@ -0,0 +1,21 @@
+import type { CheckedEdit } from "./session.js";
+
+/**
+ * Judged edits must chain from the turn's start content to the disk now.
+ * A change made by a shell, or while a judge was looking, breaks the chain.
+ */
+export const editsCoverFile = (
+  start: string | null,
+  edits: readonly CheckedEdit[],
+  now: string,
+): boolean => {
+  const unused = [...edits];
+  let at = start;
+  while (at !== now) {
+    const index = unused.findIndex((e) => e.before === at);
+    const next = index === -1 ? undefined : unused.splice(index, 1)[0];
+    if (next === undefined) return false;
+    at = next.after;
+  }
+  return true;
+};

package/src/lib/credentials.ts

@@ -0,0 +1,104 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { GATEWAY_KEY_ENV, TYPESAFE_KEY_ENV } from "./constants.js";
+import { globalAbideDir } from "./paths.js";
+import { readRegularText } from "./regularFile.js";
+
+/**
+ * Which key abide has, and where it goes. A TypeSafe key talks to Jev
+ * directly; a gateway key goes through the user's Vercel AI Gateway.
+ */
+export type Credentials =
+  | { kind: "typesafe"; key: string; from: string }
+  | { kind: "gateway"; key: string; from: string }
+  | { kind: "none" };
+
+export const KEY_NAMES: readonly string[] = [TYPESAFE_KEY_ENV, GATEWAY_KEY_ENV];
+
+export const userEnvPath = (): string => path.join(globalAbideDir(), ".env");
+
+/** Only the two abide keys are read from a file; nothing else in it is touched or loaded. */
+export const parseEnvFile = (text: string): Map<string, string> => {
+  const found = new Map<string, string>();
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const m = /^(?:export\s+)?([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (m === null) continue;
+    const name = m[1];
+    let value = (m[2] ?? "").trim();
+    if (name === undefined || !KEY_NAMES.includes(name)) continue;
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (value !== "") found.set(name, value);
+  }
+  return found;
+};
+
+const readEnvFile = (file: string): Map<string, string> => {
+  const text = readRegularText(file);
+  return text === undefined ? new Map() : parseEnvFile(text);
+};
+
+const pick = (vars: Map<string, string>, from: string): Credentials => {
+  const typesafe = vars.get(TYPESAFE_KEY_ENV);
+  if (typesafe !== undefined) return { kind: "typesafe", key: typesafe, from };
+  const gateway = vars.get(GATEWAY_KEY_ENV);
+  if (gateway !== undefined) return { kind: "gateway", key: gateway, from };
+  return { kind: "none" };
+};
+
+const fromProcessEnv = (): Map<string, string> => {
+  const vars = new Map<string, string>();
+  for (const name of KEY_NAMES) {
+    const value = (process.env[name] ?? "").trim();
+    if (value !== "") vars.set(name, value);
+  }
+  return vars;
+};
+
+export const findCredentials = (root: string): Credentials => {
+  const places: [string, () => Map<string, string>][] = [
+    ["the environment", fromProcessEnv],
+    [".env.local", () => readEnvFile(path.join(root, ".env.local"))],
+    [".env", () => readEnvFile(path.join(root, ".env"))],
+    [userEnvPath(), () => readEnvFile(userEnvPath())],
+  ];
+  for (const [from, read] of places) {
+    const picked = pick(read(), from);
+    if (picked.kind !== "none") return picked;
+  }
+  return { kind: "none" };
+};
+
+let current: Credentials | undefined;
+
+export const resolveCredentials = (root: string): Credentials => {
+  current ??= findCredentials(root);
+  return current;
+};
+
+export const credentials = (): Credentials => {
+  current ??= pick(fromProcessEnv(), "the environment");
+  return current;
+};
+
+export const hasApiKey = (root: string): boolean => resolveCredentials(root).kind !== "none";
+
+/** The one file abide may write a key to; see AGENTS.md. */
+export const saveUserKey = (name: string, key: string): string => {
+  const file = userEnvPath();
+  mkdirSync(path.dirname(file), { recursive: true });
+  const existing = readEnvFile(file);
+  existing.set(name, key);
+  const body = [...existing.entries()].map(([k, v]) => `${k}=${v}`).join("\n");
+  writeFileSync(file, `${body}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+  return file;
+};
+
+export const NO_KEY_HINT = `No API key found. Run "abide login" with your TypeSafe key, or put ${TYPESAFE_KEY_ENV} in the environment or a .env file at the repo root.`;

package/src/lib/diff.ts

@@ -0,0 +1,209 @@
+import path from "node:path";
+import { createTwoFilesPatch, structuredPatch } from "diff";
+import type { PatchHunk, PostToolUseInput } from "@coldtea/abide-schema";
+import { assertNever } from "@coldtea/abide-schema";
+import { parseApplyPatch } from "./applyPatch.js";
+import { DIFF_TIMEOUT_MS, MAX_DIFF_INPUT_CHARS, MAX_STATE_CHARS } from "./constants.js";
+import { readRegularText } from "./regularFile.js";
+
+export const renderHunks = (hunks: readonly PatchHunk[]): string =>
+  hunks
+    .map(
+      (h) =>
+        `@@ -${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines} @@\n${h.lines.join("\n")}`,
+    )
+    .join("\n");
+
+/** Undefined when the diff would take longer than a hook may spend on it, or the inputs are too big to try. */
+const hunksBetween = (
+  before: string,
+  after: string,
+  timeoutMs = DIFF_TIMEOUT_MS,
+): PatchHunk[] | undefined => {
+  if (timeoutMs <= 0 || before.length + after.length > MAX_DIFF_INPUT_CHARS) return undefined;
+  const patch = structuredPatch("a", "b", before, after, undefined, undefined, {
+    context: 3,
+    timeout: timeoutMs,
+  });
+  return patch?.hunks.map((h) => ({
+    oldStart: h.oldStart,
+    oldLines: h.oldLines,
+    newStart: h.newStart,
+    newLines: h.newLines,
+    lines: h.lines,
+  }));
+};
+
+const allAdded = (content: string): string => {
+  const lines = content.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  return `@@ -0,0 +1,${lines.length} @@\n${lines.map((l) => `+${l}`).join("\n")}`;
+};
+
+/**
+ * One file's change from a PostToolUse payload. `text` is undefined when the
+ * diff could not be computed within the time a hook may spend on it; the
+ * caller skips that file and says so rather than holding the agent.
+ * `original` is the file's content before the edit when the host said, for
+ * a Stop check without a git baseline. `after` is derived from the payload
+ * alone, so it is exactly what the judge saw; null when it cannot be.
+ */
+export type EditHunk = {
+  filePath: string;
+  text: string | undefined;
+  isNewFile: boolean;
+  original: string | null;
+  after: string | null;
+};
+
+type Replacement = { old: string; new: string; all?: boolean };
+
+// A function replacement keeps "$" in the new text literal.
+const applyEdit = (content: string, edit: Replacement): string =>
+  edit.all
+    ? content.replaceAll(edit.old, () => edit.new)
+    : content.replace(edit.old, () => edit.new);
+
+const applyEdits = (content: string | null, edits: readonly Replacement[]): string | null =>
+  content === null ? null : edits.reduce(applyEdit, content);
+
+const synthesized = (
+  before: string,
+  after: string,
+  timeoutMs = DIFF_TIMEOUT_MS,
+): string | undefined => {
+  const hunks = hunksBetween(before, after, timeoutMs);
+  return hunks === undefined ? undefined : renderHunks(hunks);
+};
+
+/** Time left on a budget that several diffs share. */
+export const remainingMs = (deadline: number): number => Math.floor(deadline - performance.now());
+
+/** Reverses the edit on the file as it is now, since the host did not send the original. */
+const reversed = (filePath: string, edits: readonly Replacement[]): string | null =>
+  applyEdits(
+    readRegularText(filePath) ?? null,
+    [...edits].reverse().map((e) => ({ old: e.new, new: e.old, ...(e.all ? { all: true } : {}) })),
+  );
+
+/** Every file one PostToolUse payload changed. Claude-style tools name one file; a Codex patch may name several. */
+export const editsFromPostToolUse = (input: PostToolUseInput): EditHunk[] => {
+  switch (input.tool_name) {
+    case "Edit": {
+      const hostPatch = input.tool_response?.structuredPatch;
+      const fromHost = hostPatch && hostPatch.length > 0 ? renderHunks(hostPatch) : undefined;
+      const filePath = input.tool_input.file_path;
+      const text =
+        fromHost ?? synthesized(input.tool_input.old_string, input.tool_input.new_string);
+      const edits: Replacement[] = [
+        {
+          old: input.tool_input.old_string,
+          new: input.tool_input.new_string,
+          ...(input.tool_input.replace_all ? { all: true } : {}),
+        },
+      ];
+      const original = input.tool_response?.originalFile ?? reversed(filePath, edits);
+      return [{ filePath, text, isNewFile: false, original, after: applyEdits(original, edits) }];
+    }
+    case "Write": {
+      const hostPatch = input.tool_response?.structuredPatch;
+      const fromHost = hostPatch && hostPatch.length > 0 ? renderHunks(hostPatch) : undefined;
+      const filePath = input.tool_input.file_path;
+      const original = input.tool_response?.originalFile;
+      const after = input.tool_input.content;
+      if (original === null || original === undefined) {
+        const text = after.length > MAX_DIFF_INPUT_CHARS ? undefined : allAdded(after);
+        return [{ filePath, text, isNewFile: true, original: null, after }];
+      }
+      const text = fromHost ?? synthesized(original, after);
+      return [{ filePath, text, isNewFile: false, original, after }];
+    }
+    case "MultiEdit": {
+      const hostPatch = input.tool_response?.structuredPatch;
+      const fromHost = hostPatch && hostPatch.length > 0 ? renderHunks(hostPatch) : undefined;
+      const filePath = input.tool_input.file_path;
+      const edits: Replacement[] = input.tool_input.edits.map((e) => ({
+        old: e.old_string,
+        new: e.new_string,
+        ...(e.replace_all ? { all: true } : {}),
+      }));
+      const original = input.tool_response?.originalFile ?? reversed(filePath, edits);
+      const after = applyEdits(original, edits);
+      if (fromHost !== undefined) {
+        return [{ filePath, text: fromHost, isNewFile: false, original, after }];
+      }
+      // One budget for every part: each on its own could pass while together they hold the hook.
+      const deadline = performance.now() + DIFF_TIMEOUT_MS;
+      const parts: string[] = [];
+      let text: string | undefined = undefined;
+      for (const edit of input.tool_input.edits) {
+        const part = synthesized(edit.old_string, edit.new_string, remainingMs(deadline));
+        if (part === undefined) {
+          parts.length = 0;
+          break;
+        }
+        parts.push(part);
+      }
+      if (parts.length > 0) text = parts.join("\n");
+      return [{ filePath, text, isNewFile: false, original, after }];
+    }
+    case "apply_patch":
+      return parseApplyPatch(input.tool_input.command).flatMap((file): EditHunk[] => {
+        const filePath = path.resolve(
+          input.cwd,
+          file.kind === "update" ? (file.movedTo ?? file.path) : file.path,
+        );
+        switch (file.kind) {
+          case "add":
+            return [{ filePath, text: file.text, isNewFile: true, original: null, after: null }];
+          case "update":
+            return [{ filePath, text: file.text, isNewFile: false, original: null, after: null }];
+          case "delete":
+            return [];
+          default:
+            return assertNever(file);
+        }
+      });
+    default:
+      return assertNever(input);
+  }
+};
+
+/** Undefined when the diff could not be computed within the time a hook may spend on it. */
+export const unifiedDiff = (
+  relativePath: string,
+  before: string,
+  after: string,
+  timeoutMs = DIFF_TIMEOUT_MS,
+): string | undefined =>
+  timeoutMs <= 0 || before.length + after.length > MAX_DIFF_INPUT_CHARS
+    ? undefined
+    : createTwoFilesPatch(
+        `a/${relativePath}`,
+        `b/${relativePath}`,
+        before,
+        after,
+        undefined,
+        undefined,
+        {
+          context: 3,
+          timeout: timeoutMs,
+        },
+      );
+
+export const addedLines = (hunkText: string): string[] =>
+  hunkText
+    .split("\n")
+    .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
+    .map((l) => l.slice(1));
+
+export const changedLineCount = (hunkText: string): number =>
+  hunkText.split("\n").filter((l) => /^[+-](?![+-]{2})/.test(l)).length;
+
+export const boundState = (
+  text: string,
+  max = MAX_STATE_CHARS,
+): { text: string; truncated: boolean } =>
+  text.length <= max
+    ? { text, truncated: false }
+    : { text: `${text.slice(0, max)}\n[abide: diff cut at ${max} characters]`, truncated: true };

package/src/lib/events.ts

@@ -0,0 +1,34 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { eventSchema, type AbideEvent } from "@coldtea/abide-schema";
+import { abideDir, eventsPath } from "./paths.js";
+import { writeRegularFile } from "./regularFile.js";
+
+/** Best effort. The log must never take the hook down with it, or hold it. */
+export const appendEvent = (root: string, event: AbideEvent): void => {
+  try {
+    mkdirSync(abideDir(root), { recursive: true });
+    writeRegularFile(eventsPath(root), `${JSON.stringify(event)}\n`, { use: "append" });
+  } catch {
+    // nothing to do: logging is optional
+  }
+};
+
+export const readEvents = (root: string): AbideEvent[] => {
+  let raw: string;
+  try {
+    raw = readFileSync(eventsPath(root), "utf8");
+  } catch {
+    return [];
+  }
+  const events: AbideEvent[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.trim() === "") continue;
+    try {
+      const parsed = eventSchema.safeParse(JSON.parse(line));
+      if (parsed.success) events.push(parsed.data);
+    } catch {
+      // skip a torn line
+    }
+  }
+  return events;
+};