co-maintainer 0.4.0-beta.1

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

@@ -0,0 +1,7 @@
+/** `co-maintainer set --token=... --ai=... --low-model=... --high-model=...
+ * --auth=... --github-app-id=... --github-app-private-key=... (or
+ * --github-app-private-key-file=path) --github-webhook-secret=...` —
+ * persists global defaults, including secrets, to config.json so every
+ * other command can skip both the flag and the interactive prompt. See
+ * docs/md/configuration.md for the tradeoff. */
+export declare function runSet(args: string[]): Promise<void>;

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

@@ -0,0 +1,171 @@
+import { writeUserConfig } from "../../config.js";
+import { readTextFile } from "../../util/runtime.js";
+function die(message) {
+    throw new Error(message);
+}
+function text(args, name) {
+    return args
+        .find((arg) => arg.startsWith(`--${name}=`))
+        ?.slice(name.length + 3);
+}
+const secretFields = new Set([
+    "token",
+    "githubPat",
+    "githubAppPrivateKey",
+    "githubWebhookSecret",
+    "githubOAuthClientSecret",
+    "remoteToken",
+]);
+/** `co-maintainer set --token=... --ai=... --low-model=... --high-model=...
+ * --auth=... --github-app-id=... --github-app-private-key=... (or
+ * --github-app-private-key-file=path) --github-webhook-secret=...` —
+ * persists global defaults, including secrets, to config.json so every
+ * other command can skip both the flag and the interactive prompt. See
+ * docs/md/configuration.md for the tradeoff. */
+export async function runSet(args) {
+    if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+        console.log("Usage: co-maintainer set --token=... --ai=none|openrouter|hetzner --low-model=... --high-model=... --auth=gh|pat --github-pat=...");
+        console.log("                        --github-app-id=... --github-app-private-key=... | --github-app-private-key-file=path");
+        console.log("                        --github-webhook-secret=...");
+        console.log("                        --github-oauth-client-id=... --github-oauth-client-secret=... --github-oauth-allowed-user=...");
+        console.log("                        --disable-auth=password --enable-auth=github");
+        console.log("Writes to the user config file; unset an entry with --unset=name (e.g. --unset=token).");
+        return;
+    }
+    const known = [
+        "token",
+        "ai",
+        "low-model",
+        "high-model",
+        "auth",
+        "github-pat",
+        "github-app-id",
+        "github-app-private-key",
+        "github-app-private-key-file",
+        "github-webhook-secret",
+        "github-oauth-client-id",
+        "github-oauth-client-secret",
+        "github-oauth-allowed-user",
+        "disable-auth",
+        "enable-auth",
+        "remote-host",
+        "remote-token",
+        "unset",
+    ];
+    for (const arg of args) {
+        if (!arg.startsWith("--") ||
+            !known.some((name) => arg.startsWith(`--${name}=`))) {
+            die(`Unknown option: ${arg}`);
+        }
+    }
+    const ai = text(args, "ai");
+    if (ai && !["none", "openrouter", "hetzner"].includes(ai)) {
+        die("--ai must be one of: none, openrouter, hetzner");
+    }
+    const auth = text(args, "auth");
+    if (auth && !["gh", "pat"].includes(auth)) {
+        die("--auth must be one of: gh, pat");
+    }
+    if (text(args, "github-app-private-key") &&
+        text(args, "github-app-private-key-file")) {
+        die("Pass only one of --github-app-private-key or --github-app-private-key-file");
+    }
+    const fieldByFlag = {
+        token: "token",
+        ai: "ai",
+        "low-model": "lowModel",
+        "high-model": "highModel",
+        auth: "auth",
+        "github-pat": "githubPat",
+        "github-app-id": "githubAppId",
+        "github-app-private-key": "githubAppPrivateKey",
+        "github-webhook-secret": "githubWebhookSecret",
+        "github-oauth-client-id": "githubOAuthClientId",
+        "github-oauth-client-secret": "githubOAuthClientSecret",
+        "github-oauth-allowed-user": "githubOAuthAllowedUser",
+        "disable-auth": "passwordAuthDisabled",
+        "enable-auth": "githubAuthEnabled",
+        "remote-host": "remoteHost",
+        "remote-token": "remoteToken",
+    };
+    const unset = new Set(args
+        .filter((arg) => arg.startsWith("--unset="))
+        .map((arg) => arg.slice("--unset=".length)));
+    const patch = {};
+    for (const [flag, field] of Object.entries(fieldByFlag)) {
+        if (unset.has(field) || unset.has(flag))
+            patch[field] = undefined;
+    }
+    if (ai)
+        patch.ai = ai;
+    if (auth)
+        patch.auth = auth;
+    const lowModel = text(args, "low-model");
+    if (lowModel)
+        patch.lowModel = lowModel;
+    const highModel = text(args, "high-model");
+    if (highModel)
+        patch.highModel = highModel;
+    const token = text(args, "token");
+    if (token)
+        patch.token = token;
+    const githubPat = text(args, "github-pat");
+    if (githubPat)
+        patch.githubPat = githubPat;
+    const githubAppId = text(args, "github-app-id");
+    if (githubAppId)
+        patch.githubAppId = githubAppId;
+    const githubWebhookSecret = text(args, "github-webhook-secret");
+    if (githubWebhookSecret)
+        patch.githubWebhookSecret = githubWebhookSecret;
+    const githubAppPrivateKey = text(args, "github-app-private-key");
+    if (githubAppPrivateKey)
+        patch.githubAppPrivateKey = githubAppPrivateKey;
+    const privateKeyFile = text(args, "github-app-private-key-file");
+    if (privateKeyFile) {
+        try {
+            patch.githubAppPrivateKey = await readTextFile(privateKeyFile);
+        }
+        catch (error) {
+            die(`Could not read ${privateKeyFile}: ${String(error)}`);
+        }
+    }
+    const oauthClientId = text(args, "github-oauth-client-id");
+    if (oauthClientId)
+        patch.githubOAuthClientId = oauthClientId;
+    const oauthClientSecret = text(args, "github-oauth-client-secret");
+    if (oauthClientSecret)
+        patch.githubOAuthClientSecret = oauthClientSecret;
+    const oauthAllowedUser = text(args, "github-oauth-allowed-user");
+    if (oauthAllowedUser)
+        patch.githubOAuthAllowedUser = oauthAllowedUser;
+    const disableAuth = text(args, "disable-auth");
+    if (disableAuth) {
+        if (disableAuth !== "password")
+            die("--disable-auth only supports: password");
+        patch.passwordAuthDisabled = true;
+    }
+    const enableAuth = text(args, "enable-auth");
+    if (enableAuth) {
+        if (enableAuth !== "github")
+            die("--enable-auth only supports: github");
+        patch.githubAuthEnabled = true;
+    }
+    const remoteHost = text(args, "remote-host");
+    if (remoteHost)
+        patch.remoteHost = remoteHost;
+    const remoteToken = text(args, "remote-token");
+    if (remoteToken)
+        patch.remoteToken = remoteToken;
+    if (Object.keys(patch).length === 0) {
+        die("Nothing to set; pass --token=, --ai=, --low-model=, --high-model=, --auth=, --github-pat=, " +
+            "--github-app-id=, --github-app-private-key(-file)=, --github-webhook-secret=, " +
+            "--github-oauth-client-id=, --github-oauth-client-secret=, --github-oauth-allowed-user=, " +
+            "--disable-auth=password, --enable-auth=github, or --unset=name");
+    }
+    await writeUserConfig(patch);
+    const summary = Object.entries(patch).map(([key, value]) => value === undefined
+        ? `${key} (unset)`
+        : `${key}=${secretFields.has(key) ? "•".repeat(8) : value}`);
+    console.log(`[set] updated: ${summary.join(", ")}`);
+}

package/dist/src/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function run(args: string[]): Promise<void>;

package/dist/src/cli/main.js

@@ -0,0 +1,27 @@
+/** CLI dispatch only. Each branch parses nothing itself beyond `args[0]` and
+ * calls straight into a command or a service — see PLAN.md Section 3. */
+import { parseArgs } from "./args.js";
+import { runServe } from "./commands/serve.js";
+import { runSet } from "./commands/set.js";
+import { runProbe } from "./commands/probe.js";
+import { runReviewFromCli } from "./commands/review.js";
+import { runInitOrRemake } from "../services/setup.js";
+export async function run(args) {
+    if (args[0] === "set") {
+        await runSet(args.slice(1));
+        return;
+    }
+    if (args[0] === "serve") {
+        await runServe(args.slice(1));
+        return;
+    }
+    if (args[0] === "review") {
+        await runReviewFromCli(args.slice(1));
+        return;
+    }
+    const options = await parseArgs(args);
+    if (options.command === "probe")
+        await runProbe(options);
+    else
+        await runInitOrRemake(options);
+}

package/dist/src/cli/prompt.d.ts

@@ -0,0 +1,4 @@
+/** Free-text question; empty input yields the fallback (or ""). */
+export declare function askLine(label: string, fallback?: string): Promise<string>;
+/** Yes/no question; anything but `y`/`yes` is a no. */
+export declare function askConfirm(question: string): Promise<boolean>;

package/dist/src/cli/prompt.js

@@ -0,0 +1,26 @@
+/** Interactive prompts over `node:readline/promises`.
+ *
+ * Every prompt opens and closes its own interface: co-maintainer rarely asks
+ * more than a couple of questions, and an interface left open keeps stdin
+ * referenced, which would hang a non-interactive pipeline. */
+import { createInterface } from "node:readline/promises";
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Free-text question; empty input yields the fallback (or ""). */
+export async function askLine(label, fallback) {
+    const suffix = fallback ? ` [${fallback}]` : "";
+    const answer = await ask(`${label}${suffix}:`);
+    return answer || fallback || "";
+}
+/** Yes/no question; anything but `y`/`yes` is a no. */
+export async function askConfirm(question) {
+    const answer = (await ask(`${question} [y/N]`)).toLowerCase();
+    return answer === "y" || answer === "yes";
+}

package/dist/src/cli/review_args.d.ts

@@ -0,0 +1,28 @@
+import type { Options } from "../types.ts";
+export type ReviewMode = "local" | "remote" | "pr";
+type ReviewFlags = {
+    json: boolean;
+    remote: boolean;
+    disableCodegraph: boolean;
+    allowToolInstall: boolean;
+    fresh: boolean;
+    toBranch?: string;
+    branch?: string;
+    repoOverride?: string;
+    remakeBeforeReview: boolean;
+};
+export type ReviewCliArgs = ({
+    mode: "pr";
+    options: Options;
+} & ReviewFlags) | ({
+    mode: "local";
+    rawArgs: string[];
+} & ReviewFlags) | ({
+    mode: "remote";
+    rawArgs: string[];
+} & ReviewFlags);
+/** Strip local-only flags before `parseArgs` for PR-style options. */
+export declare function filterReviewConfigArgs(raw: string[]): string[];
+/** Parses `co-maintainer review` after the `review` token (plan §8.1). */
+export declare function parseReviewArgs(args: string[]): Promise<ReviewCliArgs>;
+export {};

package/dist/src/cli/review_args.js

@@ -0,0 +1,84 @@
+import { parseArgs } from "./args.js";
+function die(message) {
+    throw new Error(message);
+}
+function reviewFlags(rest) {
+    const text = (name) => rest.find((item) => item.startsWith(`--${name}=`))?.slice(name.length + 3);
+    for (const arg of rest) {
+        if (arg === "--codegraph") {
+            die("Unknown option: --codegraph");
+        }
+        if (arg === "--remote" &&
+            rest.some((r) => r === "--remake-before-review")) {
+            die("--remake-before-review cannot be used with --remote");
+        }
+    }
+    return {
+        json: rest.includes("--json"),
+        remote: rest.includes("--remote"),
+        disableCodegraph: rest.includes("--disable-codegraph"),
+        allowToolInstall: rest.includes("--allow-tool-install"),
+        fresh: rest.includes("--fresh"),
+        toBranch: text("to-branch"),
+        branch: text("branch"),
+        repoOverride: text("repo"),
+        remakeBeforeReview: rest.includes("--remake-before-review"),
+    };
+}
+const LOCAL_ONLY_FLAGS = new Set([
+    "--json",
+    "--remote",
+    "--disable-codegraph",
+    "--allow-tool-install",
+    "--fresh",
+    "--remake-before-review",
+]);
+/** Strip local-only flags before `parseArgs` for PR-style options. */
+export function filterReviewConfigArgs(raw) {
+    return raw.filter((arg) => {
+        if (LOCAL_ONLY_FLAGS.has(arg))
+            return false;
+        if (arg.startsWith("--to-branch=") ||
+            arg.startsWith("--branch=") ||
+            arg.startsWith("--repo=")) {
+            return false;
+        }
+        return true;
+    });
+}
+/** Parses `co-maintainer review` after the `review` token (plan §8.1). */
+export async function parseReviewArgs(args) {
+    const positional = args.filter((a) => !a.startsWith("--"));
+    const flags = reviewFlags(args);
+    const isPr = positional.length >= 2 &&
+        /^[^/]+\/[^/]+$/.test(positional[0]) &&
+        /^\d+$/.test(positional[1]);
+    if (isPr) {
+        const options = await parseArgs([
+            "review",
+            positional[0],
+            positional[1],
+            ...filterReviewConfigArgs(args),
+        ]);
+        if (flags.remote)
+            die("--remote is only for local review without a PR number");
+        if (flags.remakeBeforeReview) {
+            die("--remake-before-review is not supported for PR review");
+        }
+        return {
+            mode: "pr",
+            options: {
+                ...options,
+                useCodegraph: flags.disableCodegraph ? false : true,
+            },
+            ...flags,
+        };
+    }
+    if (positional.length === 0) {
+        if (flags.remote)
+            return { mode: "remote", rawArgs: args, ...flags };
+        return { mode: "local", rawArgs: args, ...flags };
+    }
+    die("Usage: co-maintainer review [options]\n" +
+        "       co-maintainer review owner/repo PR_NUMBER [options]");
+}

package/dist/src/cli/review_output.d.ts

@@ -0,0 +1,2 @@
+export declare function reviewExitCode(markdown: string): number;
+export declare function printLocalReview(header: string, markdown: string): void;

package/dist/src/cli/review_output.js

@@ -0,0 +1,10 @@
+import { parseFindings } from "../pr/findings.js";
+import { humanCopy } from "../services/review.js";
+export function reviewExitCode(markdown) {
+    const findings = parseFindings(markdown);
+    const blocking = findings.some((f) => f.blocking === true || /\[P0\b/i.test(f.heading));
+    return blocking ? 1 : 0;
+}
+export function printLocalReview(header, markdown) {
+    console.log(`\n${header}\n\n${humanCopy(markdown)}\n`);
+}

package/dist/src/cli/review_result.d.ts

@@ -0,0 +1,81 @@
+import { type ParsedFinding } from "../pr/findings.ts";
+import { type ResolvedFinding } from "../review/carry_over.ts";
+import type { Revision } from "../review/revision.ts";
+export type ReviewWarning = {
+    code: string;
+    message: string;
+};
+export type JsonReviewFinding = {
+    id: string;
+    state: "new" | "open" | "closed";
+    closeReason: "fixed" | "file_reverted" | null;
+    severity: string;
+    blocking: boolean;
+    path: string | null;
+    lineFrom: number | null;
+    lineTo: number | null;
+    title: string;
+    body: string;
+    suggestion: {
+        lineFrom: number;
+        lineTo: number;
+        text: string;
+    } | null;
+};
+export declare function isBlockingFinding(title: string, severity: string): boolean;
+export declare function resolvedFromFirstReview(parsed: ParsedFinding[], filesByPath: Map<string, {
+    patch: string;
+}>): ResolvedFinding[];
+export declare function sortResolvedFindings(findings: ResolvedFinding[]): ResolvedFinding[];
+export declare function toJsonFinding(row: ResolvedFinding): JsonReviewFinding;
+export declare function revisionStats(revision: Revision): {
+    files: number;
+    additions: number;
+    deletions: number;
+    truncated: boolean;
+};
+export declare function summaryCounts(findings: ResolvedFinding[]): {
+    new: number;
+    open: number;
+    closed: number;
+    blocking: number;
+};
+export declare function reviewExitCodeFromResolved(findings: ResolvedFinding[]): number;
+/** Plan §9.1 human-readable local review output. */
+export declare function formatHumanLocalReview(header: string, revision: Revision, guideBuiltAt: string | null, codegraphState: "used" | "disabled" | "unavailable", findings: ResolvedFinding[], warnings: ReviewWarning[]): string;
+/** Human-readable findings block for remote sync JSON (same shape as `toJsonFinding`). */
+export declare function formatHumanJsonFindings(findings: JsonReviewFinding[]): string;
+export declare function reviewExitCodeFromJsonFindings(findings: JsonReviewFinding[]): number;
+export type LocalReviewJsonInput = {
+    repo: string;
+    branch: string;
+    baseLabel: string;
+    revision: Revision;
+    guideBuiltAt: string | null;
+    codegraphState: "used" | "disabled" | "unavailable";
+    codegraphReason: string | null;
+    findings: ResolvedFinding[];
+    warnings: ReviewWarning[];
+    usage: {
+        tokensIn: number;
+        tokensOut: number;
+        costUsd: number | null;
+    };
+    durationMs: number;
+};
+export type PrReviewJsonInput = {
+    repo: string;
+    prNumber: number;
+    markdown: string;
+    guideBuiltAt: string | null;
+    codegraphState: "used" | "disabled" | "unavailable";
+    codegraphReason: string | null;
+    usage: {
+        tokensIn: number;
+        tokensOut: number;
+        costUsd: number | null;
+    };
+    durationMs: number;
+};
+export declare function buildPrReviewJson(input: PrReviewJsonInput): string;
+export declare function buildLocalReviewJson(input: LocalReviewJsonInput): string;