@coldtea/abide 0.0.1

package/src/ui/views/ErrorView.tsx

@@ -0,0 +1,32 @@
+import { Text } from "ink";
+import { isAbideError, type AbideErrorCode } from "@coldtea/abide-schema";
+import { Callout } from "../components/Callout.js";
+import { palette } from "../theme.js";
+
+/** Our own sentence for each failure; the machine's detail sits under it, dimmed. */
+const TITLES: Record<AbideErrorCode, string> = {
+  NO_API_KEY: "No API key, so nothing can be checked",
+  NO_INSTRUCTION_FILES: "No instruction files here, so there is nothing to compile",
+  RUBRIC_INVALID: "The rubric could not be read",
+  RUBRIC_MISSING: "No rubric yet",
+  SETTINGS_INVALID: "The settings file could not be changed",
+  GIT_UNAVAILABLE: "Git history is not readable here",
+  CLAUDE_UNAVAILABLE: "Claude Code did not finish the turn",
+  HOST_UNKNOWN: "That is not an agent abide knows",
+  HOST_NOT_FOUND: "No supported agent was found on this machine",
+  CHECK_TIMEOUT: "Jev did not answer in time",
+  CHECK_FAILED: "Jev refused the check",
+};
+
+export function ErrorView({ error }: { error: unknown }) {
+  const detail = error instanceof Error ? error.message : String(error);
+  if (!isAbideError(error)) return <Callout tone="bad" title={detail} />;
+  return (
+    <Callout tone="bad" title={TITLES[error.code]}>
+      <Text color={palette.mist} wrap="wrap">
+        {detail}
+      </Text>
+      <Text color={palette.ash}>{error.code}</Text>
+    </Callout>
+  );
+}

package/src/ui/views/HelpView.tsx

@@ -0,0 +1,51 @@
+import { Box, Text } from "ink";
+import { Header } from "../components/Header.js";
+import { palette } from "../theme.js";
+
+const COMMANDS: [string, string][] = [
+  ["login [--gateway]", "store your TypeSafe key in ~/.abide/.env, owner-only"],
+  ["init [agent] [--project]", "hook into claude, codex, opencode, or every one found here"],
+  ["compile", "compile the rubric now, in a headless Claude Code turn"],
+  ["tune [--global]", "rewrite rules that never fire, with their statistics attached"],
+  ["rubric validate [--global]", "check .abide/rubric.json and fill in source hashes"],
+  ["calibrate [--global]", "test every rule against this repo's recent history"],
+  ["check [paths] [--all]", "check uncommitted changes the way the hooks would"],
+  ["audit [paths] [--all]", "judge every file in scope as if just written; what breaks which rule"],
+  ["report", "what is compiled, what fired, what never fires"],
+  [
+    "replay <agent>",
+    "judge past claude, codex or opencode sessions in this repo as if abide had been installed",
+  ],
+  ["bench [--runs N]", "latency and spend, measured on this machine"],
+  ["uninstall [agent] [--project]", "remove the hooks from one agent, or all"],
+];
+
+export function HelpView() {
+  return (
+    <Box flexDirection="column">
+      <Header
+        command="help"
+        note="Enforce your own AGENTS.md rules on every edit a coding agent makes."
+      />
+      {COMMANDS.map(([name, what]) => (
+        <Box key={name}>
+          <Box width={30}>
+            <Text color={palette.cloud} bold>
+              {name}
+            </Text>
+          </Box>
+          <Text color={palette.mist}>{what}</Text>
+        </Box>
+      ))}
+      <Box marginTop={1} flexDirection="column">
+        <Text color={palette.ash}>
+          --json prints machine-readable output on report, check, audit, bench and calibrate.
+        </Text>
+        <Text color={palette.ash}>
+          Key: abide login, or TYPESAFE_AI_API_KEY (or AI_GATEWAY_API_KEY) in the environment or a
+          .env at the repo root.
+        </Text>
+      </Box>
+    </Box>
+  );
+}

package/src/ui/views/InitView.tsx

@@ -0,0 +1,103 @@
+import { Box, Text } from "ink";
+import { assertNever } from "@coldtea/abide-schema";
+import { Callout } from "../components/Callout.js";
+import { Checklist, type Step } from "../components/Checklist.js";
+import { Header } from "../components/Header.js";
+import { palette, scopeLabel } from "../theme.js";
+
+export type InitData =
+  | { kind: "no-key"; root: string }
+  | { kind: "no-sources"; root: string }
+  | {
+      kind: "installed";
+      root: string;
+      steps: Step[];
+      hosts: string[];
+      afterwards: string[];
+      sources: { path: string; scope: string; global: boolean }[];
+      rubric: { path: string; rules: number } | null;
+    };
+
+export function InitView({ data }: { data: InitData }) {
+  switch (data.kind) {
+    case "no-key":
+      return (
+        <Box flexDirection="column">
+          <Header command="init" where={data.root} />
+          <Callout tone="warn" title="No API key found, so abide has nothing to check with">
+            <Text color={palette.cloud}>
+              Get a TypeSafe key at typesafe.ai, then run{" "}
+              <Text color={palette.ceramic}>abide login</Text> and paste it.
+            </Text>
+            <Text color={palette.mist}>
+              Or put TYPESAFE_AI_API_KEY (or a Vercel AI_GATEWAY_API_KEY) in the environment or a
+              .env at the repo root.
+            </Text>
+            <Text color={palette.ash}>Never a flag. It is never logged.</Text>
+          </Callout>
+        </Box>
+      );
+    case "no-sources":
+      return (
+        <Box flexDirection="column">
+          <Header command="init" where={data.root} />
+          <Callout tone="warn" title="Found 0 instruction files, so there are 0 rules">
+            <Text color={palette.cloud}>
+              Add an AGENTS.md and run abide init again. Abide ships no rules of its own.
+            </Text>
+          </Callout>
+        </Box>
+      );
+    case "installed":
+      return (
+        <Box flexDirection="column">
+          <Header command="init" where={data.root} />
+          <Checklist steps={data.steps} />
+          <Box flexDirection="column" marginTop={1}>
+            <Text color={palette.mist}>Instruction files</Text>
+            {data.sources.map((s) => (
+              <Box key={s.path}>
+                <Text color={palette.cloud}> {s.path}</Text>
+                <Text color={palette.ash}>
+                  {" "}
+                  {s.global
+                    ? "global, every repo"
+                    : s.scope === "**/*"
+                      ? "everywhere in this repo"
+                      : `applies to ${scopeLabel([s.scope])}`}
+                </Text>
+              </Box>
+            ))}
+          </Box>
+          <Box marginTop={1}>
+            {data.rubric ? (
+              <Callout tone="ok" title={`Rubric present: ${data.rubric.rules} rules`}>
+                <Text color={palette.mist}>
+                  {data.rubric.path}. It is rehashed at the start of every session.
+                </Text>
+              </Callout>
+            ) : (
+              <Callout tone="accent" title={`Next: start ${data.hosts.join(" or ")} in this repo`}>
+                <Text color={palette.cloud}>
+                  The first turn compiles the rubric, on your own subscription.
+                </Text>
+                <Text color={palette.mist}>
+                  To compile right now instead: <Text color={palette.ceramic}>abide compile</Text>
+                </Text>
+              </Callout>
+            )}
+          </Box>
+          {data.afterwards.map((line) => (
+            <Text key={line} color={palette.amber}>
+              {line}
+            </Text>
+          ))}
+          <Text color={palette.ash}>
+            Later: abide report shows what fired, abide bench measures latency and spend here.
+          </Text>
+        </Box>
+      );
+    default:
+      return assertNever(data);
+  }
+}

package/src/ui/views/ReplayView.tsx

@@ -0,0 +1,100 @@
+import { Box, Text } from "ink";
+import type { DriftRow, ReplayResult, RuleTally } from "../../lib/replay.js";
+import { ms, usd } from "../../lib/ui.js";
+import { Columns } from "../components/Columns.js";
+import { Header } from "../components/Header.js";
+import { Section } from "../components/Section.js";
+import { glyph, palette } from "../theme.js";
+
+export type ReplayData = {
+  root: string;
+  host: string;
+  sessions: number;
+  edits: number;
+  result: ReplayResult;
+  drift: DriftRow[];
+  tallies: RuleTally[];
+  spendUsd: number;
+  elapsedMs: number;
+};
+
+const percent = (rate: number): string => `${Math.round(rate * 100)}%`;
+
+export function ReplayView({ data }: { data: ReplayData }) {
+  const judged = data.result.edits.filter((e) => e.error === undefined);
+  const broken = judged.filter((e) => e.verdicts.some((v) => v.band === "act"));
+  const failed = data.result.edits.filter((e) => e.error !== undefined);
+  const brokenTurns = data.result.turns.filter((t) => t.verdicts.some((v) => v.band === "act"));
+  const rows = data.tallies.filter((t) => t.broken + t.flagged > 0);
+  return (
+    <Box flexDirection="column">
+      <Header
+        command="replay"
+        where={data.root}
+        note={`${data.host} ${glyph.dotSep} ${data.sessions} sessions ${glyph.dotSep} ${judged.length} edits judged ${glyph.dotSep} ${ms(data.elapsedMs)} ${glyph.dotSep} about ${usd(data.spendUsd)}`}
+      />
+      <Section
+        title="What abide would have caught"
+        aside={`${broken.length} of ${judged.length} edits, ${brokenTurns.length} of ${data.result.turns.length} turns`}
+      >
+        <Columns
+          indent={2}
+          columns={[
+            { key: "label", label: "when", width: 20 },
+            { key: "edits", label: "edits", width: 6, align: "right" },
+            { key: "broken", label: "broken", width: 7, align: "right" },
+            { key: "rate", label: "rate", width: 6, align: "right" },
+          ]}
+          rows={data.drift.map((d) => ({
+            label: { text: d.label, color: palette.cloud },
+            edits: { text: String(d.edits), color: palette.mist },
+            broken: { text: String(d.broken), color: d.broken > 0 ? palette.rose : palette.mist },
+            rate: { text: percent(d.rate), color: palette.cloud, bold: true },
+          }))}
+        />
+      </Section>
+      <Section
+        title="By rule"
+        aside={rows.length === 0 ? "nothing fired" : `${rows.length} rules fired`}
+      >
+        {rows.length === 0 ? (
+          <Text color={palette.sage}>
+            {glyph.check} No edit or turn broke a rule above the act line.
+          </Text>
+        ) : (
+          <Columns
+            indent={2}
+            columns={[
+              { key: "rule", label: "rule", width: 34 },
+              { key: "phase", label: "phase", width: 5 },
+              { key: "broken", label: "broken", width: 7, align: "right" },
+              { key: "flagged", label: "uncertain", width: 9, align: "right" },
+              { key: "of", label: "of", width: 6, align: "right" },
+              { key: "example", label: "for example", keep: "tail" },
+            ]}
+            rows={rows.map((t) => ({
+              rule: { text: t.rule, color: palette.cloud, bold: true },
+              phase: { text: t.phase, color: palette.mist },
+              broken: { text: String(t.broken), color: t.broken > 0 ? palette.rose : palette.mist },
+              flagged: {
+                text: String(t.flagged),
+                color: t.flagged > 0 ? palette.amber : palette.mist,
+              },
+              of: { text: String(t.of), color: palette.ash },
+              example: { text: t.example, color: palette.ash },
+            }))}
+          />
+        )}
+      </Section>
+      {failed.length > 0 ? (
+        <Text color={palette.amber}>
+          {failed.length} edits could not be judged: {failed[0]?.error}
+        </Text>
+      ) : null}
+      <Text color={palette.ash}>
+        Jev is the judge here, so this is what abide would have flagged, not ground truth.
+        Shell-made changes are not in a transcript and were not judged.
+      </Text>
+    </Box>
+  );
+}

package/src/ui/views/ReportView.tsx

@@ -0,0 +1,225 @@
+import { Box, Text } from "ink";
+import type { AbideEvent, Rule } from "@coldtea/abide-schema";
+import { Buckets } from "../components/Buckets.js";
+import { Callout } from "../components/Callout.js";
+import { Columns } from "../components/Columns.js";
+import { Header } from "../components/Header.js";
+import { RuleTable, type RuleStats } from "../components/RuleTable.js";
+import { Section } from "../components/Section.js";
+import { median, ms, usd } from "../../lib/ui.js";
+import { glyph, palette } from "../theme.js";
+
+export type ReportData = {
+  root: string;
+  rules: Rule[];
+  events: AbideEvent[];
+  stats: Map<string, RuleStats>;
+  dead: Rule[];
+  problems: string[];
+};
+
+type Check = Extract<AbideEvent, { kind: "check" }>;
+
+const reasonOf = (rule: Rule): string =>
+  rule.check.type === "deferred" || rule.check.type === "unenforceable" ? rule.check.reason : "";
+
+export function ReportView({ data }: { data: ReportData }) {
+  const checks = data.events.filter((e): e is Check => e.kind === "check");
+  const errors = data.events.filter((e) => e.kind === "error").length;
+  const edit = checks.filter((c) => c.phase === "edit");
+  const turn = checks.filter((c) => c.phase === "turn");
+  const spend = (list: readonly Check[]) => list.reduce((s, c) => s + (c.usage?.costUsd ?? 0), 0);
+
+  const stuck = data.rules.filter((r) => r.status === "weak" || r.status === "noisy");
+  const notRunning = [...stuck, ...data.dead];
+  const lintable = data.rules.flatMap((r) =>
+    r.check.type === "lint"
+      ? [
+          {
+            id: r.id,
+            how: r.check.how ?? `pattern: ${r.check.pattern ?? ""}`,
+            overlaps: r.check.overlaps,
+          },
+        ]
+      : [],
+  );
+  const deferred = data.rules.filter((r) => r.check.type === "deferred");
+  const unenforceable = data.rules.filter((r) => r.check.type === "unenforceable");
+  const quiet = data.rules.filter((r) => {
+    const s = data.stats.get(r.id);
+    return (
+      r.status === "active" &&
+      r.check.type === "model" &&
+      s !== undefined &&
+      s.checks > 0 &&
+      s.fired === 0 &&
+      s.flagged === 0 &&
+      !data.dead.includes(r)
+    );
+  });
+
+  return (
+    <Box flexDirection="column">
+      <Header command="report" where={data.root} />
+      {data.problems.map((p) => (
+        <Callout key={p} tone="warn" title="A rubric could not be read and is being ignored">
+          <Text color={palette.mist}>{p}</Text>
+        </Callout>
+      ))}
+
+      <Section title="Rules">
+        <Buckets rules={data.rules} />
+        <Box marginTop={1}>
+          <RuleTable
+            rules={data.rules}
+            stats={checks.length > 0 ? data.stats : undefined}
+            runnableOnly
+          />
+        </Box>
+        {quiet.length > 0 ? (
+          <Box marginTop={1}>
+            <Text color={palette.ash}>
+              {quiet.length} {quiet.length === 1 ? "rule has" : "rules have"} answered no on every
+              check so far, which is what a clear answer looks like.
+            </Text>
+          </Box>
+        ) : null}
+      </Section>
+
+      {notRunning.length > 0 ? (
+        <Callout
+          tone="warn"
+          title={`${notRunning.length} ${notRunning.length === 1 ? "rule is switched off or never answers" : "rules are switched off or never answer"}. Likely badly worded.`}
+        >
+          {notRunning.map((r) => (
+            <Text key={r.id} color={palette.cloud}>
+              {r.id}
+              <Text color={palette.ash}>
+                {"  "}
+                {r.status === "weak"
+                  ? "weak, off"
+                  : r.status === "noisy"
+                    ? "noisy, off"
+                    : "never fired or flagged"}
+                {r.calibration ? ` ${glyph.dotSep} median ${r.calibration.median.toFixed(2)}` : ""}
+              </Text>
+            </Text>
+          ))}
+          <Text color={palette.mist}>Run abide tune to rewrite them.</Text>
+        </Callout>
+      ) : null}
+
+      {lintable.length > 0 ? (
+        <Section
+          title="For your linter"
+          aside={`${lintable.length} ${lintable.length === 1 ? "rule" : "rules"} a linter enforces exactly. Abide does not run them.`}
+        >
+          <Columns
+            indent={2}
+            columns={[
+              { key: "id", label: "", width: 30 },
+              { key: "have", label: "", width: 16 },
+              { key: "how", label: "" },
+            ]}
+            rows={lintable.map((r) => ({
+              id: { text: r.id, color: palette.mist },
+              how: { text: r.how, color: palette.cloud },
+              have: r.overlaps
+                ? { text: `${glyph.check} configured`, color: palette.sage }
+                : { text: "not configured", color: palette.amber },
+            }))}
+          />
+        </Section>
+      ) : null}
+
+      {deferred.length + unenforceable.length > 0 ? (
+        <Section
+          title="Not checked"
+          aside={`${deferred.length} deferred ${glyph.dotSep} ${unenforceable.length} unenforceable`}
+        >
+          {deferred.length > 0 ? (
+            <Box flexDirection="column">
+              <Text color={palette.ceramicWarm}>
+                Need the rest of the repository, which a diff does not carry
+              </Text>
+              <Columns
+                indent={2}
+                columns={[
+                  { key: "id", label: "", width: 30 },
+                  { key: "why", label: "" },
+                ]}
+                rows={deferred.map((r) => ({
+                  id: { text: r.id, color: palette.mist },
+                  why: { text: reasonOf(r), color: palette.ash },
+                }))}
+              />
+            </Box>
+          ) : null}
+          {unenforceable.length > 0 ? (
+            <Box flexDirection="column" marginTop={deferred.length > 0 ? 1 : 0}>
+              <Text color={palette.ash}>
+                About the process or the conversation, not a change to a file
+              </Text>
+              <Text color={palette.ash} wrap="wrap">
+                {"  "}
+                {unenforceable.map((r) => r.id).join(`  ${glyph.dotSep}  `)}
+              </Text>
+            </Box>
+          ) : null}
+        </Section>
+      ) : null}
+
+      <Section
+        title="Checks"
+        aside={
+          checks.length === 0 ? "none recorded yet" : `${checks.length} in .abide/events.jsonl`
+        }
+      >
+        {checks.length === 0 ? (
+          <Text color={palette.ash}>
+            Every check the hooks run lands here: what fired, how long it took, what it cost.
+          </Text>
+        ) : (
+          <Box flexDirection="column">
+            <Columns
+              indent={2}
+              columns={[
+                { key: "phase", label: "", width: 6 },
+                { key: "checks", label: "checks", width: 7, align: "right" },
+                { key: "blocked", label: "blocked", width: 8, align: "right" },
+                { key: "latency", label: "median", width: 8, align: "right" },
+                { key: "spend", label: "spend", width: 10, align: "right" },
+                { key: "pad", label: "" },
+              ]}
+              rows={[edit, turn].map((list, i) => ({
+                phase: {
+                  text: i === 0 ? "edit" : "turn",
+                  color: i === 0 ? palette.mist : palette.plum,
+                },
+                checks: { text: String(list.length), color: palette.cloud },
+                blocked: {
+                  text: String(list.filter((c) => c.blocked).length),
+                  color: list.some((c) => c.blocked) ? palette.rose : palette.mist,
+                },
+                latency: {
+                  text: list.length ? ms(median(list.map((c) => c.latencyMs)) ?? 0) : "",
+                  color: palette.cloud,
+                },
+                spend: { text: usd(spend(list)), color: palette.ceramic },
+                pad: { text: "" },
+              }))}
+            />
+            {errors > 0 ? (
+              <Box marginTop={1}>
+                <Text color={palette.amber}>
+                  {errors} {errors === 1 ? "check" : "checks"} failed or timed out. Those edits went
+                  unchecked.
+                </Text>
+              </Box>
+            ) : null}
+          </Box>
+        )}
+      </Section>
+    </Box>
+  );
+}

package/src/ui/views/RubricView.tsx

@@ -0,0 +1,82 @@
+import { Box, Text } from "ink";
+import type { Rule } from "@coldtea/abide-schema";
+import { Buckets } from "../components/Buckets.js";
+import { Callout } from "../components/Callout.js";
+import { Header } from "../components/Header.js";
+import { RuleTable } from "../components/RuleTable.js";
+import { Section } from "../components/Section.js";
+import { glyph, palette } from "../theme.js";
+
+export type RubricData =
+  | { kind: "invalid"; root: string; file: string; issues: string[] }
+  | {
+      kind: "ok";
+      root: string;
+      file: string;
+      rules: Rule[];
+      missing: string[];
+      orphaned: string[];
+    };
+
+export function RubricView({ data }: { data: RubricData }) {
+  if (data.kind === "invalid") {
+    return (
+      <Box flexDirection="column">
+        <Header command="rubric validate" where={data.root} />
+        <Callout tone="bad" title={`${data.file} is not a valid rubric`}>
+          {data.issues.map((issue) => (
+            <Text key={issue} color={palette.cloud}>
+              {glyph.dot} {issue}
+            </Text>
+          ))}
+        </Callout>
+      </Box>
+    );
+  }
+  const stuck = data.rules.filter((r) => r.status === "weak" || r.status === "noisy");
+  return (
+    <Box flexDirection="column">
+      <Header command="rubric validate" where={data.root} />
+      <Text color={palette.sage}>
+        {glyph.check} wrote {data.file} with source hashes
+      </Text>
+      {data.missing.length > 0 ? (
+        <Callout tone="bad" title="Sources that could not be hashed. Fix the path.">
+          <Text color={palette.cloud}>{data.missing.join(", ")}</Text>
+        </Callout>
+      ) : null}
+      {data.orphaned.length > 0 ? (
+        <Callout
+          tone="bad"
+          title='Rules whose source is not listed under "sources". Add it or fix the path.'
+        >
+          <Text color={palette.cloud}>{data.orphaned.join(", ")}</Text>
+        </Callout>
+      ) : null}
+      <Box marginTop={1}>
+        <Section title="Rules">
+          <Buckets rules={data.rules} />
+          <Box marginTop={1}>
+            <RuleTable rules={data.rules} />
+          </Box>
+        </Section>
+      </Box>
+      {stuck.length > 0 ? (
+        <Callout
+          tone="warn"
+          title={`${stuck.length} ${stuck.length === 1 ? "rule" : "rules"} will not run until rewritten`}
+        >
+          <Text color={palette.cloud}>
+            {stuck
+              .map(
+                (r) =>
+                  `${r.id} (${r.status}${r.calibration ? `, median ${r.calibration.median.toFixed(2)}` : ""})`,
+              )
+              .join(", ")}
+          </Text>
+          <Text color={palette.mist}>Run abide tune.</Text>
+        </Callout>
+      ) : null}
+    </Box>
+  );
+}