@pristine-ts/cli 1.0.440 → 2.0.2

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

@@ -0,0 +1,60 @@
+import { CommandInterface } from "../interfaces/command.interface";
+import { ConsoleManager } from "../managers/console.manager";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+import { InitCommandOptions } from "./init.command-options";
+import { InitPrompt } from "../bootstrap/init-prompt";
+/**
+ * Scaffolds a new Pristine project setup. In a TTY, prompts the user for source path,
+ * output path, tsconfig, build format, and a couple of yes/no decisions; in non-TTY (CI),
+ * accepts every value via `--source-path`, `--output-path`, etc. flags or refuses to run.
+ *
+ * What it produces:
+ *   - `pristine.config.ts` at the project root with the answers populated.
+ *   - Optionally, a starter AppModule at the configured `sourcePath` (only when the file
+ *     doesn't already exist — never overwrites).
+ *   - Optionally, `npm` scripts in `package.json`: `build`, `start`, `verify` (only ones
+ *     that don't already exist — never overwrites).
+ *   - `.pristine/` added to `.gitignore` if a `.gitignore` exists at the project root.
+ *
+ * Refuses to overwrite an existing `pristine.config.ts` so re-running init is safe.
+ */
+export declare class InitCommand implements CommandInterface<InitCommandOptions> {
+    private readonly consoleManager;
+    private readonly initPrompt;
+    optionsType: typeof InitCommandOptions;
+    name: string;
+    description: string;
+    private readonly configFileName;
+    private readonly gitignoreEntry;
+    constructor(consoleManager: ConsoleManager, initPrompt: InitPrompt);
+    run(args: InitCommandOptions): Promise<ExitCodeEnum | number>;
+    /**
+     * Fills in answers from CLI flags first, then prompts (in TTY) for whatever's missing.
+     * Returns undefined when running non-TTY with insufficient flags so the caller can exit
+     * with the right error code (already rendered).
+     * @private
+     */
+    private gatherAnswers;
+    /**
+     * Writes a starter AppModule at the configured source path if and only if the file
+     * doesn't already exist. Never overwrites — re-running init on an established project
+     * shouldn't risk clobbering real code.
+     * @private
+     */
+    private scaffoldSource;
+    /**
+     * Adds `build`, `start`, `verify` to package.json's scripts. Only adds scripts that
+     * don't already exist — never overwrites a user-defined script.
+     * @private
+     */
+    private addPackageScripts;
+    /**
+     * Adds `.pristine/` to `.gitignore` if `.gitignore` exists and the entry isn't already
+     * there. Doesn't create `.gitignore` from scratch — that would be presumptuous in a
+     * project that hasn't initialized git.
+     * @private
+     */
+    private addToGitignore;
+    private renderConfigTemplate;
+    private renderAppModuleTemplate;
+}

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

@@ -0,0 +1,15 @@
+import { CommandInterface } from "../interfaces/command.interface";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+import { ListCommand } from "./list.command";
+/**
+ * Top-level alias for the framework-reserved `p:list` command. Injects the delegate
+ * directly via standard DI.
+ */
+export declare class ListAliasCommand implements CommandInterface<null> {
+    private readonly delegate;
+    optionsType: null;
+    name: string;
+    description: string;
+    constructor(delegate: ListCommand);
+    run(args: any): Promise<ExitCodeEnum | number>;
+}

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

@@ -2,11 +2,17 @@ import { DependencyContainer } from "tsyringe";
 import { CommandInterface } from "../interfaces/command.interface";
 import { ConsoleManager } from "../managers/console.manager";
 import { ExitCodeEnum } from "../enums/exit-code.enum";
+/**
+ * Lists every registered command's name. Like `HelpCommand`, this resolves the command set
+ * lazily inside `run()` via the injected child container to avoid the self-referential cycle
+ * that constructor-time `@injectAll(Command)` would create — see `HelpCommand` for details.
+ */
 export declare class ListCommand implements CommandInterface<null> {
     private readonly consoleManager;
     private readonly container;
     optionsType: null;
     name: string;
+    description: string;
     constructor(consoleManager: ConsoleManager, container: DependencyContainer);
     run(args: any): Promise<ExitCodeEnum | number>;
 }

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

@@ -0,0 +1,16 @@
+import { CommandInterface } from "../interfaces/command.interface";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+import { StartCommand } from "./start.command";
+import { StartCommandOptions } from "./start.command-options";
+/**
+ * Top-level alias for the framework-reserved `p:start` command. Injects the delegate
+ * directly via standard DI.
+ */
+export declare class StartAliasCommand implements CommandInterface<StartCommandOptions> {
+    private readonly delegate;
+    optionsType: typeof StartCommandOptions;
+    name: string;
+    description: string;
+    constructor(delegate: StartCommand);
+    run(args: StartCommandOptions): Promise<ExitCodeEnum | number>;
+}

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

@@ -0,0 +1,11 @@
+import "reflect-metadata";
+/**
+ * Runtime overrides for `pristine start`. These are applied to every `RuntimeServerInterface`
+ * the kernel resolves — implementations are free to ignore them. The flags exist mainly for
+ * one-off cases ("I just need to test on a different port right now"); the canonical place
+ * to set defaults is the matching module's configurationDefinitions or `pristine.config.ts`.
+ */
+export declare class StartCommandOptions {
+    port?: number;
+    address?: string;
+}

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

@@ -0,0 +1,47 @@
+import { Kernel, RuntimeServerInterface } from "@pristine-ts/core";
+import { CommandInterface } from "../interfaces/command.interface";
+import { ConsoleManager } from "../managers/console.manager";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+import { StartCommandOptions } from "./start.command-options";
+/**
+ * Boots the AppModule, starts every registered `RuntimeServerInterface` (HTTP server, gRPC
+ * server, etc.), and keeps the process alive until SIGTERM or SIGINT. On signal, runs the
+ * registered `onShutdown` hooks via `Kernel.stop()` and exits.
+ *
+ * This is the production-grade entry point. Use `pristine start` (or its `pristine p:start`
+ * canonical name) instead of `node dist/main.js` if you want Pristine to manage the lifecycle,
+ * signal handling, and graceful shutdown — including listening on every server module the
+ * AppModule imports.
+ *
+ * Notes:
+ *   - The kernel is **already started** by `bootstrap()` before this command runs (the CLI
+ *     boots once for every command). This command does not call `kernel.start()` again — it
+ *     just starts the registered servers and keeps the process alive.
+ *   - `RuntimeServer`-tagged services are constructor-injected via `@injectAll`. This works
+ *     because `RuntimeServer` is a different tag than `Command`, so there's no self-reference
+ *     cycle (StartCommand is `@tag(Command)`, not `@tag(RuntimeServer)`). When no servers
+ *     are registered, the array is empty and the start path skips the loop.
+ *   - The `Kernel` is injected only for `kernel.stop()` — the legitimate use of the Kernel
+ *     as a service. Other resolution (commands, runtime servers, etc.) goes through
+ *     standard DI rather than reaching through `kernel.container`.
+ *   - The shutdown timeout (per `onShutdown` hook) defaults to 10 seconds. The whole-process
+ *     hard exit timeout defaults to 30 seconds — if the orderly shutdown doesn't finish in
+ *     that window, the process is force-exited so Kubernetes / ECS don't get stuck waiting.
+ *   - `--port` / `--address` flags are propagated to every RuntimeServer's `start()`. In
+ *     multi-server scenarios where servers should listen on different ports, use the per-module
+ *     configuration values (e.g. `pristine.http.kernel-server.port`) instead of CLI flags.
+ *   - Watch mode (`--watch`) is not yet implemented. For a dev loop, wrap `pristine start` in
+ *     `nodemon` or `tsx --watch`.
+ */
+export declare class StartCommand implements CommandInterface<StartCommandOptions> {
+    private readonly consoleManager;
+    private readonly kernel;
+    private readonly servers;
+    optionsType: typeof StartCommandOptions;
+    name: string;
+    description: string;
+    private static readonly HARD_EXIT_TIMEOUT_MS;
+    private readonly defaultRuntimeServerName;
+    constructor(consoleManager: ConsoleManager, kernel: Kernel, servers: RuntimeServerInterface[]);
+    run(args: StartCommandOptions): Promise<ExitCodeEnum | number>;
+}

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

@@ -0,0 +1,15 @@
+import { CommandInterface } from "../interfaces/command.interface";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+import { VerifyCommand } from "./verify.command";
+/**
+ * Top-level alias for the framework-reserved `p:verify` command. Injects the delegate
+ * directly via standard DI.
+ */
+export declare class VerifyAliasCommand implements CommandInterface<null> {
+    private readonly delegate;
+    optionsType: null;
+    name: string;
+    description: string;
+    constructor(delegate: VerifyCommand);
+    run(args: any): Promise<ExitCodeEnum | number>;
+}

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

@@ -0,0 +1,24 @@
+import { LogHandlerInterface } from "@pristine-ts/logging";
+import { CommandInterface } from "../interfaces/command.interface";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+import { AppModuleLoader } from "../bootstrap/app-module-loader";
+/**
+ * Verifies that the consumer's AppModule can be instantiated against its configuration.
+ * Builds a fresh throw-away kernel, runs every boot phase capturing per-phase outcomes,
+ * executes every embedder-registered `InstantiationTestInterface`, and routes the resulting
+ * report through the project's `LogHandlerInterface`.
+ *
+ * Note: this command runs after the CLI's own `kernel.start()` has succeeded, so it cannot
+ * be used to debug a configuration that is so broken the CLI can't start. For that case,
+ * call `kernel.verifyInstantiation(...)` directly from a small script that imports your
+ * AppModule.
+ */
+export declare class VerifyCommand implements CommandInterface<null> {
+    private readonly logHandler;
+    private readonly appModuleLoader;
+    optionsType: null;
+    name: string;
+    description: string;
+    constructor(logHandler: LogHandlerInterface, appModuleLoader: AppModuleLoader);
+    run(args: any): Promise<ExitCodeEnum | number>;
+}

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

@@ -0,0 +1,40 @@
+import { ResolvedPristineConfig } from "./resolved-pristine-config";
+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`).
+ *
+ * Returns a `ResolvedPristineConfig` carrying the file path (when found) and per-field
+ * provenance, which `pristine p:config:print` uses to render an annotated dump.
+ */
+export declare class ConfigLoader {
+    private readonly dynamicImporter;
+    /**
+     * File names searched for, in order. `.ts` is the canonical form — `defineConfig()`
+     * gives full IDE autocomplete and every Pristine project ships a TS toolchain anyway.
+     * `.js` is the escape hatch for the rare pure-JS project that cannot have a `.ts`
+     * file at the root.
+     */
+    private readonly configFileNames;
+    constructor(dynamicImporter: DynamicImporter);
+    load(options?: {
+        explicitPath?: string;
+        startDir?: string;
+    }): Promise<ResolvedPristineConfig>;
+    /**
+     * Walks up from `startDir` looking for a config file with any of the supported names.
+     * Stops at the first match, returning the absolute path. Stops at the filesystem root
+     * without finding anything → returns undefined. Walking up matters in monorepos: a CLI
+     * invoked in `packages/foo/` should still find a `pristine.config.ts` at the repo root.
+     * @private
+     */
+    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
+     * `pristineConfig` export for users who prefer not to use `export default`.
+     * @private
+     */
+    private importConfigFile;
+}

package/dist/types/config/config-provenance.enum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Where a resolved configuration value originated. Used by `pristine p:config:print` to
+ * annotate output so users can tell whether a value comes from their config file, a
+ * deprecated `package.json` field, or the CLI's built-in defaults.
+ */
+export declare enum ConfigProvenanceEnum {
+    ConfigFile = "config-file",
+    PackageJsonDeprecated = "package-json-deprecated",
+    Default = "default"
+}

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

@@ -0,0 +1,5 @@
+export * from "./config-loader";
+export * from "./config-provenance.enum";
+export * from "./define-config";
+export * from "./pristine-config.interface";
+export * from "./resolved-pristine-config";

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

@@ -0,0 +1,14 @@
+import { PristineConfig } from "./pristine-config.interface";
+/**
+ * Identity helper that gives an authored `pristine.config.ts` full type checking and
+ * autocomplete. Implementation is intentionally trivial — the types do all the work.
+ *
+ * ```ts
+ * import {defineConfig} from "@pristine-ts/cli";
+ *
+ * export default defineConfig({
+ *   appModule: { path: "dist/app.module.js" },
+ * });
+ * ```
+ */
+export declare const defineConfig: (config: PristineConfig) => PristineConfig;

package/dist/types/config/pristine-config.interface.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The shape of `pristine.config.ts` (or `pristine.config.js`). The `appModule` block is
+ * the canonical (and only) way to tell the CLI where your AppModule lives. When that
+ * block is present, both `sourcePath` and `outputPath` must be provided so the build
+ * manifest can keep them in sync.
+ *
+ * Authored as a `.ts` file by default; use `defineConfig()` (re-exported from
+ * `@pristine-ts/cli`) for full IDE autocomplete:
+ *
+ * ```ts
+ * import {defineConfig} from "@pristine-ts/cli";
+ *
+ * export default defineConfig({
+ *   appModule: {
+ *     sourcePath: "src/app.module.ts",
+ *     outputPath: "dist/app.module.js",
+ *   },
+ * });
+ * ```
+ *
+ * Run `pristine init` to generate this file interactively.
+ */
+export interface PristineConfig {
+    /**
+     * Where the AppModule lives. Both `sourcePath` and `outputPath` are required when
+     * `appModule` is set. Paths are resolved relative to the directory containing the
+     * config file.
+     */
+    appModule?: {
+        /** Source TypeScript file the build compiles. */
+        sourcePath: string;
+        /** Compiled JavaScript file the runtime loads. */
+        outputPath: string;
+        /** Name of the export holding the AppModule definition. Default: `AppModule`. */
+        export?: string;
+    };
+    /** Build pipeline configuration. Used by `pristine build`. */
+    build?: {
+        outDir?: string;
+        tsconfig?: string;
+        format?: "esm" | "cjs" | "both";
+        clean?: boolean;
+    };
+    /** Reserved for future `pristine start` features (entry path, watch mode, node args). */
+    start?: {
+        entry?: string;
+        watch?: boolean | {
+            paths: string[];
+            ignore?: string[];
+        };
+        nodeArgs?: string[];
+    };
+    /**
+     * Extra packages whose `*Module` exports should be merged into the runtime AppModule when
+     * the CLI boots. Lets tooling-only modules (e.g. a generator package) contribute commands
+     * without forcing the consumer to import them into their production runtime AppModule.
+     */
+    plugins?: Array<string | {
+        name: string;
+        options?: unknown;
+    }>;
+    /**
+     * Default `kernel.start()` configuration values, merged on top of the CLI's defaults. Lets
+     * you keep CLI-only runtime overrides out of your AppModule.
+     */
+    kernelConfiguration?: Record<string, unknown>;
+}

package/dist/types/config/resolved-pristine-config.d.ts

@@ -0,0 +1,28 @@
+import { ConfigProvenanceEnum } from "./config-provenance.enum";
+import { PristineConfig } from "./pristine-config.interface";
+/**
+ * A loaded `PristineConfig` augmented with discovery metadata. `ConfigLoader` returns this
+ * shape; the raw `PristineConfig` is what users author.
+ */
+export declare class ResolvedPristineConfig {
+    readonly config: PristineConfig;
+    /** Absolute path to the config file that was loaded, if any. */
+    readonly configFilePath: string | undefined;
+    /**
+     * Per-top-level-field provenance markers, mainly for `pristine p:config:print`. Keys are
+     * top-level fields of `PristineConfig` (`appModule`, `build`, `start`, `plugins`,
+     * `kernelConfiguration`); values are the `ConfigProvenanceEnum` describing where each
+     * came from.
+     */
+    readonly provenance: Record<string, ConfigProvenanceEnum>;
+    constructor(config: PristineConfig, 
+    /** Absolute path to the config file that was loaded, if any. */
+    configFilePath: string | undefined, 
+    /**
+     * Per-top-level-field provenance markers, mainly for `pristine p:config:print`. Keys are
+     * top-level fields of `PristineConfig` (`appModule`, `build`, `start`, `plugins`,
+     * `kernelConfiguration`); values are the `ConfigProvenanceEnum` describing where each
+     * came from.
+     */
+    provenance: Record<string, ConfigProvenanceEnum>);
+}

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

@@ -5,14 +5,41 @@ 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 { DataMapper } from "@pristine-ts/data-mapping-common";
+import { ExitCodeEnum } from "../enums/exit-code.enum";
+/**
+ * Resolution of a command's argv input. Either we successfully produced an instance of the
+ * command's `optionsType` (or the raw args for null-optionsType commands) and `args` is set,
+ * OR mapping/validation failed and `exitCode` carries the failure status. Mutually exclusive
+ * by construction — `args` is undefined iff `exitCode` is set.
+ *
+ * Used as the return value of `CliEventHandler.resolveArgs` so the call site can branch on
+ * the success/failure case without a thrown exception in the hot path.
+ */
+interface ResolvedCommandArgs {
+    args?: any;
+    exitCode?: ExitCodeEnum;
+}
 export declare class CliEventHandler implements EventHandlerInterface<any, any> {
     private readonly logHandler;
     private readonly validator;
     private readonly consoleManager;
-    private readonly dataMapper;
     private readonly commands;
-    constructor(logHandler: LogHandlerInterface, validator: Validator, consoleManager: ConsoleManager, dataMapper: DataMapper, commands: CommandInterface<any>[]);
+    constructor(logHandler: LogHandlerInterface, validator: Validator, consoleManager: ConsoleManager, commands: CommandInterface<any>[]);
     handle(event: CommandEvent): Promise<CommandEventResponse>;
+    /**
+     * 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.
+     *
+     * Mapping or validation failures print the underlying error to the console and return an
+     * `exitCode` so the caller can exit non-zero. Success returns the typed instance under
+     * `args`. The two are mutually exclusive — see `ResolvedCommandArgs`.
+     */
+    resolveArgs(command: CommandInterface<any>, rawArgs: any): Promise<ResolvedCommandArgs>;
     supports(event: Event<any>): boolean;
+    private logExitStatus;
 }
+export {};

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

@@ -1,6 +1,34 @@
+import { ClassConstructor } from "class-transformer";
 import { ExitCodeEnum } from "../enums/exit-code.enum";
-export interface CommandInterface<ArgumentsOptionsType> {
+/**
+ * The contract every CLI command implements. The CliEventHandler reads `optionsType` to
+ * map raw `process.argv` flags onto a typed instance of the declared options class, runs
+ * `class-validator` against the instance, and then calls `run(args)` with the validated
+ * instance.
+ *
+ * `optionsType` MUST be a class constructor (the class itself, e.g. `optionsType = MyOptions`)
+ * — not an instance. Set it to `null` for commands that don't accept any options. Returning
+ * an instance from a property declared as a constructor was a long-standing footgun: the
+ * data mapper silently failed and the validator never ran, so `run(args)`'s typed signature
+ * lied. The class-constructor contract makes the mapping/validation pipeline work as designed.
+ *
+ * Type parameter `T` is the options class. Commands without options use `null`.
+ */
+export interface CommandInterface<T> {
     name: string;
-    optionsType: ArgumentsOptionsType;
-    run(args: ArgumentsOptionsType): Promise<ExitCodeEnum | number>;
+    /**
+     * Optional one-line summary shown by `pristine help`. Keep it short — multi-line
+     * descriptions belong in the command's own documentation, not in the help output.
+     */
+    description?: string;
+    /**
+     * Constructor of the class that describes this command's CLI flags, decorated with
+     * `class-validator` rules. Use `null` for commands that take no flags.
+     */
+    optionsType: ClassConstructor<T> | null;
+    /**
+     * Invoked with a validated instance of `optionsType` (when `optionsType` is non-null) or
+     * the raw parsed argv shape (when `optionsType` is null). Return an exit code.
+     */
+    run(args: T): Promise<ExitCodeEnum | number>;
 }

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@pristine-ts/cli",
-  "version": "1.0.440",
+  "version": "2.0.2",
   "description": "",
   "module": "dist/lib/esm/cli.module.js",
   "main": "dist/lib/cjs/cli.module.js",
   "types": "dist/types/cli.module.d.ts",
   "bin": {
-    "pristine": "dist/lib/cjs/bin.js"
+    "pristine": "dist/bin/pristine.cjs"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json",
-    "postbuild": "chmod +x dist/lib/cjs/bin.js",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/build-bin.mjs",
     "prepublish": "npm run build",
     "test": "jest",
     "test:cov": "jest --coverage",
@@ -25,16 +24,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@pristine-ts/common": "^1.0.440",
-    "@pristine-ts/core": "^1.0.440",
-    "@pristine-ts/data-mapping": "^1.0.440",
-    "@pristine-ts/data-mapping-common": "^1.0.440",
-    "@pristine-ts/file": "^1.0.440",
-    "@pristine-ts/logging": "^1.0.440",
-    "@pristine-ts/validation": "^1.0.440",
-    "class-transformer": "^0.5.1",
+    "@inquirer/prompts": "^7.2.0",
+    "@pristine-ts/common": "^2.0.2",
+    "@pristine-ts/core": "^2.0.2",
+    "@pristine-ts/data-mapping": "^2.0.2",
+    "@pristine-ts/data-mapping-common": "^2.0.2",
+    "@pristine-ts/file": "^2.0.2",
+    "@pristine-ts/logging": "^2.0.2",
+    "@pristine-ts/validation": "^2.0.2",
+    "jiti": "^2.4.0",
     "uuid": "^9.0.1"
   },
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  },
   "jest": {
     "transform": {
       ".(ts|tsx)": "ts-jest"
@@ -69,7 +72,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "2828491bc8cc720476584f3cf60791a4a705a77e",
+  "gitHead": "b0899c7eb6b34a99c6df0739507b1458549a0009",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",