@wardby/cli 0.2.0 → 0.3.0

package/dist/providers/memory/postgres.d.ts

@@ -6,7 +6,7 @@
  * schema.prisma). Every other operation goes through the normal Prisma
  * Client since it never touches `contentTsv`.
  */
-import type { PrismaClient } from "@prisma/client";
+import type { PrismaClient } from "#prisma";
 import type { AgentMemorySearchHit, AgentMemoryStore } from "./types.js";
 export type AgentMemoryDb = Pick<PrismaClient, "agentMemory" | "$executeRaw" | "$queryRaw">;
 export declare class PostgresAgentMemory implements AgentMemoryStore {

package/dist/providers/review-host/diff-lines.d.ts

@@ -0,0 +1,16 @@
+import type { InlineComment } from "./types.js";
+/**
+ * The lines a host accepts inline comments on for one file's unified patch:
+ * added and context lines on the RIGHT (new) side, removed and context lines
+ * on the LEFT (old) side. Hosts reject comments anywhere else, which is the
+ * usual way review bots break; callers move those comments into the summary.
+ */
+export declare function commentableLines(patch: string): {
+    right: Set<number>;
+    left: Set<number>;
+};
+/** Splits comments into those the host will accept inline and those that must go in the summary. */
+export declare function partitionComments(comments: readonly InlineComment[], patches: ReadonlyMap<string, string | undefined>): {
+    inline: InlineComment[];
+    outside: InlineComment[];
+};

package/dist/providers/review-host/diff-lines.js

@@ -0,0 +1,59 @@
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+/**
+ * The lines a host accepts inline comments on for one file's unified patch:
+ * added and context lines on the RIGHT (new) side, removed and context lines
+ * on the LEFT (old) side. Hosts reject comments anywhere else, which is the
+ * usual way review bots break; callers move those comments into the summary.
+ */
+export function commentableLines(patch) {
+    const right = new Set();
+    const left = new Set();
+    let oldLine = 0;
+    let newLine = 0;
+    let inHunk = false;
+    for (const raw of patch.split("\n")) {
+        if (!raw)
+            continue; // Skip empty segments from trailing newlines
+        const header = HUNK_HEADER.exec(raw);
+        if (header) {
+            oldLine = Number(header[1]);
+            newLine = Number(header[2]);
+            inHunk = true;
+            continue;
+        }
+        if (!inHunk || raw.startsWith("\\"))
+            continue;
+        if (raw.startsWith("+")) {
+            right.add(newLine++);
+        }
+        else if (raw.startsWith("-")) {
+            left.add(oldLine++);
+        }
+        else {
+            right.add(newLine++);
+            left.add(oldLine++);
+        }
+    }
+    return { right, left };
+}
+/** Splits comments into those the host will accept inline and those that must go in the summary. */
+export function partitionComments(comments, patches) {
+    const cache = new Map();
+    const inline = [];
+    const outside = [];
+    for (const comment of comments) {
+        const patch = patches.get(comment.path);
+        if (!patch) {
+            outside.push(comment);
+            continue;
+        }
+        let lines = cache.get(comment.path);
+        if (!lines) {
+            lines = commentableLines(patch);
+            cache.set(comment.path, lines);
+        }
+        const allowed = comment.side === "LEFT" ? lines.left : lines.right;
+        (allowed.has(comment.line) ? inline : outside).push(comment);
+    }
+    return { inline, outside };
+}

package/dist/providers/review-host/github-events.d.ts

@@ -0,0 +1,6 @@
+import type { HostEvent } from "./types.js";
+export declare function verifyGitHubSignature(rawBody: string, header: string | undefined, secret: string): boolean;
+export declare function normalizeGitHubEvent(eventName: string, payload: unknown, app: {
+    id: number;
+    slug: string;
+}): HostEvent | null;

package/dist/providers/review-host/github-events.js

@@ -0,0 +1,180 @@
+/**
+ * GitHub App webhook → host-neutral HostEvent. Pure: no I/O. Signature
+ * verification is over the exact request body text GitHub signed.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { normalizeGitHubRepository } from "../../coding/protocol.js";
+const PR_ACTIONS = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);
+const TRUSTED_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+const SAFE_SHA = /^[0-9a-f]{40}$/;
+/** Mirrors the runId shape validated in providers/vcs (github.ts, git.ts). */
+const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** The hidden marker a coding run writes at the top of every PR it opens (providers/vcs/github.ts); legacy prefix too. */
+const RUN_MARKER = /^\s*<!-- (?:wardby|reevo-run):(\S+) -->/;
+export function verifyGitHubSignature(rawBody, header, secret) {
+    if (!header || !/^sha256=[0-9a-f]{64}$/.test(header))
+        return false;
+    const expected = createHmac("sha256", secret).update(rawBody, "utf8").digest();
+    const presented = Buffer.from(header.slice("sha256=".length), "hex");
+    return presented.length === expected.length && timingSafeEqual(presented, expected);
+}
+const obj = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+const int = (value) => Number.isSafeInteger(value) && value > 0 ? value : null;
+function repositoryOf(payload) {
+    const name = obj(payload.repository)?.full_name;
+    if (typeof name !== "string")
+        return null;
+    try {
+        return normalizeGitHubRepository(name);
+    }
+    catch {
+        return null;
+    }
+}
+function mentions(body, slug) {
+    const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^\\w@.-])@${escaped}(?![\\w-])`, "i").test(body);
+}
+const text = (value) => (typeof value === "string" ? value : "");
+function subjectOf(item) {
+    return typeof item?.title === "string" ? { title: item.title, body: text(item.body) } : undefined;
+}
+/**
+ * The run that opened this PR. Only a PR the App itself authored counts:
+ * anyone can write the marker into their own PR's description. Only an open
+ * PR counts too: a merged or closed PR's branch is stale (a squash merge leaves
+ * its commits behind), so a follow-up there starts from the default branch.
+ */
+function priorRunIdOf(pr, slug) {
+    if (pr?.state !== "open")
+        return undefined;
+    const author = obj(pr?.user);
+    if (author?.type !== "Bot" || typeof author.login !== "string")
+        return undefined;
+    if (author.login.toLowerCase() !== `${slug}[bot]`.toLowerCase())
+        return undefined;
+    const id = RUN_MARKER.exec(text(pr?.body))?.[1];
+    return id && SAFE_RUN_ID.test(id) ? id : undefined;
+}
+/**
+ * A cheap pre-filter only: author_association is not a permission (MEMBER is
+ * any org member, COLLABORATOR includes read and triage). The real gate is the
+ * author's live repository permission, checked by id in core/host-events.ts.
+ */
+function trustedHuman(association, user) {
+    return (typeof association === "string" &&
+        TRUSTED_ASSOCIATIONS.has(association) &&
+        user?.type === "User" &&
+        typeof user.login === "string" &&
+        int(user.id) !== null);
+}
+export function normalizeGitHubEvent(eventName, payload, app) {
+    const p = obj(payload);
+    if (!p)
+        return null;
+    const repository = repositoryOf(p);
+    if (!repository)
+        return null;
+    if (eventName === "pull_request") {
+        if (typeof p.action !== "string" || !PR_ACTIONS.has(p.action))
+            return null;
+        const pr = obj(p.pull_request);
+        const head = obj(pr?.head);
+        const prNumber = int(pr?.number);
+        const headSha = head?.sha;
+        if (!prNumber || typeof headSha !== "string" || !SAFE_SHA.test(headSha))
+            return null;
+        const headRepo = obj(head?.repo)?.full_name;
+        const isFork = typeof headRepo !== "string" || headRepo.toLowerCase() !== repository;
+        return { kind: "pr_updated", provider: "github", repository, prNumber, headSha, isFork };
+    }
+    if (eventName === "check_run") {
+        if (p.action !== "rerequested")
+            return null;
+        const check = obj(p.check_run);
+        if (int(obj(check?.app)?.id) !== app.id)
+            return null;
+        const prNumber = int(obj(Array.isArray(check?.pull_requests) ? check.pull_requests[0] : null)?.number);
+        const headSha = check?.head_sha;
+        const checkName = check?.name;
+        if (!prNumber || typeof headSha !== "string" || !SAFE_SHA.test(headSha) || typeof checkName !== "string")
+            return null;
+        return { kind: "check_rerun", provider: "github", repository, prNumber, headSha, checkName };
+    }
+    if (eventName === "issues") {
+        if (p.action !== "opened" && p.action !== "edited")
+            return null;
+        const issue = obj(p.issue);
+        const number = int(issue?.number);
+        const title = issue?.title;
+        if (!number || typeof title !== "string")
+            return null;
+        const body = text(issue?.body);
+        const user = obj(issue?.user);
+        if (!trustedHuman(issue?.author_association, user))
+            return null;
+        if (!mentions(title, app.slug) && !mentions(body, app.slug))
+            return null;
+        if (p.action === "edited") {
+            // Only the author's own edit, and only one that newly adds the mention — not every later edit.
+            const sender = obj(p.sender);
+            if (sender?.type !== "User" || sender.login !== user.login)
+                return null;
+            const changes = obj(p.changes);
+            const oldTitle = obj(changes?.title)?.from;
+            const oldBody = obj(changes?.body)?.from;
+            if (typeof oldTitle !== "string" && typeof oldBody !== "string")
+                return null;
+            const before = [typeof oldTitle === "string" ? oldTitle : title, typeof oldBody === "string" ? oldBody : body];
+            if (before.some((t) => mentions(t, app.slug)))
+                return null;
+        }
+        return {
+            kind: "mention",
+            provider: "github",
+            repository,
+            number,
+            isPullRequest: obj(issue?.pull_request) !== null,
+            comment: { kind: "subject", id: String(number) },
+            body,
+            author: user.login,
+            authorId: String(user.id),
+            subject: { title, body },
+        };
+    }
+    if (eventName === "issue_comment" || eventName === "pull_request_review_comment") {
+        if (p.action !== "created")
+            return null;
+        const comment = obj(p.comment);
+        const user = obj(comment?.user);
+        const body = comment?.body;
+        const commentId = int(comment?.id);
+        if (typeof body !== "string" || !commentId || !mentions(body, app.slug))
+            return null;
+        if (!trustedHuman(comment?.author_association, user))
+            return null;
+        const isInline = eventName === "pull_request_review_comment";
+        const parent = obj(isInline ? p.pull_request : p.issue);
+        const number = int(parent?.number);
+        if (!number)
+            return null;
+        const isPullRequest = isInline || obj(parent?.pull_request) !== null;
+        const subject = subjectOf(parent);
+        const priorRunId = isPullRequest ? priorRunIdOf(parent, app.slug) : undefined;
+        return {
+            kind: "mention",
+            provider: "github",
+            repository,
+            number,
+            isPullRequest,
+            comment: { kind: isInline ? "inline" : "conversation", id: String(commentId) },
+            ...(isInline ? { replyToReviewCommentId: String(commentId) } : {}),
+            body,
+            author: user.login,
+            authorId: String(user.id),
+            ...(subject ? { subject } : {}),
+            ...(priorRunId ? { priorRunId } : {}),
+        };
+    }
+    return null;
+}

package/dist/providers/review-host/github-user-auth.d.ts

@@ -0,0 +1,38 @@
+import type { GitHubAppClient } from "../vcs/github.js";
+import { type HostUserAuthorizer } from "./types.js";
+type Fetch = typeof globalThis.fetch;
+export interface GitHubUserAuthorizerOptions {
+    /** The App's API client; `GET /user` and the revocation go through its requestJson. */
+    client: Pick<GitHubAppClient, "requestJson">;
+    /** The App's OAuth Client ID (not the numeric App ID). */
+    clientId: string;
+    clientSecret: string;
+    /** Tests only: the web host that serves /login/oauth/*. */
+    webBaseUrl?: string;
+    /** Tests only: the fetch used for the web host. */
+    fetch?: Fetch;
+}
+export declare class GitHubUserAuthorizer implements HostUserAuthorizer {
+    private readonly options;
+    readonly provider: "github";
+    private readonly webBaseUrl;
+    private readonly fetchImpl;
+    constructor(options: GitHubUserAuthorizerOptions);
+    authorizeUrl(input: {
+        state: string;
+        codeChallenge: string;
+        redirectUri: string;
+    }): string;
+    complete(input: {
+        code: string;
+        codeVerifier: string;
+        redirectUri: string;
+    }): Promise<{
+        hostUserId: string;
+        login: string;
+    }>;
+    private exchange;
+    /** DELETE /applications/{client_id}/token (Basic auth with the client credentials). Never throws. */
+    private revoke;
+}
+export {};

package/dist/providers/review-host/github-user-auth.js

@@ -0,0 +1,128 @@
+/**
+ * GitHub App user authorization (the OAuth web flow), used only to learn a
+ * wardby principal's GitHub identity for link_host_account. The user token is
+ * never stored, logged, or returned: `complete` exchanges the code (with the
+ * PKCE verifier and the App's client secret), reads `GET /user`, and revokes
+ * the token immediately, on every path. Repository permission checks use the
+ * App's installation token instead (GitHubReviewHost.repositoryPermission).
+ * See docs/private/2026-09-26-repo-access-authorization-spec-and-plan.md §3.
+ */
+import { logger } from "../../core/logger.js";
+import { ReviewHostError } from "./types.js";
+const log = logger.child({ module: "github-user-auth" });
+const DEFAULT_WEB_BASE_URL = "https://github.com";
+const GITHUB_LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+/** GitHub user-to-server tokens (ghu_…) are opaque; accept a bounded, header-safe shape only. */
+const SAFE_TOKEN = /^[A-Za-z0-9_.-]{20,512}$/;
+const SAFE_ERROR_CODE = /^[a-z_]{1,64}$/;
+export class GitHubUserAuthorizer {
+    options;
+    provider = "github";
+    webBaseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        const web = new URL(options.webBaseUrl ?? DEFAULT_WEB_BASE_URL);
+        if (web.protocol !== "https:" || web.pathname !== "/" || web.search || web.username || web.password) {
+            throw new Error("github_web_base_url_invalid");
+        }
+        this.webBaseUrl = web.origin;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+    }
+    authorizeUrl(input) {
+        const url = new URL("/login/oauth/authorize", this.webBaseUrl);
+        url.search = new URLSearchParams({
+            client_id: this.options.clientId,
+            redirect_uri: input.redirectUri,
+            state: input.state,
+            code_challenge: input.codeChallenge,
+            code_challenge_method: "S256",
+            // The link is for an existing GitHub account, never a new one.
+            allow_signup: "false",
+            // Lets someone signed in to several accounts pick the right one.
+            prompt: "select_account",
+        }).toString();
+        return url.toString();
+    }
+    async complete(input) {
+        const token = await this.exchange(input);
+        try {
+            const response = await this.options.client.requestJson("/user", token);
+            const user = (await response.json());
+            const id = user?.id;
+            const login = user?.login;
+            if (user?.type !== "User" ||
+                !Number.isSafeInteger(id) ||
+                id <= 0 ||
+                typeof login !== "string" ||
+                !GITHUB_LOGIN.test(login)) {
+                throw new ReviewHostError("host_invalid_response", "github_user_invalid");
+            }
+            return { hostUserId: String(id), login };
+        }
+        catch (err) {
+            if (err instanceof ReviewHostError)
+                throw err;
+            const message = err instanceof Error && /^github_[a-z_]+(:\d{3})?/.test(err.message) ? err.message : "";
+            throw new ReviewHostError("host_api_error", message.split(":").slice(0, 2).join(":") || "github_user_failed");
+        }
+        finally {
+            await this.revoke(token);
+        }
+    }
+    async exchange(input) {
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.webBaseUrl}/login/oauth/access_token`, {
+                method: "POST",
+                headers: { accept: "application/json", "content-type": "application/json", "user-agent": "wardby" },
+                body: JSON.stringify({
+                    client_id: this.options.clientId,
+                    client_secret: this.options.clientSecret,
+                    code: input.code,
+                    code_verifier: input.codeVerifier,
+                    redirect_uri: input.redirectUri,
+                }),
+            });
+        }
+        catch {
+            throw new ReviewHostError("host_api_error", "github_oauth_unavailable");
+        }
+        if (response.status !== 200) {
+            throw new ReviewHostError("host_api_error", `github_oauth_exchange_failed:${response.status}`);
+        }
+        let payload = null;
+        try {
+            payload = (await response.json());
+        }
+        catch {
+            // handled below
+        }
+        // GitHub reports a refused exchange (bad or expired code, wrong verifier) as a 200 with `error`.
+        if (payload && typeof payload.error === "string") {
+            const code = SAFE_ERROR_CODE.test(payload.error) ? payload.error : "unknown";
+            throw new ReviewHostError("host_api_error", `github_oauth_exchange_failed:${code}`);
+        }
+        const token = payload?.access_token;
+        if (typeof token !== "string" || !SAFE_TOKEN.test(token)) {
+            throw new ReviewHostError("host_invalid_response", "github_oauth_token_invalid");
+        }
+        return token;
+    }
+    /** DELETE /applications/{client_id}/token (Basic auth with the client credentials). Never throws. */
+    async revoke(token) {
+        const basic = Buffer.from(`${this.options.clientId}:${this.options.clientSecret}`).toString("base64");
+        try {
+            await this.options.client.requestJson(`/applications/${encodeURIComponent(this.options.clientId)}/token`, 
+            // requestJson always sets a bearer; the explicit header below replaces it.
+            "revocation", {
+                method: "DELETE",
+                headers: { authorization: `Basic ${basic}` },
+                body: JSON.stringify({ access_token: token }),
+            }, [204]);
+        }
+        catch (err) {
+            log.warn({ reason: err instanceof Error ? err.message.split(":").slice(0, 2).join(":") : "unknown" }, "could not revoke a GitHub user token; it expires on its own");
+        }
+    }
+}

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

@@ -0,0 +1,57 @@
+/**
+ * GitHub implementation of CodeReviewHost, acting as the wardby GitHub App.
+ * Each method mints its own installation token scoped to one repository and
+ * the narrowest permission set that call needs (GitHubAppClient.withScopedToken),
+ * and revokes it afterwards. See docs/private/2026-09-25-code-review-host-design.md §5.1.
+ */
+import type { GitHubAppClient } from "../vcs/github.js";
+import { ReviewHostError, type CodeReviewHost, type CommentInput, type CommentRef, type CompleteCheckInput, type EditCommentInput, type FileListView, type FileReadResult, type HostPermission, type HostUser, type PublishReviewInput, type PublishReviewResult, type PullRequestHead, type PullRequestView, type StartCheckInput } from "./types.js";
+type Json = Record<string, unknown>;
+/** Maps GitHubAppClient's fixed error messages onto host-neutral codes; keeps the body-free message. */
+export declare function toReviewHostError(err: unknown): ReviewHostError;
+type GraphQl = (query: string, variables: Record<string, unknown>) => Promise<Json>;
+export declare class GitHubReviewHost implements CodeReviewHost {
+    private readonly client;
+    readonly provider: "github";
+    constructor(client: GitHubAppClient);
+    /** Runs `action` with a token for exactly `permissions`, translating failures to ReviewHostError. */
+    protected withToken<T>(repository: string, permissions: Record<string, "read" | "write">, action: (get: (path: string, init?: RequestInit, expected?: number[]) => Promise<Response>, graphql: GraphQl) => Promise<T>): Promise<T>;
+    repositoryPermission(repository: string, user: HostUser): Promise<{
+        level: HostPermission;
+        login: string;
+    }>;
+    pullRequestHead(repository: string, prNumber: number): Promise<PullRequestHead>;
+    private head;
+    readPullRequest(repository: string, prNumber: number, opts: {
+        sinceSha?: string;
+        maxPatchChars: number;
+        agentMarker: string;
+    }): Promise<PullRequestView>;
+    readFile(repository: string, path: string, ref: string | undefined, window: {
+        startLine: number;
+        maxLines: number;
+    }): Promise<FileReadResult>;
+    listFiles(repository: string, ref: string | undefined, pathPrefix?: string): Promise<FileListView>;
+    publishReview(repository: string, input: PublishReviewInput): Promise<PublishReviewResult>;
+    /**
+     * Resolves the requested threads that are still this agent's own open
+     * threads on the PR, each with its own GraphQL call; everything else is
+     * skipped. Never throws: the review is already published, so a refusal
+     * (for example an App without Contents write) only skips.
+     */
+    private resolveOwnThreads;
+    private publishOnly;
+    private findSummaryComment;
+    private patchCheck;
+    comment(repository: string, input: CommentInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    editComment(repository: string, input: EditCommentInput): Promise<void>;
+    acknowledge(repository: string, target: CommentRef): Promise<void>;
+    startCheck(repository: string, input: StartCheckInput): Promise<{
+        checkId: string;
+    }>;
+    completeCheck(repository: string, input: CompleteCheckInput): Promise<void>;
+}
+export {};