API reference
caique/prompt-for
Every export of caique/prompt-for, with its signature and doc comment: promptFor, PromptRefusal, plus 5 types.
import { promptFor, PromptRefusal } from 'caique/prompt-for';Functions
promptFor
Wrap a command so that its declared prompts are resolved before its handler runs (R1, R2, R6).
function promptFor<T extends PromptableCommand>(command: T & CarriesContext<T>, name?: string, spec?: PromptSpec, opts?: PromptForOptions): T;| Parameter | Type |
|---|---|
command | T & CarriesContext<T> |
name (optional) | string |
spec (optional) | PromptSpec |
opts (optional) | PromptForOptions |
Returns T
Classes
PromptRefusal
A refusal a handler throws: burgee reads code by name, prints message and fix (P2, P3).
class PromptRefusal extends Error {
readonly code: ResolveFailure['code'];
readonly fix: string | undefined;
/** The option or positional it stopped at, by its declared name. */
readonly option: string;
constructor(failure: ResolveFailure);
}Interfaces
PromptableArgument
A positional as promptFor reads it. burgee's ArgumentSpec satisfies it.
interface PromptableArgument extends PromptableSpec {
name: string;
}PromptableCommand
A command as promptFor reads it. burgee's Command satisfies it. run takes the host's own
context, whatever it is called; {@link promptFor} checks that it carries a {@link PromptContext}.
interface PromptableCommand {
options?: Record<string, PromptableSpec>;
arguments?: readonly PromptableArgument[];
run?: (ctx: never) => unknown;
}PromptableSpec
An option as promptFor reads it. burgee's OptionSpec satisfies it; the rest of a host's spec is carried as it is.
interface PromptableSpec {
required?: boolean;
prompt?: PromptSpec;
[field: string]: unknown;
}PromptContext
What promptFor reads of a host's run context. burgee's RunContext satisfies it.
interface PromptContext {
options: Record<string, unknown>;
/** The declared positionals by name. */
args: Record<string, unknown>;
/** The positionals as typed; an answered one is written in at its declared place. */
positionals: string[];
env: Record<string, string | undefined>;
/** Whether a person may be asked: a terminal on stdin, no `CI`, no agent (N12) — the host's answer. */
interactive: boolean;
/** The run was asked for `--json`, which an `--mcp` tool call always is (R6): nobody is there to type. */
json?: boolean;
/** The host's exit path (E5): what closes the terminal if the run is ended mid-question. */
onExit?: (handler: () => void, label?: string) => () => void;
}PromptForOptions
interface PromptForOptions {
/** Where to ask; the process's stdin and stderr when omitted, opened only if a question is asked. */
io?: Io;
}