@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/ghcred.js

@@ -0,0 +1,139 @@
+// The GitHub credential chain of the LOCAL review route (`qcr review`).
+//
+// The App-only credential rule, and its carve-out: the daemon holds only the
+// App credential. The local and Action review routes run as the person at their
+// own terminal, so they may also use the credentials that person already has.
+// This module is that route's alone: the daemon's code never imports it
+// (tests/review-pr-target.test.ts fences who may).
+//
+// Order: the App if configured, then the token handed to a container as a
+// file (below), then GITHUB_TOKEN / GH_TOKEN, then `gh auth token`.
+//
+// The handoff: a token a container runs with is never env
+// and never argv. The caller (the host wrapper, or the Action) writes it to a
+// 0600 file in a fresh 0700 dir, bind-mounted at /run/qcr-in, and names the
+// file in QCR_GH_TOKEN_FILE. `takeHandoffToken` reads it ONCE at startup,
+// unlinks it, deletes the variable and keeps the token in this module's
+// memory only, all before any pi or bash child exists.
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const CREDENTIAL_SOURCES = [
+    "app",
+    "handoff",
+    "gh",
+    "env:GITHUB_TOKEN",
+    "env:GH_TOKEN",
+];
+/** The variable that names the handed-over token file. */
+export const HANDOFF_FILE_ENV = "QCR_GH_TOKEN_FILE";
+/** Where the container sees the handoff dir. */
+export const HANDOFF_MOUNT = "/run/qcr-in";
+let handed = null;
+/**
+ * Read the handed-over token file once and unlink it. Returns the token (also
+ * kept for `handedToken()`), or null when no file was named. Throws, leaving
+ * nothing in memory, when the file is named but unreadable, empty, or cannot
+ * be removed: a token that stays on disk beside a model's tools is refused,
+ * never used. The variable is deleted from `env` either way, so no child
+ * inherits the path.
+ */
+export function takeHandoffToken(env = process.env) {
+    const file = env[HANDOFF_FILE_ENV];
+    delete env[HANDOFF_FILE_ENV];
+    if (file === undefined || file === "")
+        return handed;
+    const fd = openSync(file, "r");
+    try {
+        // Unlink first, read from the open descriptor: the file is gone before
+        // its content is in memory, and a failed unlink reads nothing.
+        unlinkSync(file);
+        const token = readFileSync(fd, "utf8").trim();
+        if (!token)
+            throw new Error("the GitHub token file is empty");
+        handed = token;
+    }
+    finally {
+        closeSync(fd);
+    }
+    return handed;
+}
+/** The token `takeHandoffToken` read, or null. */
+export const handedToken = () => handed;
+/** Forget the handed-over token (tests; a long-lived host after its last use). */
+export function dropHandedToken() {
+    handed = null;
+}
+/**
+ * The caller's half: write `token` to a 0600 file in a fresh 0700 dir. On
+ * Linux the dir is under an absolute $XDG_RUNTIME_DIR (normally a tmpfs);
+ * without one, and elsewhere (macOS), it comes from mkdtemp under the OS
+ * temp dir ($TMPDIR), which may be disk-backed. The token is never put in env or argv.
+ */
+export function stageHandoffToken(token, env = process.env, platform = process.platform) {
+    const runtime = env["XDG_RUNTIME_DIR"];
+    const base = platform === "linux" && runtime && runtime.startsWith("/") ? runtime : tmpdir();
+    mkdirSync(base, { recursive: true });
+    const dir = mkdtempSync(join(base, "qcr-in-")); // 0700
+    try {
+        writeFileSync(join(dir, "gh-token"), token, { mode: 0o600, flag: "wx" });
+    }
+    catch (err) {
+        rmSync(dir, { recursive: true, force: true });
+        throw err;
+    }
+    return {
+        dir,
+        containerFile: `${HANDOFF_MOUNT}/gh-token`,
+        remove: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}
+export const MISSING_CREDENTIAL_HELP = "no GitHub credential found. Run `gh auth login`, or set GITHUB_TOKEN (or GH_TOKEN) " +
+    "to a token that can read the repository, or configure the GitHub App.";
+/** The real `gh auth token`. */
+export function ghAuthTokenFromCli() {
+    try {
+        const out = execFileSync("gh", ["auth", "token"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+        }).trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveGithubCredential(d) {
+    let appNote = "";
+    const appConfigured = d.secretsDir !== "" &&
+        existsSync(join(d.secretsDir, "app_id")) &&
+        existsSync(join(d.secretsDir, "app.pem"));
+    if (appConfigured) {
+        try {
+            const token = (await d.mintApp(d.secretsDir)).trim();
+            if (token)
+                return { ok: true, source: "app", token };
+        }
+        catch (err) {
+            appNote = `the configured GitHub App could not mint a token (${String(err instanceof Error ? err.message : err).slice(0, 200)}). `;
+        }
+    }
+    const given = d.handoff?.trim();
+    if (given)
+        return { ok: true, source: "handoff", token: given };
+    for (const name of ["GITHUB_TOKEN", "GH_TOKEN"]) {
+        const v = d.env[name]?.trim();
+        if (v)
+            return { ok: true, source: `env:${name}`, token: v };
+    }
+    const gh = d.ghAuthToken();
+    if (gh)
+        return { ok: true, source: "gh", token: gh };
+    return {
+        ok: false,
+        error: appNote ? appNote + MISSING_CREDENTIAL_HELP : MISSING_CREDENTIAL_HELP,
+    };
+}
+//# sourceMappingURL=ghcred.js.map

package/dist/src/ghcred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ghcred.js","sourceRoot":"","sources":["../../src/ghcred.ts"],"names":[],"mappings":"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"}

package/dist/src/githubAuth.d.ts

@@ -0,0 +1,32 @@
+export type FetchFn = typeof fetch;
+/** GraphQL's bare App actor, only for a matching configured bot login. */
+export declare function appActorAlias(botLogin: string, appSlug: string): string | undefined;
+export declare function mintAppJwt(appId: string, privateKeyPem: string, now?: () => number): string;
+export interface InstallationToken {
+    token: string;
+    expires_at: string;
+}
+/** The deadline on each request — the same as the adapter's REST calls, so a
+ * stalled mint cannot hold every caller waiting on its shared promise. */
+export declare const GITHUB_REQUEST_TIMEOUT_MS = 60000;
+export declare class TokenMinter {
+    private readonly secretsDir;
+    private readonly fetchFn;
+    private readonly apiBase;
+    private readonly now;
+    private cache;
+    private inflight;
+    private installationId;
+    constructor(secretsDir: string, fetchFn?: FetchFn, apiBase?: string, now?: () => number);
+    private readSecret;
+    appJwt(): string;
+    /** Resolve (and cache) the single installation this app serves. */
+    resolveInstallationId(): Promise<number>;
+    private fresh;
+    /** Installation token, minting/refreshing as needed (single-flight). */
+    installationToken(installationId?: number): Promise<string>;
+    private mint;
+    /** Drop the cache after a 401 so the next call re-mints. */
+    invalidate(installationId?: number): void;
+}
+//# sourceMappingURL=githubAuth.d.ts.map

package/dist/src/githubAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubAuth.d.ts","sourceRoot":"","sources":["../../src/githubAuth.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC;AAEnC,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnF;AAMD,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,MAAM,MAAiB,GAC3B,MAAM,CAOR;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;0EAC0E;AAC1E,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAchD,qBAAa,WAAW;IAMpB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IARtB,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,cAAc,CAAuB;gBAG1B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,OAAe,EACxB,OAAO,SAA2B,EAClC,GAAG,GAAE,MAAM,MAAiB;IAG/C,OAAO,CAAC,UAAU;IAIlB,MAAM,IAAI,MAAM;IAQhB,mEAAmE;IAC7D,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC;IAe9C,OAAO,CAAC,KAAK;IAIb,wEAAwE;IAClE,iBAAiB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAWnD,IAAI;IAelB,4DAA4D;IAC5D,UAAU,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI;CAI1C"}

package/dist/src/githubAuth.js

@@ -0,0 +1,116 @@
+// GitHub App authentication: RS256 app JWTs and cached installation tokens.
+// The JWT is backdated 60 s against clock skew and lives 600 s from that iat
+// (9 min from now); scripts/mint-token.sh signs its own with a 540 s life
+// (8 min from now). Both stay under GitHub's 10-minute ceiling. Tokens are
+// cached per installation off `expires_at` with a ~5 min proactive refresh
+// window, refreshed single-flight, re-minted once on a 401 (by the caller's
+// `invalidate`). Every request carries the adapter's 60 s deadline.
+// The app PEM is the only credential anywhere — no personal token code path.
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** GraphQL's bare App actor, only for a matching configured bot login. */
+export function appActorAlias(botLogin, appSlug) {
+    return botLogin === `${appSlug}[bot]` ? appSlug : undefined;
+}
+function b64url(input) {
+    return Buffer.from(input).toString("base64url");
+}
+export function mintAppJwt(appId, privateKeyPem, now = Date.now) {
+    const iat = Math.floor(now() / 1000) - 60;
+    const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+    const payload = b64url(JSON.stringify({ iat, exp: iat + 600, iss: appId }));
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${payload}`);
+    return `${header}.${payload}.${signer.sign(privateKeyPem, "base64url")}`;
+}
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+/** The deadline on each request — the same as the adapter's REST calls, so a
+ * stalled mint cannot hold every caller waiting on its shared promise. */
+export const GITHUB_REQUEST_TIMEOUT_MS = 60_000;
+/** GitHub's own words for a failed call (its `message`), capped, as ": <text>";
+ * empty when the body cannot be read. A 403's permission or rate-limit
+ * explanation is what tells operators two failures of one status apart. */
+async function explanation(res) {
+    try {
+        const text = (await res.text()).replace(/\s+/g, " ").trim().slice(0, 300);
+        return text ? `: ${text}` : "";
+    }
+    catch {
+        return "";
+    }
+}
+export class TokenMinter {
+    secretsDir;
+    fetchFn;
+    apiBase;
+    now;
+    cache = new Map();
+    inflight = new Map();
+    installationId = null;
+    constructor(secretsDir, fetchFn = fetch, apiBase = "https://api.github.com", now = Date.now) {
+        this.secretsDir = secretsDir;
+        this.fetchFn = fetchFn;
+        this.apiBase = apiBase;
+        this.now = now;
+    }
+    readSecret(name) {
+        return readFileSync(join(this.secretsDir, name), "utf8").trim();
+    }
+    appJwt() {
+        return mintAppJwt(this.readSecret("app_id"), readFileSync(join(this.secretsDir, "app.pem"), "utf8"), this.now);
+    }
+    /** Resolve (and cache) the single installation this app serves. */
+    async resolveInstallationId() {
+        if (this.installationId !== null)
+            return this.installationId;
+        const res = await this.fetchFn(`${this.apiBase}/app/installations`, {
+            signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
+            headers: { authorization: `Bearer ${this.appJwt()}`, accept: "application/vnd.github+json" },
+        });
+        if (!res.ok)
+            throw new Error(`GET /app/installations failed: ${res.status}${await explanation(res)}`);
+        const installs = (await res.json());
+        const first = installs[0];
+        if (!first)
+            throw new Error("app has no installations");
+        this.installationId = first.id;
+        return first.id;
+    }
+    fresh(tok) {
+        return !!tok && Date.parse(tok.expires_at) - this.now() > REFRESH_MARGIN_MS;
+    }
+    /** Installation token, minting/refreshing as needed (single-flight). */
+    async installationToken(installationId) {
+        const id = installationId ?? (await this.resolveInstallationId());
+        const cached = this.cache.get(id);
+        if (this.fresh(cached))
+            return cached.token;
+        const inflight = this.inflight.get(id);
+        if (inflight)
+            return inflight;
+        const p = this.mint(id).finally(() => this.inflight.delete(id));
+        this.inflight.set(id, p);
+        return p;
+    }
+    async mint(id) {
+        const res = await this.fetchFn(`${this.apiBase}/app/installations/${id}/access_tokens`, {
+            method: "POST",
+            signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
+            headers: { authorization: `Bearer ${this.appJwt()}`, accept: "application/vnd.github+json" },
+        });
+        if (!res.ok)
+            throw new Error(`token mint failed for installation ${id}: ${res.status}${await explanation(res)}`);
+        const tok = (await res.json());
+        this.cache.set(id, tok);
+        return tok.token;
+    }
+    /** Drop the cache after a 401 so the next call re-mints. */
+    invalidate(installationId) {
+        if (installationId === undefined)
+            this.cache.clear();
+        else
+            this.cache.delete(installationId);
+    }
+}
+//# sourceMappingURL=githubAuth.js.map

package/dist/src/githubAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubAuth.js","sourceRoot":"","sources":["../../src/githubAuth.ts"],"names":[],"mappings":"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"}

package/dist/src/githubcore.d.ts

@@ -0,0 +1,20 @@
+/** A GitHub request that came back refused: the method, path and status, and
+ * how long GitHub asked us to wait, when it said. */
+export declare class GitHubRequestError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    readonly retryAfterMs?: number | undefined;
+    constructor(method: string, path: string, status: number, detail: string, retryAfterMs?: number | undefined);
+}
+export interface PrFileEntry {
+    filename: string;
+    additions: number;
+    deletions: number;
+    status: string;
+    /** Unified diff for the file when GitHub returns one (absent for binaries). */
+    patch?: string;
+    /** The path before a rename, when GitHub detected one (renumber detection). */
+    previous_filename?: string;
+}
+//# sourceMappingURL=githubcore.d.ts.map

package/dist/src/githubcore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubcore.d.ts","sourceRoot":"","sources":["../../src/githubcore.ts"],"names":[],"mappings":"AAIA;qDACqD;AACrD,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM;gBAJrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,EACL,YAAY,CAAC,EAAE,MAAM,YAAA;CAKjC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/src/githubcore.js

@@ -0,0 +1,20 @@
+// The core's half of the GitHub client: what a review route needs to read a
+// PR and post through the one gate without the daemon's adapter
+// (src/github.ts, which re-exports these).
+/** A GitHub request that came back refused: the method, path and status, and
+ * how long GitHub asked us to wait, when it said. */
+export class GitHubRequestError extends Error {
+    method;
+    path;
+    status;
+    retryAfterMs;
+    constructor(method, path, status, detail, retryAfterMs) {
+        super(`${method} ${path} → ${status}: ${detail}`);
+        this.method = method;
+        this.path = path;
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "GitHubRequestError";
+    }
+}
+//# sourceMappingURL=githubcore.js.map

package/dist/src/githubcore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"githubcore.js","sourceRoot":"","sources":["../../src/githubcore.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,gEAAgE;AAChE,2CAA2C;AAE3C;qDACqD;AACrD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IACA;IACA;IAEA;IALX,YACW,MAAc,EACd,IAAY,EACZ,MAAc,EACvB,MAAc,EACL,YAAqB;QAE9B,KAAK,CAAC,GAAG,MAAM,IAAI,IAAI,MAAM,MAAM,KAAK,MAAM,EAAE,CAAC,CAAC;QANzC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAQ;QAEd,iBAAY,GAAZ,YAAY,CAAS;QAG9B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/src/glob.d.ts

@@ -0,0 +1,11 @@
+/** Why `glob` is not a usable pattern, or null when it is. */
+export declare function globProblem(glob: unknown): string | null;
+export declare function globBody(pattern: string): string;
+/** The RegExp a glob compiles to (see the header). */
+export declare function globToRegExp(glob: string): RegExp;
+/** A predicate over repo-relative paths: true when any glob matches. */
+export declare function globMatcher(globs: readonly string[]): (path: string) => boolean;
+/** `globMatcher`, failing CLOSED: a list the compiler refuses matches
+ * nothing (never everything). */
+export declare function globMatcherOrNothing(globs: readonly string[]): (path: string) => boolean;
+//# sourceMappingURL=glob.d.ts.map

package/dist/src/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/glob.ts"],"names":[],"mappings":"AAeA,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMxD;AAMD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,sDAAsD;AACtD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAG/E;AAED;iCACiC;AACjC,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAMxF"}

package/dist/src/glob.js

@@ -0,0 +1,69 @@
+// Path globs for exclusion lists (`[scan] exclude`). Deliberately
+// small and gitignore-shaped, so an operator's pattern means what it looks
+// like:
+//
+//   *        any run of characters inside one path segment
+//   **       any run of characters, `/` included (`a/**/b`, `**/x.py`)
+//   ?        one character inside a segment
+//   name     a pattern with no `/` (a trailing one aside) matches that name
+//            at ANY depth (`*.pb.go`, `generated/`); one with an inner `/`
+//            is anchored at the repo root (`src/legacy/**`, `docs/api`)
+//
+// A pattern also matches everything under a directory it matches, so
+// `generated` excludes `a/generated/x.py`. Nothing else is special: every
+// other character is literal.
+/** Why `glob` is not a usable pattern, or null when it is. */
+export function globProblem(glob) {
+    if (typeof glob !== "string" || glob.trim() === "")
+        return "must be a non-empty string";
+    if (glob.startsWith("/"))
+        return "must be repo-relative (no leading /)";
+    if (glob.split("/").includes(".."))
+        return "must not contain `..`";
+    if (glob.includes("\0"))
+        return "must not contain NUL";
+    return null;
+}
+// A pattern's wildcards as an unanchored RegExp source: `**/` any run of
+// whole leading segments, `**` any run, `*` a run inside one segment, `?` one
+// character inside one; everything else literal. The ONE wildcard grammar —
+// each caller adds its own anchoring around it.
+export function globBody(pattern) {
+    return pattern
+        .split(/(\*\*\/|\*\*|\*|\?)/)
+        .map((part) => {
+        if (part === "**/")
+            return "(?:[\\s\\S]*/)?";
+        if (part === "**")
+            return "[\\s\\S]*";
+        if (part === "*")
+            return "[^/]*";
+        if (part === "?")
+            return "[^/]";
+        return part.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("");
+}
+/** The RegExp a glob compiles to (see the header). */
+export function globToRegExp(glob) {
+    // A trailing slash adds nothing the `(?:/.*)?` tail does not already say.
+    const g = glob.trim().replace(/\/+$/, "");
+    const lead = g.includes("/") ? "^" : "(?:^|/)";
+    return new RegExp(`${lead}${globBody(g)}(?:/[\\s\\S]*)?$`);
+}
+/** A predicate over repo-relative paths: true when any glob matches. */
+export function globMatcher(globs) {
+    const res = globs.map(globToRegExp);
+    return (path) => res.some((re) => re.test(path));
+}
+/** `globMatcher`, failing CLOSED: a list the compiler refuses matches
+ * nothing (never everything). */
+export function globMatcherOrNothing(globs) {
+    try {
+        return globMatcher(globs);
+    }
+    catch {
+        return () => false;
+    }
+}
+//# sourceMappingURL=glob.js.map

package/dist/src/glob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.js","sourceRoot":"","sources":["../../src/glob.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,2EAA2E;AAC3E,QAAQ;AACR,EAAE;AACF,2DAA2D;AAC3D,uEAAuE;AACvE,4CAA4C;AAC5C,4EAA4E;AAC5E,2EAA2E;AAC3E,wEAAwE;AACxE,EAAE;AACF,qEAAqE;AACrE,0EAA0E;AAC1E,8BAA8B;AAE9B,8DAA8D;AAC9D,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,4BAA4B,CAAC;IACxF,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,sCAAsC,CAAC;IACxE,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,uBAAuB,CAAC;IACnE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,sBAAsB,CAAC;IACvD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yEAAyE;AACzE,8EAA8E;AAC9E,4EAA4E;AAC5E,gDAAgD;AAChD,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,OAAO;SACX,KAAK,CAAC,qBAAqB,CAAC;SAC5B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,iBAAiB,CAAC;QAC7C,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,WAAW,CAAC;QACtC,IAAI,IAAI,KAAK,GAAG;YAAE,OAAO,OAAO,CAAC;QACjC,IAAI,IAAI,KAAK,GAAG;YAAE,OAAO,MAAM,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,0EAA0E;IAC1E,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/C,OAAO,IAAI,MAAM,CAAC,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAC7D,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAwB;IAClD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;iCACiC;AACjC,MAAM,UAAU,oBAAoB,CAAC,KAAwB;IAC3D,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/src/guards.d.ts

@@ -0,0 +1,93 @@
+import { type CheckSummary, type CiReviewBody } from "./cigate.js";
+import type { GuardsConfig } from "./reviewconfig.js";
+import type { MutationGuard } from "./gate.js";
+import type { ReviewedHeadRow } from "./storerows.js";
+/** A bot's login: the App's own, or any `[bot]` account. Bot-authored PRs
+ * never enter the state machine (spec §3, src/statemachine.ts re-exports
+ * this), and a bot's approval is no human's. */
+export declare function isBotAuthor(author: string, botLogin: string): boolean;
+/** Mutation kinds that put words on a PR — the ones the guards inspect. */
+export declare const POSTING_KINDS: ReadonlySet<string>;
+/** The read-only slice of the adapter the guards need. Both calls are reads,
+ * and a read is never gated. */
+export interface GuardAdapter {
+    getPr(n: number): Promise<{
+        state: "open" | "closed";
+        merged: boolean;
+        head_sha: string;
+        author: string;
+    }>;
+    listReviews(n: number): Promise<Array<{
+        id: number;
+        user: string;
+        state: string;
+        commit_id: string;
+    }>>;
+    /** Checks at a head (guard 4). Optional: an adapter without it
+     * cannot see CI, and a guard never blocks on what it cannot see. */
+    listChecks?(ref: string): Promise<CheckSummary[]>;
+}
+/** The store slice: the reviewed-head mark, the withheld-approval mark, and
+ * the event log. */
+export interface GuardStore {
+    reviewedHead(pr: number): ReviewedHeadRow | undefined;
+    recordReviewedHead(pr: number, mark: {
+        head_sha: string;
+        verdict?: string | null;
+        posted_event?: string | null;
+        round_no?: number | null;
+    }): void;
+    logEvent(kind: string, pr: number | null, payload?: unknown): void;
+    recordApprovalWithheld(pr: number, mark: {
+        head_sha: string;
+        ci_state?: string | null;
+        reason?: string | null;
+    }): void;
+    clearApprovalWithheld(pr: number): void;
+}
+export interface GuardDeps {
+    store: GuardStore;
+    adapter: GuardAdapter;
+    botLogin: string;
+    guards: GuardsConfig;
+    log?: (msg: string, extra?: unknown) => void;
+}
+/** The review payload as it appears inside a `create_review` intent — the
+ * one shape both softenings (guard 1 here, guard 4 in cigate.ts) rewrite. */
+type ReviewBody = CiReviewBody;
+/**
+ * The login of a non-author human whose APPROVED review stands at `head_sha`,
+ * or null. "Stands" means it is that person's LATEST verdict-bearing review:
+ * a later CHANGES_REQUESTED or DISMISSED by the same person retires it.
+ * COMMENTED/PENDING reviews carry no verdict and are ignored.
+ *
+ * Reviews are read in submission order, which is the order the REST endpoint
+ * returns them in.
+ */
+export declare function humanApprovalAtHead(reviews: Array<{
+    user: string;
+    state: string;
+    commit_id: string;
+}>, opts: {
+    head_sha: string;
+    author: string;
+    botLogin: string;
+}): string | null;
+/** The note the downgraded review carries, so the softer event is never a
+ * silent change of mind. */
+export declare function downgradeNote(approver: string, headSha: string): string;
+/** REQUEST_CHANGES → COMMENT, findings untouched, with the note appended. */
+export declare function downgradeForHumanApproval(body: ReviewBody, approver: string, headSha: string): ReviewBody;
+/**
+ * Is there anything new to review at `head_sha`? True unless the mark sits on
+ * exactly this head and no author reply has landed since it was stamped.
+ * An unknown head (empty string) is always "new": guessing would suppress a
+ * real review.
+ */
+export declare function hasNewEvidence(mark: ReviewedHeadRow | undefined, headSha: string): boolean;
+/** Why a posting mutation was refused. Short tags — they land in the event log
+ * and in `GateResult.blocked`. */
+export type BlockReason = "pr-merged" | "pr-closed" | "pr-unreadable" | "no-new-evidence" | "head-drift";
+export declare function makePostingGuard(deps: GuardDeps): MutationGuard;
+export {};
+//# sourceMappingURL=guards.d.ts.map

package/dist/src/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/guards.ts"],"names":[],"mappings":"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"}