co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/ai/openrouter.js

@@ -1,7 +1,35 @@
 import { chatBody, parseChatResponse } from "./provider.js";
+import { getEnv } from "../util/runtime.js";
+import { CliError, EXIT_RUNTIME, EXIT_USAGE, networkFailure, } from "../cli/error.js";
+/** Provider failures as actionable text (CORE-12, F24/F28). A 401 and a 400 for
+ * an unknown model are preconditions the user can fix, so they are usage
+ * errors; anything else is a runtime failure. Only the provider's own
+ * `error.message` is surfaced: the raw body can carry account metadata
+ * (`user_id`) that has no business in a terminal. */
+export function openRouterError(model, status, body) {
+    let detail = "";
+    try {
+        const parsed = JSON.parse(body);
+        detail = String(parsed.error?.message ?? "");
+    }
+    catch {
+        detail = body.trim().slice(0, 200);
+    }
+    if (status === 401 || status === 403) {
+        return new CliError("openrouter_unauthorized", "OpenRouter rejected the API key.", "Set a new one with co-maintainer set --token=...", EXIT_USAGE);
+    }
+    if (status === 400 && /model/i.test(detail)) {
+        return new CliError("openrouter_unknown_model", `OpenRouter does not know the model ${model}.`, `Pick one at https://openrouter.ai/models and set it with co-maintainer set --high-model=...`, EXIT_USAGE);
+    }
+    return new CliError("openrouter_failed", `OpenRouter failed with ${status}${detail ? `: ${detail}` : "."}`, undefined, EXIT_RUNTIME);
+}
 export class OpenRouterProvider {
     supportsTools = true;
-    endpoint = "https://openrouter.ai/api/v1/chat/completions";
+    /** `CM_OPENROUTER_URL` points the provider at a local fake in tests. It is
+     * only a default override: with the env unset the real endpoint is used, so
+     * nothing changes for users. */
+    endpoint = getEnv("CM_OPENROUTER_URL") ??
+        "https://openrouter.ai/api/v1/chat/completions";
     apiKey;
     model;
     constructor(apiKey, model) {
@@ -10,19 +38,45 @@ export class OpenRouterProvider {
         this.apiKey = apiKey;
         this.model = model;
     }
+    /** One POST. Returns the raw response so `complete` can decide whether the
+     * failure is worth a retry without the schema. */
+    async post(body) {
+        try {
+            return await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                    "HTTP-Referer": "https://github.com/GroophyLifefor/co-maintainer",
+                    "X-Title": "co-maintainer",
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            // `fetch failed` alone names neither the host nor the cause (CORE-12).
+            throw networkFailure(this.endpoint, error);
+        }
+    }
     async complete(request) {
-        const response = await fetch(this.endpoint, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.apiKey}`,
-                "Content-Type": "application/json",
-                "HTTP-Referer": "https://github.com/GroophyLifefor/co-maintainer",
-                "X-Title": "co-maintainer",
-            },
-            body: JSON.stringify(chatBody(this.model, request)),
-        });
+        let response = await this.post(chatBody(this.model, request));
+        // A provider may refuse `response_format` next to `tools`. The schema is
+        // only a hint — the prompt also asks for a fenced JSON block — so one
+        // retry without it is better than failing the review (CORE-40).
+        if (response.status === 400 && request.responseFormat) {
+            const detail = await response.text();
+            if (/response_format|json_schema|structured/i.test(detail)) {
+                const { responseFormat: _dropped, ...withoutSchema } = request;
+                response = await this.post(chatBody(this.model, withoutSchema));
+                if (response.ok) {
+                    return parseChatResponse((await response.json()), "openrouter", this.model);
+                }
+                throw openRouterError(this.model, response.status, await response.text());
+            }
+            throw openRouterError(this.model, response.status, detail);
+        }
         if (!response.ok) {
-            throw new Error(`OpenRouter ${response.status}: ${await response.text()}`);
+            throw openRouterError(this.model, response.status, await response.text());
         }
         return parseChatResponse((await response.json()), "openrouter", this.model);
     }

package/dist/src/ai/pricing.d.ts

@@ -0,0 +1,14 @@
+/** USD per one million tokens. OpenRouter reports USD per single token. */
+export type ModelPrice = {
+    usdPerMillionIn: number;
+    usdPerMillionOut: number;
+};
+export type PriceTable = {
+    /** Model id -> price. A model OpenRouter does not list is simply absent. */
+    prices: Map<string, ModelPrice>;
+    /** Where the table came from, so the estimate can be honest about it. */
+    source: "network" | "cache" | "unavailable";
+};
+/** Fetches or reads the cached OpenRouter price list. Never throws: a failure
+ * becomes `source: "unavailable"` so the caller degrades instead of failing. */
+export declare function loadPrices(): Promise<PriceTable>;

package/dist/src/ai/pricing.js

@@ -0,0 +1,77 @@
+/** OpenRouter model prices for the probe estimate (CORE-24).
+ *
+ * `/api/v1/models` is public: no key needed. The list is large and changes
+ * slowly, so it is cached for 24 hours in cache.db. A network failure is not
+ * fatal — the estimate then reports tokens and time but no dollars, which is
+ * still useful and never invents a price. */
+import { openRouterBase } from "./verify.js";
+import { cacheGet, cacheSet } from "../store/cache_db.js";
+const CACHE_NAMESPACE = "pricing";
+const CACHE_KEY = "openrouter/models";
+const TTL_MS = 24 * 60 * 60 * 1_000;
+function toPrice(row) {
+    const pricing = row
+        ?.pricing;
+    if (!pricing)
+        return undefined;
+    const inUsd = Number(pricing.prompt);
+    const outUsd = Number(pricing.completion);
+    if (!Number.isFinite(inUsd) || !Number.isFinite(outUsd))
+        return undefined;
+    return {
+        usdPerMillionIn: inUsd * 1_000_000,
+        usdPerMillionOut: outUsd * 1_000_000,
+    };
+}
+/** Fetches or reads the cached OpenRouter price list. Never throws: a failure
+ * becomes `source: "unavailable"` so the caller degrades instead of failing. */
+export async function loadPrices() {
+    let cached;
+    try {
+        cached = await cacheGet(CACHE_NAMESPACE, CACHE_KEY);
+    }
+    catch {
+        cached = undefined;
+    }
+    if (cached) {
+        try {
+            const parsed = JSON.parse(cached);
+            const age = Date.now() - new Date(parsed.at).getTime();
+            if (age < TTL_MS) {
+                return { prices: buildMap(parsed.rows), source: "cache" };
+            }
+        }
+        catch {
+            // A corrupt cache entry falls through to the network.
+        }
+    }
+    try {
+        const response = await fetch(`${openRouterBase()}/models`);
+        if (!response.ok)
+            return { prices: new Map(), source: "unavailable" };
+        const body = (await response.json());
+        const rows = Array.isArray(body.data) ? body.data : [];
+        try {
+            await cacheSet(CACHE_NAMESPACE, CACHE_KEY, JSON.stringify({ at: new Date().toISOString(), rows }));
+        }
+        catch {
+            // A cache write failure must not lose the freshly fetched prices.
+        }
+        return { prices: buildMap(rows), source: "network" };
+    }
+    catch {
+        return { prices: new Map(), source: "unavailable" };
+    }
+}
+function buildMap(rows) {
+    const prices = new Map();
+    for (const row of rows) {
+        const id = row?.id;
+        if (typeof id !== "string")
+            continue;
+        const price = toPrice(row);
+        if (price)
+            prices.set(id, price);
+    }
+    return prices;
+}

package/dist/src/ai/provider.js

@@ -59,5 +59,13 @@ export function chatBody(model, request) {
         ...(request.tools?.length
             ? { tools: request.tools, tool_choice: "auto" }
             : {}),
+        // A review asks for structured output (CORE-40). The schema is sent even
+        // when tools are present, because most providers accept the pair; one that
+        // rejects it gets a single retry without the schema (see
+        // `OpenRouterProvider.complete`), and the prompt also asks for a fenced
+        // JSON block, so a plain-text provider still works.
+        ...(request.responseFormat
+            ? { response_format: request.responseFormat }
+            : {}),
     };
 }

package/dist/src/ai/verify.d.ts

@@ -0,0 +1,25 @@
+/** Pre-flight checks for `config set` (CORE-22, F35).
+ *
+ * A wrong API key or an unknown model used to be accepted by `set` and only
+ * surfaced during a review, after the pull request had been fetched and
+ * cloned. These call OpenRouter's own `/key` and `/models` endpoints so the
+ * mistake is caught the moment it is typed. A network failure is not the
+ * user's mistake, so it warns and saves instead of refusing. */
+import { CliError } from "../cli/error.ts";
+/** The chat endpoint the provider uses, with `/chat/completions` removed.
+ * `CM_OPENROUTER_URL` points at a local fake in tests, so the base follows it
+ * and the verification hits the same server the review would. */
+export declare function openRouterBase(): string;
+export type VerifyResult = {
+    status: "ok";
+} | {
+    status: "unreachable";
+    reason: string;
+} | {
+    status: "rejected";
+    error: CliError;
+};
+/** Checks the key against `/key` and, when `model` is given, that `/models`
+ * lists it. The first failure decides: a bad key is reported before a model
+ * question, since the model check would fail on the key too. */
+export declare function verifyOpenRouter(apiKey: string, model?: string): Promise<VerifyResult>;

package/dist/src/ai/verify.js

@@ -0,0 +1,78 @@
+/** Pre-flight checks for `config set` (CORE-22, F35).
+ *
+ * A wrong API key or an unknown model used to be accepted by `set` and only
+ * surfaced during a review, after the pull request had been fetched and
+ * cloned. These call OpenRouter's own `/key` and `/models` endpoints so the
+ * mistake is caught the moment it is typed. A network failure is not the
+ * user's mistake, so it warns and saves instead of refusing. */
+import { CliError, EXIT_USAGE } from "../cli/error.js";
+import { getEnv } from "../util/runtime.js";
+/** The chat endpoint the provider uses, with `/chat/completions` removed.
+ * `CM_OPENROUTER_URL` points at a local fake in tests, so the base follows it
+ * and the verification hits the same server the review would. */
+export function openRouterBase() {
+    const endpoint = getEnv("CM_OPENROUTER_URL") ??
+        "https://openrouter.ai/api/v1/chat/completions";
+    return endpoint.replace(/\/chat\/completions\/?$/, "");
+}
+async function getJson(url, apiKey) {
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+    }
+    catch (error) {
+        const code = error.cause?.code;
+        return { unreachable: code ?? "network error" };
+    }
+    let body = undefined;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    return { status: response.status, body };
+}
+/** Checks the key against `/key` and, when `model` is given, that `/models`
+ * lists it. The first failure decides: a bad key is reported before a model
+ * question, since the model check would fail on the key too. */
+export async function verifyOpenRouter(apiKey, model) {
+    const base = openRouterBase();
+    const key = await getJson(`${base}/key`, apiKey);
+    if ("unreachable" in key)
+        return { status: "unreachable", reason: key.unreachable };
+    if (key.status === 401 || key.status === 403) {
+        return {
+            status: "rejected",
+            error: new CliError("openrouter_unauthorized", "OpenRouter rejected the API key.", "Check the key at https://openrouter.ai/keys and pass it again.", EXIT_USAGE),
+        };
+    }
+    if (key.status >= 400) {
+        return {
+            status: "unreachable",
+            reason: `OpenRouter returned ${key.status}`,
+        };
+    }
+    if (!model)
+        return { status: "ok" };
+    const models = await getJson(`${base}/models`, apiKey);
+    if ("unreachable" in models) {
+        return { status: "unreachable", reason: models.unreachable };
+    }
+    const rows = models.body?.data;
+    if (!Array.isArray(rows)) {
+        return {
+            status: "unreachable",
+            reason: "OpenRouter returned no model list",
+        };
+    }
+    if (!rows.some((row) => row?.id === model)) {
+        return {
+            status: "rejected",
+            error: new CliError("openrouter_unknown_model", `OpenRouter does not know the model ${model}.`, "Pick one at https://openrouter.ai/models and set it with co-maintainer set --high-model=...", EXIT_USAGE),
+        };
+    }
+    return { status: "ok" };
+}

package/dist/src/cli/args.js

@@ -1,9 +1,10 @@
 import { prepareConfig } from "../config.js";
 import { getEnv } from "../util/runtime.js";
 import { askLine } from "./prompt.js";
-function die(message) {
-    throw new Error(message);
-}
+import { die } from "./error.js";
+import { detectRemoteRepo } from "../local/git_ops.js";
+import { reviewBlockingFrom } from "../review/blocking.js";
+import { renderCommandHelp, renderGlobalHelp, unknownCommandMessage, unknownOptionMessage, } from "./commands/registry.js";
 function numberOption(value, name) {
     const number = Number(value);
     if (!Number.isInteger(number) || number < 0) {
@@ -11,7 +12,7 @@ function numberOption(value, name) {
     }
     return number;
 }
-const commands = ["probe", "init", "remake", "review"];
+const commands = ["probe", "init", "sync", "remake", "review"];
 export const defaultLowModel = "openai/gpt-oss-120b";
 const defaultHighModel = "openai/gpt-5.6-luna";
 let cliInteractive = true;
@@ -41,36 +42,27 @@ export async function parseArgs(args) {
         command === "-h" ||
         repo === "--help" ||
         repo === "-h") {
-        console.log("Usage: co-maintainer <probe|init|remake|review> owner/repo [options]");
-        console.log("       co-maintainer review [options]");
-        console.log("       co-maintainer review owner/repo PR_NUMBER [options]");
-        console.log("       co-maintainer set --token=... --ai=... --low-model=... --high-model=... --auth=...");
-        console.log("       co-maintainer serve --port=N");
-        console.log("       co-maintainer -v | --version");
-        console.log("         --webhook-url=https://host/github/webhook [or CM_WEBHOOK_URL]");
-        console.log("         --env=PATH --debug --log-time --gh-concurrent=N --ai-concurrent=N");
-        console.log("Options: --include-codebase --include-pull-requests --include-pull-request-changes");
-        console.log("         --include-commit-history --include-how-repo-works");
-        console.log("         --max-commits=N --max-pr-months=N --max-pull-request-change-lines=N --max-comment=N");
-        console.log("         --only-request-changed-pr");
-        console.log("         --pr-state=open,closed,merged");
-        console.log("         --auth=gh|pat --github-pat=... --ai=none|openrouter|hetzner --token=... --low-model=... --high-model=...");
+        console.log(renderGlobalHelp());
         process.exit(0);
     }
     if (!commands.includes(command)) {
-        die(`Unknown command: ${command}`);
+        die(unknownCommandMessage(command));
     }
     if (rest.includes("--help") || rest.includes("-h")) {
-        console.log(`Usage: co-maintainer ${command} ...`);
-        console.log("Run co-maintainer --help for all options.");
+        console.log(renderCommandHelp(command) ?? renderGlobalHelp());
         process.exit(0);
     }
     if (repo === "--help" || repo === "-h") {
-        console.log(`Usage: co-maintainer ${command} ...`);
-        console.log("Run co-maintainer --help for all options.");
+        console.log(renderCommandHelp(command) ?? renderGlobalHelp());
         process.exit(0);
     }
-    if (!repo || !/^[^/]+\/[^/]+$/.test(repo)) {
+    // `probe` (and only probe, for now) may omit the repo and let the current
+    // directory's git remote name it (CORE-24).
+    let repoName = repo;
+    if ((!repoName || repoName.startsWith("-")) && command === "probe") {
+        repoName = await detectRemoteRepo(process.cwd());
+    }
+    if (!repoName || !/^[^/]+\/[^/]+$/.test(repoName)) {
         die("Repository must look like owner/repo");
     }
     const { config, envPath } = prepareConfig(args);
@@ -78,7 +70,8 @@ export async function parseArgs(args) {
     const configDefault = config.defaults ?? {};
     // Remembered from a prior `init`/`remake` on this exact repo — never a
     // secret, so it can safely fill in everything except the API token.
-    const repoConfig = config.repos?.[repo] ?? {};
+    const repoConfig = config.repos?.[repoName] ?? {};
+    const reviewBlocking = reviewBlockingFrom(env("CO_MAINTAINER_REVIEW_BLOCKING") ?? config.reviewBlocking);
     let prNumber;
     if (command === "review") {
         const rawNumber = rest[0];
@@ -167,10 +160,11 @@ export async function parseArgs(args) {
             arg === "--log-time" ||
             arg === "--review-upstream" ||
             arg === "--disable-codegraph" ||
+            arg === "--run" ||
             arg === "--only-request-changed-pr")
             continue;
         if (arg.startsWith("--") && !known)
-            die(`Unknown option: ${arg}`);
+            die(unknownOptionMessage(arg));
     }
     const explicitAi = rest.some((arg) => arg.startsWith("--ai="));
     const configuredAiRaw = env("CO_MAINTAINER_AI") ?? repoConfig.ai ?? config.ai;
@@ -190,7 +184,7 @@ export async function parseArgs(args) {
         env("GH_TOKEN") ??
         config.githubPat;
     if (auth === "pat" && !githubPat) {
-        die("--auth=pat requires a GitHub token; pass --github-pat=..., set GITHUB_TOKEN/GH_TOKEN, " +
+        die("--auth=pat requires a GitHub token. Pass --github-pat=..., set GITHUB_TOKEN/GH_TOKEN, " +
             "or run: co-maintainer set --github-pat=...");
     }
     let ai = choice("ai", ["none", "openrouter", "hetzner"], configuredAi ?? "none");
@@ -240,12 +234,13 @@ export async function parseArgs(args) {
         die("--token, --low-model, and --high-model are required when AI is enabled");
     }
     return {
-        command: command,
-        repo,
+        command: command === "sync" ? "remake" : command,
+        repo: repoName,
         prNumber,
         debug: rest.includes("--debug"),
         logTime: rest.includes("--log-time"),
         reviewUpstream: rest.includes("--review-upstream"),
+        run: rest.includes("--run"),
         useCodegraph: command === "review" ? !rest.includes("--disable-codegraph") : false,
         envPath,
         improveMatrix: value("improve-matrix") ?? 1,
@@ -274,5 +269,6 @@ export async function parseArgs(args) {
             repoConfig.maxPullRequestChangeLines ??
             configDefault.maxPullRequestChangeLines,
         maxComments: value("max-comment") ?? repoConfig.maxComments,
+        reviewBlocking,
     };
 }

package/dist/src/cli/commands/config.d.ts

@@ -0,0 +1,44 @@
+import type { UserConfig } from "../../config.ts";
+/** Fields whose value must never be printed in full. */
+export declare const SECRET_FIELDS: Set<string>;
+/** `lowModel` -> `low-model`. The inverse of {@link configKey}. */
+export declare function flagName(field: string): string;
+/** `low-model` -> `lowModel`. */
+export declare function configKey(name: string): string;
+/** Masks a secret for display: 12 characters or more keep the last four so a
+ * user can tell two keys apart, anything shorter is fully hidden. `password`
+ * is handled by the caller because it is a hash, not a key. */
+export declare function maskSecret(value: string): string;
+/** Where a value came from, so `config list` can say why a field is what it
+ * is. Env beats the file because env overrides it at run time. */
+export type Source = "env" | "file" | "default";
+/** The env var that supplies each field, mirroring args.ts. Only the fields
+ * that actually read env are listed. */
+export declare const ENV_BY_FIELD: Record<string, string[]>;
+/** Renders one field for people. A secret is masked; the password hash, which
+ * nobody can use, only reports whether it is set. */
+export declare function displayValue(field: string, value: unknown): string;
+/** Values a field falls back to when neither env nor the file sets it, so
+ * `config list` can say a row is the default rather than leaving it out. */
+export declare const DEFAULTS: Record<string, string>;
+type Row = {
+    key: string;
+    field: string;
+    value: string;
+    source: Source;
+};
+/** Every top-level UserConfig key with a value and where it came from. */
+export declare function configRows(config: UserConfig): Row[];
+/** Resolves a user-supplied key name to its field. Accepts kebab-case
+ * (`low-model`), camelCase (`lowModel`), and rejects anything that is not a
+ * `UserConfig` key, so a typo cannot silently read undefined. */
+export declare function resolveField(name: string): string;
+/** The scalar `UserConfig` keys `config` can read and write. `repos` and
+ * `defaults` are nested maps, not settings, so they are not listed.
+ * `satisfies` makes this the type's own vocabulary: a name that is not a
+ * `UserConfig` key is a compile error rather than a silently undefined read. */
+export declare const KNOWN_FIELDS: readonly ["auth", "ai", "lowModel", "highModel", "token", "githubPat", "githubAppId", "githubAppPrivateKey", "githubAppPrivateKeyPath", "githubWebhookSecret", "webhookUrl", "githubOAuthClientId", "githubOAuthClientSecret", "githubOAuthAllowedUser", "passwordAuthDisabled", "githubAuthEnabled", "dashboardPasswordHash", "maxConcurrentJobs", "reviewBlocking", "remoteHost", "remoteToken", "remoteNoticeShownFor", "remoteSyncTimeoutSeconds", "maxConcurrentRemoteReviewsPerToken", "remoteToolOutputMaxChars"];
+/** `co-maintainer config <sub> ...`. `set` is handled by runSet, which this
+ * command delegates to so there is one implementation of the write rules. */
+export declare function runConfig(args: string[]): Promise<void>;
+export {};