co-maintainer 0.4.0-beta.1

package/dist/src/util/atomic.js

@@ -0,0 +1,78 @@
+import { basename, dirname } from "node:path";
+import { isNotFound, isWindows, mkdir, readDir, remove, rename, stat, writeTextFile, } from "../util/runtime.js";
+function tempName(dir, base) {
+    return `${dir}/.${base}.tmp-${crypto.randomUUID()}`;
+}
+/** Remove leftover `.<name>.tmp-*` files from an interrupted write.
+ * Only deletes temps older than `minAgeMs` so concurrent writers are not disturbed. */
+export async function cleanStaleTempFiles(directory, baseName, minAgeMs = 60_000) {
+    const prefix = `.${baseName}.tmp-`;
+    const cutoff = Date.now() - minAgeMs;
+    try {
+        for await (const entry of readDir(directory)) {
+            if (!entry.isFile || !entry.name.startsWith(prefix))
+                continue;
+            const path = `${directory}/${entry.name}`;
+            const info = await stat(path);
+            const mtime = info.mtimeMs;
+            if (mtime > cutoff)
+                continue;
+            await remove(path).catch(() => { });
+        }
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Windows `rename` does not replace an existing file; swap via a backup
+ * name so a failed promote can restore the previous contents. */
+async function promoteTempOnWindows(temp, path) {
+    if (!(await pathExists(path))) {
+        await rename(temp, path);
+        return;
+    }
+    const backup = `${path}.atomic-backup`;
+    await remove(backup).catch(() => { });
+    await rename(path, backup);
+    try {
+        await rename(temp, path);
+    }
+    catch (error) {
+        await rename(backup, path).catch(() => { });
+        throw error;
+    }
+    await remove(backup).catch(() => { });
+}
+/** Write then rename into place so readers never see a half-written file. */
+async function recoverWindowsAtomicBackup(path) {
+    if (!isWindows())
+        return;
+    const backup = `${path}.atomic-backup`;
+    if (!(await pathExists(path)) && (await pathExists(backup))) {
+        await rename(backup, path);
+    }
+}
+export async function writeTextFileAtomic(path, text) {
+    await recoverWindowsAtomicBackup(path);
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true });
+    const base = basename(path);
+    const temp = tempName(dir, base);
+    await writeTextFile(temp, text);
+    if (isWindows()) {
+        await promoteTempOnWindows(temp, path);
+    }
+    else {
+        await rename(temp, path);
+    }
+}

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

@@ -0,0 +1,3 @@
+/** @internal For tests — number of keys with an active or queued lock. */
+export declare function keyedLockActiveKeys(): number;
+export declare function withKeyedLock<T>(key: string, fn: () => Promise<T>): Promise<T>;

package/dist/src/util/keyed_lock.js

@@ -0,0 +1,33 @@
+const queues = new Map();
+/** @internal For tests — number of keys with an active or queued lock. */
+export function keyedLockActiveKeys() {
+    return queues.size;
+}
+export async function withKeyedLock(key, fn) {
+    let queue = queues.get(key);
+    if (!queue) {
+        queue = { running: false, waiters: [] };
+        queues.set(key, queue);
+    }
+    if (queue.running) {
+        await new Promise((resolve) => {
+            queue.waiters.push(resolve);
+        });
+    }
+    else {
+        queue.running = true;
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        const current = queues.get(key);
+        if (current) {
+            const wake = current.waiters.shift();
+            if (wake)
+                wake();
+            else
+                queues.delete(key);
+        }
+    }
+}

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

@@ -0,0 +1,11 @@
+/** Outside a job, `log()` just prints to the console. Inside one (wrapped
+ * with `withLogSink`), it also reaches `job_logs` and any live SSE
+ * subscriber, without threading a logger through every function signature. */
+type Sink = (phase: string, message: string) => void;
+/** Plan §8.4 — progress and logs on stderr during CLI review. */
+export declare function withCliLogsToStderr<T>(fn: () => Promise<T>): Promise<T>;
+export declare function withLogSink<T>(sink: Sink, fn: () => Promise<T>): Promise<T>;
+export declare function log(phase: string, message: string): void;
+export declare function startHeartbeat(phase: string | (() => string)): () => void;
+export declare function timed<T>(label: string, enabled: boolean, operation: () => Promise<T>): Promise<T>;
+export {};

package/dist/src/util/log.js

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const sinkStorage = new AsyncLocalStorage();
+let cliLogsToStderr = false;
+/** Plan §8.4 — progress and logs on stderr during CLI review. */
+export function withCliLogsToStderr(fn) {
+    const prev = cliLogsToStderr;
+    cliLogsToStderr = true;
+    return fn().finally(() => {
+        cliLogsToStderr = prev;
+    });
+}
+export function withLogSink(sink, fn) {
+    return sinkStorage.run(sink, fn);
+}
+export function log(phase, message) {
+    const sink = sinkStorage.getStore();
+    if (sink)
+        sink(phase, message);
+    else if (cliLogsToStderr)
+        console.error(`[${phase}] ${message}`);
+    else
+        console.log(`[${phase}] ${message}`);
+}
+export function startHeartbeat(phase) {
+    const started = Date.now();
+    const label = () => (typeof phase === "function" ? phase() : phase);
+    const timer = setInterval(() => {
+        log("progress", `still running ${label()} · ${Math.round((Date.now() - started) / 1000)}s elapsed`);
+    }, 15_000);
+    return () => clearInterval(timer);
+}
+export async function timed(label, enabled, operation) {
+    const started = performance.now();
+    try {
+        return await operation();
+    }
+    finally {
+        if (enabled) {
+            log("time", `${label} · ${((performance.now() - started) / 1000).toFixed(2)}s`);
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+export declare function redact(text: string): string;
+export declare function outsideCode(text: string, clean: (prose: string) => string): string;
+/** Dashboard and other human-readable copy. Secrets out, no dash, no
+ * semicolon. Code keeps its own punctuation or it stops compiling. */
+export declare function safeCopy(text: string): string;

package/dist/src/util/redact.js

@@ -0,0 +1,30 @@
+/** Matches known secret shapes, not a generic "long random string"
+ * heuristic — too many false positives on commit SHAs and hashes. */
+const PATTERNS = [
+    /gh[pousr]_[A-Za-z0-9]{20,}/g, // ghp_, gho_, ghu_, ghs_, ghr_ (classic GitHub PATs and tokens)
+    /github_pat_[A-Za-z0-9_]{20,}/g, // fine-grained GitHub PATs
+    /sk-or-[A-Za-z0-9-]{10,}/g, // OpenRouter keys
+    /cmr_[A-Za-z0-9_-]{20,}/g, // remote review bearer tokens
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+];
+export function redact(text) {
+    let result = text;
+    for (const pattern of PATTERNS) {
+        result = result.replace(pattern, "[redacted]");
+    }
+    return result;
+}
+/** Fenced blocks and inline code spans. The capture group puts code on odd
+ * split indices, so prose can be cleaned without rewriting the code. */
+const CODE = /(````[\s\S]*?````|```[\s\S]*?```|`[^`\n]*`)/;
+export function outsideCode(text, clean) {
+    return text
+        .split(CODE)
+        .map((part, index) => (index % 2 === 1 ? part : clean(part)))
+        .join("");
+}
+/** Dashboard and other human-readable copy. Secrets out, no dash, no
+ * semicolon. Code keeps its own punctuation or it stops compiling. */
+export function safeCopy(text) {
+    return outsideCode(redact(text), (prose) => prose.replaceAll("\u2014", ", ").replaceAll(";", "."));
+}

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

@@ -0,0 +1,90 @@
+import type { Stats } from "node:fs";
+export declare function isWindows(): boolean;
+export type Platform = "windows" | "darwin" | "linux";
+/** The current OS in the vocabulary the config paths already used under Deno
+ * (`"windows"`, not Node's `"win32"`). */
+export declare function currentPlatform(): Platform;
+/** A missing path: Node's `ENOENT`, plus `ENOTDIR` (a parent is a file). */
+export declare function isNotFound(error: unknown): boolean;
+export declare function getEnv(name: string): string | undefined;
+export declare function setEnv(name: string, value: string): void;
+export declare function deleteEnv(name: string): void;
+export declare function envToObject(): Record<string, string>;
+export declare function readTextFileSync(path: string | URL): string;
+export declare function writeTextFileSync(path: string | URL, text: string): void;
+export declare function mkdirSync(path: string | URL, options?: {
+    recursive?: boolean;
+}): void;
+export declare function removeSync(path: string | URL, options?: {
+    recursive?: boolean;
+}): void;
+export declare function statSync(path: string | URL): Stats;
+export declare function readTextFile(path: string | URL): Promise<string>;
+export declare function readFile(path: string | URL): Promise<Uint8Array>;
+export declare function writeTextFile(path: string | URL, text: string): Promise<void>;
+export declare function writeFile(path: string | URL, data: Uint8Array | string): Promise<void>;
+export declare function mkdir(path: string | URL, options?: {
+    recursive?: boolean;
+}): Promise<void>;
+export declare function remove(path: string | URL, options?: {
+    recursive?: boolean;
+}): Promise<void>;
+export declare function stat(path: string | URL): Promise<Stats>;
+export declare function lstat(path: string | URL): Promise<Stats>;
+export declare function readLink(path: string | URL): Promise<string>;
+export declare function rename(from: string, to: string): Promise<void>;
+export declare function chmod(path: string, mode: number): Promise<void>;
+export declare function makeTempDir(options?: {
+    prefix?: string;
+}): Promise<string>;
+export declare function makeTempDirSync(options?: {
+    prefix?: string;
+}): string;
+/** A uniquely named temp file (created empty), mirroring `Deno.makeTempFile`. */
+export declare function makeTempFile(options?: {
+    prefix?: string;
+    suffix?: string;
+}): Promise<string>;
+export type DirEntry = {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymlink: boolean;
+};
+export declare function readDir(dir: string | URL): AsyncGenerator<DirEntry>;
+export type CommandOptions = {
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    stdin?: "piped";
+    stdout?: "piped";
+    stderr?: "piped";
+    /** Windows runs `.cmd`/shell builtins only through a shell. */
+    shell?: boolean;
+};
+export type CommandOutput = {
+    success: boolean;
+    code: number;
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+};
+/** `Deno.Command(...).output()` equivalent: run to completion, capture both
+ * streams, never throw on a non-zero exit. */
+export declare function commandOutput(command: string, options?: CommandOptions): Promise<CommandOutput>;
+/** `Deno.Command(...).spawn()` then write to stdin: used by the `gh` client
+ * to pass a JSON body with `--input -`. */
+export declare function commandWithInput(command: string, options: CommandOptions, input: string): Promise<CommandOutput>;
+/** A spawned process that can be killed on timeout, mirroring
+ * `Deno.Command(...).spawn()` + `proc.kill()`. */
+export declare function commandSpawn(command: string, options?: CommandOptions): {
+    kill: (signal?: NodeJS.Signals) => void;
+    output: () => Promise<CommandOutput>;
+};
+/** Whether `pid` names a live process.
+ *
+ * Windows: `process.kill(pid, 0)` is unreliable (Node emulates signals and
+ * would terminate the target), so `tasklist` answers without touching it.
+ * POSIX: signal 0 checks existence without delivering; `ESRCH` means dead,
+ * while `EPERM` (or anything else) means it exists but is not ours — assume
+ * alive rather than risk two writers on the same database. */
+export declare function isProcessAlive(pid: number): boolean;

package/dist/src/util/runtime.js

@@ -0,0 +1,206 @@
+/** Production runtime helpers for the Node migration.
+ *
+ * These deliberately mirror the Deno API names and shapes the codebase was
+ * written against, so the migration is a mechanical `Deno.foo(` → `foo(`
+ * substitution and every deviation lives in exactly one file. Centralizes the
+ * two silent-break classes too: `"windows"` vs `"win32"`, and
+ * `Deno.errors.NotFound` vs `ENOENT`.
+ */
+import { chmod as fsChmod, lstat as fsLstat, mkdir as fsMkdir, mkdtemp as fsMkdtemp, readFile as fsReadFile, readdir, readlink as fsReadLink, rename as fsRename, rm as fsRm, stat as fsStat, writeFile as fsWriteFile, } from "node:fs/promises";
+import { mkdirSync as fsMkdirSync, mkdtempSync as fsMkdtempSync, readFileSync as fsReadFileSync, rmSync as fsRmSync, statSync as fsStatSync, writeFileSync as fsWriteFileSync, } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function isWindows() {
+    return process.platform === "win32";
+}
+/** The current OS in the vocabulary the config paths already used under Deno
+ * (`"windows"`, not Node's `"win32"`). */
+export function currentPlatform() {
+    return isWindows()
+        ? "windows"
+        : process.platform === "darwin"
+            ? "darwin"
+            : "linux";
+}
+/** A missing path: Node's `ENOENT`, plus `ENOTDIR` (a parent is a file). */
+export function isNotFound(error) {
+    const code = error?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+// ---------------------------------------------------------------- environment
+export function getEnv(name) {
+    return process.env[name];
+}
+export function setEnv(name, value) {
+    process.env[name] = value;
+}
+export function deleteEnv(name) {
+    delete process.env[name];
+}
+export function envToObject() {
+    const out = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+// ------------------------------------------------------------------- sync fs
+export function readTextFileSync(path) {
+    return fsReadFileSync(path, "utf8");
+}
+export function writeTextFileSync(path, text) {
+    fsWriteFileSync(path, text);
+}
+export function mkdirSync(path, options) {
+    fsMkdirSync(path, { recursive: options?.recursive ?? false });
+}
+export function removeSync(path, options) {
+    fsRmSync(path, { recursive: options?.recursive ?? false, force: false });
+}
+export function statSync(path) {
+    return fsStatSync(path);
+}
+// ------------------------------------------------------------------ async fs
+export function readTextFile(path) {
+    return fsReadFile(path, "utf8");
+}
+export function readFile(path) {
+    return fsReadFile(path);
+}
+export function writeTextFile(path, text) {
+    return fsWriteFile(path, text);
+}
+export function writeFile(path, data) {
+    return fsWriteFile(path, data);
+}
+export function mkdir(path, options) {
+    return fsMkdir(path, { recursive: options?.recursive ?? false }).then(() => { });
+}
+export function remove(path, options) {
+    return fsRm(path, { recursive: options?.recursive ?? false, force: false });
+}
+export function stat(path) {
+    return fsStat(path);
+}
+export function lstat(path) {
+    return fsLstat(path);
+}
+export function readLink(path) {
+    return fsReadLink(path);
+}
+export function rename(from, to) {
+    return fsRename(from, to);
+}
+export function chmod(path, mode) {
+    return fsChmod(path, mode);
+}
+export function makeTempDir(options) {
+    return fsMkdtemp(join(tmpdir(), options?.prefix ?? "cm-"));
+}
+export function makeTempDirSync(options) {
+    return fsMkdtempSync(join(tmpdir(), options?.prefix ?? "cm-"));
+}
+/** A uniquely named temp file (created empty), mirroring `Deno.makeTempFile`. */
+export async function makeTempFile(options) {
+    const dir = await fsMkdtemp(join(tmpdir(), options?.prefix ?? "cm-"));
+    const name = `${crypto.randomUUID()}${options?.suffix ?? ""}`;
+    const path = join(dir, name);
+    await fsWriteFile(path, "");
+    return path;
+}
+export async function* readDir(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        yield {
+            name: entry.name,
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+            isSymlink: entry.isSymbolicLink(),
+        };
+    }
+}
+function baseSpawnOptions(options) {
+    return {
+        cwd: options.cwd,
+        env: options.env,
+        shell: options.shell ?? false,
+    };
+}
+function collect(child) {
+    return new Promise((resolve, reject) => {
+        const stdout = [];
+        const stderr = [];
+        child.stdout?.on("data", (chunk) => stdout.push(chunk));
+        child.stderr?.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({
+                success: code === 0,
+                code: code ?? 1,
+                stdout: new Uint8Array(Buffer.concat(stdout)),
+                stderr: new Uint8Array(Buffer.concat(stderr)),
+            });
+        });
+    });
+}
+/** `Deno.Command(...).output()` equivalent: run to completion, capture both
+ * streams, never throw on a non-zero exit. */
+export function commandOutput(command, options = {}) {
+    const child = spawn(command, options.args ?? [], {
+        ...baseSpawnOptions(options),
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return collect(child);
+}
+/** `Deno.Command(...).spawn()` then write to stdin: used by the `gh` client
+ * to pass a JSON body with `--input -`. */
+export function commandWithInput(command, options, input) {
+    const child = spawn(command, options.args ?? [], {
+        ...baseSpawnOptions(options),
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stdin?.end(input);
+    return collect(child);
+}
+/** A spawned process that can be killed on timeout, mirroring
+ * `Deno.Command(...).spawn()` + `proc.kill()`. */
+export function commandSpawn(command, options = {}) {
+    const child = spawn(command, options.args ?? [], {
+        ...baseSpawnOptions(options),
+        stdio: [options.stdin === "piped" ? "pipe" : "ignore", "pipe", "pipe"],
+    });
+    return {
+        kill: (signal = "SIGTERM") => {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // already exited
+            }
+        },
+        output: () => collect(child),
+    };
+}
+/** Whether `pid` names a live process.
+ *
+ * Windows: `process.kill(pid, 0)` is unreliable (Node emulates signals and
+ * would terminate the target), so `tasklist` answers without touching it.
+ * POSIX: signal 0 checks existence without delivering; `ESRCH` means dead,
+ * while `EPERM` (or anything else) means it exists but is not ours — assume
+ * alive rather than risk two writers on the same database. */
+export function isProcessAlive(pid) {
+    if (isWindows()) {
+        const result = spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], {
+            encoding: "utf8",
+        });
+        return (result.stdout ?? "").trim().startsWith('"');
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}

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

@@ -0,0 +1,9 @@
+/** The one place every stored timestamp comes from. PLAN.md Section 3's
+ * "every timestamp is ISO8601 UTC" rule lives here instead of as a
+ * convention repeated at each call site — `store/*` never calls
+ * `new Date().toISOString()` directly. */
+export declare function nowIso(): string;
+/** Short relative label for dashboard tables. Never emits a dash or
+ * semicolon. */
+export declare function relativeTime(iso: string, nowMs?: number): string;
+export declare function daysAgoIso(days: number, nowMs?: number): string;

package/dist/src/util/time.js

@@ -0,0 +1,36 @@
+/** The one place every stored timestamp comes from. PLAN.md Section 3's
+ * "every timestamp is ISO8601 UTC" rule lives here instead of as a
+ * convention repeated at each call site — `store/*` never calls
+ * `new Date().toISOString()` directly. */
+export function nowIso() {
+    return new Date().toISOString();
+}
+/** Short relative label for dashboard tables. Never emits a dash or
+ * semicolon. */
+export function relativeTime(iso, nowMs = Date.now()) {
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return "";
+    const sec = Math.max(0, Math.round((nowMs - then) / 1000));
+    if (sec < 60)
+        return "just now";
+    const min = Math.round(sec / 60);
+    if (min < 60)
+        return min === 1 ? "1 minute ago" : `${min} minutes ago`;
+    const hour = Math.round(min / 60);
+    if (hour < 24)
+        return hour === 1 ? "1 hour ago" : `${hour} hours ago`;
+    const day = Math.round(hour / 24);
+    if (day === 1)
+        return "yesterday";
+    if (day < 30)
+        return `${day} days ago`;
+    const month = Math.round(day / 30);
+    if (month < 12)
+        return month === 1 ? "1 month ago" : `${month} months ago`;
+    const year = Math.round(day / 365);
+    return year === 1 ? "1 year ago" : `${year} years ago`;
+}
+export function daysAgoIso(days, nowMs = Date.now()) {
+    return new Date(nowMs - days * 24 * 60 * 60 * 1000).toISOString();
+}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/src/version.js

@@ -0,0 +1,5 @@
+/** The single source of truth for the released version: `package.json`.
+ * Import attributes work identically under Node 24 and Deno 2, and reading
+ * it once here keeps the six call sites independent of the file layout. */
+import pkg from "../package.json" with { type: "json" };
+export const VERSION = pkg.version;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "co-maintainer",
+  "version": "0.4.0-beta.1",
+  "description": "Analyzes a GitHub repository and writes repository-specific contribution guidance.",
+  "license": "MIT",
+  "bin": {
+    "co-maintainer": "./dist/main.js"
+  },
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/mod.js"
+  },
+  "scripts": {
+    "build": "npm run assets:embed && tsc -p tsconfig.build.json",
+    "assets:embed": "node scripts/embed_assets.mjs",
+    "prepack": "npm run build",
+    "test": "node --test \"src/**/*.test.ts\" \"benchmark/**/*.test.ts\"",
+    "check": "tsc --noEmit",
+    "lint": "oxlint",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
+    "dev": "node --watch main.ts",
+    "probe": "node main.ts probe",
+    "init": "node main.ts init",
+    "remake": "node main.ts remake",
+    "review": "node main.ts review",
+    "serve": "node main.ts serve",
+    "bench": "node benchmark/core_v2/run.ts",
+    "bench-rereview": "node benchmark/core_v2/run_rereview.ts",
+    "bench-swe-prbench": "node benchmark/swe-prbench/run.ts",
+    "bench-core-v3": "node benchmark/core_v3/run.ts",
+    "swe-prbench-prepare": "node benchmark/swe-prbench/prepare_dataset.ts",
+    "e2e": "node scripts/e2e.ts",
+    "review-local-e2e": "node scripts/review_local_e2e.ts",
+    "docs:build": "node scripts/build_docs.ts"
+  },
+  "dependencies": {
+    "marked": "^15.0.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "oxfmt": "^0.68.0",
+    "oxlint": "^1.83.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}