faberwright 0.3.1 → 0.4.0

package/dist/onboard.js

@@ -0,0 +1,254 @@
+import pc from "picocolors";
+import { select, readSecret } from "./prompt.js";
+import { vendors, modelsForRoute, baseUrlFor, getRoute, DEFAULT_REGION, } from "./routes.js";
+import * as fs from "node:fs";
+import { loadSettings, saveSettings, settingsPath } from "./settings.js";
+import { credentialSource, saveCredential, maskCredential, credentialsPath, looksLikeKey, } from "./credentials.js";
+/** First run = no settings file yet. */
+/** Where a credential comes from, so setup can point people at the right page. */
+const KEY_SOURCE = {
+    ANTHROPIC_API_KEY: "https://console.anthropic.com/settings/keys",
+    OPENAI_API_KEY: "https://platform.openai.com/api-keys",
+    BEDROCK_API_KEY: "the AWS console (Bedrock → API keys)",
+};
+export function needsOnboarding() {
+    return !hasAnySettingsFile();
+}
+/**
+ * Is this project actually ready to run?
+ *
+ * "A settings file exists" is the wrong question — a profile can name a route
+ * whose credential was never supplied, which then fails as a 401 on the first
+ * task instead of at launch. What counts as complete depends on the route:
+ *
+ *   Anthropic / OpenAI  a key, from the environment or Faber's store
+ *   Bedrock             a key OR AWS credentials it can sign with
+ *   Ollama / local      nothing — but a model id, since there are no defaults
+ *   custom endpoint     a base URL, and a key unless it's localhost
+ */
+export async function setupComplete(cfg) {
+    const route = getRoute(cfg.route);
+    if (!route)
+        return { complete: false, missing: `unknown route "${cfg.route}"`, fix: "/setup" };
+    if (!route.implemented) {
+        return { complete: false, missing: `${route.label} isn't wired up yet`, fix: "/route" };
+    }
+    if (!cfg.model)
+        return { complete: false, missing: "no model chosen", fix: "/model" };
+    if (route.needsBaseUrl && !cfg.baseUrl) {
+        return { complete: false, missing: "no endpoint URL for this route", fix: "/route" };
+    }
+    if (cfg.apiKey)
+        return { complete: true };
+    if (route.id === "bedrock") {
+        const { discoverAwsCredentials } = await import("./sigv4.js");
+        if (await discoverAwsCredentials())
+            return { complete: true }; // IAM role signs
+        return {
+            complete: false,
+            missing: "no AWS credentials and no BEDROCK_API_KEY",
+            fix: "/key set BEDROCK_API_KEY",
+        };
+    }
+    const isLocal = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/.test(cfg.baseUrl ?? "");
+    if (isLocal)
+        return { complete: true }; // local models need no key
+    if (!route.keyEnv)
+        return { complete: true };
+    return { complete: false, missing: `${route.keyEnv} is not set`, fix: `/key set ${route.keyEnv}` };
+}
+function hasAnySettingsFile() {
+    try {
+        return fs.existsSync(settingsPath());
+    }
+    catch {
+        return false;
+    }
+}
+/** True when we can prompt at all. */
+export function interactive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Read a key and refuse to silently store something that isn't one. A typo
+ * saved here becomes the preferred credential and breaks every later run,
+ * which is a much worse outcome than one extra confirmation.
+ */
+async function readKey(rl, envName, promptText) {
+    const key = await readSecret(rl, promptText);
+    if (!key)
+        return undefined;
+    const problem = looksLikeKey(envName, key);
+    if (problem) {
+        console.log(pc.yellow(`  ${problem}.`));
+        const ok = await select(rl, "Save it anyway?", ["No, discard it", "Yes, save it"]);
+        if (ok === 0)
+            return undefined;
+    }
+    return key;
+}
+/**
+ * Walk vendor -> route -> region/endpoint -> model. Returns the profile it
+ * saved so the caller can report what still needs doing (e.g. an unset key).
+ */
+export async function runOnboarding(rl, opts = {}) {
+    if (opts.first) {
+        console.log();
+        console.log(pc.cyan("Welcome to Faber."));
+        console.log(pc.dim("Let's pick where your model comes from. You can change this any time with /route or /model."));
+        console.log();
+    }
+    const groups = vendors();
+    const vi = await select(rl, "Who provides the model?", groups.map((g) => g.vendor));
+    const routes = groups[vi].routes;
+    const ri = await select(rl, "How should Faber reach it?", routes.map((r) => `${r.label.padEnd(30)} ${pc.dim(r.hint)}${r.implemented ? "" : pc.yellow("  (not yet wired)")}`));
+    const route = routes[ri];
+    if (!route.implemented) {
+        console.log(pc.yellow(`${route.label} isn't wired up yet — falling back to the Anthropic API.`));
+        const fallback = groups[0].routes[0];
+        return finish(rl, fallback, {});
+    }
+    return finish(rl, route, {});
+}
+/**
+ * Make sure the route has a usable credential, prompting if not.
+ * Exported so startup can run just this step: a configured profile with a
+ * missing key should ask at launch, not fail with a 401 on the first task.
+ *
+ * Returns what the user chose to do when they have no key — the ways forward
+ * are offered as choices, because the REPL that prose would point them at
+ * never opens when setup is incomplete.
+ */
+export async function ensureCredential(rl, route, profile) {
+    if (!route.keyEnv)
+        return {};
+    const found = credentialSource(route.keyEnv);
+    if (found?.from === "store") {
+        console.log(pc.dim(`  Using ${route.keyEnv} saved on this computer (${maskCredential(found.value)})`));
+        return {};
+    }
+    if (found?.from === "environment") {
+        console.log();
+        console.log(`Found ${route.keyEnv} in your environment (${maskCredential(found.value)}).`);
+        const choice = await select(rl, "Use it?", [
+            `Yes, and remember it here        ${pc.dim("works in any shell, even without the env var")}`,
+            `Yes, but don't save it           ${pc.dim("keep reading it from the environment")}`,
+            `No, use a different key          ${pc.dim("paste another one")}`,
+        ]);
+        if (choice === 0) {
+            saveCredential(route.keyEnv, found.value);
+            console.log(pc.dim(`  kept on this computer only, at ${credentialsPath()}`));
+        }
+        else if (choice === 1) {
+            console.log(pc.dim("  not saved — Faber will read it from the environment each run"));
+        }
+        else {
+            const key = await readKey(rl, route.keyEnv, `  ${route.keyEnv} (hidden): `);
+            if (key) {
+                saveCredential(route.keyEnv, key);
+                profile.preferStoredKey = true; // an explicit choice beats the env var
+                console.log(pc.dim(`  saved (${maskCredential(key)}) — Faber will use this one, not the environment`));
+            }
+            else {
+                console.log(pc.dim("  not saved — keeping the key from your environment"));
+            }
+        }
+        return {};
+    }
+    if (route.id === "bedrock") {
+        // Bedrock can sign with an IAM role, so a key may not be needed at all.
+        const { discoverAwsCredentials } = await import("./sigv4.js");
+        const aws = await discoverAwsCredentials();
+        console.log();
+        console.log(aws
+            ? pc.dim(`  No key needed — signing with AWS credentials from ${aws.source}.`)
+            : pc.yellow(`  No AWS credentials found. Set ${route.keyEnv}, or run where an IAM role is available.`));
+        return {};
+    }
+    // No key anywhere: say where to get one, read it hidden, and if they don't
+    // have one, offer real alternatives rather than a dead end.
+    console.log();
+    console.log(`Faber needs an API key for ${route.label}.`);
+    const where = KEY_SOURCE[route.keyEnv];
+    if (where)
+        console.log(pc.dim(`  Get one at ${where}`));
+    const key = await readKey(rl, route.keyEnv, `  ${route.keyEnv} (hidden): `);
+    if (key) {
+        saveCredential(route.keyEnv, key);
+        console.log(pc.dim(`  saved (${maskCredential(key)}) — kept on this computer only, at ${credentialsPath()}`));
+        return {};
+    }
+    // No key means setup didn't complete. Nothing is written, so the next run
+    // starts over from the beginning rather than resuming into a broken state.
+    return { switchedTo: "quit" };
+}
+async function finish(rl, route, base) {
+    const profile = { ...base, route: route.id };
+    const activeRoute = route;
+    if (route.needsRegion) {
+        const ans = (await rl.question(`AWS region [${DEFAULT_REGION}]: `)).trim();
+        profile.region = ans || DEFAULT_REGION;
+    }
+    if (route.needsBaseUrl) {
+        const ans = (await rl.question("Base URL of the OpenAI-compatible endpoint: ")).trim();
+        if (ans)
+            profile.baseUrl = ans;
+    }
+    if (route.keyEnv) {
+        profile.apiKeyEnv = route.keyEnv;
+        const outcome = await ensureCredential(rl, activeRoute, profile);
+        if (outcome.switchedTo === "quit") {
+            // Nothing is written: an incomplete profile would make the next run
+            // look configured when it isn't.
+            return { profile, route: activeRoute, aborted: true };
+        }
+    }
+    // model: pick from aliases, or ask for an id on routes where ids vary
+    const choices = modelsForRoute(activeRoute);
+    if (choices.length) {
+        const mi = await select(rl, "Default model", choices.map((m) => `${m.alias.padEnd(8)} ${pc.dim(m.blurb)}`));
+        profile.model = choices[mi].alias;
+    }
+    else {
+        const hint = activeRoute.id === "ollama" ? "qwen2.5-coder" : "";
+        const ans = (await rl.question(`Model id${hint ? ` [${hint}]` : ""} ${pc.dim("(ids differ on this route)")}: `)).trim();
+        profile.model = ans || hint || undefined;
+    }
+    // Fetch prices once during setup: costs are frozen per task, so starting
+    // with current rates keeps day-one history accurate.
+    const { refreshPrices } = await import("./pricing.js");
+    process.stdout.write(pc.dim("  fetching current prices… "));
+    const n = await refreshPrices(undefined, { baseUrl: profile.baseUrl ?? activeRoute.baseUrl });
+    process.stdout.write("\r\x1b[2K");
+    if (!n)
+        console.log(pc.dim("  (couldn't fetch prices — using built-in rates)"));
+    const settings = loadSettings();
+    settings.profiles[settings.activeProfile] = profile;
+    saveSettings(settings);
+    const missingKeyEnv = activeRoute.keyEnv && !credentialSource(activeRoute.keyEnv)
+        ? activeRoute.keyEnv : undefined;
+    return { profile, route: activeRoute, missingKeyEnv };
+}
+/** Summary printed after onboarding, including anything still to be done. */
+export function reportSetup(r) {
+    if (r.aborted) {
+        console.log();
+        console.log(pc.yellow("Setup not completed — nothing was saved."));
+        console.log(pc.dim("  Run faber again when you have a key, or choose a local model."));
+        console.log();
+        return;
+    }
+    const url = r.profile.baseUrl ?? baseUrlFor(r.route, r.profile.region);
+    console.log();
+    console.log(`Route:    ${r.route.label}`);
+    if (url)
+        console.log(pc.dim(`Endpoint: ${url}`));
+    if (r.profile.model)
+        console.log(pc.dim(`Model:    ${r.profile.model}`));
+    if (r.missingKeyEnv) {
+        console.log();
+        console.log(pc.yellow(`One thing left — ${r.missingKeyEnv} isn't set:`));
+        console.log(pc.dim(`  /key set ${r.missingKeyEnv}`));
+    }
+    console.log();
+}

package/dist/pricing.js

@@ -0,0 +1,254 @@
+/**
+ * Model pricing.
+ *
+ * Where prices come from, best source first:
+ *   1. What you configured (env vars or a profile) — always wins.
+ *   2. The provider itself, when it publishes prices. OpenRouter's
+ *      /api/v1/models returns live per-token rates including cache read/write,
+ *      and it needs no key. That is authoritative for that route.
+ *   3. A refreshable community dataset covering everyone else.
+ *   4. A small built-in table so /usage works with zero configuration.
+ *
+ * Anthropic's and OpenAI's own /v1/models return ids and capabilities but not
+ * dollars, which is why 3 and 4 exist at all.
+ *
+ * The built-in table is deliberately small and dated. It exists so `/usage`
+ * shows real numbers out of the box; it is not the source of truth. Anything
+ * you set explicitly always wins, and `/usage --refresh-prices` pulls current
+ * figures. Prices here are $ per MILLION tokens.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Verified 2026-08. Check the vendor's pricing page before quoting these. */
+export const PRICES_AS_OF = "2026-08";
+export const BUILTIN_PRICES = {
+    "claude-fable-5": { in: 10, out: 50, cacheRead: 1, cacheWrite: 12.5 },
+    "claude-opus-5": { in: 5, out: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+    "claude-sonnet-5": { in: 2, out: 10, cacheRead: 0.2, cacheWrite: 2.5 },
+    "claude-haiku-4-5-20251001": { in: 1, out: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+    "claude-sonnet-4-5": { in: 3, out: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    "claude-opus-4-1": { in: 15, out: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    "gpt-4o": { in: 2.5, out: 10, cacheRead: 1.25 },
+    "gpt-4o-mini": { in: 0.15, out: 0.6, cacheRead: 0.075 },
+};
+/**
+ * Cloud routes prefix ids with a region scope and suffix a version, e.g.
+ * "us.anthropic.claude-sonnet-5" or "anthropic.claude-haiku-4-5-20251001-v1:0".
+ * Strip those so one table entry covers every deployment of a model.
+ * (Regional Bedrock endpoints do cost a little more than global — treat the
+ * result as an estimate, and pin exact prices in your profile if it matters.)
+ */
+export function normalizeModelId(id) {
+    let s = id.trim();
+    s = s.replace(/^(global|us|eu|apac|au|jp)\./, ""); // region scope
+    s = s.replace(/^anthropic\./, ""); // provider scope
+    s = s.replace(/-v\d+:\d+$/, ""); // bedrock version suffix
+    s = s.replace(/@\d{8}$/, ""); // vertex date suffix
+    return s;
+}
+function cacheFile() {
+    return path.join(os.homedir(), ".faber", "cache", "prices.json");
+}
+/** Wait this long before retrying after a failed refresh. */
+export const RETRY_AFTER_FAILURE_MS = 24 * 60 * 60 * 1000;
+/** How old the cached prices are, in days. undefined = never fetched. */
+export function priceAgeDays(now = Date.now()) {
+    const c = readPriceCache();
+    return c ? (now - c.fetchedAt) / 86_400_000 : undefined;
+}
+/** Prices this old are worth re-checking before they get baked into history. */
+export const STALE_AFTER_DAYS = 14;
+export function pricesAreStale(now = Date.now()) {
+    const age = priceAgeDays(now);
+    return age === undefined || age > STALE_AFTER_DAYS;
+}
+export function readPriceCache() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(cacheFile(), "utf8"));
+        return raw.prices && typeof raw.prices === "object" ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writePriceCache(prices, source, etag) {
+    try {
+        const f = cacheFile();
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        const now = Date.now();
+        fs.writeFileSync(f, JSON.stringify({ fetchedAt: now, lastAttempt: now, source, etag, prices }, null, 2));
+    }
+    catch { /* best effort */ }
+}
+/** Prices were re-confirmed unchanged (a 304) — still current, nothing to store. */
+export function markPricesConfirmed(now = Date.now()) {
+    try {
+        const existing = readPriceCache();
+        if (!existing)
+            return;
+        const f = cacheFile();
+        fs.writeFileSync(f, JSON.stringify({ ...existing, fetchedAt: now, lastAttempt: now }, null, 2));
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Remember that we tried, even when the fetch failed. Without this an offline
+ * machine would retry on every single launch, which is exactly the behaviour
+ * a background refresh must not have.
+ */
+export function markRefreshAttempt(now = Date.now()) {
+    try {
+        const f = cacheFile();
+        fs.mkdirSync(path.dirname(f), { recursive: true });
+        const existing = readPriceCache();
+        fs.writeFileSync(f, JSON.stringify({
+            fetchedAt: existing?.fetchedAt ?? 0,
+            lastAttempt: now,
+            source: existing?.source ?? "none",
+            etag: existing?.etag, // must survive, or conditional GET breaks
+            prices: existing?.prices ?? {},
+        }, null, 2));
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Should a background refresh run now?
+ *
+ * Yes on every launch — a conditional request is ~0 bytes when nothing has
+ * changed, so there's no reason to tolerate a stale price window. The only
+ * exception is backing off after a FAILED attempt, so an offline machine
+ * isn't making a doomed request every time you start.
+ */
+export function shouldAutoRefresh(now = Date.now()) {
+    const c = readPriceCache();
+    if (!c)
+        return true; // never fetched
+    const failedRecently = c.lastAttempt !== undefined
+        && c.lastAttempt > c.fetchedAt // attempt newer than success
+        && now - c.lastAttempt < RETRY_AFTER_FAILURE_MS;
+    return !failedRecently;
+}
+const DATASET_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
+/** True when this endpoint is OpenRouter, which publishes live prices. */
+export function isOpenRouter(baseUrl) {
+    return Boolean(baseUrl && /(^|\/\/)([^/]*\.)?openrouter\.ai/.test(baseUrl));
+}
+/**
+ * Live prices straight from OpenRouter. Values are USD per token as strings;
+ * we convert to per-Mtok. No API key needed for the catalogue.
+ */
+export async function fetchOpenRouterPrices(url = OPENROUTER_MODELS_URL) {
+    try {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), 15000);
+        const res = await fetch(url, { signal: ctl.signal });
+        clearTimeout(timer);
+        if (!res.ok)
+            return undefined;
+        const body = await res.json();
+        const out = {};
+        const perM = (s) => {
+            const n = Number(s);
+            return Number.isFinite(n) ? Math.round(n * 1e6 * 1e6) / 1e6 : undefined;
+        };
+        for (const m of body.data ?? []) {
+            if (!m.id || !m.pricing)
+                continue;
+            const inC = perM(m.pricing["prompt"]), outC = perM(m.pricing["completion"]);
+            if (inC === undefined || outC === undefined)
+                continue;
+            const price = { in: inC, out: outC };
+            const cr = perM(m.pricing["input_cache_read"]);
+            const cw = perM(m.pricing["input_cache_write"]);
+            if (cr !== undefined)
+                price.cacheRead = cr;
+            if (cw !== undefined)
+                price.cacheWrite = cw;
+            out[m.id] = price;
+        }
+        return Object.keys(out).length ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+"https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+export async function refreshPrices(url = DATASET_URL, opts = {}) {
+    markRefreshAttempt(); // recorded first, so a crash mid-fetch still backs off
+    // If the active endpoint publishes its own prices, that beats any dataset.
+    if (isOpenRouter(opts.baseUrl)) {
+        const live = await fetchOpenRouterPrices();
+        if (live) {
+            const merged = { ...(readPriceCache()?.prices ?? {}), ...live };
+            writePriceCache(merged, OPENROUTER_MODELS_URL);
+            return Object.keys(live).length;
+        }
+    }
+    try {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), 15000);
+        // Conditional request: if the price list hasn't changed the server answers
+        // 304 with no body, so checking every launch costs ~0 bytes instead of 1.6MB.
+        const known = readPriceCache();
+        const headers = {};
+        if (known?.etag && !opts.force)
+            headers["if-none-match"] = known.etag;
+        const res = await fetch(url, { signal: ctl.signal, headers });
+        clearTimeout(timer);
+        if (res.status === 304) {
+            markPricesConfirmed();
+            return "unchanged";
+        }
+        if (!res.ok)
+            return undefined;
+        const etag = res.headers.get("etag") ?? undefined;
+        const raw = await res.json();
+        const out = {};
+        for (const [id, v] of Object.entries(raw)) {
+            const inC = v["input_cost_per_token"], outC = v["output_cost_per_token"];
+            if (typeof inC !== "number" || typeof outC !== "number")
+                continue;
+            // per-token floats round badly at 1e6 (2e-7 -> 0.19999999999999998),
+            // and these values get written to a file people read.
+            const perM = (n) => Math.round(n * 1e6 * 1e6) / 1e6;
+            const price = { in: perM(inC), out: perM(outC) };
+            const cr = v["cache_read_input_token_cost"], cw = v["cache_creation_input_token_cost"];
+            if (typeof cr === "number")
+                price.cacheRead = perM(cr);
+            if (typeof cw === "number")
+                price.cacheWrite = perM(cw);
+            out[id] = price;
+        }
+        if (!Object.keys(out).length)
+            return undefined;
+        writePriceCache(out, url, etag);
+        return Object.keys(out).length;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Price for a model. Explicit overrides win, then a refreshed dataset (exact
+ * id, then normalized), then the built-in table. Undefined means "unknown",
+ * which the ledger renders as — rather than guessing.
+ */
+export function priceFor(modelId, override) {
+    if (override?.in && override?.out)
+        return { in: override.in, out: override.out };
+    const norm = normalizeModelId(modelId);
+    const cached = readPriceCache()?.prices;
+    const hit = cached?.[modelId] ?? cached?.[norm] ?? BUILTIN_PRICES[modelId] ?? BUILTIN_PRICES[norm];
+    return hit;
+}
+/** Multipliers used when a model's exact cache prices aren't known. */
+export const CACHE_READ_RATIO = 0.1;
+export const CACHE_WRITE_RATIO = 1.25;
+export function cacheReadPrice(p) {
+    return p.cacheRead ?? p.in * CACHE_READ_RATIO;
+}
+export function cacheWritePrice(p) {
+    return p.cacheWrite ?? p.in * CACHE_WRITE_RATIO;
+}

package/dist/prompt.js

@@ -2,10 +2,18 @@ import pc from "picocolors";
 let guardFn;
 /** Wired by the CLI: pauses the composed-input pipe while the selector owns stdin. */
 export function setSelectGuard(fn) { guardFn = fn; }
-export async function select(rl, question, options, defaultIndex = 0) {
+async function selectRaw(rl, question, options, defaultIndex = 0) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         const menu = options.map((o, i) => `  ${i + 1}) ${o}`).join("\n");
-        const ans = (await rl.question(`${question}\n${menu}\nChoose [1-${options.length}] (default ${defaultIndex + 1}): `)).trim();
+        let ans;
+        try {
+            ans = (await rl.question(`${question}\n${menu}\nChoose [1-${options.length}] (default ${defaultIndex + 1}): `)).trim();
+        }
+        catch {
+            // stdin closed mid-prompt (piped input ran out, or Ctrl-D):
+            // take the default rather than surfacing a readline stack trace.
+            return defaultIndex;
+        }
         const n = Number.parseInt(ans, 10);
         return Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : defaultIndex;
     }
@@ -68,6 +76,9 @@ export async function select(rl, question, options, defaultIndex = 0) {
                     finish(idx);
                     done = true;
                 }
+                // Ctrl-C or Esc cancels. Returning -1 used to leak out as an array
+                // index, crashing the caller with "cannot read properties of
+                // undefined" — a cancel must be a clean exit, not a bad index.
                 else if (key === "\x03" || key === "\x1b") {
                     finish(-1);
                     done = true;
@@ -78,3 +89,69 @@ export async function select(rl, question, options, defaultIndex = 0) {
         stdin.on("data", onData);
     });
 }
+/**
+ * Read a secret without echoing it. A pasted API key that appears on screen
+ * survives in terminal scrollback, `script` logs, and screen recordings — so
+ * the characters are consumed in raw mode and only a masked length is shown.
+ * Falls back to a normal read when there's no TTY (CI piping a key in).
+ */
+export async function readSecret(rl, promptText, io) {
+    const stdin = io?.stdin ?? process.stdin;
+    const stdout = io?.stdout ?? process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return (await rl.question(promptText)).trim();
+    }
+    guardFn?.(true);
+    rl.pause();
+    const wasRaw = stdin.isRaw ?? false;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdout.write(promptText);
+    return new Promise((resolve) => {
+        let value = "";
+        const done = () => {
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw);
+            guardFn?.(false);
+            rl.resume();
+            stdout.write("\n");
+            resolve(value.trim());
+        };
+        const onData = (buf) => {
+            for (const ch of buf.toString("utf8")) {
+                if (ch === "\r" || ch === "\n")
+                    return done();
+                if (ch === "\x03") {
+                    value = "";
+                    return done();
+                } // Ctrl-C
+                if (ch === "\x7f" || ch === "\b") { // backspace
+                    if (value.length) {
+                        value = value.slice(0, -1);
+                        stdout.write("\b \b");
+                    }
+                    continue;
+                }
+                if (ch >= " ") {
+                    value += ch;
+                    stdout.write("•");
+                }
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/**
+ * Arrow-key menu. Cancelling (Ctrl-C or Esc) exits the process cleanly rather
+ * than returning a sentinel index that every caller would have to check —
+ * one forgotten check produced a raw TypeError mid-setup.
+ */
+export async function select(rl, question, options, defaultIndex = 0) {
+    const picked = await selectRaw(rl, question, options, defaultIndex);
+    if (picked < 0 || picked >= options.length) {
+        process.stdout.write("\n");
+        rl.close();
+        process.exit(130); // 128 + SIGINT, the conventional cancel code
+    }
+    return picked;
+}