@pristine-ts/cli 2.0.7 → 2.0.17

package/dist/lib/esm/types/start-repl-event-response.type.js

@@ -0,0 +1,9 @@
+import { EventResponse } from "@pristine-ts/core";
+/**
+ * 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 class StartReplEventResponse extends EventResponse {
+}
+//# sourceMappingURL=start-repl-event-response.type.js.map

package/dist/lib/esm/types/start-repl-event-response.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-repl-event-response.type.js","sourceRoot":"","sources":["../../../../src/types/start-repl-event-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,mBAAmB,CAAC;AAIhD;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,aAAuD;CAClG"}

package/dist/lib/esm/types/types.js

@@ -1,3 +1,4 @@
 export * from "./command-event.type";
 export * from "./command-event-response.type";
+export * from "./start-repl-event-response.type";
 //# sourceMappingURL=types.js.map

package/dist/lib/esm/types/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/types/types.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/types/types.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC"}

package/dist/lib/esm/utils/boolean-answer-parser.js

@@ -0,0 +1,21 @@
+/**
+ * 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 class BooleanAnswerParser {
+    static parse(raw) {
+        const normalized = raw.trim().toLowerCase();
+        if (normalized === "y" || normalized === "yes" || normalized === "true" || normalized === "1") {
+            return true;
+        }
+        if (normalized === "n" || normalized === "no" || normalized === "false" || normalized === "0") {
+            return false;
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=boolean-answer-parser.js.map

package/dist/lib/esm/utils/boolean-answer-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boolean-answer-parser.js","sourceRoot":"","sources":["../../../../src/utils/boolean-answer-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAmB;IAC9B,MAAM,CAAC,KAAK,CAAC,GAAW;QACtB,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC5C,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YAC9F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;YAC9F,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/lib/esm/utils/pristine-argv.js

@@ -0,0 +1,50 @@
+import * as path from "path";
+/**
+ * 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 class PristineArgv {
+    constructor(rawArgv) {
+        const binIndex = rawArgv.findIndex(arg => PristineArgv.isPristineBin(arg));
+        if (binIndex === -1) {
+            this.scriptPath = "";
+            this.userArgs = [];
+            return;
+        }
+        const scriptPath = rawArgv[binIndex];
+        this.scriptPath = typeof scriptPath === "string" ? scriptPath : "";
+        this.userArgs = rawArgv
+            .slice(binIndex + 1)
+            .filter((arg) => typeof arg === "string");
+    }
+    /**
+     * True when the argv was recognizable as a pristine invocation (the bin token was
+     * located). Mappers short-circuit `supportsMapping` on this.
+     */
+    get isValid() {
+        return this.scriptPath !== "";
+    }
+    static isPristineBin(arg) {
+        if (typeof arg !== "string") {
+            return false;
+        }
+        return path.basename(arg, path.extname(arg)) === PristineArgv.BIN_NAME;
+    }
+}
+PristineArgv.BIN_NAME = "pristine";
+//# sourceMappingURL=pristine-argv.js.map

package/dist/lib/esm/utils/pristine-argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-argv.js","sourceRoot":"","sources":["../../../../src/utils/pristine-argv.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,YAAY;IASvB,YAAY,OAA2B;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3E,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QACD,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,IAAI,CAAC,QAAQ,GAAG,OAAO;aACpB,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;aACnB,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC;IAC7D,CAAC;IAED;;;OAGG;IACH,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC;IAChC,CAAC;IAEO,MAAM,CAAC,aAAa,CAAC,GAAY;QACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,YAAY,CAAC,QAAQ,CAAC;IACzE,CAAC;;AAnCuB,qBAAQ,GAAG,UAAU,CAAC"}

package/dist/lib/esm/utils/terminal-key-decoder.js

@@ -0,0 +1,67 @@
+import { TerminalKeyName } from "../enums/terminal-key-name.enum";
+/**
+ * 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 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) {
+        const whole = TerminalKeyDecoder.decodeControl(data);
+        if (whole !== undefined) {
+            return [whole];
+        }
+        if (data.charCodeAt(0) === 0x1b) {
+            return [{ name: TerminalKeyName.Other, sequence: data }];
+        }
+        const keys = [];
+        for (const character of data) {
+            const control = TerminalKeyDecoder.decodeControl(character);
+            if (control !== undefined) {
+                keys.push(control);
+            }
+            else if (character.charCodeAt(0) < 0x20) {
+                keys.push({ name: TerminalKeyName.Other, sequence: character });
+            }
+            else {
+                keys.push({ name: TerminalKeyName.Character, sequence: character });
+            }
+        }
+        return keys;
+    }
+    /**
+     * Maps a single recognized control byte or escape sequence to its key, or `undefined`
+     * when the input isn't one we handle.
+     * @private
+     */
+    static decodeControl(sequence) {
+        switch (sequence) {
+            case "\x1b[A":
+                return { name: TerminalKeyName.Up, sequence };
+            case "\x1b[B":
+                return { name: TerminalKeyName.Down, sequence };
+            case "\r":
+            case "\n":
+                return { name: TerminalKeyName.Enter, sequence };
+            case "\x7f":
+            case "\b":
+                return { name: TerminalKeyName.Backspace, sequence };
+            case "\x03":
+                return { name: TerminalKeyName.CtrlC, sequence };
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=terminal-key-decoder.js.map

package/dist/lib/esm/utils/terminal-key-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-key-decoder.js","sourceRoot":"","sources":["../../../../src/utils/terminal-key-decoder.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAEhE;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IAC7B;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,CAAC,IAAY;QACxB,MAAM,KAAK,GAAG,kBAAkB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAChC,OAAO,CAAC,EAAC,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAC,CAAC,CAAC;QACzD,CAAC;QAED,MAAM,IAAI,GAAkB,EAAE,CAAC;QAC/B,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,kBAAkB,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;YAC5D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,CAAC;iBAAM,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC;gBAC1C,IAAI,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAC,CAAC,CAAC;YAChE,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAC,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,aAAa,CAAC,QAAgB;QAC3C,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,QAAQ;gBACX,OAAO,EAAC,IAAI,EAAE,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAC,CAAC;YAC9C,KAAK,QAAQ;gBACX,OAAO,EAAC,IAAI,EAAE,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAC,CAAC;YAChD,KAAK,IAAI,CAAC;YACV,KAAK,IAAI;gBACP,OAAO,EAAC,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAC,CAAC;YACjD,KAAK,MAAM,CAAC;YACZ,KAAK,IAAI;gBACP,OAAO,EAAC,IAAI,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAC,CAAC;YACrD,KAAK,MAAM;gBACT,OAAO,EAAC,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAC,CAAC;QACnD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/types/bootstrap/build-staleness-prompt.d.ts

@@ -1,5 +1,5 @@
 import { BuildManifestStalenessEnum } from "./build-manifest-staleness.enum";
-import { DynamicImporter } from "./dynamic-importer";
+import { CliPrompt } from "../managers/cli-prompt.manager";
 /**
  * When the build manifest is stale (source edited, output missing, etc.), `AppModuleLoader`
  * stops the load and consults this prompt. In a TTY, asks the user whether to run
@@ -10,9 +10,9 @@ import { DynamicImporter } from "./dynamic-importer";
  * this class stays small and testable.
  */
 export declare class BuildStalenessPrompt {
-    private readonly dynamicImporter;
+    private readonly cliPrompt;
     private readonly promptMessage;
-    constructor(dynamicImporter: DynamicImporter);
+    constructor(cliPrompt: CliPrompt);
     isInteractive(): boolean;
     /**
      * Renders a one-line explanation of why the manifest is stale. Used by both the prompt

package/dist/types/bootstrap/init-prompt.d.ts

@@ -1,4 +1,4 @@
-import { DynamicImporter } from "./dynamic-importer";
+import { CliPrompt } from "../managers/cli-prompt.manager";
 /**
  * Answers the init flow needs to gather. Each field corresponds to one config value that
  * `pristine.config.ts` will end up with. The init command resolves these from CLI flags
@@ -13,8 +13,8 @@ export interface InitAnswers {
     writePackageScripts: boolean;
 }
 /**
- * Interactive Q&A for `pristine init`. Lazy-loads `@inquirer/prompts` so the dep cost is
- * only paid when actually prompting (the same pattern as `BuildStalenessPrompt` uses).
+ * Interactive Q&A for `pristine init`. Prompts through {@link CliPrompt}, the CLI's native
+ * (no third-party dependency) terminal-prompt manager.
  *
  * Each method takes a "current value" so callers can pre-fill answers from CLI flags and
  * only prompt for the gaps. Returning the same value the user passed in is intentional —
@@ -22,12 +22,12 @@ export interface InitAnswers {
  * prompt.
  */
 export declare class InitPrompt {
-    private readonly dynamicImporter;
+    private readonly cliPrompt;
     private readonly defaultSourcePath;
     private readonly defaultOutputPath;
     private readonly defaultTsconfig;
     private readonly defaultFormat;
-    constructor(dynamicImporter: DynamicImporter);
+    constructor(cliPrompt: CliPrompt);
     isInteractive(): boolean;
     askSourcePath(current: string | undefined): Promise<string>;
     askOutputPath(current: string | undefined): Promise<string>;

package/dist/types/cli.configuration-keys.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed configuration keys for `@pristine-ts/cli`. Use these constants with `@injectConfig`
+ * for autocomplete + rename safety, instead of typing the parameter name as a string.
+ *
+ * ```ts
+ * import {injectConfig} from "@pristine-ts/common";
+ * import {CliConfigurationKeys} from "@pristine-ts/cli";
+ *
+ * constructor(@injectConfig(CliConfigurationKeys.InteractiveParameters) enabled: boolean) {}
+ * ```
+ */
+export declare const CliConfigurationKeys: {
+    /**
+     * Whether the CLI may interactively ask for missing command parameters that declare a
+     * `question` (via `@commandParameter`). Defaults to `true`; set it to `false` to disable
+     * all such prompting (e.g. in CI). Prompting is also skipped automatically whenever the
+     * input is not an interactive terminal, regardless of this value.
+     */
+    readonly InteractiveParameters: "pristine.cli.interactiveParameters";
+};
+/**
+ * The expected runtime types for each configuration value defined by `@pristine-ts/cli`. The
+ * `@pristine-ts/eslint-plugin` rule `inject-config-type-match` reads the merged map to
+ * enforce parameter types on `@injectConfig` calls.
+ */
+export interface CliConfigurationValueMap {
+    "pristine.cli.interactiveParameters": boolean;
+}
+declare module "@pristine-ts/common" {
+    interface PristineConfigurationValueMap extends CliConfigurationValueMap {
+    }
+}

package/dist/types/cli.d.ts

@@ -47,11 +47,15 @@ export declare class Cli {
      */
     private readEnvironmentFromConfigFile;
     /**
-     * Builds a synthetic outer AppModule that imports both the user's AppModule and CliModule.
+     * Builds a synthetic outer AppModule that imports the user's AppModule plus `CliModule`
+     * — so the CLI's own commands are always registered when the bin is the entry point.
+     * `CliModule` itself imports `ObservabilityModule`, so the logs/traces store travels
+     * along without being named here.
+     *
      * The wrap is unconditional — the kernel dedupes module imports by keyname, so adding
-     * CliModule on top of a graph that already contains it is a no-op rather than an error
-     * or duplicate registration. Cheaper than walking the user's import tree to detect the
-     * already-present case.
+     * `CliModule` on top of a graph that already contains it is a no-op rather than an
+     * error or duplicate registration. Cheaper than walking the user's import tree to
+     * detect the already-present case.
      */
     private wrapWithCliModule;
     /**

package/dist/types/cli.module.d.ts

@@ -1,7 +1,10 @@
 import { ModuleInterface } from "@pristine-ts/common";
 export * from "./bootstrap/bootstrap";
+export * from "./cli.configuration-keys";
 export * from "./commands/commands";
 export * from "./config/config";
+export * from "./decorators/decorators";
+export * from "./enums/enums";
 export * from "./errors/errors";
 export * from "./event-handlers/event-handlers";
 export * from "./event-payloads/event-payloads";
@@ -10,6 +13,7 @@ export * from "./managers/managers";
 export * from "./mappers/mappers";
 export * from "./options/options";
 export * from "./reporters/cli-error.reporter";
+export * from "./services/services";
 export * from "./types/types";
 export { Cli } from "./cli";
 export declare const CliModule: ModuleInterface;

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

@@ -10,8 +10,14 @@ export * from "./init.command";
 export * from "./init.command-options";
 export * from "./list-alias.command";
 export * from "./list.command";
+export * from "./logs-alias.command";
+export * from "./logs.command";
+export * from "./requests-alias.command";
+export * from "./requests.command";
 export * from "./start-alias.command";
 export * from "./start.command";
 export * from "./start.command-options";
+export * from "./trace-alias.command";
+export * from "./trace.command";
 export * from "./verify-alias.command";
 export * from "./verify.command";

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

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

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/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/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"
+}