co-maintainer 0.4.0-beta.1

package/dist/src/cli/args.js

@@ -0,0 +1,252 @@
+import { prepareConfig } from "../config.js";
+import { getEnv } from "../util/runtime.js";
+import { askLine } from "./prompt.js";
+function die(message) {
+    throw new Error(message);
+}
+function numberOption(value, name) {
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < 0) {
+        die(`${name} must be a non-negative integer`);
+    }
+    return number;
+}
+const commands = ["probe", "init", "remake", "review"];
+export const defaultLowModel = "openai/gpt-oss-120b";
+const defaultHighModel = "openai/gpt-5.6-luna";
+let cliInteractive = true;
+/** Plan §8.7 — `--json` must not prompt. */
+export function setCliInteractive(value) {
+    cliInteractive = value;
+}
+async function ask(label, fallback, required = false) {
+    if (!cliInteractive) {
+        if (fallback !== undefined && fallback !== "")
+            return fallback;
+        die(`Missing ${label}; pass it as a CLI option when running without an interactive terminal`);
+    }
+    if (process.stdin.isTTY !== true) {
+        die(`Missing ${label}; pass it as a CLI option when running without an interactive terminal`);
+    }
+    const value = await askLine(label, fallback);
+    if (required && !value)
+        die(`${label} is required`);
+    return value;
+}
+export async function parseArgs(args) {
+    const [command, repo, ...rest] = args;
+    if (!command ||
+        command === "help" ||
+        command === "--help" ||
+        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("         --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("         --auth=gh|pat --github-pat=... --ai=none|openrouter|hetzner --token=... --low-model=... --high-model=...");
+        process.exit(0);
+    }
+    if (!commands.includes(command)) {
+        die(`Unknown command: ${command}`);
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        console.log(`Usage: co-maintainer ${command} ...`);
+        console.log("Run co-maintainer --help for all options.");
+        process.exit(0);
+    }
+    if (repo === "--help" || repo === "-h") {
+        console.log(`Usage: co-maintainer ${command} ...`);
+        console.log("Run co-maintainer --help for all options.");
+        process.exit(0);
+    }
+    if (!repo || !/^[^/]+\/[^/]+$/.test(repo)) {
+        die("Repository must look like owner/repo");
+    }
+    const { config, envPath } = prepareConfig(args);
+    const env = (name) => getEnv(name);
+    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] ?? {};
+    let prNumber;
+    if (command === "review") {
+        const rawNumber = rest[0];
+        if (rawNumber && /^\d+$/.test(rawNumber)) {
+            rest.shift();
+            prNumber = Number(rawNumber);
+        }
+    }
+    const includeNames = [
+        "include-codebase",
+        "include-pull-requests",
+        "include-pull-request-changes",
+        "include-commit-history",
+        "include-how-repo-works",
+    ];
+    const explicitlyIncluded = rest.some((arg) => includeNames.some((name) => arg === `--${name}`));
+    const includeKeys = {
+        "include-codebase": "includeCodebase",
+        "include-pull-requests": "includePullRequests",
+        "include-pull-request-changes": "includePullRequestChanges",
+        "include-commit-history": "includeCommitHistory",
+        "include-how-repo-works": "includeHowRepoWorks",
+    };
+    const enabled = (name) => explicitlyIncluded
+        ? rest.includes(`--${name}`)
+        : (repoConfig[includeKeys[name]] ?? true);
+    const value = (name) => {
+        const arg = rest.find((item) => item.startsWith(`--${name}=`));
+        return arg
+            ? numberOption(arg.slice(name.length + 3), `--${name}`)
+            : undefined;
+    };
+    const text = (name) => rest.find((item) => item.startsWith(`--${name}=`))?.slice(name.length + 3);
+    const choice = (name, allowed, fallback) => {
+        const prefix = `--${name}=`;
+        const raw = rest
+            .find((arg) => arg.startsWith(prefix))
+            ?.slice(prefix.length);
+        if (!raw)
+            return fallback;
+        if (!allowed.includes(raw)) {
+            die(`${name} must be one of: ${allowed.join(", ")}`);
+        }
+        return raw;
+    };
+    for (const arg of rest) {
+        const known = includeNames.some((name) => arg === `--${name}`) ||
+            [
+                "max-commits",
+                "max-pr-months",
+                "max-pull-request-change-lines",
+                "max-comment",
+                "improve-matrix",
+                "env",
+                "gh-concurrent",
+                "ai-concurrent",
+                "auth",
+                "ai",
+                "token",
+                "github-pat",
+                "low-model",
+                "high-model",
+            ].some((name) => arg.startsWith(`--${name}=`));
+        if (arg === "--codegraph")
+            die("Unknown option: --codegraph");
+        if (arg === "--debug" ||
+            arg === "--log-time" ||
+            arg === "--review-upstream" ||
+            arg === "--disable-codegraph")
+            continue;
+        if (arg.startsWith("--") && !known)
+            die(`Unknown option: ${arg}`);
+    }
+    const explicitAi = rest.some((arg) => arg.startsWith("--ai="));
+    const configuredAiRaw = env("CO_MAINTAINER_AI") ?? repoConfig.ai ?? config.ai;
+    if (configuredAiRaw &&
+        !["none", "openrouter", "hetzner"].includes(configuredAiRaw)) {
+        die("CO_MAINTAINER_AI/config.ai must be none, openrouter, or hetzner");
+    }
+    const configuredAi = configuredAiRaw;
+    const configuredAuthRaw = env("CO_MAINTAINER_AUTH") ?? repoConfig.auth ?? config.auth;
+    if (configuredAuthRaw && !["gh", "pat"].includes(configuredAuthRaw)) {
+        die("CO_MAINTAINER_AUTH/config.auth must be gh or pat");
+    }
+    const configuredAuth = configuredAuthRaw;
+    const auth = choice("auth", ["gh", "pat"], configuredAuth ?? "gh");
+    const githubPat = text("github-pat") ??
+        env("GITHUB_TOKEN") ??
+        env("GH_TOKEN") ??
+        config.githubPat;
+    if (auth === "pat" && !githubPat) {
+        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");
+    if (command === "review") {
+        if (explicitAi &&
+            choice("ai", ["none", "openrouter", "hetzner"], "none") !== "openrouter") {
+            die("review supports OpenRouter only");
+        }
+        ai = "openrouter";
+    }
+    else if (!explicitAi && !configuredAi && command !== "probe") {
+        const selected = await ask("AI provider (openrouter|hetzner)", "openrouter");
+        if (!["openrouter", "hetzner"].includes(selected)) {
+            die("AI provider must be openrouter or hetzner");
+        }
+        ai = selected;
+    }
+    let aiToken = text("token") ??
+        env("CO_MAINTAINER_TOKEN") ??
+        (ai === "openrouter" ? env("OPENROUTER_API_KEY") : undefined) ??
+        (ai === "hetzner" ? env("HETZNER_API_KEY") : undefined) ??
+        config.token;
+    let lowModel = text("low-model") ??
+        env("OPENROUTER_LOW_MODEL") ??
+        env("HETZNER_LOW_MODEL") ??
+        env("LOW_MODEL") ??
+        repoConfig.lowModel ??
+        config.lowModel;
+    let highModel = text("high-model") ??
+        env("OPENROUTER_HIGH_MODEL") ??
+        env("HETZNER_HIGH_MODEL") ??
+        env("HIGH_MODEL") ??
+        repoConfig.highModel ??
+        config.highModel;
+    if (command === "review") {
+        aiToken ??= await ask("openrouter API key", undefined, true);
+        highModel ??= await ask("high model", defaultHighModel, true);
+    }
+    else if (ai !== "none" && command !== "probe") {
+        aiToken ??= await ask(`${ai} API key`, undefined, true);
+        lowModel ??= await ask("low model", defaultLowModel, true);
+        highModel ??= await ask("high model", defaultHighModel, true);
+    }
+    if (command !== "review" &&
+        ai !== "none" &&
+        (!lowModel || !highModel || !aiToken)) {
+        die("--token, --low-model, and --high-model are required when AI is enabled");
+    }
+    return {
+        command: command,
+        repo,
+        prNumber,
+        debug: rest.includes("--debug"),
+        logTime: rest.includes("--log-time"),
+        reviewUpstream: rest.includes("--review-upstream"),
+        useCodegraph: command === "review" ? !rest.includes("--disable-codegraph") : false,
+        envPath,
+        improveMatrix: value("improve-matrix") ?? 1,
+        ghConcurrent: Math.max(1, value("gh-concurrent") ?? 1),
+        aiConcurrent: Math.max(1, value("ai-concurrent") ?? 3),
+        auth,
+        githubPat,
+        ai,
+        aiToken,
+        lowModel,
+        highModel,
+        synthesisVersion: 16,
+        includeCodebase: enabled("include-codebase"),
+        includePullRequests: enabled("include-pull-requests"),
+        includePullRequestChanges: enabled("include-pull-request-changes"),
+        includeCommitHistory: enabled("include-commit-history"),
+        includeHowRepoWorks: enabled("include-how-repo-works"),
+        maxCommits: value("max-commits") ?? repoConfig.maxCommits ?? configDefault.maxCommits,
+        maxPrMonths: value("max-pr-months") ??
+            repoConfig.maxPrMonths ??
+            configDefault.maxPrMonths,
+        maxPullRequestChangeLines: value("max-pull-request-change-lines") ??
+            repoConfig.maxPullRequestChangeLines ??
+            configDefault.maxPullRequestChangeLines,
+        maxComments: value("max-comment") ?? repoConfig.maxComments,
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { Options } from "../../types.ts";
+export declare function runProbe(options: Options): Promise<void>;

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

@@ -0,0 +1,122 @@
+import { clientFor } from "../../services/setup.js";
+import { analyzeProbe } from "../../knowledge/probe.js";
+import { cacheSet } from "../../store/cache_db.js";
+import { log, startHeartbeat, timed } from "../../util/log.js";
+export async function runProbe(options) {
+    const operationStarted = performance.now();
+    const stopHeartbeat = startHeartbeat("probing repository");
+    const client = clientFor(options);
+    log("probe", `reading ${options.repo} via ${options.auth}`);
+    const meta = await timed("probe repository metadata", options.logTime, () => client.request(`repos/${options.repo}`));
+    let latestReleaseAt = "";
+    log("probe", "reading release metadata");
+    try {
+        const releases = await timed("probe release metadata", options.logTime, () => client.pages(`repos/${options.repo}/releases?per_page=1`, 1));
+        latestReleaseAt = String(releases[0]?.published_at ?? releases[0]?.created_at ?? "");
+    }
+    catch {
+        // Release metadata is an optional probe signal.
+    }
+    log("probe", "reading pull request list");
+    const pulls = await timed("probe pull request listing", options.logTime, () => client.pages(`repos/${options.repo}/pulls?state=all&sort=updated&direction=desc`, undefined, (page, fetched) => log("probe", `pull request listing · page ${page} · fetched ${fetched} · total unknown`)));
+    const yearBuckets = new Map();
+    for (const pull of pulls) {
+        const year = new Date(String(pull.updated_at)).getFullYear();
+        yearBuckets.set(year, [...(yearBuckets.get(year) ?? []), pull]);
+    }
+    const sampleTargets = new Map();
+    for (const pull of pulls.slice(0, 30)) {
+        sampleTargets.set(Number(pull.number), pull);
+    }
+    for (const yearPulls of yearBuckets.values()) {
+        for (const pull of yearPulls.slice(0, 3)) {
+            sampleTargets.set(Number(pull.number), pull);
+        }
+    }
+    const samplePulls = [...sampleTargets.values()];
+    const detailSamples = [];
+    log("probe", `sampling ${samplePulls.length} pull request details · concurrency=${options.ghConcurrent}`);
+    await timed("probe PR detail sampling", options.logTime, async () => {
+        const details = new Array(samplePulls.length);
+        let cursor = 0;
+        let completed = 0;
+        const worker = async () => {
+            while (cursor < samplePulls.length) {
+                const index = cursor++;
+                const pull = samplePulls[index];
+                try {
+                    details[index] = await client.request(`repos/${options.repo}/pulls/${Number(pull.number)}`);
+                }
+                catch {
+                    // A missing detail should not invalidate the rest of the probe.
+                }
+                finally {
+                    completed++;
+                    log("probe", `PR detail sampling · ${completed}/${samplePulls.length} · ${Math.round((completed / samplePulls.length) * 100)}%`);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(options.ghConcurrent, samplePulls.length) }, worker));
+        detailSamples.push(...details.filter((detail) => !!detail));
+    });
+    const branch = String(meta.default_branch ?? "main");
+    log("probe", `sampled ${detailSamples.length} PR details; reading ${branch} commit history`);
+    const commits = await timed("probe commit history", options.logTime, () => client.pages(`repos/${options.repo}/commits?sha=${encodeURIComponent(branch)}`, undefined, (page, fetched) => log("probe", `commit history · page ${page} · fetched ${fetched} · total unknown`)));
+    const analysis = await timed("probe analysis", options.logTime, async () => analyzeProbe({ ...meta, latest_release_at: latestReleaseAt }, pulls, detailSamples, commits));
+    const recommendation = ["--include-codebase"];
+    if (analysis.includePullRequests) {
+        recommendation.push("--include-pull-requests");
+    }
+    if (analysis.includePullRequestChanges) {
+        recommendation.push("--include-pull-request-changes");
+    }
+    if (analysis.includeCommitHistory) {
+        recommendation.push("--include-commit-history");
+    }
+    if (pulls.length || Boolean(meta.has_issues)) {
+        recommendation.push("--include-how-repo-works");
+    }
+    if (analysis.maxPullRequestChangeLines) {
+        recommendation.push(`--max-pull-request-change-lines=${analysis.maxPullRequestChangeLines}`);
+    }
+    if (analysis.maxPrMonths) {
+        recommendation.push(`--max-pr-months=${analysis.maxPrMonths}`);
+    }
+    if (analysis.maxCommits) {
+        recommendation.push(`--max-commits=${analysis.maxCommits}`);
+    }
+    const command = [
+        "co-maintainer",
+        "init",
+        options.repo,
+        ...recommendation,
+    ].join(" ");
+    const report = {
+        repo: options.repo,
+        ...analysis.report,
+        recommendations: {
+            includePullRequests: analysis.includePullRequests,
+            includePullRequestChanges: analysis.includePullRequestChanges,
+            includeCommitHistory: analysis.includeCommitHistory,
+            maxPrMonths: analysis.maxPrMonths ?? "all",
+            maxCommits: analysis.maxCommits ?? "all",
+            maxPullRequestChangeLines: analysis.maxPullRequestChangeLines ?? "all",
+        },
+        reasons: analysis.reasons,
+        recommendedCommand: command,
+        createdAt: new Date().toISOString(),
+    };
+    await timed("probe report write", options.logTime, () => cacheSet("probe", options.repo, JSON.stringify(report)));
+    console.log(`\nrecommended\n  ${command}`);
+    console.log("\nresearch");
+    console.log(`  PRs: ${analysis.report.pullRequests} · sampled: ${analysis.report.sampledPullRequests}`);
+    console.log(`  commits: ${analysis.report.commits} · useful: ${analysis.report.usefulCommits}`);
+    console.log(`  windows: PR months=${analysis.maxPrMonths ?? "all"} · commits=${analysis.maxCommits ?? "all"} · diff lines=${analysis.maxPullRequestChangeLines ?? "all"}`);
+    for (const reason of analysis.reasons)
+        console.log(`  - ${reason}`);
+    console.log("  This is a recommendation only; probe does not create or modify a skill.");
+    if (options.logTime) {
+        console.log(`  total time: ${((performance.now() - operationStarted) / 1000).toFixed(2)}s`);
+    }
+    stopHeartbeat();
+}

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

@@ -0,0 +1,3 @@
+import type { Options } from "../../types.ts";
+export declare function runReviewFromCli(args: string[]): Promise<void>;
+export declare function runReview(options: Options): Promise<void>;

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

@@ -0,0 +1,84 @@
+import { parseReviewArgs } from "../review_args.js";
+import { setCliInteractive } from "../args.js";
+import { emptyAiMetrics, recordAiCost } from "../../services/setup.js";
+import { reviewPullRequest } from "../../pr/reviewer.js";
+import { GhClient } from "../../github/gh.js";
+import { log, startHeartbeat, timed, withCliLogsToStderr, } from "../../util/log.js";
+import { runLocalReview } from "../../local/review_local.js";
+import { runRemoteReview } from "../../remote/client.js";
+import { printLocalReview, reviewExitCode } from "../review_output.js";
+import { buildPrReviewJson, resolvedFromFirstReview, reviewExitCodeFromResolved, } from "../review_result.js";
+import { parseFindings } from "../../pr/findings.js";
+export async function runReviewFromCli(args) {
+    const parsed = await parseReviewArgs(args);
+    if (parsed.mode === "local") {
+        await runLocalReview(parsed);
+        return;
+    }
+    if (parsed.mode === "remote") {
+        await runRemoteReview(parsed);
+        return;
+    }
+    await runReviewPr(parsed.options, parsed);
+}
+export async function runReview(options) {
+    await runReviewPr(options, {
+        json: false,
+        disableCodegraph: false,
+        allowToolInstall: false,
+        remakeBeforeReview: false,
+    });
+}
+async function runReviewPr(options, cli) {
+    setCliInteractive(!cli.json);
+    await withCliLogsToStderr(async () => {
+        const operationStarted = performance.now();
+        const aiMetrics = emptyAiMetrics();
+        const stopHeartbeat = startHeartbeat("reviewing pull request");
+        if (options.auth !== "gh") {
+            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) => {
+            aiMetrics.calls++;
+            aiMetrics.tokensIn += response.tokensIn;
+            aiMetrics.tokensOut += response.tokensOut;
+            if (response.cost === undefined)
+                aiMetrics.costKnown = false;
+            else
+                aiMetrics.cost += response.cost;
+            await recordAiCost(options.repo, "review_pull_request", response);
+        }));
+        const durationMs = Math.round(performance.now() - operationStarted);
+        const usage = {
+            tokensIn: aiMetrics.tokensIn,
+            tokensOut: aiMetrics.tokensOut,
+            costUsd: aiMetrics.costKnown ? aiMetrics.cost : null,
+        };
+        const codegraphState = options.useCodegraph ? "used" : "disabled";
+        const findings = resolvedFromFirstReview(parseFindings(result.text), new Map());
+        if (cli.json) {
+            console.log(buildPrReviewJson({
+                repo: options.repo,
+                prNumber: options.prNumber,
+                markdown: result.text,
+                guideBuiltAt: result.guideBuiltAt,
+                codegraphState,
+                codegraphReason: null,
+                usage,
+                durationMs,
+            }));
+        }
+        else {
+            printLocalReview(`co-maintainer review · ${options.repo} · PR #${options.prNumber}`, result.text);
+            if (options.logTime) {
+                log("time", `AI total · calls=${aiMetrics.calls} · input=${aiMetrics.tokensIn} tokens · output=${aiMetrics.tokensOut} tokens · cost=${aiMetrics.costKnown ? aiMetrics.cost.toFixed(4) : "unknown"}`);
+                console.error(`[time] total review · ${((performance.now() - operationStarted) / 1000).toFixed(2)}s`);
+            }
+        }
+        stopHeartbeat();
+        process.exit(cli.json
+            ? reviewExitCodeFromResolved(findings)
+            : reviewExitCode(result.text));
+    });
+}

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

@@ -0,0 +1,18 @@
+import type { UserConfig } from "../../config.ts";
+import type { AuthMethods } from "../../server/auth.ts";
+import { type Platform } from "../../util/runtime.ts";
+/** `undefined` on Linux, otherwise one line naming the platform (a pure
+ * function so it is testable without actually being off Linux). */
+export declare function platformWarning(os: Platform): string | undefined;
+/** `--disable-auth=password` / `--enable-auth=github` always win over the
+ * config defaults `co-maintainer set` persisted; dies if the result would
+ * leave no sign-in method active. Pure so it is testable without a server. */
+export declare function resolveAuthMethods(args: string[], config: Pick<UserConfig, "passwordAuthDisabled" | "githubAuthEnabled">): AuthMethods;
+export declare function resolveWebhookUrl(args: string[], port: number, configured?: string): string;
+/** `co-maintainer serve --port=N [--password=...] [--disable-auth=password]
+ * [--enable-auth=github] [--inject-500]`. HMAC-verified `POST /github/webhook`
+ * plus a dashboard gated by password and/or GitHub sign-in. Requires the
+ * GitHub App via `co-maintainer set` (webhook secret is optional, only the
+ * App ID and private key gate startup); GitHub sign-in additionally needs
+ * `--github-oauth-client-id`/`-client-secret`/`-allowed-user` set. */
+export declare function runServe(args: string[]): Promise<void>;

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

@@ -0,0 +1,183 @@
+import { readConfig } from "../../config.js";
+import { appDbPath, closeAppDb, openAppDb } from "../../store/app_db.js";
+import { createApp } from "../../server/app.js";
+import { recoverOrphans, startWorkerLoop, stopWorkerLoop, } from "../../services/jobs.js";
+import { registerSetupJobHandler } from "../../services/setup.js";
+import { registerReviewJobHandler } from "../../services/review.js";
+import { recoverReplyRequests, registerReplyJobHandler, } from "../../services/replies.js";
+import { registerRemoteReviewHandler } from "../../services/remote_review.js";
+import { startRemoteWatchdog } from "../../remote/server/sessions.js";
+import { serveHttp } from "../../server/http.js";
+import { currentPlatform, getEnv } from "../../util/runtime.js";
+/** `undefined` on Linux, otherwise one line naming the platform (a pure
+ * function so it is testable without actually being off Linux). */
+export function platformWarning(os) {
+    if (os === "linux")
+        return undefined;
+    return `running on ${os}. Linux (WSL included) is the recommended platform for serve — see PLAN.md Decision 5.`;
+}
+function die(message) {
+    throw new Error(message);
+}
+function generatePassword() {
+    const bytes = new Uint8Array(12);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** `--disable-auth=password` / `--enable-auth=github` always win over the
+ * config defaults `co-maintainer set` persisted; dies if the result would
+ * leave no sign-in method active. Pure so it is testable without a server. */
+export function resolveAuthMethods(args, config) {
+    const disableAuth = args
+        .find((arg) => arg.startsWith("--disable-auth="))
+        ?.slice("--disable-auth=".length);
+    if (disableAuth && disableAuth !== "password") {
+        die("--disable-auth only supports: password");
+    }
+    const enableAuth = args
+        .find((arg) => arg.startsWith("--enable-auth="))
+        ?.slice("--enable-auth=".length);
+    if (enableAuth && enableAuth !== "github") {
+        die("--enable-auth only supports: github");
+    }
+    const password = disableAuth ? false : !config.passwordAuthDisabled;
+    const github = enableAuth ? true : Boolean(config.githubAuthEnabled);
+    if (!password && !github) {
+        die("at least one sign-in method is required; drop --disable-auth=password or pass --enable-auth=github");
+    }
+    return { password, github };
+}
+export function resolveWebhookUrl(args, port, configured) {
+    const flag = args.find((arg) => arg.startsWith("--webhook-url="));
+    const raw = flag?.slice("--webhook-url=".length) ??
+        getEnv("CM_WEBHOOK_URL") ??
+        configured ??
+        `http://localhost:${port}/github/webhook`;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        die("--webhook-url must be an absolute http(s) URL, e.g. " +
+            "--webhook-url=https://example.com/github/webhook");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        die("--webhook-url must use http or https");
+    }
+    return url.toString();
+}
+/** `co-maintainer serve --port=N [--password=...] [--disable-auth=password]
+ * [--enable-auth=github] [--inject-500]`. HMAC-verified `POST /github/webhook`
+ * plus a dashboard gated by password and/or GitHub sign-in. Requires the
+ * GitHub App via `co-maintainer set` (webhook secret is optional, only the
+ * App ID and private key gate startup); GitHub sign-in additionally needs
+ * `--github-oauth-client-id`/`-client-secret`/`-allowed-user` set. */
+export async function runServe(args) {
+    const portArg = args
+        .find((arg) => arg.startsWith("--port="))
+        ?.slice("--port=".length);
+    if (!portArg)
+        die("--port is required, e.g. --port=5000");
+    const port = Number(portArg);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        die("--port must be an integer between 1 and 65535");
+    }
+    const config = readConfig();
+    const webhookUrl = resolveWebhookUrl(args, port, config.webhookUrl);
+    const missing = [
+        !config.githubAppId && "--github-app-id=...",
+        !config.githubAppPrivateKey &&
+            "--github-app-private-key=... (or --github-app-private-key-file=path)",
+    ].filter(Boolean);
+    if (missing.length > 0) {
+        die(`serve requires the GitHub App to be configured first; run:\n` +
+            `  co-maintainer set ${missing.join(" ")}`);
+    }
+    const auth = resolveAuthMethods(args, config);
+    let githubOAuth;
+    if (auth.github) {
+        if (!config.githubOAuthClientId ||
+            !config.githubOAuthClientSecret ||
+            !config.githubOAuthAllowedUser) {
+            die("GitHub sign-in requires OAuth credentials; run:\n" +
+                "  co-maintainer set --github-oauth-client-id=... --github-oauth-client-secret=... --github-oauth-allowed-user=...");
+        }
+        githubOAuth = {
+            clientId: config.githubOAuthClientId,
+            clientSecret: config.githubOAuthClientSecret,
+            allowedUser: config.githubOAuthAllowedUser,
+        };
+    }
+    const warning = platformWarning(currentPlatform());
+    if (warning)
+        console.log(`[serve] warning: ${warning}`);
+    await openAppDb();
+    console.log(`[serve] app.db ready at ${appDbPath()}`);
+    registerSetupJobHandler();
+    registerReviewJobHandler();
+    registerRemoteReviewHandler();
+    startRemoteWatchdog();
+    registerReplyJobHandler();
+    const recovered = await recoverOrphans();
+    if (recovered > 0) {
+        console.log(`[serve] recovered ${recovered} orphaned job(s) from a previous run`);
+    }
+    const recoveredReplies = recoverReplyRequests();
+    if (recoveredReplies > 0) {
+        console.log(`[serve] requeued ${recoveredReplies} unfinished conversation repl${recoveredReplies === 1 ? "y" : "ies"}`);
+    }
+    startWorkerLoop();
+    const password = auth.password
+        ? (args
+            .find((arg) => arg.startsWith("--password="))
+            ?.slice("--password=".length) ?? generatePassword())
+        : "";
+    if (auth.password)
+        console.log(`[serve] dashboard password: ${password}`);
+    if (auth.github)
+        console.log(`[serve] GitHub sign-in enabled for ${githubOAuth.allowedUser}`);
+    const inject500 = args.includes("--inject-500") || getEnv("CM_INJECT_500") === "1";
+    if (inject500) {
+        console.log("[serve] --inject-500 is on. Mutating /api requests return 500.");
+    }
+    const app = createApp({
+        password,
+        githubApp: config.githubAppId && config.githubAppPrivateKey
+            ? {
+                appId: config.githubAppId,
+                privateKeyPem: config.githubAppPrivateKey,
+            }
+            : undefined,
+        webhookSecret: config.githubWebhookSecret,
+        webhookUrl,
+        inject500,
+        auth,
+        githubOAuth,
+    });
+    const server = serveHttp((req, remoteAddr) => app.fetch(req, remoteAddr), port);
+    console.log(`[serve] listening on http://localhost:${port}`);
+    console.log(`[serve] dashboard at http://localhost:${port}/`);
+    console.log(`[serve] webhook URL: ${webhookUrl}`);
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`[serve] received ${signal}, stopping new requests and closing app.db`);
+        await stopWorkerLoop();
+        await server.shutdown();
+        await closeAppDb();
+        console.log("[serve] shut down cleanly");
+        process.exit(0);
+    };
+    // Ctrl+C in an interactive terminal fires this reliably everywhere,
+    // including Windows. A SIGTERM sent by another process (a process
+    // manager, `kill`, `taskkill`) is reliable on Linux but not on Windows,
+    // where it forcibly terminates the process before any handler can run —
+    // see the P3 Live note in PLAN.md. Registering it anyway costs nothing
+    // and is correct wherever it does work.
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => void shutdown(signal));
+    }
+    await server.finished;
+}