@catalyst-cloud/cli 0.14.6 → 0.14.8

package/dist/events.js

@@ -1,10 +1,24 @@
 import { flagInt, flagString, positionals } from "./args.js";
-import { apiBase, requireConfig } from "./config.js";
+import { normalizeBaseUrl, requireConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { authStrategyFor } from "./oauth.js";
 import { eventCacheStatus } from "./event-status.js";
+import { cloudEventHead, queryCloudEvents, unreachableError, unreachableKind } from "./events-cloud.js";
+import { eventMatches, tailCloudEvents, waitForCloudEvent } from "./events-cloud-tail.js";
 const eventsModule = "@catalyst-cloud/sdk/events";
 export const loadEventsSdk = () => import(eventsModule);
+/** Consecutive failed attempts after which `wait-for` reports an outage rather than waiting on. */
+const OUTAGE_ATTEMPTS = 5;
+/** How long the cloud may be unreachable before `tail` says so on stderr. */
+const TAIL_WARN_AFTER_MS = 60_000;
+function processInterrupts(handler) {
+    process.once("SIGINT", handler);
+    process.once("SIGTERM", handler);
+    return () => {
+        process.off("SIGINT", handler);
+        process.off("SIGTERM", handler);
+    };
+}
 export async function createEventSync(ctx, deps = {}) {
     const cfg = requireConfig(ctx);
     const sdk = await (deps.loadSdk ?? loadEventsSdk)();
@@ -12,7 +26,8 @@ export async function createEventSync(ctx, deps = {}) {
     if (auth.kind === "cookie")
         throw new CliError("event sync requires a token or OAuth session", "events-auth");
     return new sdk.CatalystEventSync({
-        baseUrl: apiBase(cfg),
+        // Events SDK adds /api/v1/events/backbone itself; unlike the replica it takes an origin.
+        baseUrl: normalizeBaseUrl(cfg.baseUrl),
         auth,
         tenantId: cfg.account,
         fetch: ctx.fetch,
@@ -24,17 +39,31 @@ export async function cmdEvents(args, ctx, deps = {}) {
         throw new UsageError("events needs a subcommand: tail | wait-for | query | status");
     if (!["tail", "wait-for", "query", "status"].includes(sub))
         throw new UsageError(`unknown events subcommand: ${sub}`);
+    // CTC-4554 — the cloud is the default source; the local event file is the opt-in.
+    if (args.flags["from-cache"] !== true) {
+        if (flagString(args, "directory") !== undefined)
+            throw new UsageError("--directory names the local event cache; add --from-cache to read it");
+        return cmdCloudEvents(sub, args, ctx, deps);
+    }
     const cfg = requireConfig(ctx);
     const sdk = await (deps.loadSdk ?? loadEventsSdk)();
     const directory = flagString(args, "directory") ??
         sdk.defaultEventCacheDirectory(cfg.account);
     if (sub === "status") {
         const status = await eventCacheStatus(ctx, directory, args.flags.probe === true);
-        ctx.stdout(args.json ? JSON.stringify(status) : `events: ${status.verdict} at ${directory}${status.reasons.length ? ` (${status.reasons.join("; ")})` : ` (cursor ${status.cursor}, cloud head ${status.head})`}`);
-        return status.verdict === "current" ? 0 : status.verdict === "stale" ? 1 : status.verdict === "absent" ? 3 : 2;
+        ctx.stdout(args.json
+            ? JSON.stringify({ source: "cache", ...status })
+            : `events: local cache ${status.verdict} at ${directory}${status.reasons.length ? ` (${status.reasons.join("; ")})` : ` (cursor ${status.cursor}, cloud head ${status.head})`}`);
+        return status.verdict === "current"
+            ? 0
+            : status.verdict === "stale"
+                ? 1
+                : status.verdict === "absent"
+                    ? 3
+                    : 2;
     }
-    const after = startingCursor(args, sub === "query");
-    const matches = matcher(args);
+    const after = startingCursor(args);
+    const matches = eventMatches(eventFilter(args));
     if (sub === "query") {
         const events = (await sdk.readCachedEvents({ tenantId: cfg.account, directory, after }))
             .filter(matches)
@@ -71,7 +100,7 @@ export async function cmdEvents(args, ctx, deps = {}) {
         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 replica start --detach`, "events-absent", 3);
+            throw new CliError(`event cache is absent at ${directory}: it is written only where local sync runs. Start the local writer with: catalyst replica start --detach, or drop --from-cache to read from the cloud`, "events-absent", 3);
         throw error;
     }
     finally {
@@ -80,33 +109,159 @@ export async function cmdEvents(args, ctx, deps = {}) {
         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)
+function startingCursor(args, name = "after") {
+    const requested = flagString(args, name);
+    if (requested === undefined)
         return undefined;
-    return undefined;
+    const parsed = Number(requested);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        throw new UsageError(`--${name} must be a non-negative event sequence`);
+    return parsed;
 }
-function matcher(args) {
+function eventFilter(args) {
     const type = flagString(args, "type");
     const ticket = flagString(args, "ticket")?.toUpperCase();
-    return (event) => (!type || event.type === type) &&
-        (!ticket || payloadReferences(event.payload, ticket));
+    return { ...(type ? { type } : {}), ...(ticket ? { ticket } : {}) };
+}
+/** A sink over `ctx.stdout` for contexts without a stream (tests): one call per line. */
+function lineSink(ctx) {
+    return {
+        write(chunk, callback) {
+            try {
+                ctx.stdout(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk);
+                callback();
+            }
+            catch (error) {
+                callback(error);
+            }
+            return true;
+        },
+        on: () => undefined,
+        off: () => undefined,
+    };
 }
-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));
+const QUERY_MAX_LIMIT = 200;
+const LOCAL_SYNC_HINT = "several agents on one machine are cheaper sharing one local cache: opt in to local sync (catalyst onboard --local-sync), then read it with --from-cache";
+/** CTC-4554 — `events tail | wait-for | query | status` against the cloud, with no local file. */
+async function cmdCloudEvents(sub, args, ctx, deps) {
+    requireConfig(ctx);
+    const filter = eventFilter(args);
+    if (sub === "status") {
+        let head;
+        try {
+            head = await cloudEventHead(ctx);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            const failure = unreachableError(error);
+            if (args.json)
+                ctx.stdout(JSON.stringify({ source: "cloud", reachable: false, error: unreachableKind(error) }));
+            else
+                ctx.stderr(`catalyst: ${failure.message}`);
+            return failure.exitCode;
+        }
+        // A cloud stream has no local cursor to fall behind. Filtered reads come from the event index,
+        // which trails the head while it fills; that lag is measured, not assumed.
+        let indexedToSeq = null;
+        try {
+            indexedToSeq = (await queryCloudEvents(ctx, { limit: 1, order: "desc" })).coverage.indexedToSeq;
+        }
+        catch {
+            indexedToSeq = null;
+        }
+        const indexLag = indexedToSeq === null ? null : Math.max(0, head - indexedToSeq);
+        const status = { source: "cloud", reachable: true, head, behind: null, indexedToSeq, indexLag, note: LOCAL_SYNC_HINT };
+        ctx.stdout(args.json
+            ? JSON.stringify(status)
+            : `events: cloud stream at head ${head}; ${indexLag === null ? "the filtered index could not be read" : `filtered reads (--ticket, --type) trail it by ${indexLag}`} (every read goes to the cloud; ${LOCAL_SYNC_HINT})`);
+        return 0;
+    }
+    if (sub === "query") {
+        const limit = flagInt(args, "limit", 50);
+        if (!Number.isInteger(limit) || limit < 1 || limit > QUERY_MAX_LIMIT)
+            throw new UsageError(`--limit must be between 1 and ${QUERY_MAX_LIMIT} for a cloud query`);
+        const order = flagString(args, "order") ?? "desc";
+        if (order !== "asc" && order !== "desc")
+            throw new UsageError("--order must be asc or desc");
+        const page = await queryCloudEvents(ctx, {
+            ...filter,
+            limit,
+            order,
+            afterSeq: startingCursor(args, "after"),
+            beforeSeq: startingCursor(args, "before"),
+        });
+        for (const event of page.events)
+            ctx.stdout(JSON.stringify(event));
+        if (page.next)
+            ctx.stderr(`more: re-run with --${page.next.param === "beforeSeq" ? "before" : "after"} ${page.next.value}`);
+        if (page.events.length === 0) {
+            const { indexedFromSeq: from, indexedToSeq: to } = page.coverage;
+            ctx.stderr(from === null || to === null
+                ? "no match; the cloud index holds no events yet"
+                : `no match; the cloud index holds sequences ${from} to ${to}, so an earlier event may exist unindexed`);
+        }
+        return 0;
+    }
+    const out = deps.out ?? ctx.stdoutStream ?? lineSink(ctx);
+    const controller = new AbortController();
+    const abort = () => controller.abort(deps.signal?.reason);
+    if (deps.signal?.aborted)
+        abort();
+    else
+        deps.signal?.addEventListener("abort", abort, { once: true });
+    let interrupted = false;
+    const removeInterrupt = (deps.onInterrupt ?? processInterrupts)(() => {
+        interrupted = true;
+        controller.abort(new Error("interrupted"));
+    });
+    let outage;
+    let warned = false;
+    const seconds = (sinceMs) => Math.round((ctx.now().getTime() - sinceMs) / 1_000);
+    const cloud = {
+        ...deps.cloud,
+        onTrouble: (state) => {
+            deps.cloud?.onTrouble?.(state);
+            if (sub === "wait-for" && state.failures >= OUTAGE_ATTEMPTS && !outage) {
+                outage = state;
+                controller.abort(new Error("cloud unreachable"));
+            }
+            if (sub === "tail" && !warned && ctx.now().getTime() - state.sinceMs > TAIL_WARN_AFTER_MS) {
+                warned = true;
+                ctx.stderr(`events: the cloud has been unreachable for ${seconds(state.sinceMs)} s (${state.failures} attempts); still retrying`);
+            }
+        },
+        onHealthy: () => {
+            deps.cloud?.onHealthy?.();
+            if (warned)
+                ctx.stderr("events: the cloud is reachable again");
+            warned = false;
+        },
+    };
+    try {
+        const after = startingCursor(args);
+        if (sub === "wait-for") {
+            const timeout = flagInt(args, "timeout", 300);
+            const result = await waitForCloudEvent(ctx, { after, filter, timeoutMs: timeout * 1_000, out, signal: controller.signal }, cloud);
+            if (interrupted)
+                return 130;
+            if (outage) {
+                ctx.stderr(`events: the cloud event service was unreachable for ${outage.failures} attempts over ${seconds(outage.sinceMs)} s; this is an outage, not a timeout`);
+                return 4;
+            }
+            if (result.outcome === "matched" || result.outcome === "closed")
+                return 0;
+            if (result.outcome === "timeout")
+                ctx.stderr(`events: no matching event within ${timeout} s`);
+            return 1;
+        }
+        const result = await tailCloudEvents(ctx, { after, filter, out, signal: controller.signal }, cloud);
+        if (result.outcome !== "closed" && result.cursor !== undefined)
+            ctx.stderr(`events: stopped at sequence ${result.cursor}; resume with --after ${result.cursor}`);
+        return interrupted ? 130 : 0;
+    }
+    finally {
+        removeInterrupt();
+        deps.signal?.removeEventListener("abort", abort);
+    }
 }

package/dist/oauth.js

@@ -1,4 +1,4 @@
-import { discoveryCachePathFor, loadConfig, normalizeBaseUrl, writeConfig } from "./config.js";
+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;
@@ -20,7 +20,9 @@ function readDiscoveryDisk(home) {
         return null;
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (isDiscovery(parsed.doc) && typeof parsed.fetchedAt === "number" && typeof parsed.baseUrl === "string")
+        if (isDiscovery(parsed.doc) &&
+            typeof parsed.fetchedAt === "number" &&
+            typeof parsed.baseUrl === "string")
             return parsed;
     }
     catch {
@@ -32,16 +34,24 @@ 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");
+    return [
+        "clientId",
+        "issuer",
+        "deviceAuthorizationUrl",
+        "tokenUrl",
+        "jwksUrl",
+    ].every((k) => typeof d[k] === "string");
 }
 export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
-    const cancelled = () => { if (opts.signal?.aborted)
-        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
+    const cancelled = () => {
+        if (opts.signal?.aborted)
+            throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11);
+    };
     cancelled();
     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 (!opts.refresh && opts.cache !== false) {
         if (fresh(memo))
             return memo.doc;
         const disk = readDiscoveryDisk(ctx.home);
@@ -51,7 +61,9 @@ export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
         }
     }
     const url = `${base}/api/v1/auth/cli`;
-    const res = await safeFetch(ctx, url, { headers: { accept: "application/json" } });
+    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");
     }
@@ -60,6 +72,8 @@ export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
     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 };
+    if (opts.cache === false)
+        return doc;
     memo = entry;
     try {
         writeFileSync(discoveryCachePathFor(ctx.home), JSON.stringify(entry, null, 2) + "\n");
@@ -83,17 +97,28 @@ export const MAX_DEVICE_CODES = 3;
  * expires, a fresh one is minted and printed, up to MAX_DEVICE_CODES in all.
  */
 export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
-    const cancelled = () => { if (deps.signal?.aborted)
-        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
+    const cancelled = () => {
+        if (deps.signal?.aborted)
+            throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11);
+    };
     cancelled();
     if (deps.signal) {
         const fetchImpl = ctx.fetch;
         const signal = deps.signal;
-        ctx = { ...ctx, fetch: ((input, init) => fetchImpl(input, {
-                ...init, signal: init?.signal ? AbortSignal.any([signal, init.signal]) : signal,
-            })) };
+        ctx = {
+            ...ctx,
+            fetch: ((input, init) => fetchImpl(input, {
+                ...init,
+                signal: init?.signal
+                    ? AbortSignal.any([signal, init.signal])
+                    : signal,
+            })),
+        };
     }
-    const discovery = await fetchDiscovery(ctx, baseUrl, { signal: deps.signal });
+    const discovery = await fetchDiscovery(ctx, baseUrl, {
+        signal: deps.signal,
+        cache: deps.discoveryCache,
+    });
     cancelled();
     // The browser rule is decided on the first code; a later code re-opens it only when the first did.
     let browserOpened = false;
@@ -110,17 +135,22 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
             ctx.stdout(`Or open this link, which fills the code in: ${auth.verification_uri_complete}`);
         if (round === 1 ? (deps.isTty ?? (() => false))() : browserOpened) {
             try {
-                (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete ?? auth.verification_uri);
+                if (!deps.openBrowser)
+                    throw new Error("browser-unavailable");
+                await deps.openBrowser(auth.verification_uri_complete ?? auth.verification_uri);
                 browserOpened = true;
                 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("Open the link above in a browser.");
             }
         }
         ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
         const poll = () => pollDeviceCode(ctx, discovery, auth, deps.sleep, deps.signal);
-        const tokens = deps.waitForApproval ? await deps.waitForApproval(poll) : await poll();
+        const tokens = deps.waitForApproval
+            ? await deps.waitForApproval(poll)
+            : await poll();
         cancelled();
         if (tokens !== "expired")
             return tokensToAuth(ctx, tokens.access_token, tokens.refresh_token);
@@ -137,8 +167,10 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
 async function pollDeviceCode(ctx, discovery, auth, sleep, external) {
     const deadline = AbortSignal.timeout(auth.expires_in * 1_000);
     const signal = external ? AbortSignal.any([external, deadline]) : deadline;
-    const cancelled = () => { if (external?.aborted)
-        throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11); };
+    const cancelled = () => {
+        if (external?.aborted)
+            throw new CliError("Sign-in paused. Run the same command to resume.", "login-cancelled", 11);
+    };
     let intervalMs = Math.max(1, auth.interval) * 1_000;
     for (;;) {
         cancelled();
@@ -158,7 +190,15 @@ async function pollDeviceCode(ctx, discovery, auth, sleep, external) {
             return "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 }) }, signal);
+            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,
+                }),
+            }, signal);
             cancelled();
         }
         catch (err) {
@@ -172,10 +212,14 @@ async function pollDeviceCode(ctx, discovery, auth, sleep, external) {
         }
         if (res.ok) {
             const pair = (await parseJson(res, discovery.tokenUrl));
-            if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string") {
+            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 { access_token: pair.access_token, refresh_token: pair.refresh_token };
+            return {
+                access_token: pair.access_token,
+                refresh_token: pair.refresh_token,
+            };
         }
         const err = await oauthError(res, discovery.tokenUrl);
         if (err === "authorization_pending")
@@ -192,7 +236,10 @@ async function pollDeviceCode(ctx, discovery, auth, sleep, external) {
         // 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);
+            intervalMs =
+                Number.isFinite(retryAfter) && retryAfter > 0
+                    ? retryAfter * 1_000
+                    : backoff(intervalMs);
             continue;
         }
         throw new CliError(`login failed (${res.status}): ${err}`, "login-failed");
@@ -202,18 +249,35 @@ async function pollDeviceCode(ctx, discovery, auth, sleep, external) {
 function devicePollDelay(ms, signal, sleep) {
     return new Promise((resolve, reject) => {
         let timer;
-        const clean = () => { clearTimeout(timer); signal.removeEventListener("abort", abort); };
-        const abort = () => { clean(); reject(new Error("device_poll_stopped")); };
+        const clean = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+        };
+        const abort = () => {
+            clean();
+            reject(new Error("device_poll_stopped"));
+        };
         if (signal.aborted) {
             abort();
             return;
         }
         signal.addEventListener("abort", abort, { once: true });
         if (sleep) {
-            Promise.resolve().then(() => sleep(ms)).then(() => { clean(); resolve(); }, error => { clean(); reject(error); });
+            Promise.resolve()
+                .then(() => sleep(ms))
+                .then(() => {
+                clean();
+                resolve();
+            }, (error) => {
+                clean();
+                reject(error);
+            });
         }
         else
-            timer = setTimeout(() => { clean(); resolve(); }, ms);
+            timer = setTimeout(() => {
+                clean();
+                resolve();
+            }, ms);
     });
 }
 /** Grow the poll interval on a transient failure, capped, so retries never hammer the endpoint. */
@@ -243,18 +307,27 @@ function persistRotation(ctx, cfg, sessionId, 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 }) });
+    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") {
+    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,
-        ...(typeof d.verification_uri_complete === "string" && d.verification_uri_complete !== "" ? { verification_uri_complete: d.verification_uri_complete } : {}),
+        ...(typeof d.verification_uri_complete === "string" &&
+            d.verification_uri_complete !== ""
+            ? { verification_uri_complete: d.verification_uri_complete }
+            : {}),
         expires_in: typeof d.expires_in === "number" ? d.expires_in : 300,
         interval: typeof d.interval === "number" ? d.interval : 5,
     };
@@ -293,10 +366,19 @@ async function refreshAndPersist(ctx, cfg, deps) {
     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 }) });
+        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")
+            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
@@ -326,9 +408,17 @@ export function authStrategyFor(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 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 };
+    return {
+        kind: "oauth",
+        accessToken,
+        refreshToken,
+        expiresAt: new Date(exp).toISOString(),
+        sessionId: sid,
+    };
 }
 function decodeJwtClaims(token) {
     const parts = token.split(".");
@@ -342,13 +432,18 @@ function decodeJwtClaims(token) {
     }
 }
 function formHeaders() {
-    return { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
+    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);
+    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 });
     }