@wardby/cli 0.6.0 → 0.8.0

package/dist/providers/review-host/patch-pages.js

@@ -0,0 +1,176 @@
+/**
+ * repo_pr_read's diff pages: which files get the patch budget first (code before docs, help,
+ * lockfiles, generated files and fixtures), how a page is filled from a cursor, and the cursor
+ * itself. Shared by every review host so paging behaves the same on GitHub and local repositories.
+ */
+import { PatchCursorError } from "./types.js";
+const LOCKFILES = new Set([
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "bun.lockb",
+    "poetry.lock",
+    "uv.lock",
+    "Pipfile.lock",
+    "Cargo.lock",
+    "go.sum",
+    "Gemfile.lock",
+    "composer.lock",
+    "mix.lock",
+    "pubspec.lock",
+]);
+const OTHER_EXTENSIONS = /\.(md|mdx|rst|adoc|txt|snap|svg|png|jpe?g|gif|webp|ico|pdf|lock)$/i;
+// docs/ and help/ are the repository's own documentation folders (root only); the rest can be anywhere.
+const OTHER_DIRECTORY = /^(docs?|help)\/|(^|\/)(generated|__generated__|dist|vendor|fixtures|__fixtures__|__snapshots__|testdata)\//i;
+const MINIFIED = /\.min\.(js|css)$/i;
+/** The longest patchCursor this module issues or accepts; callers use it as the tool schema's maximum. */
+export const MAX_PATCH_CURSOR_CHARS = 4000;
+/** "code" (source, tests, config, migrations) is filled first; "other" is everything a review can skim. */
+export function reviewGroup(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    if (/^requirements.*\.txt$/i.test(base) || base === "CMakeLists.txt")
+        return "code";
+    if (LOCKFILES.has(base) || OTHER_EXTENSIONS.test(base) || MINIFIED.test(base) || OTHER_DIRECTORY.test(path))
+        return "other";
+    return "code";
+}
+/** Code first; the host's order within each group (stable). */
+export function reviewOrder(files) {
+    return [
+        ...files.filter((f) => reviewGroup(f.filename) === "code"),
+        ...files.filter((f) => reviewGroup(f.filename) === "other"),
+    ];
+}
+const CURSOR = /^v1\.([0-9a-f]{40})\.([0-9a-f]{40}|-)\.(\d{1,6})\.(\d{1,9})\.(-|\d{1,6}(?:,\d{1,6})*)$/;
+function encodeCursor(headSha, comparedFrom, pos) {
+    const u = pos.unavailable.length ? pos.unavailable.join(",") : "-";
+    return `v1.${headSha}.${comparedFrom ?? "-"}.${pos.fileIndex}.${pos.offset}.${u}`;
+}
+function parseCursor(cursor, headSha, comparedFrom, fileCount) {
+    const m = cursor.length <= MAX_PATCH_CURSOR_CHARS ? CURSOR.exec(cursor) : null;
+    if (!m)
+        throw new PatchCursorError("malformed");
+    if (m[1] !== headSha || m[2] !== (comparedFrom ?? "-"))
+        throw new PatchCursorError("stale");
+    const pos = {
+        fileIndex: Number(m[3]),
+        offset: Number(m[4]),
+        unavailable: m[5] === "-" ? [] : m[5].split(",").map(Number),
+    };
+    if (pos.fileIndex > fileCount)
+        throw new PatchCursorError("malformed");
+    let previous = -1;
+    for (const index of pos.unavailable) {
+        if (index <= previous || index >= pos.fileIndex)
+            throw new PatchCursorError("malformed");
+        previous = index;
+    }
+    return pos;
+}
+/**
+ * The longest prefix of `text` within `max` characters that ends at a line break. With no break
+ * in range, a single longer line is cut at `max` when `hardCut`, else nothing is returned.
+ */
+function cutAtLine(text, max, hardCut) {
+    if (text.length <= max)
+        return text;
+    const cut = text.lastIndexOf("\n", max - 1);
+    if (cut >= 0)
+        return text.slice(0, cut + 1);
+    return hardCut ? text.slice(0, max) : "";
+}
+/**
+ * One page of patches: every file in review order, with patch content for the files from the
+ * cursor on until `budget` characters are used. `load` is called only for files on this page
+ * (undefined: the host has no patch, which is unavailable when the file has changes).
+ */
+export async function pagePatches(sources, opts, load) {
+    const ordered = reviewOrder(sources);
+    const start = opts.cursor
+        ? parseCursor(opts.cursor, opts.headSha, opts.comparedFrom, ordered.length)
+        : { fileIndex: 0, offset: 0, unavailable: [] };
+    const earlierUnavailable = new Set(start.unavailable);
+    const unavailable = [...start.unavailable];
+    let budget = opts.budget;
+    let next = null;
+    const files = [];
+    let pageHasCode = false;
+    for (const [index, source] of ordered.entries()) {
+        const { changes, ...view } = source;
+        const out = (patchStatus, patch = "", part) => ({
+            ...view,
+            patch,
+            patchStatus,
+            patchTruncated: patchStatus === "later_page" || patchStatus === "unavailable" || (part?.continues ?? false),
+            ...(part ? { patchOffset: part.offset, patchContinues: part.continues } : {}),
+        });
+        if (index < start.fileIndex) {
+            files.push(out(changes === 0 ? "empty" : earlierUnavailable.has(index) ? "unavailable" : "earlier_page"));
+            continue;
+        }
+        if (next) {
+            files.push(out(changes === 0 ? "empty" : "later_page"));
+            continue;
+        }
+        // A page that carries code ends where the docs, lockfiles and generated files begin, so a
+        // reviewer can stop paging there without that text sitting in its context.
+        if (pageHasCode && changes > 0 && reviewGroup(source.filename) === "other") {
+            files.push(out("later_page"));
+            next = { fileIndex: index, offset: 0 };
+            continue;
+        }
+        const patch = await load(source);
+        const offset = index === start.fileIndex ? start.offset : 0;
+        if (patch === undefined || patch === "") {
+            if (offset > 0)
+                throw new PatchCursorError("malformed");
+            if (changes === 0) {
+                files.push(out("empty"));
+            }
+            else {
+                files.push(out("unavailable"));
+                unavailable.push(index);
+            }
+            continue;
+        }
+        // A cursor never points at the end: the part that reaches it does not continue.
+        if (offset >= patch.length && offset > 0)
+            throw new PatchCursorError("malformed");
+        const rest = patch.slice(offset);
+        if (reviewGroup(source.filename) === "code")
+            pageHasCode = true;
+        if (rest.length <= budget) {
+            files.push(offset === 0 ? out("complete", rest) : out("partial", rest, { offset, continues: false }));
+            budget -= rest.length;
+            if (budget <= 0 && index + 1 < ordered.length)
+                next = { fileIndex: index + 1, offset: 0 };
+            continue;
+        }
+        // A single line longer than the whole budget is cut only when nothing else is on the page;
+        // otherwise the file waits for the next page.
+        const firstContent = !files.some((f) => f.patchStatus === "complete" || f.patchStatus === "partial");
+        const part = budget > 0 ? cutAtLine(rest, budget, firstContent) : "";
+        if (part.length === 0) {
+            files.push(out("later_page"));
+            next = { fileIndex: index, offset };
+            continue;
+        }
+        files.push(out("partial", part, { offset, continues: true }));
+        next = { fileIndex: index, offset: offset + part.length };
+    }
+    const truncatedFiles = files.filter((f) => f.patchTruncated).map((f) => f.filename);
+    const remainingPatchFiles = files.filter((f) => f.patchStatus === "later_page" || (f.patchStatus === "partial" && f.patchContinues)).length;
+    return {
+        files,
+        truncatedFiles,
+        remainingPatchFiles,
+        nextPatchCursor: next
+            ? encodeCursor(opts.headSha, opts.comparedFrom, {
+                ...next,
+                unavailable: unavailable.filter((i) => i < next.fileIndex),
+            })
+            : null,
+        patchesComplete: next === null && unavailable.length === 0,
+    };
+}

package/dist/providers/review-host/review-format.d.ts

@@ -1,9 +1,26 @@
 import type { CheckConclusion, InlineComment, ReviewVerdict } from "./types.js";
 /** Agent ids are cuids; anything else could break out of the HTML comment. */
 export declare const SAFE_AGENT_MARKER: RegExp;
-export declare function reviewMarker(agentMarker: string, headSha: string): string;
+/**
+ * `coveredSha`: the latest head this agent reviewed after reading every file. A marker without
+ * it (an older one included) means none.
+ */
+export declare function reviewMarker(agentMarker: string, headSha: string, coveredSha?: string | null): string;
+/**
+ * The review marker counts only at the very start of a body, where renderSummaryComment writes it:
+ * anywhere else it is text someone else wrote (model text the App posted, for one).
+ */
 export declare function hasReviewMarker(body: string, agentMarker: string): boolean;
 export declare function parseReviewMarker(body: string, agentMarker: string): string | null;
+/** The marker's covered head; null for a marker without one. */
+export declare function parseCoveredMarker(body: string, agentMarker: string): string | null;
+/**
+ * Model-written text the App posts, with each opener of a wardby marker escaped (`<!--`, shown
+ * as text), so no wardby marker can come from it. Any other `<!--` (in a code block or a
+ * ```suggestion, say) is left as written. One pass is enough: the replacement adds no `<` and no
+ * marker name, so it can never complete a new opener. wardby adds its own markers after this.
+ */
+export declare function escapeHtmlComments(text: string): string;
 export declare function verdictConclusion(verdict: ReviewVerdict): CheckConclusion;
 /** Tags an inline comment with the agent that wrote it, so only that agent resolves its thread. */
 export declare function findingMarker(agentMarker: string): string;
@@ -12,6 +29,7 @@ export declare function renderInlineComment(comment: InlineComment, agentMarker:
 export declare function renderSummaryComment(input: {
     agentMarker: string;
     headSha: string;
+    coveredSha?: string | null;
     verdict: ReviewVerdict;
     summary: string;
     body: string;

package/dist/providers/review-host/review-format.js

@@ -6,20 +6,51 @@ function assertMarker(agentMarker) {
     if (!SAFE_AGENT_MARKER.test(agentMarker))
         throw new Error("review_marker_invalid");
 }
-export function reviewMarker(agentMarker, headSha) {
+/**
+ * `coveredSha`: the latest head this agent reviewed after reading every file. A marker without
+ * it (an older one included) means none.
+ */
+export function reviewMarker(agentMarker, headSha, coveredSha) {
     assertMarker(agentMarker);
     if (!SAFE_SHA.test(headSha))
         throw new Error("review_marker_invalid");
-    return `${MARKER_PREFIX}${agentMarker} sha=${headSha} -->`;
+    if (coveredSha && !SAFE_SHA.test(coveredSha))
+        throw new Error("review_marker_invalid");
+    return `${MARKER_PREFIX}${agentMarker} sha=${headSha}${coveredSha ? ` covered=${coveredSha}` : ""} -->`;
 }
+/**
+ * The review marker counts only at the very start of a body, where renderSummaryComment writes it:
+ * anywhere else it is text someone else wrote (model text the App posted, for one).
+ */
 export function hasReviewMarker(body, agentMarker) {
     assertMarker(agentMarker);
-    return body.includes(`${MARKER_PREFIX}${agentMarker} sha=`);
+    return body.startsWith(`${MARKER_PREFIX}${agentMarker} sha=`);
 }
-export function parseReviewMarker(body, agentMarker) {
+function matchReviewMarker(body, agentMarker) {
     assertMarker(agentMarker);
-    const match = new RegExp(`${MARKER_PREFIX}${agentMarker} sha=([0-9a-f]{40}) -->`).exec(body);
-    return match ? match[1] : null;
+    return new RegExp(`^${MARKER_PREFIX}${agentMarker} sha=([0-9a-f]{40})(?: covered=([0-9a-f]{40}))? -->`).exec(body);
+}
+export function parseReviewMarker(body, agentMarker) {
+    return matchReviewMarker(body, agentMarker)?.[1] ?? null;
+}
+/** The marker's covered head; null for a marker without one. */
+export function parseCoveredMarker(body, agentMarker) {
+    return matchReviewMarker(body, agentMarker)?.[2] ?? null;
+}
+/**
+ * An HTML comment opener that starts a wardby marker: every marker wardby writes or ever wrote
+ * names `wardby…` (wardby:review/finding, wardby-status/description/latest/related) or the legacy
+ * `reevo-run…`. Case-insensitive, wider than any parse of them.
+ */
+const MARKER_OPENER = /<!--(?=\s*(?:wardby|reevo-run))/gi;
+/**
+ * Model-written text the App posts, with each opener of a wardby marker escaped (`&lt;!--`, shown
+ * as text), so no wardby marker can come from it. Any other `<!--` (in a code block or a
+ * ```suggestion, say) is left as written. One pass is enough: the replacement adds no `<` and no
+ * marker name, so it can never complete a new opener. wardby adds its own markers after this.
+ */
+export function escapeHtmlComments(text) {
+    return text.replace(MARKER_OPENER, "&lt;!--");
 }
 export function verdictConclusion(verdict) {
     if (verdict === "APPROVE")
@@ -47,7 +78,7 @@ export function renderInlineComment(comment, agentMarker) {
 }
 export function renderSummaryComment(input) {
     const sections = [
-        reviewMarker(input.agentMarker, input.headSha),
+        reviewMarker(input.agentMarker, input.headSha, input.coveredSha),
         `${BADGES[input.verdict]} — reviewed \`${input.headSha.slice(0, 7)}\``,
         input.summary,
         input.body,

package/dist/providers/review-host/types.d.ts

@@ -1,17 +1,29 @@
 /**
  * Host-neutral code-review surface for native agents. GitHub (./github.ts) and
- * local git repositories (./local.ts) implement it; Bitbucket Cloud is anticipated. Every method
+ * local git repositories (./local.ts) implement it, and registered host providers add their own. Every method
  * takes the repository and mints its own least-permission credential — no
  * method accepts a token or a permission. See
  * docs/private/2026-09-25-code-review-host-design.md §5.
  */
-export type ReviewHostProvider = "github" | "local";
-export declare const REVIEW_HOST_PROVIDERS: readonly ReviewHostProvider[];
+/** Compiled-in hosts. Registered host providers add their own names at runtime. */
+export type BuiltInHostProvider = "github" | "local";
+export type ReviewHostProvider = BuiltInHostProvider | (string & {});
+export declare const REVIEW_HOST_PROVIDERS: readonly BuiltInHostProvider[];
 /** Providers with host user accounts to link (link_host_account); a local repository has none. */
-export declare const HOST_ACCOUNT_PROVIDERS: readonly ReviewHostProvider[];
+export declare const HOST_ACCOUNT_PROVIDERS: readonly BuiltInHostProvider[];
 export type ReviewVerdict = "APPROVE" | "CHANGES_REQUESTED" | "COMMENT";
 export type CheckConclusion = "success" | "failure" | "neutral";
 export type CommentSide = "LEFT" | "RIGHT";
+/**
+ * Where a file's patch is in a repo_pr_read result:
+ * - complete: the whole patch is in this result;
+ * - partial: one part, starting at patchOffset; the rest comes with nextPatchCursor;
+ * - later_page: not in this result; call again with nextPatchCursor;
+ * - earlier_page: delivered by an earlier call of the same cursor chain;
+ * - unavailable: the host has no patch for it (too large, binary): read it with repo_read_file;
+ * - empty: nothing to show (no line changes, a pure rename).
+ */
+export type PatchStatus = "complete" | "partial" | "later_page" | "earlier_page" | "unavailable" | "empty";
 export interface PullRequestFileView {
     filename: string;
     status: string;
@@ -19,7 +31,18 @@ export interface PullRequestFileView {
     deletions: number;
     previousFilename?: string;
     patch: string;
+    /** True for later_page, unavailable, and a partial part that the next page continues. */
     patchTruncated: boolean;
+    patchStatus: PatchStatus;
+    /** Where this part starts in the file's patch; only on partial. */
+    patchOffset?: number;
+    /** Only on partial: true when the next page continues this file, false when this part is its last. */
+    patchContinues?: boolean;
+}
+/** A patchCursor that is not one this deployment issued, or one for a head or compare that has moved on. */
+export declare class PatchCursorError extends Error {
+    readonly reason: "malformed" | "stale";
+    constructor(reason: "malformed" | "stale");
 }
 /** One of this agent's own review threads that is still unresolved. */
 export interface ReviewThreadView {
@@ -71,6 +94,12 @@ export interface PullRequestView {
     htmlUrl: string;
     /** Head sha recorded in this agent's summary comment, if it reviewed before. */
     lastReviewedSha: string | null;
+    /**
+     * The latest head this agent reviewed after reading every file (a whole, uncut list of the
+     * pull request or a delta from an earlier covered head, every source/test/config file read),
+     * whatever the verdict. The only safe sinceSha for a re-review that may APPROVE.
+     */
+    lastCoveredSha: string | null;
     /** Set when `files` is the compare of `comparedFrom...headSha` rather than the whole PR. */
     comparedFrom: string | null;
     /**
@@ -80,10 +109,26 @@ export interface PullRequestView {
      */
     baseMergedSince: boolean;
     files: PullRequestFileView[];
+    /**
+     * False when `files` is cut: the host's listing stopped at its upper bound before every
+     * changed file (on GitHub, also a compare at its 300-file limit). repo_publish_review then
+     * refuses an APPROVE of this head with file_list_truncated.
+     */
+    fileListComplete: boolean;
+    /** No patch is left to page through and none is unavailable: with earlier pages, every patch was delivered. */
+    patchesComplete: boolean;
+    /** Files whose patch is not (fully) delivered yet: later_page, unavailable, or a partial part the next page continues; in review order. */
+    truncatedFiles: string[];
+    /** Pass as repo_pr_read's patchCursor for the next page; null when nothing is left to page. */
+    nextPatchCursor: string | null;
+    /** Estimate of files with patch content still to come after this page (a partial file counts once); a later_page file may turn out empty or unavailable once loaded. */
+    remainingPatchFiles: number;
     /** This agent's own unresolved review threads on the PR (the first 100 threads are searched). */
     openThreads: ReviewThreadView[];
     /** CI on headSha (check runs and commit statuses, minus wardby's own); absent on hosts that can't read CI. */
     ci?: CiView;
+    /** Only on a wardby pull request with a pending proposal in its description comment. */
+    descriptionProposal?: DescriptionProposalView;
 }
 export interface PullRequestHead {
     headSha: string;
@@ -120,6 +165,59 @@ export type FileReadResult = {
     kind: "not_found";
     path: string;
 };
+/** One issue comment; author-written text, untrusted. */
+export interface IssueCommentView {
+    author: string | null;
+    body: string;
+    createdAt: string;
+    /** The body was cut at the per-comment cap. */
+    truncated: boolean;
+}
+/** An issue as repo_issue_read shows it. Title, body, labels, and comments are untrusted text. */
+export interface IssueView {
+    number: number;
+    title: string;
+    state: "open" | "closed";
+    body: string;
+    bodyTruncated: boolean;
+    labels: string[];
+    author: string | null;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+    /** The most recent comments, oldest first. */
+    comments: IssueCommentView[];
+    /** All comments on the issue, including any left out. */
+    totalComments: number;
+    /** Anything was cut: the body, a comment, or older comments left out. */
+    truncated: boolean;
+}
+/**
+ * wardby's proposed description on a pull request whose description wardby
+ * couldn't confirm as its own (from its description comment). `current`: the
+ * proposal is for the head being read; `not_for_this_head`: it isn't yet;
+ * `unavailable`: the comments couldn't be read.
+ */
+export type DescriptionProposalView = {
+    state: "current";
+    forHead: string;
+    runId?: string;
+    text: string;
+    truncated: boolean;
+    note: string;
+} | {
+    state: "not_for_this_head" | "unavailable";
+    note: string;
+};
+export type IssueReadResult = ({
+    kind: "issue";
+} & IssueView) | {
+    kind: "pull_request";
+    number: number;
+} | {
+    kind: "not_found";
+    number: number;
+};
 export interface FileListView {
     ref: string;
     count: number;
@@ -157,6 +255,11 @@ export interface PublishReviewInput {
      * unresolved threads on this PR are resolved; any other id is skipped.
      */
     resolveThreadIds?: string[];
+    /**
+     * headSha when this review read every file of it (see PullRequestView.lastCoveredSha); null or
+     * absent otherwise, and the host keeps the earlier covered head.
+     */
+    coveredSha?: string | null;
 }
 export type PublishReviewResult = {
     published: true;
@@ -225,6 +328,7 @@ export type UpsertNamedCheckInput = {
  * collaborator permission onto these directly; GitLab would map reporter ->
  * read, developer -> write, maintainer -> maintain, owner -> admin.
  */
+export type AcknowledgeOutcome = "picked_up" | "refused";
 export type HostPermission = "none" | "read" | "triage" | "write" | "maintain" | "admin";
 export declare const HOST_PERMISSION_RANK: Readonly<Record<HostPermission, number>>;
 /** A host user, by its immutable numeric id (as text) and its current login. */
@@ -250,6 +354,7 @@ export interface CodeReviewHost {
         sinceSha?: string;
         maxPatchChars: number;
         agentMarker: string;
+        patchCursor?: string;
     }): Promise<PullRequestView>;
     pullRequestHead(repository: string, prNumber: number): Promise<PullRequestHead>;
     /** CI on one commit, excluding wardby's own checks. Never throws. Hosts that can't say leave it out. */
@@ -274,6 +379,11 @@ export interface CodeReviewHost {
         maxLines: number;
     }): Promise<FileReadResult>;
     listFiles(repository: string, ref: string | undefined, pathPrefix?: string): Promise<FileListView>;
+    /** An issue and its most recent comments, read-only. Hosts without issues (a local repository) leave it out. */
+    /** `comments: false` reads the issue alone (title, body, labels), without its comments. */
+    readIssue?(repository: string, number: number, opts?: {
+        comments?: boolean;
+    }): Promise<IssueReadResult>;
     publishReview(repository: string, input: PublishReviewInput): Promise<PublishReviewResult>;
     /** `id` identifies the new comment for editComment; a reply is an "inline" comment, anything else "conversation". */
     comment(repository: string, input: CommentInput): Promise<{
@@ -282,8 +392,12 @@ export interface CodeReviewHost {
     }>;
     /** Replaces the body of a comment the App wrote. */
     editComment(repository: string, input: EditCommentInput): Promise<void>;
-    /** Marks a comment as picked up (GitHub: a 👀 reaction); a host without reactions may do nothing. */
-    acknowledge(repository: string, target: CommentRef): Promise<void>;
+    /**
+     * Marks a comment as picked up (GitHub: a 👀 reaction), or as refused (😕)
+     * when its author can see the repository but lacks the access to start a
+     * run. A host without reactions may do nothing.
+     */
+    acknowledge(repository: string, target: CommentRef, outcome?: AcknowledgeOutcome): Promise<void>;
     startCheck(repository: string, input: StartCheckInput): Promise<{
         checkId: string;
     }>;
@@ -297,6 +411,22 @@ export interface CodeReviewHost {
      * post checks (e.g. a local repository) leave this out.
      */
     upsertNamedCheck?(repository: string, input: UpsertNamedCheckInput): Promise<void>;
+    /**
+     * This App's newest check run per name on one commit (names not found are absent).
+     * At most 10 names. Hosts that can't say leave it out.
+     */
+    readOwnChecks?(repository: string, headSha: string, names: string[]): Promise<Map<string, OwnCheckView>>;
+    /**
+     * Marks a draft pull request this App authored ready for review, only while it is
+     * open, a draft, at `expectedHeadSha`, and carrying `expectedMarkerRunId` in its
+     * description's run marker (mirrors replaceRelatedSection's expectedMarkerRunId).
+     * "skipped" covers every refusal.
+     */
+    markReadyForReview?(repository: string, prNumber: number, expectedHeadSha: string, expectedMarkerRunId: string): Promise<"marked" | "skipped">;
+}
+export interface OwnCheckView {
+    status: string;
+    conclusion: string | null;
 }
 export type ReviewHostErrorCode = "host_not_installed" | "host_permission_missing" | "host_api_error" | "host_invalid_response";
 export declare class ReviewHostError extends Error {
@@ -384,6 +514,10 @@ export type HostEvent = {
     author: string;
     /** The author's immutable numeric host user id, as text; their permission is checked by it. */
     authorId: string;
+    /** GitHub's `author_association` for the author; a hint only, never a permission. */
+    authorAssociation?: string;
+    /** Whether the repository is private, when the payload says. */
+    repositoryPrivate?: boolean;
     /** The issue or PR the mention is on, when the payload carries it. */
     subject?: {
         title: string;

package/dist/providers/review-host/types.js

@@ -1,6 +1,6 @@
 /**
  * Host-neutral code-review surface for native agents. GitHub (./github.ts) and
- * local git repositories (./local.ts) implement it; Bitbucket Cloud is anticipated. Every method
+ * local git repositories (./local.ts) implement it, and registered host providers add their own. Every method
  * takes the repository and mints its own least-permission credential — no
  * method accepts a token or a permission. See
  * docs/private/2026-09-25-code-review-host-design.md §5.
@@ -8,6 +8,14 @@
 export const REVIEW_HOST_PROVIDERS = ["github", "local"];
 /** Providers with host user accounts to link (link_host_account); a local repository has none. */
 export const HOST_ACCOUNT_PROVIDERS = ["github"];
+/** A patchCursor that is not one this deployment issued, or one for a head or compare that has moved on. */
+export class PatchCursorError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason === "stale" ? "patch_cursor_stale" : "patch_cursor_malformed");
+        this.reason = reason;
+    }
+}
 export const HOST_PERMISSION_RANK = {
     none: 0,
     read: 1,

package/dist/providers/storage/gcs.d.ts

@@ -0,0 +1,63 @@
+import type { Readable, Writable } from "node:stream";
+import { type BlobInfo, type BlobStore } from "./types.js";
+/** The slice of a GCS File the adapter uses (the real `File` satisfies it; tests supply an in-memory fake). */
+export interface GcsFileLike {
+    createWriteStream(options?: {
+        resumable?: boolean;
+        contentType?: string;
+    }): Writable;
+    createReadStream(): Readable;
+    getMetadata(): Promise<[
+        {
+            size?: string | number;
+            updated?: string;
+            metadata?: Record<string, unknown>;
+        },
+        ...unknown[]
+    ]>;
+    save(data: Buffer, options?: {
+        resumable?: boolean;
+        contentType?: string;
+    }): Promise<unknown>;
+    delete(options?: {
+        ignoreNotFound?: boolean;
+    }): Promise<unknown>;
+    getSignedUrl(config: {
+        version: "v4";
+        action: "read" | "write";
+        expires: number;
+    }): Promise<[string]>;
+}
+export interface GcsBucketLike {
+    file(name: string): GcsFileLike;
+}
+/**
+ * Google Cloud Storage blob store. Credentials come from Application Default Credentials (Workload Identity on
+ * GKE); no key files. Uploads are single-request (non-resumable), so an upload that is destroyed before it
+ * finishes never creates or replaces an object.
+ */
+export declare class GcsBlobStore implements BlobStore {
+    private readonly bucket;
+    constructor(bucket: GcsBucketLike);
+    /** Build a store over `bucketName` using Application Default Credentials. */
+    static forBucket(bucketName: string): GcsBlobStore;
+    private file;
+    put(key: string, body: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<void>;
+    signedUrl(key: string, opts: {
+        expiresSec: number;
+        method: "GET" | "PUT";
+    }): Promise<string>;
+    putStream(key: string, body: NodeJS.ReadableStream, opts?: {
+        contentType?: string;
+        maxBytes?: number;
+    }): Promise<{
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    getStream(key: string): Promise<NodeJS.ReadableStream>;
+    head(key: string): Promise<BlobInfo | null>;
+}

package/dist/providers/storage/gcs.js

@@ -0,0 +1,69 @@
+import { pipeline } from "node:stream/promises";
+import { Storage } from "@google-cloud/storage";
+import { collectStream, createByteMeter } from "./meter.js";
+import { assertValidBlobKey, BlobStoreError } from "./types.js";
+function isNotFound(error) {
+    return error?.code === 404;
+}
+/**
+ * Google Cloud Storage blob store. Credentials come from Application Default Credentials (Workload Identity on
+ * GKE); no key files. Uploads are single-request (non-resumable), so an upload that is destroyed before it
+ * finishes never creates or replaces an object.
+ */
+export class GcsBlobStore {
+    bucket;
+    constructor(bucket) {
+        this.bucket = bucket;
+    }
+    /** Build a store over `bucketName` using Application Default Credentials. */
+    static forBucket(bucketName) {
+        return new GcsBlobStore(new Storage().bucket(bucketName));
+    }
+    file(key) {
+        assertValidBlobKey(key);
+        return this.bucket.file(key);
+    }
+    async put(key, body, opts) {
+        await this.file(key).save(body, { resumable: false, contentType: opts?.contentType });
+    }
+    async get(key) {
+        return collectStream(await this.getStream(key));
+    }
+    async delete(key) {
+        await this.file(key).delete({ ignoreNotFound: true });
+    }
+    async signedUrl(key, opts) {
+        const [url] = await this.file(key).getSignedUrl({
+            version: "v4",
+            action: opts.method === "GET" ? "read" : "write",
+            expires: Date.now() + opts.expiresSec * 1000,
+        });
+        return url;
+    }
+    async putStream(key, body, opts) {
+        const file = this.file(key);
+        const meter = createByteMeter(opts?.maxBytes);
+        // pipeline destroys every stream (including the GCS write stream) on failure, which aborts the HTTP request
+        // before the object is finalized.
+        await pipeline(body, meter.stream, file.createWriteStream({ resumable: false, contentType: opts?.contentType }));
+        return { sizeBytes: meter.size(), sha256: meter.digest() };
+    }
+    async getStream(key) {
+        const file = this.file(key);
+        // createReadStream reports a missing object asynchronously; look first so callers get a typed not_found.
+        if ((await this.head(key)) === null)
+            throw new BlobStoreError("not_found");
+        return file.createReadStream();
+    }
+    async head(key) {
+        try {
+            const [metadata] = await this.file(key).getMetadata();
+            return { sizeBytes: Number(metadata.size ?? 0), updatedAt: new Date(metadata.updated ?? 0) };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    }
+}