@coldtea/abide 0.0.1

package/src/lib/settings.ts

@@ -0,0 +1,112 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { AbideError } from "@coldtea/abide-schema";
+
+const hookEntrySchema = z
+  .object({ type: z.string(), command: z.string().optional() })
+  .passthrough();
+const hookGroupSchema = z
+  .object({ matcher: z.string().optional(), hooks: z.array(hookEntrySchema) })
+  .passthrough();
+const settingsSchema = z
+  .object({ hooks: z.record(z.string(), z.array(hookGroupSchema)).optional() })
+  .passthrough();
+type Settings = z.infer<typeof settingsSchema>;
+type HookEntry = z.infer<typeof hookEntrySchema>;
+type HookGroup = z.infer<typeof hookGroupSchema>;
+
+export const ABIDE_HOOK_MARKER = "abide-hook.js";
+
+export type HookEvent = "SessionStart" | "UserPromptSubmit" | "PostToolUse" | "Stop";
+
+export type HookSpec = { event: HookEvent; matcher?: string; command: string; timeout: number };
+
+export const hookSpecs = (hookScript: string): HookSpec[] => {
+  const cmd = (name: string): string => `node "${hookScript}" ${name}`;
+  return [
+    { event: "SessionStart", command: cmd("session-start"), timeout: 10 },
+    { event: "UserPromptSubmit", command: cmd("turn-start"), timeout: 10 },
+    {
+      event: "PostToolUse",
+      matcher: "Edit|Write|MultiEdit|apply_patch",
+      command: cmd("post-tool-use"),
+      timeout: 20,
+    },
+    { event: "Stop", command: cmd("stop"), timeout: 30 },
+  ];
+};
+
+const isOurs = (entry: HookEntry): boolean => entry.command?.includes(ABIDE_HOOK_MARKER) ?? false;
+
+/** A group shared with someone else's hook keeps theirs. */
+const withoutOurs = (groups: readonly HookGroup[]): { kept: HookGroup[]; removed: number } => {
+  const kept: HookGroup[] = [];
+  let removed = 0;
+  for (const group of groups) {
+    const hooks = group.hooks.filter((h) => !isOurs(h));
+    removed += group.hooks.length - hooks.length;
+    if (hooks.length > 0) kept.push({ ...group, hooks });
+  }
+  return { kept, removed };
+};
+
+export const readSettings = (file: string): Settings => {
+  let raw: string;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return {};
+  }
+  if (raw.trim() === "") return {};
+  try {
+    return settingsSchema.parse(JSON.parse(raw));
+  } catch (error) {
+    throw new AbideError("SETTINGS_INVALID", `${file} is not a settings file abide can edit`, {
+      cause: error,
+    });
+  }
+};
+
+export const installHooks = (file: string, specs: readonly HookSpec[]): void => {
+  const settings = readSettings(file);
+  const hooks = { ...(settings.hooks ?? {}) };
+  for (const spec of specs) {
+    const { kept } = withoutOurs(hooks[spec.event] ?? []);
+    const group: HookGroup = {
+      ...(spec.matcher === undefined ? {} : { matcher: spec.matcher }),
+      hooks: [{ type: "command", command: spec.command, timeout: spec.timeout }],
+    };
+    hooks[spec.event] = [...kept, group];
+  }
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ ...settings, hooks }, null, 2)}\n`);
+};
+
+export const uninstallHooks = (file: string): number => {
+  const settings = readSettings(file);
+  if (settings.hooks === undefined) return 0;
+  let removed = 0;
+  const hooks: Record<string, HookGroup[]> = {};
+  for (const [event, groups] of Object.entries(settings.hooks)) {
+    const result = withoutOurs(groups);
+    removed += result.removed;
+    if (result.kept.length > 0) hooks[event] = result.kept;
+  }
+  writeFileSync(file, `${JSON.stringify({ ...settings, hooks }, null, 2)}\n`);
+  return removed;
+};
+
+export const installedHookEvents = (file: string): HookEvent[] => {
+  const settings = readSettings(file);
+  const events: HookEvent[] = [];
+  for (const event of [
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "Stop",
+  ] satisfies HookEvent[]) {
+    if ((settings.hooks?.[event] ?? []).some((g) => g.hooks.some(isOurs))) events.push(event);
+  }
+  return events;
+};

package/src/lib/sources.ts

@@ -0,0 +1,154 @@
+import { readdirSync, existsSync, type Dirent } from "node:fs";
+import path from "node:path";
+import { createSourceSha, type Rubric } from "@coldtea/abide-schema";
+import { homeDir, resolveSourcePath, toSourcePath } from "./paths.js";
+import { readRegularFile } from "./regularFile.js";
+
+export type SourceCandidate = {
+  /** Rubric spelling: repo-relative or "~/...". */
+  path: string;
+  absolute: string;
+  /** Glob the file's rules apply to. */
+  scope: string;
+  /** Required candidates must appear in the rubric for it to be fresh. */
+  required: boolean;
+  origin: "root" | "nested" | "global" | "contributing";
+};
+
+const ROOT_NAMES = ["AGENTS.md", "CLAUDE.md", ".cursorrules"];
+const NESTED_NAMES = ["AGENTS.md", "CLAUDE.md"];
+const GLOBAL_NAMES = ["~/.claude/CLAUDE.md", "~/.codex/AGENTS.md", "~/.config/opencode/AGENTS.md"];
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  "vendor",
+  "coverage",
+  ".turbo",
+  ".cache",
+  "target",
+  ".abide",
+  ".claude",
+  ".codex",
+  ".opencode",
+]);
+const MAX_DEPTH = 6;
+
+const walkNested = (root: string, dir: string, depth: number, out: SourceCandidate[]): void => {
+  if (depth > MAX_DEPTH) return;
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+    const sub = path.join(dir, entry.name);
+    for (const name of NESTED_NAMES) {
+      const file = path.join(sub, name);
+      if (existsSync(file)) {
+        const rel = toSourcePath(root, sub);
+        out.push({
+          path: toSourcePath(root, file),
+          absolute: file,
+          scope: `${rel}/**/*`,
+          required: true,
+          origin: "nested",
+        });
+      }
+    }
+    walkNested(root, sub, depth + 1, out);
+  }
+};
+
+export const discoverProjectSources = (root: string): SourceCandidate[] => {
+  const found: SourceCandidate[] = [];
+  for (const name of ROOT_NAMES) {
+    const file = path.join(root, name);
+    if (existsSync(file)) {
+      found.push({ path: name, absolute: file, scope: "**/*", required: true, origin: "root" });
+    }
+  }
+  walkNested(root, root, 1, found);
+  const contributing = path.join(root, "CONTRIBUTING.md");
+  if (existsSync(contributing)) {
+    found.push({
+      path: "CONTRIBUTING.md",
+      absolute: contributing,
+      scope: "**/*",
+      required: false,
+      origin: "contributing",
+    });
+  }
+  return found;
+};
+
+export const discoverGlobalSources = (): SourceCandidate[] =>
+  GLOBAL_NAMES.flatMap((p) => {
+    const absolute = path.join(homeDir(), p.slice(2));
+    return existsSync(absolute)
+      ? [{ path: p, absolute, scope: "**/*", required: true, origin: "global" as const }]
+      : [];
+  });
+
+export const hashFile = (absolute: string): string | undefined => {
+  const bytes = readRegularFile(absolute);
+  return bytes === undefined ? undefined : createSourceSha(bytes);
+};
+
+export type Staleness =
+  | { status: "missing" }
+  | { status: "fresh" }
+  | { status: "stale"; changed: string[]; added: string[]; removed: string[]; unhashed: string[] };
+
+export const checkStaleness = (
+  rubric: Rubric | undefined,
+  candidates: SourceCandidate[],
+  root: string,
+): Staleness => {
+  if (rubric === undefined) return { status: "missing" };
+  const changed: string[] = [];
+  const removed: string[] = [];
+  const unhashed: string[] = [];
+  for (const source of rubric.sources) {
+    const now = hashFile(resolveSourcePath(root, source.path));
+    if (now === undefined) removed.push(source.path);
+    else if (source.sha === undefined) unhashed.push(source.path);
+    else if (source.sha !== now) changed.push(source.path);
+  }
+  const listed = new Set(rubric.sources.map((s) => path.resolve(resolveSourcePath(root, s.path))));
+  const added = candidates
+    .filter((c) => c.required && !listed.has(path.resolve(c.absolute)))
+    .map((c) => c.path);
+  if (changed.length + removed.length + unhashed.length + added.length === 0) {
+    return { status: "fresh" };
+  }
+  return { status: "stale", changed, added, removed, unhashed };
+};
+
+export const describeStaleness = (s: Staleness): string => {
+  switch (s.status) {
+    case "missing":
+      return "no rubric yet";
+    case "fresh":
+      return "up to date";
+    case "stale": {
+      const parts: string[] = [];
+      if (s.changed.length) parts.push(`changed: ${s.changed.join(", ")}`);
+      if (s.added.length) parts.push(`new: ${s.added.join(", ")}`);
+      if (s.removed.length) parts.push(`gone: ${s.removed.join(", ")}`);
+      if (s.unhashed.length) parts.push(`never hashed: ${s.unhashed.join(", ")}`);
+      return parts.join("; ");
+    }
+    default:
+      return assertNeverStaleness(s);
+  }
+};
+
+const assertNeverStaleness = (value: never): never => {
+  throw new Error(`Unhandled staleness: ${JSON.stringify(value)}`);
+};

package/src/lib/stdin.ts

@@ -0,0 +1,23 @@
+import { STDIN_TIMEOUT_MS } from "./constants.js";
+
+/** Reads all of stdin, giving up after a short wait so a host that sends nothing cannot hang us, and lets go of the handle. */
+export const readStdin = (timeoutMs = STDIN_TIMEOUT_MS): Promise<string> =>
+  new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    let settled = false;
+    const done = (): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.destroy();
+      } catch {
+        // nothing to release
+      }
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    };
+    const timer = setTimeout(done, timeoutMs);
+    process.stdin.on("data", (c: Buffer) => chunks.push(c));
+    process.stdin.on("end", done);
+    process.stdin.on("error", done);
+  });

package/src/lib/transcript.ts

@@ -0,0 +1,49 @@
+import { closeSync, readSync } from "node:fs";
+import { MAX_TASK_CHARS } from "./constants.js";
+import { openRegular } from "./regularFile.js";
+
+const TAIL_BYTES = 512 * 1024;
+
+const readTail = (file: string): string | undefined => {
+  const opened = openRegular(file);
+  if (opened === undefined) return undefined;
+  const { fd, size } = opened;
+  try {
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    readSync(fd, buffer, 0, buffer.length, start);
+    return buffer.toString("utf8");
+  } catch {
+    return undefined;
+  } finally {
+    closeSync(fd);
+  }
+};
+
+/** The user's most recent typed prompt, so the check knows what the change was for. */
+export const lastUserPrompt = (transcriptPath: string | undefined): string | undefined => {
+  if (transcriptPath === undefined) return undefined;
+  const tail = readTail(transcriptPath);
+  if (tail === undefined) return undefined;
+  const lines = tail.split("\n");
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (line === undefined || !line.includes('"type":"user"')) continue;
+    try {
+      const entry: unknown = JSON.parse(line);
+      if (typeof entry !== "object" || entry === null) continue;
+      const record: Record<string, unknown> = { ...entry };
+      if (record.type !== "user" || record.isMeta === true) continue;
+      const message = record.message;
+      if (typeof message !== "object" || message === null) continue;
+      const body: Record<string, unknown> = { ...message };
+      const content = body.content;
+      if (typeof content === "string" && content.trim() !== "") {
+        return content.trim().slice(0, MAX_TASK_CHARS);
+      }
+    } catch {
+      // torn line while the transcript is being written
+    }
+  }
+  return undefined;
+};

package/src/lib/ui.ts

@@ -0,0 +1,38 @@
+export const say = (line = ""): void => {
+  process.stdout.write(`${line}\n`);
+};
+
+export const warn = (line: string): void => {
+  process.stderr.write(`${line}\n`);
+};
+
+export const table = (rows: readonly (readonly string[])[]): string => {
+  const widths: number[] = [];
+  for (const row of rows)
+    row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, cell.length)));
+  return rows
+    .map((row) =>
+      row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0))).join("  "),
+    )
+    .join("\n");
+};
+
+export const ms = (n: number): string =>
+  n >= 1000 ? `${(n / 1000).toFixed(1)}s` : `${Math.round(n)}ms`;
+export const usd = (n: number): string => (n < 0.01 ? `$${n.toFixed(5)}` : `$${n.toFixed(3)}`);
+
+export const median = (values: readonly number[]): number | undefined => {
+  if (values.length === 0) return undefined;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  const a = sorted[mid];
+  const b = sorted[mid - 1];
+  if (a === undefined) return undefined;
+  return sorted.length % 2 === 1 || b === undefined ? a : (a + b) / 2;
+};
+
+export const percentile = (values: readonly number[], p: number): number | undefined => {
+  if (values.length === 0) return undefined;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)];
+};

package/src/ui/components/Buckets.tsx

@@ -0,0 +1,30 @@
+import { Box, Text } from "ink";
+import type { Rule } from "@coldtea/abide-schema";
+import { bucketCounts } from "../../lib/rubricFile.js";
+import { glyph, palette } from "../theme.js";
+
+/** One line: how many rules, and how each one is enforced. */
+export function Buckets({ rules }: { rules: readonly Rule[] }) {
+  const c = bucketCounts(rules);
+  const part = (n: number, label: string, color: string) => (
+    <>
+      <Text color={palette.mist}> {glyph.dotSep} </Text>
+      <Text color={n > 0 ? color : palette.ash} bold={n > 0}>
+        {n}
+      </Text>
+      <Text color={n > 0 ? palette.cloud : palette.ash}> {label}</Text>
+    </>
+  );
+  return (
+    <Box>
+      <Text color={palette.cloud} bold>
+        {c.total}
+      </Text>
+      <Text color={palette.cloud}> rules</Text>
+      {part(c.model, "checked by Jev", palette.indigo)}
+      {part(c.lint, "for your linter", palette.sage)}
+      {part(c.deferred, "deferred", palette.ceramicWarm)}
+      {part(c.unenforceable, "unenforceable", palette.ash)}
+    </Box>
+  );
+}

package/src/ui/components/Callout.tsx

@@ -0,0 +1,26 @@
+import { Box, Text } from "ink";
+import type { ReactNode } from "react";
+import { glyph, toneColor, type Tone } from "../theme.js";
+
+type CalloutProps = { tone: Tone; title: string; children?: ReactNode };
+
+/** Something the reader should act on, boxed so it is not lost in a table. */
+export function Callout({ tone, title, children }: CalloutProps) {
+  const color = toneColor[tone];
+  const mark = tone === "ok" ? glyph.check : tone === "bad" ? glyph.cross : glyph.dot;
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={color}
+      paddingX={1}
+      marginBottom={1}
+      alignSelf="flex-start"
+    >
+      <Text color={color} bold>
+        {mark} {title}
+      </Text>
+      {children ? <Box flexDirection="column">{children}</Box> : null}
+    </Box>
+  );
+}

package/src/ui/components/Checklist.tsx

@@ -0,0 +1,29 @@
+import { Box, Text } from "ink";
+import { glyph, palette } from "../theme.js";
+
+export type Step = { ok: boolean; text: string; detail?: string };
+
+/** What happened, one line per step, so a person can see where an install stopped. */
+export function Checklist({ steps }: { steps: readonly Step[] }) {
+  return (
+    <Box flexDirection="column">
+      {steps.map((step, i) => (
+        <Box key={i} flexDirection="column">
+          <Box>
+            <Text color={step.ok ? palette.sage : palette.rose}>
+              {step.ok ? glyph.check : glyph.cross}
+            </Text>
+            <Text color={palette.cloud}> {step.text}</Text>
+          </Box>
+          {step.detail ? (
+            <Box paddingLeft={2}>
+              <Text color={palette.ash} wrap="truncate-end">
+                {step.detail}
+              </Text>
+            </Box>
+          ) : null}
+        </Box>
+      ))}
+    </Box>
+  );
+}

package/src/ui/components/Columns.tsx

@@ -0,0 +1,62 @@
+import { Box, Text, useStdout } from "ink";
+import { palette, truncate } from "../theme.js";
+
+export type Column = {
+  key: string;
+  label: string;
+  /** Fixed width, or omitted for the one column that takes what is left. */
+  width?: number;
+  align?: "left" | "right";
+  keep?: "head" | "tail";
+};
+
+export type Cell = { text: string; color?: string; bold?: boolean; dim?: boolean };
+export type Row = Record<string, Cell>;
+
+type ColumnsProps = { columns: Column[]; rows: Row[]; indent?: number };
+
+const GAP = 2;
+const MIN_FLEX = 10;
+
+/**
+ * A table that fits the terminal. Fixed columns keep their width whatever
+ * happens, the flexible one takes what is left, and every cell is cut with an
+ * ellipsis rather than wrapped, so a row is always one line.
+ */
+export function Columns({ columns, rows, indent = 0 }: ColumnsProps) {
+  const { stdout } = useStdout();
+  const available = Math.max(60, (stdout?.columns ?? 100) - indent - 1);
+  const fixed = columns.reduce((sum, c) => sum + (c.width ?? 0), 0) + GAP * (columns.length - 1);
+  const flexWidth = Math.max(MIN_FLEX, available - fixed);
+  const widthOf = (c: Column): number => c.width ?? flexWidth;
+  const cell = (c: Column, content: Cell, header: boolean, last: boolean) => (
+    <Box
+      key={c.key}
+      width={widthOf(c)}
+      flexShrink={0}
+      marginRight={last ? 0 : GAP}
+      justifyContent={c.align === "right" ? "flex-end" : "flex-start"}
+    >
+      <Text
+        color={header ? palette.ash : (content.color ?? palette.cloud)}
+        bold={content.bold}
+        dimColor={content.dim}
+        wrap="truncate"
+      >
+        {truncate(content.text, widthOf(c), c.keep ?? "head")}
+      </Text>
+    </Box>
+  );
+  return (
+    <Box flexDirection="column">
+      <Box>{columns.map((c, i) => cell(c, { text: c.label }, true, i === columns.length - 1))}</Box>
+      {rows.map((row, r) => (
+        <Box key={r}>
+          {columns.map((c, i) =>
+            cell(c, row[c.key] ?? { text: "" }, false, i === columns.length - 1),
+          )}
+        </Box>
+      ))}
+    </Box>
+  );
+}

package/src/ui/components/Header.tsx

@@ -0,0 +1,35 @@
+import { Box, Text } from "ink";
+import { glyph, palette } from "../theme.js";
+
+type HeaderProps = {
+  command: string;
+  /** Where this ran, on its own line: a person switching between repos should not have to guess. */
+  where?: string;
+  note?: string;
+};
+
+export function Header({ command, where, note }: HeaderProps) {
+  return (
+    <Box flexDirection="column" marginBottom={1}>
+      <Box>
+        <Text color={palette.teal} bold>
+          abide
+        </Text>
+        <Text color={palette.mist}> {glyph.dotSep} </Text>
+        <Text color={palette.cloud} bold>
+          {command}
+        </Text>
+      </Box>
+      {where ? (
+        <Text color={palette.ash} wrap="truncate-start">
+          {where}
+        </Text>
+      ) : null}
+      {note ? (
+        <Text color={palette.mist} wrap="wrap">
+          {note}
+        </Text>
+      ) : null}
+    </Box>
+  );
+}

package/src/ui/components/Live.tsx

@@ -0,0 +1,73 @@
+import { Box, Text, useApp } from "ink";
+import Spinner from "ink-spinner";
+import { useEffect, useState, type ReactNode } from "react";
+import { palette } from "../theme.js";
+
+export type Progress = (label: string) => void;
+
+type LiveProps<T> = {
+  /** Shown above the spinner while `run` is going. */
+  header: ReactNode;
+  run: (progress: Progress) => Promise<T>;
+  done: (result: T) => ReactNode;
+  failed: (error: unknown) => ReactNode;
+  onExit?: (code: number) => void;
+  /** Redraw the progress line. Off on a pipe, where every frame would be printed as a new line. */
+  animate?: boolean;
+};
+
+type State<T> =
+  | { kind: "running"; label: string }
+  | { kind: "done"; result: T }
+  | { kind: "failed"; error: unknown };
+
+/** Runs a job and draws its progress, then its result, then leaves. */
+export function Live<T>({ header, run, done, failed, onExit, animate = true }: LiveProps<T>) {
+  const { exit } = useApp();
+  const [state, setState] = useState<State<T>>({ kind: "running", label: "starting" });
+  useEffect(() => {
+    let alive = true;
+    run((label) => {
+      if (alive && animate) setState({ kind: "running", label });
+    })
+      .then((result) => {
+        if (alive) setState({ kind: "done", result });
+      })
+      .catch((error: unknown) => {
+        if (alive) setState({ kind: "failed", error });
+      });
+    return () => {
+      alive = false;
+    };
+    // The job runs once for the life of the view.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  // Leave only after the final frame has been drawn, not in the same tick it was asked for.
+  useEffect(() => {
+    if (state.kind === "running") return;
+    onExit?.(state.kind === "done" ? 0 : 1);
+    exit();
+  }, [state.kind, exit, onExit]);
+  // The result view draws its own header, so the wrapper shows one only while there is nothing else to show.
+  return (
+    <Box flexDirection="column">
+      {state.kind === "running" ? header : null}
+      {state.kind === "running" ? (
+        animate ? (
+          <Box>
+            <Text color={palette.teal}>
+              <Spinner type="dots" />
+            </Text>
+            <Text color={palette.mist}> {state.label}</Text>
+          </Box>
+        ) : (
+          <Text color={palette.mist}>working</Text>
+        )
+      ) : state.kind === "done" ? (
+        done(state.result)
+      ) : (
+        failed(state.error)
+      )}
+    </Box>
+  );
+}