co-maintainer 0.4.6 → 0.4.7

package/README.md

@@ -1,6 +1,10 @@
 # co-maintainer
 
-[![NPM Version](https://img.shields.io/npm/v/co-maintainer)](https://www.npmjs.com/package/co-maintainer)
+[![NPM Version](https://img.shields.io/npm/v/co-maintainer)](https://www.npmjs.com/package/co-maintainer) [![](https://img.shields.io/badge/blog-co_maintainer_an_imitator_of_yours-blue)](https://muratkirazkaya.com/blogs/co-maintainer-an-imitator-of-yours)
+
+[Website](https://groophylifefor.github.io/co-maintainer/) ·
+[Docs](https://groophylifefor.github.io/co-maintainer/getting-started.html) ·
+[Cloud](https://dashboard.cm.ordu.dev/) (hosted, free, early access, invite only for now)
 
 `co-maintainer` analyzes a GitHub repository and writes repository-specific
 `SKILL.md` guidance that helps developers contribute changes more reliably.
@@ -18,24 +22,8 @@ npm install -g co-maintainer
 
 Requires Node.js 24 or newer.
 
-> **Migrating from JSR:** co-maintainer used to be published as
-> `jsr:@murat/co-maintainer` for Deno. JSR is deprecated and no longer updated;
-> install the npm package instead.
-
-On a Linux VPS, persist npm's global bin directory if the installer prints a
-PATH notice:
-
-```sh
-grep -qxF 'export PATH="$(npm prefix -g)/bin:$PATH"' ~/.bashrc || printf '\nexport PATH="$(npm prefix -g)/bin:$PATH"\n' >> ~/.bashrc
-source ~/.bashrc
-```
-
 ## Usage
 
-```sh
-co-maintainer probe owner/repo --auth=gh
-```
-
 ```sh
 co-maintainer probe owner/repo --auth=gh
 
@@ -54,24 +42,25 @@ co-maintainer review --json       # machine-readable stdout; logs on stderr
 npm run review-local-e2e        # fake-AI local loop (developers, from repo root)
 ```
 
-Documentation: [Getting started](docs/getting-started.html) (install → first
-review), [full docs site](docs/index.html), sources in [`docs/md/`](docs/md/).
+Documentation: [Getting started](https://groophylifefor.github.io/co-maintainer/getting-started.html)
+(install → first review), [full docs site](https://groophylifefor.github.io/co-maintainer/),
+sources in [`docs/md/`](docs/md/).
 
 Use `co-maintainer help`, `co-maintainer -h`, or `co-maintainer --help` for the
 full CLI help.
 
 ## Compared to other tools
 
-co-maintainer is a newly tool so not compared a lot of other tools. But did
-benchmarks with [OCR](https://open-codereview.ai/). Although I cannot offer any
-guarantees because I am working with very small datasets, but it shows promise.
+co-maintainer is a new tool, so it has not been compared with many others yet.
+It was benchmarked against [OCR](https://open-codereview.ai/). I cannot offer any
+guarantees because the datasets are very small, but it shows promise.
 
 In core_v2 benchmarks:
 
 - **2-3x better results** than OCR
 - **2-8x faster** than OCR
 - **70-200x fewer tokens** than OCR
-- **60-270x cheaper** than
+- **60-270x cheaper** than OCR
 
 ```mermaid
 xychart-beta

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "co-maintainer",
-    "version": "0.4.6",
+    "version": "0.4.7",
     "description": "Analyzes a GitHub repository and writes repository-specific contribution guidance.",
     "license": "MIT",
     "repository": {

package/dist/src/cli/commands/review.js

@@ -39,7 +39,7 @@ async function runReviewPr(options, cli) {
             throw new Error("review supports gh authentication only");
         }
         log("review", `reading PR #${options.prNumber} in ${options.repo} via gh`);
-        const result = await timed("review GitHub collection and AI", options.logTime, () => reviewPullRequest(new GhClient(), options, async (response) => {
+        const result = await timed("review GitHub collection and AI", options.logTime, () => reviewPullRequest(new GhClient(options.debug), options, async (response) => {
             aiMetrics.calls++;
             aiMetrics.tokensIn += response.tokensIn;
             aiMetrics.tokensOut += response.tokensOut;

package/dist/src/github/client.d.ts

@@ -1,17 +1,24 @@
 /** Shared by every `GitHubClient` implementation that talks over `fetch`
- * (pat.ts, and app.ts in P5). `GhClient` shells out to the `gh` binary,
- * which already retries on its own, so it never calls `githubFetch` — it
- * still shares `paginate`, the one 20-line loop every client used to carry
- * its own copy of. */
+ * (pat.ts, and app.ts). `GhClient` shells out to the `gh` binary and does
+ * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
 export declare class GitHubHttpError extends Error {
     readonly status: number;
     constructor(status: number, body: string);
 }
 export declare function isAccessDenied(error: unknown): boolean;
+/** Primary probes wake at the reset, but at least every half hour. */
+export declare const RATE_LIMIT_PROBE_MS: number;
+/** How long to sleep before the next try. A past reset is `0` (try now).
+ * An unreadable reset is one probe interval. */
+export declare function probeDelay(resetAt: Date, now: number): number;
+export declare function rateLimitError(resetAt: Date): Error;
+/** Sleep until `resetAt`, or at most `RATE_LIMIT_PROBE_MS`, whichever is
+ * sooner. Throws once this attempt has already waited two hours. A `0`
+ * delay returns immediately so the caller can try once more. */
+export declare function waitForRateLimit(resetAt: Date, startedAt: number): Promise<void>;
 /** A secondary (abuse-detection) rate limit carries a short `retry-after`
  * and is retried in place, up to three attempts total. A primary limit at
- * zero remaining fails the request right away, with the reset time in the
- * message, rather than pausing the caller for however long that reset
- * takes — the caller decides whether to wait, not this function. */
+ * zero remaining sleeps until its reset, probing at least every 30 minutes,
+ * then retries the same request. */
 export declare function githubFetch(url: string, init: RequestInit): Promise<Response>;
 export declare function paginate<T>(request: (endpoint: string) => Promise<T[]>, endpoint: string, limit?: number, progress?: (page: number, fetched: number) => void): Promise<T[]>;

package/dist/src/github/client.js

@@ -1,8 +1,7 @@
 /** Shared by every `GitHubClient` implementation that talks over `fetch`
- * (pat.ts, and app.ts in P5). `GhClient` shells out to the `gh` binary,
- * which already retries on its own, so it never calls `githubFetch` — it
- * still shares `paginate`, the one 20-line loop every client used to carry
- * its own copy of. */
+ * (pat.ts, and app.ts). `GhClient` shells out to the `gh` binary and does
+ * not use `githubFetch`; both paths share `paginate` and `waitForRateLimit`. */
+import { log } from "../util/log.js";
 export class GitHubHttpError extends Error {
     status;
     constructor(status, body) {
@@ -15,6 +14,10 @@ export function isAccessDenied(error) {
     return (error instanceof GitHubHttpError &&
         (error.status === 403 || error.status === 404));
 }
+/** Primary probes wake at the reset, but at least every half hour. */
+export const RATE_LIMIT_PROBE_MS = 30 * 60 * 1000;
+/** A sliding reset header must not pin a serve job. */
+const RATE_LIMIT_MAX_WAIT_MS = 2 * 60 * 60 * 1000;
 function rateLimit(headers) {
     const remaining = headers.get("x-ratelimit-remaining");
     const reset = headers.get("x-ratelimit-reset");
@@ -25,31 +28,92 @@ function rateLimit(headers) {
         resetAt: new Date(Number(reset) * 1000),
     };
 }
+/** How long to sleep before the next try. A past reset is `0` (try now).
+ * An unreadable reset is one probe interval. */
+export function probeDelay(resetAt, now) {
+    const until = resetAt.getTime() - now;
+    if (!Number.isFinite(until))
+        return RATE_LIMIT_PROBE_MS;
+    if (until <= 0)
+        return 0;
+    return Math.min(until, RATE_LIMIT_PROBE_MS);
+}
+export function rateLimitError(resetAt) {
+    const when = Number.isFinite(resetAt.getTime())
+        ? resetAt.toISOString()
+        : "unknown";
+    return new Error(`GitHub rate limit exhausted, resets at ${when}`);
+}
+function resetLabel(resetAt) {
+    return Number.isFinite(resetAt.getTime()) ? resetAt.toISOString() : "unknown";
+}
+// ponytail: one process-wide sleep. A search limit (minutes) and a core
+// limit (an hour) exhausted together wait out the longer one.
+let rateLimitGate;
+function pauseForReset(resetAt, delay) {
+    if (rateLimitGate)
+        return rateLimitGate;
+    log("github", `rate limit, next probe in ${Math.ceil(delay / 60_000)}m (reset ${resetLabel(resetAt)})`);
+    const pending = new Promise((resolve) => {
+        setTimeout(resolve, delay);
+    });
+    rateLimitGate = pending.finally(() => {
+        rateLimitGate = undefined;
+    });
+    return rateLimitGate;
+}
+/** Sleep until `resetAt`, or at most `RATE_LIMIT_PROBE_MS`, whichever is
+ * sooner. Throws once this attempt has already waited two hours. A `0`
+ * delay returns immediately so the caller can try once more. */
+export async function waitForRateLimit(resetAt, startedAt) {
+    if (Date.now() - startedAt >= RATE_LIMIT_MAX_WAIT_MS) {
+        throw rateLimitError(resetAt);
+    }
+    const delay = probeDelay(resetAt, Date.now());
+    if (delay === 0)
+        return;
+    await pauseForReset(resetAt, delay);
+}
 /** A secondary (abuse-detection) rate limit carries a short `retry-after`
  * and is retried in place, up to three attempts total. A primary limit at
- * zero remaining fails the request right away, with the reset time in the
- * message, rather than pausing the caller for however long that reset
- * takes — the caller decides whether to wait, not this function. */
+ * zero remaining sleeps until its reset, probing at least every 30 minutes,
+ * then retries the same request. */
 export async function githubFetch(url, init) {
-    let response;
-    for (let attempt = 1; attempt <= 3; attempt++) {
-        response = await fetch(url, init);
-        if (response.status !== 403 && response.status !== 429)
+    const started = Date.now();
+    let spun = false;
+    for (;;) {
+        let response;
+        let exhausted;
+        for (let attempt = 1; attempt <= 3; attempt++) {
+            response = await fetch(url, init);
+            if (response.status !== 403 && response.status !== 429)
+                return response;
+            const retryAfterHeader = response.headers.get("retry-after");
+            const retryAfter = retryAfterHeader === null ? NaN : Number(retryAfterHeader);
+            if (Number.isFinite(retryAfter) && retryAfter >= 0 && attempt < 3) {
+                console.log(`[github] secondary rate limit, waiting ${retryAfter}s (attempt ${attempt} of 3)`);
+                await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+                continue;
+            }
+            const limit = rateLimit(response.headers);
+            if (limit && limit.remaining === 0) {
+                exhausted = limit;
+                break;
+            }
             return response;
-        const retryAfterHeader = response.headers.get("retry-after");
-        const retryAfter = retryAfterHeader === null ? NaN : Number(retryAfterHeader);
-        if (Number.isFinite(retryAfter) && retryAfter >= 0 && attempt < 3) {
-            console.log(`[github] secondary rate limit, waiting ${retryAfter}s (attempt ${attempt} of 3)`);
-            await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
-            continue;
         }
-        const limit = rateLimit(response.headers);
-        if (limit && limit.remaining === 0) {
-            throw new Error(`GitHub rate limit exhausted, resets at ${limit.resetAt.toISOString()}`);
+        if (!exhausted)
+            return response;
+        const delay = probeDelay(exhausted.resetAt, Date.now());
+        if (delay === 0) {
+            if (spun)
+                throw rateLimitError(exhausted.resetAt);
+            spun = true;
+            continue;
         }
-        return response;
+        spun = false;
+        await waitForRateLimit(exhausted.resetAt, started);
     }
-    return response;
 }
 export async function paginate(request, endpoint, limit, progress) {
     const items = [];

package/dist/src/github/gh.d.ts

@@ -1,8 +1,26 @@
 import type { GitHubClient } from "../types.ts";
+type QuotaRow = {
+    limit?: number;
+    remaining?: number;
+    reset?: number;
+};
+type QuotaBody = {
+    resources?: {
+        core?: QuotaRow;
+        search?: QuotaRow;
+    };
+};
+/** `core 4120/5000 · search 28/30 · reset 21:58` from a `rate_limit` body. */
+export declare function quotaLine(body: QuotaBody): string;
 export declare class GhClient implements GitHubClient {
+    private readonly debug;
+    constructor(debug?: boolean);
     request<T>(endpoint: string): Promise<T>;
     write<T>(endpoint: string, body: unknown): Promise<T>;
     createCheckRun<T>(endpoint: string, body: unknown): Promise<T>;
     updateCheckRun<T>(endpoint: string, body: unknown): Promise<T>;
     pages<T>(endpoint: string, limit?: number, progress?: (page: number, fetched: number) => void): Promise<T[]>;
+    private send;
+    private call;
 }
+export {};

package/dist/src/github/gh.js

@@ -1,63 +1,152 @@
-import { paginate } from "./client.js";
-import { commandOutput, commandWithInput } from "../util/runtime.js";
-export class GhClient {
-    async request(endpoint) {
+import { paginate, probeDelay, RATE_LIMIT_PROBE_MS, rateLimitError, waitForRateLimit, } from "./client.js";
+import { log } from "../util/log.js";
+import { commandOutput, commandWithInput, } from "../util/runtime.js";
+const PULSE_MS = 120_000;
+let lastCallAt = 0;
+let pulse;
+function count(value) {
+    return typeof value === "number" ? String(value) : "?";
+}
+function hhmm(reset) {
+    if (typeof reset !== "number" || !Number.isFinite(reset))
+        return "??:??";
+    const date = new Date(reset * 1000);
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    return `${hours}:${minutes}`;
+}
+/** `core 4120/5000 · search 28/30 · reset 21:58` from a `rate_limit` body. */
+export function quotaLine(body) {
+    const core = body.resources?.core;
+    const search = body.resources?.search;
+    return `github quota · core ${count(core?.remaining)}/${count(core?.limit)} · search ${count(search?.remaining)}/${count(search?.limit)} · reset ${hhmm(core?.reset)}`;
+}
+async function printQuota() {
+    try {
         const result = await commandOutput("gh", {
-            args: ["api", endpoint],
+            args: ["api", "rate_limit"],
             stdout: "piped",
             stderr: "piped",
         });
-        if (!result.success) {
-            const error = new TextDecoder().decode(result.stderr).trim();
-            throw new Error(`gh api failed: ${error || endpoint}`);
-        }
-        try {
-            return JSON.parse(new TextDecoder().decode(result.stdout));
+        if (!result.success)
+            return;
+        log("debug", quotaLine(JSON.parse(new TextDecoder().decode(result.stdout))));
+    }
+    catch {
+        // The line is diagnostic. The request it follows still stands.
+    }
+}
+function unref(timer) {
+    if (typeof timer === "object" && timer !== null && "unref" in timer) {
+        timer.unref();
+    }
+}
+/** While `gh` calls keep landing, print the quota every two minutes.
+ * The probe itself does not count as a call, so a quiet process stops. */
+function noteGhCall(debug) {
+    if (!debug)
+        return;
+    lastCallAt = Date.now();
+    if (pulse)
+        return;
+    const timer = setInterval(() => {
+        if (Date.now() - lastCallAt > PULSE_MS) {
+            clearInterval(timer);
+            pulse = undefined;
+            return;
         }
-        catch {
-            throw new Error(`gh returned invalid JSON for ${endpoint}`);
+        void printQuota();
+    }, PULSE_MS);
+    unref(timer);
+    pulse = timer;
+}
+async function readLimit(endpoint) {
+    try {
+        const result = await commandOutput("gh", {
+            args: ["api", "rate_limit"],
+            stdout: "piped",
+            stderr: "piped",
+        });
+        if (!result.success)
+            return undefined;
+        const body = JSON.parse(new TextDecoder().decode(result.stdout));
+        const row = endpoint.startsWith("search/")
+            ? body.resources?.search
+            : body.resources?.core;
+        if (!row ||
+            typeof row.remaining !== "number" ||
+            typeof row.reset !== "number") {
+            return undefined;
         }
+        return { remaining: row.remaining, resetAt: new Date(row.reset * 1000) };
     }
-    async write(endpoint, body) {
-        const result = await commandWithInput("gh", {
-            args: ["api", "-X", "POST", endpoint, "--input", "-"],
-            stdin: "piped",
+    catch {
+        return undefined;
+    }
+}
+export class GhClient {
+    debug;
+    constructor(debug = false) {
+        this.debug = debug;
+    }
+    request(endpoint) {
+        return this.call(endpoint, () => commandOutput("gh", {
+            args: ["api", endpoint],
             stdout: "piped",
             stderr: "piped",
-        }, JSON.stringify(body));
-        if (!result.success) {
-            const error = new TextDecoder().decode(result.stderr).trim();
-            throw new Error(`gh api failed: ${error || endpoint}`);
-        }
-        try {
-            return JSON.parse(new TextDecoder().decode(result.stdout));
-        }
-        catch {
-            throw new Error(`gh returned invalid JSON for ${endpoint}`);
-        }
+        }));
+    }
+    write(endpoint, body) {
+        return this.send(endpoint, "POST", body);
+    }
+    createCheckRun(endpoint, body) {
+        return this.write(endpoint, body);
     }
-    async createCheckRun(endpoint, body) {
-        return await this.write(endpoint, body);
+    updateCheckRun(endpoint, body) {
+        return this.send(endpoint, "PATCH", body);
     }
-    async updateCheckRun(endpoint, body) {
-        const result = await commandWithInput("gh", {
-            args: ["api", "-X", "PATCH", endpoint, "--input", "-"],
+    pages(endpoint, limit, progress) {
+        return paginate((e) => this.request(e), endpoint, limit, progress);
+    }
+    send(endpoint, method, body) {
+        return this.call(endpoint, () => commandWithInput("gh", {
+            args: ["api", "-X", method, endpoint, "--input", "-"],
             stdin: "piped",
             stdout: "piped",
             stderr: "piped",
-        }, JSON.stringify(body));
-        if (!result.success) {
+        }, JSON.stringify(body)));
+    }
+    async call(endpoint, run) {
+        noteGhCall(this.debug);
+        const started = Date.now();
+        let spun = false;
+        for (;;) {
+            const result = await run();
+            if (result.success) {
+                try {
+                    return JSON.parse(new TextDecoder().decode(result.stdout));
+                }
+                catch {
+                    throw new Error(`gh returned invalid JSON for ${endpoint}`);
+                }
+            }
             const error = new TextDecoder().decode(result.stderr).trim();
-            throw new Error(`gh api failed: ${error || endpoint}`);
-        }
-        try {
-            return JSON.parse(new TextDecoder().decode(result.stdout));
+            const bucket = await readLimit(endpoint);
+            const limited = bucket
+                ? bucket.remaining === 0
+                : /rate limit/i.test(error);
+            if (!limited)
+                throw new Error(`gh api failed: ${error || endpoint}`);
+            const resetAt = bucket?.resetAt ?? new Date(Date.now() + RATE_LIMIT_PROBE_MS);
+            const delay = probeDelay(resetAt, Date.now());
+            if (delay === 0) {
+                if (spun)
+                    throw rateLimitError(resetAt);
+                spun = true;
+                continue;
+            }
+            spun = false;
+            await waitForRateLimit(resetAt, started);
         }
-        catch {
-            throw new Error(`gh returned invalid JSON for ${endpoint}`);
-        }
-    }
-    pages(endpoint, limit, progress) {
-        return paginate((e) => this.request(e), endpoint, limit, progress);
     }
 }

package/dist/src/services/setup.js

@@ -36,7 +36,7 @@ export function clientFor(options) {
     if (options.auth === "pat") {
         return new PatClient(options.githubPat ?? "");
     }
-    return new GhClient();
+    return new GhClient(options.debug);
 }
 function optionsForState(options) {
     const { command: _, aiToken: __, githubPat: ___, ...rest } = options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "co-maintainer",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Analyzes a GitHub repository and writes repository-specific contribution guidance.",
   "license": "MIT",
   "repository": {