promptdock 1.0.1 → 1.2.0

package/dist/context.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
 import { readFileSync } from "node:fs";
 /**
  * argv joined for the `X-Promptdock-Cli-Args` header, with bearer tokens removed.
@@ -13,6 +14,12 @@ import { readFileSync } from "node:fs";
  * still needs to show that `--token` was passed.
  */
 export function redactArgs(argv) {
+    // ⚠️ COUPLING: this is a DENYLIST keyed on the flags that carry sensitive
+    // values. Any NEW value-carrying flag added to args.ts COMMAND_SPECS must be
+    // assessed here in the same change — a missed one leaks silently (the header
+    // rides every request and every proxy logs it). Current set: --token (the
+    // live bearer) and --dir (absolute local paths carry the OS username +
+    // client/project names — data the 426 remedy does not need; review find).
     return argv
         .map((a, i) => {
         if (/^pdk_/.test(a))
@@ -22,10 +29,55 @@ export function redactArgs(argv) {
             return "--token=***";
         if (argv[i - 1] === "--token")
             return "***";
+        if (/^--dir=/.test(a))
+            return "--dir=***";
+        if (argv[i - 1] === "--dir")
+            return "***";
         return a;
     })
         .join(" ");
 }
+/**
+ * Process-level terminal safety net. The picker's `finally` restores raw mode
+ * + cursor on every JS path (resolve/reject/throw, and ^C arrives as a
+ * keypress under raw mode) — but an EXTERNAL SIGTERM/SIGHUP or `kill` runs no
+ * finally: the process dies with the cursor hidden (`?25l` persists until
+ * `reset`; 4 review voices converged on this). One-shot handlers restore the
+ * terminal and re-exit with the conventional 128+signal code.
+ */
+let activeRawRelease = null;
+let terminalSafetyInstalled = false;
+function installTerminalSafety() {
+    if (terminalSafetyInstalled)
+        return;
+    terminalSafetyInstalled = true;
+    const restore = () => {
+        try {
+            activeRawRelease?.();
+        }
+        catch {
+            /* stdin already torn down */
+        }
+        try {
+            process.stdout.write("[?25h");
+        }
+        catch {
+            /* stdout already torn down */
+        }
+    };
+    // 'exit' covers process.exit() and normal termination; fatal signals with
+    // default handlers do NOT fire it, hence the explicit signal hooks.
+    process.on("exit", restore);
+    for (const [sig, code] of [
+        ["SIGTERM", 143],
+        ["SIGHUP", 129],
+    ]) {
+        process.on(sig, () => {
+            restore();
+            process.exit(code);
+        });
+    }
+}
 /** Read the package's own version (dist/ and src/ both sit one level under the root). */
 export function readOwnVersion() {
     try {
@@ -70,6 +122,54 @@ export function realContext(argv) {
                     rl.close();
                 }
             },
+            // Only offered when raw mode is genuinely available AND the terminal can
+            // render ANSI. `setRawMode` is absent whenever stdin is not a TTY (a
+            // pipe, a spawned child, CI); TERM=dumb (Emacs M-x shell, some IDE
+            // consoles) IS a pty but cannot render the escapes the picker paints —
+            // it gets the numbered reader, as the README promises (review find).
+            ...(isTTY &&
+                typeof process.stdin.setRawMode === "function" &&
+                process.env.TERM !== "dumb"
+                ? {
+                    rawKeys: (onKey) => {
+                        installTerminalSafety();
+                        const stdin = process.stdin;
+                        emitKeypressEvents(stdin);
+                        const wasRaw = stdin.isRaw === true;
+                        stdin.setRawMode(true);
+                        stdin.resume();
+                        const handler = (_s, key) => {
+                            if (key)
+                                onKey(key);
+                        };
+                        stdin.on("keypress", handler);
+                        let released = false;
+                        // Idempotent: the picker releases in a `finally`, and a second call
+                        // during process teardown must not throw on an already-closed stdin.
+                        const release = () => {
+                            if (released)
+                                return;
+                            released = true;
+                            if (activeRawRelease === release)
+                                activeRawRelease = null;
+                            stdin.off("keypress", handler);
+                            try {
+                                stdin.setRawMode(wasRaw);
+                            }
+                            catch {
+                                /* stdin already torn down */
+                            }
+                            stdin.pause();
+                        };
+                        activeRawRelease = release;
+                        return release;
+                    },
+                    size: () => ({
+                        rows: process.stdout.rows ?? 24,
+                        columns: process.stdout.columns ?? 80,
+                    }),
+                }
+                : {}),
         },
         env: process.env,
         cwd: process.cwd(),

package/dist/contract.d.ts

@@ -31,6 +31,13 @@ export type ResolveResponse = {
     is_free?: boolean;
     file_count?: number;
     total_bytes?: number;
+    /**
+     * The oldest CLI generation whose install-safety fuses admit this package, or
+     * null/absent when every published CLI can install it. Lets an old client refuse
+     * ONE oversized package with an upgrade prompt instead of the server bumping a
+     * global version floor that would 426 every request from every old client.
+     */
+    min_cli_version?: string | null;
     description?: string;
     license?: string;
     /** insufficient_tier */

package/dist/errors.d.ts

@@ -12,6 +12,11 @@ export declare const EXIT: {
     readonly IO: 5;
     /** couldn't reach the API */
     readonly NETWORK: 6;
+    /** Ctrl-C during an interactive picker — 128+SIGINT, the shell convention.
+     *  Raw mode swallows the real signal (it arrives as a keypress), so the CLI
+     *  exits with the code a signal death would have produced. Esc (a deliberate
+     *  in-UI cancel) stays USAGE=1. Scripts never reach pickers (TTY-only). */
+    readonly INTERRUPT: 130;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
 /** DX3: every named error footer links its docs anchor. */

package/dist/errors.js

@@ -13,6 +13,11 @@ export const EXIT = {
     IO: 5,
     /** couldn't reach the API */
     NETWORK: 6,
+    /** Ctrl-C during an interactive picker — 128+SIGINT, the shell convention.
+     *  Raw mode swallows the real signal (it arrives as a keypress), so the CLI
+     *  exits with the code a signal death would have produced. Esc (a deliberate
+     *  in-UI cancel) stays USAGE=1. Scripts never reach pickers (TTY-only). */
+    INTERRUPT: 130,
 };
 /** DX3: every named error footer links its docs anchor. */
 export function footerUrl(code) {

package/dist/generated/constants.d.ts

@@ -1,9 +1,19 @@
 export declare const MAX_SKILL_FILES = 25;
 export declare const MAX_SKILL_TOTAL_BYTES = 5242880;
 export declare const MAX_SKILL_FILE_BYTES = 1048576;
+export declare const CLI_DOS_MAX_SKILL_FILES = 200;
+export declare const CLI_DOS_MAX_SKILL_TOTAL_BYTES = 52428800;
+export declare const CLI_DOS_MAX_SKILL_FILE_BYTES = 5242880;
+export declare const CLI_FUSE_HISTORY: {
+    cli_version: string;
+    max_files: number;
+    max_file_bytes: number;
+    max_total_bytes: number;
+}[];
 export declare const MAX_SKILL_IMAGES = 5;
 export declare const SKILL_REVEAL_DAILY_CAP = 15;
-export declare const CLI_MIN_VERSION = "0.1.0";
+export declare const CLI_MIN_VERSION = "1.0.1";
+export declare const PUBLISHED_CLI_VERSION = "1.1.0";
 export declare const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
 export declare const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
 export declare const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";

package/dist/generated/constants.js

@@ -3,9 +3,14 @@
 export const MAX_SKILL_FILES = 25;
 export const MAX_SKILL_TOTAL_BYTES = 5242880;
 export const MAX_SKILL_FILE_BYTES = 1048576;
+export const CLI_DOS_MAX_SKILL_FILES = 200;
+export const CLI_DOS_MAX_SKILL_TOTAL_BYTES = 52428800;
+export const CLI_DOS_MAX_SKILL_FILE_BYTES = 5242880;
+export const CLI_FUSE_HISTORY = [{ "cli_version": "0.0.0", "max_files": 25, "max_file_bytes": 1048576, "max_total_bytes": 5242880 }, { "cli_version": "1.2.0", "max_files": 200, "max_file_bytes": 5242880, "max_total_bytes": 52428800 }];
 export const MAX_SKILL_IMAGES = 5;
 export const SKILL_REVEAL_DAILY_CAP = 15;
-export const CLI_MIN_VERSION = "0.1.0";
+export const CLI_MIN_VERSION = "1.0.1";
+export const PUBLISHED_CLI_VERSION = "1.1.0";
 export const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
 export const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
 export const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";

package/dist/help.js

@@ -21,8 +21,8 @@ export function globalHelp(version) {
     help                      this map
 
   Install options
-    -g, --global              install into the tool's per-user dir instead of the project
-    --target <tool>           skip the picker (${TARGETS.map((t) => t.id).join(", ")})
+    -g, --global              install into the tool's per-user dir (skips the scope prompt)
+    --target <tool>           pick the tool (${TARGETS.map((t) => t.id).join(", ")}); scope is still asked — add -g or -y to skip
     --dir <path>              install into an explicit directory
     -y, --yes                 skip prompts (needs an unambiguous target; NEVER implies --force)
     --force                   replace a non-empty foreign directory / overwrite local edits
@@ -62,11 +62,15 @@ session stays valid until revoked in Settings → Account → CLI sessions.`,
 Shows the signed-in handle, role, and token expiry.`,
     install: `promptdock install <handle>/<slug> [-g] [--target <tool>] [--dir <path>] [-y] [--force] [--dry-run] [--json]
 
-Installs a skill. Non-interactive sessions (CI) must pass --target or --dir
-plus -y, and authenticate via PROMPTDOCK_TOKEN. -y skips the target picker
-ONLY — a non-empty foreign directory still requires --force. --dry-run
-resolves and prints the plan without installing (and without spending any
-premium-unlock slot).`,
+Installs a skill. Interactively it asks two things: which TOOL, then whether
+to install for THIS PROJECT or for your USER ACCOUNT (each shown as its real
+destination path). -g answers the second one up front; --dir answers both.
+
+Non-interactive sessions (CI) must pass --target or --dir plus -y, and
+authenticate via PROMPTDOCK_TOKEN. -y skips the prompts ONLY — a non-empty
+foreign directory still requires --force, and scope stays project-local
+unless -g is passed. --dry-run resolves and prints the plan without
+installing (and without spending any premium-unlock slot).`,
     uninstall: `promptdock uninstall <handle>/<slug> | --all [-g] [--target <tool>] [--dir <path>] [--force] [-y] [--json]
 
 Removes an installed skill using its .promptdock.json receipt — only files the

package/dist/installer.d.ts

@@ -5,8 +5,18 @@ import { type Receipt } from "./receipts.js";
 /** Narrow the untrusted install response; throws INTEGRITY on a bad shape. */
 export declare function checkInstallResponse(resp: unknown): InstallResponse;
 /**
- * E8 client-side re-validation + the shared D7 bounds. A server compromise must
- * not become an arbitrary file write OR a disk-filling download.
+ * E8 client-side re-validation against this CLI's own INSTALL-SAFETY FUSES.
+ *
+ * ⚠️ These bounds are SELF-PROTECTION, not a mirror of the platform's policy: "a
+ * server compromise must not become an arbitrary file write OR a disk-filling
+ * download." They are sized from memory/disk/runtime budgets and are deliberately far
+ * above any policy the platform would set, so a legitimate policy raise never needs a
+ * CLI release. Reaching one of them means the server sent something this CLI considers
+ * impossible — hence EXIT.INTEGRITY.
+ *
+ * The FRIENDLY, package-scoped refusal ("this skill needs a newer CLI") lives in
+ * verdicts.ts::assertInstallable and fires BEFORE the metered install POST. This
+ * function is the untrusted-server backstop behind it and must never be removed.
  */
 export declare function assertSafeManifest(manifest: ManifestEntry[]): void;
 export type StagedInstall = {

package/dist/installer.js

@@ -9,7 +9,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CliError, EXIT, mapFsError, networkError } from "./errors.js";
-import { MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, MAX_SKILL_TOTAL_BYTES, } from "./generated/constants.js";
+import { CLI_DOS_MAX_SKILL_FILES as MAX_SKILL_FILES, CLI_DOS_MAX_SKILL_FILE_BYTES as MAX_SKILL_FILE_BYTES, CLI_DOS_MAX_SKILL_TOTAL_BYTES as MAX_SKILL_TOTAL_BYTES, } from "./generated/constants.js";
 import { sha256Hex, sha256Matches } from "./integrity.js";
 import { validateSkillPaths } from "./paths.js";
 import { writeReceipt, RECEIPT_SCHEMA } from "./receipts.js";
@@ -37,8 +37,62 @@ export function checkInstallResponse(resp) {
     return r;
 }
 /**
- * E8 client-side re-validation + the shared D7 bounds. A server compromise must
- * not become an arbitrary file write OR a disk-filling download.
+ * Read a response body, aborting the moment it exceeds `limit`.
+ *
+ * `res.arrayBuffer()` has no ceiling: it reads whatever the server sends. Streaming and
+ * cancelling means a hostile or broken server cannot make this process hold more than
+ * one file's worth of bytes, which is the property the install-safety fuse is claiming.
+ *
+ * Falls back to `arrayBuffer()` only when the runtime gives us no readable stream (older
+ * Node fetch shims) — with the post-hoc size check still applied, so the bound holds
+ * either way.
+ */
+async function readBounded(res, limit, path) {
+    const tooBig = () => new CliError(`${INTEGRITY_ABORT} ("${path}" oversized)`, EXIT.INTEGRITY, { footer: "integrity" });
+    const body = res.body;
+    if (!body || typeof body.getReader !== "function") {
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.byteLength > limit)
+            throw tooBig();
+        return buf;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > limit) {
+                // Stop pulling bytes immediately — this is the whole point.
+                await reader.cancel().catch(() => { });
+                throw tooBig();
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c)), total);
+}
+/**
+ * E8 client-side re-validation against this CLI's own INSTALL-SAFETY FUSES.
+ *
+ * ⚠️ These bounds are SELF-PROTECTION, not a mirror of the platform's policy: "a
+ * server compromise must not become an arbitrary file write OR a disk-filling
+ * download." They are sized from memory/disk/runtime budgets and are deliberately far
+ * above any policy the platform would set, so a legitimate policy raise never needs a
+ * CLI release. Reaching one of them means the server sent something this CLI considers
+ * impossible — hence EXIT.INTEGRITY.
+ *
+ * The FRIENDLY, package-scoped refusal ("this skill needs a newer CLI") lives in
+ * verdicts.ts::assertInstallable and fires BEFORE the metered install POST. This
+ * function is the untrusted-server backstop behind it and must never be removed.
  */
 export function assertSafeManifest(manifest) {
     const issues = validateSkillPaths(manifest.map((e) => e.path));
@@ -79,6 +133,18 @@ export async function downloadAndStage(ctx, api, resp, targetDir) {
     }
     const tempDir = join(parent, `.promptdock-staging-${randomBytes(6).toString("hex")}`);
     const files = [];
+    /**
+     * Bytes actually RECEIVED, not bytes the server said it would send.
+     *
+     * ⚠️ `assertSafeManifest` enforces the aggregate fuse against `entry.bytes` — a field
+     * the untrusted server supplies and that the response check does not even require. So
+     * before this counter the only bound the wire really carried was PER FILE, and a
+     * hostile server could declare 1 KB per entry and stream the per-file maximum for every
+     * one of them: at the raised fuses that is 200 × 5 MB ≈ 1 GB written to disk, which is
+     * precisely the "disk-filling download" this module's own docstring says it prevents.
+     * The manifest check is a fast pre-flight; THIS is the enforcement.
+     */
+    let received = 0;
     try {
         mkdirSync(tempDir, { recursive: true });
         for (const entry of resp.manifest) {
@@ -99,11 +165,25 @@ export async function downloadAndStage(ctx, api, resp, targetDir) {
                 // A lapsed signed URL is a free re-request (audit row 13) — say so.
                 throw new CliError(`download failed for "${entry.path}" (HTTP ${res.status}) — re-run the install (the download link may have expired; retrying is free)`, EXIT.NETWORK, { footer: "download" });
             }
-            const buf = Buffer.from(await res.arrayBuffer());
-            if (buf.byteLength > MAX_SKILL_FILE_BYTES) {
-                throw new CliError(`${INTEGRITY_ABORT} ("${entry.path}" oversized)`, EXIT.INTEGRITY, {
-                    footer: "integrity",
-                });
+            // ⚠️ CHECK BEFORE BUFFERING, then check again after.
+            //
+            // The fuse exists so a compromised server cannot fill your disk, and
+            // `await res.arrayBuffer()` reads the ENTIRE body into memory first — so a check
+            // that only runs afterwards has already let the download happen. A hostile server
+            // could stream gigabytes and the guard would fire, too late, on a machine that had
+            // already paid for it.
+            //
+            // So: refuse on a declared `content-length` over the fuse without reading a byte,
+            // and refuse again on the real length (content-length is server-supplied and may
+            // be absent or lie, which is exactly why the second check stays).
+            const declared = Number(res.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > MAX_SKILL_FILE_BYTES) {
+                throw new CliError(`${INTEGRITY_ABORT} ("${entry.path}" declares ${declared} bytes, over the limit)`, EXIT.INTEGRITY, { footer: "integrity" });
+            }
+            const buf = await readBounded(res, MAX_SKILL_FILE_BYTES, entry.path);
+            received += buf.byteLength;
+            if (received > MAX_SKILL_TOTAL_BYTES) {
+                throw new CliError(`${INTEGRITY_ABORT} (the package sent more than the ${MAX_SKILL_TOTAL_BYTES}-byte install limit)`, EXIT.INTEGRITY, { footer: "integrity" });
             }
             if (!sha256Matches(buf, entry.sha256)) {
                 throw new CliError(`${INTEGRITY_ABORT} (sha256 mismatch on "${entry.path}")`, EXIT.INTEGRITY, {

package/dist/registry.d.ts

@@ -26,6 +26,62 @@ export declare function targetInstallDir(t: TargetDef, opts: {
     global: boolean;
     slug: string;
 }): string;
+/** Is this tool set up in each scope? Path knowledge stays in this module. */
+export declare function detectScopes(t: TargetDef, opts: {
+    cwd: string;
+    home: string;
+    exists?: (p: string) => boolean;
+}): {
+    local: boolean;
+    global: boolean;
+};
+export type ScopedTarget = TargetDef & {
+    detectedLocal: boolean;
+    detectedGlobal: boolean;
+    detected: boolean;
+};
+/**
+ * Scope-agnostic detection for the interactive picker, which asks for the TOOL
+ * first and the SCOPE second — so at list time there is no single scope to
+ * probe. `detected` (either scope) drives the D-UX11 float ordering; the
+ * per-scope flags let the row say WHERE it was found, which the old
+ * one-scope-only tag could not.
+ */
+export declare function detectTargetsAnyScope(opts: {
+    cwd: string;
+    home: string;
+    exists?: (p: string) => boolean;
+}): ScopedTarget[];
+/** Where a tool was found, for the picker row ("" when nowhere). */
+export declare function detectionLabel(t: {
+    detectedLocal: boolean;
+    detectedGlobal: boolean;
+}): string;
+export type ScopeChoice = {
+    global: boolean;
+    label: string;
+    dir: string;
+    detected: boolean;
+};
+/**
+ * The two concrete destinations for a chosen tool, in prompt order (project,
+ * then global), plus the preselect index. Pure so the prompt's content is
+ * unit-testable without a TTY.
+ *
+ * Preselect prefers the scope where the tool is ALREADY set up. When it is set
+ * up in both — or in neither — it stays project-local, which is exactly what
+ * `-y` and non-TTY runs default to, so the interactive and non-interactive
+ * paths can never disagree about the same repo.
+ */
+export declare function scopeChoices(t: TargetDef, opts: {
+    cwd: string;
+    home: string;
+    slug: string;
+    exists?: (p: string) => boolean;
+}): {
+    choices: [ScopeChoice, ScopeChoice];
+    preselect: 0 | 1;
+};
 export type DetectedTarget = TargetDef & {
     detected: boolean;
 };

package/dist/registry.js

@@ -80,6 +80,71 @@ export function targetBaseDir(t, opts) {
 export function targetInstallDir(t, opts) {
     return join(targetBaseDir(t, opts), opts.slug);
 }
+/** Is this tool set up in each scope? Path knowledge stays in this module. */
+export function detectScopes(t, opts) {
+    const exists = opts.exists ?? existsSync;
+    return {
+        local: exists(join(opts.cwd, t.detectLocal)),
+        global: exists(join(opts.home, t.detectGlobal)),
+    };
+}
+/**
+ * Scope-agnostic detection for the interactive picker, which asks for the TOOL
+ * first and the SCOPE second — so at list time there is no single scope to
+ * probe. `detected` (either scope) drives the D-UX11 float ordering; the
+ * per-scope flags let the row say WHERE it was found, which the old
+ * one-scope-only tag could not.
+ */
+export function detectTargetsAnyScope(opts) {
+    const all = TARGETS.map((t) => {
+        const found = detectScopes(t, opts);
+        return {
+            ...t,
+            detectedLocal: found.local,
+            detectedGlobal: found.global,
+            detected: found.local || found.global,
+        };
+    });
+    return [...all.filter((t) => t.detected), ...all.filter((t) => !t.detected)];
+}
+/** Where a tool was found, for the picker row ("" when nowhere). */
+export function detectionLabel(t) {
+    if (t.detectedLocal && t.detectedGlobal)
+        return "(detected: project + global)";
+    if (t.detectedLocal)
+        return "(detected: project)";
+    if (t.detectedGlobal)
+        return "(detected: global)";
+    return "";
+}
+/**
+ * The two concrete destinations for a chosen tool, in prompt order (project,
+ * then global), plus the preselect index. Pure so the prompt's content is
+ * unit-testable without a TTY.
+ *
+ * Preselect prefers the scope where the tool is ALREADY set up. When it is set
+ * up in both — or in neither — it stays project-local, which is exactly what
+ * `-y` and non-TTY runs default to, so the interactive and non-interactive
+ * paths can never disagree about the same repo.
+ */
+export function scopeChoices(t, opts) {
+    const found = detectScopes(t, opts);
+    const choices = [
+        {
+            global: false,
+            label: "This directory",
+            dir: targetInstallDir(t, { ...opts, global: false }),
+            detected: found.local,
+        },
+        {
+            global: true,
+            label: "Global",
+            dir: targetInstallDir(t, { ...opts, global: true }),
+            detected: found.global,
+        },
+    ];
+    return { choices, preselect: !found.local && found.global ? 1 : 0 };
+}
 /**
  * D-UX11 ordering: detected tools float to the top (registry order preserved
  * within each group); the preselect is index 0 (first detected, else Claude).

package/dist/select-keys.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Key handling for the interactive picker, as a PURE reducer.
+ *
+ * Kept out of ui.ts on purpose: the rendering half needs a real TTY (raw mode,
+ * cursor moves) and cannot be unit-tested, but the DECISIONS — what wraps, what
+ * commits, what cancels — are the part that regresses. Pure in, pure out, so
+ * every key path is pinned by a table test with no terminal involved.
+ */
+/** The subset of node:readline's keypress event this reducer reads. */
+export type Key = {
+    name?: string;
+    sequence?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+};
+export type SelectState = {
+    /** highlighted option */
+    index: number;
+    /** digits typed so far — the "type a number" path, empty when unused */
+    buffer: string;
+};
+export type SelectResult = {
+    kind: "state";
+    state: SelectState;
+} | {
+    kind: "commit";
+    index: number;
+}
+/** `signal` marks Ctrl-C (exit 130, the 128+SIGINT convention); Esc/Ctrl-D
+ *  are deliberate in-UI cancels (exit 1). */
+ | {
+    kind: "cancel";
+    signal?: boolean;
+}
+/** a typed number that names no option — caller flashes a hint, keeps the prompt */
+ | {
+    kind: "reject";
+    state: SelectState;
+    message: string;
+};
+/**
+ * One keypress → the next state, or a terminal outcome.
+ *
+ * Both input styles stay live at once, which is the whole point: arrows move the
+ * highlight, digits ALSO move it (so typing is visible before you commit), and
+ * Enter commits whichever the user last expressed. Space commits the highlight
+ * only — it is a "this one" gesture, and treating it as a number-confirm would
+ * make a half-typed "1" + Space silently pick option 1 when the user meant 12.
+ *
+ * Digits never auto-commit. `3` in a 4-item list is unambiguous and a fancier
+ * picker would fire immediately, but the user asked to KEEP number entry, and
+ * number entry means "type it, then press Enter" — auto-firing would make a
+ * two-digit list behave differently from a one-digit list.
+ *
+ * `hotkeys` (letter → option index) commit IMMEDIATELY — the confirm path
+ * passes {y:0, n:1}. Without this, `n`+Enter at a default-Yes "Install?"
+ * committed the DEFAULT: the muscle-memory answer this CLI's own [y/N]
+ * fallback trains was silently ignored and the UI executed the opposite of
+ * what the user typed (dual-review find, PTY-proven).
+ */
+export declare function reduceSelectKey(state: SelectState, key: Key, count: number, hotkeys?: Record<string, number>): SelectResult;
+/** Footer hint. Mentions BOTH input styles — neither is discoverable otherwise.
+ *  `hotkeyLabel` (e.g. "y/n") leads when the picker has letter hotkeys. */
+export declare function selectHint(count: number, buffer: string, hotkeyLabel?: string): string;