@catalyst-cloud/cli 0.8.0

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/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/prompt.js

@@ -0,0 +1,35 @@
+// prompt.ts — the one interactive read in the CLI: asking for the personal key on a terminal without
+// echoing it. The streams are parameters so the tests can drive it without a real TTY.
+import { createInterface } from "node:readline";
+/** True when there is a terminal to prompt on. Both ends matter: the question needs somewhere to go. */
+export function stdinIsTty() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Read one line without echoing it. Everything readline would write after the question itself goes
+ * to a muted stream, so the key never reaches the screen or a scrollback buffer; the caller still
+ * gets it back, trimmed.
+ */
+export async function promptSecret(question, io) {
+    const input = io?.input ?? process.stdin;
+    const target = io?.output ?? process.stdout;
+    let muted = false;
+    const output = Object.create(target);
+    output.write = (chunk) => {
+        if (!muted)
+            target.write(chunk);
+        return true;
+    };
+    const rl = createInterface({ input, output, terminal: true });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(question, (value) => resolve(value));
+            muted = true;
+        });
+        target.write("\n");
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/published.js

@@ -0,0 +1,79 @@
+// 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 { LEGACY_PACKAGE_NAME, publishedCachePathFor } from "./config.js";
+/** CTC-3479 — asks about the forwarder package whichever package is installed. The release publishes
+ *  @catalyst-cloud/cli first and the forwarder last, at one version, so the forwarder's `latest`
+ *  never names a release that either package lacks. The upgrade hint names the installed package
+ *  (config.ts updatePackageName). */
+export const REGISTRY_DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${encodeURIComponent(LEGACY_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" };
+}