co-maintainer 0.4.13 → 0.5.0-beta.1

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

@@ -6,9 +6,12 @@ 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 { reviewExitCode } from "../review_output.js";
 import { buildPrReviewJson, resolvedFromFirstReview, reviewExitCodeFromResolved, } from "../review_result.js";
 import { parseFindings } from "../../pr/findings.js";
+import { exitWith } from "../error.js";
+import { printRunSummary, summaryFromMetrics } from "../../util/run_summary.js";
+import { formatHumanReview, humanFindingsFromResolved, } from "../review_result.js";
 export async function runReviewFromCli(args) {
     const parsed = await parseReviewArgs(args);
     if (parsed.mode === "local") {
@@ -35,50 +38,70 @@ async function runReviewPr(options, cli) {
         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.debug), 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,
+        try {
+            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.debug), 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);
             }));
-        }
-        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`);
+            const durationMs = Math.round(performance.now() - operationStarted);
+            const usage = {
+                tokensIn: aiMetrics.tokensIn,
+                tokensOut: aiMetrics.tokensOut,
+                costUsd: aiMetrics.costKnown ? aiMetrics.cost : null,
+            };
+            // The engine reports the codegraph state it actually reached, instead of
+            // the old `useCodegraph ? "used" : "disabled"` that claimed "used" while
+            // stderr said codegraph was missing (CORE-43 / F23).
+            const codegraphState = result.codegraphState;
+            const resolved = 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,
+                    reviewBlocking: options.reviewBlocking,
+                }));
             }
+            else {
+                // One presentation layer for local, PR and remote reviews (CORE-43).
+                console.log("\n" +
+                    formatHumanReview({
+                        title: `co-maintainer review · ${options.repo} · PR #${options.prNumber}`,
+                        guideBuiltAt: result.guideBuiltAt,
+                        codegraphState,
+                        findings: humanFindingsFromResolved(resolved, options.reviewBlocking),
+                    }) +
+                    "\n");
+                printRunSummary(summaryFromMetrics(aiMetrics, performance.now() - operationStarted));
+                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`);
+                }
+            }
+            exitWith(cli.json
+                ? reviewExitCodeFromResolved(resolved, options.reviewBlocking)
+                : reviewExitCode(result.text, options.reviewBlocking));
+        }
+        finally {
+            // A heartbeat left running on the error path keeps the event loop alive
+            // forever, so the process would never drain and the exit code would never
+            // be applied. CORE-11.
+            stopHeartbeat();
         }
-        stopHeartbeat();
-        process.exit(cli.json
-            ? reviewExitCodeFromResolved(findings)
-            : reviewExitCode(result.text));
     });
 }

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

@@ -1,8 +1,10 @@
 import type { UserConfig } from "../../config.ts";
 import type { AuthMethods, PasswordStore } 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). */
+/** `undefined` on Linux, otherwise one line naming the platform. The
+ * recommendation is spelled out rather than pointing at an internal
+ * document, so the message stands on its own and links to the public
+ * troubleshooting page for the details. */
 export declare function platformWarning(os: Platform): string | undefined;
 export declare function resolveTrustProxy(args: string[], env?: (name: string) => string | undefined): boolean;
 /** `--password=` replaces the stored password. With no flag the stored one is

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

@@ -1,4 +1,4 @@
-import { readConfig } from "../../config.js";
+import { readConfig, resolveAppPrivateKey, appPrivateKeyFileMissing, } from "../../config.js";
 import { appDbPath, closeAppDb, openAppDb } from "../../store/app_db.js";
 import { createApp } from "../../server/app.js";
 import { configPasswordStore } from "../../server/auth.js";
@@ -12,15 +12,15 @@ import { startRemoteWatchdog } from "../../remote/server/sessions.js";
 import { passwordProblem } from "../../util/password.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). */
+import { die } from "../error.js";
+/** `undefined` on Linux, otherwise one line naming the platform. The
+ * recommendation is spelled out rather than pointing at an internal
+ * document, so the message stands on its own and links to the public
+ * troubleshooting page for the details. */
 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);
+    return `running on ${os}. Linux (WSL included) is the recommended platform for serve. See https://co-maintainer.com/docs/troubleshooting.html`;
 }
 function generatePassword() {
     const bytes = new Uint8Array(12);
@@ -68,7 +68,7 @@ export function resolveAuthMethods(args, config) {
     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");
+        die("at least one sign-in method is required. Drop --disable-auth=password or pass --enable-auth=github");
     }
     return { password, github };
 }
@@ -124,16 +124,19 @@ export async function runServe(args) {
     }
     const config = readConfig();
     const webhookUrl = resolveWebhookUrl(args, port, config.webhookUrl);
-    if (!config.githubAppId || !config.githubAppPrivateKey) {
+    if (!config.githubAppId || !resolveAppPrivateKey(config)) {
         console.log("[serve] GitHub App is not configured yet. Add it in the dashboard settings or with co-maintainer set.");
     }
+    if (appPrivateKeyFileMissing(config)) {
+        console.log(`[serve] warning: the GitHub App private key file listed in config.json cannot be read (${config.githubAppPrivateKeyPath}). The App will not work until it is restored or replaced.`);
+    }
     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" +
+            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 = {
@@ -187,6 +190,7 @@ export async function runServe(args) {
         trustProxy,
         auth,
         githubOAuth,
+        loginHint: getEnv("CM_LOGIN_HINT"),
     });
     const server = serveHttp((req, remoteAddr) => app.fetch(req, remoteAddr), port);
     console.log(`[serve] listening on http://localhost:${port}`);

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

@@ -1,6 +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=...` —
+ * --github-app-private-key-file=path or --github-app-private-key-path=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. */

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

@@ -1,9 +1,9 @@
-import { writeUserConfig } from "../../config.js";
+import { readConfig, configPath, writeUserConfig } from "../../config.js";
 import { hashPassword, passwordProblem } from "../../util/password.js";
 import { readTextFile } from "../../util/runtime.js";
-function die(message) {
-    throw new Error(message);
-}
+import { verifyOpenRouter } from "../../ai/verify.js";
+import { die } from "../error.js";
+import { renderCommandHelp, renderGlobalHelp } from "./registry.js";
 function text(args, name) {
     return args
         .find((arg) => arg.startsWith(`--${name}=`))
@@ -20,22 +20,19 @@ const secretFields = new Set([
 ]);
 /** `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=...` —
+ * --github-app-private-key-file=path or --github-app-private-key-path=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("                        --password=... --disable-auth=password --enable-auth=github");
-        console.log("Writes to the user config file; unset an entry with --unset=name (e.g. --unset=token).");
+        console.log(renderCommandHelp("set") ?? renderGlobalHelp());
         return;
     }
     const known = [
         "token",
+        "ai-key",
         "ai",
         "low-model",
         "high-model",
@@ -44,6 +41,7 @@ export async function runSet(args) {
         "github-app-id",
         "github-app-private-key",
         "github-app-private-key-file",
+        "github-app-private-key-path",
         "github-webhook-secret",
         "github-oauth-client-id",
         "github-oauth-client-secret",
@@ -52,10 +50,14 @@ export async function runSet(args) {
         "enable-auth",
         "remote-host",
         "remote-token",
+        "review-blocking",
         "password",
         "unset",
     ];
+    const verify = !args.includes("--no-verify");
     for (const arg of args) {
+        if (arg === "--no-verify")
+            continue;
         if (!arg.startsWith("--") ||
             !known.some((name) => arg.startsWith(`--${name}=`))) {
             die(`Unknown option: ${arg}`);
@@ -69,12 +71,17 @@ export async function runSet(args) {
     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 providedKeySources = [
+        text(args, "github-app-private-key"),
+        text(args, "github-app-private-key-file"),
+        text(args, "github-app-private-key-path"),
+    ].filter((value) => value !== undefined);
+    if (providedKeySources.length > 1) {
+        die("Pass only one of --github-app-private-key, --github-app-private-key-file, or --github-app-private-key-path");
     }
     const fieldByFlag = {
         token: "token",
+        "ai-key": "token",
         ai: "ai",
         "low-model": "lowModel",
         "high-model": "highModel",
@@ -82,6 +89,7 @@ export async function runSet(args) {
         "github-pat": "githubPat",
         "github-app-id": "githubAppId",
         "github-app-private-key": "githubAppPrivateKey",
+        "github-app-private-key-path": "githubAppPrivateKeyPath",
         "github-webhook-secret": "githubWebhookSecret",
         "github-oauth-client-id": "githubOAuthClientId",
         "github-oauth-client-secret": "githubOAuthClientSecret",
@@ -90,6 +98,7 @@ export async function runSet(args) {
         "enable-auth": "githubAuthEnabled",
         "remote-host": "remoteHost",
         "remote-token": "remoteToken",
+        "review-blocking": "reviewBlocking",
         password: "dashboardPasswordHash",
     };
     const unset = new Set(args
@@ -110,7 +119,7 @@ export async function runSet(args) {
     const highModel = text(args, "high-model");
     if (highModel)
         patch.highModel = highModel;
-    const token = text(args, "token");
+    const token = text(args, "token") ?? text(args, "ai-key");
     if (token)
         patch.token = token;
     const githubPat = text(args, "github-pat");
@@ -134,6 +143,17 @@ export async function runSet(args) {
             die(`Could not read ${privateKeyFile}: ${String(error)}`);
         }
     }
+    // The path form keeps the key on disk: only the location is stored, and it
+    // is read at startup. Passing one of the other two forms also clears a
+    // previously saved path so the inline key or file wins unambiguously.
+    const privateKeyPath = text(args, "github-app-private-key-path");
+    if (privateKeyPath) {
+        patch.githubAppPrivateKeyPath = privateKeyPath;
+        patch.githubAppPrivateKey = undefined;
+    }
+    else if (githubAppPrivateKey || privateKeyFile) {
+        patch.githubAppPrivateKeyPath = undefined;
+    }
     const oauthClientId = text(args, "github-oauth-client-id");
     if (oauthClientId)
         patch.githubOAuthClientId = oauthClientId;
@@ -161,6 +181,13 @@ export async function runSet(args) {
     const remoteToken = text(args, "remote-token");
     if (remoteToken)
         patch.remoteToken = remoteToken;
+    const reviewBlocking = text(args, "review-blocking");
+    if (reviewBlocking) {
+        if (!["model", "severity"].includes(reviewBlocking)) {
+            die("--review-blocking must be one of: model, severity");
+        }
+        patch.reviewBlocking = reviewBlocking;
+    }
     const password = text(args, "password");
     if (password) {
         const problem = passwordProblem(password);
@@ -169,14 +196,33 @@ export async function runSet(args) {
         patch.dashboardPasswordHash = await hashPassword(password);
     }
     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=, " +
+        die("Nothing to set. Pass --token= (or --ai-key=), --ai=, --low-model=, --high-model=, --auth=, --github-pat=, " +
+            "--github-app-id=, --github-app-private-key(-file|-path)=, --github-webhook-secret=, " +
             "--github-oauth-client-id=, --github-oauth-client-secret=, --github-oauth-allowed-user=, " +
+            "--remote-host=, --remote-token=, --review-blocking=model|severity, " +
             "--password=, --disable-auth=password, --enable-auth=github, or --unset=name");
     }
+    // Verify the key and model before writing, so a typo fails here instead of
+    // after a review has already fetched and cloned the pull request (CORE-22).
+    // A field present in the patch wins, including when its value is `undefined`
+    // — that is an unset, and there is nothing left to verify.
+    const before = readConfig();
+    const effective = (field) => field in patch ? patch[field] : before[field];
+    const effectiveAi = effective("ai");
+    const effectiveToken = effective("token");
+    const effectiveHighModel = effective("highModel");
+    if (verify && effectiveAi === "openrouter" && effectiveToken) {
+        const result = await verifyOpenRouter(String(effectiveToken), effectiveHighModel === undefined ? undefined : String(effectiveHighModel));
+        if (result.status === "rejected")
+            throw result.error;
+        if (result.status === "unreachable") {
+            console.error(`[set] could not verify the key and model (${result.reason}); saved anyway.`);
+        }
+    }
     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(", ")}`);
+    console.log(`Saved to ${configPath()}`);
 }

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

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

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

@@ -0,0 +1,180 @@
+/** `co-maintainer view`: print the guides co-maintainer already generated
+ * (CORE-23, F25). Read-only — the counterpart to `config` for the generated
+ * knowledge rather than the settings.
+ *
+ * Two sources, one presentation (CORE-44): the guide directory on this machine,
+ * or the servers a remote review token can read (`--remote`). Local and remote
+ * differ only in where the guide list comes from, so `--list`, a single guide
+ * and the every-guide headers are all rendered by the same code.
+ *
+ * Naming: the plan calls the guide kinds `skill`, `codebase`,
+ * `review-guide`, `detailed-guide`; `--list` and the headers show the real
+ * file names, and a kind name is accepted too so a user never has to type
+ * `PR_REVIEW_GUIDE.md` unless they want to. */
+import { readConfig, reposDir } from "../../config.js";
+import { detectRemoteRepo } from "../../local/git_ops.js";
+import { CliError, EXIT_USAGE } from "../error.js";
+import { renderCommandHelp, unknownOptionMessage } from "./registry.js";
+import { readDir, readTextFile, stat } from "../../util/runtime.js";
+import { baseUrl, die, readApiError, remoteFetch } from "../../remote/http.js";
+/** The four generated guides, in the order a reader wants them: the
+ * contribution skill first, then the codebase notes, then the two review
+ * guides (short, then the evidence behind it). */
+const GUIDES = [
+    { kind: "skill", file: "SKILL.md" },
+    { kind: "codebase", file: "CODEBASE.md" },
+    { kind: "review-guide", file: "PR_REVIEW_GUIDE.md" },
+    { kind: "detailed-guide", file: "PR_REVIEW_DETAILED_GUIDE.md" },
+];
+/** Resolves a user-supplied name to a guide. Accepts the plan's kind names
+ * (`review-guide`), the file name (`PR_REVIEW_GUIDE.md`), and the bare stem
+ * (`PR_REVIEW_GUIDE`), case-insensitively. */
+function resolveGuide(name) {
+    const wanted = name.toLowerCase();
+    const match = GUIDES.find((guide) => guide.kind === wanted ||
+        guide.file.toLowerCase() === wanted ||
+        guide.file.toLowerCase().replace(/\.md$/, "") === wanted);
+    if (!match) {
+        throw new CliError("unknown_guide", `Unknown guide: ${name}.`, `Pass one of ${GUIDES.map((guide) => guide.kind).join(", ")}, or --list.`, EXIT_USAGE);
+    }
+    return match;
+}
+/** `2026-09-22` from an ISO timestamp, so a header says when the guide was
+ * built without a database lookup. */
+function builtDate(iso) {
+    return iso.slice(0, 10);
+}
+/** A human size for `--list`, so a glance says whether a guide is present. */
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    return `${(bytes / 1024).toFixed(1)} KB`;
+}
+/** The guides that actually exist on disk, in {@link GUIDES} order first so a
+ * local listing reads like a remote one. A file co-maintainer did not write
+ * (an older name, a hand-written note) is kept, after the four known ones. */
+async function readLocalGuides(repo) {
+    const dir = `${reposDir()}/${repo}`;
+    const names = [];
+    try {
+        for await (const entry of readDir(dir)) {
+            if (entry.isFile)
+                names.push(entry.name);
+        }
+    }
+    catch {
+        return [];
+    }
+    const order = (name) => {
+        const index = GUIDES.findIndex((guide) => guide.file === name);
+        return index === -1 ? GUIDES.length : index;
+    };
+    const guides = [];
+    for (const file of names.sort((a, b) => order(a) - order(b) || a.localeCompare(b))) {
+        try {
+            const info = await stat(`${dir}/${file}`);
+            guides.push({
+                kind: GUIDES.find((guide) => guide.file === file)?.kind ?? "other",
+                file,
+                size: info.size,
+                builtAt: info.mtime.toISOString(),
+                content: await readTextFile(`${dir}/${file}`),
+            });
+        }
+        catch {
+            // Vanished between the listing and the read: skip it rather than fail
+            // the whole directory.
+        }
+    }
+    return guides;
+}
+/** The guides a remote review server holds for `repo` (CORE-44). The token is
+ * the same one `review --remote` uses, so a host already configured for remote
+ * review needs no extra setup. */
+async function readRemoteGuides(repo) {
+    const config = readConfig();
+    const host = config.remoteHost;
+    const token = config.remoteToken;
+    if (!host || !token) {
+        die("remote_not_configured", "Remote review is not configured.", "co-maintainer config set remote-host https://your-server " +
+            "&& co-maintainer config set remote-token <token>");
+    }
+    const response = await remoteFetch(host, token, `/api/remote/guides?repo=${encodeURIComponent(repo)}`, { method: "GET" });
+    if (!response.ok) {
+        die("remote_guides_failed", `The server at ${baseUrl(host)} could not list the guides for ${repo}.`, await readApiError(response));
+    }
+    const body = (await response.json());
+    return body.guides ?? [];
+}
+/** Resolves the repo: the explicit `owner/repo` when given, otherwise the
+ * git remote of the current directory. */
+async function resolveRepo(args) {
+    const positional = args.find((arg) => !arg.startsWith("-"));
+    if (positional && /^[^/]+\/[^/]+$/.test(positional))
+        return positional;
+    return detectRemoteRepo(process.cwd(), positional);
+}
+/** Prints one guide list: `--list` rows, the raw single guide, or every guide
+ * behind its own header. Shared by the local and remote sources so the two
+ * cannot drift into different outputs. */
+function printGuides(repo, guides, options) {
+    if (options.list) {
+        const width = Math.max(...guides.map((guide) => guide.file.length));
+        for (const guide of guides) {
+            console.log(`${guide.file.padEnd(width)}  ${humanSize(guide.size).padStart(8)}  ${builtDate(guide.builtAt)}`);
+        }
+        return;
+    }
+    if (options.name) {
+        // A single guide is printed raw, with no header, so `view ... | pbcopy`
+        // and `view ... > file` produce exactly the markdown.
+        const wanted = resolveGuide(options.name);
+        const found = guides.find((guide) => guide.file === wanted.file);
+        if (!found) {
+            throw new CliError("guide_missing", `${repo} has no ${wanted.file}.`, `co-maintainer view ${repo} --list`, EXIT_USAGE);
+        }
+        process.stdout.write(found.content);
+        return;
+    }
+    // Every guide, each behind a header that says which file and when it was
+    // built, so a scroll through the output never loses its place.
+    console.log(guides
+        .map((guide) => `== ${guide.file} · built ${builtDate(guide.builtAt)} ==\n${guide.content.trimEnd()}`)
+        .join("\n\n"));
+}
+export async function runView(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(renderCommandHelp("view") ??
+            "Usage: co-maintainer view [owner/repo] [guide]");
+        return;
+    }
+    const remote = args.includes("--remote");
+    for (const arg of args) {
+        if (arg.startsWith("--") &&
+            !["--list", "--path", "--remote", "--help", "-h"].includes(arg)) {
+            throw new CliError("usage", unknownOptionMessage(arg));
+        }
+    }
+    // The directory belongs to this machine, so it cannot answer for a server.
+    if (remote && args.includes("--path")) {
+        throw new CliError("usage", "--path and --remote cannot be combined.", "Drop --remote to print the local guide directory.", EXIT_USAGE);
+    }
+    const repo = await resolveRepo(args);
+    const name = args.find((arg) => !arg.startsWith("-") && arg !== repo);
+    if (!remote && args.includes("--path")) {
+        console.log(`${reposDir()}/${repo}`);
+        return;
+    }
+    const guides = remote
+        ? await readRemoteGuides(repo)
+        : await readLocalGuides(repo);
+    if (guides.length === 0) {
+        throw new CliError("no_guides", remote
+            ? `The server has no guides for ${repo}.`
+            : `No guides for ${repo}.`, `co-maintainer probe ${repo}`, EXIT_USAGE);
+    }
+    printGuides(repo, guides, {
+        list: args.includes("--list"),
+        name,
+    });
+}

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

@@ -0,0 +1,39 @@
+/** One error shape for every CLI failure (CORE-10).
+ *
+ * The message is the first line the user reads, `hint` is an optional
+ * follow-up line printed as `Hint: ...`, and `exitCode` is the documented
+ * contract: 1 only for blocking review findings, 2 for usage and precondition
+ * errors, 3 for runtime failures. Anything thrown that is not a `CliError` is
+ * treated as a runtime failure (3), which is the safe default for the network,
+ * provider and filesystem errors the CLI does not classify yet.
+ */
+export declare const EXIT_FINDINGS = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_RUNTIME = 3;
+export declare class CliError extends Error {
+    code: string;
+    hint?: string;
+    exitCode: number;
+    constructor(code: string, message: string, hint?: string, exitCode?: number);
+}
+/** Throws a usage or precondition error. Kept as a helper so the existing
+ * `die(...)` call sites read the same as before. */
+export declare function die(message: string, code?: string): never;
+/** Ends the CLI with `code`, letting the event loop drain first.
+ *
+ * `process.exit` while undici's fetch connection pool is still open asserts in
+ * libuv on Windows (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING),
+ * file src\win\async.c, line 94`) and the process dies with 0xC0000409 instead
+ * of the intended code. Every provider and remote call uses fetch, so this is
+ * reachable from any error path after a request. Setting `exitCode` and letting
+ * the loop empty is what the probe confirms is crash-free and immediate (the
+ * undici pool does not keep the process alive). CORE-11. */
+export declare function exitWith(code: number): void;
+/** Renders an error the way the CLI prints it: the message, then `Hint: ...`
+ * when there is one. Used where an error becomes a log line rather than the
+ * top-level exit (CORE-12), so a hint is not lost just because the failure was
+ * quarantined. */
+export declare function formatError(error: unknown): string;
+/** A failed `fetch` as a message that names the host and the cause (CORE-12).
+ * Node's own text is only `fetch failed`, which says neither. */
+export declare function networkFailure(url: string, error: unknown): CliError;