pr-shepherd 0.33.0 → 0.35.0

package/bin/cli/help.mjs

@@ -5,6 +5,23 @@ export const USAGE = {
     top: TOP_USAGE,
     ...COMMAND_USAGE,
 };
+/** Resolve help keys for nested public commands before any command I/O. */
+export function helpKeyForArgs(args) {
+    if (args[0] === "apply" && args[1] === "review")
+        return "apply review";
+    if (args[0] === "apply" && args[1] === "files")
+        return "apply files";
+    if (args[0] === "apply" && args[1] === "journal")
+        return "apply journal";
+    if (args[0] === "admin" && args[1] === "clean")
+        return "admin clean";
+    if (args[0] === "admin" && args[1] === "log-file")
+        return "admin log-file";
+    if (args[0] != null && args[0] in USAGE) {
+        return args[0];
+    }
+    return "top";
+}
 /** Prints usage for `key` to stdout and returns true if `--help` or `-h` is in args. */
 export function maybePrintHelp(args, key) {
     if (!hasFlag(args, "--help") && !hasFlag(args, "-h"))

package/bin/cli/iterate-emitter.d.mts

@@ -0,0 +1,8 @@
+import type { IterateResult } from "../types.mts";
+interface EmitIterateResultOpts {
+    format: "text" | "json";
+    verbose: boolean;
+    readyDelaySuffix?: string;
+}
+export declare function emitIterateResult(result: IterateResult, opts: EmitIterateResultOpts): void;
+export {};

package/bin/cli/iterate-emitter.mjs

@@ -1,4 +1,4 @@
-import { iterateActionToExitCode } from "./exit-codes.mjs";
+import { iterateResultToExitCode } from "../exit-codes.mjs";
 import { formatIterateResult, projectIterateLean, projectIterateVerbose } from "./formatters.mjs";
 export function emitIterateResult(result, opts) {
     const projectionOpts = {
@@ -14,5 +14,5 @@ export function emitIterateResult(result, opts) {
         const text = formatIterateResult(result, { verbose: opts.verbose, ...projectionOpts });
         process.stdout.write(`${text}\n`);
     }
-    process.exitCode = iterateActionToExitCode(result.action);
+    process.exitCode = iterateResultToExitCode(result);
 }

package/bin/cli/iterate-flags.d.mts

@@ -0,0 +1,11 @@
+import type { loadConfig } from "../config/load.mts";
+interface IterateFlags {
+    readyDelaySuffix: string | undefined | null;
+    readyDelaySeconds: number;
+    stallTimeoutSuffix: string | undefined | null;
+    stallTimeoutSeconds: number;
+    noAutoMarkReady: boolean;
+    noAutoCancelActionable: boolean;
+}
+export declare function parseIterateFlags(extra: string[], cfg: ReturnType<typeof loadConfig>): IterateFlags;
+export {};

package/bin/cli/iterate-flags.mjs

@@ -1,5 +1,5 @@
 import { getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 // --ready-delay and --stall-timeout are minute-family flags: a bare number means minutes, and 0 is a
 // valid value (it disables the ready-delay settle window / stall-timeout escalation, respectively).

package/bin/cli/iterate-formatter.d.mts

@@ -0,0 +1,19 @@
+import type { IterateResult } from "../types.mts";
+/**
+ * Format an IterateResult as human-readable Markdown.
+ *
+ * Load-bearing conventions the iterate skill relies on:
+ *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
+ *      the output for logging and validation. Behavior is driven by `## Instructions`,
+ *      not by dispatching on the tag.
+ *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix push` in
+ *      backticks — the skill extracts the backticked content for execution.
+ *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
+ *      that tells the agent exactly what to do with this output. The section is
+ *      unconditional: every action, every variant, always emits at least one step.
+ *      The skill simply follows those steps; it does not need its own dispatch table.
+ */
+export declare function formatIterateResult(result: IterateResult, opts?: {
+    verbose?: boolean;
+    readyDelaySuffix?: string;
+}): string;

package/bin/cli/iterate-instructions.d.mts

@@ -0,0 +1,6 @@
+import type { IterateResult } from "../types.mts";
+export declare function buildSimpleIterateInstructions(result: Exclude<IterateResult, {
+    action: "fix_code";
+}>): string[];
+export declare function adaptIterateLog(log: string): string;
+export declare function numberInstructions(instructions: string[]): string;

package/bin/cli/iterate-lean.d.mts

@@ -0,0 +1,12 @@
+import type { IterateResult } from "../types.mts";
+interface IterateProjectionOptions {
+    readyDelaySuffix?: string;
+}
+/**
+ * Project an IterateResult to a lean JSON shape for the default (non-verbose) output.
+ * Omits fields that are the trivial default (false, 0, empty) or state-gated fields
+ * outside the state where they are meaningful.
+ */
+export declare function projectIterateLean(result: IterateResult, opts?: IterateProjectionOptions): unknown;
+export declare function projectIterateVerbose(result: IterateResult, opts?: IterateProjectionOptions): unknown;
+export {};

package/bin/cli/journal-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { JournalResult } from "../commands/journal/index.mts";
+export declare function formatJournalResult(result: JournalResult): string;

package/bin/cli/journal-formatter.mjs

@@ -0,0 +1,15 @@
+export function formatJournalResult(result) {
+    if (result.dryRun) {
+        const lines = ["Dry run — no body change written."];
+        if (result.previewBody !== undefined) {
+            lines.push("", result.previewBody);
+        }
+        return lines.join("\n");
+    }
+    if (!result.mutated)
+        return "No change — entry already present.";
+    if (!result.sectionExisted) {
+        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
+    }
+    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
+}

package/bin/cli/journal-handler.d.mts

@@ -0,0 +1 @@
+export declare function handleJournal(args: string[], command?: "apply journal" | "journal"): Promise<void>;

package/bin/cli/journal-handler.mjs

@@ -1,8 +1,10 @@
 import { readFile } from "node:fs/promises";
+import { EXIT, errorToExitCode } from "../exit-codes.mjs";
 import { runJournal } from "../commands/journal/index.mjs";
 import { getFlag, parsePrNumber } from "./args.mjs";
 import { USAGE } from "./help.mjs";
-export async function handleJournal(args) {
+import { formatJournalResult } from "./journal-formatter.mjs";
+export async function handleJournal(args, command = "apply journal") {
     for (const a of args) {
         if (!a.startsWith("--"))
             continue;
@@ -10,15 +12,15 @@ export async function handleJournal(args) {
             continue;
         if (a === "--file" || a.startsWith("--file="))
             continue;
-        process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const { prNumber, extra } = parseJournalArgs(args);
     const filePath = getFlag(args, "--file");
     if (filePath !== null && extra[0]) {
-        process.stderr.write(`pr-shepherd: journal: provide the entry as a positional argument or via --file, not both\n`);
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: ${command}: provide the entry as a positional argument or via --file, not both\n`);
+        process.exitCode = EXIT.USAGE;
         return;
     }
     let rawItem;
@@ -26,13 +28,13 @@ export async function handleJournal(args) {
         rawItem = filePath !== null ? await readItemSource(filePath) : extra[0];
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: ${command}: ${String(e)}\n`);
+        process.exitCode = EXIT.NOINPUT;
         return;
     }
     if (rawItem === undefined) {
-        process.stderr.write(`${USAGE.journal}\n`);
-        process.exitCode = 1;
+        process.stderr.write(`${USAGE[command]}\n`);
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const dryRun = args.includes("--dry-run");
@@ -48,8 +50,8 @@ export async function handleJournal(args) {
         }
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: ${command}: ${String(e)}\n`);
+        process.exitCode = errorToExitCode(e);
     }
 }
 /** Reads the journal entry from a file, or from stdin when `filePath` is `-`. */
@@ -95,17 +97,3 @@ function parseJournalArgs(args) {
     }
     return { prNumber, extra };
 }
-function formatJournalResult(result) {
-    if (result.dryRun) {
-        const lines = ["Dry run — no body change written."];
-        if (result.previewBody !== undefined) {
-            lines.push("", result.previewBody);
-        }
-        return lines.join("\n");
-    }
-    if (!result.mutated)
-        return "No change — entry already present.";
-    if (!result.sectionExisted)
-        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
-    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
-}

package/bin/cli/list-formatters.d.mts

@@ -0,0 +1,76 @@
+import type { AuthorType, CommentAuthorAssociation, SuggestionBlock } from "../types.mts";
+import type { FirstLookThread, FirstLookComment } from "../types/report.mts";
+export declare function renderAuthor(author: string, authorType?: AuthorType, authorAssociation?: CommentAuthorAssociation): string;
+export declare function renderBodyPreview(body: string): string;
+export declare function renderThreadResolutionStatusTag(t: {
+    isOutdated?: boolean;
+    isMinimized?: boolean;
+}): string;
+interface ThreadBulletInput {
+    id: string;
+    reviewId?: string;
+    url?: string;
+    path?: string | null;
+    startLine?: number | null;
+    line?: number | null;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+    comments?: Array<{
+        id: string;
+        author: string;
+        authorType?: AuthorType;
+        authorAssociation?: CommentAuthorAssociation;
+        body: string;
+        url: string;
+    }>;
+    suggestion?: SuggestionBlock;
+    edited?: boolean;
+}
+export declare function renderThreadBullet(t: ThreadBulletInput, opts?: {
+    statusTag?: string;
+    renderSuggestion?: boolean;
+    noBody?: boolean;
+    suppressEditedMarker?: boolean;
+}): string;
+export declare function renderThreadConversation(t: ThreadBulletInput): string;
+export declare function blockquote(body: string): string;
+export declare function renderCommentBullet(c: {
+    id: string;
+    url?: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body: string;
+}, opts?: {
+    statusTag?: string;
+}): string;
+export declare function renderEditedCommentTag(c: {
+    edited?: boolean;
+}): string | undefined;
+export declare function renderReviewBullet(r: {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body?: string;
+    staleBotCr?: boolean;
+    staleReview?: boolean;
+}, opts?: {
+    includeBody?: boolean;
+}): string;
+export declare function renderReviewListSection(heading: string, items: {
+    id: string;
+    author: string;
+    authorType?: AuthorType;
+    authorAssociation?: CommentAuthorAssociation;
+    body?: string;
+}[]): string | null;
+/**
+ * Build bullet strings for the `## First-look items` section.
+ * Threads that also appear in resolutionOnlyIds have their body suppressed
+ * (already shown in `## Review threads to resolve`).
+ */
+export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[]): string[];
+export {};

package/bin/cli/list-formatters.mjs

@@ -1,8 +1,8 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 import { threadComments } from "../threads/transcript.mjs";
 const BODY_PREVIEW_MAX = 100;
-export function renderAuthor(author, authorType) {
-    return authorType ? `@${author} · ${authorType}` : `@${author}`;
+export function renderAuthor(author, authorType, authorAssociation) {
+    return [`@${author}`, authorType, authorAssociation].filter(Boolean).join(" · ");
 }
 export function renderBodyPreview(body) {
     const normalizedBody = body.replace(/\r\n?/g, "\n");
@@ -30,7 +30,7 @@ export function renderThreadBullet(t, opts = {}) {
     const editedMarker = t.edited && !opts.suppressEditedMarker ? " [edited since first look]" : "";
     const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
     if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
         const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
         return t.suggestion && opts.renderSuggestion
@@ -53,9 +53,9 @@ export function renderThreadConversation(t) {
         .map((c) => {
         const heading = c.id
             ? c.url
-                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType)})`
-                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType)})`
-            : `#### (${renderAuthor(c.author, c.authorType)})`;
+                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
+                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
+            : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`;
         return `${heading}\n\n${blockquote(c.body)}`;
     })
         .join("\n\n");
@@ -73,7 +73,7 @@ function renderThreadCommentBullets(t) {
         const link = c.url ? ` [↗](${c.url})` : "";
         const id = c.id ? `\`commentId=${c.id}\`` : "comment";
         return [
-            `  - ${id}${link} (${renderAuthor(c.author, c.authorType)})`,
+            `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`,
             indentBlockquote(c.body, "    "),
         ].join("\n");
     })
@@ -88,13 +88,13 @@ function indentBlockquote(body, indent) {
 export function renderCommentBullet(c, opts = {}) {
     const link = c.url ? ` [↗](${c.url})` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
+    return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
 export function renderEditedCommentTag(c) {
     return c.edited ? "[edited since first look]" : undefined;
 }
 export function renderReviewBullet(r, opts = {}) {
-    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`;
+    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`;
     const staleTag = r.staleReview
         ? " [stale — review is on an old commit, all threads resolved]"
         : "";

package/bin/cli/mark-files-as-viewed-flags.d.mts

@@ -0,0 +1,11 @@
+type ParseMarkFilesAsViewedResult = {
+    ok: true;
+    files: string[];
+    tests: boolean;
+    matchPatterns: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseMarkFilesAsViewedArgs(args: string[]): ParseMarkFilesAsViewedResult;
+export {};

package/bin/cli/mark-files-as-viewed-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { MarkFilesAsViewedResult } from "../commands/mark-files-as-viewed.mts";
+export declare function formatMarkFilesAsViewedResult(result: MarkFilesAsViewedResult): string;

package/bin/cli/mutate-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { ResolveResult } from "../comments/resolve.mts";
+export declare function formatMutateResult(result: ResolveResult): string;

package/bin/cli/poll-handler.d.mts

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

package/bin/cli/poll-handler.mjs

@@ -1,7 +1,7 @@
 import { runPoll } from "../commands/poll.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
@@ -14,12 +14,12 @@ export async function handlePoll(args) {
     if (flags.readyDelaySuffix === null || flags.stallTimeoutSuffix === null)
         return;
     const intervalStr = getFlag(extra, "--interval");
-    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));
+    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd", "--interval", intervalStr, hasFlag(extra, "--interval"));
     if (intervalSuffix === null)
         return;
     const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", DEFAULT_POLL_INTERVAL_SECONDS);
     const timeoutStr = getFlag(extra, "--timeout");
-    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
+    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
     if (timeoutSuffix === null)
         return;
     const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", DEFAULT_POLL_TIMEOUT_SECONDS);

package/bin/cli/resolve-validators.d.mts

@@ -0,0 +1,3 @@
+export declare function rejectPrrcMinimizeIds(ids: string[]): string[];
+export declare function warnPrrcThreadIds(ids: string[]): string[];
+export declare function validateRequireSha(sha: string | undefined): boolean;

package/bin/cli/resolve-validators.mjs

@@ -1,15 +1,16 @@
+import { EXIT } from "../exit-codes.mjs";
 export function rejectPrrcMinimizeIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: apply review: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
+        process.exitCode = EXIT.DATAERR;
     }
     return prrcIds;
 }
 export function warnPrrcThreadIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
-        process.stderr.write(`pr-shepherd: resolve: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
+        process.stderr.write(`pr-shepherd: apply review: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
     }
     return prrcIds;
 }
@@ -18,7 +19,7 @@ export function validateRequireSha(sha) {
         return true;
     if (/^[0-9a-f]{40}$/.test(sha))
         return true;
-    process.stderr.write(`pr-shepherd: resolve: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
-    process.exitCode = 1;
+    process.stderr.write(`pr-shepherd: apply review: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
+    process.exitCode = EXIT.DATAERR;
     return false;
 }

package/bin/cli/runner.d.mts

@@ -0,0 +1,7 @@
+interface PrShepherdCommand {
+    argv: string[];
+    text: string;
+}
+export declare function buildPrShepherdCommand(args: string[]): PrShepherdCommand;
+export declare function renderShellCommand(argv: string[]): string;
+export {};

package/bin/cli/suggestion-renderer.d.mts

@@ -0,0 +1,3 @@
+import type { SuggestionBlock } from "../types.mts";
+export declare function renderLineRange(startLine: number | undefined, endLine: number | null): string;
+export declare function renderSuggestionBlock(s: SuggestionBlock, indent?: string): string;

package/bin/cli/validate-default-args.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Validate args for default-dispatch paths (e.g. `pr-shepherd [PR] [flags]`).
+ * Returns false when an unexpected token is found; calls onError with the
+ * offending arg so callers can print their own usage message.
+ */
+export declare function validateDefaultArgs(args: string[], flagsWithValues: ReadonlySet<string>, booleanFlags: ReadonlySet<string>, onError: (arg: string) => void): boolean;

package/bin/cli-parser.d.mts

@@ -0,0 +1,2 @@
+/** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
+export declare function main(argv: string[]): Promise<void>;

package/bin/cli-parser.mjs

@@ -1,10 +1,12 @@
+/* eslint-disable max-lines */
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
+import { EXIT, errorToExitCode } from "./exit-codes.mjs";
 import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
-import { USAGE, maybePrintHelp } from "./cli/help.mjs";
+import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
@@ -30,19 +32,33 @@ export async function main(argv) {
         await handleLogFile(args.slice(1));
         return;
     }
+    // The public command groups keep admin diagnostics out of the normal
+    // command namespace. Keep this before setupLog because log-file reads the
+    // log path and must not initialize/tee the log it is reporting.
+    if (subcommand === "admin" && args[1] === "log-file") {
+        await handleLogFile(args.slice(2), "admin log-file");
+        return;
+    }
     // Short-circuit all --help/-h before any I/O or logging.
     if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
         if (isDefaultPollInvocation(subcommand)) {
-            process.stdout.write(`${USAGE.poll}\n`);
+            process.stdout.write(`${USAGE.default}\n`);
         }
         else {
-            const key = subcommand != null && subcommand in USAGE
-                ? subcommand
-                : "top";
-            process.stdout.write(`${USAGE[key]}\n`);
+            process.stdout.write(`${USAGE[helpKeyForArgs(args)]}\n`);
         }
         return;
     }
+    const legacyReplacement = {
+        poll: "pr-shepherd [PR] (the default PR polling command)",
+        resolve: "apply review",
+        "mark-files-as-viewed": "apply files",
+        journal: "apply journal",
+        "commit-suggestion": "build-suggestion-patch",
+    };
+    if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
+        warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
+    }
     // Initialize the per-worktree log and install a stdout tee.
     await setupLog(argv);
     if (isDefaultPollInvocation(subcommand)) {
@@ -52,14 +68,23 @@ export async function main(argv) {
         return;
     }
     switch (subcommand) {
+        case "apply":
+            await handleApply(args.slice(1));
+            break;
+        case "build-suggestion-patch":
+            await handleCommitSuggestion(args.slice(1));
+            break;
+        case "admin":
+            await handleAdmin(args.slice(1));
+            break;
         case "resolve":
-            await handleResolve(args.slice(1));
+            await handleResolve(args.slice(1), "resolve");
             break;
         case "commit-suggestion":
-            await handleCommitSuggestion(args.slice(1));
+            await handleCommitSuggestion(args.slice(1), "commit-suggestion");
             break;
         case "mark-files-as-viewed":
-            await handleMarkFilesAsViewed(args.slice(1));
+            await handleMarkFilesAsViewed(args.slice(1), "mark-files-as-viewed");
             break;
         case "iterate":
             await handleIterate(args.slice(1));
@@ -68,18 +93,50 @@ export async function main(argv) {
             await handlePoll(args.slice(1));
             break;
         case "clean":
-            await handleClean(args.slice(1));
+            await handleClean(args.slice(1), "clean");
             break;
         case "journal":
-            await handleJournal(args.slice(1));
+            await handleJournal(args.slice(1), "journal");
             break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
             process.stderr.write(`${USAGE.top}\n`);
-            process.exitCode = 1;
+            process.exitCode = EXIT.USAGE;
             return;
     }
 }
+function warnLegacyAlias(alias, replacement) {
+    process.stderr.write(`pr-shepherd: ${alias} is deprecated; use ${replacement.startsWith("pr-shepherd") ? replacement : `pr-shepherd ${replacement}`} instead.\n`);
+}
+async function handleApply(args) {
+    const action = args[0];
+    switch (action) {
+        case "review":
+            await handleResolve(args.slice(1));
+            return;
+        case "files":
+            await handleMarkFilesAsViewed(args.slice(1));
+            return;
+        case "journal":
+            await handleJournal(args.slice(1));
+            return;
+        default:
+            process.stderr.write(`Unknown apply action: ${action ?? "(none)"}\n`);
+            process.stderr.write(`${USAGE.apply}\n`);
+            process.exitCode = EXIT.USAGE;
+    }
+}
+async function handleAdmin(args) {
+    switch (args[0]) {
+        case "clean":
+            await handleClean(args.slice(1));
+            return;
+        default:
+            process.stderr.write(`Unknown admin command: ${args[0] ?? "(none)"}\n`);
+            process.stderr.write(`${USAGE.admin}\n`);
+            process.exitCode = EXIT.USAGE;
+    }
+}
 function readVersion() {
     const pkgUrl = new URL("../package.json", import.meta.url);
     const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
@@ -88,8 +145,8 @@ function readVersion() {
 // ---------------------------------------------------------------------------
 // Subcommand handlers
 // ---------------------------------------------------------------------------
-async function handleLogFile(args) {
-    if (maybePrintHelp(args, "log-file"))
+async function handleLogFile(args, usageKey = "log-file") {
+    if (maybePrintHelp(args, usageKey))
         return;
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {
@@ -102,10 +159,10 @@ async function handleLogFile(args) {
     }
     catch (e) {
         process.stderr.write(`pr-shepherd: log-file: ${String(e)}\n`);
-        process.exitCode = 1;
+        process.exitCode = errorToExitCode(e);
     }
 }
-async function handleResolve(args) {
+async function handleResolve(args, command = "apply review") {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
     const replyThreadIds = parseList(getFlag(extra, "--reply-thread-ids"));
@@ -119,8 +176,8 @@ async function handleResolve(args) {
     if (rejectPrrcMinimizeIds(minimizeCommentIds).length > 0)
         return;
     if (hasFlag(extra, "--fetch")) {
-        process.stderr.write("pr-shepherd: resolve: --fetch has been removed; run pr-shepherd iterate or poll to fetch the next action.\n");
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: ${command}: --fetch has been removed; run pr-shepherd iterate to fetch the next action.\n`);
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const hasAction = resolveThreadIds.length > 0 ||
@@ -128,8 +185,8 @@ async function handleResolve(args) {
         minimizeCommentIds.length > 0 ||
         dismissReviewIds.length > 0;
     if (!hasAction) {
-        process.stderr.write("pr-shepherd: resolve: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n");
-        process.exitCode = 1;
+        process.stderr.write(`pr-shepherd: ${command}: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n`);
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const result = await runResolveMutate({

package/bin/commands/check-annotations.d.mts

@@ -0,0 +1,5 @@
+import type { CheckAnnotation, TriagedCheck } from "../types.mts";
+export declare function attachUnseenCheckAnnotations(checks: TriagedCheck[], seenMap: Map<string, {
+    seenAt: number;
+}>, prNumber: number): Promise<TriagedCheck[]>;
+export declare function annotationMarkerBody(a: CheckAnnotation): string;

package/bin/commands/check-status.d.mts

@@ -0,0 +1,3 @@
+import type { MergeStatusResult, ShepherdStatus } from "../types.mts";
+import type { CiVerdict } from "../checks/classify.mts";
+export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number): ShepherdStatus;