@pristine-ts/cli 2.0.6 → 2.0.16

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

@@ -0,0 +1,79 @@
+import { ConsoleReadlineOptions } from "../options/console-readline.options";
+import { TerminalKeyReader } from "./terminal-key-reader.manager";
+/**
+ * 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).
+     */
+    read(): string;
+    /**
+     * 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 (a post-input clear,
+     * not true keystroke suppression — use {@link readSecret} for real masking).
+     *
+     * `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/cli-spinner.manager.d.ts

@@ -0,0 +1,34 @@
+import { LogHandlerInterface } from "@pristine-ts/logging";
+/**
+ * Animated spinner for indicating long-running work in a TTY. Hides the cursor while
+ * spinning, redraws the current line every 80ms, and routes the completion message
+ * through the injected `LogHandler` so success/failure rendering matches the rest of
+ * the framework.
+ *
+ * Avoid emitting other output (especially LogHandler narration) while the spinner is
+ * active — concurrent writes will fight the spinner's line clearing and produce visual
+ * artifacts.
+ */
+export declare class CliSpinner {
+    private readonly logHandler;
+    private spinnerInterval;
+    private isSpinning;
+    private static readonly FRAMES;
+    private static readonly FRAME_INTERVAL_MS;
+    private static readonly CYAN;
+    private static readonly RESET;
+    private static readonly HIDE_CURSOR;
+    private static readonly SHOW_CURSOR;
+    constructor(logHandler: LogHandlerInterface);
+    /**
+     * Starts the spinner with the given label. Subsequent calls are no-ops until `stop()`
+     * is invoked.
+     */
+    start(message: string): void;
+    /**
+     * Stops the spinner, restores the cursor, and optionally emits a final completion
+     * message. `success` controls whether the message is rendered as a success log
+     * (`logHandler.success`) or an error log (`logHandler.error`).
+     */
+    stop(message?: string, success?: boolean): void;
+}

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

@@ -1,2 +1,6 @@
-export * from "./console.manager";
+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/repl-session.d.ts

@@ -0,0 +1,62 @@
+import { Kernel } from "@pristine-ts/core";
+import { ObservabilityStoreReader } from "@pristine-ts/observability";
+import { CliOutput } from "./cli-output.manager";
+/**
+ * The interactive `pristine` console — launched when the bin is invoked with no command
+ * (or `pristine repl`). It keeps the kernel booted for the whole session, so every
+ * command runs instantly with no per-invocation boot cost.
+ *
+ * Slash-prefixed commands dispatch through the *same* path as a one-shot
+ * `pristine <command>` invocation — `kernel.handle(argv, {keyname: Cli})` — so the REPL
+ * and the command line resolve, validate and run commands identically. (This works
+ * because `CliEventHandler` returns the exit code instead of calling `process.exit`.)
+ * Plus the session verbs `/help`, `/clear`, `/exit`. Tab-completion is driven by the live
+ * command registry and by recent trace ids for `/trace` / `/logs`.
+ *
+ * The kernel is **not** a constructor dependency — `ReplSession` is a driver *of* the
+ * kernel, so the running kernel is handed to `start()` by whoever owns it (`Cli`). Only
+ * genuine collaborator services are injected.
+ */
+export declare class ReplSession {
+    private readonly cliOutput;
+    private readonly storeReader;
+    private static readonly PROMPT;
+    private static readonly SESSION_VERBS;
+    private static readonly TRACE_ID_COMPLETION_LIMIT;
+    private commands;
+    constructor(cliOutput: CliOutput, storeReader: ObservabilityStoreReader);
+    /**
+     * Runs the read-eval-print loop until `/exit` or EOF (Ctrl-D). Resolves with the exit
+     * code the bin should return.
+     *
+     * @param kernel The already-started kernel this session drives — passed in by the
+     *   caller that owns it, rather than injected.
+     */
+    start(kernel: Kernel): Promise<number>;
+    /**
+     * 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 a dedicated child container with the `CurrentChildContainer` token
+     * registered — some commands (`HelpCommand`, `ListCommand`) inject that token, which
+     * only the kernel's per-event child containers carry. The one-shot path gets it for
+     * free because `CliEventHandler` runs inside such a child container; the REPL builds an
+     * equivalent one once for the whole session.
+     *
+     * `resolveAll`, justified: this is framework REPL infrastructure resolved at session
+     * start, mirroring `Cli.warnOnCommandCollisions`. Enumerating every `Command`-tagged
+     * service is inherently a container-introspection operation with no constructor seam.
+     */
+    private resolveCommands;
+}

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

@@ -1,12 +1,12 @@
 import { ChildProcessWithoutNullStreams } from "child_process";
-import { ConsoleManager } from "./console.manager";
 import { PathManager } from "@pristine-ts/core";
 import { DateUtil } from "@pristine-ts/common";
+import { LogHandlerInterface } from "@pristine-ts/logging";
 export declare class ShellManager {
-    private readonly consoleManager;
+    private readonly logHandler;
     private readonly pathManager;
     private readonly dateUtil;
-    constructor(consoleManager: ConsoleManager, pathManager: PathManager, dateUtil: DateUtil);
+    constructor(logHandler: LogHandlerInterface, pathManager: PathManager, dateUtil: DateUtil);
     execute(command: string, options?: {
         directory?: string;
         streamStdout?: boolean;

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;
+}

package/dist/types/utils/pristine-argv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Parses an argv array — typically `process.argv` — to locate the pristine bin and
+ * extract the user-typed arguments that follow it.
+ *
+ * Why scan rather than positional-index: argv shape is runtime-dependent. Node and Bun
+ * happen to put `[executable, scriptPath, ...userArgs]` today, but a different runtime
+ * (or a launcher that prepends flags before the script) can violate that. Locating the
+ * bin by name — an element whose basename (stripped of any extension like `.cjs` /
+ * `.js` / `.mjs`) is `pristine` — is robust across:
+ *
+ *   - global installs (`pristine repl` → argv contains `/usr/local/.../pristine.cjs`)
+ *   - local installs (`./node_modules/.bin/pristine`)
+ *   - `npx pristine`
+ *   - direct `node dist/bin/pristine.cjs`
+ *   - alternative runtimes that may shape argv differently
+ *   - the synthetic argv the REPL handler builds for each typed line
+ *
+ * Stateless after construction; instantiate per parse.
+ */
+export declare class PristineArgv {
+    private static readonly BIN_NAME;
+    /** The argv element identified as the pristine bin (empty when not found). */
+    readonly scriptPath: string;
+    /** Every argv element after the pristine bin, in order. */
+    readonly userArgs: readonly string[];
+    constructor(rawArgv: readonly unknown[]);
+    /**
+     * True when the argv was recognizable as a pristine invocation (the bin token was
+     * located). Mappers short-circuit `supportsMapping` on this.
+     */
+    get isValid(): boolean;
+    private static isPristineBin;
+}

package/dist/types/utils/terminal-key-decoder.d.ts

@@ -0,0 +1,28 @@
+import { TerminalKey } from "../interfaces/terminal-key.interface";
+/**
+ * Translates the raw bytes Node delivers from a raw-mode stdin into structured
+ * {@link TerminalKey}s. Pure and static so it can be unit-tested without a real TTY.
+ *
+ * A single `data` chunk can carry more than one keystroke (notably a paste, or fast
+ * typing), so this returns an array. Control and escape sequences are recognized as one
+ * key each; a run of printable characters is split into one `Character` key per character
+ * so callers (masked input, menus) can echo and handle them uniformly.
+ */
+export declare class TerminalKeyDecoder {
+    /**
+     * Decodes a raw stdin chunk into the keys it represents.
+     *
+     *   - A recognized control byte / escape sequence that spans the whole chunk → one key.
+     *   - An unrecognized escape sequence (starts with ESC) → a single `Other` key, rather
+     *     than splitting it into bogus printable characters.
+     *   - Anything else → one key per character, with non-printable control bytes mapped to
+     *     `Other` so they're ignored rather than echoed.
+     */
+    static decode(data: string): TerminalKey[];
+    /**
+     * Maps a single recognized control byte or escape sequence to its key, or `undefined`
+     * when the input isn't one we handle.
+     * @private
+     */
+    private static decodeControl;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/cli",
-  "version": "2.0.6",
+  "version": "2.0.16",
   "description": "",
   "module": "dist/lib/esm/cli.module.js",
   "main": "dist/lib/cjs/cli.module.js",
@@ -20,20 +20,24 @@
   ],
   "author": "",
   "license": "ISC",
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.2.0",
-    "@pristine-ts/common": "^2.0.6",
-    "@pristine-ts/core": "^2.0.6",
-    "@pristine-ts/data-mapping": "^2.0.6",
-    "@pristine-ts/data-mapping-common": "^2.0.6",
-    "@pristine-ts/file": "^2.0.6",
-    "@pristine-ts/logging": "^2.0.6",
-    "@pristine-ts/validation": "^2.0.6",
-    "jiti": "^2.4.0",
-    "uuid": "^9.0.1"
+    "@pristine-ts/common": "^2.0.16",
+    "@pristine-ts/configuration": "^2.0.16",
+    "@pristine-ts/core": "^2.0.16",
+    "@pristine-ts/data-mapping": "^2.0.16",
+    "@pristine-ts/data-mapping-common": "^2.0.16",
+    "@pristine-ts/file": "^2.0.16",
+    "@pristine-ts/logging": "^2.0.16",
+    "@pristine-ts/metadata": "^1.0.16",
+    "@pristine-ts/observability": "^2.0.16",
+    "@pristine-ts/telemetry": "^2.0.16",
+    "@pristine-ts/validation": "^2.0.16"
   },
   "devDependencies": {
     "esbuild": "^0.24.0"
@@ -72,7 +76,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "539029d624372f9bb1e22e09da7152eabb95c105",
+  "gitHead": "a55d7d59862672a8cbbca4088fed090779b37705",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",