@proagentstore/cli 0.4.56 → 0.4.58

package/dist/browser-runner/coding/github-browse.js

@@ -0,0 +1,796 @@
+/**
+ * Read-only enumeration and search of GitHub organizations and repositories reachable
+ * by the machine's own `gh` credentials (#685, #686).
+ *
+ * ── Enumeration (#685)
+ *
+ * Uses `gh api` with `--paginate` to walk GitHub's REST API: first the list of
+ * organizations the authenticated user belongs to, then the repos for each (plus the
+ * user's own personal repos). Never writes, never mutates, never touches a credential
+ * beyond what `gh` already has.
+ *
+ * ── Search (#686)
+ *
+ * Uses GitHub's own search API (`GET /search/repositories`) via `gh api` — one request
+ * instead of a per-repo fan-out. GitHub's search index spans all repos the credential
+ * can read (public + private owned/member repos), so it is the correct tool for
+ * questions that span the whole account (open PRs, recently-active repos, topic match).
+ *
+ * Rate-limit strategy (#686 hard constraint): GitHub's authenticated search quota is
+ * 30 requests/min (separate from the 5 000/hr REST quota). To stay within it:
+ *
+ *   1. An in-process LRU cache (`SEARCH_CACHE`) holds the last result per canonical
+ *      query string. Cache entries are fresh for `SEARCH_TTL_MS` (5 minutes). A cache
+ *      hit is returned immediately without touching the network.
+ *   2. When GitHub returns 403 or the rate-limit error text, the function returns
+ *      `{ rateLimited: true, cachedAt }` and the cloud relays that to the caller.
+ *      The UI should tell the user to retry after a minute rather than looping.
+ *   3. `limit` is always bounded (default 30, max 100) — GitHub's own search cap is
+ *      100 items per request and paginating further risks burning the quota on one query.
+ *
+ * ── Scale
+ *
+ * The measured account (serge-ivo, 2026-08-16) has ~90 distinct owners and >1 000
+ * repos. A single unpaginated call cannot work: GitHub caps list endpoints at 100
+ * items per page. This module paginates by driving `gh api --paginate`, which
+ * follows GitHub's `Link: <…>; rel="next"` header automatically and collects all
+ * pages into one JSON array.
+ *
+ * Returning the full 1 000+ list in a single relay call is also unworkable: it would
+ * blow the relay timeout and the relay body limit. Instead callers pass `owner` to
+ * scope the query, `limit` to cap the result set, and `since` (an ISO timestamp) to
+ * request only repos pushed after a given point. The most useful default is sorting
+ * by last-pushed because the long tail is single-repo owners nobody has touched in
+ * years.
+ *
+ * ── Why `gh api`, not the GitHub API directly
+ *
+ * The machine's `gh auth login` already stores a token (or an OAuth device flow
+ * credential) under `~/.config/gh`. There is no token to extract, no secret to pass
+ * over the relay, and no auth surface to widen. `gh api` uses that credential
+ * transparently, exactly the way every other `gh` call in a coding session does.
+ *
+ * ── What remains open (stated rather than hidden)
+ *
+ * - `gh` must be on PATH. A machine without `gh` gets an error rather than an empty
+ *   list; the error is surfaced to the caller, not swallowed.
+ * - The machine credential determines what is visible. A deploy key sees exactly one
+ *   repository; a user account sees what that account can read.
+ * - Rate limits are GitHub's (5 000/hr for authenticated requests, 30/min for search).
+ *   Long enumerations of a large org will consume REST quota; `limit` keeps this
+ *   manageable. Search has its own quota; the cache and bounded limit guard it.
+ *
+ * ── Repository detail (#687)
+ *
+ * For a given `owner/repo`, returns the repository's open issues, open pull requests,
+ * and branches in three separate arrays. Each is fetched with a separate `gh api` call
+ * (no `--paginate` to stay within the REST quota) and bounded to a sensible limit.
+ * The same caching strategy as search (#686) is applied: results are held in-process
+ * for `DETAIL_TTL_MS` (2 minutes — shorter than search because PR/issue state changes
+ * faster than repo metadata) and the caller is told when data is from cache via
+ * `fromCache: true`. Read-only by construction: only `gh api GET` verbs are used.
+ *
+ * ── Credential scope and read-only enforcement (#688)
+ *
+ * The machine's `gh` credential is account-wide: it can write to any repository the
+ * user can reach, not just the ones this browser is browsing. The read-only invariant
+ * is enforced at the single function boundary that every `gh api` call passes through:
+ * `assertReadOnlyGhApiArgs` rejects any args that carry a non-GET HTTP method flag
+ * (`-X`, `--method`, or `--method=`). This means a future code path cannot accidentally
+ * issue a mutating call — the guard refuses before `spawnSync` is reached.
+ *
+ * `getGithubCredentialScope` surfaces the credential's effective scope to the user:
+ * the authenticated login and the organisations it belongs to. This is the answer to
+ * "what can this credential actually reach?" before any browse operation begins.
+ */
+import { spawnSync } from "node:child_process";
+/**
+ * HTTP methods that write state on GitHub. Any `gh api` call carrying one of these
+ * is a mutating call and is refused at this boundary.
+ *
+ * `GET` and `HEAD` (GitHub's `gh api` default is GET) are the only safe verbs.
+ * `DELETE` is included: while GitHub's REST spec marks it as "idempotent", it
+ * irreversibly removes resources and is not idempotent from a data-safety view.
+ */
+const WRITE_METHODS = new Set(["POST", "PATCH", "PUT", "DELETE"]);
+/**
+ * Guard that every `gh api` call in this module passes through (#688).
+ *
+ * Scans `args` for any HTTP method flag (`-X <method>`, `--method <method>`,
+ * `--method=<method>`) and returns `{ error }` if the resolved method is a write
+ * verb. Called from both `runGhApi` (paginated) and `runGhApiOnce` (single page),
+ * which are the only two `spawnSync` call sites in this file.
+ *
+ * Fails closed: an unrecognised / empty method passes through (gh defaults to GET).
+ * A caller that tries to be clever by lowercasing the method is also caught — the
+ * check is case-insensitive.
+ *
+ * Returns `undefined` when the args are safe; returns `{ error: string }` when
+ * a write method is found, so callers can return early in the same shape they use
+ * for every other error.
+ */
+export function assertReadOnlyGhApiArgs(args) {
+    let method = "";
+    let nextIsMethod = false;
+    for (const arg of args) {
+        if (nextIsMethod) {
+            method = arg;
+            nextIsMethod = false;
+            continue;
+        }
+        if (arg === "-X" || arg === "--method") {
+            nextIsMethod = true;
+            continue;
+        }
+        if (arg.startsWith("--method=")) {
+            method = arg.slice("--method=".length);
+        }
+    }
+    if (!method)
+        return undefined; // no explicit method — gh defaults to GET, safe
+    const upper = method.toUpperCase();
+    if (WRITE_METHODS.has(upper)) {
+        return { error: `github-browse: refused mutating gh api call (method: ${upper}) — this tool is read-only` };
+    }
+    return undefined;
+}
+/** The maximum `limit` the cloud may request from one call. */
+const MAX_LIMIT = 200;
+const DEFAULT_LIMIT = 50;
+/**
+ * Run one `gh api` call and return the parsed JSON array, or throw on failure.
+ *
+ * `--paginate` follows all pages and concatenates them into one array. Large orgs
+ * may generate hundreds of pages; `--jq` is used to project down to the fields we
+ * need BEFORE the pages are concatenated, keeping the payload small.
+ *
+ * `spawnSync` is used so the function is synchronous (matching the runner's
+ * synchronous endpoint contract — no event-loop gymnastics in `server.ts`). The
+ * runner's relay timeout is 120s; a full pagination of the largest org (~250 repos)
+ * takes under 10s in practice.
+ *
+ * Never throws — errors are returned as `{ error: string }`.
+ */
+function runGhApi(args) {
+    // Runtime read-only guard (#688): reject before spawnSync if the caller somehow
+    // passes a write method. This is the chokepoint for all paginated gh api calls.
+    const guardErr = assertReadOnlyGhApiArgs(args);
+    if (guardErr)
+        return guardErr;
+    const result = spawnSync("gh", ["api", "--paginate", ...args], {
+        encoding: "utf-8",
+        timeout: 60_000,
+        // Inherit the machine's PATH and credentials but nothing else sensitive.
+        env: process.env,
+    });
+    if (result.error) {
+        // ENOENT means `gh` is not installed.
+        const code = result.error?.code;
+        return { error: code === "ENOENT" ? "`gh` is not installed or not on PATH" : result.error.message };
+    }
+    if (result.status !== 0) {
+        const msg = String(result.stderr ?? "").slice(0, 500).trim() || `gh exited ${result.status ?? "unknown"}`;
+        return { error: msg };
+    }
+    // `gh api --paginate` writes each page's JSON array on a line; the full output
+    // is valid JSON only as a concatenated array. GitHub's paginator combines pages
+    // with `[][]` (two arrays back-to-back), which is not valid JSON. The `--jq`
+    // flag, when combined with `--paginate`, instead produces one JSON array overall,
+    // so we parse the whole stdout as a single array.
+    const raw = String(result.stdout ?? "").trim();
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    catch {
+        return { error: "gh returned unparsable output" };
+    }
+}
+/**
+ * Project a raw GitHub API repository object down to {@link GithubRepoEntry}.
+ *
+ * Accepts `unknown` because `gh api` output is untyped; every field is defensively
+ * coerced rather than assumed to be present. A missing field becomes its zero value:
+ * `null` for strings, `"main"` for the branch.
+ */
+function toEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const fullName = String(r.full_name ?? r.nameWithOwner ?? "");
+    const slash = fullName.lastIndexOf("/");
+    if (slash < 1)
+        return null;
+    const owner = fullName.slice(0, slash);
+    const name = fullName.slice(slash + 1);
+    // Operator-precedence guard: parenthesise the fallback so `??` doesn't bind into
+    // the ternary. Without parens `r.visibility ?? r.isPrivate === true ? … : …` parses
+    // as `(r.visibility ?? r.isPrivate === true) ? "private" : "public"`, which makes
+    // EVERY truthy visibility string map to "private".
+    const rawVis = r.visibility != null ? String(r.visibility) : (r.isPrivate === true ? "private" : "public");
+    const visibility = rawVis === "private" ? "private" : rawVis === "internal" ? "internal" : "public";
+    return {
+        owner,
+        name,
+        full_name: fullName,
+        visibility,
+        default_branch: String(r.default_branch ?? r.defaultBranchRef ?? "main") || "main",
+        pushed_at: r.pushed_at != null ? String(r.pushed_at) : (r.pushedAt != null ? String(r.pushedAt) : null),
+        language: r.language != null ? String(r.language) : null,
+    };
+}
+/**
+ * Enumerate GitHub organizations the authenticated user belongs to.
+ *
+ * Returns `{ orgs: string[] }` — the login names only, so the caller can let the
+ * user pick one before fetching its (potentially large) repo list.
+ *
+ * Returns `{ error: string }` when `gh` is unavailable or the call fails.
+ */
+export function listGithubOrgs() {
+    // Minimal projection: we only need the `login` field.
+    const jq = "[.[] | {login: .login}]";
+    const raw = runGhApi(["user/orgs", "--jq", jq]);
+    if ("error" in raw)
+        return raw;
+    const orgs = [];
+    for (const item of raw) {
+        if (item && typeof item === "object" && "login" in item) {
+            orgs.push(String(item.login));
+        }
+    }
+    return { orgs };
+}
+/**
+ * Report the effective credential scope of the machine's `gh` login (#688).
+ *
+ * Two sequential calls: `gh api user` (login) + `gh api user/orgs` (org list).
+ * Neither call mutates anything; both are read-only GET requests. The result tells
+ * the user which GitHub account the runner is acting as and which organisations
+ * that account can see, BEFORE any browse operation begins.
+ *
+ * Returns `{ error }` when `gh` is unavailable or unauthenticated.
+ */
+export function getGithubCredentialScope() {
+    // Fetch the authenticated user's login.
+    const userRaw = runGhApiOnce("user");
+    if (userRaw != null && typeof userRaw === "object" && "error" in userRaw) {
+        return userRaw;
+    }
+    const login = userRaw != null && typeof userRaw === "object"
+        ? String(userRaw.login ?? "")
+        : "";
+    // Fetch org memberships.
+    const orgsJq = "[.[] | {login: .login}]";
+    const orgsRaw = runGhApi(["user/orgs", "--jq", orgsJq]);
+    if ("error" in orgsRaw)
+        return orgsRaw;
+    const orgs = [];
+    for (const item of orgsRaw) {
+        if (item && typeof item === "object" && "login" in item) {
+            orgs.push(String(item.login));
+        }
+    }
+    return { checked: true, login, orgs };
+}
+/**
+ * Enumerate GitHub repositories reachable by the machine's `gh` credentials.
+ *
+ * Read-only by construction: the only `gh` call is `gh api GET /user/repos` or
+ * `gh api GET /orgs/{org}/repos`, which never mutates anything on GitHub.
+ *
+ * Never throws — every failure is a descriptive `{ error }` property.
+ */
+export function listGithubRepos(input = {}) {
+    const limit = Math.max(1, Math.min(MAX_LIMIT, Math.floor(Number(input.limit) || DEFAULT_LIMIT)));
+    const visibility = input.visibility === "public" ? "public" : input.visibility === "private" ? "private" : "all";
+    // JQ projection — only the fields we return, so large responses stay small.
+    // `pushed_at` is the sort key and the `since` filter key.
+    const jq = "[.[] | {full_name, visibility, default_branch, pushed_at, language}]";
+    let raw;
+    const owner = (input.owner ?? "").trim();
+    if (!owner || owner === "me") {
+        // Personal repos: https://docs.github.com/en/rest/repos/repos#list-repositories-for-the-authenticated-user
+        raw = runGhApi([`user/repos?sort=pushed&direction=desc&per_page=100&visibility=${visibility}&affiliation=owner`, "--jq", jq]);
+    }
+    else {
+        // Org repos: https://docs.github.com/en/rest/repos/repos#list-organization-repositories
+        raw = runGhApi([`orgs/${encodeURIComponent(owner)}/repos?sort=pushed&direction=desc&per_page=100&type=all`, "--jq", jq]);
+    }
+    if ("error" in raw)
+        return raw;
+    // Filter by `since` if requested.
+    const since = input.since ? new Date(input.since).getTime() : 0;
+    const all = [];
+    for (const item of raw) {
+        const entry = toEntry(item);
+        if (!entry)
+            continue;
+        if (since > 0) {
+            const pushedMs = entry.pushed_at ? new Date(entry.pushed_at).getTime() : 0;
+            if (pushedMs < since)
+                continue;
+        }
+        all.push(entry);
+    }
+    const hasMore = all.length > limit;
+    const repos = all.slice(0, limit);
+    return { checked: true, repos, hasMore, total: all.length };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// GitHub repository search (#686)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Maximum items GitHub's search API returns in a single request. */
+const SEARCH_MAX_LIMIT = 100;
+const SEARCH_DEFAULT_LIMIT = 30;
+const SEARCH_CACHE = new Map();
+/** How long a cached search result is considered fresh (milliseconds). */
+const SEARCH_TTL_MS = 5 * 60 * 1000; // 5 minutes
+/** Evict entries older than `SEARCH_TTL_MS` to keep the cache bounded. */
+function pruneSearchCache() {
+    const cutoff = Date.now() - SEARCH_TTL_MS;
+    for (const [key, entry] of SEARCH_CACHE) {
+        if (entry.fetchedAt < cutoff)
+            SEARCH_CACHE.delete(key);
+    }
+}
+/**
+ * Clear the entire search cache.
+ *
+ * Exported for test isolation only — tests must call this in `beforeEach` so
+ * that no cached result bleeds from one test case to the next.
+ */
+export function clearSearchCacheForTesting() {
+    SEARCH_CACHE.clear();
+}
+/**
+ * Build the canonical GitHub search query string from structured input.
+ *
+ * Qualifiers are appended in a fixed order so the same logical query always
+ * produces the same string (used as the cache key).
+ */
+function buildSearchQuery(input) {
+    const parts = [];
+    // Free-text query first.
+    if (input.query?.trim())
+        parts.push(input.query.trim());
+    // Structured qualifiers in stable order.
+    if (input.owner?.trim())
+        parts.push(`user:${input.owner.trim()}`);
+    if (input.language?.trim())
+        parts.push(`language:${input.language.trim()}`);
+    if (input.topic?.trim())
+        parts.push(`topic:${input.topic.trim()}`);
+    if (input.pushedAfter?.trim()) {
+        // GitHub expects YYYY-MM-DD; accept ISO with time and truncate.
+        const date = input.pushedAfter.trim().slice(0, 10);
+        parts.push(`pushed:>=${date}`);
+    }
+    // Fallback: when nothing is specified, search for repos the user can see.
+    // GitHub search requires at least one qualifier or text — use a sort-only query.
+    return parts.length > 0 ? parts.join(" ") : "is:public";
+}
+/**
+ * Project a raw GitHub search API item to {@link GithubSearchRepoEntry}.
+ *
+ * GitHub's search response nests the owner under `owner.login`. Fields that
+ * may be absent are coerced to their zero values rather than assumed present.
+ */
+function toSearchEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const fullName = String(r.full_name ?? "");
+    if (!fullName.includes("/"))
+        return null;
+    const slash = fullName.lastIndexOf("/");
+    const owner = fullName.slice(0, slash);
+    const name = fullName.slice(slash + 1);
+    const rawVis = r.visibility != null ? String(r.visibility) : (r.private === true ? "private" : "public");
+    const visibility = rawVis === "private" ? "private" : rawVis === "internal" ? "internal" : "public";
+    const topics = Array.isArray(r.topics) ? r.topics.filter((t) => typeof t === "string") : [];
+    return {
+        full_name: fullName,
+        owner,
+        name,
+        description: r.description != null ? String(r.description) : null,
+        visibility,
+        language: r.language != null ? String(r.language) : null,
+        pushed_at: r.pushed_at != null ? String(r.pushed_at) : null,
+        stars: typeof r.stargazers_count === "number" ? r.stargazers_count : 0,
+        forks: typeof r.forks_count === "number" ? r.forks_count : 0,
+        open_issues: typeof r.open_issues_count === "number" ? r.open_issues_count : 0,
+        topics,
+    };
+}
+/**
+ * Search GitHub repositories reachable by the machine's `gh` credentials.
+ *
+ * Uses GitHub's `/search/repositories` API (or `/search/issues?type=pr` when
+ * `openPrs` is set), which searches across all repos the credential can read
+ * without a per-repo fan-out. One API call, bounded result, rate-limit guarded
+ * by an in-process 5-minute cache.
+ *
+ * Read-only by construction: the only `gh` call is `gh api GET /search/*`.
+ *
+ * Never throws — every failure is a descriptive `{ error }` property.
+ */
+export function searchGithubRepos(input = {}) {
+    const limit = Math.max(1, Math.min(SEARCH_MAX_LIMIT, Math.floor(Number(input.limit) || SEARCH_DEFAULT_LIMIT)));
+    const sort = input.sort === "stars" ? "stars" : input.sort === "forks" ? "forks" : "updated";
+    let canonicalQuery;
+    let apiPath;
+    if (input.openPrs) {
+        // "Which repos have open pull requests?" uses the PR/issue search API.
+        // We build a query for open PRs and group by repository.
+        const prParts = ["is:pr", "is:open"];
+        if (input.owner?.trim())
+            prParts.push(`user:${input.owner.trim()}`);
+        if (input.pushedAfter?.trim()) {
+            const date = input.pushedAfter.trim().slice(0, 10);
+            prParts.push(`created:>=${date}`);
+        }
+        if (input.query?.trim())
+            prParts.push(input.query.trim());
+        canonicalQuery = prParts.join(" ");
+        // GitHub search API for issues/PRs — we'll extract unique repos from results.
+        apiPath = `search/issues?q=${encodeURIComponent(canonicalQuery)}&per_page=${Math.min(limit * 3, 100)}&sort=updated&order=desc`;
+    }
+    else {
+        canonicalQuery = buildSearchQuery(input);
+        apiPath = `search/repositories?q=${encodeURIComponent(canonicalQuery)}&per_page=${limit}&sort=${sort}&order=desc`;
+    }
+    // Check fresh cache before hitting the network.
+    const cacheKey = `${apiPath}:${limit}`;
+    const existing = SEARCH_CACHE.get(cacheKey);
+    if (existing && Date.now() - existing.fetchedAt < SEARCH_TTL_MS) {
+        return { ...existing.result, fromCache: true };
+    }
+    // GitHub search API returns a `{ total_count, items: [...] }` wrapper —
+    // NOT a bare array. We cannot use `--paginate` here because paginating search
+    // results would burn quota; instead we ask for exactly what we need in one page.
+    // `runGhApi` uses `--paginate` which doesn't work for search (it'd parse the
+    // wrapper as one item). We call spawnSync directly.
+    // Read-only by construction (#688): `apiPath` is a search endpoint path constructed
+    // above; no method override is passed. The only way in is a GET to search/repositories
+    // or search/issues — both read-only. `assertReadOnlyGhApiArgs` is not needed here
+    // because there are no caller-supplied args; the path is constructed, not forwarded.
+    const ghResult = spawnSync("gh", ["api", apiPath], {
+        encoding: "utf-8",
+        timeout: 30_000,
+        env: process.env,
+    });
+    if (ghResult.error) {
+        const code = ghResult.error?.code;
+        return { error: code === "ENOENT" ? "`gh` is not installed or not on PATH" : ghResult.error.message };
+    }
+    // GitHub returns 403 with a rate-limit body when the search quota is exhausted.
+    const isRateLimited = ghResult.status === 403 ||
+        String(ghResult.stderr ?? "").toLowerCase().includes("rate limit") ||
+        String(ghResult.stdout ?? "").includes("rate limit exceeded");
+    if (isRateLimited) {
+        // Return the stale cache entry (if any) with the rate-limited flag so the
+        // caller knows the data is old and retrying immediately won't help.
+        // Note: we do NOT call pruneSearchCache before this point so that stale entries
+        // are available here as a fallback — we only prune when we have fresh data to store.
+        const stale = SEARCH_CACHE.get(cacheKey);
+        if (stale) {
+            return { ...stale.result, fromCache: true, rateLimited: true };
+        }
+        return { error: "GitHub search rate limit exceeded — try again in a minute (30 requests/min quota)" };
+    }
+    if (ghResult.status !== 0) {
+        const msg = String(ghResult.stderr ?? "").slice(0, 500).trim() || `gh exited ${ghResult.status ?? "unknown"}`;
+        return { error: msg };
+    }
+    const raw = String(ghResult.stdout ?? "").trim();
+    if (!raw) {
+        return { error: "gh returned empty output" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { error: "gh returned unparsable output" };
+    }
+    const fetchedAt = Date.now();
+    const cachedAt = new Date(fetchedAt).toISOString();
+    // Prune stale entries now that we have fresh data to store. Pruning here (rather
+    // than at the start of the function) ensures stale entries survive to serve as
+    // rate-limit fallbacks when the network call fails with 403.
+    pruneSearchCache();
+    if (input.openPrs) {
+        // PR search response: `{ total_count, items: [{ repository: {...} }] }`
+        const wrapper = parsed;
+        const items = Array.isArray(wrapper.items) ? wrapper.items : [];
+        // De-duplicate by repository full_name — one row per repo.
+        const seen = new Set();
+        const repos = [];
+        for (const item of items) {
+            const prItem = item;
+            const repoObj = prItem.repository;
+            if (!repoObj || typeof repoObj !== "object")
+                continue;
+            const entry = toSearchEntry(repoObj);
+            if (!entry || seen.has(entry.full_name))
+                continue;
+            seen.add(entry.full_name);
+            repos.push(entry);
+            if (repos.length >= limit)
+                break;
+        }
+        const result = {
+            checked: true,
+            repos,
+            totalCount: typeof wrapper.total_count === "number" ? wrapper.total_count : repos.length,
+            fromCache: false,
+            cachedAt,
+            canonicalQuery,
+        };
+        SEARCH_CACHE.set(cacheKey, { result, fetchedAt });
+        return result;
+    }
+    // Repository search response: `{ total_count, items: [{…repo…}] }`.
+    const wrapper = parsed;
+    const items = Array.isArray(wrapper.items) ? wrapper.items : [];
+    const repos = [];
+    for (const item of items) {
+        const entry = toSearchEntry(item);
+        if (entry)
+            repos.push(entry);
+    }
+    const result = {
+        checked: true,
+        repos,
+        totalCount: typeof wrapper.total_count === "number" ? wrapper.total_count : repos.length,
+        fromCache: false,
+        cachedAt,
+        canonicalQuery,
+    };
+    SEARCH_CACHE.set(cacheKey, { result, fetchedAt });
+    return result;
+}
+/** Maximum items to return per list. Mirrors GitHub's own page cap for these endpoints. */
+const DETAIL_MAX_LIMIT = 100;
+const DETAIL_DEFAULT_LIMIT = 30;
+/** How long a cached detail result is considered fresh (milliseconds). */
+const DETAIL_TTL_MS = 2 * 60 * 1000; // 2 minutes — issues/PRs change faster than repo metadata
+const DETAIL_CACHE = new Map();
+/** Evict stale entries to keep the cache bounded. */
+function pruneDetailCache() {
+    const cutoff = Date.now() - DETAIL_TTL_MS;
+    for (const [key, entry] of DETAIL_CACHE) {
+        if (entry.fetchedAt < cutoff)
+            DETAIL_CACHE.delete(key);
+    }
+}
+/**
+ * Clear the entire detail cache.
+ *
+ * Exported for test isolation only — tests must call this in `beforeEach` so
+ * that no cached result bleeds from one test case to the next.
+ */
+export function clearDetailCacheForTesting() {
+    DETAIL_CACHE.clear();
+}
+/**
+ * Run a single `gh api` call (no `--paginate`) and return the parsed JSON, or
+ * `{ error }` on failure. Used for the detail endpoints where pagination would
+ * consume too much quota; instead `per_page` is bounded by `limit`.
+ *
+ * Returns the raw parsed value (object or array), not wrapped in `unknown[]`,
+ * because the detail API paths return both array and object shapes.
+ */
+function runGhApiOnce(path) {
+    // Read-only by construction (#688): `path` is a REST resource path, never a method
+    // flag. The only argument to `gh api` is the path; the default method is GET and
+    // there is no way to override it from this call site. `assertReadOnlyGhApiArgs`
+    // covers `runGhApi` (where args is caller-supplied); here the signature enforces it.
+    const result = spawnSync("gh", ["api", path], {
+        encoding: "utf-8",
+        timeout: 30_000,
+        env: process.env,
+    });
+    if (result.error) {
+        const code = result.error?.code;
+        return { error: code === "ENOENT" ? "`gh` is not installed or not on PATH" : result.error.message };
+    }
+    if (result.status !== 0) {
+        const msg = String(result.stderr ?? "").slice(0, 500).trim() || `gh exited ${result.status ?? "unknown"}`;
+        return { error: msg };
+    }
+    const raw = String(result.stdout ?? "").trim();
+    if (!raw)
+        return { error: "gh returned empty output" };
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { error: "gh returned unparsable output" };
+    }
+}
+/** Project a raw GitHub issue object to {@link GithubIssueEntry}. */
+function toIssueEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const num = typeof r.number === "number" ? r.number : Number(r.number);
+    if (!Number.isFinite(num) || num < 1)
+        return null;
+    const title = r.title != null ? String(r.title) : "";
+    const rawState = String(r.state ?? "open");
+    const state = rawState === "closed" ? "closed" : "open";
+    const author = r.user != null && typeof r.user === "object"
+        ? (String(r.user.login ?? "") || null)
+        : null;
+    const labels = Array.isArray(r.labels)
+        ? r.labels.map((l) => {
+            if (typeof l === "string")
+                return l;
+            if (l && typeof l === "object")
+                return String(l.name ?? "");
+            return "";
+        }).filter(Boolean)
+        : [];
+    const assignee = r.assignee != null && typeof r.assignee === "object"
+        ? (String(r.assignee.login ?? "") || null)
+        : null;
+    return {
+        number: num,
+        title,
+        state,
+        author,
+        created_at: r.created_at != null ? String(r.created_at) : "",
+        updated_at: r.updated_at != null ? String(r.updated_at) : "",
+        labels,
+        assignee,
+    };
+}
+/** Project a raw GitHub pull request object to {@link GithubPullEntry}. */
+function toPullEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const num = typeof r.number === "number" ? r.number : Number(r.number);
+    if (!Number.isFinite(num) || num < 1)
+        return null;
+    const title = r.title != null ? String(r.title) : "";
+    // GitHub marks merged PRs as `state: "closed"` with a `merged_at` timestamp.
+    const rawState = String(r.state ?? "open");
+    const merged = r.merged_at != null && r.merged_at !== null;
+    const state = merged ? "merged" : rawState === "closed" ? "closed" : "open";
+    const author = r.user != null && typeof r.user === "object"
+        ? (String(r.user.login ?? "") || null)
+        : null;
+    const head = r.head != null && typeof r.head === "object"
+        ? String(r.head.ref ?? "") : "";
+    const base = r.base != null && typeof r.base === "object"
+        ? String(r.base.ref ?? "") : "";
+    const labels = Array.isArray(r.labels)
+        ? r.labels.map((l) => {
+            if (typeof l === "string")
+                return l;
+            if (l && typeof l === "object")
+                return String(l.name ?? "");
+            return "";
+        }).filter(Boolean)
+        : [];
+    return {
+        number: num,
+        title,
+        state,
+        author,
+        created_at: r.created_at != null ? String(r.created_at) : "",
+        updated_at: r.updated_at != null ? String(r.updated_at) : "",
+        head_branch: head,
+        base_branch: base,
+        draft: r.draft === true,
+        labels,
+    };
+}
+/** Project a raw GitHub branch object to {@link GithubBranchEntry}. */
+function toBranchEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const name = r.name != null ? String(r.name) : "";
+    if (!name)
+        return null;
+    const commit = r.commit != null && typeof r.commit === "object"
+        ? r.commit
+        : {};
+    const sha = commit.sha != null ? String(commit.sha) : "";
+    return {
+        name,
+        sha,
+        protected: r.protected === true,
+    };
+}
+/**
+ * Fetch issues, pull requests, and branches for a given `owner/repo`.
+ *
+ * Read-only by construction: the only `gh` calls are `gh api GET /repos/{owner}/{repo}/issues`,
+ * `/pulls`, and `/branches` — all read endpoints. Never writes, never mutates anything.
+ *
+ * Results are cached in-process for {@link DETAIL_TTL_MS} (2 minutes) to guard against
+ * repeated calls from the same runner session. Cache hits return `fromCache: true`.
+ *
+ * Never throws — every failure is a descriptive `{ error }` property.
+ */
+export function getGithubRepoDetail(input) {
+    const repoSlug = (input.repo ?? "").trim();
+    // Validate the slug — must be "owner/repo" with no extra slashes.
+    if (!repoSlug?.includes("/") || repoSlug.split("/").length !== 2) {
+        return { error: "repo must be an \"owner/repo\" slug (e.g. \"serge-ivo/my-app\")" };
+    }
+    const limit = Math.max(1, Math.min(DETAIL_MAX_LIMIT, Math.floor(Number(input.limit) || DETAIL_DEFAULT_LIMIT)));
+    const state = input.state === "all" ? "all" : "open";
+    const cacheKey = `${repoSlug}:${limit}:${state}`;
+    const existing = DETAIL_CACHE.get(cacheKey);
+    if (existing && Date.now() - existing.fetchedAt < DETAIL_TTL_MS) {
+        return { ...existing.result, fromCache: true };
+    }
+    const encodedRepo = repoSlug.split("/").map(encodeURIComponent).join("/");
+    // Fetch issues (GitHub issues endpoint returns issues only, not PRs, when `pulls=false`
+    // is implicit). Use `?state=open&per_page=N` to bound the result.
+    const issuesRaw = runGhApiOnce(`repos/${encodedRepo}/issues?state=${state}&per_page=${limit}&sort=updated&direction=desc`);
+    if (issuesRaw != null && typeof issuesRaw === "object" && "error" in issuesRaw) {
+        return issuesRaw;
+    }
+    // Fetch pull requests.
+    const pullsRaw = runGhApiOnce(`repos/${encodedRepo}/pulls?state=${state}&per_page=${limit}&sort=updated&direction=desc`);
+    if (pullsRaw != null && typeof pullsRaw === "object" && "error" in pullsRaw) {
+        return pullsRaw;
+    }
+    // Fetch branches (no state filter — branches are either there or not).
+    const branchesRaw = runGhApiOnce(`repos/${encodedRepo}/branches?per_page=${limit}`);
+    if (branchesRaw != null && typeof branchesRaw === "object" && "error" in branchesRaw) {
+        return branchesRaw;
+    }
+    // Project down to typed entries, skipping malformed items.
+    const issues = [];
+    if (Array.isArray(issuesRaw)) {
+        for (const item of issuesRaw) {
+            // GitHub's /issues endpoint also returns pull requests — exclude them so the
+            // caller gets a clean issues-only list (PRs are in the pulls array).
+            if (item && typeof item === "object" && item.pull_request != null)
+                continue;
+            const entry = toIssueEntry(item);
+            if (entry)
+                issues.push(entry);
+        }
+    }
+    const pulls = [];
+    if (Array.isArray(pullsRaw)) {
+        for (const item of pullsRaw) {
+            const entry = toPullEntry(item);
+            if (entry)
+                pulls.push(entry);
+        }
+    }
+    const branches = [];
+    if (Array.isArray(branchesRaw)) {
+        for (const item of branchesRaw) {
+            const entry = toBranchEntry(item);
+            if (entry)
+                branches.push(entry);
+        }
+    }
+    const fetchedAt = Date.now();
+    const cachedAt = new Date(fetchedAt).toISOString();
+    pruneDetailCache();
+    const result = {
+        checked: true,
+        repo: repoSlug,
+        issues,
+        pulls,
+        branches,
+        fromCache: false,
+        cachedAt,
+    };
+    DETAIL_CACHE.set(cacheKey, { result, fetchedAt });
+    return result;
+}