co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/cli/error.js

@@ -0,0 +1,64 @@
+/** 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 const EXIT_FINDINGS = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_RUNTIME = 3;
+export class CliError extends Error {
+    code;
+    hint;
+    exitCode;
+    constructor(code, message, hint, exitCode = EXIT_USAGE) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+    }
+}
+/** Throws a usage or precondition error. Kept as a helper so the existing
+ * `die(...)` call sites read the same as before. */
+export function die(message, code = "usage") {
+    throw new CliError(code, message, undefined, EXIT_USAGE);
+}
+/** 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 function exitWith(code) {
+    process.exitCode = code;
+}
+/** 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 function formatError(error) {
+    if (error instanceof CliError) {
+        return error.hint ? `${error.message} Hint: ${error.hint}` : error.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/** 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 function networkFailure(url, error) {
+    const code = error.cause?.code;
+    let host = url;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // Keep the raw value when it does not parse.
+    }
+    return new CliError("network_failed", `Could not reach ${host}${code ? `: ${code}` : "."}`, undefined, EXIT_RUNTIME);
+}

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

@@ -1 +1,8 @@
 export declare function run(args: string[]): Promise<void>;
+/** The single place a CLI error turns into output and an exit code (CORE-10).
+ * The message's first line and the optional `Hint:` line keep the 0.4.13
+ * shape. With `--json` the error goes to stdout as `schemaVersion 1` JSON, the
+ * same shape local review already used. CORE-11 later replaces the direct
+ * `process.exit` with `exitCode` plus handle cleanup, which is why that work is
+ * separate. */
+export declare function reportCliError(error: unknown): void;

package/dist/src/cli/main.js

@@ -3,12 +3,55 @@
 import { parseArgs } from "./args.js";
 import { runServe } from "./commands/serve.js";
 import { runSet } from "./commands/set.js";
+import { runConfig } from "./commands/config.js";
+import { runView } from "./commands/view.js";
 import { runProbe } from "./commands/probe.js";
 import { runReviewFromCli } from "./commands/review.js";
 import { runInitOrRemake } from "../services/setup.js";
 import { VERSION } from "../version.js";
+import { CliError, EXIT_RUNTIME, exitWith } from "./error.js";
+import { findCommand, renderCommandHelp, renderGlobalHelp, unknownCommandMessage, } from "./commands/registry.js";
+/** Every command's help is rendered from the registry, so a new flag cannot
+ * drift out of it. `help <command>`, `<command> --help` and `<command> -h` all
+ * land here and all exit 0 (CORE-20). */
+function printHelpFor(name) {
+    const help = renderCommandHelp(name);
+    console.log(help ?? renderGlobalHelp());
+    exitWith(0);
+}
+/** True when the help was printed and `run` should stop. */
+function handleHelp(args) {
+    const first = args[0];
+    if (first === "help") {
+        const target = args.find((arg) => !arg.startsWith("-") && arg !== "help");
+        if (target)
+            printHelpFor(target);
+        else {
+            console.log(renderGlobalHelp());
+            exitWith(0);
+        }
+        return true;
+    }
+    if (first === "--help" || first === "-h") {
+        console.log(renderGlobalHelp());
+        exitWith(0);
+        return true;
+    }
+    // `<command> --help` without a repo: `serve --help` and `set --help` must not
+    // reach their handlers, which would start a server or demand a flag (CORE-20).
+    if (first && (args.includes("--help") || args.includes("-h"))) {
+        const spec = findCommand(first);
+        if (spec) {
+            printHelpFor(first);
+            return true;
+        }
+    }
+    return false;
+}
 export async function run(args) {
-    if (args[0] === "-v" || args[0] === "--version") {
+    if (handleHelp(args))
+        return;
+    if (args[0] === "-v" || args[0] === "--version" || args[0] === "version") {
         console.log(VERSION);
         return;
     }
@@ -16,6 +59,14 @@ export async function run(args) {
         await runSet(args.slice(1));
         return;
     }
+    if (args[0] === "config") {
+        await runConfig(args.slice(1));
+        return;
+    }
+    if (args[0] === "view") {
+        await runView(args.slice(1));
+        return;
+    }
     if (args[0] === "serve") {
         await runServe(args.slice(1));
         return;
@@ -24,9 +75,39 @@ export async function run(args) {
         await runReviewFromCli(args.slice(1));
         return;
     }
+    // An unknown command is a usage error with a suggestion, and it must resolve
+    // through the registry so hidden aliases still work (CORE-20).
+    if (args[0] && !args[0].startsWith("-") && !findCommand(args[0])) {
+        throw new CliError("usage", unknownCommandMessage(args[0]));
+    }
     const options = await parseArgs(args);
     if (options.command === "probe")
         await runProbe(options);
     else
         await runInitOrRemake(options);
 }
+/** The single place a CLI error turns into output and an exit code (CORE-10).
+ * The message's first line and the optional `Hint:` line keep the 0.4.13
+ * shape. With `--json` the error goes to stdout as `schemaVersion 1` JSON, the
+ * same shape local review already used. CORE-11 later replaces the direct
+ * `process.exit` with `exitCode` plus handle cleanup, which is why that work is
+ * separate. */
+export function reportCliError(error) {
+    const cli = error instanceof CliError
+        ? error
+        : new CliError("runtime", error instanceof Error ? error.message : String(error), undefined, EXIT_RUNTIME);
+    if (process.argv.includes("--json")) {
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            ok: false,
+            error: { code: cli.code, message: cli.message, hint: cli.hint },
+            exitCode: cli.exitCode,
+        }));
+    }
+    else {
+        console.error(`[error] ${cli.message}`);
+        if (cli.hint)
+            console.error(`Hint: ${cli.hint}`);
+    }
+    exitWith(cli.exitCode);
+}

package/dist/src/cli/prompt.js

@@ -4,16 +4,30 @@
  * 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";
+/** Asks one question and always settles.
+ *
+ * `rl.question` never settles when stdin reaches EOF before an answer, which
+ * is the F01 hang: `co-maintainer review </dev/null` awaited the answer
+ * forever, printed `Warning: Detected unsettled top-level await`, and exited
+ * 13. Racing the question against `close`/`end` and treating those as "no
+ * answer" keeps the caller's fallback path alive instead. */
 async function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
-        return (await rl.question(question)).trim();
-    }
-    catch {
-        // `question` rejects when stdin closes mid-prompt (Ctrl-D, a detached
-        // pipeline, a killed parent). Treat that as "no answer" so the caller's
-        // own fallback/required validation runs instead of an uncaught rejection.
-        return "";
+        return (await new Promise((resolve) => {
+            let settled = false;
+            const done = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
+            // `question` rejects when stdin closes mid-prompt (Ctrl-D, a detached
+            // pipeline, a killed parent); treat that as "no answer" too.
+            void rl.question(question).then(done, () => done(""));
+            rl.once("close", () => done(""));
+            process.stdin.once("end", () => done(""));
+        })).trim();
     }
     finally {
         rl.close();

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

@@ -10,6 +10,10 @@ type ReviewFlags = {
     branch?: string;
     repoOverride?: string;
     remakeBeforeReview: boolean;
+    /** `--remote-host` override for this run only (CORE-25). */
+    remoteHost?: string;
+    /** `--remote-token` override for this run only (CORE-25). */
+    remoteToken?: string;
 };
 export type ReviewCliArgs = ({
     mode: "pr";

package/dist/src/cli/review_args.js

@@ -1,16 +1,16 @@
 import { parseArgs, setCliInteractive } from "./args.js";
-function die(message) {
-    throw new Error(message);
-}
+import { die } from "./error.js";
 function reviewFlags(rest) {
     const text = (name) => rest.find((item) => item.startsWith(`--${name}=`))?.slice(name.length + 3);
+    // `--remake-before-review` is the 0.4.13 spelling; both names mean the same
+    // thing, and only the new one is documented (CORE-21).
+    const syncBeforeReview = rest.some((arg) => arg === "--sync-before-review" || arg === "--remake-before-review");
     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");
+        if (arg === "--remote" && syncBeforeReview) {
+            die("--sync-before-review cannot be used with --remote");
         }
     }
     return {
@@ -22,7 +22,9 @@ function reviewFlags(rest) {
         toBranch: text("to-branch"),
         branch: text("branch"),
         repoOverride: text("repo"),
-        remakeBeforeReview: rest.includes("--remake-before-review"),
+        remakeBeforeReview: syncBeforeReview,
+        remoteHost: text("remote-host"),
+        remoteToken: text("remote-token"),
     };
 }
 const LOCAL_ONLY_FLAGS = new Set([
@@ -32,6 +34,7 @@ const LOCAL_ONLY_FLAGS = new Set([
     "--allow-tool-install",
     "--fresh",
     "--remake-before-review",
+    "--sync-before-review",
 ]);
 /** Strip local-only flags before `parseArgs` for PR-style options. */
 export function filterReviewConfigArgs(raw) {
@@ -40,7 +43,9 @@ export function filterReviewConfigArgs(raw) {
             return false;
         if (arg.startsWith("--to-branch=") ||
             arg.startsWith("--branch=") ||
-            arg.startsWith("--repo=")) {
+            arg.startsWith("--repo=") ||
+            arg.startsWith("--remote-host=") ||
+            arg.startsWith("--remote-token=")) {
             return false;
         }
         return true;
@@ -50,6 +55,11 @@ export function filterReviewConfigArgs(raw) {
 export async function parseReviewArgs(args) {
     const positional = args.filter((a) => !a.startsWith("--"));
     const flags = reviewFlags(args);
+    // `--remote-host` / `--remote-token` only mean something together with
+    // `--remote`; silently dropping them is exactly the F33 surprise (CORE-25).
+    if ((flags.remoteHost || flags.remoteToken) && !flags.remote) {
+        die("--remote-host and --remote-token require --remote");
+    }
     // `--json` must never prompt (plan §8.7). `parseArgs` only receives the
     // filtered args, and `--json` is stripped before it sees them, so the flag
     // has to be applied here rather than after the parse returns.
@@ -58,6 +68,9 @@ export async function parseReviewArgs(args) {
         /^[^/]+\/[^/]+$/.test(positional[0]) &&
         /^\d+$/.test(positional[1]);
     if (isPr) {
+        if (flags.remoteHost || flags.remoteToken) {
+            die("--remote-host is only for remote review without a PR number");
+        }
         const options = await parseArgs([
             "review",
             positional[0],
@@ -67,7 +80,7 @@ export async function parseReviewArgs(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");
+            die("--sync-before-review is not supported for PR review");
         }
         return {
             mode: "pr",

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

@@ -1,2 +1,2 @@
-export declare function reviewExitCode(markdown: string): number;
-export declare function printLocalReview(header: string, markdown: string): void;
+import { type ReviewBlocking } from "../review/blocking.ts";
+export declare function reviewExitCode(markdown: string, mode?: ReviewBlocking): number;

package/dist/src/cli/review_output.js

@@ -1,10 +1,11 @@
 import { parseFindings } from "../pr/findings.js";
-import { humanCopy } from "../services/review.js";
-export function reviewExitCode(markdown) {
+import { DEFAULT_REVIEW_BLOCKING, isBlocking, } from "../review/blocking.js";
+export function reviewExitCode(markdown, mode = DEFAULT_REVIEW_BLOCKING) {
     const findings = parseFindings(markdown);
-    const blocking = findings.some((f) => f.blocking === true || /\[P0\b/i.test(f.heading));
+    const blocking = findings.some((f) => isBlocking(mode, {
+        severity: f.severity,
+        blocked: f.blocking,
+        text: 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

@@ -1,5 +1,6 @@
 import { type ParsedFinding } from "../pr/findings.ts";
 import { type ResolvedFinding } from "../review/carry_over.ts";
+import { type ReviewBlocking } from "../review/blocking.ts";
 import type { Revision } from "../review/revision.ts";
 export type ReviewWarning = {
     code: string;
@@ -22,29 +23,77 @@ export type JsonReviewFinding = {
         text: string;
     } | null;
 };
-export declare function isBlockingFinding(title: string, severity: string): boolean;
+export declare function isBlockingFinding(title: string, severity: string, mode?: ReviewBlocking): 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 toJsonFinding(row: ResolvedFinding, mode?: ReviewBlocking): JsonReviewFinding;
 export declare function revisionStats(revision: Revision): {
     files: number;
     additions: number;
     deletions: number;
     truncated: boolean;
 };
-export declare function summaryCounts(findings: ResolvedFinding[]): {
+export declare function summaryCounts(findings: ResolvedFinding[], mode?: ReviewBlocking): {
     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 reviewExitCodeFromResolved(findings: ResolvedFinding[], mode?: ReviewBlocking): number;
+/** One finding as the human renderer prints it. Local, PR and remote reviews
+ * all normalize into this shape before printing, so the three modes cannot
+ * drift into different products (CORE-43 / F21, F22). */
+export type HumanFinding = {
+    state: "new" | "open" | "closed";
+    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;
+};
+/** Local and PR findings: blocking is decided here from the configured rule,
+ * exactly as the exit code decides it (CORE-41). */
+export declare function humanFindingsFromResolved(findings: ResolvedFinding[], mode?: ReviewBlocking): HumanFinding[];
+/** Remote findings already carry the server's blocking decision, so the label
+ * uses that field rather than re-deriving the rule on a client that may not
+ * share the server's config (CORE-41). */
+export declare function humanFindingsFromJson(findings: JsonReviewFinding[]): HumanFinding[];
+export type HumanReviewInput = {
+    /** Header line: repo, subject and mode. */
+    title: string;
+    /** Optional `N files · +a −b` fragment, present for a local review. */
+    stats?: string;
+    guideBuiltAt: string | null;
+    /** `null` when the run cannot say (a server older than 0.5.0 sends no
+     * codegraph block). A wrong "used" is what F23 was about, so unknown is
+     * reported as unknown rather than guessed. */
+    codegraphState: "used" | "disabled" | "unavailable" | null;
+    findings: HumanFinding[];
+    warnings?: ReviewWarning[];
+};
+/** The single human-readable review format (CORE-43 / F21, F22, F23). Local,
+ * PR and remote reviews print this: a header naming the guide build date and
+ * the codegraph state, the findings grouped by state, then one summary line.
+ *
+ * The severity legend and the "ask for more detail" sentence are deliberately
+ * absent: a terminal has nobody to ask, and the legend is fixed noise. Both
+ * stay in the GitHub comment, which is a different reader. */
+export declare function formatHumanReview(input: HumanReviewInput): string;
+/** Local review output: the shared format plus the working-tree file stats. */
+export declare function formatHumanLocalReview(header: string, revision: Revision, guideBuiltAt: string | null, codegraphState: "used" | "disabled" | "unavailable", findings: ResolvedFinding[], warnings: ReviewWarning[], mode?: ReviewBlocking): string;
+/** The exit code for a remote review (CORE-41). The server already decided
+ * each finding's `blocking` under its own configured rule, so the client
+ * trusts that field instead of re-deriving the rule from a title: the client
+ * may not even have the same config as the server. */
 export declare function reviewExitCodeFromJsonFindings(findings: JsonReviewFinding[]): number;
 export type LocalReviewJsonInput = {
     repo: string;
@@ -62,6 +111,7 @@ export type LocalReviewJsonInput = {
         costUsd: number | null;
     };
     durationMs: number;
+    reviewBlocking?: ReviewBlocking;
 };
 export type PrReviewJsonInput = {
     repo: string;
@@ -76,6 +126,7 @@ export type PrReviewJsonInput = {
         costUsd: number | null;
     };
     durationMs: number;
+    reviewBlocking?: ReviewBlocking;
 };
 export declare function buildPrReviewJson(input: PrReviewJsonInput): string;
 export declare function buildLocalReviewJson(input: LocalReviewJsonInput): string;