co-maintainer 0.4.0-beta.1

package/dist/src/store/skill_state.js

@@ -0,0 +1,24 @@
+import { cacheGet, cacheSet } from "./cache_db.js";
+import { isNotFound, readTextFile } from "../util/runtime.js";
+export async function readState(repo) {
+    const value = await cacheGet("state", repo);
+    if (value)
+        return JSON.parse(value);
+    try {
+        const legacy = JSON.parse(await readTextFile(`.cache/${repo}/state.json`));
+        if (legacy.options.maxPrMonths === undefined &&
+            legacy.options.maxPrYears !== undefined) {
+            legacy.options.maxPrMonths = legacy.options.maxPrYears * 12;
+        }
+        await writeState(legacy);
+        return legacy;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function writeState(state) {
+    await cacheSet("state", state.repo, JSON.stringify(state));
+}

package/dist/src/store/sqlite.d.ts

@@ -0,0 +1,39 @@
+/** Thin compatibility layer over `node:sqlite`, preserving the `@db/sqlite`
+ * surface the store layer was written against: a synchronous `Database`,
+ * `prepare<T>()` generics, `.get()/.all()/.run()`, and `db.changes`.
+ *
+ * Two behaviours of the JSR driver must be reproduced on top of
+ * `node:sqlite`:
+ *  - `undefined` parameters bind as SQL NULL (node:sqlite rejects undefined)
+ *  - `db.changes` reports the rows modified by the most recent `run()`, which
+ *    `node:sqlite` only returns from the statement call
+ */
+import { type StatementSync } from "node:sqlite";
+type BindValue = string | number | bigint | boolean | null | Uint8Array;
+type BindObject = Record<string, BindValue | undefined>;
+type Params = (BindValue | undefined)[] | [BindObject];
+/** Where a `Statement` reports its modified-row count back to its owner. */
+export type ChangeSink = {
+    recordChanges: (changes: number | bigint) => void;
+};
+export declare class Statement<Row = Record<string, unknown>> {
+    #private;
+    constructor(statement: StatementSync, sink: ChangeSink);
+    get(...params: Params): Row | undefined;
+    all(...params: Params): Row[];
+    run(...params: Params): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+}
+export declare class Database implements ChangeSink {
+    #private;
+    constructor(path: string);
+    /** Rows modified by the most recent `run()`. */
+    get changes(): number;
+    recordChanges(changes: number | bigint): void;
+    exec(sql: string): void;
+    prepare<Row = Record<string, unknown>>(sql: string): Statement<Row>;
+    close(): void;
+}
+export {};

package/dist/src/store/sqlite.js

@@ -0,0 +1,77 @@
+/** Thin compatibility layer over `node:sqlite`, preserving the `@db/sqlite`
+ * surface the store layer was written against: a synchronous `Database`,
+ * `prepare<T>()` generics, `.get()/.all()/.run()`, and `db.changes`.
+ *
+ * Two behaviours of the JSR driver must be reproduced on top of
+ * `node:sqlite`:
+ *  - `undefined` parameters bind as SQL NULL (node:sqlite rejects undefined)
+ *  - `db.changes` reports the rows modified by the most recent `run()`, which
+ *    `node:sqlite` only returns from the statement call
+ */
+import { DatabaseSync } from "node:sqlite";
+export class Statement {
+    #statement;
+    #sink;
+    constructor(statement, sink) {
+        this.#statement = statement;
+        this.#sink = sink;
+    }
+    get(...params) {
+        return this.#statement.get(...bind(args(params)));
+    }
+    all(...params) {
+        return this.#statement.all(...bind(args(params)));
+    }
+    run(...params) {
+        const result = this.#statement.run(...bind(args(params)));
+        this.#sink.recordChanges(result.changes);
+        return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+        };
+    }
+}
+/** Normalizes call arguments: a single object binds by name, everything else
+ * is a positional list with `undefined` mapped to NULL. */
+function args(params) {
+    if (params.length === 1 && isBindObject(params[0]))
+        return [params[0]];
+    return params.map((value) => value === undefined ? null : value);
+}
+function isBindObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Uint8Array));
+}
+// node:sqlite's declared input union is narrower than what it accepts at
+// runtime (named-parameter objects and Uint8Array blobs both work).
+function bind(params) {
+    return params;
+}
+export class Database {
+    #database;
+    #changes = 0;
+    constructor(path) {
+        // node --test runs test files in parallel processes, and the cache/app
+        // databases are shared; node:sqlite defaults to no busy timeout while
+        // @db/sqlite tolerated contention. Wait rather than throw SQLITE_BUSY.
+        this.#database = new DatabaseSync(path, { timeout: 5_000 });
+    }
+    /** Rows modified by the most recent `run()`. */
+    get changes() {
+        return this.#changes;
+    }
+    recordChanges(changes) {
+        this.#changes = Number(changes);
+    }
+    exec(sql) {
+        this.#database.exec(sql);
+    }
+    prepare(sql) {
+        return new Statement(this.#database.prepare(sql), this);
+    }
+    close() {
+        this.#database.close();
+    }
+}

package/dist/src/store/subjects.d.ts

@@ -0,0 +1,15 @@
+import type { RevisionFile } from "../review/revision.ts";
+import type { SubjectRevisionRow, SubjectRow } from "./rows.ts";
+export declare function getOrCreateRemoteSubject(repo: string, branch: string, tokenId: string): SubjectRow;
+export declare function deleteSubjectRevision(subjectId: string): void;
+export declare function getOrCreatePrSubject(repo: string, prNumber: number): SubjectRow;
+export declare function getSubjectRevision(subjectId: string): SubjectRevisionRow | undefined;
+export declare function saveSubjectRevision(input: {
+    subjectId: string;
+    reviewId: string;
+    files: RevisionFile[];
+    visiblePaths: string[];
+    guideBuiltAt: string | null;
+}): void;
+export declare function parseRevisionFiles(row: SubjectRevisionRow): RevisionFile[];
+export declare function parseVisiblePaths(row: SubjectRevisionRow): Set<string>;

package/dist/src/store/subjects.js

@@ -0,0 +1,78 @@
+import { getAppDb } from "./app_db.js";
+import { nowIso } from "../util/time.js";
+export function getOrCreateRemoteSubject(repo, branch, tokenId) {
+    const db = getAppDb();
+    const existing = db
+        .prepare(`SELECT * FROM subjects
+     WHERE kind = 'remote' AND repo = ? AND branch = ? AND token_id = ?`)
+        .get(repo, branch, tokenId);
+    if (existing)
+        return existing;
+    const row = {
+        id: crypto.randomUUID(),
+        kind: "remote",
+        repo,
+        pr_number: null,
+        branch,
+        token_id: tokenId,
+        created_at: nowIso(),
+        updated_at: nowIso(),
+    };
+    db.prepare(`INSERT INTO subjects (id, kind, repo, pr_number, branch, token_id, created_at, updated_at)
+     VALUES (?, 'remote', ?, NULL, ?, ?, ?, ?)`).run(row.id, repo, branch, tokenId, row.created_at, row.updated_at);
+    return row;
+}
+export function deleteSubjectRevision(subjectId) {
+    getAppDb()
+        .prepare(`DELETE FROM subject_revisions WHERE subject_id = ?`)
+        .run(subjectId);
+}
+export function getOrCreatePrSubject(repo, prNumber) {
+    const db = getAppDb();
+    const existing = db
+        .prepare(`SELECT * FROM subjects WHERE kind = 'pr' AND repo = ? AND pr_number = ?`)
+        .get(repo, prNumber);
+    if (existing)
+        return existing;
+    const row = {
+        id: crypto.randomUUID(),
+        kind: "pr",
+        repo,
+        pr_number: prNumber,
+        branch: null,
+        token_id: null,
+        created_at: nowIso(),
+        updated_at: nowIso(),
+    };
+    db.prepare(`INSERT INTO subjects (id, kind, repo, pr_number, branch, token_id, created_at, updated_at)
+     VALUES (?, 'pr', ?, ?, NULL, NULL, ?, ?)`).run(row.id, repo, prNumber, row.created_at, row.updated_at);
+    return row;
+}
+export function getSubjectRevision(subjectId) {
+    return getAppDb()
+        .prepare(`SELECT * FROM subject_revisions WHERE subject_id = ?`)
+        .get(subjectId);
+}
+export function saveSubjectRevision(input) {
+    const createdAt = nowIso();
+    getAppDb()
+        .prepare(`INSERT INTO subject_revisions
+       (subject_id, review_id, files_json, visible_paths_json, guide_built_at, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(subject_id) DO UPDATE SET
+       review_id = excluded.review_id,
+       files_json = excluded.files_json,
+       visible_paths_json = excluded.visible_paths_json,
+       guide_built_at = excluded.guide_built_at,
+       created_at = excluded.created_at`)
+        .run(input.subjectId, input.reviewId, JSON.stringify(input.files), JSON.stringify(input.visiblePaths), input.guideBuiltAt, createdAt);
+    getAppDb()
+        .prepare(`UPDATE subjects SET updated_at = ? WHERE id = ?`)
+        .run(createdAt, input.subjectId);
+}
+export function parseRevisionFiles(row) {
+    return JSON.parse(row.files_json);
+}
+export function parseVisiblePaths(row) {
+    return new Set(JSON.parse(row.visible_paths_json));
+}

package/dist/src/tools/codegraph.d.ts

@@ -0,0 +1,58 @@
+/** The version co-maintainer is built against. codegraph's CLI output shape is
+ * what the reviewer parses, so this is pinned rather than tracking latest: a
+ * format change upstream must be an explicit upgrade here, not a surprise on
+ * someone else's machine. Raise it, adjust whatever reads the output, done. */
+export declare const CODEGRAPH_VERSION = "1.6.0";
+export declare const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
+export type CommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type Runner = (command: string, args: string[]) => Promise<CommandResult>;
+export type EnsureOptions = {
+    /** Skips the prompt and installs. Set by `--allow-tool-install`. */
+    allowInstall?: boolean;
+    interactive?: boolean;
+    run?: Runner;
+    confirm?: (question: string) => boolean;
+    log?: (message: string) => void;
+    /** Overrides `toolsDir()`, for tests. */
+    root?: string;
+};
+export declare function runCommand(command: string, args: string[]): Promise<CommandResult>;
+/** One version per directory, so several can sit side by side and an upgrade
+ * never half-overwrites a working install. */
+export declare function versionDir(version: string, root?: string): string;
+export declare function binaryPath(version: string, root?: string): string;
+/** codegraph prints a bare semver on `--version`, but be lenient: any leading
+ * `v`, surrounding whitespace or trailing build text is tolerated so a future
+ * release that decorates the line does not read as "not installed". */
+export declare function parseVersion(stdout: string): string | undefined;
+export type Presence = {
+    state: "ok";
+    version: string;
+    path: string;
+} | {
+    state: "mismatch";
+    version: string;
+    path: string;
+} | {
+    state: "missing";
+};
+export declare function detect(version?: string, root?: string, run?: Runner): Promise<Presence>;
+export declare function installCommand(version?: string, root?: string): {
+    command: string;
+    args: string[];
+};
+export declare function installHint(version?: string, root?: string): string;
+/** Makes sure the pinned codegraph is available, asking first. Returns the path
+ * to the binary, or exits: co-maintainer indexes the repository with it, so
+ * declining is a decision not to run this command, not a degraded mode. */
+export declare function ensureCodegraph(options?: EnsureOptions): Promise<string>;
+/** Review paths must not call `Deno.exit` (plan §8.7, S13). */
+export declare function ensureCodegraphForReview(options?: EnsureOptions): Promise<{
+    path: string;
+} | {
+    reason: string;
+}>;

package/dist/src/tools/codegraph.js

@@ -0,0 +1,165 @@
+import { toolsDir } from "../config.js";
+import { commandOutput, isWindows, mkdir, stat } from "../util/runtime.js";
+import { askConfirm } from "../cli/prompt.js";
+/** The version co-maintainer is built against. codegraph's CLI output shape is
+ * what the reviewer parses, so this is pinned rather than tracking latest: a
+ * format change upstream must be an explicit upgrade here, not a surprise on
+ * someone else's machine. Raise it, adjust whatever reads the output, done. */
+export const CODEGRAPH_VERSION = "1.6.0";
+export const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph";
+export async function runCommand(command, args) {
+    // Windows resolves npm and other shims through the shell, not as bare exes.
+    const windows = isWindows();
+    const output = await commandOutput(windows ? "cmd" : command, {
+        args: windows ? ["/c", command, ...args] : args,
+        stdout: "piped",
+        stderr: "piped",
+    });
+    return {
+        code: output.code,
+        stdout: new TextDecoder().decode(output.stdout),
+        stderr: new TextDecoder().decode(output.stderr),
+    };
+}
+/** One version per directory, so several can sit side by side and an upgrade
+ * never half-overwrites a working install. */
+export function versionDir(version, root = toolsDir()) {
+    return `${root}/codegraph/${version}`;
+}
+export function binaryPath(version, root = toolsDir()) {
+    const dir = versionDir(version, root);
+    return isWindows()
+        ? `${dir}/node_modules/.bin/codegraph.cmd`
+        : `${dir}/node_modules/.bin/codegraph`;
+}
+/** codegraph prints a bare semver on `--version`, but be lenient: any leading
+ * `v`, surrounding whitespace or trailing build text is tolerated so a future
+ * release that decorates the line does not read as "not installed". */
+export function parseVersion(stdout) {
+    // No `\b` before the number: a `v` prefix is a word character, so a boundary
+    // would refuse to match the common `v1.6.0` spelling.
+    const match = stdout.match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+    return match?.[1];
+}
+export async function detect(version = CODEGRAPH_VERSION, root = toolsDir(), run = runCommand) {
+    const path = binaryPath(version, root);
+    try {
+        await stat(path);
+    }
+    catch {
+        return { state: "missing" };
+    }
+    const result = await run(path, ["--version"]);
+    const found = parseVersion(result.stdout) ?? parseVersion(result.stderr);
+    if (!found)
+        return { state: "missing" };
+    return found === version
+        ? { state: "ok", version: found, path }
+        : { state: "mismatch", version: found, path };
+}
+export function installCommand(version = CODEGRAPH_VERSION, root = toolsDir()) {
+    return {
+        command: "npm",
+        args: [
+            "install",
+            `${CODEGRAPH_PACKAGE}@${version}`,
+            "--prefix",
+            versionDir(version, root),
+            "--no-audit",
+            "--no-fund",
+        ],
+    };
+}
+export function installHint(version = CODEGRAPH_VERSION, root = toolsDir()) {
+    const { command, args } = installCommand(version, root);
+    return `${command} ${args.join(" ")}`;
+}
+async function defaultConfirm(question) {
+    return await askConfirm(question);
+}
+/** Makes sure the pinned codegraph is available, asking first. Returns the path
+ * to the binary, or exits: co-maintainer indexes the repository with it, so
+ * declining is a decision not to run this command, not a degraded mode. */
+export async function ensureCodegraph(options = {}) {
+    const root = options.root ?? toolsDir();
+    const run = options.run ?? runCommand;
+    const log = options.log ?? ((message) => console.log(message));
+    const interactive = options.interactive ?? process.stdin.isTTY === true;
+    const present = await detect(CODEGRAPH_VERSION, root, run);
+    if (present.state === "ok")
+        return present.path;
+    if (present.state === "mismatch") {
+        log(`[codegraph] expected ${CODEGRAPH_VERSION} but found ${present.version} ` +
+            `at ${present.path}; reinstalling the pinned version`);
+    }
+    if (!options.allowInstall) {
+        if (!interactive) {
+            log(`[codegraph] co-maintainer needs codegraph ${CODEGRAPH_VERSION} to index the repository.\n` +
+                `Run it with --allow-tool-install, or install it yourself:\n  ${installHint(CODEGRAPH_VERSION, root)}`);
+            process.exit(1);
+        }
+        const confirm = options.confirm ?? defaultConfirm;
+        const approved = confirm(`co-maintainer needs codegraph ${CODEGRAPH_VERSION} to index the repository.\n` +
+            `Install it into ${versionDir(CODEGRAPH_VERSION, root)} (your global PATH is not touched)?`);
+        if (!approved) {
+            log("[codegraph] declined; nothing was installed");
+            process.exit(1);
+        }
+    }
+    const { command, args } = installCommand(CODEGRAPH_VERSION, root);
+    log(`[codegraph] installing ${CODEGRAPH_PACKAGE}@${CODEGRAPH_VERSION}`);
+    await mkdir(versionDir(CODEGRAPH_VERSION, root), { recursive: true });
+    const result = await run(command, args);
+    if (result.code !== 0) {
+        log(`[codegraph] install failed (exit ${result.code}): ${result.stderr.trim() || result.stdout.trim()}`);
+        process.exit(1);
+    }
+    const after = await detect(CODEGRAPH_VERSION, root, run);
+    if (after.state !== "ok") {
+        log(`[codegraph] install finished but ${binaryPath(CODEGRAPH_VERSION, root)} is still not usable`);
+        process.exit(1);
+    }
+    log(`[codegraph] ready at ${after.path}`);
+    return after.path;
+}
+/** Review paths must not call `Deno.exit` (plan §8.7, S13). */
+export async function ensureCodegraphForReview(options = {}) {
+    const root = options.root ?? toolsDir();
+    const run = options.run ?? runCommand;
+    const log = options.log ?? ((message) => console.error(message));
+    const interactive = options.interactive ?? process.stdin.isTTY === true;
+    const present = await detect(CODEGRAPH_VERSION, root, run);
+    if (present.state === "ok")
+        return { path: present.path };
+    if (present.state === "mismatch") {
+        log(`[codegraph] expected ${CODEGRAPH_VERSION} but found ${present.version}; reinstalling`);
+    }
+    if (!options.allowInstall) {
+        if (!interactive) {
+            return {
+                reason: `codegraph ${CODEGRAPH_VERSION} is not installed (use --allow-tool-install)`,
+            };
+        }
+        const confirm = options.confirm ?? defaultConfirm;
+        const approved = confirm(`co-maintainer needs codegraph ${CODEGRAPH_VERSION} to index this repository.\n` +
+            `Install into ${versionDir(CODEGRAPH_VERSION, root)}?`);
+        if (!approved)
+            return { reason: "codegraph install declined" };
+    }
+    const { command, args } = installCommand(CODEGRAPH_VERSION, root);
+    log(`[codegraph] installing ${CODEGRAPH_PACKAGE}@${CODEGRAPH_VERSION}`);
+    await mkdir(versionDir(CODEGRAPH_VERSION, root), { recursive: true });
+    const result = await run(command, args);
+    if (result.code !== 0) {
+        return {
+            reason: result.stderr.trim() ||
+                result.stdout.trim() ||
+                `install failed (exit ${result.code})`,
+        };
+    }
+    const after = await detect(CODEGRAPH_VERSION, root, run);
+    if (after.state !== "ok") {
+        return { reason: "install finished but the binary is still not usable" };
+    }
+    return { path: after.path };
+}

package/dist/src/tools/codegraph_exec.d.ts

@@ -0,0 +1,13 @@
+import type { CommandResult } from "./codegraph.ts";
+export declare const LOCAL_CODEGRAPH_DIR = ".co-maintainer-codegraph";
+export declare const SERVER_CODEGRAPH_DIR = ".codegraph";
+export type ExecOptions = {
+    timeoutMs?: number | null;
+    codegraphDir?: string;
+    env?: Record<string, string>;
+};
+export type CodegraphRunner = (binary: string, args: string[], worktree: string) => Promise<CommandResult>;
+/** Run the codegraph CLI in a repo root (plan §13.4). No `cmd /c` wrapper. */
+export declare function execCodegraph(binary: string, args: string[], cwd: string, options?: ExecOptions): Promise<CommandResult>;
+export declare function createCodegraphRunner(indexDir: string): CodegraphRunner;
+export declare function runCodegraphTool(binary: string, args: string[], worktree: string, runner: CodegraphRunner): Promise<string>;

package/dist/src/tools/codegraph_exec.js

@@ -0,0 +1,66 @@
+import { commandOutput, commandSpawn, envToObject, } from "../util/runtime.js";
+export const LOCAL_CODEGRAPH_DIR = ".co-maintainer-codegraph";
+export const SERVER_CODEGRAPH_DIR = ".codegraph";
+const TOOL_TIMEOUT_MS = 60_000;
+const INDEX_COMMANDS = new Set(["init", "sync", "index", "unlock"]);
+/** Run the codegraph CLI in a repo root (plan §13.4). No `cmd /c` wrapper. */
+export async function execCodegraph(binary, args, cwd, options = {}) {
+    const indexDir = options.codegraphDir ?? LOCAL_CODEGRAPH_DIR;
+    const env = {
+        ...envToObject(),
+        CODEGRAPH_DIR: indexDir,
+        ...options.env,
+    };
+    const timeoutMs = options.timeoutMs === undefined ? TOOL_TIMEOUT_MS : options.timeoutMs;
+    const commandOptions = {
+        args,
+        cwd,
+        env,
+        stdout: "piped",
+        stderr: "piped",
+    };
+    if (timeoutMs === null) {
+        const output = await commandOutput(binary, commandOptions);
+        return decode(output);
+    }
+    const proc = commandSpawn(binary, commandOptions);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        proc.kill("SIGKILL");
+    }, timeoutMs);
+    const output = await proc.output();
+    clearTimeout(timer);
+    if (timedOut) {
+        return {
+            code: 1,
+            stdout: "",
+            stderr: `codegraph ${args[0] ?? ""} timed out after ${timeoutMs / 1000}s`,
+        };
+    }
+    return decode(output);
+}
+function decode(output) {
+    return {
+        code: output.code,
+        stdout: new TextDecoder().decode(output.stdout),
+        stderr: new TextDecoder().decode(output.stderr),
+    };
+}
+export function createCodegraphRunner(indexDir) {
+    return (binary, args, worktree) => {
+        const timeoutMs = INDEX_COMMANDS.has(args[0] ?? "") ? null : undefined;
+        return execCodegraph(binary, args, worktree, {
+            timeoutMs,
+            codegraphDir: indexDir,
+        });
+    };
+}
+export async function runCodegraphTool(binary, args, worktree, runner) {
+    const result = await runner(binary, args, worktree);
+    const output = result.stdout.trim() || result.stderr.trim();
+    if (result.code !== 0) {
+        return `codegraph ${args[0]} exited ${result.code}: ${output}`;
+    }
+    return output || "(no output)";
+}

package/dist/src/types.d.ts

@@ -0,0 +1,89 @@
+/** Cross-layer contracts only. A type owned by one layer (Fact, Source,
+ * PullRequest, State) lives next to the code that owns it instead, in
+ * `knowledge/types.ts` — see PLAN.md Section 3. */
+export type Json = Record<string, unknown>;
+export type Options = {
+    command: "probe" | "init" | "remake" | "review";
+    repo: string;
+    prNumber?: number;
+    debug: boolean;
+    logTime: boolean;
+    /** Reviews every changed file with no own/upstream split — the behavior
+     * before scope.ts existed. Off by default: a re-review round's diff can
+     * carry a merge from the default branch that dwarfs the PR's own change,
+     * and neither a human reviewer nor this flag's absence asks anyone to read
+     * it as if the PR authored it. */
+    reviewUpstream?: boolean;
+    /** CLI review enables codegraph by default (`--disable-codegraph` to skip).
+     * Server jobs still follow per-repo settings. Indexing adds tokens and time;
+     * measured PR recall gains were small when this was opt-in only (K25). */
+    useCodegraph?: boolean;
+    improveMatrix: number;
+    ghConcurrent: number;
+    aiConcurrent: number;
+    envPath?: string;
+    auth: "gh" | "pat";
+    githubPat?: string;
+    ai: "none" | "openrouter" | "hetzner";
+    aiToken?: string;
+    lowModel?: string;
+    highModel?: string;
+    synthesisVersion: number;
+    includeCodebase: boolean;
+    includePullRequests: boolean;
+    includePullRequestChanges: boolean;
+    includeCommitHistory: boolean;
+    includeHowRepoWorks: boolean;
+    maxCommits?: number;
+    maxPrMonths?: number;
+    maxPullRequestChangeLines?: number;
+    maxComments?: number;
+};
+export type GitHubClient = {
+    request<T>(endpoint: string): Promise<T>;
+    pages<T>(endpoint: string, limit?: number, progress?: (page: number, fetched: number) => void): Promise<T[]>;
+    /** POST JSON. Optional so collect-test fakes stay GET-only. Review
+     * posting requires it. */
+    write?<T>(endpoint: string, body: unknown): Promise<T>;
+    /** GitHub Checks API operations. Optional so read-only test clients and
+     * older integrations can continue to review without check runs. */
+    createCheckRun?<T>(endpoint: string, body: unknown): Promise<T>;
+    updateCheckRun?<T>(endpoint: string, body: unknown): Promise<T>;
+};
+export type AiToolCall = {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type AiMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content?: string | null;
+    tool_calls?: AiToolCall[];
+    tool_call_id?: string;
+    name?: string;
+};
+export type AiRequest = {
+    system?: string;
+    prompt: string;
+    messages?: AiMessage[];
+    tools?: Json[];
+    maxTokens: number;
+    job: string;
+    reasoningEffort?: "max" | "xhigh" | "high" | "medium" | "low" | "none";
+};
+export type AiResponse = {
+    text: string;
+    toolCalls?: AiToolCall[];
+    tokensIn: number;
+    tokensOut: number;
+    cost?: number;
+    model: string;
+    provider: "openrouter" | "hetzner";
+};
+export type AiProvider = {
+    supportsTools?: boolean;
+    complete(request: AiRequest): Promise<AiResponse>;
+};

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/util/atomic.d.ts

@@ -0,0 +1,4 @@
+/** Remove leftover `.<name>.tmp-*` files from an interrupted write.
+ * Only deletes temps older than `minAgeMs` so concurrent writers are not disturbed. */
+export declare function cleanStaleTempFiles(directory: string, baseName: string, minAgeMs?: number): Promise<void>;
+export declare function writeTextFileAtomic(path: string, text: string): Promise<void>;