@pristine-ts/cli 2.0.6 → 2.0.16

package/dist/types/commands/logs.command-options.d.ts

@@ -0,0 +1,38 @@
+import "reflect-metadata";
+/**
+ * Flags + positional for `pristine logs [<id>] [--event-id <x>] [--trace-id <x>] [--request-id <x>] [--follow|-f]`.
+ *
+ * Filter the log stream by any of three correlation ids — `--event-id` is canonical,
+ * `--trace-id` covers the distributed-tracing case (a propagated `traceparent`),
+ * `--request-id` covers HTTP requests with an `x-pristine-request-id` header. A
+ * positional id (e.g. `pristine logs abc-123`) is tried against all three.
+ *
+ * `--follow` and `-f` are accepted as independent boolean keys (that's how
+ * `CommandEventMapper` records short-vs-long flags); the `isFollowing` getter combines
+ * them so the command body reads a single field.
+ */
+export declare class LogsCommandOptions {
+    /** `--event-id <id>`: filter by the canonical event id. */
+    "event-id"?: string;
+    /** `--trace-id <id>`: filter by the trace id (distributed-tracing scenarios). */
+    "trace-id"?: string;
+    /** `--request-id <id>`: filter by the request id (HTTP `x-pristine-request-id`). */
+    "request-id"?: string;
+    /** `--follow`: tail the log stream and render new entries as they arrive. */
+    follow?: boolean;
+    /** `-f`: short alias for `--follow`. */
+    f?: boolean;
+    /**
+     * Bare positional tokens. A positional id is tried against all three correlation
+     * fields by `LogStore.read(id)` / `LogStore.tail(id, ...)`. Decorators are required
+     * for `AutoDataMappingBuilder` to round-trip the field.
+     */
+    _?: string[];
+    /**
+     * Resolves the filter id: an explicit flag wins over the positional, and explicit
+     * flags are preferred in `eventId > traceId > requestId` order on the (rare) chance
+     * the user passed several.
+     */
+    get filterId(): string | undefined;
+    get isFollowing(): boolean;
+}

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

@@ -0,0 +1,31 @@
+import { ExitCode } from "@pristine-ts/common";
+import { LogStore } from "@pristine-ts/observability";
+import { CommandInterface } from "../interfaces/command.interface";
+import { CliOutput } from "../managers/cli-output.manager";
+import { LogsCommandOptions } from "./logs.command-options";
+/**
+ * Renders captured logs: `pristine logs` for everything (newest first across all
+ * processes), `pristine logs <id>` to filter by any of event/trace/request id, or
+ * the explicit `--event-id` / `--trace-id` / `--request-id` flags. With `--follow`/`-f`
+ * it tails the live writers (Ctrl-C to stop). A pure report command: output goes
+ * through `CliOutput`.
+ */
+export declare class LogsCommand implements CommandInterface<LogsCommandOptions> {
+    private readonly cliOutput;
+    private readonly logStore;
+    optionsType: typeof LogsCommandOptions;
+    name: string;
+    description: string;
+    constructor(cliOutput: CliOutput, logStore: LogStore);
+    run(args: LogsCommandOptions): Promise<ExitCode | number>;
+    /**
+     * Tails live writes, rendering each newly-appended line until SIGINT.
+     */
+    private followLogs;
+    /**
+     * Renders one stored log entry through `PrettyLogFormatter`. The store keeps `date`
+     * as an ISO string and `severity` as a numeric `SeverityEnum`; rehydrate the date so
+     * the formatter (date-fns) can format it.
+     */
+    private render;
+}

package/dist/types/commands/requests-alias.command.d.ts

@@ -0,0 +1,14 @@
+import { ExitCode } from "@pristine-ts/common";
+import { CommandInterface } from "../interfaces/command.interface";
+import { RequestsCommand } from "./requests.command";
+/**
+ * Top-level alias for `p:requests`.
+ */
+export declare class RequestsAliasCommand implements CommandInterface<null> {
+    private readonly delegate;
+    optionsType: null;
+    name: string;
+    description: string;
+    constructor(delegate: RequestsCommand);
+    run(args: any): Promise<ExitCode | number>;
+}

package/dist/types/commands/requests.command-options.d.ts

@@ -0,0 +1,8 @@
+import "reflect-metadata";
+/**
+ * Flags for `pristine requests [--limit <n>]`.
+ */
+export declare class RequestsCommandOptions {
+    /** `--limit <n>`: cap the number of summaries returned. Default `20`. */
+    limit?: number;
+}

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

@@ -0,0 +1,25 @@
+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 { RequestsCommandOptions } from "./requests.command-options";
+/**
+ * Lists recent requests captured in the observability store — the entry point for
+ * "what just happened, and what's the event id I want to inspect?".
+ *
+ * Pulls summaries from every captured process newest-first. A pure report command: all
+ * output goes through `CliOutput` so it pipes cleanly.
+ *
+ * Flags: `--limit <n>` (default 20).
+ */
+export declare class RequestsCommand implements CommandInterface<RequestsCommandOptions> {
+    private readonly cliOutput;
+    private readonly traceStore;
+    optionsType: typeof RequestsCommandOptions;
+    name: string;
+    description: string;
+    private static readonly DEFAULT_LIMIT;
+    constructor(cliOutput: CliOutput, traceStore: TraceStore);
+    run(args: RequestsCommandOptions): Promise<ExitCode | number>;
+    private renderTable;
+}

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

@@ -1,7 +1,7 @@
 import { ExitCode } from "@pristine-ts/common";
 import { Kernel, RuntimeServerInterface } from "@pristine-ts/core";
+import { LogHandlerInterface } from "@pristine-ts/logging";
 import { CommandInterface } from "../interfaces/command.interface";
-import { ConsoleManager } from "../managers/console.manager";
 import { StartCommandOptions } from "./start.command-options";
 /**
  * Boots the AppModule, starts every registered `RuntimeServerInterface` (HTTP server, gRPC
@@ -34,7 +34,7 @@ import { StartCommandOptions } from "./start.command-options";
  *     `nodemon` or `tsx --watch`.
  */
 export declare class StartCommand implements CommandInterface<StartCommandOptions> {
-    private readonly consoleManager;
+    private readonly logHandler;
     private readonly kernel;
     private readonly servers;
     optionsType: typeof StartCommandOptions;
@@ -42,6 +42,6 @@ export declare class StartCommand implements CommandInterface<StartCommandOption
     description: string;
     private static readonly HARD_EXIT_TIMEOUT_MS;
     private readonly defaultRuntimeServerName;
-    constructor(consoleManager: ConsoleManager, kernel: Kernel, servers: RuntimeServerInterface[]);
+    constructor(logHandler: LogHandlerInterface, kernel: Kernel, servers: RuntimeServerInterface[]);
     run(args: StartCommandOptions): Promise<ExitCode | number>;
 }

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

@@ -0,0 +1,14 @@
+import { ExitCode } from "@pristine-ts/common";
+import { CommandInterface } from "../interfaces/command.interface";
+import { TraceCommand } from "./trace.command";
+/**
+ * Top-level alias for `p:trace`.
+ */
+export declare class TraceAliasCommand implements CommandInterface<null> {
+    private readonly delegate;
+    optionsType: null;
+    name: string;
+    description: string;
+    constructor(delegate: TraceCommand);
+    run(args: any): Promise<ExitCode | number>;
+}

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

@@ -0,0 +1,31 @@
+import "reflect-metadata";
+export type TraceFormat = "tree" | "flat" | "json";
+/**
+ * Flags + positional for `pristine trace [<id>] [--event-id <x>] [--trace-id <x>] [--request-id <x>] [--format tree|flat|json]`.
+ *
+ * Look up a trace by any of three correlation ids — `--event-id` is canonical,
+ * `--trace-id` covers the distributed-tracing case (a propagated `traceparent`),
+ * `--request-id` covers HTTP requests with an `x-pristine-request-id` header. A
+ * positional id is tried against all three.
+ */
+export declare class TraceCommandOptions {
+    /** `--event-id <id>`: look up by the canonical event id. */
+    "event-id"?: string;
+    /** `--trace-id <id>`: look up by the trace id (distributed-tracing scenarios). */
+    "trace-id"?: string;
+    /** `--request-id <id>`: look up by the request id (HTTP `x-pristine-request-id`). */
+    "request-id"?: string;
+    /** `--format tree|flat|json`: how to render the trace. Defaults to `tree`. */
+    format?: TraceFormat;
+    /**
+     * Bare positional tokens. A positional id is tried against all three correlation
+     * fields by `TraceStore.find(id)`. Decorators are required for `AutoDataMappingBuilder`
+     * to round-trip the field.
+     */
+    _?: string[];
+    /**
+     * Resolves the lookup id: an explicit flag wins over the positional, and explicit
+     * flags are preferred in `eventId > traceId > requestId` order.
+     */
+    get lookupId(): string | undefined;
+}

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,26 +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 { ConsoleManager } from "../managers/console.manager";
+import { CommandArgumentResolver } from "../services/command-argument-resolver";
 export declare class CliEventHandler implements EventHandlerInterface<any, any> {
     private readonly logHandler;
-    private readonly validator;
-    private readonly consoleManager;
+    private readonly commandArgumentResolver;
     private readonly commands;
-    constructor(logHandler: LogHandlerInterface, validator: Validator, consoleManager: ConsoleManager, 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-output.manager.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pipe-friendly stdout primitives for the CLI. Use this when you need to emit text that
+ * a user might redirect or pipe — help banners, command tables, JSON dumps — and the
+ * `LogHandler` pipeline would be wrong because it can be severity-gated, routed to
+ * stderr per-severity, or fanned out to file/Sentry transports. For event narration
+ * ("Compiling X", "Server started"), use `LogHandler` instead.
+ */
+export declare class CliOutput {
+    /**
+     * Writes a message to stdout without a newline.
+     */
+    write(message: string): void;
+    /**
+     * Writes a message to stdout with a newline.
+     */
+    writeLine(message: string): void;
+    /**
+     * Renders an array of objects as a table using Node's `console.table`.
+     */
+    writeTable(rows: any[]): void;
+}

package/dist/types/managers/cli-progress-bar.manager.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Inline progress bar rendered on the current TTY line. Each call clears and redraws
+ * the line, so callers must not interleave other output (LogHandler narration, raw
+ * CliOutput writes, etc.) between updates or the previous bar will be left behind on
+ * the line above.
+ */
+export declare class CliProgressBar {
+    private static readonly FILLED;
+    private static readonly EMPTY;
+    private static readonly CYAN;
+    private static readonly RESET;
+    /**
+     * Renders the progress bar at the current line. When `current >= total` the cursor
+     * is advanced to the next line so subsequent output doesn't overwrite the finished bar.
+     */
+    update(current: number, total: number, message?: string, width?: number): void;
+}