@pristine-ts/cli 2.0.7 → 2.0.16

package/dist/types/commands/trace.command.d.ts

@@ -0,0 +1,21 @@
+import { ExitCode } from "@pristine-ts/common";
+import { TraceStore } from "@pristine-ts/observability";
+import { CommandInterface } from "../interfaces/command.interface";
+import { CliOutput } from "../managers/cli-output.manager";
+import { TraceCommandOptions } from "./trace.command-options";
+/**
+ * Renders the span tree of one captured trace. Look it up by any of event/trace/request
+ * id — `pristine trace <id>` tries all three, or use the explicit `--event-id`,
+ * `--trace-id`, `--request-id` flags.
+ *
+ * `--format tree|flat|json` controls the rendering (defaults to `tree`).
+ */
+export declare class TraceCommand implements CommandInterface<TraceCommandOptions> {
+    private readonly cliOutput;
+    private readonly traceStore;
+    optionsType: typeof TraceCommandOptions;
+    name: string;
+    description: string;
+    constructor(cliOutput: CliOutput, traceStore: TraceStore);
+    run(args: TraceCommandOptions): Promise<ExitCode | number>;
+}

package/dist/types/config/config-loader.d.ts

@@ -3,7 +3,8 @@ import { DynamicImporter } from "../bootstrap/dynamic-importer";
 /**
  * Loads `pristine.config.ts` (preferred) or `pristine.config.js` (escape hatch for
  * pure-JS projects). Walks up from `process.cwd()` looking for the file, then loads it
- * through `jiti` (for `.ts`) or Node's dynamic `import()` (for `.js`).
+ * through Node's native dynamic `import()`: TypeScript type-stripping (Node >= 22.18)
+ * handles `.ts`, while `.js` loads directly.
  *
  * Returns a `ResolvedPristineConfig` carrying the file path (when found) and per-field
  * provenance, which `pristine p:config:print` uses to render an annotated dump.
@@ -31,10 +32,21 @@ export declare class ConfigLoader {
      */
     private findConfigFile;
     /**
-     * Loads a config file from `absolutePath`. `.ts` goes through `jiti`; `.js` uses Node's
-     * native dynamic `import()`. Extracts the default export, falling back to a named
+     * Loads a config file from `absolutePath` via Node's native dynamic `import()`. A `.ts`
+     * config is handled by Node's built-in TypeScript type-stripping (Node >= 22.18); a `.js`
+     * config loads directly. Extracts the default export, falling back to a named
      * `pristineConfig` export for users who prefer not to use `export default`.
      * @private
      */
     private importConfigFile;
+    /**
+     * Translates Node's low-level module-loading failures for a `.ts` config into an
+     * actionable error. Native type-stripping has two distinct failure modes worth telling
+     * apart: the running Node is too old (or has stripping disabled) to import `.ts` at all
+     * (`ERR_UNKNOWN_FILE_EXTENSION`), versus a config written with non-erasable TypeScript that
+     * stripping refuses (`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`). Any other error is passed through
+     * unchanged so genuine config bugs surface as-is.
+     * @private
+     */
+    private describeImportError;
 }

package/dist/types/decorators/command-parameter.decorator.d.ts

@@ -0,0 +1,30 @@
+import { CommandParameterOptions } from "../options/command-parameter.options";
+/**
+ * Describes a command-line parameter on a command's options class. Stored as property
+ * metadata and read by the CLI while resolving a command's arguments — before the arguments
+ * are mapped onto the options instance and validated.
+ *
+ * Two behaviors flow from the options:
+ *
+ *   - `flag` rebinds the property to a differently-named flag (the property name is the
+ *     default), so the property and the flag no longer have to be spelled identically.
+ *   - `question` makes the CLI ask for the value interactively when the flag is absent
+ *     (subject to configuration and an interactive terminal). Omit it to never prompt.
+ *
+ * ```ts
+ * import {IsString, IsOptional} from "@pristine-ts/class-validator";
+ * import {commandParameter} from "@pristine-ts/cli";
+ *
+ * export class MigrateCommandOptions {
+ *   @commandParameter({flag: "db-url", question: "What is the database URL?"})
+ *   @IsString()
+ *   databaseUrl?: string;            // bound to --db-url; asked for when missing
+ *
+ *   @commandParameter({flag: "dir"}) // bound to --dir; never asked for
+ *   @IsOptional()
+ *   @IsString()
+ *   migrationsDirectory?: string;
+ * }
+ * ```
+ */
+export declare const commandParameter: (options?: CommandParameterOptions) => (target: any, propertyKey: string) => void;

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

@@ -0,0 +1 @@
+export * from "./command-parameter.decorator";

package/dist/types/enums/cli-decorator-metadata-keyname.enum.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Metadata keynames written by `@pristine-ts/cli`'s own property/class decorators and read
+ * back when resolving a command's options. Namespaced under `cli:` so they never collide
+ * with the keys other Pristine decorators (validation, data-mapping, mysql, …) store on the
+ * same class.
+ */
+export declare enum CliDecoratorMetadataKeynameEnum {
+    CommandParameter = "cli:command-parameter"
+}

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

@@ -0,0 +1,2 @@
+export * from "./cli-decorator-metadata-keyname.enum";
+export * from "./terminal-key-name.enum";

package/dist/types/enums/exit-code.enum.d.ts

@@ -0,0 +1,4 @@
+export declare enum ExitCodeEnum {
+    Success = 0,
+    Error = 1
+}

package/dist/types/enums/terminal-key-name.enum.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The kinds of keypress the CLI's interactive prompts understand. `TerminalKeyDecoder`
+ * maps the raw bytes Node delivers from a raw-mode stdin onto one of these; every printable
+ * keystroke collapses to `Character` (with the literal character carried separately on
+ * {@link TerminalKey}). `Other` covers control/escape sequences the prompts don't act on
+ * (function keys, unhandled arrows) so callers can ignore them instead of echoing garbage.
+ */
+export declare enum TerminalKeyName {
+    Up = "up",
+    Down = "down",
+    Enter = "enter",
+    Backspace = "backspace",
+    CtrlC = "ctrl-c",
+    Character = "character",
+    Other = "other"
+}

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/console.manager.d.ts

@@ -0,0 +1,93 @@
+import { ConsoleReadlineOptions } from "../options/console-readline.options";
+export declare class ConsoleManager {
+    private spinnerInterval;
+    private isSpinning;
+    /**
+     * Writes a message to stdout without a newline.
+     * @param message The message to write.
+     */
+    write(message: string): void;
+    /**
+     * Writes a message to stdout with a newline.
+     * @param message The message to write.
+     */
+    writeLine(message: string): void;
+    /**
+     * Writes a table to stdout.
+     * @param table The array of objects to display as a table.
+     */
+    writeTable(table: any[]): void;
+    /**
+     * Writes an error message in red with an 'Error:' prefix.
+     * @param message The error message to display.
+     */
+    writeError(message: string): void;
+    /**
+     * Writes a success message in green with a 'Success:' prefix.
+     * @param message The success message to display.
+     */
+    writeSuccess(message: string): void;
+    /**
+     * Writes a warning message in yellow with a 'Warning:' prefix.
+     * @param message The warning message to display.
+     */
+    writeWarning(message: string): void;
+    /**
+     * Writes an info message in cyan with an 'Info:' prefix.
+     * @param message The info message to display.
+     */
+    writeInfo(message: string): void;
+    /**
+     * Starts a loading spinner with a message.
+     *
+     * @param message The message to display next to the spinner.
+     * @remarks
+     * This method hides the cursor and continuously updates the current line.
+     * Avoid calling other write methods while the spinner is active as they may conflict with the spinner's line clearing.
+     */
+    startSpinner(message: string): void;
+    /**
+     * Stops the loading spinner and optionally prints a completion message.
+     *
+     * @param message Optional completion message to display.
+     * @param success Whether the operation was successful. Defaults to true.
+     * @remarks
+     * Stops the spinner, shows the cursor, and prints a final success or error message on the same line.
+     */
+    stopSpinner(message?: string, success?: boolean): void;
+    /**
+     * Displays or updates a progress bar.
+     *
+     * @param current The current progress value.
+     * @param total The total value to reach (100%).
+     * @param message Optional message to display next to the bar.
+     * @param width The visual width of the progress bar in characters. Defaults to 30.
+     *
+     * @remarks
+     * This method clears the *current* line and writes the progress bar.
+     *
+     * **Important:** If you call `writeLine()` (or any other method that outputs a newline) between calls to `updateProgressBar()`,
+     * the next call to `updateProgressBar()` will start on the *new* line, leaving the previous progress bar state on the line above.
+     *
+     * **Example of creating artifacts:**
+     * ```typescript
+     * manager.updateProgressBar(10, 100); // Draws bar at line N
+     * manager.writeLine("Log message");   // Moves cursor to line N+1
+     * manager.updateProgressBar(20, 100); // Draws bar at line N+1 (Line N has the old bar)
+     * ```
+     */
+    updateProgressBar(current: number, total: number, message?: string, width?: number): void;
+    /**
+     * Reads a string from stdin.
+     * @returns The raw string read from stdin.
+     */
+    read(): string;
+    /**
+     * Reads a line from stdin with a prompt.
+     *
+     * @param question The prompt text to display.
+     * @param options Configuration options for the input (e.g., masking characters).
+     * @returns A promise resolving to the user's input string.
+     */
+    readLine(question: string, options?: ConsoleReadlineOptions): Promise<string>;
+}

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/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/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";