mailfully 0.1.0

package/dist/failure.d.ts

@@ -0,0 +1,22 @@
+import type { MailfullyResult } from "@mailfully/node";
+/**
+ * The API accepted the request and will dispatch nothing — every recipient was
+ * suppressed. Deliberately NOT 1: `1` means "the API refused me", and a script
+ * distinguishing the two needs them to differ. Deliberately not 0 either, so
+ * `mailfully send … && next-step` cannot treat zero delivery as success.
+ */
+export declare const EXIT_NOTHING_SENT = 3;
+/** A command-level failure: a user-facing message plus the process exit code. */
+export declare class CommandFailure extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** Raised by context resolution when no API key can be found anywhere. */
+export declare class MissingApiKeyError extends Error {
+    constructor();
+}
+/**
+ * Collapse an SDK result tuple: return the data, or throw a CommandFailure
+ * carrying the rendered API error (exit code 1).
+ */
+export declare function unwrap<T>(result: MailfullyResult<T>): T;

package/dist/failure.js

@@ -0,0 +1,34 @@
+import { renderError } from "./output.js";
+/**
+ * The API accepted the request and will dispatch nothing — every recipient was
+ * suppressed. Deliberately NOT 1: `1` means "the API refused me", and a script
+ * distinguishing the two needs them to differ. Deliberately not 0 either, so
+ * `mailfully send … && next-step` cannot treat zero delivery as success.
+ */
+export const EXIT_NOTHING_SENT = 3;
+/** A command-level failure: a user-facing message plus the process exit code. */
+export class CommandFailure extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CommandFailure";
+        this.exitCode = exitCode;
+    }
+}
+/** Raised by context resolution when no API key can be found anywhere. */
+export class MissingApiKeyError extends Error {
+    constructor() {
+        super("No API key found. Run `mailfully login`, set MAILFULLY_API_KEY, or pass --api-key.");
+        this.name = "MissingApiKeyError";
+    }
+}
+/**
+ * Collapse an SDK result tuple: return the data, or throw a CommandFailure
+ * carrying the rendered API error (exit code 1).
+ */
+export function unwrap(result) {
+    if (result.error !== null) {
+        throw new CommandFailure(renderError(result.error));
+    }
+    return result.data;
+}

package/dist/flags.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+/** Add the three per-command global flags to a leaf command. */
+export declare function withGlobalOptions(cmd: Command): Command;

package/dist/flags.js

@@ -0,0 +1,7 @@
+/** Add the three per-command global flags to a leaf command. */
+export function withGlobalOptions(cmd) {
+    return cmd
+        .option("--api-key <key>", "API key (overrides MAILFULLY_API_KEY and the stored config).")
+        .option("--api-url <url>", "API base URL (overrides MAILFULLY_API_URL and the stored config).")
+        .option("--json", "Print the raw API response as JSON.");
+}

package/dist/output.d.ts

@@ -0,0 +1,15 @@
+import type { MailfullyError } from "@mailfully/node";
+/**
+ * Render a plain-text table: header row + data rows, columns padded to the
+ * widest cell, two spaces between columns, no trailing whitespace, trailing
+ * newline. No colors, no borders — grep/cut friendly.
+ */
+export declare function formatTable(header: string[], rows: string[][]): string;
+/** Pretty-print a value as JSON with a trailing newline (for --json mode). */
+export declare function toJson(value: unknown): string;
+/**
+ * One human-readable block for an SDK error: type + status + message, the
+ * offending param when present, and a hint for the classic self-serve fixes.
+ * No trailing newline (the caller appends it when writing).
+ */
+export declare function renderError(error: MailfullyError): string;

package/dist/output.js

@@ -0,0 +1,84 @@
+/**
+ * `error.type` values that mean the credential itself is the problem — as
+ * opposed to a 403 that is refusing something else about the request
+ * (e.g. `domain_limit_reached`, also a 403, which a fresh key would not fix).
+ * This allowlist gates the 403 arm of the hint ONLY: a 401 is unconditional,
+ * because the status by itself already says the credential was not accepted.
+ */
+const AUTH_ERROR_TYPES = new Set([
+    "missing_api_key",
+    "invalid_api_key",
+    "invalid_session_token",
+    "insufficient_scope",
+]);
+/**
+ * Render a plain-text table: header row + data rows, columns padded to the
+ * widest cell, two spaces between columns, no trailing whitespace, trailing
+ * newline. No colors, no borders — grep/cut friendly.
+ */
+export function formatTable(header, rows) {
+    const all = [header, ...rows];
+    const widths = header.map((_, col) => Math.max(...all.map((row) => (row[col] ?? "").length)));
+    return (all
+        .map((row) => row
+        .map((cell, col) => cell.padEnd(widths[col] ?? 0))
+        .join("  ")
+        .trimEnd())
+        .join("\n") + "\n");
+}
+/** Pretty-print a value as JSON with a trailing newline (for --json mode). */
+export function toJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * One human-readable block for an SDK error: type + status + message, the
+ * offending param when present, and a hint for the classic self-serve fixes.
+ * No trailing newline (the caller appends it when writing).
+ */
+export function renderError(error) {
+    const status = error.statusCode === null ? "network" : `HTTP ${error.statusCode}`;
+    const lines = [
+        `Error (${error.type ?? "error"}, ${status}): ${error.message}`,
+    ];
+    if (error.param !== null) {
+        lines.push(`  param: ${error.param}`);
+    }
+    // 401 ALWAYS hints: the status alone means the credential was not accepted,
+    // and a 401 whose envelope carries no `type` (a proxy or gateway answering
+    // ahead of the API) is exactly the case a user most needs the hint for. Only
+    // 403 needs the allowlist, because a 403 can be refusing something else about
+    // the request that a fresh key would not fix.
+    if (error.statusCode === 401 ||
+        (error.statusCode === 403 &&
+            error.type !== null &&
+            AUTH_ERROR_TYPES.has(error.type))) {
+        lines.push("  Hint: check the API key and its scopes — run `mailfully login` with a fresh key from the dashboard.");
+    }
+    else if (error.statusCode === 429) {
+        // Six distinct 429s reach here and only ONE is cleared by waiting: the
+        // per-second limiter. The rest are the `SEND_REFUSAL_REASONS` family
+        // (`packages/db/src/schema/sendRefusals.ts`) — allowances, caps, and the
+        // admission hold. The retry advice is therefore an ALLOWLIST of one rather
+        // than a copy of the other five: the CLI cannot import that enum
+        // (`@mailfully/db` is private and pulls drizzle + ioredis), so a sixth code
+        // added there inherits whichever branch is the default. Defaulting to "not
+        // retryable" makes that drift harmless instead of actively misleading.
+        //
+        // A TYPELESS 429 is the deliberate exception, and the mirror of the 401 arm
+        // above: no envelope means a proxy or gateway answered ahead of the API,
+        // and that one really is a rate limiter.
+        if (error.type === "account_under_review") {
+            // Deliberately does NOT restate the server's own message (already
+            // printed verbatim above) or its 24-hour figure, which is owned by
+            // `APPROVAL_QUEUE_SLA_HOURS`. It adds only what the envelope omits.
+            lines.push("  Hint: retrying will not clear this — the account is waiting on a human review. Test-mode keys (`mf_test_`) keep working meanwhile.");
+        }
+        else if (error.type === null || error.type === "rate_limit_exceeded") {
+            lines.push("  Hint: rate limited — wait a moment and retry.");
+        }
+        else {
+            lines.push("  Hint: a send quota or cap, not the per-second rate limit — retrying will not clear it until the window resets or the limit is raised in the dashboard.");
+        }
+    }
+    return lines.join("\n");
+}

package/dist/pages.d.ts

@@ -0,0 +1,42 @@
+import type { MailfullyResult, Page } from "@mailfully/node";
+/** Injectable delay so tests run instantly (see ProgramDeps.sleep). */
+export type Sleep = (ms: number) => Promise<void>;
+export declare const defaultSleep: Sleep;
+/**
+ * Walk every page of a keyset-paginated endpoint (--all). Two behaviors
+ * single-page calls don't need:
+ *   - a 429 waits RETRY_DELAY_MS and retries (up to MAX_RETRIES_PER_PAGE per
+ *     page) — a bulk walk is exactly the client that trips the rate limiter;
+ *   - a terminal failure mid-walk names the last good cursor in its message,
+ *     so a long walk is resumable rather than all-or-nothing.
+ *
+ * `initialCursor` seeds the walk (from `--cursor`, when the caller passed
+ * one) — omit it to start from page one.
+ */
+export declare function walkPages<T>(fetchPage: (cursor: string | undefined) => Promise<MailfullyResult<Page<T>>>, sleep: Sleep, initialCursor?: string): Promise<T[]>;
+/**
+ * Shared driver for a paginated `list` command (`--limit`/`--cursor`/`--all`),
+ * so every list renders and pages identically. `--all` walks every page via
+ * {@link walkPages} and `--all --json` prints a synthesized `{ data: [...] }`
+ * (there is no single wire page to echo); a single-page `--json` echoes the
+ * raw page, and a single-page table is followed by a next-cursor hint.
+ */
+export declare function renderPagedList<T>(args: {
+    all: boolean | undefined;
+    cursor: string | undefined;
+    limit: string | undefined;
+    json: boolean;
+    header: string[];
+    toCells: (item: T) => string[];
+    fetchPage: (paging: {
+        cursor?: string;
+        limit?: number;
+    }) => Promise<MailfullyResult<Page<T>>>;
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    sleep: Sleep;
+}): Promise<void>;

package/dist/pages.js

@@ -0,0 +1,76 @@
+import { CommandFailure, unwrap } from "./failure.js";
+import { formatTable, renderError, toJson } from "./output.js";
+export const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const MAX_RETRIES_PER_PAGE = 5;
+const RETRY_DELAY_MS = 2000;
+/**
+ * Walk every page of a keyset-paginated endpoint (--all). Two behaviors
+ * single-page calls don't need:
+ *   - a 429 waits RETRY_DELAY_MS and retries (up to MAX_RETRIES_PER_PAGE per
+ *     page) — a bulk walk is exactly the client that trips the rate limiter;
+ *   - a terminal failure mid-walk names the last good cursor in its message,
+ *     so a long walk is resumable rather than all-or-nothing.
+ *
+ * `initialCursor` seeds the walk (from `--cursor`, when the caller passed
+ * one) — omit it to start from page one.
+ */
+export async function walkPages(fetchPage, sleep, initialCursor) {
+    const rows = [];
+    let cursor = initialCursor;
+    for (;;) {
+        let page;
+        let attempt = 0;
+        for (;;) {
+            const result = await fetchPage(cursor);
+            if (result.error === null) {
+                page = result.data;
+                break;
+            }
+            if (result.error.statusCode === 429 && attempt < MAX_RETRIES_PER_PAGE) {
+                attempt += 1;
+                await sleep(RETRY_DELAY_MS);
+                continue;
+            }
+            const resume = cursor === undefined
+                ? ""
+                : `\n  Rows fetched so far were discarded — re-run with --all --cursor ${cursor} to resume.`;
+            throw new CommandFailure(`${renderError(result.error)}${resume}`);
+        }
+        rows.push(...page.data);
+        if (page.next_cursor === null)
+            return rows;
+        cursor = page.next_cursor;
+    }
+}
+/**
+ * Shared driver for a paginated `list` command (`--limit`/`--cursor`/`--all`),
+ * so every list renders and pages identically. `--all` walks every page via
+ * {@link walkPages} and `--all --json` prints a synthesized `{ data: [...] }`
+ * (there is no single wire page to echo); a single-page `--json` echoes the
+ * raw page, and a single-page table is followed by a next-cursor hint.
+ */
+export async function renderPagedList(args) {
+    const { header, toCells, fetchPage } = args;
+    if (args.all === true) {
+        const rows = await walkPages((cursor) => fetchPage({ cursor, limit: 100 }), args.sleep, args.cursor);
+        if (args.json) {
+            args.stdout.write(toJson({ data: rows }));
+            return;
+        }
+        args.stdout.write(formatTable(header, rows.map(toCells)));
+        return;
+    }
+    const page = unwrap(await fetchPage({
+        ...(args.cursor !== undefined ? { cursor: args.cursor } : {}),
+        ...(args.limit !== undefined ? { limit: Number(args.limit) } : {}),
+    }));
+    if (args.json) {
+        args.stdout.write(toJson(page));
+        return;
+    }
+    args.stdout.write(formatTable(header, page.data.map(toCells)));
+    if (page.has_more && page.next_cursor !== null) {
+        // Hint goes to stderr: stdout carries only data, so pipelines stay clean.
+        args.stderr.write(`More results: rerun with --cursor ${page.next_cursor}\n`);
+    }
+}

package/dist/parse.d.ts

@@ -0,0 +1,37 @@
+import type { MessageType, SendEmailInput, Tag } from "@mailfully/node";
+/** commander collector: repeatable string option → string[]. */
+export declare function collectString(value: string, previous: string[] | undefined): string[];
+/**
+ * commander collector: repeatable `name=value` option → record. Splits on the
+ * FIRST `=` so values may contain `=`. An empty name is a usage error
+ * (InvalidArgumentError → commander usage failure → exit 2).
+ */
+export declare function collectPair(value: string, previous: Record<string, string> | undefined): Record<string, string>;
+/**
+ * commander parser: validate `--type` against the wire `MessageType` enum.
+ * An unrecognized value is a usage error (InvalidArgumentError → commander
+ * usage failure → exit 2), matching {@link collectPair}'s treatment of a
+ * malformed `--tag`/`--var`/`--header` value.
+ */
+export declare function parseMessageType(value: string): MessageType;
+/** `--tag` pairs → the SDK's Tag[] shape. */
+export declare function pairsToTags(pairs: Record<string, string>): Tag[];
+/**
+ * Resolve a body that may come inline (`--html "<p>x</p>"`) or from a file
+ * (`--html-file body.html`). Both at once is a usage error (exit 2); an
+ * unreadable file is a runtime failure (exit 1).
+ */
+export declare function readBody(inline: string | undefined, file: string | undefined, flag: string): Promise<string | undefined>;
+/**
+ * Read and JSON-parse a file argument. An unreadable file is a runtime
+ * failure (exit 1); malformed JSON is a usage error (exit 2) — the file's
+ * contents are the user's input.
+ */
+export declare function readJsonFile(path: string): Promise<unknown>;
+/**
+ * Map one wire-shape (snake_case) email object from a batch file to the SDK's
+ * camelCase {@link SendEmailInput}. Only two keys differ (`reply_to`,
+ * `scheduled_at`); everything else passes through untouched — the API is the
+ * validator, the CLI is a faithful courier.
+ */
+export declare function wireToSendInput(raw: Record<string, unknown>): SendEmailInput;

package/dist/parse.js

@@ -0,0 +1,92 @@
+import { readFile } from "node:fs/promises";
+import { InvalidArgumentError } from "commander";
+import { CommandFailure } from "./failure.js";
+/** commander collector: repeatable string option → string[]. */
+export function collectString(value, previous) {
+    return [...(previous ?? []), value];
+}
+/**
+ * commander collector: repeatable `name=value` option → record. Splits on the
+ * FIRST `=` so values may contain `=`. An empty name is a usage error
+ * (InvalidArgumentError → commander usage failure → exit 2).
+ */
+export function collectPair(value, previous) {
+    const eq = value.indexOf("=");
+    if (eq <= 0) {
+        throw new InvalidArgumentError("Expected name=value.");
+    }
+    return { ...(previous ?? {}), [value.slice(0, eq)]: value.slice(eq + 1) };
+}
+/**
+ * commander parser: validate `--type` against the wire `MessageType` enum.
+ * An unrecognized value is a usage error (InvalidArgumentError → commander
+ * usage failure → exit 2), matching {@link collectPair}'s treatment of a
+ * malformed `--tag`/`--var`/`--header` value.
+ */
+export function parseMessageType(value) {
+    if (value !== "transactional" && value !== "marketing") {
+        throw new InvalidArgumentError(`Expected "transactional" or "marketing", got "${value}".`);
+    }
+    return value;
+}
+/** `--tag` pairs → the SDK's Tag[] shape. */
+export function pairsToTags(pairs) {
+    return Object.entries(pairs).map(([name, value]) => ({ name, value }));
+}
+/**
+ * Resolve a body that may come inline (`--html "<p>x</p>"`) or from a file
+ * (`--html-file body.html`). Both at once is a usage error (exit 2); an
+ * unreadable file is a runtime failure (exit 1).
+ */
+export async function readBody(inline, file, flag) {
+    if (inline !== undefined && file !== undefined) {
+        throw new CommandFailure(`Use ${flag} or ${flag}-file, not both.`, 2);
+    }
+    if (file !== undefined) {
+        try {
+            return await readFile(file, "utf8");
+        }
+        catch {
+            throw new CommandFailure(`Could not read ${file}.`);
+        }
+    }
+    return inline;
+}
+/**
+ * Read and JSON-parse a file argument. An unreadable file is a runtime
+ * failure (exit 1); malformed JSON is a usage error (exit 2) — the file's
+ * contents are the user's input.
+ */
+export async function readJsonFile(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        throw new CommandFailure(`Could not read ${path}.`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new CommandFailure(`${path} is not valid JSON.`, 2);
+    }
+}
+/**
+ * Map one wire-shape (snake_case) email object from a batch file to the SDK's
+ * camelCase {@link SendEmailInput}. Only two keys differ (`reply_to`,
+ * `scheduled_at`); everything else passes through untouched — the API is the
+ * validator, the CLI is a faithful courier.
+ */
+export function wireToSendInput(raw) {
+    const { reply_to, scheduled_at, ...rest } = raw;
+    return {
+        ...rest,
+        ...(reply_to !== undefined
+            ? { replyTo: reply_to }
+            : {}),
+        ...(scheduled_at !== undefined
+            ? { scheduledAt: scheduled_at }
+            : {}),
+    };
+}

package/dist/program.d.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+/** Everything the program touches in the outside world, injected for tests. */
+export interface ProgramDeps {
+    env: Record<string, string | undefined>;
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    /** Injected into the SDK; defaults to global fetch when omitted. */
+    fetchImpl?: typeof fetch;
+    /** Config-file location (tests point this at a temp file). */
+    configPath: string;
+    /** Injected secret prompt; defaults to the readline prompt (Task 8). */
+    promptSecret?: (promptText: string) => Promise<string>;
+    /** Injected delay for the --all 429 backoff (Task 12); tests pass an instant one. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Build the full command tree. Output is routed through the injected streams
+ * and exits are overridden, so the program is a pure function of (argv, deps).
+ *
+ * NOTE: `.configureOutput` and `.exitOverride` MUST be set before any
+ * `.command(...)` call — commander copies inherited settings into subcommands
+ * at creation time.
+ */
+export declare function buildProgram(deps: ProgramDeps): Command;
+/**
+ * Parse argv and translate every outcome into an exit code:
+ *   0 — success, help, or version
+ *   1 — API/transport/config failure (CommandFailure, MissingApiKeyError)
+ *   2 — usage error (unknown command/option, bad argument)
+ */
+export declare function runCli(argv: string[], deps: ProgramDeps): Promise<number>;

package/dist/program.js

@@ -0,0 +1,83 @@
+import { Command, CommanderError } from "commander";
+import { registerAnalyticsCommands } from "./commands/analytics.js";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerDomainsCommands } from "./commands/domains.js";
+import { registerEmailsCommands } from "./commands/emails.js";
+import { registerSuppressionsCommands } from "./commands/suppressions.js";
+import { registerTemplatesCommands } from "./commands/templates.js";
+import { CommandFailure, MissingApiKeyError } from "./failure.js";
+import { cliVersion } from "./version.js";
+/**
+ * Build the full command tree. Output is routed through the injected streams
+ * and exits are overridden, so the program is a pure function of (argv, deps).
+ *
+ * NOTE: `.configureOutput` and `.exitOverride` MUST be set before any
+ * `.command(...)` call — commander copies inherited settings into subcommands
+ * at creation time.
+ */
+export function buildProgram(deps) {
+    const program = new Command("mailfully");
+    program
+        .description("The Mailfully command-line interface.")
+        .version(cliVersion(), "--version", "Print the CLI version.")
+        .configureOutput({
+        writeOut: (str) => void deps.stdout.write(str),
+        writeErr: (str) => void deps.stderr.write(str),
+    })
+        .exitOverride();
+    registerAuthCommands(program, deps);
+    registerEmailsCommands(program, deps);
+    registerDomainsCommands(program, deps);
+    registerTemplatesCommands(program, deps);
+    registerSuppressionsCommands(program, deps);
+    registerAnalyticsCommands(program, deps);
+    return program;
+}
+/**
+ * Parse argv and translate every outcome into an exit code:
+ *   0 — success, help, or version
+ *   1 — API/transport/config failure (CommandFailure, MissingApiKeyError)
+ *   2 — usage error (unknown command/option, bad argument)
+ */
+export async function runCli(argv, deps) {
+    const program = buildProgram(deps);
+    if (argv.length === 0) {
+        program.outputHelp();
+        return 0;
+    }
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CommandFailure) {
+            // An EMPTY message means the command already wrote its own explanation
+            // (or is in --json mode, where stderr must stay clean) and is throwing
+            // only to carry the exit code out.
+            if (err.message !== "") {
+                deps.stderr.write(`${err.message}\n`);
+            }
+            return err.exitCode;
+        }
+        if (err instanceof MissingApiKeyError) {
+            deps.stderr.write(`${err.message}\n`);
+            return 1;
+        }
+        if (err instanceof CommanderError) {
+            if (err.code === "commander.helpDisplayed" ||
+                err.code === "commander.version") {
+                return 0;
+            }
+            if (err.code === "commander.help") {
+                // Thrown for both `mailfully help` (exitCode 0) and a bare group
+                // command like `mailfully emails` (help({ error: true }), exitCode 1
+                // — a usage mistake). Preserve the 0/2 contract accordingly.
+                return err.exitCode === 0 ? 0 : 2;
+            }
+            // commander already wrote the usage message via configureOutput.
+            return 2;
+        }
+        deps.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Prompt for a secret on the controlling terminal without echoing it: the
+ * prompt text goes to stderr (stdout stays clean for piping) and the readline
+ * interface is given NO output stream, so typed characters are never echoed.
+ * When stdin is not a TTY (e.g. `mailfully login < keyfile`), reads one line.
+ *
+ * EOF safety: on a closed/empty stdin (CI with no input, Ctrl+D) the question
+ * callback never fires — the `close` handler resolves with "" so the caller's
+ * empty-key check turns it into a clean usage error instead of a hang. Ctrl+C
+ * at the prompt maps to the same path.
+ */
+export declare function promptSecret(promptText: string): Promise<string>;

package/dist/prompt.js

@@ -0,0 +1,37 @@
+import { createInterface } from "node:readline";
+/**
+ * Prompt for a secret on the controlling terminal without echoing it: the
+ * prompt text goes to stderr (stdout stays clean for piping) and the readline
+ * interface is given NO output stream, so typed characters are never echoed.
+ * When stdin is not a TTY (e.g. `mailfully login < keyfile`), reads one line.
+ *
+ * EOF safety: on a closed/empty stdin (CI with no input, Ctrl+D) the question
+ * callback never fires — the `close` handler resolves with "" so the caller's
+ * empty-key check turns it into a clean usage error instead of a hang. Ctrl+C
+ * at the prompt maps to the same path.
+ */
+export function promptSecret(promptText) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            process.stderr.write("\n");
+            resolve(value.trim());
+        };
+        process.stderr.write(promptText);
+        const rl = createInterface({
+            input: process.stdin,
+            terminal: process.stdin.isTTY === true,
+        });
+        rl.on("close", () => settle(""));
+        rl.on("SIGINT", () => rl.close());
+        rl.question("", (answer) => {
+            // settle BEFORE close: rl.close() emits 'close' synchronously, and the
+            // close handler's settle("") must lose this race, not win it.
+            settle(answer);
+            rl.close();
+        });
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The CLI's own version, read from package.json at runtime via createRequire —
+ * works identically from src (tests) and from the published dist layout, since
+ * both sit one directory below the package root.
+ */
+export declare function cliVersion(): string;

package/dist/version.js

@@ -0,0 +1,11 @@
+import { createRequire } from "node:module";
+/**
+ * The CLI's own version, read from package.json at runtime via createRequire —
+ * works identically from src (tests) and from the published dist layout, since
+ * both sit one directory below the package root.
+ */
+export function cliVersion() {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../package.json");
+    return pkg.version;
+}