@catalyst-cloud/catalyst-skills 0.3.1 → 0.5.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

@@ -5,7 +5,7 @@ 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 { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 /** Every exclusion reason the eligibility evaluator names, in plain English. */
 export const EXCLUSION_REASONS = {
     ticket_terminal: "the ticket is in a done or canceled state, so there is nothing left to run",
@@ -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,20 @@ 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) {
+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
@@ -130,11 +150,15 @@ export async function cmdExplain(args, ctx) {
         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 mirror probe above found the ticket; a 404 keeps the unknown wording.
+    const gate = !row && knownState ? (res.body.eligibility?.dispatchGate ?? null) : null;
+    const explanation = renderExplain(ticket, row, team, knownState, gate);
     if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team, knownState) }));
+        ctx.stdout(JSON.stringify({ ticket, row, ...(gate ? { dispatchGate: gate } : {}), explanation }));
     }
     else {
-        ctx.stdout(renderExplain(ticket, row, team, knownState));
+        ctx.stdout(explanation);
     }
     return 0;
 }
@@ -237,7 +261,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 +334,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/oauth.js

@@ -0,0 +1,300 @@
+import { discoveryCachePathFor, loadConfig, normalizeBaseUrl, writeConfig } from "./config.js";
+import { CliError } from "./errors.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+const DISCOVERY_TTL_MS = 60 * 60_000;
+const REFRESH_SKEW_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+const SLOW_DOWN_BUMP_MS = 5_000;
+const MAX_POLL_BACKOFF_MS = 30_000;
+const REFRESH_MAX_ATTEMPTS = 4;
+const REFRESH_BASE_BACKOFF_MS = 500;
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let memo = null;
+/** Test seam: forget the cached discovery document. */
+export function resetDiscoveryCache() {
+    memo = null;
+}
+function readDiscoveryDisk(home) {
+    const path = discoveryCachePathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (isDiscovery(parsed.doc) && typeof parsed.fetchedAt === "number" && typeof parsed.baseUrl === "string")
+            return parsed;
+    }
+    catch {
+        // a corrupt cache is just a cache miss
+    }
+    return null;
+}
+function isDiscovery(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const d = v;
+    return ["clientId", "issuer", "deviceAuthorizationUrl", "tokenUrl", "jwksUrl"].every((k) => typeof d[k] === "string");
+}
+export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
+    const base = normalizeBaseUrl(baseUrl);
+    const nowMs = ctx.now().getTime();
+    const fresh = (e) => e !== null && e.baseUrl === base && nowMs - e.fetchedAt < DISCOVERY_TTL_MS;
+    if (!opts.refresh) {
+        if (fresh(memo))
+            return memo.doc;
+        const disk = readDiscoveryDisk(ctx.home);
+        if (fresh(disk)) {
+            memo = disk;
+            return disk.doc;
+        }
+    }
+    const url = `${base}/api/v1/auth/cli`;
+    const res = await safeFetch(ctx, url, { headers: { accept: "application/json" } });
+    if (!res.ok) {
+        throw new CliError(`could not read the login discovery document (${res.status}) at ${url} — is this a Catalyst Cloud origin?`, "discovery-failed");
+    }
+    const doc = (await parseJson(res, url));
+    if (!isDiscovery(doc))
+        throw new CliError(`the login discovery document at ${url} is not the expected shape`, "discovery-shape");
+    const entry = { baseUrl: base, fetchedAt: nowMs, doc };
+    memo = entry;
+    try {
+        writeFileSync(discoveryCachePathFor(ctx.home), JSON.stringify(entry, null, 2) + "\n");
+    }
+    catch {
+        // the disk cache is an optimisation; the in-memory memo is enough
+    }
+    return doc;
+}
+/**
+ * Run the device-authorization grant to completion and return the stored session block. Prints the
+ * user code and where to enter it; on a TTY it also opens the completion URL. Polls at the server's
+ * `interval`, honours `slow_down`, and is bounded by `AbortSignal.timeout(expires_in)` so it can
+ * never poll past the device code's own lifetime.
+ */
+export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const discovery = await fetchDiscovery(ctx, baseUrl);
+    const auth = await deviceAuthorize(ctx, discovery);
+    ctx.stdout("");
+    ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
+    ctx.stdout(`and enter the code:              ${auth.user_code}`);
+    if ((deps.isTty ?? (() => false))()) {
+        try {
+            (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete);
+            ctx.stdout("Opened your browser to that page — approve there, or use the code above.");
+        }
+        catch {
+            // a browser that will not open is not a failure; the code and URL still work
+        }
+    }
+    ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
+    // Terminal states print ONE clear, actionable line and exit 2 (CliError's default). The duration
+    // comes from the device code's own `expires_in`, so it is right whatever the server set.
+    const mins = Math.round(auth.expires_in / 60);
+    const expired = () => new CliError(`the login code expired${mins >= 1 ? ` after ${mins} minute${mins === 1 ? "" : "s"}` : ""} — run: catalyst-skills login again`, "login-expired");
+    const deadline = AbortSignal.timeout(auth.expires_in * 1_000);
+    let intervalMs = Math.max(1, auth.interval) * 1_000;
+    for (;;) {
+        await sleep(intervalMs);
+        // The device code's own lifetime bounds the loop: once it lapses, say so plainly rather than
+        // letting the next fetch's aborted signal surface as a generic network error (Codex P2).
+        if (deadline.aborted)
+            throw expired();
+        let res;
+        try {
+            res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: auth.device_code, client_id: discovery.clientId }) }, deadline);
+        }
+        catch (err) {
+            // The deadline firing mid-fetch is an expiry, not a failure; anything else is a transient
+            // network blip — retry with backoff until the deadline, never abandon the login (CTC-2112 P1).
+            if (deadline.aborted)
+                throw expired();
+            intervalMs = backoff(intervalMs);
+            continue;
+        }
+        if (res.ok) {
+            const pair = (await parseJson(res, discovery.tokenUrl));
+            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string") {
+                throw new CliError("the login token response was missing a token", "login-shape");
+            }
+            return tokensToAuth(ctx, pair.access_token, pair.refresh_token);
+        }
+        const err = await oauthError(res, discovery.tokenUrl);
+        if (err === "authorization_pending")
+            continue;
+        if (err === "slow_down") {
+            intervalMs += SLOW_DOWN_BUMP_MS;
+            continue;
+        }
+        if (err === "access_denied")
+            throw new CliError("login was denied — run: catalyst-skills login to try again", "login-denied");
+        if (err === "expired_token")
+            throw expired();
+        // A transient HTTP failure (request timeout, rate limit, server error) is retried, honouring
+        // Retry-After for a 429; only a genuine, non-transient refusal ends the loop.
+        if (res.status === 408 || res.status === 429 || res.status >= 500) {
+            const retryAfter = Number(res.headers.get("retry-after"));
+            intervalMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1_000 : backoff(intervalMs);
+            continue;
+        }
+        throw new CliError(`login failed (${res.status}): ${err}`, "login-failed");
+    }
+}
+/** Grow the poll interval on a transient failure, capped, so retries never hammer the endpoint. */
+function backoff(intervalMs) {
+    return Math.min(intervalMs * 2, MAX_POLL_BACKOFF_MS);
+}
+/**
+ * Persist a rotated token pair WITHOUT clobbering a newer login (Codex P1). A long-running watch or
+ * detached replica holds the `cfg` it started with; if the person meanwhile re-ran `login` (a new
+ * session, a different tenant, or the key rail), that config is already on disk and must survive. So
+ * we reload disk and only write when it is still the same session we just refreshed — or when there
+ * is nothing on disk yet. The reloaded doc is written (not our in-memory `cfg`), so its tenant, user
+ * and CLI-path fields are preserved and only the auth block advances.
+ */
+function persistRotation(ctx, cfg, sessionId, rotated) {
+    let disk;
+    try {
+        disk = loadConfig(ctx.home);
+    }
+    catch {
+        return; // a corrupt/unreadable disk config: don't overwrite what we can't understand
+    }
+    if (disk && disk.auth?.sessionId !== sessionId)
+        return; // a newer login (or a switch to a key) — leave it
+    const target = disk ?? cfg;
+    target.auth = rotated;
+    writeConfig(ctx.home, target); // atomic; the rotated pair survives a crash
+}
+async function deviceAuthorize(ctx, discovery) {
+    const res = await safeFetch(ctx, discovery.deviceAuthorizationUrl, { method: "POST", headers: formHeaders(), body: form({ client_id: discovery.clientId }) });
+    if (!res.ok)
+        throw new CliError(`could not start login (${res.status}) at ${discovery.deviceAuthorizationUrl}`, "login-failed");
+    const d = (await parseJson(res, discovery.deviceAuthorizationUrl));
+    if (typeof d.device_code !== "string" || typeof d.user_code !== "string" || typeof d.verification_uri !== "string") {
+        throw new CliError("the login authorization response was not the expected shape", "login-shape");
+    }
+    return {
+        device_code: d.device_code,
+        user_code: d.user_code,
+        verification_uri: d.verification_uri,
+        verification_uri_complete: d.verification_uri_complete ?? d.verification_uri,
+        expires_in: typeof d.expires_in === "number" ? d.expires_in : 300,
+        interval: typeof d.interval === "number" ? d.interval : 5,
+    };
+}
+// ── the silent refresh ─────────────────────────────────────────────────────────────────────────
+const inFlight = new Map();
+/**
+ * The current bearer for `cfg`: the personal key verbatim, or (for an OAuth session) the access
+ * token, refreshed in place when it is within 60s of expiry. Concurrent callers that both hit the
+ * refresh window share one refresh (single-flight, keyed by the config's home) so the rotating
+ * refresh token is spent exactly once.
+ */
+export async function bearerFor(ctx, cfg, deps = {}) {
+    if (typeof cfg.key === "string" && cfg.key !== "")
+        return cfg.key;
+    if (!cfg.auth)
+        throw new CliError("this machine is not connected — run: catalyst-skills login", "not-configured");
+    const msToExpiry = Date.parse(cfg.auth.expiresAt) - ctx.now().getTime();
+    if (Number.isFinite(msToExpiry) && msToExpiry > REFRESH_SKEW_MS)
+        return cfg.auth.accessToken;
+    const pending = inFlight.get(ctx.home);
+    if (pending) {
+        const rotated = await pending;
+        return rotated.accessToken;
+    }
+    const promise = refreshAndPersist(ctx, cfg, deps).finally(() => inFlight.delete(ctx.home));
+    inFlight.set(ctx.home, promise);
+    const rotated = await promise;
+    return rotated.accessToken;
+}
+async function refreshAndPersist(ctx, cfg, deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const discovery = await fetchDiscovery(ctx, cfg.baseUrl);
+    const current = cfg.auth;
+    let lastStatus = 0;
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS; attempt++) {
+        if (attempt > 0)
+            await sleep(REFRESH_BASE_BACKOFF_MS * 2 ** (attempt - 1));
+        const res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "refresh_token", refresh_token: current.refreshToken, client_id: discovery.clientId }) });
+        if (res.ok) {
+            const pair = (await parseJson(res, discovery.tokenUrl));
+            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string")
+                throw new CliError("the refresh response was missing a token", "session-refresh-shape");
+            const rotated = tokensToAuth(ctx, pair.access_token, pair.refresh_token, current.sessionId);
+            cfg.auth = rotated; // this process keeps using its own refreshed token
+            persistRotation(ctx, cfg, current.sessionId, rotated);
+            return rotated;
+        }
+        lastStatus = res.status;
+        const err = await oauthError(res, discovery.tokenUrl);
+        if (err === "invalid_grant") {
+            // revocation or > inactivity window — the ONLY session-expired case; NOT routine expiry.
+            throw new CliError("your login expired or was revoked — run: catalyst-skills login", "session-expired");
+        }
+        const transient = res.status === 429 || res.status >= 500;
+        if (!transient)
+            throw new CliError(`could not refresh your login (${res.status}): ${err}`, "session-refresh-failed");
+        // transient: fall through to backoff + retry, keeping the stored tokens untouched
+    }
+    throw new CliError(`could not refresh your login after ${REFRESH_MAX_ATTEMPTS} attempts (last status ${lastStatus}) — your tokens are unchanged; try again`, "session-refresh-failed");
+}
+/** The SDK auth strategy for `cfg`: a static token for the key rail, a fresh-per-connect bearer for
+ *  the OAuth rail (its `getToken` runs the same refresh path as every HTTP request). */
+export function authStrategyFor(ctx, cfg) {
+    if (typeof cfg.key === "string" && cfg.key !== "")
+        return { kind: "token", token: cfg.key };
+    return { kind: "bearer", getToken: () => bearerFor(ctx, cfg) };
+}
+// ── helpers ──────────────────────────────────────────────────────────────────────────────────────
+function tokensToAuth(ctx, accessToken, refreshToken, fallbackSid) {
+    const claims = decodeJwtClaims(accessToken);
+    const exp = typeof claims.exp === "number" ? claims.exp * 1_000 : ctx.now().getTime() + 15 * 60_000;
+    const sid = typeof claims.sid === "string" ? claims.sid : (fallbackSid ?? "");
+    return { kind: "oauth", accessToken, refreshToken, expiresAt: new Date(exp).toISOString(), sessionId: sid };
+}
+function decodeJwtClaims(token) {
+    const parts = token.split(".");
+    if (parts.length < 2)
+        return {};
+    try {
+        return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function formHeaders() {
+    return { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+}
+function form(fields) {
+    return new URLSearchParams(fields).toString();
+}
+async function safeFetch(ctx, url, init, signal) {
+    const sig = signal ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]) : AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    try {
+        return await ctx.fetch(url, { ...init, signal: sig });
+    }
+    catch (err) {
+        throw new CliError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+}
+async function parseJson(res, url) {
+    try {
+        return await res.json();
+    }
+    catch {
+        throw new CliError(`${url} returned a non-JSON body`, "shape");
+    }
+}
+/** The OAuth `error` code from a 4xx body, or a short reason when there is none. */
+async function oauthError(res, url) {
+    try {
+        const body = (await res.json());
+        return body.error ?? body.error_description ?? `HTTP ${res.status}`;
+    }
+    catch {
+        return `HTTP ${res.status}`;
+    }
+}

package/dist/query.js

@@ -5,7 +5,7 @@
 import { flagInt, flagString, positionals } from "./args.js";
 import { requireConfig, replicaDbPath } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 import { engineFor, replicaStatus } from "./replica.js";
 import { loadSdk } from "./sdk.js";
 const REPLICA_CAPABLE = new Set(["issues", "issue", "pulls", "projects"]);

package/dist/ready.js

@@ -48,7 +48,7 @@ export async function readyReport(ctx, deps) {
                     ? `config: joined ${cfg.name} as ${cfg.user.label} (${cfg.user.role})`
                     : `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}`,
             }
-            : { id: "config", ok: false, line: "config: not connected", fix: "CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login", who: "you (mint the key at Settings → API keys)" });
+            : { id: "config", ok: false, line: "config: not connected", fix: "npx @catalyst-cloud/catalyst-skills login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)", who: "you (approve the login in your browser)" });
     }
     catch (err) {
         checks.push({ id: "config", ok: false, line: `config: ${err instanceof CliError ? err.message : String(err)}`, fix: "re-run login to rewrite it", who: "you" });