@2kw/ai 5.2.0-dev.8 → 5.3.0-dev.11

package/dist/lib/auth-service.js

@@ -0,0 +1,240 @@
+/**
+ * Thin fetch wrappers for the auth service (Better Auth) endpoints the CLI
+ * needs. Deliberately dependency-free: endpoints are stable REST paths and a
+ * full better-auth client would drag react-oriented tooling into the CLI.
+ *
+ * Failures leave through exactly three exits, and callers branch on which:
+ *
+ * 1. **Mapped {@link DeviceTokenResult} values** — {@link pollDeviceToken} only.
+ *    `pending` / `slow_down` / `denied` / `expired` are ordinary device-flow
+ *    states, so they are returned rather than thrown and the poll loop reads as
+ *    the state machine it is instead of a try/catch.
+ * 2. **{@link AuthServiceError}** — the service answered, and the answer was no.
+ *    Carries the HTTP `status` and any OAuth `code`. A response came back, so
+ *    replaying the identical request is usually pointless.
+ * 3. **A raw fetch `TypeError`** ("fetch failed") — the transport never
+ *    completed: DNS, TLS, connection refused. This module neither catches nor
+ *    wraps it; it propagates untouched, and it is the retry-worthy case.
+ *
+ * So `err instanceof AuthServiceError` separates "the server rejected us" from
+ * "we never reached the server" — the split retry and diagnostics need.
+ * `classifyAuthFailure` in errors.ts already covers the transport half.
+ */
+/**
+ * OAuth client id sent with every device-flow request.
+ *
+ * Cross-repo coupling: this must equal the auth service's configured app slug
+ * (`APP_1_SLUG`, default `backbone` — see compose.yaml), which the service's
+ * `validateClient` checks the incoming `client_id` against. Change it on one
+ * side only and every login fails with `invalid_client`.
+ */
+export const CLI_CLIENT_ID = "backbone";
+/** RFC 8628 grant type used when exchanging a device code for a session. */
+export const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+/**
+ * A failed auth-service call. Carries the HTTP status and, when the service
+ * supplied one, the machine-readable OAuth error code (e.g. "invalid_client").
+ */
+export class AuthServiceError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AuthServiceError";
+    }
+}
+const JSON_HEADERS = { "content-type": "application/json" };
+/** Build an absolute endpoint URL, tolerating trailing slashes on authUrl. */
+function api(authUrl, path) {
+    return `${authUrl.replace(/\/+$/, "")}/api/auth${path}`;
+}
+function bearer(sessionToken) {
+    return { Authorization: `Bearer ${sessionToken}` };
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** View a parsed body as a keyed object; anything else (string, null) reads as empty. */
+function rec(value) {
+    return value !== null && typeof value === "object" ? value : {};
+}
+/**
+ * Parse a JSON body, degrading to `{}` rather than throwing on an empty or
+ * non-JSON payload (a gateway's HTML 502, say). Returns `unknown` because these
+ * endpoints legitimately answer with arrays as well as objects.
+ */
+async function readJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Return the parsed body of a successful response, or throw an AuthServiceError
+ * built from whatever the service reported.
+ */
+async function requireOk(res, what) {
+    const body = await readJson(res);
+    if (res.ok)
+        return body;
+    const err = rec(body);
+    const detail = str(err.error_description) ?? str(err.message) ?? `HTTP ${res.status}`;
+    throw new AuthServiceError(`${what}: ${detail}`, res.status, str(err.error));
+}
+/**
+ * Start a device authorization: returns the user code to display and the URL
+ * to open, plus the polling parameters for {@link pollDeviceToken}.
+ *
+ * The payload is validated rather than cast — the login flow prints these
+ * strings and polls with `device_code`, so a malformed 200 must fail here
+ * instead of surfacing as the literal "undefined" in a user's terminal.
+ */
+export async function requestDeviceCode(authUrl, clientId, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/device/code"), {
+        method: "POST",
+        headers: { ...JSON_HEADERS },
+        body: JSON.stringify({ client_id: clientId }),
+    });
+    const body = rec(await requireOk(res, "Device authorization request failed"));
+    const deviceCode = str(body.device_code);
+    const userCode = str(body.user_code);
+    const verificationUri = str(body.verification_uri);
+    if (!deviceCode || !userCode || !verificationUri) {
+        throw new AuthServiceError("Auth service returned an incomplete device authorization " +
+            "(device_code, user_code, and verification_uri are required).", res.status);
+    }
+    return {
+        device_code: deviceCode,
+        user_code: userCode,
+        verification_uri: verificationUri,
+        // RFC 8628 marks the pre-filled URI optional; fall back to the bare
+        // verification URI so callers always have something to open.
+        verification_uri_complete: str(body.verification_uri_complete) ?? verificationUri,
+        interval: num(body.interval),
+        expires_in: num(body.expires_in),
+    };
+}
+/**
+ * Poll once for the session token behind a device code.
+ *
+ * Unlike the other wrappers this does not treat a 400 as fatal: the RFC 8628
+ * flow reports its in-progress and terminal states through the error field of a
+ * 400 body, so those are mapped to results the caller's loop can act on. Only
+ * an outcome that is neither a token nor a known state throws.
+ */
+export async function pollDeviceToken(authUrl, clientId, deviceCode, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/device/token"), {
+        method: "POST",
+        headers: { ...JSON_HEADERS },
+        body: JSON.stringify({
+            grant_type: DEVICE_GRANT_TYPE,
+            device_code: deviceCode,
+            client_id: clientId,
+        }),
+    });
+    const body = rec(await readJson(res));
+    const accessToken = str(body.access_token);
+    if (res.ok && accessToken)
+        return { status: "ok", accessToken };
+    switch (str(body.error)) {
+        case "authorization_pending":
+            return { status: "pending" };
+        case "slow_down":
+            return { status: "slow_down" };
+        case "access_denied":
+            return { status: "denied" };
+        case "expired_token":
+            return { status: "expired" };
+    }
+    // Neither a token nor a state we know. Say which, because "failed: HTTP 200"
+    // reads as a contradiction when the real fault is a well-formed empty answer.
+    const detail = str(body.error_description) ?? str(body.message);
+    throw new AuthServiceError(detail
+        ? `Device token exchange failed: ${detail}`
+        : `Unrecognized device token response (HTTP ${res.status}, no access_token, no error).`, res.status, str(body.error));
+}
+/**
+ * Exchange a browser session for a short-lived organization JWT — the token the
+ * API itself accepts. Scoped to the session's currently active organization.
+ */
+export async function fetchJwt(authUrl, sessionToken, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/token"), { headers: bearer(sessionToken) });
+    const body = rec(await requireOk(res, "Could not obtain an organization token"));
+    const token = str(body.token);
+    if (!token) {
+        throw new AuthServiceError("Auth service returned no token for this session.", res.status);
+    }
+    return token;
+}
+/**
+ * Organizations the session's user belongs to, projected to what the CLI shows.
+ *
+ * Entries without a usable string `id` are dropped: an org that cannot be named
+ * in `set-active` is not selectable, and coercing one into the list would put
+ * the string "undefined" in front of the user.
+ */
+export async function listOrganizations(authUrl, sessionToken, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/organization/list"), {
+        headers: bearer(sessionToken),
+    });
+    const body = await requireOk(res, "Could not list organizations");
+    if (!Array.isArray(body))
+        return [];
+    return body.flatMap((entry) => {
+        const org = rec(entry);
+        const id = str(org.id);
+        if (!id)
+            return [];
+        // A nameless org is still selectable — show the id rather than drop it.
+        return [{ id, name: str(org.name) ?? id, slug: str(org.slug) ?? id }];
+    });
+}
+/**
+ * Switch the session's active organization. The choice is server-side state, so
+ * every JWT minted afterwards is scoped to it.
+ */
+export async function setActiveOrganization(authUrl, sessionToken, organizationId, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/organization/set-active"), {
+        method: "POST",
+        headers: { ...JSON_HEADERS, ...bearer(sessionToken) },
+        body: JSON.stringify({ organizationId }),
+    });
+    await requireOk(res, "Could not set the active organization");
+}
+/** Who the stored session belongs to — used by `auth status` and login output. */
+export async function getSessionInfo(authUrl, sessionToken, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/get-session"), {
+        headers: bearer(sessionToken),
+    });
+    const body = rec(await requireOk(res, "Could not read the current session"));
+    const email = str(rec(body.user).email);
+    if (!email) {
+        throw new AuthServiceError("Auth service returned a session without a user email.", res.status);
+    }
+    return { email };
+}
+/**
+ * Ask the auth service to revoke the session.
+ *
+ * A 200 is *not* proof of revocation: Better Auth answers `{success: true}`
+ * unconditionally and only deletes the session when the bearer actually
+ * resolves to one. Callers should therefore clear local credentials regardless
+ * of the outcome, and must not report "revoked server-side" on the strength of
+ * this call alone.
+ */
+export async function revokeSession(authUrl, sessionToken, fetchFn = fetch) {
+    const res = await fetchFn(api(authUrl, "/sign-out"), {
+        method: "POST",
+        headers: { ...JSON_HEADERS, ...bearer(sessionToken) },
+        body: "{}",
+    });
+    await requireOk(res, "Could not sign out");
+}
+//# sourceMappingURL=auth-service.js.map

package/dist/lib/auth-session.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The stateful half of browser login: the RFC 8628 polling loop that waits for
+ * the user to approve a device code, and the cache that keeps the short-lived
+ * organization JWT out of the auth service between rapid commands.
+ *
+ * auth-service.ts owns single requests; this module owns what happens across
+ * several of them, so it is where the retry policy lives. It keeps the three
+ * exits that module documents apart: an {@link AuthServiceError} means the
+ * service answered and said no (replaying it would only repeat the answer),
+ * while a raw fetch `TypeError` means the request never landed (worth retrying).
+ */
+import { fetchJwt, type DeviceTokenResult, type OrgSummary } from "./auth-service.js";
+import { type ResolvedConfig } from "./config.js";
+/**
+ * The user's own answer to a device login: they refused it, or they left it
+ * long enough to lapse.
+ *
+ * Typed rather than a bare Error because the login command has to tell these
+ * two outcomes apart from everything else the polling loop can raise (a refused
+ * client id, a dead network). Those are faults and belong in the shared error
+ * rendering; these are answers, and get a plain line and a non-zero exit.
+ */
+export declare class DeviceApprovalError extends Error {
+    readonly reason: "denied" | "expired";
+    constructor(message: string, reason: "denied" | "expired");
+}
+/**
+ * The stored session is gone — revoked, or expired server-side. Distinct from
+ * AuthServiceError so callers can offer the one fix that works (sign in again)
+ * instead of reporting a bare 401.
+ */
+export declare class SessionExpiredError extends Error {
+    constructor();
+}
+/**
+ * Read a JWT's `exp` claim as epoch millis.
+ *
+ * Only the payload is decoded and nothing is verified — the CLI is not the
+ * audience for this token, it merely needs to know when to stop reusing it.
+ * Anything that is not a three-segment JWT with a numeric `exp` throws, because
+ * a silently-assumed expiry would either hand a dead token to the API or
+ * re-exchange on every single command.
+ */
+export declare function decodeJwtExpMs(jwt: string): number;
+/**
+ * Whether a cached JWT has enough life left to be worth reusing — an unknown
+ * expiry counts as stale, so a cache entry written by an older CLI is simply
+ * re-exchanged rather than trusted.
+ */
+export declare function isJwtFresh(expMs: number | undefined, nowMs: number): boolean;
+/** Inputs to {@link runDevicePolling}; `poll` and `sleep` are injectable for tests. */
+export interface DevicePollingOptions {
+    /** One device-token poll — normally a bound `pollDeviceToken`. */
+    poll: () => Promise<DeviceTokenResult>;
+    /** Seconds between polls, per the device-code response. Defaults to 5. */
+    intervalSec?: number;
+    /** Total seconds the device code stays valid. Defaults to 1800. */
+    expiresInSec?: number;
+    /** Delay implementation; defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll until the user approves the login in their browser, and return the
+ * session token.
+ *
+ * Failure handling follows the auth-service taxonomy. A transport error is
+ * retried (up to {@link MAX_CONSECUTIVE_POLL_ERRORS} in a row, the count reset
+ * by any poll that completes) because a laptop that drops its Wi-Fi mid-login
+ * should not have to start over. An {@link AuthServiceError} is not retried —
+ * the service answered, and asking again gets the same answer.
+ *
+ * The deadline is spent from the poll budget rather than read off the wall
+ * clock, so an injected sleep makes the whole loop deterministic.
+ *
+ * @throws {DeviceApprovalError} when the user denies the login, or the code
+ *   expires — either because the service said so or because the budget ran out.
+ * @throws {AuthServiceError} when the service refused the exchange outright.
+ * @throws {TypeError} the last transport error, once retrying is pointless.
+ */
+export declare function runDevicePolling(opts: DevicePollingOptions): Promise<string>;
+/** Asks one question and resolves with what the user typed. */
+export type Asker = (question: string) => Promise<string>;
+/** Injection points for {@link selectOrganization}; both default to the real thing. */
+export interface SelectOrgDeps {
+    /** Question function — tests (and any non-readline caller) supply their own;
+     *  the default reads a line from stdin. */
+    ask?: Asker;
+    /** Whether stdin can be prompted; defaults to `process.stdin.isTTY`. */
+    isTTY?: boolean;
+}
+/**
+ * Decide which organization the new session should act as.
+ *
+ * A single membership needs no ceremony, so it is chosen silently; several
+ * memberships get a numbered prompt that repeats until the answer names one of
+ * them. Lives here rather than in the login command because org switching
+ * reuses the identical choice.
+ *
+ * Two guards keep the prompt from becoming a hang. Without a terminal there is
+ * nobody to answer, and readline on a closed or piped stdin resolves nothing
+ * and never ends — so that case is refused up front, with the fix in the
+ * message. The attempt cap covers what the first guard cannot see: an input
+ * that does answer, always invalidly (a pipe that yields "" forever).
+ *
+ * @throws {Error} when the account has no organizations at all, when there is
+ *   no terminal to prompt, or when the attempts run out.
+ */
+export declare function selectOrganization(orgs: OrgSummary[], deps?: SelectOrgDeps): Promise<OrgSummary>;
+/** Injection points for {@link ensureJwt}; all default to the real thing. */
+export interface EnsureJwtDeps {
+    /** Session-to-JWT exchange; defaults to {@link fetchJwt}. */
+    fetchJwtFn?: typeof fetchJwt;
+    /** Cache writer; defaults to {@link updateContext}. */
+    persist?: (contextName: string, patch: {
+        cachedJwt: string;
+        cachedJwtExp: number;
+    }) => void;
+    /** Clock; defaults to `Date.now`. */
+    now?: () => number;
+    /** Skip the cache and always exchange — e.g. right after switching org. */
+    force?: boolean;
+}
+type SessionConfig = Extract<ResolvedConfig, {
+    kind: "session";
+}>;
+/**
+ * Return an organization JWT for a session context, exchanging the session for
+ * a new one whenever the cached token is missing, stale, or explicitly bypassed.
+ *
+ * A fresh token is written both to the config store and back onto `cfg`: a
+ * single command may reach here more than once (a retry after a 401, say), and
+ * the in-memory copy is what those later reads see. Caching is best-effort — a
+ * token that cannot be cached is still a token that works.
+ *
+ * @throws {SessionExpiredError} when the stored session is no longer valid.
+ */
+export declare function ensureJwt(cfg: SessionConfig, deps?: EnsureJwtDeps): Promise<string>;
+export {};
+//# sourceMappingURL=auth-session.d.ts.map

package/dist/lib/auth-session.js

@@ -0,0 +1,275 @@
+/**
+ * The stateful half of browser login: the RFC 8628 polling loop that waits for
+ * the user to approve a device code, and the cache that keeps the short-lived
+ * organization JWT out of the auth service between rapid commands.
+ *
+ * auth-service.ts owns single requests; this module owns what happens across
+ * several of them, so it is where the retry policy lives. It keeps the three
+ * exits that module documents apart: an {@link AuthServiceError} means the
+ * service answered and said no (replaying it would only repeat the answer),
+ * while a raw fetch `TypeError` means the request never landed (worth retrying).
+ */
+import { Buffer } from "node:buffer";
+import { createInterface } from "node:readline/promises";
+import chalk from "chalk";
+import { AuthServiceError, fetchJwt, } from "./auth-service.js";
+import { updateContext } from "./config.js";
+/**
+ * How much life a cached JWT must have left to be reused. Also absorbs modest
+ * client-clock skew: a token minted against a server clock a few seconds ahead
+ * of ours must not be handed to the API a moment before it becomes valid.
+ */
+const JWT_FRESHNESS_MARGIN_MS = 30_000;
+/** Consecutive-transport-failure count at which the loop gives up: two are
+ *  ridden out, the third is rethrown. */
+const MAX_CONSECUTIVE_POLL_ERRORS = 3;
+/** RFC 8628 §3.2 recommends 5 s when the service states no interval. */
+const DEFAULT_POLL_INTERVAL_SEC = 5;
+/** Ceiling on the whole login wait when the service states no expiry. */
+const DEFAULT_POLL_EXPIRES_SEC = 1800;
+/** RFC 8628 §3.5: each slow_down widens the polling interval by 5 s. */
+const SLOW_DOWN_BACKOFF_MS = 5_000;
+const DENIED_MESSAGE = "Login was denied in the browser.";
+const EXPIRED_MESSAGE = 'Login attempt expired — run "2kw auth login" again.';
+/** Nothing to select from, and nothing the CLI can do about it — orgs are
+ *  created in the web app. */
+const NO_ORG_MESSAGE = "Your account belongs to no organization yet — create one in the web app first.";
+/**
+ * The user's own answer to a device login: they refused it, or they left it
+ * long enough to lapse.
+ *
+ * Typed rather than a bare Error because the login command has to tell these
+ * two outcomes apart from everything else the polling loop can raise (a refused
+ * client id, a dead network). Those are faults and belong in the shared error
+ * rendering; these are answers, and get a plain line and a non-zero exit.
+ */
+export class DeviceApprovalError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "DeviceApprovalError";
+    }
+}
+/**
+ * The stored session is gone — revoked, or expired server-side. Distinct from
+ * AuthServiceError so callers can offer the one fix that works (sign in again)
+ * instead of reporting a bare 401.
+ */
+export class SessionExpiredError extends Error {
+    constructor() {
+        super('Session expired or revoked — run "2kw auth login" to sign in again.');
+        this.name = "SessionExpiredError";
+    }
+}
+/** Wait `ms`, used when the caller injects no sleep of its own. */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Read a JWT's `exp` claim as epoch millis.
+ *
+ * Only the payload is decoded and nothing is verified — the CLI is not the
+ * audience for this token, it merely needs to know when to stop reusing it.
+ * Anything that is not a three-segment JWT with a numeric `exp` throws, because
+ * a silently-assumed expiry would either hand a dead token to the API or
+ * re-exchange on every single command.
+ */
+export function decodeJwtExpMs(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) {
+        throw new Error("Malformed token: expected three dot-separated JWT segments.");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+    }
+    catch {
+        throw new Error("Malformed token: the JWT payload is not valid JSON.");
+    }
+    const exp = payload !== null && typeof payload === "object"
+        ? payload.exp
+        : undefined;
+    if (typeof exp !== "number" || !Number.isFinite(exp)) {
+        throw new Error("Malformed token: the JWT payload carries no numeric exp claim.");
+    }
+    return exp * 1000;
+}
+/**
+ * Whether a cached JWT has enough life left to be worth reusing — an unknown
+ * expiry counts as stale, so a cache entry written by an older CLI is simply
+ * re-exchanged rather than trusted.
+ */
+export function isJwtFresh(expMs, nowMs) {
+    return expMs !== undefined && expMs - nowMs > JWT_FRESHNESS_MARGIN_MS;
+}
+/**
+ * Poll until the user approves the login in their browser, and return the
+ * session token.
+ *
+ * Failure handling follows the auth-service taxonomy. A transport error is
+ * retried (up to {@link MAX_CONSECUTIVE_POLL_ERRORS} in a row, the count reset
+ * by any poll that completes) because a laptop that drops its Wi-Fi mid-login
+ * should not have to start over. An {@link AuthServiceError} is not retried —
+ * the service answered, and asking again gets the same answer.
+ *
+ * The deadline is spent from the poll budget rather than read off the wall
+ * clock, so an injected sleep makes the whole loop deterministic.
+ *
+ * @throws {DeviceApprovalError} when the user denies the login, or the code
+ *   expires — either because the service said so or because the budget ran out.
+ * @throws {AuthServiceError} when the service refused the exchange outright.
+ * @throws {TypeError} the last transport error, once retrying is pointless.
+ */
+export async function runDevicePolling(opts) {
+    const { poll, sleep = defaultSleep } = opts;
+    // A zero or negative interval would spin the loop without ever spending the
+    // budget, so treat anything non-positive as "not stated".
+    const intervalSec = opts.intervalSec !== undefined && opts.intervalSec > 0
+        ? opts.intervalSec
+        : DEFAULT_POLL_INTERVAL_SEC;
+    let intervalMs = intervalSec * 1000;
+    let remainingMs = (opts.expiresInSec ?? DEFAULT_POLL_EXPIRES_SEC) * 1000;
+    let consecutiveErrors = 0;
+    for (;;) {
+        let result;
+        try {
+            result = await poll();
+            consecutiveErrors = 0;
+        }
+        catch (err) {
+            // Exit #2: the service answered. Retrying just replays the refusal.
+            if (err instanceof AuthServiceError)
+                throw err;
+            // Exit #3: the request never completed. Retry-worthy, within reason.
+            consecutiveErrors += 1;
+            if (consecutiveErrors >= MAX_CONSECUTIVE_POLL_ERRORS)
+                throw err;
+        }
+        switch (result?.status) {
+            case "ok":
+                return result.accessToken;
+            case "denied":
+                throw new DeviceApprovalError(DENIED_MESSAGE, "denied");
+            case "expired":
+                throw new DeviceApprovalError(EXPIRED_MESSAGE, "expired");
+            case "slow_down":
+                intervalMs += SLOW_DOWN_BACKOFF_MS;
+                break;
+            default:
+                // "pending", or a tolerated transport error: wait and ask again.
+                break;
+        }
+        remainingMs -= intervalMs;
+        if (remainingMs <= 0)
+            throw new DeviceApprovalError(EXPIRED_MESSAGE, "expired");
+        await sleep(intervalMs);
+    }
+}
+/** Attempts allowed at the prompt before the loop is called a lost cause. */
+const MAX_ORG_PROMPT_ATTEMPTS = 5;
+const NO_TTY_MESSAGE = "Cannot prompt for an organization: no interactive terminal. " +
+    "Pass an org explicitly or run in a terminal.";
+const TOO_MANY_ATTEMPTS_MESSAGE = `No organization chosen after ${MAX_ORG_PROMPT_ATTEMPTS} attempts.`;
+/**
+ * Decide which organization the new session should act as.
+ *
+ * A single membership needs no ceremony, so it is chosen silently; several
+ * memberships get a numbered prompt that repeats until the answer names one of
+ * them. Lives here rather than in the login command because org switching
+ * reuses the identical choice.
+ *
+ * Two guards keep the prompt from becoming a hang. Without a terminal there is
+ * nobody to answer, and readline on a closed or piped stdin resolves nothing
+ * and never ends — so that case is refused up front, with the fix in the
+ * message. The attempt cap covers what the first guard cannot see: an input
+ * that does answer, always invalidly (a pipe that yields "" forever).
+ *
+ * @throws {Error} when the account has no organizations at all, when there is
+ *   no terminal to prompt, or when the attempts run out.
+ */
+export async function selectOrganization(orgs, deps = {}) {
+    const { ask, isTTY = Boolean(process.stdin.isTTY) } = deps;
+    if (orgs.length === 0)
+        throw new Error(NO_ORG_MESSAGE);
+    if (orgs.length === 1)
+        return orgs[0];
+    // Checked before anything is printed: an injected asker owns its own input,
+    // but the default one is about to open readline on a stdin nobody will type
+    // into.
+    if (!ask && !isTTY)
+        throw new Error(NO_TTY_MESSAGE);
+    console.log("");
+    console.log("Select an organization:");
+    orgs.forEach((org, i) => {
+        console.log(`  ${i + 1}) ${org.name}`);
+    });
+    // Only open a real readline when we have to: an injected asker means the
+    // caller owns the input, and an unused interface would hold stdin open.
+    const rl = ask ? undefined : createInterface({ input: process.stdin, output: process.stdout });
+    const askFn = ask ?? ((question) => rl.question(question));
+    try {
+        for (let attempt = 0; attempt < MAX_ORG_PROMPT_ATTEMPTS; attempt++) {
+            const answer = (await askFn(`Organization [1-${orgs.length}]: `)).trim();
+            // Digits only — parseInt would happily read "2 or so" as 2.
+            if (/^\d+$/.test(answer)) {
+                const choice = Number(answer);
+                if (choice >= 1 && choice <= orgs.length)
+                    return orgs[choice - 1];
+            }
+            console.log(chalk.yellow(`Enter a number between 1 and ${orgs.length}.`));
+        }
+        throw new Error(TOO_MANY_ATTEMPTS_MESSAGE);
+    }
+    finally {
+        rl?.close();
+    }
+}
+/**
+ * Return an organization JWT for a session context, exchanging the session for
+ * a new one whenever the cached token is missing, stale, or explicitly bypassed.
+ *
+ * A fresh token is written both to the config store and back onto `cfg`: a
+ * single command may reach here more than once (a retry after a 401, say), and
+ * the in-memory copy is what those later reads see. Caching is best-effort — a
+ * token that cannot be cached is still a token that works.
+ *
+ * @throws {SessionExpiredError} when the stored session is no longer valid.
+ */
+export async function ensureJwt(cfg, deps = {}) {
+    const { fetchJwtFn = fetchJwt, persist = updateContext, now = Date.now, force = false } = deps;
+    if (!force && cfg.cachedJwt && isJwtFresh(cfg.cachedJwtExp, now())) {
+        return cfg.cachedJwt;
+    }
+    let jwt;
+    try {
+        jwt = await fetchJwtFn(cfg.authUrl, cfg.sessionToken);
+    }
+    catch (err) {
+        // Only a 401 means "this session is done". Every other failure — a 502, a
+        // dead network — says nothing about the session, so it must not tell the
+        // user to sign in again.
+        if (err instanceof AuthServiceError && err.status === 401) {
+            // The stale cache is dropped where this lands rather than here:
+            // handleError in errors.ts clears cachedJwt/cachedJwtExp for the active
+            // context, so every command path gets it, including the raw-fetch ones.
+            throw new SessionExpiredError();
+        }
+        throw err;
+    }
+    try {
+        const expMs = decodeJwtExpMs(jwt);
+        cfg.cachedJwtExp = expMs;
+        cfg.cachedJwt = jwt;
+        persist(cfg.contextName, { cachedJwt: jwt, cachedJwtExp: expMs });
+    }
+    catch {
+        // An unparseable token or a read-only config store must not fail a command
+        // that holds a working credential — skip the cache and use it this once.
+        // Cleared as a pair so a half-written entry can never be read back as fresh.
+        cfg.cachedJwt = undefined;
+        cfg.cachedJwtExp = undefined;
+    }
+    return jwt;
+}
+//# sourceMappingURL=auth-session.js.map