@pristine-ts/cli 2.0.7 → 2.0.17

package/dist/types/errors/cli-error-code.enum.d.ts

@@ -3,10 +3,20 @@
  * (typed `PristineErrorCode | string`, so any enum value is accepted).
  *
  * Codes here describe CLI-specific failures — command resolution, argument mapping,
- * and argument validation.
+ * argument validation, and command-parameter binding.
  */
 export declare enum CliErrorCode {
     CommandNotFound = "COMMAND_NOT_FOUND",
     ArgumentMappingFailed = "ARGUMENT_MAPPING_FAILED",
-    ArgumentValidationFailed = "ARGUMENT_VALIDATION_FAILED"
+    ArgumentValidationFailed = "ARGUMENT_VALIDATION_FAILED",
+    /**
+     * Two `@commandParameter` properties on the same options class resolve to the same flag.
+     * A programming error in the command's options definition, not bad user input.
+     */
+    CommandParameterFlagConflict = "COMMAND_PARAMETER_FLAG_CONFLICT",
+    /**
+     * The user cancelled an interactive prompt with `Ctrl+C`. Carried by
+     * `PromptCancelledError` — a clean, user-initiated cancellation, not a failure.
+     */
+    PromptCancelled = "PROMPT_CANCELLED"
 }

package/dist/types/errors/errors.d.ts

@@ -1,2 +1,3 @@
 export * from "./cli-error-code.enum";
 export * from "./command-not-found.error";
+export * from "./prompt-cancelled.error";

package/dist/types/errors/prompt-cancelled.error.d.ts

@@ -0,0 +1,13 @@
+import { PristineError } from "@pristine-ts/common";
+/**
+ * Thrown when the user cancels an interactive prompt with `Ctrl+C`. A clean, user-initiated
+ * cancellation — not a crash — so it carries `kind: UserError` (the `CliErrorReporter`
+ * renders the message verbatim instead of a stack dump) and exit code `130`, following the
+ * POSIX `128 + SIGINT(2)` convention so shell pipelines can detect the interrupt.
+ *
+ * Callers that treat cancellation as a normal branch (e.g. `BuildStalenessPrompt`) catch it
+ * via `instanceof`; everywhere else it propagates to the reporter for a tidy exit.
+ */
+export declare class PromptCancelledError extends PristineError {
+    constructor();
+}

package/dist/types/event-handlers/cli.event-handler.d.ts

@@ -3,24 +3,27 @@ import { CommandEvent } from "../types/command-event.type";
 import { CommandEventResponse } from "../types/command-event-response.type";
 import { CommandInterface } from "../interfaces/command.interface";
 import { LogHandlerInterface } from "@pristine-ts/logging";
-import { Validator } from "@pristine-ts/class-validator";
+import { CommandArgumentResolver } from "../services/command-argument-resolver";
 export declare class CliEventHandler implements EventHandlerInterface<any, any> {
     private readonly logHandler;
-    private readonly validator;
+    private readonly commandArgumentResolver;
     private readonly commands;
-    constructor(logHandler: LogHandlerInterface, validator: Validator, commands: CommandInterface<any>[]);
-    handle(event: CommandEvent): Promise<CommandEventResponse>;
+    constructor(logHandler: LogHandlerInterface, commandArgumentResolver: CommandArgumentResolver, commands: CommandInterface<any>[]);
     /**
-     * Maps `rawArgs` (the parsed argv shape produced by `CommandEventMapper`) into a typed
-     * instance of `command.optionsType`, then runs `class-validator` against the instance.
-     *
-     * For commands that opt out of typed options (`optionsType === null`), passes the raw
-     * args through unchanged — the legacy escape hatch for commands that want to handle
-     * argv parsing themselves.
+     * Resolves and runs the command, then **returns** its exit code wrapped in a
+     * `CommandEventResponse` — it does not call `process.exit`.
      *
-     * Throws `UsageError` for mapping failures and `ValidationError` for class-validator
-     * failures. Both carry structured `details` so `CliErrorReporter` can render them as
-     * readable stderr lines without this method touching the console directly.
+     * Process lifecycle is the bin's job: `kernel.handle` resolves with this exit code,
+     * `Cli.bootstrap` returns it, and `bin.ts` does the actual `process.exit`. Returning
+     * (rather than exiting) is also what lets the interactive REPL dispatch commands
+     * through this very handler — `kernel.handle(argv, {keyname: Cli})` per typed line —
+     * without the process dying after the first command.
+     */
+    handle(event: CommandEvent): Promise<CommandEventResponse>;
+    /**
+     * Maps + validates a command's raw arguments. Delegates to the shared
+     * `CommandArgumentResolver`. Since the REPL dispatches through this same handler, the
+     * one-shot CLI and the REPL resolve arguments through identical logic.
      */
     resolveArgs(command: CommandInterface<any>, rawArgs: any): Promise<any>;
     supports(event: Event<any>): boolean;

package/dist/types/event-handlers/event-handlers.d.ts

@@ -1 +1,2 @@
 export * from "./cli.event-handler";
+export * from "./repl-start.event-handler";

package/dist/types/event-handlers/repl-start.event-handler.d.ts

@@ -0,0 +1,70 @@
+import { DependencyContainer } from "tsyringe";
+import { Event, EventHandlerInterface, Kernel } from "@pristine-ts/core";
+import { ExitCode } from "@pristine-ts/common";
+import { TraceStore } from "@pristine-ts/observability";
+import { CliOutput } from "../managers/cli-output.manager";
+import { StartReplEventPayload } from "../event-payloads/start-repl.event-payload";
+import { StartReplEventResponse } from "../types/start-repl-event-response.type";
+/**
+ * The interactive `pristine` console, modelled as a long-running event handler. Launched
+ * when the bin is invoked with no command (or `pristine repl`) — `ReplStartEventMapper`
+ * produces a `StartReplEventPayload` and this handler runs the readline loop for the rest
+ * of the process lifetime.
+ *
+ * **Why an event handler.** The REPL is the same shape as `pristine start` (or any
+ * long-running command): an EventHandler whose `handle()` doesn't return until the
+ * session ends. This gives the CLI bootstrap a uniform shape — `cli.ts` just calls
+ * `kernel.handle(argv, {keyname: Cli})` regardless of whether the user invoked a one-shot
+ * command or wants the interactive console. There is no driver/handler asymmetry left in
+ * the bootstrap; the mapping layer routes argv to the right payload.
+ *
+ * **Per-line dispatch.** Each typed line is re-entered through `kernel.handle(...,
+ * {keyname: Cli})` — using `Kernel` (the proper re-entry seam — it owns trace lifecycle,
+ * child container creation, the works). The `Kernel` is `registerInstance`-d into its
+ * own container by `Cli.bootstrap()`, so this handler injects it via DI like any other
+ * service.
+ *
+ * Plus the session verbs `/help`, `/clear`, `/exit` handled in-process (they're not
+ * commands — they don't re-enter the kernel). Tab-completion is driven by the live
+ * command registry and by recent trace ids for `/trace` / `/logs`.
+ */
+export declare class ReplStartEventHandler implements EventHandlerInterface<StartReplEventPayload, ExitCode | number> {
+    private readonly kernel;
+    private readonly container;
+    private readonly cliOutput;
+    private readonly traceStore;
+    private static readonly PROMPT;
+    private static readonly SESSION_VERBS;
+    private static readonly TRACE_ID_COMPLETION_LIMIT;
+    private commands;
+    constructor(kernel: Kernel, container: DependencyContainer, cliOutput: CliOutput, traceStore: TraceStore);
+    supports<T>(event: Event<T>): boolean;
+    /**
+     * Runs the read-eval-print loop until `/exit` or EOF (Ctrl-D). Resolves with the exit
+     * code wrapped in a `StartReplEventResponse`; the mapper surfaces that to `Cli.bootstrap`.
+     */
+    handle(event: Event<StartReplEventPayload>): Promise<StartReplEventResponse>;
+    /**
+     * Handles one input line. Returns true when the session should end.
+     */
+    private handleLine;
+    /**
+     * Readline completer. Completes `/`-prefixed command names and session verbs; for
+     * `/trace` and `/logs` it completes the trailing token with recent trace ids.
+     */
+    private complete;
+    private printBanner;
+    private printHelp;
+    private shutdown;
+    /**
+     * Enumerates every registered command. Resolved from the per-event child container the
+     * kernel handed this handler when it dispatched the REPL-start event — same container
+     * `HelpCommand`/`ListCommand` themselves use, so commands that depend on
+     * `CurrentChildContainer` resolve cleanly.
+     *
+     * `resolveAll`, justified: framework REPL infrastructure at session start — enumerating
+     * every `Command`-tagged service is a container-introspection operation with no
+     * constructor seam.
+     */
+    private resolveCommands;
+}

package/dist/types/event-payloads/event-payloads.d.ts

@@ -1 +1,2 @@
 export * from "./command.event-payload";
+export * from "./start-repl.event-payload";

package/dist/types/event-payloads/start-repl.event-payload.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Payload that signals "launch the interactive REPL." Produced by `ReplStartEventMapper`
+ * for argv shapes with no command (`pristine`) or with the explicit `repl` command
+ * (`pristine repl`). Consumed by `ReplStartEventHandler` which runs the readline loop
+ * for the rest of the process lifetime.
+ *
+ * The payload carries the `scriptPath` (argv[1]) for parity with `CommandEventPayload`
+ * and for diagnostics; the REPL itself reads its input from stdin, not from the payload.
+ */
+export declare class StartReplEventPayload {
+    scriptPath: string;
+    constructor(scriptPath: string);
+}

package/dist/types/interfaces/interfaces.d.ts

@@ -1 +1,2 @@
 export * from "./command.interface";
+export * from "./terminal-key.interface";

package/dist/types/interfaces/terminal-key.interface.d.ts

@@ -0,0 +1,11 @@
+import { TerminalKeyName } from "../enums/terminal-key-name.enum";
+/**
+ * A single decoded keypress from an interactive terminal. `name` classifies the key;
+ * `sequence` is the raw character(s) it produced — meaningful for `Character` keys (the
+ * literal typed character, echoed/accumulated by callers) and retained for the rest for
+ * diagnostics.
+ */
+export interface TerminalKey {
+    name: TerminalKeyName;
+    sequence: string;
+}

package/dist/types/managers/cli-prompt.manager.d.ts

@@ -1,9 +1,24 @@
 import { ConsoleReadlineOptions } from "../options/console-readline.options";
+import { TerminalKeyReader } from "./terminal-key-reader.manager";
 /**
- * Interactive stdin reader for CLI commands. Wraps Node's `readline/promises` and offers
- * a single `readLine` method with optional masking after input is received.
+ * Interactive terminal prompts for CLI commands, implemented entirely on Node's `readline`
+ * and raw-mode stdin — no third-party prompt library. Line-based prompts (`readLine`,
+ * `input`, `confirm`) go through `readline/promises`; the keystroke-level prompts (`select`
+ * arrow menu, masked `readSecret`) go through {@link TerminalKeyReader}.
+ *
+ * `Ctrl+C` rejects with {@link PromptCancelledError} across all of them — the line prompts
+ * via a `readline` SIGINT handler, the raw-mode prompts via the key reader — so callers get
+ * one consistent cancellation signal.
  */
 export declare class CliPrompt {
+    private readonly terminalKeyReader;
+    private static readonly CYAN;
+    private static readonly DIM;
+    private static readonly RESET;
+    private static readonly HIDE_CURSOR;
+    private static readonly SHOW_CURSOR;
+    private static readonly POINTER;
+    constructor(terminalKeyReader: TerminalKeyReader);
     /**
      * Reads a string from stdin synchronously. Returns whatever `process.stdin.read()`
      * gives back (which may be `null` when no data is buffered).
@@ -12,11 +27,53 @@ export declare class CliPrompt {
     /**
      * Reads a line from stdin after displaying a prompt. When
      * `options.showCharactersOnTyping` is false, the answered line is cleared and replaced
-     * with a masked echo so the typed value isn't left visible on screen.
+     * with a masked echo so the typed value isn't left visible on screen (a post-input clear,
+     * not true keystroke suppression — use {@link readSecret} for real masking).
      *
-     * Note: this is not a true keystroke-suppressing password input — Node's stock
-     * `readline` does not support that without raw-mode handling. The current behavior is
-     * a post-input clear, sufficient for most CLI prompts.
+     * `Ctrl+C` rejects with {@link PromptCancelledError}: registering a `SIGINT` listener on
+     * the readline interface overrides Node's default interrupt handling, turning it into a
+     * clean rejection rather than a hung promise.
      */
     readLine(question: string, options?: ConsoleReadlineOptions): Promise<string>;
+    /**
+     * Asks a free-text question, optionally with a default. The default is shown as a hint and
+     * returned verbatim when the user submits an empty line. The answer is trimmed.
+     */
+    input(message: string, defaultValue?: string): Promise<string>;
+    /**
+     * Asks a yes/no question. An empty answer takes the default; anything `BooleanAnswerParser`
+     * understands (`y`/`yes`/`true`/`1`, `n`/`no`/`false`/`0`) is accepted; anything else is
+     * re-asked. The default is shown capitalized in the `(Y/n)` / `(y/N)` hint.
+     */
+    confirm(message: string, defaultValue?: boolean): Promise<boolean>;
+    /**
+     * Presents an arrow-key menu and returns the chosen choice's `value`. `↑`/`↓` move the
+     * highlight (wrapping at the ends), `Enter` selects, `Ctrl+C` cancels. When `defaultValue`
+     * matches a choice, the menu starts on it. The cursor is hidden while the menu is active
+     * and restored afterward.
+     */
+    select<T>(message: string, choices: {
+        name: string;
+        value: T;
+    }[], defaultValue?: T): Promise<T>;
+    /**
+     * Reads a secret (password, token, …) from stdin with the typed characters masked as `*`.
+     * Real keystroke suppression via raw mode (unlike {@link readLine}'s post-input clear):
+     * each character echoes a `*`, `Backspace` erases one, `Enter` submits, `Ctrl+C` cancels.
+     * The value is returned untrimmed — a secret may legitimately contain surrounding
+     * whitespace.
+     */
+    readSecret(question: string): Promise<string>;
+    /**
+     * Writes the choice rows, highlighting the active one with a colored pointer. Each row is
+     * cleared before it's written so a repaint never leaves a longer previous label behind.
+     * @private
+     */
+    private renderChoices;
+    /**
+     * Moves the cursor back up over the previously-rendered choice rows and rewrites them, so
+     * the menu updates in place as the selection moves.
+     * @private
+     */
+    private repaintChoices;
 }

package/dist/types/managers/managers.d.ts

@@ -2,4 +2,5 @@ export * from "./cli-output.manager";
 export * from "./cli-progress-bar.manager";
 export * from "./cli-prompt.manager";
 export * from "./cli-spinner.manager";
+export * from "./terminal-key-reader.manager";
 export * from "./shell.manager";

package/dist/types/managers/terminal-key-reader.manager.d.ts

@@ -0,0 +1,31 @@
+import { TerminalKey } from "../interfaces/terminal-key.interface";
+/**
+ * Owns the raw-mode keystroke reading the interactive prompts need (arrow-key `select`,
+ * masked `readSecret`) — the one place in the CLI that flips stdin into raw mode. Node's
+ * stock `readline` is line-buffered and echoes input, so it can't drive an arrow-key menu
+ * or suppress a password's characters; this reads keys one at a time instead.
+ *
+ * Two responsibilities are handled centrally so callers don't each reimplement them:
+ *   - **Cancellation:** `Ctrl+C` rejects the read with {@link PromptCancelledError}.
+ *   - **Terminal restore:** raw mode is entered on start and restored in every exit path,
+ *     so a thrown handler or a cancellation never leaves the terminal in raw mode.
+ *
+ * The `input`/`output` fields default to the process streams and exist as a seam so tests
+ * can drive synthetic keystrokes without a real TTY.
+ */
+export declare class TerminalKeyReader {
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    /**
+     * Whether both stdin and stdout are interactive terminals. Raw-mode reading is only
+     * meaningful on a real TTY; callers fall back (or skip prompting) when this is false.
+     */
+    isInteractive(): boolean;
+    /**
+     * Reads keystrokes in raw mode, handing each decoded {@link TerminalKey} to `onKey` until
+     * `onKey` ends the read by invoking its `resolve` callback with the result. Resolves to
+     * that value; rejects with {@link PromptCancelledError} on `Ctrl+C`. Raw mode is entered
+     * on start and restored to its prior state in every exit path.
+     */
+    read<T>(onKey: (key: TerminalKey, resolve: (value: T) => void) => void): Promise<T>;
+}

package/dist/types/mappers/command-event.mapper.d.ts

@@ -1,6 +1,15 @@
-import { EventMapperInterface, EventResponse, EventsExecutionOptionsInterface, ExecutionContextInterface } from "@pristine-ts/core";
+import { EventIdManager, EventMapperInterface, EventResponse, EventsExecutionOptionsInterface, ExecutionContextInterface } from "@pristine-ts/core";
 import { CommandEventPayload } from "../event-payloads/command.event-payload";
 export declare class CommandEventMapper implements EventMapperInterface<CommandEventPayload, number> {
+    private readonly eventIdManager;
+    constructor(eventIdManager: EventIdManager);
+    /**
+     * Matches argv that names an explicit command. The no-command shape and the bare
+     * `pristine repl` form are deliberately rejected here; `ReplStartEventMapper` claims
+     * those. Commands typed inside the interactive session are also re-dispatched under
+     * `Cli`, so this mapper handles them too. Argv parsing is delegated to `PristineArgv`,
+     * which scans for the bin token rather than relying on positional indexing.
+     */
     supportsMapping(rawEvent: any, executionContext: ExecutionContextInterface<any>): boolean;
     /**
      * Inspired from: https://github.com/eveningkid/args-parser

package/dist/types/mappers/mappers.d.ts

@@ -1 +1,2 @@
 export * from "./command-event.mapper";
+export * from "./repl-start-event.mapper";

package/dist/types/mappers/repl-start-event.mapper.d.ts

@@ -0,0 +1,28 @@
+import { EventIdManager, EventMapperInterface, EventResponse, EventsExecutionOptionsInterface, ExecutionContextInterface } from "@pristine-ts/core";
+import { StartReplEventPayload } from "../event-payloads/start-repl.event-payload";
+/**
+ * Maps the "no command" / `repl` argv shapes onto a `StartReplEventPayload` so the kernel
+ * can dispatch the REPL launch through the normal event pipeline — `cli.ts` just calls
+ * `kernel.handle(process.argv, {keyname: Cli})` regardless of whether the user invoked
+ * `pristine`, `pristine repl`, or `pristine <some-command>`.
+ *
+ * Argv parsing is delegated to `PristineArgv`, which scans for the bin token rather than
+ * assuming positional layout — so the rule is runtime-agnostic and survives launchers
+ * that shape argv differently.
+ *
+ * `CommandEventMapper` explicitly excludes these same shapes from its own
+ * `supportsMapping` so the two mappers partition argv space cleanly — no shape is claimed
+ * by both.
+ */
+export declare class ReplStartEventMapper implements EventMapperInterface<StartReplEventPayload, number> {
+    private readonly eventIdManager;
+    constructor(eventIdManager: EventIdManager);
+    supportsMapping(rawEvent: any, executionContext: ExecutionContextInterface<any>): boolean;
+    map(rawEvent: any, executionContext: ExecutionContextInterface<any>): EventsExecutionOptionsInterface<StartReplEventPayload>;
+    supportsReverseMapping(eventResponse: EventResponse<StartReplEventPayload, number>, response: any, executionContext: ExecutionContextInterface<any>): boolean;
+    /**
+     * The REPL handler resolves with the session's exit code; surface it as-is so
+     * `Cli.bootstrap()` can return it to the bin (which calls `process.exit`).
+     */
+    reverseMap(eventResponse: EventResponse<StartReplEventPayload, number>, response: any, executionContext: ExecutionContextInterface<any>): any;
+}

package/dist/types/options/command-parameter.options.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Options accepted by the `@commandParameter` decorator. Every field is optional: an empty
+ * `@commandParameter()` is valid and simply marks the property as a known command-line
+ * parameter, while individual fields opt into extra behavior.
+ */
+export interface CommandParameterOptions {
+    /**
+     * The command-line flag this property binds to. Defaults to the property name.
+     *
+     * Arguments are bound to options by property name, so without an override the property
+     * must be named exactly like the flag. Set this to let the property name and the flag
+     * differ (e.g. a camelCase property bound to a dash-separated flag).
+     */
+    flag?: string;
+    /**
+     * The question to ask interactively when this parameter is absent from the command line.
+     *
+     * When set — and interactive parameters are enabled (see `CliConfigurationKeys`) and the
+     * input is an interactive terminal — the CLI asks this question and uses the answer.
+     * When omitted, the parameter is never asked for; a missing value is left to validation.
+     */
+    question?: string;
+    /**
+     * Marks the value as a secret (password, token, connection string with credentials, …).
+     * When asked for interactively, the input is masked rather than echoed, and the answer is
+     * never trimmed or printed back in any re-ask/validation feedback.
+     */
+    sensitive?: boolean;
+}

package/dist/types/options/options.d.ts

@@ -1 +1,2 @@
+export * from "./command-parameter.options";
 export * from "./console-readline.options";

package/dist/types/services/command-argument-resolver.d.ts

@@ -0,0 +1,24 @@
+import { CommandInterface } from "../interfaces/command.interface";
+import { CommandOptionsResolver } from "./command-options-resolver";
+/**
+ * Maps a command's raw parsed arguments onto a typed, validated instance of its
+ * `optionsType`. Used by both the one-shot dispatch path (`CliEventHandler.resolveArgs`)
+ * and the interactive REPL (which dispatches via that same handler), so command
+ * arguments are resolved through identical logic everywhere.
+ *
+ * Thin wrapper over `CommandOptionsResolver`: it passes the raw argv straight through for
+ * commands that opt out of typed options (`optionsType === null`) and otherwise delegates
+ * the prompt → map → validate pipeline. Commands (or dynamic flows) that need to fill an
+ * options class directly can inject `CommandOptionsResolver` instead.
+ */
+export declare class CommandArgumentResolver {
+    private readonly commandOptionsResolver;
+    constructor(commandOptionsResolver: CommandOptionsResolver);
+    /**
+     * For commands that opt out of typed options (`optionsType === null`), passes the raw
+     * args through unchanged. Otherwise delegates to `CommandOptionsResolver`, which fills any
+     * missing `@commandParameter` values by prompting, maps the result onto `optionsType`, and
+     * validates it.
+     */
+    resolve(command: CommandInterface<any>, rawArgs: any): Promise<any>;
+}

package/dist/types/services/command-options-resolver.d.ts

@@ -0,0 +1,35 @@
+import { ClassConstructor } from "class-transformer";
+import { Validator } from "@pristine-ts/class-validator";
+import { DataMapper } from "@pristine-ts/data-mapping";
+import { CommandParameterPrompter } from "./command-parameter-prompter";
+/**
+ * Resolves a typed, validated options instance from raw arguments: it fills any missing
+ * `@commandParameter` values by prompting, maps the result onto a real `optionsType`
+ * instance (prototype + decorator metadata intact, so `class-validator` finds its rules),
+ * and validates it.
+ *
+ * This is the reusable core behind command dispatch — `CommandArgumentResolver` delegates
+ * here — exposed so commands and dynamic flows can fill an options class from prompts on
+ * demand, including ones not tied to a registered command:
+ *
+ * ```ts
+ * constructor(private readonly optionsResolver: CommandOptionsResolver) {}
+ * // ...later, possibly choosing the class at runtime:
+ * const options = await this.optionsResolver.resolve(MyOptions, {region: "us"});
+ * ```
+ *
+ * Throws `UsageError` for mapping failures and `ValidationError` for validation failures —
+ * both carry structured `details` for `CliErrorReporter`.
+ */
+export declare class CommandOptionsResolver {
+    private readonly validator;
+    private readonly dataMapper;
+    private readonly commandParameterPrompter;
+    constructor(validator: Validator, dataMapper: DataMapper, commandParameterPrompter: CommandParameterPrompter);
+    /**
+     * Prompts for any missing parameters declared on `optionsType`, then maps `rawArgs` (plus
+     * the prompted answers) onto a real instance and validates it. `rawArgs` seeds the values
+     * already known — anything absent that carries a `question` is asked for interactively.
+     */
+    resolve<T>(optionsType: ClassConstructor<T>, rawArgs?: Record<string, any>): Promise<T>;
+}

package/dist/types/services/command-parameter-prompter.d.ts

@@ -0,0 +1,113 @@
+import "reflect-metadata";
+import { ClassConstructor } from "class-transformer";
+import { Validator } from "@pristine-ts/class-validator";
+import { DataMapper } from "@pristine-ts/data-mapping";
+import { CliPrompt } from "../managers/cli-prompt.manager";
+import { CliOutput } from "../managers/cli-output.manager";
+/**
+ * Applies a command's `@commandParameter` metadata to its raw, parsed arguments before they
+ * are mapped onto the options instance and validated. Two things happen here:
+ *
+ *   1. **Flag binding** — a parameter whose `flag` differs from its property name is copied
+ *      from the flag key onto the property key, so the by-property-name data mapper picks it
+ *      up. Two parameters resolving to the same flag is a programming error and throws.
+ *   2. **Interactive fill** — a parameter that is absent and declares a `question` is asked
+ *      for interactively. Answers are rendered and checked against the property's declared
+ *      type (booleans as `(y/n)`, enum-constrained values list their choices) and coerced +
+ *      validated through the same mapper/validator the command pipeline uses, re-asking on an
+ *      invalid answer. Gated by the `InteractiveParameters` configuration and only run against
+ *      an interactive terminal; otherwise the absent value is left for validation to report.
+ *
+ * Parameters without a `@commandParameter` decorator are untouched, so commands that don't
+ * use it pay nothing.
+ */
+export declare class CommandParameterPrompter {
+    private readonly cliPrompt;
+    private readonly cliOutput;
+    private readonly validator;
+    private readonly dataMapper;
+    private readonly interactiveParametersEnabled;
+    /**
+     * `@pristine-ts/class-validator` stores its instantiated validators (one per `@IsX`
+     * decorator) as an array under this property-metadata key. We read it only to surface enum
+     * choices in the prompt; all actual validation goes through `Validator`.
+     */
+    private static readonly ClassValidatorMetadataKey;
+    /**
+     * How many times a single value is re-asked before giving up and letting the missing /
+     * invalid value fall through to the normal validation error. A bound (rather than an
+     * unbounded loop) keeps a misconfigured validator that can never pass from hanging the CLI.
+     */
+    private static readonly MaxAttempts;
+    constructor(cliPrompt: CliPrompt, cliOutput: CliOutput, validator: Validator, dataMapper: DataMapper, interactiveParametersEnabled: boolean);
+    /**
+     * Returns a copy of `rawArgs` with aliased flags bound to their property and any missing,
+     * question-carrying parameters filled in interactively. The input object is never mutated
+     * — the original command event payload stays intact.
+     */
+    fillMissingParameters(optionsType: ClassConstructor<any>, rawArgs: Record<string, any>): Promise<Record<string, any>>;
+    /**
+     * Reads every `@commandParameter` off `optionsType`, resolving each to its effective flag
+     * and detecting two parameters that would claim the same flag (a programming error).
+     * @private
+     */
+    private collectParameters;
+    /**
+     * Asks for a single parameter's value, rendering and validating it according to the
+     * property's declared type:
+     *
+     *   - sensitive values are read with the input masked and never trimmed;
+     *   - booleans render as `(y/n)` and accept y/yes/true/1 & n/no/false/0;
+     *   - enum-constrained values (`@IsIn` / `@IsEnum`) list their choices;
+     *   - every other answer is coerced (via the data mapper) and validated (via the validator)
+     *     exactly as a typed flag would be, re-asking with the real constraint message when it
+     *     doesn't pass.
+     *
+     * Returns the coerced value, or `undefined` when the user enters nothing or the attempt
+     * budget is exhausted — in which case the absent value falls through to validation.
+     * @private
+     */
+    private promptForValue;
+    /**
+     * Maps a single raw answer onto a probe instance of `optionsType` and validates just that
+     * property, returning the coerced value when it passes or the constraint messages when it
+     * doesn't. Reuses the same mapper + validator the command pipeline uses, so coercion and
+     * constraints behave identically whether a value was typed as a flag or answered here.
+     * @private
+     */
+    private coerceAndValidate;
+    /**
+     * Flattens `class-validator`'s per-property constraint objects into plain, user-facing
+     * lines. `@pristine-ts/class-validator` stores each constraint as `{keyname, message}`
+     * rather than a bare string, so prefer `.message`, falling back so we never print
+     * `[object Object]`.
+     * @private
+     */
+    private describeErrors;
+    /**
+     * The allowed values declared by an `@IsIn([...])` or `@IsEnum(Enum)` on the property, for
+     * display in the prompt. Reads `@pristine-ts/class-validator`'s stored validator instances
+     * defensively — any shape mismatch just yields no menu (validation still rejects bad input
+     * and re-asks). Returns undefined when the property isn't enum-constrained.
+     * @private
+     */
+    private getChoices;
+    /**
+     * Appends a type hint to the question: `(y/n)` for booleans, `(a/b/c)` for enum choices.
+     * @private
+     */
+    private decorateQuestion;
+    /**
+     * Whether stdin is an interactive terminal. Pulled out so the gate is easy to reason about
+     * (and to stub in tests) — there is no point asking a question when input is piped or runs
+     * under CI, where a read would either hang or return EOF.
+     * @private
+     */
+    private isInputInteractive;
+    /**
+     * Ensures the rendered question ends with a trailing space so the typed answer doesn't butt
+     * up against the prompt text.
+     * @private
+     */
+    private formatQuestion;
+}

package/dist/types/services/services.d.ts

@@ -0,0 +1,3 @@
+export * from "./command-argument-resolver";
+export * from "./command-options-resolver";
+export * from "./command-parameter-prompter";

package/dist/types/types/start-repl-event-response.type.d.ts

@@ -0,0 +1,10 @@
+import { EventResponse } from "@pristine-ts/core";
+import { ExitCode } from "@pristine-ts/common";
+import { StartReplEventPayload } from "../event-payloads/start-repl.event-payload";
+/**
+ * The response shape produced by `ReplStartEventHandler` when the interactive session
+ * ends (`/exit` or EOF). Carries the exit code the bin should pass to `process.exit`,
+ * surfaced through `ReplStartEventMapper.reverseMap`.
+ */
+export declare class StartReplEventResponse extends EventResponse<StartReplEventPayload, ExitCode | number> {
+}

package/dist/types/types/types.d.ts

@@ -1,2 +1,3 @@
 export * from "./command-event.type";
 export * from "./command-event-response.type";
+export * from "./start-repl-event-response.type";

package/dist/types/utils/boolean-answer-parser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interprets a free-text answer as a boolean the way traditional CLIs do — accepting
+ * `y`/`yes`/`true`/`1` and `n`/`no`/`false`/`0` (case-insensitive, surrounding whitespace
+ * ignored). Returns `undefined` for anything unrecognized so callers can re-ask.
+ *
+ * Shared by `CliPrompt.confirm` (yes/no prompts) and `CommandParameterPrompter` (typed
+ * boolean parameters) so both accept exactly the same set of answers.
+ */
+export declare class BooleanAnswerParser {
+    static parse(raw: string): boolean | undefined;
+}