@cortexkit/common-auth 0.2.4 → 0.2.5

package/dist/auth-menu/doctor.js

@@ -0,0 +1,81 @@
+/** The code of the finding recorded for a check that threw. */
+export const DOCTOR_CHECK_FAILED = 'doctor-check-failed';
+/**
+ * Runs every check in order. A check that throws becomes a finding of its
+ * own instead of hiding what the other checks found.
+ */
+export async function runDoctorChecks(checks) {
+    const findings = [];
+    for (const check of checks) {
+        try {
+            findings.push(...(await check.run()));
+        }
+        catch (error) {
+            findings.push({
+                code: DOCTOR_CHECK_FAILED,
+                message: `Check ${check.id} failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    return { findings };
+}
+export function formatDoctorReport(title, report) {
+    const lines = [title];
+    if (report.findings.length === 0) {
+        lines.push('No problems found.');
+        return lines;
+    }
+    for (const finding of report.findings) {
+        const repair = finding.repair ? ' (repair available)' : '';
+        lines.push(`- ${finding.message}${repair}`);
+    }
+    return lines;
+}
+/**
+ * Asks about each available repair in turn and applies only the ones the
+ * operator answers yes to. Without an interactive terminal every question
+ * is answered no, so nothing is written.
+ */
+export async function applyChosenRepairs(context, report) {
+    const outcome = { applied: [], declined: [], failed: [] };
+    for (const finding of report.findings) {
+        const repair = finding.repair;
+        if (!repair)
+            continue;
+        if (!(await context.confirm(`Apply repair: ${repair.label}?`))) {
+            outcome.declined.push(finding);
+            continue;
+        }
+        try {
+            await repair.apply();
+            outcome.applied.push(finding);
+        }
+        catch (error) {
+            outcome.failed.push({ finding, error });
+            context.print(`Repair failed: ${repair.label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return outcome;
+}
+/** The menu's doctor: lists every finding, then offers each repair. */
+export function doctorAction(options) {
+    const title = options.title ?? 'Auth doctor';
+    return {
+        id: 'doctor',
+        label: options.label ?? 'Auth doctor',
+        hint: 'check accounts and offer repairs',
+        async run(context) {
+            const report = await runDoctorChecks(options.checks);
+            for (const line of formatDoctorReport(title, report))
+                context.print(line);
+            const repairable = report.findings.filter((finding) => finding.repair);
+            if (repairable.length === 0) {
+                if (report.findings.length > 0)
+                    context.print('No repairs are available.');
+                return;
+            }
+            const outcome = await applyChosenRepairs(context, report);
+            context.print(`Applied ${outcome.applied.length} of ${repairable.length} repair(s).`);
+        },
+    };
+}

package/dist/auth-menu/index.d.ts

@@ -1 +1,17 @@
-export {};
+export type { AccountMenuOptions } from './accounts.js';
+export { accountMenuActions, addAccountAction, checkQuotasAction, deleteAllAction, listAccountsAction, MENU_DISABLE_REASON, poolHasCredential, quotaLines, reauthenticateAction, removeAccountAction, runAccountMenu, toggleAccountAction, } from './accounts.js';
+export type { KeyAction } from './ansi.js';
+export { ANSI, parseKey, stripAnsi, truncateAnsi } from './ansi.js';
+export { confirm } from './confirm.js';
+export type { DoctorActionOptions, DoctorCheck, DoctorFinding, DoctorRepair, DoctorReport, RepairOutcome, } from './doctor.js';
+export { applyChosenRepairs, DOCTOR_CHECK_FAILED, doctorAction, formatDoctorReport, runDoctorChecks, } from './doctor.js';
+export type { LoginAccount, LoginFlow, MenuLogin } from './login.js';
+export { openBrowserForMenu, runMenuLogin } from './login.js';
+export type { MenuAction, MenuContext, MenuOutcome, RunMenuOptions, } from './menu.js';
+export { menuContext, runMenu } from './menu.js';
+export type { AuthorizeInputs, MenuAuthorizeOptions, MenuCompletedResult, } from './opencode-v1.js';
+export { isCliAuthorize, menuAuthorize, menuCompletedResult, } from './opencode-v1.js';
+export type { MenuItem, SelectOptions } from './select.js';
+export { select } from './select.js';
+export type { MenuInput, MenuOutput, MenuSignals, MenuTerminal, } from './terminal.js';
+export { isInteractive, printLine, processTerminal } from './terminal.js';

package/dist/auth-menu/index.js

@@ -1,2 +1,12 @@
-// Placeholder so the export resolves until this subpath is built.
-export {};
+// The `opencode auth login` account menu: a first-party full-screen menu
+// runtime, the OpenCode v1 `authorize` contract around it, and the account
+// actions built over the `/store` pool.
+export { accountMenuActions, addAccountAction, checkQuotasAction, deleteAllAction, listAccountsAction, MENU_DISABLE_REASON, poolHasCredential, quotaLines, reauthenticateAction, removeAccountAction, runAccountMenu, toggleAccountAction, } from './accounts.js';
+export { ANSI, parseKey, stripAnsi, truncateAnsi } from './ansi.js';
+export { confirm } from './confirm.js';
+export { applyChosenRepairs, DOCTOR_CHECK_FAILED, doctorAction, formatDoctorReport, runDoctorChecks, } from './doctor.js';
+export { openBrowserForMenu, runMenuLogin } from './login.js';
+export { menuContext, runMenu } from './menu.js';
+export { isCliAuthorize, menuAuthorize, menuCompletedResult, } from './opencode-v1.js';
+export { select } from './select.js';
+export { isInteractive, printLine, processTerminal } from './terminal.js';

package/dist/auth-menu/login.d.ts

@@ -0,0 +1,47 @@
+import type { PoolCredential } from '../store/index.js';
+import type { MenuContext } from './menu.js';
+/** An account a login produced, ready to become a pool row. */
+export interface LoginAccount {
+    credential: PoolCredential;
+    /** The provider's account identity, recorded on the row when known. */
+    identity?: string;
+    label?: string;
+    /** The row id to use for a new account; the menu makes one otherwise. */
+    id?: string;
+}
+/** A started login: where the operator signs in, and its eventual account. */
+export interface LoginFlow {
+    url: string;
+    instructions: string;
+    completion: Promise<LoginAccount>;
+}
+/** The plugin's login, supplied to the menu's add and re-authenticate actions. */
+export interface MenuLogin {
+    /**
+     * Starts a browser login (`headless: false`, abortable through `signal`) or
+     * a device-code login (`headless: true`) for a machine without a browser.
+     */
+    begin(options: {
+        headless: boolean;
+        signal?: AbortSignal;
+    }): Promise<LoginFlow>;
+    /**
+     * Opens the URL in a browser; false or a throw means no browser could be
+     * opened. Defaults to `openBrowserForMenu`.
+     */
+    openBrowser?(url: string): boolean | undefined | Promise<boolean | undefined>;
+}
+type BrowserExec = (file: string, args: string[], options: {
+    stdio: 'ignore';
+    timeout: number;
+}) => unknown;
+/** Opens a URL with the platform's opener; false when that fails. */
+export declare function openBrowserForMenu(url: string, platform?: NodeJS.Platform, execFileSync?: BrowserExec): boolean;
+/**
+ * Runs a login for the menu: a browser login first and, when no browser can
+ * be opened, a device-code login instead, so a headless machine can still
+ * add an account. The URL is always printed, so an operator can open it by
+ * hand when the opener reports success but nothing appears.
+ */
+export declare function runMenuLogin(login: MenuLogin, context: MenuContext): Promise<LoginAccount>;
+export {};

package/dist/auth-menu/login.js

@@ -0,0 +1,63 @@
+import { execFileSync as defaultExecFileSync } from 'node:child_process';
+/** Opens a URL with the platform's opener; false when that fails. */
+export function openBrowserForMenu(url, platform = process.platform, execFileSync = defaultExecFileSync) {
+    try {
+        if (platform === 'win32') {
+            execFileSync('cmd', ['/c', 'start', '', url], {
+                stdio: 'ignore',
+                timeout: 3000,
+            });
+        }
+        else {
+            execFileSync(platform === 'darwin' ? 'open' : 'xdg-open', [url], {
+                stdio: 'ignore',
+                timeout: 3000,
+            });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function printFlow(context, flow) {
+    context.print('');
+    context.print('Open this URL in your browser and complete sign-in:');
+    context.print('');
+    context.print(flow.url);
+    context.print('');
+    if (flow.instructions) {
+        context.print(flow.instructions);
+        context.print('');
+    }
+}
+/**
+ * Runs a login for the menu: a browser login first and, when no browser can
+ * be opened, a device-code login instead, so a headless machine can still
+ * add an account. The URL is always printed, so an operator can open it by
+ * hand when the opener reports success but nothing appears.
+ */
+export async function runMenuLogin(login, context) {
+    const abort = new AbortController();
+    let flow = await login.begin({ headless: false, signal: abort.signal });
+    // Attached before the opener runs: an opener failure aborts this flow in
+    // the same turn, and its rejection must not surface as unhandled.
+    void flow.completion.catch(() => { });
+    printFlow(context, flow);
+    let opened = false;
+    try {
+        opened =
+            (await (login.openBrowser ?? openBrowserForMenu)(flow.url)) !== false;
+    }
+    catch {
+        opened = false;
+    }
+    if (!opened) {
+        abort.abort();
+        context.print('Could not open a browser. Switching to device authorization.');
+        context.print('');
+        flow = await login.begin({ headless: true });
+        printFlow(context, flow);
+    }
+    return flow.completion;
+}

package/dist/auth-menu/menu.d.ts

@@ -0,0 +1,59 @@
+import { type MenuItem, type SelectOptions } from './select.js';
+import { type MenuTerminal } from './terminal.js';
+/** What an action is given to talk to the operator. */
+export interface MenuContext {
+    terminal: MenuTerminal;
+    /** Whether keys can be read; false when the menu printed a plain list. */
+    interactive: boolean;
+    print(line?: string): void;
+    /** A yes/no question; false on a terminal that cannot take keys. */
+    confirm(message: string, defaultYes?: boolean): Promise<boolean>;
+    /** A list choice; null on cancel or on a terminal that cannot take keys. */
+    select<T>(items: readonly MenuItem<T>[], options: SelectOptions): Promise<T | null>;
+}
+export interface MenuAction {
+    id: string;
+    label: string;
+    hint?: string;
+    /**
+     * Shown in red and run only after the operator answers yes to `confirm`
+     * (or "<label>?"). An action that first asks which account to act on
+     * leaves this unset and confirms through its context once it knows.
+     */
+    destructive?: boolean;
+    confirm?: string;
+    run(context: MenuContext): void | Promise<void>;
+}
+export interface RunMenuOptions {
+    title: string;
+    subtitle?: string;
+    /** Lines shown above the actions, such as the accounts and their state. */
+    status?: readonly string[];
+    actions: readonly MenuAction[];
+    /** Defaults to the current process's terminal. */
+    terminal?: MenuTerminal;
+}
+export type MenuOutcome = {
+    status: 'ran';
+    action: string;
+} | {
+    status: 'declined';
+    action: string;
+} | {
+    status: 'failed';
+    action: string;
+    error: unknown;
+} | {
+    status: 'cancelled';
+} | {
+    status: 'not-interactive';
+};
+export declare function menuContext(terminal: MenuTerminal): MenuContext;
+/**
+ * Show the full-screen menu once and run the chosen action. Without an
+ * interactive terminal it prints the same content as a plain list and runs
+ * nothing, so a piped or scripted login exits cleanly instead of hanging on
+ * a key that never comes. An action's failure is printed and reported rather
+ * than thrown, because the caller still owes the host its result.
+ */
+export declare function runMenu(options: RunMenuOptions): Promise<MenuOutcome>;

package/dist/auth-menu/menu.js

@@ -0,0 +1,73 @@
+import { confirm } from './confirm.js';
+import { select } from './select.js';
+import { isInteractive, printLine, processTerminal, } from './terminal.js';
+export function menuContext(terminal) {
+    const interactive = isInteractive(terminal);
+    return {
+        terminal,
+        interactive,
+        print: (line) => printLine(terminal, line),
+        confirm: (message, defaultYes) => confirm(terminal, message, defaultYes),
+        select: async (items, options) => interactive && items.length > 0 ? select(terminal, items, options) : null,
+    };
+}
+function printPlainMenu(context, options) {
+    context.print(options.title);
+    if (options.subtitle)
+        context.print(options.subtitle);
+    for (const line of options.status ?? [])
+        context.print(`  ${line}`);
+    context.print('');
+    context.print('Actions:');
+    for (const action of options.actions) {
+        context.print(action.hint
+            ? `  - ${action.label} (${action.hint})`
+            : `  - ${action.label}`);
+    }
+    context.print('');
+    context.print('This menu needs an interactive terminal to choose an action; nothing was changed.');
+    return { status: 'not-interactive' };
+}
+/**
+ * Show the full-screen menu once and run the chosen action. Without an
+ * interactive terminal it prints the same content as a plain list and runs
+ * nothing, so a piped or scripted login exits cleanly instead of hanging on
+ * a key that never comes. An action's failure is printed and reported rather
+ * than thrown, because the caller still owes the host its result.
+ */
+export async function runMenu(options) {
+    const terminal = options.terminal ?? processTerminal();
+    const context = menuContext(terminal);
+    if (!context.interactive)
+        return printPlainMenu(context, options);
+    if (options.actions.length === 0) {
+        context.print('No actions are available.');
+        return { status: 'cancelled' };
+    }
+    const chosen = await select(terminal, options.actions.map((action) => ({
+        label: action.label,
+        value: action,
+        color: action.destructive ? 'red' : 'cyan',
+        ...(action.hint ? { hint: action.hint } : {}),
+    })), {
+        message: options.title,
+        subtitle: options.subtitle ?? 'Select an account action',
+        ...(options.status ? { lines: options.status } : {}),
+        clearScreen: true,
+    });
+    if (!chosen)
+        return { status: 'cancelled' };
+    if (chosen.destructive &&
+        !(await context.confirm(chosen.confirm ?? `${chosen.label}?`))) {
+        context.print('Cancelled; nothing was changed.');
+        return { status: 'declined', action: chosen.id };
+    }
+    try {
+        await chosen.run(context);
+        return { status: 'ran', action: chosen.id };
+    }
+    catch (error) {
+        context.print(`${chosen.label} failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { status: 'failed', action: chosen.id, error };
+    }
+}

package/dist/auth-menu/opencode-v1.d.ts

@@ -0,0 +1,49 @@
+/** The inputs the CLI passes to `authorize`; the TUI passes none. */
+export type AuthorizeInputs = Record<string, string>;
+/** The automatic-method result OpenCode v1 awaits after `authorize`. */
+export interface MenuCompletedResult {
+    url: '';
+    instructions: '';
+    method: 'auto';
+    callback(): Promise<{
+        type: 'failed';
+    }>;
+}
+/**
+ * The result to hand back after the menu has run, whatever the action did.
+ *
+ * The host's result type has no top-level "done, store nothing": every
+ * result ends in a callback whose success the host files as the provider's
+ * own credential. An account added, re-authenticated or repaired from the
+ * menu is already stored by the plugin, and storing it again in the host's
+ * slot would make an extra account the provider's main credential. A failed
+ * callback is the only result that stores nothing, so the operator sees
+ * "Failed to authorize" after every menu action; that line is expected.
+ */
+export declare function menuCompletedResult(): MenuCompletedResult;
+/** Whether `authorize` was called by `opencode auth login` rather than the TUI. */
+export declare function isCliAuthorize(inputs: AuthorizeInputs | undefined): inputs is AuthorizeInputs;
+export interface MenuAuthorizeOptions<R> {
+    /**
+     * Whether this machine is past its first sign-in: a real credential exists,
+     * in the host's slot or in the plugin's store.
+     *
+     * Do not answer "the account roster is not empty". The signed-in account
+     * is usually the only one there is and may not be a roster row, so a
+     * roster check hides the menu from exactly the operator who came to add
+     * their first extra account, and on a headless machine leaves them no way
+     * to do it.
+     */
+    hasCredential(): boolean | Promise<boolean>;
+    /** Shows the menu and runs the chosen action. */
+    openMenu(inputs: AuthorizeInputs): Promise<unknown>;
+    /** The plugin's normal login, used by the TUI and by a first CLI login. */
+    login(inputs?: AuthorizeInputs): Promise<R>;
+}
+/**
+ * Builds an OAuth method's `authorize`: the TUI and a first CLI login get
+ * the plugin's normal login; a CLI login on a machine with a credential gets
+ * the menu, then the failed result described at `menuCompletedResult`. The
+ * TUI path never runs `hasCredential`, so it reads nothing it did not before.
+ */
+export declare function menuAuthorize<R>(options: MenuAuthorizeOptions<R>): (inputs?: AuthorizeInputs) => Promise<R | MenuCompletedResult>;

package/dist/auth-menu/opencode-v1.js

@@ -0,0 +1,47 @@
+// The OpenCode v1 side of the account menu.
+//
+// `opencode auth login` calls an OAuth method's `authorize(inputs?)` and then
+// awaits the returned result's `callback()`; a success there is stored as the
+// provider's credential. `inputs` is passed only by the CLI, never by the TUI,
+// which is what lets the CLI path open a menu while the TUI keeps signing in
+// as before. The types here are structural copies of the host's
+// `AuthOAuthResult` so the library does not depend on the host's package.
+/**
+ * The result to hand back after the menu has run, whatever the action did.
+ *
+ * The host's result type has no top-level "done, store nothing": every
+ * result ends in a callback whose success the host files as the provider's
+ * own credential. An account added, re-authenticated or repaired from the
+ * menu is already stored by the plugin, and storing it again in the host's
+ * slot would make an extra account the provider's main credential. A failed
+ * callback is the only result that stores nothing, so the operator sees
+ * "Failed to authorize" after every menu action; that line is expected.
+ */
+export function menuCompletedResult() {
+    return {
+        url: '',
+        instructions: '',
+        method: 'auto',
+        callback: async () => ({ type: 'failed' }),
+    };
+}
+/** Whether `authorize` was called by `opencode auth login` rather than the TUI. */
+export function isCliAuthorize(inputs) {
+    return inputs !== undefined;
+}
+/**
+ * Builds an OAuth method's `authorize`: the TUI and a first CLI login get
+ * the plugin's normal login; a CLI login on a machine with a credential gets
+ * the menu, then the failed result described at `menuCompletedResult`. The
+ * TUI path never runs `hasCredential`, so it reads nothing it did not before.
+ */
+export function menuAuthorize(options) {
+    return async (inputs) => {
+        if (!isCliAuthorize(inputs))
+            return options.login();
+        if (!(await options.hasCredential()))
+            return options.login(inputs);
+        await options.openMenu(inputs);
+        return menuCompletedResult();
+    };
+}

package/dist/auth-menu/select.d.ts

@@ -0,0 +1,21 @@
+import { type MenuTerminal } from './terminal.js';
+export interface MenuItem<T = string> {
+    label: string;
+    value: T;
+    color?: 'red' | 'cyan';
+    /** Dim text shown after the label, such as an account's state. */
+    hint?: string;
+}
+export interface SelectOptions {
+    message: string;
+    subtitle?: string;
+    /** Lines shown between the subtitle and the items, such as status lines. */
+    lines?: readonly string[];
+    clearScreen?: boolean;
+}
+/**
+ * Render a bounded, keyboard-only terminal selector without a prompt
+ * dependency. Resolves the chosen value, or null on Escape, Ctrl-C, a signal,
+ * or a terminal that refuses raw mode.
+ */
+export declare function select<T>(terminal: MenuTerminal, items: readonly MenuItem<T>[], options: SelectOptions): Promise<T | null>;

package/dist/auth-menu/select.js

@@ -0,0 +1,153 @@
+import { ANSI, parseKey, truncateAnsi } from './ansi.js';
+import { isInteractive } from './terminal.js';
+/** How long a lone Escape byte waits for the rest of an arrow-key sequence. */
+const ESCAPE_TIMEOUT_MS = 50;
+function colorCode(color) {
+    if (color === 'red')
+        return ANSI.red;
+    if (color === 'cyan')
+        return ANSI.cyan;
+    return '';
+}
+/**
+ * Render a bounded, keyboard-only terminal selector without a prompt
+ * dependency. Resolves the chosen value, or null on Escape, Ctrl-C, a signal,
+ * or a terminal that refuses raw mode.
+ */
+export async function select(terminal, items, options) {
+    if (!isInteractive(terminal))
+        throw new Error('Interactive select requires a TTY terminal');
+    if (items.length === 0)
+        throw new Error('No menu items provided');
+    const { input: stdin, output: stdout, signals } = terminal;
+    let cursor = 0;
+    let escapeTimeout = null;
+    let cleaned = false;
+    let renderedLines = 0;
+    const render = () => {
+        const columns = stdout.columns ?? 80;
+        const rows = stdout.rows ?? 24;
+        const previousLines = renderedLines;
+        if (options.clearScreen) {
+            stdout.write(ANSI.clearScreen + ANSI.moveTo(1, 1));
+        }
+        else if (previousLines > 0) {
+            stdout.write(ANSI.up(previousLines));
+        }
+        let lines = 0;
+        const writeLine = (line) => {
+            stdout.write(`${ANSI.clearLine}${line}\n`);
+            lines += 1;
+        };
+        const extraLines = options.lines ?? [];
+        const headerLines = 1 +
+            (options.subtitle ? 3 : 0) +
+            extraLines.length +
+            (extraLines.length ? 1 : 0);
+        const maxVisible = Math.max(1, Math.min(items.length, rows - headerLines - 2 - 1));
+        const windowStart = Math.max(0, Math.min(cursor - Math.floor(maxVisible / 2), Math.max(0, items.length - maxVisible)));
+        const visibleItems = items.slice(windowStart, windowStart + maxVisible);
+        writeLine(`${ANSI.dim}┌  ${ANSI.reset}${truncateAnsi(options.message, Math.max(1, columns - 4))}`);
+        if (options.subtitle) {
+            writeLine(`${ANSI.dim}│${ANSI.reset}`);
+            writeLine(`${ANSI.cyan}◆${ANSI.reset}  ${truncateAnsi(options.subtitle, Math.max(1, columns - 4))}`);
+            writeLine('');
+        }
+        for (const line of extraLines) {
+            writeLine(`${ANSI.cyan}│${ANSI.reset}  ${truncateAnsi(line, Math.max(1, columns - 4))}`);
+        }
+        if (extraLines.length)
+            writeLine(`${ANSI.cyan}│${ANSI.reset}`);
+        for (let offset = 0; offset < visibleItems.length; offset++) {
+            const item = visibleItems[offset];
+            if (!item)
+                continue;
+            const selected = windowStart + offset === cursor;
+            const color = colorCode(item.color);
+            let label = color
+                ? `${selected ? '' : ANSI.dim}${color}${item.label}${ANSI.reset}`
+                : selected
+                    ? item.label
+                    : `${ANSI.dim}${item.label}${ANSI.reset}`;
+            if (item.hint)
+                label += ` ${ANSI.dim}${item.hint}${ANSI.reset}`;
+            label = truncateAnsi(label, Math.max(1, columns - 8));
+            writeLine(selected
+                ? `${ANSI.cyan}│${ANSI.reset}  ${ANSI.green}●${ANSI.reset} ${label}`
+                : `${ANSI.cyan}│${ANSI.reset}  ${ANSI.dim}○${ANSI.reset} ${label}`);
+        }
+        const windowHint = visibleItems.length < items.length
+            ? ` (${windowStart + 1}-${windowStart + visibleItems.length}/${items.length})`
+            : '';
+        writeLine(`${ANSI.cyan}│${ANSI.reset}  ${ANSI.dim}${truncateAnsi(`Up/Down to select | Enter: confirm | Esc: back${windowHint}`, Math.max(1, columns - 6))}${ANSI.reset}`);
+        writeLine(`${ANSI.cyan}└${ANSI.reset}`);
+        for (let extra = lines; extra < previousLines; extra++)
+            writeLine('');
+        renderedLines = lines;
+    };
+    return new Promise((resolve) => {
+        const wasRaw = stdin.isRaw ?? false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            if (escapeTimeout)
+                clearTimeout(escapeTimeout);
+            stdin.removeListener('data', onKey);
+            try {
+                stdin.setRawMode(wasRaw);
+                stdin.pause();
+                stdout.write(ANSI.show);
+            }
+            catch { }
+            signals?.removeListener('SIGINT', onSignal);
+            signals?.removeListener('SIGTERM', onSignal);
+        };
+        const finish = (value) => {
+            cleanup();
+            resolve(value);
+        };
+        const onSignal = () => finish(null);
+        const onKey = (data) => {
+            if (escapeTimeout) {
+                clearTimeout(escapeTimeout);
+                escapeTimeout = null;
+            }
+            switch (parseKey(data)) {
+                case 'up':
+                    cursor = (cursor - 1 + items.length) % items.length;
+                    render();
+                    break;
+                case 'down':
+                    cursor = (cursor + 1) % items.length;
+                    render();
+                    break;
+                case 'enter':
+                    finish(items[cursor]?.value ?? null);
+                    break;
+                case 'escape':
+                    finish(null);
+                    break;
+                case 'escape-start':
+                    // A bare Escape byte is also the start of an arrow-key sequence
+                    // that may arrive split across reads; only a lone one cancels.
+                    escapeTimeout = setTimeout(() => finish(null), ESCAPE_TIMEOUT_MS);
+                    break;
+            }
+        };
+        signals?.once('SIGINT', onSignal);
+        signals?.once('SIGTERM', onSignal);
+        try {
+            stdin.setRawMode(true);
+        }
+        catch {
+            cleanup();
+            resolve(null);
+            return;
+        }
+        stdin.resume();
+        stdout.write(ANSI.hide);
+        render();
+        stdin.on('data', onKey);
+    });
+}