@coldtea/abide 0.0.1

package/src/commands/replay.ts

@@ -0,0 +1,148 @@
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { AbideError, assertNever, hostSchema, type Host } from "@coldtea/abide-schema";
+import { hasApiKey, NO_KEY_HINT } from "../lib/credentials.js";
+import { hostLabel } from "../lib/hosts.js";
+import { loadRules } from "../lib/loadRules.js";
+import { findRepoRoot } from "../lib/paths.js";
+import {
+  driftByTurn,
+  parseTranscript,
+  replaySessions,
+  tallyRules,
+  type ReplaySession,
+} from "../lib/replay.js";
+import { codexSessionsDir, codexSessionsFor } from "../lib/replayCodex.js";
+import { opencodeDbPath, opencodeSessionsFor } from "../lib/replayOpencode.js";
+import { say, usd } from "../lib/ui.js";
+import { Header } from "../ui/components/Header.js";
+import { showLive } from "../ui/render.js";
+import { ReplayView, type ReplayData } from "../ui/views/ReplayView.js";
+
+/** Claude Code names the transcript directory after the repo path. */
+export const claudeProjectDir = (root: string): string =>
+  path.join(homedir(), ".claude", "projects", root.replace(/[/.]/g, "-"));
+
+const transcriptFiles = (target: string): string[] => {
+  const stat = statSync(target);
+  if (stat.isFile()) return [target];
+  return readdirSync(target)
+    .filter((name) => name.endsWith(".jsonl"))
+    .map((name) => path.join(target, name))
+    .sort();
+};
+
+const inside = (root: string, dir: string): boolean => {
+  const rel = path.relative(root, dir);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+};
+
+const sessionsFor = (host: Host, root: string, paths: readonly string[]): ReplaySession[] => {
+  switch (host) {
+    case "claude":
+      return (paths.length > 0 ? paths : [claudeProjectDir(root)])
+        .flatMap(transcriptFiles)
+        .map(parseTranscript)
+        .filter((s) => s.turns.length > 0 && inside(root, s.cwd));
+    case "codex":
+      return codexSessionsFor(root, paths[0] ?? codexSessionsDir());
+    case "opencode":
+      return opencodeSessionsFor(root, paths[0] ?? opencodeDbPath());
+    default:
+      return assertNever(host);
+  }
+};
+
+export const runReplay = async (argv: string[]): Promise<number> => {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      repo: { type: "string" },
+      concurrency: { type: "string", default: "3" },
+      "max-sessions": { type: "string" },
+      diffs: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+    },
+  });
+  const [first, ...rest] = positionals;
+  if (first === undefined)
+    throw new AbideError(
+      "HOST_UNKNOWN",
+      "name the agent whose sessions to replay: abide replay claude|codex|opencode [--repo <path>]",
+    );
+  const named = hostSchema.safeParse(first.toLowerCase());
+  // no agent name: positionals are Claude Code transcripts
+  const host: Host = named.success ? named.data : "claude";
+  const paths = named.success ? rest : positionals;
+  const root = findRepoRoot(values.repo ?? process.cwd());
+  if (!hasApiKey(root)) throw new AbideError("NO_API_KEY", NO_KEY_HINT);
+  const loaded = loadRules(root);
+  if (loaded.rules.length === 0)
+    throw new AbideError(
+      "RUBRIC_MISSING",
+      `no rubric in ${root} or ~/.abide; run abide compile there first`,
+    );
+  const cap = values["max-sessions"] === undefined ? Infinity : Number(values["max-sessions"]);
+  const sessions = sessionsFor(host, root, paths).slice(0, cap);
+  const editCount = sessions.reduce(
+    (n, s) => n + s.turns.reduce((m, t) => m + t.edits.length, 0),
+    0,
+  );
+  const concurrency = Math.max(1, Number(values.concurrency));
+
+  const run = async (progress: (label: string) => void): Promise<ReplayData> => {
+    const started = performance.now();
+    const result = await replaySessions(
+      sessions,
+      loaded.rules,
+      loaded.thresholds,
+      concurrency,
+      (done, total, spend) => progress(`${done} of ${total} edits · about ${usd(spend)}`),
+      values.diffs,
+    );
+    return {
+      root,
+      host: hostLabel(host),
+      sessions: sessions.length,
+      edits: editCount,
+      result,
+      drift: driftByTurn(result.edits),
+      tallies: tallyRules(result, loaded.rules),
+      spendUsd:
+        result.edits.reduce((s, e) => s + e.costUsd, 0) +
+        result.turns.reduce((s, t) => s + t.costUsd, 0),
+      elapsedMs: performance.now() - started,
+    };
+  };
+
+  if (values.json) {
+    const data = await run(() => {});
+    say(
+      JSON.stringify({
+        root,
+        host,
+        sessions: data.sessions,
+        edits: data.edits,
+        spendUsd: data.spendUsd,
+        elapsedMs: data.elapsedMs,
+        drift: data.drift,
+        byRule: data.tallies,
+        editResults: data.result.edits,
+        turnResults: data.result.turns,
+      }),
+    );
+    return 0;
+  }
+  return showLive<ReplayData>({
+    header: Header({
+      command: "replay",
+      where: root,
+      note: `${hostLabel(host)}: ${sessions.length} sessions, ${editCount} edits, ${concurrency} at a time`,
+    }),
+    run,
+    done: (data) => ReplayView({ data }),
+  });
+};

package/src/commands/report.ts

@@ -0,0 +1,83 @@
+import { parseArgs } from "node:util";
+import type { AbideEvent, Rule } from "@coldtea/abide-schema";
+import { readEvents } from "../lib/events.js";
+import { loadRules } from "../lib/loadRules.js";
+import { findRepoRoot } from "../lib/paths.js";
+import { say } from "../lib/ui.js";
+import type { RuleStats } from "../ui/components/RuleTable.js";
+import { showStatic } from "../ui/render.js";
+import { ReportView, type ReportData } from "../ui/views/ReportView.js";
+import { InitView } from "../ui/views/InitView.js";
+
+const statsFrom = (events: readonly AbideEvent[]): Map<string, RuleStats> => {
+  const stats = new Map<string, RuleStats>();
+  for (const event of events) {
+    if (event.kind !== "check") continue;
+    for (const v of event.verdicts) {
+      const s = stats.get(v.ruleId) ?? { checks: 0, fired: 0, flagged: 0 };
+      s.checks += 1;
+      if (v.band === "act") s.fired += 1;
+      if (v.band === "flag") s.flagged += 1;
+      stats.set(v.ruleId, s);
+    }
+  }
+  return stats;
+};
+
+const MIN_CHECKS_TO_CALL_DEAD = 20;
+
+export const collectReport = (root: string): ReportData | undefined => {
+  const loaded = loadRules(root);
+  if (loaded.rules.length === 0) return undefined;
+  const events = readEvents(root);
+  const stats = statsFrom(events);
+  // Dead means it never answers: no fire, no flag, and a calibration that
+  // never cleared confidently either. A rule at 0.02 on every check is not
+  // dead, it is a rule nobody has broken yet.
+  const dead: Rule[] = loaded.rules.filter((rule) => {
+    const s = stats.get(rule.id);
+    const middling = rule.calibration === undefined || rule.calibration.median >= 0.25;
+    return (
+      rule.status === "active" &&
+      rule.check.type === "model" &&
+      middling &&
+      s !== undefined &&
+      s.checks >= MIN_CHECKS_TO_CALL_DEAD &&
+      s.fired === 0 &&
+      s.flagged === 0
+    );
+  });
+  return { root, rules: loaded.rules, events, stats, dead, problems: loaded.problems };
+};
+
+/** Rules, calibration, and what has fired so far in this repository. */
+export const runReport = async (argv: string[]): Promise<number> => {
+  const { values } = parseArgs({
+    args: argv,
+    options: { json: { type: "boolean", default: false } },
+  });
+  const root = findRepoRoot(process.cwd());
+  const data = collectReport(root);
+  if (data === undefined) {
+    if (values.json) {
+      say(JSON.stringify({ root, rules: [], events: [] }));
+      return 1;
+    }
+    await showStatic(InitView({ data: { kind: "no-sources", root } }));
+    return 1;
+  }
+  if (values.json) {
+    say(
+      JSON.stringify({
+        root: data.root,
+        rules: data.rules,
+        stats: Object.fromEntries(data.stats),
+        dead: data.dead.map((r) => r.id),
+        events: data.events.length,
+      }),
+    );
+    return 0;
+  }
+  await showStatic(ReportView({ data }));
+  return 0;
+};

package/src/commands/rubric.ts

@@ -0,0 +1,45 @@
+import { parseArgs } from "node:util";
+import { AbideError } from "@coldtea/abide-schema";
+import { findRepoRoot, globalRubricPath, homeDir, rubricPath } from "../lib/paths.js";
+import { fillSourceShas, readRubric, writeRubric } from "../lib/rubricFile.js";
+import { showStatic } from "../ui/render.js";
+import { RubricView } from "../ui/views/RubricView.js";
+
+/** Parses the rubric the agent just wrote, fills in real source hashes, writes it back. */
+export const runRubric = async (argv: string[]): Promise<number> => {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: { global: { type: "boolean", default: false } },
+  });
+  const sub = positionals[0] ?? "validate";
+  if (sub !== "validate")
+    throw new AbideError(
+      "RUBRIC_INVALID",
+      `unknown rubric command "${sub}"; try: abide rubric validate`,
+    );
+  const root = values.global ? homeDir() : findRepoRoot(process.cwd());
+  const file = values.global ? globalRubricPath() : rubricPath(root);
+  const read = readRubric(file);
+  switch (read.kind) {
+    case "missing":
+      throw new AbideError("RUBRIC_MISSING", `${file} does not exist yet`);
+    case "invalid":
+      await showStatic(RubricView({ data: { kind: "invalid", root, file, issues: read.issues } }));
+      return 1;
+    case "ok": {
+      const { rubric, missing } = fillSourceShas(read.rubric, root);
+      const listed = new Set(rubric.sources.map((s) => s.path));
+      const orphaned = rubric.rules
+        .filter((r) => !listed.has(r.source.path))
+        .map((r) => `${r.id} (${r.source.path})`);
+      writeRubric(file, rubric);
+      await showStatic(
+        RubricView({ data: { kind: "ok", root, file, rules: rubric.rules, missing, orphaned } }),
+      );
+      return missing.length + orphaned.length > 0 ? 1 : 0;
+    }
+    default:
+      return 1;
+  }
+};

package/src/commands/uninstall.ts

@@ -0,0 +1,33 @@
+import { parseArgs } from "node:util";
+import { HOSTS } from "@coldtea/abide-schema";
+import { hostLabel, parseHost, uninstallHost } from "../lib/hosts.js";
+import { findRepoRoot } from "../lib/paths.js";
+import { Callout } from "../ui/components/Callout.js";
+import { showStatic } from "../ui/render.js";
+
+export const runUninstall = async (argv: string[]): Promise<number> => {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: { project: { type: "boolean", default: false } },
+  });
+  const root = findRepoRoot(process.cwd());
+  const hosts = positionals.length > 0 ? [...new Set(positionals.map(parseHost))] : [...HOSTS];
+  const removed = hosts.map((host) => ({
+    host,
+    count: uninstallHost(host, root, values.project),
+  }));
+  const touched = removed.filter((r) => r.count > 0);
+  await showStatic(
+    touched.length === 0
+      ? Callout({
+          tone: "muted",
+          title: "No abide entries found for " + hosts.map(hostLabel).join(", "),
+        })
+      : Callout({
+          tone: "ok",
+          title: `Removed abide from ${touched.map((r) => hostLabel(r.host)).join(", ")}. Your rubric files are untouched.`,
+        }),
+  );
+  return 0;
+};

package/src/hooks/postToolUse.ts

@@ -0,0 +1,171 @@
+import {
+  createBlobId,
+  createBlockKey,
+  isAbideError,
+  postToolUseInputSchema,
+  turnIdOf,
+  type HookOutput,
+  type Rule,
+  type Verdict,
+} from "@coldtea/abide-schema";
+import { runCheck, type CheckOutcome } from "../lib/checkRunner.js";
+import { EDIT_CHECK_TIMEOUT_MS, MAX_BLOCKS_PER_RULE_PER_TURN } from "../lib/constants.js";
+import { hasApiKey } from "../lib/credentials.js";
+import { boundState, editsFromPostToolUse, type EditHunk } from "../lib/diff.js";
+import { appendEvent } from "../lib/events.js";
+import { loadRules } from "../lib/loadRules.js";
+import { debug } from "../lib/output.js";
+import { findRepoRoot, isExcludedPath, relativeToRoot } from "../lib/paths.js";
+import { flagNotice, repairReason } from "../lib/reason.js";
+import {
+  blockCount,
+  incrementBlock,
+  readPrompt,
+  recordBlockedFile,
+  recordChecked,
+  recordFileStart,
+  turnDir,
+} from "../lib/session.js";
+import { lastUserPrompt } from "../lib/transcript.js";
+
+type Pair = { rule: Rule; verdict: Verdict };
+
+type Checked = { edit: EditHunk; relative: string; outcome: CheckOutcome };
+
+export const handlePostToolUse = async (raw: unknown): Promise<HookOutput> => {
+  const parsed = postToolUseInputSchema.safeParse(raw);
+  if (!parsed.success) return { kind: "silent" };
+  const input = parsed.data;
+  const started = performance.now();
+  const at = new Date().toISOString();
+  const all = editsFromPostToolUse(input);
+  const root = findRepoRoot(all[0]?.filePath ?? input.cwd);
+  const edits = all.filter((e) => !isExcludedPath(relativeToRoot(root, e.filePath)));
+  if (edits.length === 0) return { kind: "silent" };
+
+  const turn = turnDir(input.session_id, turnIdOf(input));
+  for (const edit of edits) recordFileStart(turn, edit.filePath, edit.original);
+
+  const loaded = loadRules(root);
+  for (const problem of loaded.problems) debug(problem);
+  if (loaded.rules.length === 0) return { kind: "silent" };
+
+  const checkable: { edit: EditHunk; relative: string; diff: string }[] = [];
+  for (const edit of edits) {
+    const relative = relativeToRoot(root, edit.filePath);
+    if (edit.text === undefined) {
+      appendEvent(root, {
+        kind: "skip",
+        at,
+        phase: "edit",
+        sessionId: input.session_id,
+        reason: "diff too large to compute in time",
+        files: [relative],
+      });
+      continue;
+    }
+    const { text: diff } = boundState(edit.text);
+    if (diff.trim() !== "") checkable.push({ edit, relative, diff });
+  }
+  if (checkable.length === 0) return { kind: "silent" };
+  const files = checkable.map((c) => c.relative);
+
+  if (!hasApiKey(root)) {
+    appendEvent(root, {
+      kind: "skip",
+      at,
+      phase: "edit",
+      sessionId: input.session_id,
+      reason: "no api key",
+      files,
+    });
+  }
+
+  const task = lastUserPrompt(input.transcript_path ?? undefined) ?? readPrompt(turn);
+  let checked: Checked[];
+  try {
+    checked = await Promise.all(
+      checkable.map(async ({ edit, relative, diff }) => ({
+        edit,
+        relative,
+        outcome: await runCheck({
+          phase: "edit",
+          fileDiffs: [{ file: relative, text: diff }],
+          task,
+          rules: loaded.rules,
+          thresholds: loaded.thresholds,
+          timeoutMs: EDIT_CHECK_TIMEOUT_MS,
+        }),
+      })),
+    );
+  } catch (error) {
+    appendEvent(root, {
+      kind: "error",
+      at,
+      phase: "edit",
+      sessionId: input.session_id,
+      code: isAbideError(error) ? error.code : "CHECK_FAILED",
+      message: error instanceof Error ? error.message : String(error),
+      latencyMs: Math.round(performance.now() - started),
+    });
+    return { kind: "silent" };
+  }
+
+  for (const { edit, relative } of checked) {
+    if (edit.after === null) continue;
+    recordChecked(turn, {
+      path: relative,
+      before: edit.original === null ? null : createBlobId(edit.original),
+      after: createBlobId(edit.after),
+    });
+  }
+
+  const byId = new Map(loaded.rules.map((r) => [r.id, r]));
+  const acting: Pair[] = [];
+  const flagged: Pair[] = [];
+  const actedOn: string[] = [];
+  for (const { relative, outcome } of checked) {
+    const pairs = (band: Verdict["band"]): Pair[] =>
+      outcome.verdicts.flatMap((verdict) => {
+        const rule = byId.get(verdict.ruleId);
+        return rule !== undefined && verdict.band === band ? [{ rule, verdict }] : [];
+      });
+    const actPairs = pairs("act");
+    const actingHere = actPairs.filter(
+      ({ rule }) =>
+        blockCount(turn, createBlockKey(rule.id, relative)) < MAX_BLOCKS_PER_RULE_PER_TURN,
+    );
+    for (const { rule } of actingHere) incrementBlock(turn, createBlockKey(rule.id, relative));
+    if (actingHere.length > 0) {
+      actedOn.push(relative);
+      recordBlockedFile(turn, relative);
+    }
+    acting.push(...actingHere);
+    flagged.push(...pairs("flag"), ...actPairs.filter((p) => !actingHere.includes(p)));
+
+    appendEvent(root, {
+      kind: "check",
+      at,
+      phase: "edit",
+      sessionId: input.session_id,
+      promptId: turnIdOf(input),
+      files: [relative],
+      rules: outcome.modelRules.length,
+      latencyMs: Math.round(performance.now() - started),
+      modelLatencyMs: outcome.modelLatencyMs,
+      usage: outcome.usage,
+      verdicts: outcome.verdicts,
+      blocked: actingHere.length > 0,
+    });
+  }
+
+  const systemMessage = flagged.length > 0 ? flagNotice("edit", flagged, files) : undefined;
+  if (acting.length > 0) {
+    return {
+      kind: "block",
+      reason: repairReason("edit", acting, actedOn),
+      ...(systemMessage === undefined ? {} : { systemMessage }),
+    };
+  }
+  return systemMessage === undefined ? { kind: "silent" } : { kind: "notice", systemMessage };
+};

package/src/hooks/sessionStart.ts

@@ -0,0 +1,100 @@
+import { sessionStartInputSchema, type HookOutput } from "@coldtea/abide-schema";
+import { compilePrompt, type CompileTarget } from "../lib/compilePrompt.js";
+import { appendEvent } from "../lib/events.js";
+import { hasApiKey } from "../lib/credentials.js";
+import { findLintConfigs } from "../lib/lintConfig.js";
+import { placeCompileSkill } from "../lib/packageRoot.js";
+import { findRepoRoot, globalRubricPath, homeDir, rubricPath } from "../lib/paths.js";
+import { readRubric } from "../lib/rubricFile.js";
+import { pruneOldTurns } from "../lib/session.js";
+import { checkStaleness, discoverGlobalSources, discoverProjectSources } from "../lib/sources.js";
+
+export type CompilePlan = {
+  targets: CompileTarget[];
+  invalid: string[];
+  noSources: boolean;
+};
+
+/** What, if anything, needs compiling for this repository and this machine. */
+export const planCompile = (root: string): CompilePlan => {
+  const targets: CompileTarget[] = [];
+  const invalid: string[] = [];
+
+  const project = discoverProjectSources(root);
+  const projectRead = readRubric(rubricPath(root));
+  if (projectRead.kind === "invalid") {
+    invalid.push(`${projectRead.path}: ${projectRead.issues.slice(0, 3).join("; ")}`);
+  }
+  const projectRubric = projectRead.kind === "ok" ? projectRead.rubric : undefined;
+  const projectStale = checkStaleness(projectRubric, project, root);
+  if (
+    project.some((c) => c.required) &&
+    projectStale.status !== "fresh" &&
+    projectRead.kind !== "invalid"
+  ) {
+    targets.push({
+      which: "project",
+      root,
+      candidates: project,
+      staleness: projectStale,
+      lintConfigs: findLintConfigs(root),
+    });
+  }
+
+  const global = discoverGlobalSources();
+  const globalRead = readRubric(globalRubricPath());
+  if (globalRead.kind === "invalid") {
+    invalid.push(`${globalRead.path}: ${globalRead.issues.slice(0, 3).join("; ")}`);
+  }
+  const globalRubric = globalRead.kind === "ok" ? globalRead.rubric : undefined;
+  const globalStale = checkStaleness(globalRubric, global, homeDir());
+  if (global.length > 0 && globalStale.status !== "fresh" && globalRead.kind !== "invalid") {
+    targets.push({
+      which: "global",
+      root: homeDir(),
+      candidates: global,
+      staleness: globalStale,
+      lintConfigs: [],
+    });
+  }
+
+  return { targets, invalid, noSources: project.length === 0 && global.length === 0 };
+};
+
+export const handleSessionStart = async (raw: unknown): Promise<HookOutput> => {
+  const parsed = sessionStartInputSchema.safeParse(raw);
+  if (!parsed.success) return { kind: "silent" };
+  const input = parsed.data;
+  const root = findRepoRoot(input.cwd);
+  pruneOldTurns();
+
+  const plan = planCompile(root);
+  const notices: string[] = [];
+  if (!hasApiKey(root)) {
+    notices.push(
+      "Abide: no API key was found, so edits are not being checked. Run abide login, or put TYPESAFE_AI_API_KEY in the environment or a .env at the repo root, then start a new session.",
+    );
+  }
+  for (const problem of plan.invalid) {
+    notices.push(`Abide: rubric could not be read and is being ignored: ${problem}`);
+  }
+  const systemMessage = notices.length > 0 ? notices.join("\n") : undefined;
+
+  if (plan.targets.length === 0) {
+    return systemMessage === undefined ? { kind: "silent" } : { kind: "notice", systemMessage };
+  }
+
+  appendEvent(root, {
+    kind: "compile-needed",
+    at: new Date().toISOString(),
+    sessionId: input.session_id,
+    reason: plan.targets.map((t) => `${t.which}: ${t.staleness.status}`).join(", "),
+    sources: plan.targets.flatMap((t) => t.candidates.map((c) => c.path)),
+  });
+
+  return {
+    kind: "session-context",
+    additionalContext: compilePrompt(placeCompileSkill(root), plan.targets),
+    ...(systemMessage === undefined ? {} : { systemMessage }),
+  };
+};