@catalyst-cloud/catalyst-skills 0.4.0 → 0.7.0

package/dist/events.js

@@ -0,0 +1,106 @@
+import { flagInt, flagString, positionals } from "./args.js";
+import { apiBase, requireConfig } from "./config.js";
+import { CliError, UsageError } from "./errors.js";
+import { authStrategyFor } from "./oauth.js";
+const eventsModule = "@catalyst-cloud/sdk/events";
+export const loadEventsSdk = () => import(eventsModule);
+export async function createEventSync(ctx, deps = {}) {
+    const cfg = requireConfig(ctx);
+    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
+    const auth = authStrategyFor(ctx, cfg);
+    if (auth.kind === "cookie")
+        throw new CliError("event sync requires a token or OAuth session", "events-auth");
+    return new sdk.CatalystEventSync({
+        baseUrl: apiBase(cfg),
+        auth,
+        tenantId: cfg.account,
+        fetch: ctx.fetch,
+    });
+}
+export async function cmdEvents(args, ctx, deps = {}) {
+    const [sub] = positionals(args);
+    if (!sub)
+        throw new UsageError("events needs a subcommand: tail | wait-for | query");
+    if (!["tail", "wait-for", "query"].includes(sub))
+        throw new UsageError(`unknown events subcommand: ${sub}`);
+    const cfg = requireConfig(ctx);
+    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
+    const directory = flagString(args, "directory") ??
+        sdk.defaultEventCacheDirectory(cfg.account);
+    const after = startingCursor(args, sub === "query");
+    const matches = matcher(args);
+    if (sub === "query") {
+        const events = (await sdk.readCachedEvents({ tenantId: cfg.account, directory, after }))
+            .filter(matches)
+            .slice(-flagInt(args, "limit", 50));
+        for (const event of events)
+            ctx.stdout(JSON.stringify(event));
+        return 0;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort(deps.signal?.reason);
+    if (deps.signal?.aborted)
+        abort();
+    else
+        deps.signal?.addEventListener("abort", abort, { once: true });
+    const timer = sub === "wait-for"
+        ? setTimeout(() => controller.abort(new Error("event wait timed out")), flagInt(args, "timeout", 300) * 1_000)
+        : undefined;
+    try {
+        for await (const event of sdk.tailCachedEvents({
+            tenantId: cfg.account,
+            directory,
+            after,
+            signal: controller.signal,
+        })) {
+            if (!matches(event))
+                continue;
+            ctx.stdout(JSON.stringify(event));
+            if (sub === "wait-for")
+                return 0;
+        }
+        return sub === "wait-for" ? 1 : 0;
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            return sub === "wait-for" ? 1 : 0;
+        if (error.code === "ENOENT")
+            throw new CliError(`event cache is absent at ${directory} — start it with: catalyst-skills replica start --detach`, "events-absent", 3);
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        deps.signal?.removeEventListener("abort", abort);
+    }
+}
+function startingCursor(args, history) {
+    const requested = flagString(args, "after");
+    if (requested !== undefined) {
+        const parsed = Number(requested);
+        if (!Number.isSafeInteger(parsed) || parsed < 0)
+            throw new UsageError("--after must be a non-negative event sequence");
+        return parsed;
+    }
+    if (history)
+        return undefined;
+    return undefined;
+}
+function matcher(args) {
+    const type = flagString(args, "type");
+    const ticket = flagString(args, "ticket")?.toUpperCase();
+    return (event) => (!type || event.type === type) &&
+        (!ticket || payloadReferences(event.payload, ticket));
+}
+function payloadReferences(value, ticket) {
+    if (typeof value === "string")
+        return value.toUpperCase() === ticket;
+    if (Array.isArray(value))
+        return value.some((item) => payloadReferences(item, ticket));
+    if (!value || typeof value !== "object")
+        return false;
+    return Object.entries(value).some(([key, item]) => ["ticket", "identifier", "workItemKey", "issueIdentifier"].includes(key) &&
+        typeof item === "string"
+        ? item.toUpperCase() === ticket
+        : payloadReferences(item, ticket));
+}

package/dist/execution.js

@@ -3,8 +3,8 @@
 // exclusion reason and unknown the cloud names; an unlisted reason prints its raw string, never nothing.
 import { flagBool, flagString, positionals } from "./args.js";
 import { normalizeBaseUrl, requireConfig } from "./config.js";
-import { loadContract } from "./contract.js";
-import { CliError, UsageError } from "./errors.js";
+import { findTeamByKey, loadContract } from "./contract.js";
+import { CliError, MeError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
 /** Every exclusion reason the eligibility evaluator names, in plain English. */
 export const EXCLUSION_REASONS = {
@@ -37,13 +37,20 @@ export const EXCLUSION_REASONS = {
     retry_backoff: "the failed phase is retrying in place and waiting out its backoff",
     routing_unavailable: "the unit was claimed and refused at kickoff (no route, no eligible coding-account slot, or the provider is unavailable)",
     repo_paused: "an operator paused the repository",
-    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired",
+    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired; `catalyst-skills release <ticket>` releases the park once its cause is fixed",
+    phase_parked: "the offered phase is parked after repeated failures or the repair-round cap; `catalyst-skills release <ticket>` releases it once its cause is fixed",
+    later_phase_lease_held: "an earlier phase is offered while a live container still holds a later phase of this ticket",
+    human_owned_pr: "a person's own pull request holds this ticket; it releases itself when that PR closes or merges",
+    review_not_converging: "review and repair kept finding new problems without converging; a person reads the findings and comments on the ticket to resume",
+    round_threshold: "the ticket spent its lifetime repair budget; answering its ask or pushing a fix buys one more cycle",
+    claim_storm: "this unit was claimed too many times in the last hour, so it waits out the hour; nothing to release",
+    repo_at_capacity: "the repository's runner seats are all in use; it starts when one frees",
 };
 /** Every fail-closed unknown the evaluator names. */
 export const UNKNOWN_REASONS = {
-    ordering_never_published: "the dispatch order has never been published for this team",
+    ordering_never_published: "the dispatch order has never been published for this team — usually because the team has no saved stage mapping, which does not clear by itself",
     ordering_stale: "the dispatch order is stale",
-    workflow_mapping_unknown: "the team's workflow mapping could not be read",
+    workflow_mapping_unknown: "the team has no saved stage mapping for dispatch, pr, done and canceled (or a mapped stage was deleted); it does not clear by itself — a tenant owner or admin maps the team in Settings → Linear teams",
     ticket_unknown: "the ticket is not in the mirror",
     dependency_snapshot_unknown: "the dependency snapshot has never completed",
     blocker_unknown: "a blocking relation could not be resolved",
@@ -61,7 +68,41 @@ export function describeReason(reason) {
         return "no reason was given";
     return EXCLUSION_REASONS[reason] ?? UNKNOWN_REASONS[reason] ?? `reason "${reason}" (not in this bundle's table; read it as the cloud spelled it)`;
 }
-export function renderExplain(ticket, row, team, knownState) {
+/** The contract spells the same concept `status`; normalize onto the `cause` the renderer uses.
+ *  `"open"` and an absent/shapeless gate both mean "nothing to report" — null. An unrecognized
+ *  status is passed through as `cause`, never swallowed (D2/D3 — CTC-2208). */
+export function gateFromContract(g) {
+    if (!g || typeof g.status !== "string")
+        return null;
+    if (g.status === "open")
+        return null;
+    return { cause: g.status, missingSlots: g.missingSlots, remedy: g.remedy, source: "contract" };
+}
+/** True when the live eligibility read failed in a way a cached gate may stand in for: the read was
+ *  UNAVAILABLE (network/timeout/non-JSON, or a 404/5xx). A cloud that ANSWERED — 401/403/400 — is
+ *  refusing, not silent, and a cached gate must never hide that refusal behind an unrelated mapping
+ *  story (D4 — CTC-2208). */
+export function liveReadMayFallBack(err) {
+    if (err instanceof MeError)
+        return true;
+    if (err instanceof CliError)
+        return err.status === undefined || err.status === 404 || err.status >= 500;
+    return false;
+}
+export function renderDispatchGate(ticket, team, gate) {
+    const slots = (gate.missingSlots ?? []).join(", ");
+    const why = gate.cause === "mapping_state_unresolved"
+        ? `the stage team ${team} mapped for ${slots} no longer exists in Linear.`
+        : gate.cause === "mapping_missing"
+            ? `team ${team} has no saved stage mapping for ${slots}.`
+            : `team ${team} cannot be dispatched (${gate.cause}).`;
+    return [`${ticket} cannot start: ${why}`, gate.remedy].filter(Boolean).join(" ");
+}
+export function renderExplain(ticket, row, team, knownState, gate) {
+    // An unmapped team has no queue and so no rows; its gate is the whole answer, and it outranks the
+    // Backlog probe below, which would otherwise call the team's own Todo "not a dispatch state".
+    if (gate)
+        return renderDispatchGate(ticket, team, gate);
     if (!row) {
         // A null dispatch row is not proof the ticket does not exist — the explainer is a dispatch scan. When
         // `knownState` is set (the mirror answered GET /issues/:id) the ticket is real; it just sits outside a
@@ -116,25 +157,90 @@ export async function cmdExplain(args, ctx) {
         throw new UsageError(`"${ticket}" is not a ticket identifier (expected KEY-123)`);
     const team = ticket.slice(0, dash).toUpperCase();
     const api = apiClient(cfg, ctx);
-    const res = await api.getJson("/api/v1/work-eligibility", {
-        query: { team, capabilities: doc.ladder.phases.join(",") },
-    });
-    const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
-    const row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
-    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as known.
-    // The mirror compares identifiers exactly, so normalize (uppercase) as the row lookup above does —
-    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 as unknown.
+    // The cached contract's own gate for this team. Read BEFORE the live call so it can stand in when
+    // that call cannot be made at all. A team absent from the contract simply has none.
+    const cachedGate = gateFromContract(findTeamByKey(doc, team)?.dispatchGate);
+    let row = null;
     let knownState = null;
+    let liveGate = null;
+    let liveFailure = null;
+    let liveGateRaw = null;
+    // This `try` wraps the eligibility read ALONE. It used to span the mirror probe below as well,
+    // which broke both reads at once: a probe outage was reported as "the live eligibility read was
+    // unavailable", and an eligibility outage skipped the probe entirely so `knownState` stayed null
+    // and a mistyped id inherited the team-wide gate — the very bug 4defc34 was written to fix.
+    try {
+        const res = await api.getJson("/api/v1/work-eligibility", { query: { team, capabilities: doc.ladder.phases.join(",") } });
+        const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
+        row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
+        liveGateRaw = res.body.eligibility?.dispatchGate ?? null;
+    }
+    catch (err) {
+        // A cached gate is an answer the live read cannot give right now — but ONLY for a failure that
+        // means "unavailable". A 401/403/400 is the cloud answering, and must still refuse (CTC-2208 D4).
+        if (!cachedGate || !liveReadMayFallBack(err))
+            throw err;
+        liveFailure = err instanceof Error ? err : new Error(String(err));
+    }
+    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as
+    // known. The mirror compares identifiers exactly, so normalize as the row lookup above does —
+    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 unknown.
+    // Deliberately OUTSIDE the `try`: the probe is the ONLY read that can prove this id exists, so it
+    // must still run when the eligibility read was unavailable, and its own failure must surface as
+    // itself — a refusal naming the /issues/ read — never as a gate paragraph or as an eligibility
+    // failure. That is the pre-4defc34 behaviour for this call and it is restored unchanged.
     if (!row) {
         const probe = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket.toUpperCase())}`, { accept: [404] });
         if (probe.status !== 404)
             knownState = typeof probe.body?.state === "string" ? probe.body.state : "unknown";
     }
+    // The gate is TEAM-wide: it can say why a real ticket in that team cannot start, never that this
+    // id exists. Applied only when the probe found the ticket; a 404 keeps the unknown wording.
+    liveGate = !row && knownState && liveGateRaw ? { ...liveGateRaw, source: "live" } : null;
+    // The cached gate is team-wide too, so it answers on exactly the same condition as the live one:
+    // the mirror found the ticket and no row explains it. An unavailable eligibility read licenses the
+    // FALLBACK, never the claim that this id exists.
+    const usingCached = !liveGate && !row && knownState !== null;
+    const gate = liveGate ?? (usingCached ? cachedGate : null);
+    // Both sides spoke and disagreed: the live read wins, and the paragraph says the cache disagreed.
+    // Computed together with its sentence so the "live is non-null here" fact never needs re-asserting.
+    let overridden = null;
+    let overriddenNote = null;
+    if (liveGate && cachedGate && liveGate.cause !== cachedGate.cause) {
+        overridden = cachedGate;
+        overriddenNote = `The cached tenant contract says ${cachedGate.cause}; this live eligibility read says ${liveGate.cause} and wins.`;
+    }
+    // A live read that produced a row contradicts a cached "nothing in this team can start".
+    const contradictedByRow = !liveFailure && row && cachedGate ? cachedGate : null;
+    const parts = [renderExplain(ticket, row, team, knownState, gate)];
+    if (gate && gate === cachedGate) {
+        parts.push(liveFailure
+            ? `Read from the cached tenant contract: the live eligibility read was unavailable (${liveFailure.message}).`
+            : "Read from the cached tenant contract: this cloud's eligibility read sent no dispatch gate.");
+    }
+    if (overriddenNote)
+        parts.push(overriddenNote);
+    // The mirror answered and the eligibility read did not: say so, rather than let a network outage
+    // read as a confident verdict from an explainer this run never actually reached.
+    if (liveFailure && gate !== cachedGate) {
+        parts.push(`The live eligibility read was unavailable (${liveFailure.message}); only the mirror answered.`);
+    }
+    if (contradictedByRow) {
+        parts.push(`The cached tenant contract says ${contradictedByRow.cause} for team ${team}; this live eligibility read has a row for ${ticket} and wins.`);
+    }
+    const explanation = parts.join(" ");
     if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team, knownState) }));
+        ctx.stdout(JSON.stringify({
+            ticket,
+            row,
+            ...(gate ? { dispatchGate: gate } : {}),
+            ...(overridden || contradictedByRow ? { dispatchGateOverridden: overridden ?? contradictedByRow } : {}),
+            ...(liveFailure ? { liveReadFailed: liveFailure.message } : {}),
+            explanation,
+        }));
     }
     else {
-        ctx.stdout(renderExplain(ticket, row, team, knownState));
+        ctx.stdout(explanation);
     }
     return 0;
 }
@@ -237,7 +343,7 @@ export function renderAccount(a) {
  * ahead of some tenants' deployed mirror; a 404 there means "your cloud is older than this bundle",
  * which is a different fact from "you have no coding accounts" and must never print as the latter.
  */
-function needsNewerCloud(what, cfg) {
+export function needsNewerCloud(what, cfg) {
     return new CliError(`${what} needs a newer Catalyst Cloud than ${normalizeBaseUrl(cfg.baseUrl)} is running — the route answered 404. Nothing is wrong with your tenant; ask your operator when the mirror last deployed.`, "route-not-deployed", 3, 404);
 }
 export async function cmdAccounts(args, ctx) {
@@ -310,7 +416,29 @@ export function renderHistory(ticket, doc) {
         lines.push(`Remediate rounds dispatched: ${doc.remediate.roundsDispatched}${typeof doc.remediate.cap === "number" ? ` (cap ${doc.remediate.cap})` : ""}`);
     }
     if (doc.park) {
-        lines.push(`Parked at ${doc.park.phase ?? "?"} (${doc.park.sentinel}): ${doc.park.selfReleases ? "releases itself" : "needs an operator"} — ${doc.park.releasedBy}`);
+        lines.push(`Parked at ${doc.park.phase ?? "?"} (${doc.park.sentinel}): ${doc.park.selfReleases ? "releases itself" : "does not release itself"} — ${doc.park.releasedBy}`);
+    }
+    // Absent (an older cloud) prints nothing; `null` is a table that could not be read.
+    if (doc.governors === null) {
+        lines.push("Held by: could not be read (unreadable, not empty)");
+    }
+    else if (doc.governors !== undefined && doc.governors.length > 0) {
+        lines.push("Held by:");
+        for (const g of doc.governors) {
+            lines.push(`  ${g.kind}${g.phase ? ` at ${g.phase}` : ""}${g.sentinel ? ` (${g.sentinel})` : ""} — ${g.release ?? "no release named"}`);
+        }
+    }
+    if (doc.releases === null) {
+        lines.push("Releases: could not be read (unreadable, not empty)");
+    }
+    else if (doc.releases !== undefined && doc.releases.length > 0) {
+        lines.push("Releases (newest first):");
+        for (const r of doc.releases) {
+            const what = r.outcome === "released"
+                ? `released: ${(r.released ?? []).map((a) => `${a.op}${a.phase ? ` ${a.phase}` : ""}`).join(", ")}`
+                : `refused: ${(r.refused ?? []).map((x) => x.code).join(", ")}`;
+            lines.push(`  ${new Date(r.atMs).toISOString()} ${r.outcome} by ${r.actor.kind}:${r.actor.id} — "${r.because}" — ${what}`);
+        }
     }
     for (const l of doc.lease ?? [])
         lines.push(`Live lease: ${l.phase} held by ${l.holder ?? "?"} until ${new Date(l.deadlineMs).toISOString()}`);

package/dist/pagination.js

@@ -0,0 +1,76 @@
+// pagination.ts — the mirror's keyset contract, followed. `/issues` and `/pulls` answer a page plus
+// three headers: X-Mirror-Cursor (the head seq the page is consistent with), X-Mirror-Total (the
+// WHOLE scope's count, independent of the page) and X-Mirror-Next-Cursor — present ONLY while rows
+// remain, ABSENT on the last page. A caller that ignores them gets a page and believes it is the
+// answer, which is the whole of CTC-2010.
+//
+// The SDK's createTenantClient parses these same three headers into a typed KeysetPageMeta, and this
+// module deliberately does not use it: that client takes a STATIC `key`, while this bundle resolves
+// its bearer fresh per request through `bearerFor` (an OAuth session refreshes mid-walk), and `ask`
+// must keep working on a runtime where the SDK cannot load (src/sdk.ts). Adopting it is the CTC-2004
+// Tier 2 migration that also deletes transport.ts — not this change.
+import { CliError } from "./errors.js";
+export const NEXT_CURSOR_HEADER = "x-mirror-next-cursor";
+export const TOTAL_HEADER = "x-mirror-total";
+/** The server clamps every page to this regardless of the requested `limit` (MAX_VIEW_LIMIT). */
+export const SERVER_PAGE_CAP = 500;
+/** 100 pages × 500 rows = 50,000. Reaching it is a refusal, not an ending. */
+export const MAX_PAGES = 100;
+/** The API answers a list route with either a bare array or `{rows|items|issues|...: []}`. */
+export function rowsOf(body) {
+    if (Array.isArray(body))
+        return body;
+    if (body && typeof body === "object") {
+        for (const key of ["rows", "items", "issues", "pulls", "projects", "cycles", "results", "changes", "data"]) {
+            const v = body[key];
+            if (Array.isArray(v))
+                return v;
+        }
+    }
+    return [];
+}
+function readTotal(headers) {
+    const raw = headers.get(TOTAL_HEADER);
+    if (raw === null)
+        return null;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : null;
+}
+export async function fetchPage(api, path, query) {
+    const res = await api.getJson(path, { query });
+    const next = res.headers.get(NEXT_CURSOR_HEADER);
+    return {
+        rows: rowsOf(res.body),
+        nextCursor: next === null || next === "" ? null : next,
+        total: readTotal(res.headers),
+    };
+}
+export async function fetchAllPages(api, path, query) {
+    const rows = [];
+    const seen = new Set();
+    let after;
+    let total = null;
+    for (let pages = 1; pages <= MAX_PAGES; pages++) {
+        const page = await fetchPage(api, path, { ...query, limit: SERVER_PAGE_CAP, after });
+        rows.push(...page.rows);
+        if (page.total !== null)
+            total = page.total;
+        if (page.nextCursor === null)
+            return { rows, total, pages };
+        // ⛔ A cursor that does not advance is an infinite loop, not a long read.
+        if (seen.has(page.nextCursor)) {
+            throw new CliError(`GET ${path} repeated a page cursor after ${rows.length} rows — the cloud is not advancing the keyset, so --all cannot finish`, "pagination-stalled", 1);
+        }
+        seen.add(page.nextCursor);
+        after = page.nextCursor;
+    }
+    throw new CliError(`GET ${path} still had pages after ${MAX_PAGES} of them (${rows.length} rows) — narrow the scope with --team/--project/--state, or read this through the replica`, "pagination-overrun", 1);
+}
+/** ⛔ N IS WHAT THE SERVER SENT, not what a client-side filter left. `--team ZZZ` over a capped page
+ *  would otherwise read "truncated at 0 of 120", which names the filter, not the truncation. */
+export function truncationNotice(page) {
+    if (page.nextCursor === null)
+        return null;
+    const of = page.total === null ? `an unknown total (the cloud sent no ${TOTAL_HEADER})` : String(page.total);
+    return `truncated at ${page.rows.length} of ${of} — re-run with --all to read the whole scope`;
+}

package/dist/published.js

@@ -0,0 +1,75 @@
+// published.ts — "what is the newest release of this package?", read from the npm registry. This is
+// the ONLY non-tenant host this package contacts. `ready` has always been an offline command, so the
+// answer is cached for six hours, the request is capped at 1500ms, and EVERY failure returns a
+// reason instead of throwing: a customer who cannot reach npm must still get a verdict (CTC-2160).
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { PACKAGE_NAME, publishedCachePathFor } from "./config.js";
+export const REGISTRY_DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
+export const PUBLISHED_TTL_SECONDS = 6 * 60 * 60;
+export const PUBLISHED_TIMEOUT_MS = 1500;
+function readPublishedCache(home) {
+    const path = publishedCachePathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.fetchedAt !== "string" || typeof parsed.latest !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** A write failure (read-only home) must not break the lookup — best-effort only. */
+function writePublishedCache(home, cache) {
+    try {
+        const path = publishedCachePathFor(home);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, JSON.stringify(cache, null, 2) + "\n", { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch {
+        // best-effort: a stale or missing cache next time is not a new failure mode
+    }
+}
+function fallback(cached, reason) {
+    return cached ? { latest: cached.latest, reason: null, source: "stale-cache" } : { latest: null, reason, source: "none" };
+}
+export async function latestPublishedVersion(ctx, opts = {}) {
+    const cached = readPublishedCache(ctx.home);
+    const ageSeconds = cached ? Math.max(0, Math.floor((ctx.now().getTime() - Date.parse(cached.fetchedAt)) / 1000)) : Infinity;
+    if (cached && ageSeconds < PUBLISHED_TTL_SECONDS) {
+        return { latest: cached.latest, reason: null, source: "cache" };
+    }
+    if (opts.offline) {
+        return cached ? { latest: cached.latest, reason: null, source: "cache" } : { latest: null, reason: "offline", source: "none" };
+    }
+    let res;
+    try {
+        res = await ctx.fetch(REGISTRY_DIST_TAGS_URL, {
+            signal: AbortSignal.timeout(PUBLISHED_TIMEOUT_MS),
+            headers: { accept: "application/json" },
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error && err.name === "TimeoutError" ? "timed out" : err instanceof Error ? err.message : String(err);
+        return fallback(cached, reason);
+    }
+    if (!res.ok)
+        return fallback(cached, `registry answered ${res.status}`);
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return fallback(cached, "the registry sent an unreadable body");
+    }
+    const latest = body?.latest;
+    if (typeof latest !== "string")
+        return fallback(cached, "the registry sent no dist-tags.latest");
+    writePublishedCache(ctx.home, { fetchedAt: ctx.now().toISOString(), latest });
+    return { latest, reason: null, source: "network" };
+}

package/dist/query.js

@@ -2,13 +2,18 @@
 // fresh, else the API, with the source named on stderr every time. Output shape is the read-model
 // view either way. `pull`, `cycles`, `search` and `changes` are API-only (the SDK wraps no view for
 // them and the read-model package is not a declared dependency of this bundle).
-import { flagInt, flagString, positionals } from "./args.js";
+import { flagBool, flagInt, flagString, positionals } from "./args.js";
 import { requireConfig, replicaDbPath } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
+import { fetchAllPages, fetchPage, rowsOf, truncationNotice } from "./pagination.js";
 import { engineFor, replicaStatus } from "./replica.js";
 import { loadSdk } from "./sdk.js";
+export { rowsOf };
 const REPLICA_CAPABLE = new Set(["issues", "issue", "pulls", "projects"]);
+/** The two keyset routes `--all` can follow. `projects`/`cycles`/`search` are offset-paged or
+ *  unpaginated and send no cursor header. */
+const PAGINATED = new Set(["issues", "pulls"]);
 export async function cmdQuery(args, ctx, deps = {}) {
     const [sub, ...rest] = positionals(args);
     if (!sub)
@@ -19,10 +24,20 @@ export async function cmdQuery(args, ctx, deps = {}) {
         project: flagString(args, "project"),
         state: flagString(args, "state"),
         limit: flagInt(args, "limit", 50),
+        all: flagBool(args, "all"),
     };
     const forced = flagString(args, "source");
     if (forced && forced !== "replica" && forced !== "api")
         throw new UsageError("--source must be replica or api");
+    if (filters.all && !PAGINATED.has(sub)) {
+        throw new UsageError(`--all follows the cloud's keyset pages, which only ${[...PAGINATED].join(" and ")} have`);
+    }
+    if (filters.all && forced === "replica") {
+        throw new UsageError("--all follows the cloud's page cursor; --source replica reads a local mirror that has none. Pick one.");
+    }
+    if (filters.all && flagString(args, "limit") !== undefined) {
+        ctx.stderr("--all reads the whole scope, so --limit is ignored");
+    }
     const status = replicaStatus(ctx, cfg);
     let source;
     let why;
@@ -34,6 +49,10 @@ export async function cmdQuery(args, ctx, deps = {}) {
         source = forced;
         why = `--source ${forced}`;
     }
+    else if (filters.all) {
+        source = "api";
+        why = "--all follows the cloud's pages";
+    }
     else if (status.verdict === "fresh") {
         source = "replica";
         why = `cursor ${status.cursor}`;
@@ -90,8 +109,16 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
     const common = { team: f.team, project: f.project, state: f.state, limit: f.limit };
     switch (sub) {
         case "issues": {
-            const res = await api.getJson("/api/v1/issues", { query: common });
-            return applyFilters(rowsOf(res.body), f).slice(0, f.limit);
+            if (f.all) {
+                const { rows } = await fetchAllPages(api, "/api/v1/issues", { team: f.team, project: f.project, state: f.state });
+                return applyFilters(rows, f); // no .slice — --all means the whole scope
+            }
+            const page = await fetchPage(api, "/api/v1/issues", common);
+            const rows = applyFilters(page.rows, f).slice(0, f.limit);
+            const notice = truncationNotice(page);
+            if (notice)
+                ctx.stderr(notice);
+            return rows;
         }
         case "issue": {
             const id = needArg(rest, "issue <identifier>");
@@ -99,8 +126,17 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
             return res.status === 404 ? null : res.body;
         }
         case "pulls": {
-            const res = await api.getJson("/api/v1/pulls", { query: { limit: f.limit, ticket: flagString(args, "ticket") } });
-            return rowsOf(res.body).slice(0, f.limit);
+            const ticket = flagString(args, "ticket");
+            if (f.all) {
+                const { rows } = await fetchAllPages(api, "/api/v1/pulls", { ticket });
+                return rows;
+            }
+            const page = await fetchPage(api, "/api/v1/pulls", { limit: f.limit, ticket });
+            const rows = page.rows.slice(0, f.limit);
+            const notice = truncationNotice(page);
+            if (notice)
+                ctx.stderr(notice);
+            return rows;
         }
         case "pull": {
             const id = needArg(rest, "pull <node id>");
@@ -177,19 +213,6 @@ function needArg(rest, usage) {
         throw new UsageError(`query ${usage}`);
     return v;
 }
-/** The API answers a list route with either a bare array or `{rows|items|issues|...: []}`. */
-export function rowsOf(body) {
-    if (Array.isArray(body))
-        return body;
-    if (body && typeof body === "object") {
-        for (const key of ["rows", "items", "issues", "pulls", "projects", "cycles", "results", "changes", "data"]) {
-            const v = body[key];
-            if (Array.isArray(v))
-                return v;
-        }
-    }
-    return [];
-}
 export function applyFilters(rows, f) {
     return rows.filter((r) => {
         if (f.team && !(String(r.identifier ?? "").toUpperCase().startsWith(`${f.team.toUpperCase()}-`) || r.team_id === f.team || r.team_key === f.team))