@ashlr/hub 3.4.0 → 3.5.0

package/dist/core/verse/github-api.js

@@ -0,0 +1,211 @@
+/**
+ * core/verse/github-api.ts — `GET /api/verse/github{,/pr-plan}`
+ * (docs/VERSE-WORKSPACES.md §2). The routes that make github.ts reachable
+ * from Ashlr Verse.
+ *
+ * Mounted from src/core/web/api.ts's handleApi() BEFORE the V1 verse handler,
+ * for the same reason the V2 control plane is: `isVerseApiPath()` matches every
+ * `/api/verse/*` path and 404s what it does not recognise, so a route mounted
+ * after it is never reached.
+ *
+ * SECURITY POSTURE — identical to control-api.ts, minus the POST half:
+ *   - Both routes are GET-only and sit behind the read-session boundary in
+ *     server.ts. There is NO mutation here. Nothing in this module opens,
+ *     closes, merges, comments on, or pushes anything; `createPr` is not
+ *     imported and `applyProposal` is not called.
+ *   - Every response goes through sendJson() → sanitizePublicJson().
+ *   - `?repo=` is refused unless the path is one the operator already brought
+ *     into Verse — an enrolled repo, or the project path of an existing
+ *     session (exactly `discoverProjects()`'s answer). The route is therefore
+ *     not a filesystem probe.
+ *   - No token, remote URL, launcher argv, or gh stderr can reach a response:
+ *     github-repo.ts reads only `nameWithOwner`, and gh failures collapse to
+ *     `prsAvailable: false` plus a fixed sentence.
+ */
+import { sendJson } from '../web/api.js';
+import { loadProposal } from '../inbox/store.js';
+import { discoverProjects } from './projects.js';
+import { expandHomePrefix, peekVerseEngine } from './verse-api.js';
+import { describeVersePrPlans } from './github-proposal.js';
+import { readVerseGithubSnapshot } from './github-repo.js';
+const VERSE_PREFIX = '/api/verse';
+export const VERSE_GITHUB_ROUTE = `${VERSE_PREFIX}/github`;
+export const VERSE_GITHUB_PR_PLAN_ROUTE = `${VERSE_PREFIX}/github/pr-plan`;
+const GITHUB_ROUTES = new Set([VERSE_GITHUB_ROUTE, VERSE_GITHUB_PR_PLAN_ROUTE]);
+/** Bound the work one request can ask for. */
+const MAX_REPOS_PER_REQUEST = 12;
+const MAX_PLAN_IDS = 50;
+const MAX_ID_CHARS = 128;
+const MAX_PATH_CHARS = 4_096;
+/** Proposal ids are `prop-<ts>-<hex>`; accept that shape and nothing exotic. */
+const PROPOSAL_ID_RE = /^[A-Za-z0-9._-]+$/;
+/** True for exactly the two GitHub routes. */
+export function isVerseGithubPath(path) {
+    return GITHUB_ROUTES.has(path);
+}
+const ERROR_STATUS = {
+    VERSE_INVALID: 400,
+    VERSE_REFUSED: 409,
+    VERSE_TOO_LARGE: 413,
+    VERSE_UNAVAILABLE: 503,
+};
+function sendError(res, code, error) {
+    sendJson(res, ERROR_STATUS[code], { code, error });
+}
+function queryParam(req, key) {
+    const raw = req.url ?? '';
+    const qIndex = raw.indexOf('?');
+    if (qIndex < 0)
+        return null;
+    const params = new URLSearchParams(raw.slice(qIndex + 1));
+    return params.get(key);
+}
+/**
+ * Every root the operator has already brought into Verse: enrolled repos
+ * first, then the project path of each live session. Identical to what
+ * `GET /api/verse/bootstrap` lists, so the GitHub panel can never show a root
+ * the picker does not.
+ *
+ * `peekVerseEngine()` is used rather than `getVerseEngine()` on purpose — a
+ * read must never be the thing that creates the session engine.
+ */
+function defaultKnownRoots() {
+    let sessions = [];
+    try {
+        sessions = peekVerseEngine()?.listSessions() ?? [];
+    }
+    catch {
+        sessions = [];
+    }
+    try {
+        return discoverProjects({ sessions }).map((p) => p.path);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Handle one `/api/verse/github*` request. Returns true when a response was
+ * written (including errors); false when `path` is not one of these routes.
+ */
+export async function handleVerseGithubApi(_ctx, req, res, path, method, deps = {}) {
+    if (!isVerseGithubPath(path))
+        return false;
+    try {
+        if (method !== 'GET') {
+            sendJson(res, 404, { error: `not found: ${method} ${path}` });
+            return true;
+        }
+        if (path === VERSE_GITHUB_ROUTE) {
+            handleRepos(req, res, deps);
+            return true;
+        }
+        handlePrPlans(req, res, deps);
+        return true;
+    }
+    catch {
+        if (!res.headersSent) {
+            sendJson(res, 500, { code: 'INTERNAL_ERROR', error: 'internal server error' });
+        }
+        else if (!res.writableEnded) {
+            try {
+                res.end();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        return true;
+    }
+}
+// ---------------------------------------------------------------------------
+// GET /api/verse/github[?repo=<absolute path>]
+// ---------------------------------------------------------------------------
+function handleRepos(req, res, deps) {
+    const read = deps.read ?? readVerseGithubSnapshot;
+    const known = (deps.knownRoots ?? defaultKnownRoots)();
+    const requested = queryParam(req, 'repo');
+    let roots;
+    // Without `?repo=`, this is the cheap index: identity and default branch per
+    // root, from local `git` reads only. `gh` is an 8 s-ceilinged synchronous
+    // subprocess on a single-threaded server, so a dozen roots' worth of list
+    // calls in one request is not something a UI mount may trigger. The panel
+    // fills in one root at a time with `?repo=`.
+    let includeLists = false;
+    if (requested === null) {
+        roots = known.slice(0, MAX_REPOS_PER_REQUEST);
+    }
+    else {
+        includeLists = true;
+        if (requested.length === 0 || requested.length > MAX_PATH_CHARS) {
+            sendError(res, 'VERSE_INVALID', 'repo must be a non-empty path');
+            return;
+        }
+        const resolved = expandHomePrefix(requested);
+        if (!known.includes(resolved)) {
+            // Not "no such directory" — deliberately the same answer whether the
+            // path exists or not, so this route cannot be used to probe the disk.
+            sendError(res, 'VERSE_REFUSED', 'repo is not an enrolled project or an open session path');
+            return;
+        }
+        roots = [resolved];
+    }
+    const snapshot = read(roots, {
+        includeLists,
+        ...(deps.readOptions ?? {}),
+    });
+    sendJson(res, 200, snapshot);
+}
+// ---------------------------------------------------------------------------
+// GET /api/verse/github/pr-plan?id=<proposalId>[,<proposalId>…]
+// ---------------------------------------------------------------------------
+function handlePrPlans(req, res, deps) {
+    const describe = deps.describePlans ?? describeVersePrPlans;
+    const load = deps.loadProposal ?? ((id) => loadProposal(id));
+    const raw = queryParam(req, 'id');
+    if (raw === null || raw.length === 0) {
+        sendError(res, 'VERSE_INVALID', 'id is required');
+        return;
+    }
+    const ids = [];
+    for (const part of raw.split(',')) {
+        const id = part.trim();
+        if (id.length === 0)
+            continue;
+        if (id.length > MAX_ID_CHARS || !PROPOSAL_ID_RE.test(id)) {
+            sendError(res, 'VERSE_INVALID', 'id contains an unsupported character');
+            return;
+        }
+        if (!ids.includes(id))
+            ids.push(id);
+        if (ids.length > MAX_PLAN_IDS) {
+            sendError(res, 'VERSE_INVALID', `at most ${MAX_PLAN_IDS} ids per request`);
+            return;
+        }
+    }
+    if (ids.length === 0) {
+        sendError(res, 'VERSE_INVALID', 'id is required');
+        return;
+    }
+    const proposals = [];
+    for (const id of ids) {
+        let proposal = null;
+        try {
+            proposal = load(id);
+        }
+        catch {
+            proposal = null;
+        }
+        // An unknown id is silently absent rather than a 404: a client asking for
+        // several plans should not lose all of them because one was just applied
+        // and rotated out from under it.
+        if (proposal)
+            proposals.push(proposal);
+    }
+    const body = {
+        plans: describe(proposals),
+        observedAt: new Date().toISOString(),
+    };
+    sendJson(res, 200, body);
+}
+//# sourceMappingURL=github-api.js.map

package/dist/core/verse/github-api.js.map

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

package/dist/core/verse/github-proposal.d.ts

@@ -0,0 +1,64 @@
+/**
+ * core/verse/github-proposal.ts — the pre-click disclosure for an approved
+ * proposal of kind `pr` (docs/VERSE-WORKSPACES.md §2).
+ *
+ * THE POINT OF THIS FILE. Approving a `pr` proposal is the one action in the
+ * hub that reaches outside the machine: `core/inbox/apply.ts` builds a branch
+ * in a throwaway worktree and calls `createPr()`, which publishes that branch
+ * and opens a real pull request. The Approvals view names the repo and the
+ * kind. It does not name the branch it is about to create or the pull request
+ * it is about to open, so the operator learns both AFTER the click, from
+ * `proposal.result` — a sentence, produced by the thing they already approved.
+ * This module computes them BEFORE.
+ *
+ * ── WHAT APPLY ACTUALLY DOES (verified against src/core/inbox/apply.ts) ────
+ *   • branch  = `ashlr/proposal/${proposal.id}`      (apply.ts:52, :125, :254)
+ *   • createPr(repo, { title: proposal.title,
+ *                      body:  proposal.summary,
+ *                      head:  branch })              (apply.ts:257-261)
+ *   • NO `base` is passed, so GitHub resolves the base to the repository's
+ *     default branch. `predictPrPlan` reproduces that locally from
+ *     `git symbolic-ref origin/HEAD` and labels it `baseSource: 'predicted'`,
+ *     because it is our reading of gh's choice, not an instruction to gh.
+ *   • NO `git push` runs. `gh pr create --head <branch>` publishes the branch
+ *     as a side effect, which is why `publishesBranch` is true and stated.
+ *
+ * ── DRIFT ──────────────────────────────────────────────────────────────────
+ * `PROPOSAL_BRANCH_PREFIX` is module-private in apply.ts, so the literal is
+ * repeated here. test/verse-github-proposal.test.ts reads apply.ts and fails
+ * if the two ever diverge — a disclosure that predicts the wrong branch name
+ * is worse than none.
+ *
+ * READ-ONLY. NEVER THROWS. Opens nothing, pushes nothing, spawns only the
+ * `git` reads core/git.ts already performs.
+ */
+import type { Proposal } from '../types.js';
+import type { VerseGithubPrPlan } from './github-types.js';
+/**
+ * Mirrors `PROPOSAL_BRANCH_PREFIX` in src/core/inbox/apply.ts:52, which is not
+ * exported. Guarded against drift by test/verse-github-proposal.test.ts.
+ */
+export declare const VERSE_PROPOSAL_BRANCH_PREFIX = "ashlr/proposal/";
+/** The subset of `Proposal` a plan needs. Structural, so fixtures stay small. */
+export type VersePrPlanProposal = Pick<Proposal, 'id' | 'kind' | 'repo' | 'title' | 'summary' | 'status'> & Partial<Pick<Proposal, 'result' | 'remoteHandoff' | 'localMergeIntent'>>;
+/** Git facts the plan needs. Defaults to core/git.ts; injected in tests. */
+export interface VersePrPlanGitProbe {
+    defaultBranch(path: string): string;
+    nameWithOwner(path: string): string | null;
+}
+export interface VersePrPlanOptions {
+    git?: VersePrPlanGitProbe;
+}
+/** The branch `applyPr` will create for this proposal id. */
+export declare function verseProposalBranch(proposalId: string): string;
+/**
+ * Describe what approving this proposal will do — or, once it has been
+ * applied, what it did.
+ *
+ * Returns `state: 'unavailable'` (and no branch/base) for anything that is not
+ * an outward-facing `pr` proposal, so a caller can render the disclosure
+ * unconditionally and let the shape decide whether there is anything to show.
+ */
+export declare function describeVersePrPlan(proposal: VersePrPlanProposal, opts?: VersePrPlanOptions): VerseGithubPrPlan;
+/** Plans for several proposals, in the order given. Never throws. */
+export declare function describeVersePrPlans(proposals: readonly VersePrPlanProposal[], opts?: VersePrPlanOptions): VerseGithubPrPlan[];

package/dist/core/verse/github-proposal.js

@@ -0,0 +1,186 @@
+/**
+ * core/verse/github-proposal.ts — the pre-click disclosure for an approved
+ * proposal of kind `pr` (docs/VERSE-WORKSPACES.md §2).
+ *
+ * THE POINT OF THIS FILE. Approving a `pr` proposal is the one action in the
+ * hub that reaches outside the machine: `core/inbox/apply.ts` builds a branch
+ * in a throwaway worktree and calls `createPr()`, which publishes that branch
+ * and opens a real pull request. The Approvals view names the repo and the
+ * kind. It does not name the branch it is about to create or the pull request
+ * it is about to open, so the operator learns both AFTER the click, from
+ * `proposal.result` — a sentence, produced by the thing they already approved.
+ * This module computes them BEFORE.
+ *
+ * ── WHAT APPLY ACTUALLY DOES (verified against src/core/inbox/apply.ts) ────
+ *   • branch  = `ashlr/proposal/${proposal.id}`      (apply.ts:52, :125, :254)
+ *   • createPr(repo, { title: proposal.title,
+ *                      body:  proposal.summary,
+ *                      head:  branch })              (apply.ts:257-261)
+ *   • NO `base` is passed, so GitHub resolves the base to the repository's
+ *     default branch. `predictPrPlan` reproduces that locally from
+ *     `git symbolic-ref origin/HEAD` and labels it `baseSource: 'predicted'`,
+ *     because it is our reading of gh's choice, not an instruction to gh.
+ *   • NO `git push` runs. `gh pr create --head <branch>` publishes the branch
+ *     as a side effect, which is why `publishesBranch` is true and stated.
+ *
+ * ── DRIFT ──────────────────────────────────────────────────────────────────
+ * `PROPOSAL_BRANCH_PREFIX` is module-private in apply.ts, so the literal is
+ * repeated here. test/verse-github-proposal.test.ts reads apply.ts and fails
+ * if the two ever diverge — a disclosure that predicts the wrong branch name
+ * is worse than none.
+ *
+ * READ-ONLY. NEVER THROWS. Opens nothing, pushes nothing, spawns only the
+ * `git` reads core/git.ts already performs.
+ */
+import { defaultBranch, resolveGitHubOriginAuthority } from '../git.js';
+/**
+ * Mirrors `PROPOSAL_BRANCH_PREFIX` in src/core/inbox/apply.ts:52, which is not
+ * exported. Guarded against drift by test/verse-github-proposal.test.ts.
+ */
+export const VERSE_PROPOSAL_BRANCH_PREFIX = 'ashlr/proposal/';
+const MAX_BODY_PREVIEW_CHARS = 400;
+const MAX_REF_CHARS = 256;
+const MAX_TITLE_CHARS = 512;
+/**
+ * Only a real GitHub pull-request URL is ever surfaced as `prUrl`.
+ * `proposal.result` also carries gh's failure text on the unhappy path, and
+ * that text is not something to hand a UI as a link.
+ */
+const PR_URL_RE = /https:\/\/github\.com\/[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9_.-]+\/pull\/\d+/;
+const realGit = {
+    defaultBranch: (path) => defaultBranch(path),
+    nameWithOwner: (path) => resolveGitHubOriginAuthority(path),
+};
+/** The branch `applyPr` will create for this proposal id. */
+export function verseProposalBranch(proposalId) {
+    return `${VERSE_PROPOSAL_BRANCH_PREFIX}${proposalId}`;
+}
+function boundedString(value, max) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    return trimmed.length > max ? trimmed.slice(0, max) : trimmed;
+}
+function extractPrUrl(...candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'string')
+            continue;
+        const match = PR_URL_RE.exec(candidate);
+        if (match)
+            return match[0];
+    }
+    return null;
+}
+function unavailable(proposal, detail) {
+    return {
+        proposalId: proposal.id,
+        state: 'unavailable',
+        kind: proposal.kind,
+        repoPath: proposal.repo ?? null,
+        nameWithOwner: null,
+        branch: null,
+        branchSource: 'unknown',
+        base: null,
+        baseSource: 'unknown',
+        title: null,
+        bodyPreview: null,
+        bodyTruncated: false,
+        prUrl: null,
+        publishesBranch: false,
+        detail,
+    };
+}
+/**
+ * Describe what approving this proposal will do — or, once it has been
+ * applied, what it did.
+ *
+ * Returns `state: 'unavailable'` (and no branch/base) for anything that is not
+ * an outward-facing `pr` proposal, so a caller can render the disclosure
+ * unconditionally and let the shape decide whether there is anything to show.
+ */
+export function describeVersePrPlan(proposal, opts = {}) {
+    const git = opts.git ?? realGit;
+    if (proposal.kind !== 'pr') {
+        return unavailable(proposal, `kind ${proposal.kind} opens no pull request`);
+    }
+    const repoPath = boundedString(proposal.repo, 4_096);
+    if (!repoPath) {
+        return unavailable(proposal, 'proposal carries no repository, so no pull request can be opened');
+    }
+    const handoff = proposal.remoteHandoff;
+    const intent = proposal.localMergeIntent;
+    // Recorded values win over predicted ones: once apply has run, the plan
+    // stops being a forecast and becomes a record of what happened.
+    const recordedBranch = boundedString(handoff?.branch, MAX_REF_CHARS)
+        ?? boundedString(intent?.branch, MAX_REF_CHARS);
+    const branch = recordedBranch ?? verseProposalBranch(proposal.id);
+    const branchSource = recordedBranch ? 'recorded' : 'predicted';
+    const recordedBase = boundedString(handoff?.base, MAX_REF_CHARS)
+        ?? boundedString(intent?.base, MAX_REF_CHARS);
+    let base = recordedBase;
+    let baseSource = recordedBase ? 'recorded' : 'unknown';
+    if (!base) {
+        try {
+            base = boundedString(git.defaultBranch(repoPath), MAX_REF_CHARS);
+            baseSource = base ? 'predicted' : 'unknown';
+        }
+        catch {
+            base = null;
+            baseSource = 'unknown';
+        }
+    }
+    let nameWithOwner = null;
+    try {
+        nameWithOwner = boundedString(git.nameWithOwner(repoPath), 512);
+    }
+    catch {
+        nameWithOwner = null;
+    }
+    const prUrl = extractPrUrl(handoff?.prUrl, proposal.result);
+    const title = boundedString(proposal.title, MAX_TITLE_CHARS);
+    const summary = typeof proposal.summary === 'string' ? proposal.summary.trim() : '';
+    const bodyTruncated = summary.length > MAX_BODY_PREVIEW_CHARS;
+    const bodyPreview = summary.length === 0
+        ? null
+        : summary.slice(0, MAX_BODY_PREVIEW_CHARS);
+    const state = prUrl ? 'opened' : 'ready';
+    const target = nameWithOwner ?? repoPath;
+    const detail = state === 'opened'
+        ? `Opened ${prUrl} from ${branch} into ${base ?? 'the default branch'} on ${target}.`
+        : `Approving pushes ${branch} to ${target} and opens a pull request into ${base ?? 'its default branch'}.`;
+    return {
+        proposalId: proposal.id,
+        state,
+        kind: proposal.kind,
+        repoPath,
+        nameWithOwner,
+        branch,
+        branchSource,
+        base,
+        baseSource,
+        title,
+        bodyPreview,
+        bodyTruncated,
+        prUrl,
+        // True for a plan that has not run yet: `gh pr create --head <branch>`
+        // publishes the branch. Once the PR exists the push has already happened.
+        publishesBranch: state === 'ready',
+        detail,
+    };
+}
+/** Plans for several proposals, in the order given. Never throws. */
+export function describeVersePrPlans(proposals, opts = {}) {
+    const out = [];
+    for (const proposal of proposals) {
+        try {
+            out.push(describeVersePrPlan(proposal, opts));
+        }
+        catch {
+            out.push(unavailable(proposal, 'could not describe this proposal'));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=github-proposal.js.map

package/dist/core/verse/github-proposal.js.map

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

package/dist/core/verse/github-repo.d.ts

@@ -0,0 +1,104 @@
+/**
+ * core/verse/github-repo.ts — per-root GitHub surfacing for Ashlr Verse
+ * (docs/VERSE-WORKSPACES.md §2). READ-ONLY. NEVER THROWS.
+ *
+ * ── AUTH ───────────────────────────────────────────────────────────────────
+ * The `gh` CLI owns its own credentials, exactly as core/integrations/github.ts
+ * does. This module spawns the same binary with the same env hygiene and holds
+ * NO token of its own. There is no second credential path here, and no code
+ * path in this file reads, stores, or emits one.
+ *
+ * ── WHY IT SPAWNS `gh` AT ALL, GIVEN github.ts EXISTS ──────────────────────
+ * github.ts does the hard part and this module reuses its conventions
+ * verbatim (same binary, same 8 s timeout, same env, same never-throw
+ * contract). It does not reuse its two list functions, for two reasons that
+ * are contract-level rather than stylistic:
+ *
+ *   1. CI STATE. `listPrs()` requests `number,title,url,state,author` and
+ *      `PrSummary` has no checks field; `githubStatus().ci` is repo-wide,
+ *      derived from the last five *workflow runs*, and cannot say which PR is
+ *      red. §2 asks for "open PRs and their CI state", which needs
+ *      `statusCheckRollup` on the PR query. github.ts exports no runner to
+ *      borrow (`runGh` is private), so the query is issued here.
+ *   2. FAILURE vs EMPTY. `listPrs()`/`listIssues()` return `[]` both when gh
+ *      fails and when nothing is open. An operator staring at an empty panel
+ *      must be able to tell "nothing to do" from "could not look", so this
+ *      module keeps gh's null and projects it as `prsAvailable` /
+ *      `issuesAvailable`.
+ *
+ * Two `gh` calls per root, both list reads. Remote identity and default branch
+ * come from core/git.ts and cost no network at all.
+ *
+ * ── NO URL LEAVES THIS MODULE ──────────────────────────────────────────────
+ * `resolveGitHubOriginAuthorityDetails()` returns fetch/push URLs, and a
+ * supported GitHub HTTPS transport may carry credentials in its userinfo. Only
+ * `nameWithOwner` is read, so no remote URL can reach a response, a log, or an
+ * SSE frame. `gh`'s own stderr is never surfaced either — a failure becomes a
+ * fixed sentence, not a passthrough of whatever the tool printed.
+ */
+import type { VerseGithubChecks, VerseGithubIssue, VerseGithubPr, VerseGithubRepoSnapshot, VerseGithubSnapshot } from './github-types.js';
+/** Run `gh` in `cwd`; trimmed stdout, or null on ANY failure. Never throws. */
+export type VerseGithubGhRunner = (cwd: string, args: readonly string[]) => string | null;
+/** The git facts this module needs. Defaults to core/git.ts. */
+export interface VerseGithubGitProbe {
+    isRepo(path: string): boolean;
+    defaultBranch(path: string): string;
+    /** Lowercase `owner/name`, or null when origin does not resolve to one GitHub repo. */
+    nameWithOwner(path: string): string | null;
+}
+export interface VerseGithubReadOptions {
+    gh?: VerseGithubGhRunner;
+    git?: VerseGithubGitProbe;
+    /** 1..100, default 20. */
+    prLimit?: number;
+    /** 1..100, default 20. */
+    issueLimit?: number;
+    /** Clock seam for tests. */
+    now?: () => Date;
+    /** Directory existence seam for tests. */
+    isDirectory?: (path: string) => boolean;
+    /**
+     * Invoke `gh` for the PR and issue lists. Default true.
+     *
+     * `gh` is a synchronous subprocess with an 8 s ceiling, and the web server
+     * is single-threaded: reading N roots' lists in one request blocks it for up
+     * to N x 2 x 8 s. A multi-root listing therefore passes false and returns
+     * identity only (`listsRequested: false`), which costs nothing but two local
+     * `git` reads per root.
+     */
+    includeLists?: boolean;
+}
+/**
+ * Summarise one PR's `statusCheckRollup`.
+ *
+ * Handles both GraphQL variants gh emits: `CheckRun` (`status`/`conclusion`)
+ * and `StatusContext` (`state`). Entries of neither shape are counted as
+ * pending rather than silently dropped — an unrecognised check is not a
+ * passing one.
+ *
+ * FAILING WINS OVER PENDING, deliberately diverging from
+ * `resolveCiStatus()`'s first-match-wins scan in github.ts: that function
+ * summarises the last five workflow *runs* of a repo, where "something is
+ * running" is the useful headline. Here the operator is deciding whether to
+ * touch a specific PR, and a red check must not be hidden behind a queued one.
+ */
+export declare function summarizeCheckRollup(rollup: unknown): VerseGithubChecks;
+/**
+ * Parse `gh pr list --json <PR_JSON_FIELDS>` output.
+ *
+ * Malformed entries are DROPPED, not defaulted — the same choice
+ * `listIssues()` makes and the opposite of `listPrs()`, which coerces a
+ * missing number to 0. A PR row that cannot name its own number or URL is not
+ * something an operator should be offered a link to.
+ */
+export declare function parsePrList(parsed: unknown): VerseGithubPr[];
+/** Parse `gh issue list --json <ISSUE_JSON_FIELDS>`. Malformed entries dropped. */
+export declare function parseIssueList(parsed: unknown): VerseGithubIssue[];
+/**
+ * Read one workspace root. Never throws, never returns a remote URL, and never
+ * mutates anything — the only subprocesses are `git` reads via core/git.ts and
+ * two `gh` list reads.
+ */
+export declare function readVerseGithubRepo(path: string, opts?: VerseGithubReadOptions): VerseGithubRepoSnapshot;
+/** Read several roots in order, de-duplicated by path. Never throws. */
+export declare function readVerseGithubSnapshot(paths: readonly string[], opts?: VerseGithubReadOptions): VerseGithubSnapshot;