@coldtea/abide 0.0.1

package/src/commands/calibrate.ts

@@ -0,0 +1,165 @@
+import { parseArgs } from "node:util";
+import { AbideError, DEFAULT_THRESHOLDS, type Rule, type RuleStatus } from "@coldtea/abide-schema";
+import { summarizeCalibration } from "../lib/calibration.js";
+import { runCheck } from "../lib/checkRunner.js";
+import { EDIT_CHECK_TIMEOUT_MS, TURN_CHECK_TIMEOUT_MS } from "../lib/constants.js";
+import { recentHistory } from "../lib/git.js";
+import { hasApiKey, NO_KEY_HINT } from "../lib/credentials.js";
+import { findRepoRoot, globalRubricPath, homeDir, rubricPath } from "../lib/paths.js";
+import { readRubric, writeRubric } from "../lib/rubricFile.js";
+import { say } from "../lib/ui.js";
+import { Header } from "../ui/components/Header.js";
+import { showLive, showStatic } from "../ui/render.js";
+import { CalibrateView, type CalibrateData, type CalibrateRow } from "../ui/views/CalibrateView.js";
+import { Callout } from "../ui/components/Callout.js";
+
+const statusAfter = (
+  rule: Rule,
+  verdict: ReturnType<typeof summarizeCalibration>["verdict"],
+): RuleStatus => {
+  if (rule.status === "disabled") return "disabled";
+  switch (verdict) {
+    case "weak":
+      return "weak";
+    case "noisy":
+      return "noisy";
+    case "decisive":
+      return "active";
+    case "skipped":
+      return rule.status;
+    default:
+      return rule.status;
+  }
+};
+
+/** Runs every model rule against the repo's own recent hunks and marks the ones that never decide. */
+export const runCalibrate = async (argv: string[]): Promise<number> => {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      global: { type: "boolean", default: false },
+      hunks: { type: "string", default: "20" },
+      commits: { type: "string", default: "8" },
+      json: { type: "boolean", default: false },
+    },
+  });
+  const repoRoot = findRepoRoot(process.cwd());
+  if (!hasApiKey(repoRoot)) throw new AbideError("NO_API_KEY", NO_KEY_HINT);
+  const file = values.global ? globalRubricPath() : rubricPath(repoRoot);
+  const read = readRubric(file);
+  if (read.kind === "missing")
+    throw new AbideError("RUBRIC_MISSING", `${file} does not exist yet; compile first`);
+  if (read.kind === "invalid")
+    throw new AbideError("RUBRIC_INVALID", `${file}: ${read.issues[0] ?? "invalid"}`);
+  const rubric = read.rubric;
+  const thresholds = rubric.thresholds ?? DEFAULT_THRESHOLDS;
+  const where = values.global ? homeDir() : repoRoot;
+
+  const modelRules = rubric.rules.filter(
+    (r) => r.check.type === "model" && r.status !== "disabled",
+  );
+  if (modelRules.length === 0) {
+    await showStatic(Callout({ tone: "ok", title: "No model-checked rules to calibrate" }));
+    return 0;
+  }
+  const rulesToRun = modelRules.map((r) => ({ ...r, status: "active" as const }));
+  const history = recentHistory(repoRoot, Number(values.hunks), Number(values.commits));
+  if (history.hunks.length === 0 && history.commits.length === 0) {
+    await showStatic(
+      Callout({
+        tone: "warn",
+        title: "No usable history in this repository yet, so calibration is skipped",
+        children: null,
+      }),
+    );
+    return 0;
+  }
+
+  const run = async (progress: (label: string) => void): Promise<CalibrateData> => {
+    const samples = new Map<string, number[]>();
+    let spendUsd = 0;
+    let calls = 0;
+    const record = (verdicts: { ruleId: string; probability: number }[]): void => {
+      for (const v of verdicts)
+        samples.set(v.ruleId, [...(samples.get(v.ruleId) ?? []), v.probability]);
+    };
+    let n = 0;
+    for (const hunk of history.hunks) {
+      progress(`hunk ${(n += 1)} of ${history.hunks.length}  ${hunk.file}`);
+      try {
+        const out = await runCheck({
+          phase: "edit",
+          fileDiffs: [{ file: hunk.file, text: hunk.text }],
+          task: hunk.subject,
+          rules: rulesToRun,
+          thresholds,
+          timeoutMs: EDIT_CHECK_TIMEOUT_MS,
+          retries: 2,
+        });
+        record(out.verdicts);
+        spendUsd += out.usage.costUsd ?? 0;
+        calls += 1;
+      } catch {
+        // a hunk that could not be judged is one fewer sample, nothing more
+      }
+    }
+    n = 0;
+    for (const commit of history.commits) {
+      progress(`commit ${(n += 1)} of ${history.commits.length}  ${commit.subject.slice(0, 60)}`);
+      try {
+        const out = await runCheck({
+          phase: "turn",
+          fileDiffs: commit.fileDiffs,
+          task: commit.subject,
+          rules: rulesToRun,
+          thresholds,
+          timeoutMs: TURN_CHECK_TIMEOUT_MS,
+          retries: 2,
+        });
+        record(out.verdicts);
+        spendUsd += out.usage.costUsd ?? 0;
+        calls += 1;
+      } catch {
+        // as above
+      }
+    }
+    const at = new Date().toISOString();
+    const rows: CalibrateRow[] = [];
+    const rules = rubric.rules.map((rule) => {
+      if (rule.check.type !== "model" || rule.status === "disabled") return rule;
+      const summary = summarizeCalibration(samples.get(rule.id) ?? [], thresholds);
+      rows.push({ id: rule.id, when: rule.when ?? "", ...summary, states: summary.hunks });
+      return {
+        ...rule,
+        status: statusAfter(rule, summary.verdict),
+        calibration: { at, ...summary },
+      };
+    });
+    writeRubric(file, { ...rubric, rules });
+    return {
+      root: where,
+      file,
+      hunks: history.hunks.length,
+      commits: history.commits.length,
+      calls,
+      spendUsd,
+      rows,
+      weak: rules.filter((r) => r.status === "weak").map((r) => r.id),
+      noisy: rules.filter((r) => r.status === "noisy").map((r) => r.id),
+    };
+  };
+
+  if (values.json) {
+    say(JSON.stringify(await run(() => {})));
+    return 0;
+  }
+  return showLive<CalibrateData>({
+    header: Header({
+      command: "calibrate",
+      where,
+      note: `${modelRules.length} rules against ${history.hunks.length} hunks and ${history.commits.length} commits from git history`,
+    }),
+    run,
+    done: (data) => CalibrateView({ data }),
+  });
+};

package/src/commands/check.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { AbideError } from "@coldtea/abide-schema";
+import { runCheck } from "../lib/checkRunner.js";
+import { EDIT_CHECK_TIMEOUT_MS, TURN_CHECK_TIMEOUT_MS } from "../lib/constants.js";
+import { hasApiKey, NO_KEY_HINT } from "../lib/credentials.js";
+import { boundState } from "../lib/diff.js";
+import { splitDiff, workingTreeDiff } from "../lib/git.js";
+import { loadRules } from "../lib/loadRules.js";
+import { findRepoRoot } from "../lib/paths.js";
+import { say } from "../lib/ui.js";
+import { Header } from "../ui/components/Header.js";
+import { showLive } from "../ui/render.js";
+import { CheckView, type CheckData, type CheckSection } from "../ui/views/CheckView.js";
+
+/** Checks uncommitted changes (or a patch file) the way the hooks would, and shows every verdict. */
+export const runCheckCommand = async (argv: string[]): Promise<number> => {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      diff: { type: "string" },
+      task: { type: "string" },
+      phase: { type: "string", default: "all" },
+      all: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+    },
+  });
+  const root = findRepoRoot(process.cwd());
+  const loaded = loadRules(root);
+  if (loaded.rules.length === 0)
+    throw new AbideError(
+      "RUBRIC_MISSING",
+      "no rubric here or in ~/.abide; run abide compile first",
+    );
+
+  if (!hasApiKey(root)) throw new AbideError("NO_API_KEY", NO_KEY_HINT);
+
+  const patch =
+    values.diff === undefined
+      ? workingTreeDiff(root, positionals)
+      : readFileSync(values.diff, "utf8");
+  const files = splitDiff(patch);
+  const phase = values.phase;
+
+  const run = async (progress: (label: string) => void): Promise<CheckData> => {
+    const sections: CheckSection[] = [];
+    let spendUsd = 0;
+    if (files.length === 0) return { root, sections, spendUsd, all: values.all };
+    if (phase === "all" || phase === "edit") {
+      for (const f of files) {
+        progress(`checking ${f.file}`);
+        const out = await runCheck({
+          phase: "edit",
+          fileDiffs: [{ file: f.file, text: boundState(f.text).text }],
+          task: values.task,
+          rules: loaded.rules,
+          thresholds: loaded.thresholds,
+          timeoutMs: EDIT_CHECK_TIMEOUT_MS,
+          retries: 2,
+        });
+        spendUsd += out.usage.costUsd ?? 0;
+        sections.push({
+          phase: "edit",
+          files: [f.file],
+          modelRules: out.modelRules.length,
+          calls: out.calls,
+          latencyMs: out.modelLatencyMs,
+          verdicts: out.verdicts,
+        });
+      }
+    }
+    if (phase === "all" || phase === "turn") {
+      progress(
+        `checking the whole change, ${files.length} ${files.length === 1 ? "file" : "files"}`,
+      );
+      const out = await runCheck({
+        phase: "turn",
+        fileDiffs: files.map((f) => ({ file: f.file, text: boundState(f.text, 8_000).text })),
+        task: values.task,
+        rules: loaded.rules,
+        thresholds: loaded.thresholds,
+        timeoutMs: TURN_CHECK_TIMEOUT_MS,
+        retries: 2,
+      });
+      spendUsd += out.usage.costUsd ?? 0;
+      sections.push({
+        phase: "turn",
+        files: files.map((f) => f.file),
+        modelRules: out.modelRules.length,
+        calls: out.calls,
+        latencyMs: out.modelLatencyMs,
+        verdicts: out.verdicts,
+      });
+    }
+    return { root, sections, spendUsd, all: values.all };
+  };
+
+  if (values.json) {
+    const data = await run(() => {});
+    say(JSON.stringify(data));
+    return data.sections.some((s) => s.verdicts.some((v) => v.band === "act")) ? 1 : 0;
+  }
+  return showLive<CheckData>({
+    header: Header({
+      command: "check",
+      where: root,
+      note: files.length === 0 ? "nothing to check: no changed lines" : undefined,
+    }),
+    run,
+    done: (data) => CheckView({ data }),
+    code: (data) => (data.sections.some((s) => s.verdicts.some((v) => v.band === "act")) ? 1 : 0),
+  });
+};

package/src/commands/compile.ts

@@ -0,0 +1,127 @@
+import { parseArgs } from "node:util";
+import { AbideError, type Rubric } from "@coldtea/abide-schema";
+import { claudeAvailable, runClaude } from "../lib/claude.js";
+import { compilePrompt, type TuneStats } from "../lib/compilePrompt.js";
+import { readEvents } from "../lib/events.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 { checkStaleness, discoverGlobalSources, discoverProjectSources } from "../lib/sources.js";
+import { say } from "../lib/ui.js";
+import { Callout } from "../ui/components/Callout.js";
+import { Header } from "../ui/components/Header.js";
+import { showStatic } from "../ui/render.js";
+import { planCompile } from "../hooks/sessionStart.js";
+
+const tuneStats = (
+  root: string,
+  file: string,
+): { rubric: Rubric; stats: TuneStats[] } | undefined => {
+  const read = readRubric(file);
+  if (read.kind !== "ok") return undefined;
+  const fired = new Map<string, number>();
+  const checks = new Map<string, number>();
+  for (const event of readEvents(root)) {
+    if (event.kind !== "check") continue;
+    for (const v of event.verdicts) {
+      checks.set(v.ruleId, (checks.get(v.ruleId) ?? 0) + 1);
+      if (v.band === "act") fired.set(v.ruleId, (fired.get(v.ruleId) ?? 0) + 1);
+    }
+  }
+  const stats = read.rubric.rules
+    .filter((r) => r.check.type === "model")
+    .map((r) => ({
+      rule: r.id,
+      status: r.status,
+      median: r.calibration?.median,
+      fired: fired.get(r.id) ?? 0,
+      checks: checks.get(r.id) ?? 0,
+    }));
+  return { rubric: read.rubric, stats };
+};
+
+/** Compiles now, in a headless Claude Code turn, instead of waiting for the next session. */
+export const runCompile = async (argv: string[], tune: boolean): Promise<number> => {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      print: { type: "boolean", default: false },
+      global: { type: "boolean", default: false },
+    },
+  });
+  const root = findRepoRoot(process.cwd());
+  const plan = planCompile(root);
+  if (plan.invalid.length > 0) {
+    await showStatic(
+      Callout({
+        tone: "bad",
+        title: "Fix the rubric first",
+        children: plan.invalid.map((p) => p).join("\n"),
+      }),
+    );
+    return 1;
+  }
+  if (plan.noSources)
+    throw new AbideError(
+      "NO_INSTRUCTION_FILES",
+      "found 0 instruction files, so there is nothing to compile. Add an AGENTS.md.",
+    );
+
+  let prompt: string;
+  if (tune) {
+    const stats = tuneStats(root, values.global ? globalRubricPath() : rubricPath(root));
+    if (stats === undefined)
+      throw new AbideError("RUBRIC_MISSING", "nothing to tune yet; compile first");
+    const target = values.global
+      ? {
+          which: "global" as const,
+          root: homeDir(),
+          candidates: discoverGlobalSources(),
+          staleness: checkStaleness(stats.rubric, discoverGlobalSources(), homeDir()),
+          lintConfigs: [],
+        }
+      : {
+          which: "project" as const,
+          root,
+          candidates: discoverProjectSources(root),
+          staleness: checkStaleness(stats.rubric, discoverProjectSources(root), root),
+          lintConfigs: findLintConfigs(root),
+        };
+    prompt = compilePrompt(placeCompileSkill(root), [target], stats);
+  } else {
+    if (plan.targets.length === 0) {
+      await showStatic(Callout({ tone: "ok", title: "Rubric is up to date. Nothing to compile." }));
+      return 0;
+    }
+    prompt = compilePrompt(placeCompileSkill(root), plan.targets);
+  }
+
+  if (values.print) {
+    say(prompt);
+    return 0;
+  }
+  if (!claudeAvailable()) {
+    await showStatic(
+      Callout({
+        tone: "warn",
+        title: "claude is not on PATH. Paste this into a Claude Code session in this repo:",
+      }),
+    );
+    say(prompt);
+    return 0;
+  }
+  await showStatic(
+    Header({
+      command: tune ? "tune" : "compile",
+      where: root,
+      note:
+        "Starting a headless Claude Code turn to " +
+        (tune ? "rewrite the weak rules" : "compile the rubric") +
+        ". This runs on your subscription.",
+    }),
+  );
+  const code = await runClaude(root, prompt);
+  if (code !== 0) throw new AbideError("CLAUDE_UNAVAILABLE", `claude exited with ${code}`);
+  return 0;
+};

package/src/commands/init.ts

@@ -0,0 +1,109 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { AbideError, HOSTS, type Host } from "@coldtea/abide-schema";
+import { resolveCredentials } from "../lib/credentials.js";
+import { detectHosts, hostLabel, installHost, parseHost, type Installed } from "../lib/hosts.js";
+import { hookScriptPath } from "../lib/packageRoot.js";
+import { abideDir, findRepoRoot, rubricPath } from "../lib/paths.js";
+import { readRubric } from "../lib/rubricFile.js";
+import { discoverGlobalSources, discoverProjectSources } from "../lib/sources.js";
+import type { Step } from "../ui/components/Checklist.js";
+import { showStatic } from "../ui/render.js";
+import { InitView } from "../ui/views/InitView.js";
+
+const selfTest = (script: string, root: string): boolean => {
+  const payload = JSON.stringify({
+    session_id: "abide-init-selftest",
+    cwd: root,
+    hook_event_name: "SessionStart",
+    source: "startup",
+  });
+  const result = spawnSync("node", [script, "session-start"], {
+    input: payload,
+    encoding: "utf8",
+    env: { ...process.env, ABIDE_DEBUG: "" },
+    timeout: 15_000,
+  });
+  return result.status === 0;
+};
+
+export const chooseHosts = (names: readonly string[]): Host[] => {
+  if (names.length > 0) return [...new Set(names.map(parseHost))];
+  const found = detectHosts();
+  if (found.length === 0)
+    throw new AbideError(
+      "HOST_NOT_FOUND",
+      `none of ${HOSTS.join(", ")} is installed here; name one to install anyway`,
+    );
+  return found;
+};
+
+export const runInit = 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 creds = resolveCredentials(root);
+  if (creds.kind === "none") {
+    await showStatic(InitView({ data: { kind: "no-key", root } }));
+    return 1;
+  }
+
+  const project = discoverProjectSources(root);
+  const global = discoverGlobalSources();
+  if (project.length === 0 && global.length === 0) {
+    await showStatic(InitView({ data: { kind: "no-sources", root } }));
+    return 1;
+  }
+
+  const hosts = chooseHosts(positionals);
+  const script = hookScriptPath();
+  const steps: Step[] = [
+    {
+      ok: true,
+      text: `${creds.kind === "typesafe" ? "TypeSafe" : "Vercel AI Gateway"} key found in ${creds.from}`,
+    },
+    {
+      ok: true,
+      text: `${project.length + global.length} instruction ${project.length + global.length === 1 ? "file" : "files"} found`,
+    },
+  ];
+  mkdirSync(abideDir(root), { recursive: true });
+  writeFileSync(path.join(abideDir(root), ".gitignore"), "events.jsonl\ncompile-skill.md\n");
+  if (!selfTest(script, root))
+    throw new AbideError(
+      "SETTINGS_INVALID",
+      `the hook at ${script} did not run cleanly; nothing was enabled`,
+    );
+  steps.push({ ok: true, text: "hook self-test passed" });
+
+  const installed: Installed[] = hosts.map((host) => installHost(host, root, values.project));
+  for (const i of installed) {
+    steps.push({ ok: true, text: `${hostLabel(i.host)}: ${i.what}`, detail: i.target });
+  }
+
+  const rubric = readRubric(rubricPath(root));
+  await showStatic(
+    InitView({
+      data: {
+        kind: "installed",
+        root,
+        steps,
+        hosts: installed.map((i) => hostLabel(i.host)),
+        afterwards: installed.flatMap((i) => (i.afterwards === undefined ? [] : [i.afterwards])),
+        sources: [
+          ...project.map((c) => ({ path: c.path, scope: c.scope, global: false })),
+          ...global.map((c) => ({ path: c.path, scope: c.scope, global: true })),
+        ],
+        rubric:
+          rubric.kind === "ok" ? { path: rubric.path, rules: rubric.rubric.rules.length } : null,
+      },
+    }),
+  );
+  return 0;
+};

package/src/commands/login.ts

@@ -0,0 +1,61 @@
+import { parseArgs } from "node:util";
+import { AbideError } from "@coldtea/abide-schema";
+import { GATEWAY_KEY_ENV, TYPESAFE_KEY_ENV } from "../lib/constants.js";
+import { saveUserKey } from "../lib/credentials.js";
+import { Callout } from "../ui/components/Callout.js";
+import { showStatic } from "../ui/render.js";
+
+/** Reads one line without echoing it, so the key never lands in a terminal scrollback. */
+const readSecret = (prompt: string): Promise<string> =>
+  new Promise((resolve) => {
+    const stdin = process.stdin;
+    process.stderr.write(prompt);
+    const wasRaw = stdin.isTTY ? stdin.isRaw : false;
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.resume();
+    let value = "";
+    const done = (): void => {
+      stdin.off("data", onData);
+      if (stdin.isTTY) stdin.setRawMode(wasRaw);
+      stdin.pause();
+      process.stderr.write("\n");
+      resolve(value.trim());
+    };
+    const onData = (chunk: string): void => {
+      for (const ch of chunk) {
+        if (ch === "\u0003") {
+          done();
+          process.exit(1);
+        }
+        if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+          done();
+          return;
+        }
+        if (ch === "\u007f" || ch === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        value += ch;
+      }
+    };
+    stdin.on("data", onData);
+  });
+
+/** Never a flag: a flag lands in shell history and CI logs. */
+export const runLogin = async (argv: string[]): Promise<number> => {
+  const { values } = parseArgs({
+    args: argv,
+    options: { gateway: { type: "boolean", default: false } },
+  });
+  const name = values.gateway ? GATEWAY_KEY_ENV : TYPESAFE_KEY_ENV;
+  const key = await readSecret(
+    values.gateway ? "Vercel AI Gateway key: " : "TypeSafe API key (from typesafe.ai): ",
+  );
+  if (key === "") throw new AbideError("NO_API_KEY", "nothing was entered");
+  const file = saveUserKey(name, key);
+  await showStatic(
+    Callout({ tone: "ok", title: `${name} saved to ${file} (owner-only). Run abide init next.` }),
+  );
+  return 0;
+};