@pristine-ts/cli 2.0.3 → 2.0.5

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

@@ -1 +1 @@
-{"version":3,"file":"command-event-response.type.js","sourceRoot":"","sources":["../../../../src/types/command-event-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,mBAAmB,CAAC;AAIhD,MAAM,OAAO,oBAAqB,SAAQ,aAAyD;CAClG"}
+{"version":3,"file":"command-event-response.type.js","sourceRoot":"","sources":["../../../../src/types/command-event-response.type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,mBAAmB,CAAC;AAIhD,MAAM,OAAO,oBAAqB,SAAQ,aAAqD;CAC9F"}

package/dist/types/bin.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+declare const Cli: any;

package/dist/types/bootstrap/app-module-loader.d.ts

@@ -8,17 +8,21 @@ import { LoadedAppModule } from "./loaded-app-module";
 import { PluginLoader } from "./plugin-loader";
 /**
  * Resolves the consumer's AppModule. The contract is intentionally narrow: there is
- * exactly one supported way to specify the module — `appModule.sourcePath` +
- * `appModule.outputPath` in `pristine.config.ts` (or `pristine.config.js`).
+ * exactly one supported way to specify the module — `cli.appModule.sourcePath` +
+ * `cli.appModule.outputPath` in `pristine.config.ts` (or `pristine.config.js`).
  *
  * Resolution path:
  *   1. Read `pristine.config.{ts,js}` via `ConfigLoader`.
- *   2. If `appModule` is configured: ensure the build is fresh (manifest check, prompt or
- *      fail on stale), then dynamically import the configured `outputPath`.
+ *   2. If `cli.appModule` is configured: ensure the build is fresh (manifest check, prompt
+ *      or fail on stale), then dynamically import the configured `outputPath`.
  *   3. If anything above is missing or broken: fall back to a `CliModule`-only synthetic
  *      AppModule so built-in commands (notably `pristine init`) remain runnable. This is
  *      the only escape hatch — there is no convention scan, no package.json discovery,
  *      no cached prior selection.
+ *
+ * **Does not read the `config:` block.** Runtime configuration values are read directly
+ * by `ConfigurationManager` during kernel boot. This class is concerned only with
+ * module-graph assembly.
  */
 export declare class AppModuleLoader {
     private readonly configLoader;
@@ -32,32 +36,27 @@ export declare class AppModuleLoader {
     private readonly fallbackKeyname;
     constructor(configLoader: ConfigLoader, pluginLoader: PluginLoader, dynamicImporter: DynamicImporter, buildManifestReader: BuildManifestReader, buildManifestChecker: BuildManifestChecker, buildStalenessPrompt: BuildStalenessPrompt, buildRunner: BuildRunner);
     /**
-     * Resolves the consumer's AppModule and the kernel configuration the CLI should boot
-     * with. The flow has five stages, executed in order:
+     * Resolves the consumer's AppModule for the CLI. The flow has five stages:
      *
      *   1. **Read the project's pristine.config.{ts,js}** — single source of truth for
      *      where the user's AppModule lives and what plugins to wire in.
      *   2. **Check the compiled AppModule is in sync with its source** — when both
-     *      `appModule.sourcePath` and `appModule.outputPath` are configured, compare the
-     *      build manifest's recorded source hash against the current source. If they
-     *      diverge (the user edited source but didn't rebuild), prompt to rebuild in an
-     *      interactive terminal, or fail with an actionable error in CI / non-interactive
-     *      contexts.
+     *      `cli.appModule.sourcePath` and `cli.appModule.outputPath` are configured,
+     *      compare the build manifest's recorded source hash against the current source.
+     *      If they diverge (the user edited source but didn't rebuild), prompt to rebuild
+     *      in an interactive terminal, or fail with an actionable error in CI /
+     *      non-interactive contexts.
      *   3. **Dynamically import the compiled AppModule** — load the JS file at
      *      `outputPath` and pull out the configured named export (default `AppModule`).
      *   4. **Substitute a CliModule-only AppModule when nothing else worked** — when
-     *      there is no config file, no `appModule` block in the config, or the import
+     *      there is no config file, no `cli.appModule` block in the config, or the import
      *      threw, build a synthetic AppModule that imports just CliModule. This keeps the
      *      bin runnable so the user can run `pristine init`, `pristine help`, etc. to
      *      recover. There is no convention scan, no package.json discovery — only this
      *      one escape hatch.
-     *   5. **Wrap with config-declared plugins** — load every plugin listed in the
-     *      config's `plugins` array and merge their modules into the AppModule's import
-     *      graph via a synthetic outer module.
-     *
-     * Final output: a `LoadedAppModule` carrying the (possibly wrapped) AppModule, the
-     * kernel configuration overlay, the logging-module-present flag, and the loaded
-     * plugin list.
+     *   5. **Wrap with config-declared plugins** — load every plugin listed in
+     *      `cli.plugins` and merge their modules into the AppModule's import graph via a
+     *      synthetic outer module.
      */
     load(): Promise<LoadedAppModule>;
     /**
@@ -72,12 +71,12 @@ export declare class AppModuleLoader {
     private ensureFreshBuild;
     private importAppModule;
     /**
-     * Builds the safety-net AppModule used when no `appModule` is configured or the configured
-     * file fails to load. Scrapes any `node_modules/@pristine-ts/*` packages already installed
-     * so built-in commands they contribute (e.g. `pristine list`) are still available, then
-     * appends `CliModule` so at minimum the CLI's own commands run. This is intentionally a
-     * one-way safety net, not a discovery tier — it only fires when nothing else worked.
+     * Builds the safety-net AppModule used when no `cli.appModule` is configured or the
+     * configured file fails to load. Scrapes any `node_modules/@pristine-ts/*` packages
+     * already installed so built-in commands they contribute (e.g. `pristine list`) are
+     * still available, then appends `CliModule` so at minimum the CLI's own commands run.
+     * This is intentionally a one-way safety net, not a discovery tier — it only fires
+     * when nothing else worked.
      */
     private buildFallbackAppModule;
-    private buildKernelConfiguration;
 }

package/dist/types/bootstrap/loaded-app-module.d.ts

@@ -1,40 +1,26 @@
 import { AppModuleInterface } from "@pristine-ts/common";
-import { ModuleConfigurationValue } from "@pristine-ts/configuration";
 import { LoadedPlugin } from "./loaded-plugin";
 /**
- * The fully-resolved AppModule + ambient configuration that the CLI uses to boot the kernel.
+ * The fully-resolved AppModule and the plugin list that the CLI uses to boot the kernel.
  * Returned by `AppModuleLoader.load()`.
+ *
+ * **No `configuration` field.** Runtime configuration values from `pristine.config.ts:config`
+ * are read directly by `ConfigurationManager` during kernel boot, not pre-loaded by the
+ * CLI. The CLI is responsible only for module-graph assembly.
  */
 export declare class LoadedAppModule {
     readonly appModule: AppModuleInterface;
-    readonly configuration: {
-        [key: string]: ModuleConfigurationValue;
-    };
     /**
-     * True when `LoggingModule` is in the resolved AppModule's import graph. The CLI uses
-     * this to decide whether to layer in opinionated default logging configuration (Simple
-     * output mode, Error severity threshold) on top of the kernel configuration.
-     */
-    readonly isLoggingModulePresent: boolean;
-    /**
-     * Plugins loaded from `pristine.config.ts`'s `plugins` array. Empty when no plugins are
-     * declared. Carried through so commands like `pristine info` can show what's contributing
-     * extra modules to the runtime.
+     * Plugins loaded from `pristine.config.ts:cli.plugins`. Empty when no plugins are
+     * declared. Carried through so commands like `pristine info` can show what's
+     * contributing extra modules to the runtime.
      */
     readonly plugins: LoadedPlugin[];
-    constructor(appModule: AppModuleInterface, configuration: {
-        [key: string]: ModuleConfigurationValue;
-    }, 
-    /**
-     * True when `LoggingModule` is in the resolved AppModule's import graph. The CLI uses
-     * this to decide whether to layer in opinionated default logging configuration (Simple
-     * output mode, Error severity threshold) on top of the kernel configuration.
-     */
-    isLoggingModulePresent: boolean, 
+    constructor(appModule: AppModuleInterface, 
     /**
-     * Plugins loaded from `pristine.config.ts`'s `plugins` array. Empty when no plugins are
-     * declared. Carried through so commands like `pristine info` can show what's contributing
-     * extra modules to the runtime.
+     * Plugins loaded from `pristine.config.ts:cli.plugins`. Empty when no plugins are
+     * declared. Carried through so commands like `pristine info` can show what's
+     * contributing extra modules to the runtime.
      */
     plugins: LoadedPlugin[]);
 }

package/dist/types/bootstrap/plugin-loader.d.ts

@@ -3,7 +3,7 @@ import { PristineConfig } from "../config/pristine-config.interface";
 import { DynamicImporter } from "./dynamic-importer";
 import { LoadedPlugin } from "./loaded-plugin";
 /**
- * Resolves and loads every plugin declared in `config.plugins`. Plugin packages are resolved
+ * Resolves and loads every plugin declared in `config.cli.plugins`. Plugin packages are resolved
  * from the **consumer's project**, not from the CLI's install location — a plugin lives in
  * the consumer's `node_modules`, not in `@pristine-ts/cli/node_modules`. Without
  * `createRequire` pinned to the project location, `import("@my-org/plugin")` would walk up

package/dist/types/cli.d.ts

@@ -1,13 +1,73 @@
 /**
  * Boots the CLI: discovers the consumer's AppModule, starts the kernel, and dispatches
- * `process.argv` to whichever command matches. Exported so `bin.ts` can call it explicitly
- * — the auto-invoke at module load was removed so library consumers importing this file for
- * its types or `bootstrap` reference do not accidentally trigger an entire kernel boot.
+ * `process.argv` to whichever command matches. Returns the process exit code rather than
+ * exiting itself — `bin.ts` does `new Cli().bootstrap().then(process.exit)`.
  *
- * The bootstrap-layer collaborators (loaders, discoverers, cache, prompt) are instantiated
- * by hand here rather than resolved through DI. The kernel container does not exist yet at
- * this point, so DI is not available — manually wiring the (small, stable) class graph is the
- * least surprising option. Once the kernel is up, the kernel itself is registered into its
- * own container so commands can inject it.
+ * **Error handling is internal.** Every throw — from `appModuleLoader.load()`,
+ * `kernel.start()`, or the dispatched command — funnels through `reportFatalError` and
+ * gets rendered via `CliErrorReporter`. The bin doesn't need its own catch.
+ *
+ * **Per-call state.** `kernel` lives as an instance field so it's available to
+ * `reportFatalError` and `warnOnCommandCollisions` without threading it through method
+ * parameters. One `Cli` instance per `bootstrap()` invocation — the lifetime matches
+ * the CLI process.
+ *
+ * **No DI.** The kernel container does not exist yet during boot — the bootstrap-layer
+ * collaborators (loaders, discoverers, cache, prompt) are hand-wired in `build()`. Once
+ * the kernel is up, it registers itself into its own container so commands can inject it.
  */
-export declare const bootstrap: () => Promise<void>;
+export declare class Cli {
+    private kernel?;
+    bootstrap(): Promise<number>;
+    /**
+     * Renders any error that escapes the boot/dispatch flow and returns the exit code the
+     * bin should pass to `process.exit`.
+     *
+     * Two resolution paths for `EnvironmentManager`, picked in order of "most likely to be
+     * correctly configured":
+     *
+     *   1. **Kernel up**: resolve `CliErrorReporter` (and its `EnvironmentManager`) through
+     *      DI. This is the path for command-runtime errors — the configuration system
+     *      already ran and `pristine.environment` is whatever the user configured.
+     *
+     *   2. **Kernel-start failed**: peek directly at `pristine.config.ts:config` via
+     *      `PristineConfigFileLoader`. If a value for `pristine.environment` is set in the
+     *      file, use it; otherwise default to production. Boot-time errors get sanitized
+     *      unless the user explicitly opted into `dev` in the file.
+     *
+     * No `process.env` reads in any branch — the environment flows exclusively through
+     * the configuration system or its file source.
+     */
+    private reportFatalError;
+    /**
+     * Peeks at `pristine.config.ts:config[pristine.environment]` directly via the shared
+     * file loader. Used only by the kernel-down fallback in `reportFatalError`. Failures
+     * (file missing, parse error, etc.) silently fall back to production — boot-time
+     * sanitized output is the safer default.
+     */
+    private readEnvironmentFromConfigFile;
+    /**
+     * Builds a synthetic outer AppModule that imports both the user's AppModule and CliModule.
+     * 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.
+     */
+    private wrapWithCliModule;
+    /**
+     * Hand-wired graph of the bootstrap-layer classes. The kernel container does not exist
+     * yet, so we cannot resolve via DI — but the class graph here is shallow and stable, so
+     * manual wiring stays readable. Each class is `@injectable()` so DI resolution would also
+     * work if we ever moved this into a kernel-pre-boot container.
+     */
+    private buildAppModuleLoader;
+    /**
+     * Walks every registered Command-tagged service and warns to stderr if multiple share a
+     * `name`. The CLI's event dispatcher picks whichever match it sees first — without this
+     * warning, a plugin silently shadowing a built-in command (or two plugins shadowing each
+     * other) would be invisible until someone debugged "why is my command not running?".
+     * Warning rather than throwing keeps the bin runnable; users decide whether to fix the
+     * conflict.
+     */
+    private warnOnCommandCollisions;
+}

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

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

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { BuildCommand } from "./build.command";
 /**
  * Top-level alias for the framework-reserved `p:build` command. Injects the delegate
@@ -11,5 +11,5 @@ export declare class BuildAliasCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(delegate: BuildCommand);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,7 +1,7 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
 import { ConsoleManager } from "../managers/console.manager";
 import { ShellManager } from "../managers/shell.manager";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { ConfigLoader } from "../config/config-loader";
 import { BuildManifestWriter } from "../bootstrap/build-manifest-writer";
 /**
@@ -34,7 +34,7 @@ export declare class BuildCommand implements CommandInterface<null> {
     private readonly defaultTsconfig;
     private readonly defaultFormat;
     constructor(consoleManager: ConsoleManager, shellManager: ShellManager, configLoader: ConfigLoader, buildManifestWriter: BuildManifestWriter);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
     private writeManifestIfConfigured;
     /**
      * For `format: "both"`, we run two passes: the primary tsconfig (assumed ESM-ish), then

package/dist/types/commands/config-print.command.d.ts

@@ -1,6 +1,6 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
 import { ConsoleManager } from "../managers/console.manager";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { ConfigLoader } from "../config/config-loader";
 /**
  * Prints the resolved Pristine configuration plus where it was loaded from. Useful for
@@ -14,5 +14,5 @@ export declare class ConfigPrintCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(consoleManager: ConsoleManager, configLoader: ConfigLoader);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { HelpCommand } from "./help.command";
 /**
  * Top-level alias for the framework-reserved `p:help` command. Injects the delegate
@@ -13,5 +13,5 @@ export declare class HelpAliasCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(delegate: HelpCommand);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,7 +1,7 @@
 import { DependencyContainer } from "tsyringe";
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
 import { ConsoleManager } from "../managers/console.manager";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 /**
  * Prints a usage banner plus a one-line summary for every registered command. The output is
  * generated from the actual `CommandInterface[]` resolved from the current DI container, so
@@ -24,5 +24,5 @@ export declare class HelpCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(consoleManager: ConsoleManager, container: DependencyContainer);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { InfoCommand } from "./info.command";
 /**
  * Top-level alias for the framework-reserved `p:info` command. Injects the delegate
@@ -11,5 +11,5 @@ export declare class InfoAliasCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(delegate: InfoCommand);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,6 +1,6 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
 import { ConsoleManager } from "../managers/console.manager";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { ConfigLoader } from "../config/config-loader";
 import { AppModuleLoader } from "../bootstrap/app-module-loader";
 /**
@@ -27,7 +27,7 @@ export declare class InfoCommand implements CommandInterface<null> {
      */
     private readonly cliPackageJsonPath;
     constructor(consoleManager: ConsoleManager, configLoader: ConfigLoader, appModuleLoader: AppModuleLoader);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
     private printRuntimeBanner;
     private printConfigSection;
     private printAppModuleSection;

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { InitCommand } from "./init.command";
 import { InitCommandOptions } from "./init.command-options";
 /**
@@ -12,5 +12,5 @@ export declare class InitAliasCommand implements CommandInterface<InitCommandOpt
     name: string;
     description: string;
     constructor(delegate: InitCommand);
-    run(args: InitCommandOptions): Promise<ExitCodeEnum | number>;
+    run(args: InitCommandOptions): Promise<ExitCode | number>;
 }

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

@@ -1,6 +1,6 @@
+import { ExitCode } from "@pristine-ts/common";
 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";
 /**
@@ -27,7 +27,7 @@ export declare class InitCommand implements CommandInterface<InitCommandOptions>
     private readonly configFileName;
     private readonly gitignoreEntry;
     constructor(consoleManager: ConsoleManager, initPrompt: InitPrompt);
-    run(args: InitCommandOptions): Promise<ExitCodeEnum | number>;
+    run(args: InitCommandOptions): Promise<ExitCode | 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

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 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
@@ -11,5 +11,5 @@ export declare class ListAliasCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(delegate: ListCommand);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,7 +1,7 @@
+import { ExitCode } from "@pristine-ts/common";
 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
@@ -14,5 +14,5 @@ export declare class ListCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(consoleManager: ConsoleManager, container: DependencyContainer);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 import { CommandInterface } from "../interfaces/command.interface";
-import { ExitCodeEnum } from "../enums/exit-code.enum";
 import { StartCommand } from "./start.command";
 import { StartCommandOptions } from "./start.command-options";
 /**
@@ -12,5 +12,5 @@ export declare class StartAliasCommand implements CommandInterface<StartCommandO
     name: string;
     description: string;
     constructor(delegate: StartCommand);
-    run(args: StartCommandOptions): Promise<ExitCodeEnum | number>;
+    run(args: StartCommandOptions): Promise<ExitCode | number>;
 }

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 { 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
@@ -43,5 +43,5 @@ export declare class StartCommand implements CommandInterface<StartCommandOption
     private static readonly HARD_EXIT_TIMEOUT_MS;
     private readonly defaultRuntimeServerName;
     constructor(consoleManager: ConsoleManager, kernel: Kernel, servers: RuntimeServerInterface[]);
-    run(args: StartCommandOptions): Promise<ExitCodeEnum | number>;
+    run(args: StartCommandOptions): Promise<ExitCode | number>;
 }

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

@@ -1,5 +1,5 @@
+import { ExitCode } from "@pristine-ts/common";
 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
@@ -11,5 +11,5 @@ export declare class VerifyAliasCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(delegate: VerifyCommand);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,6 +1,6 @@
+import { ExitCode } from "@pristine-ts/common";
 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.
@@ -20,5 +20,5 @@ export declare class VerifyCommand implements CommandInterface<null> {
     name: string;
     description: string;
     constructor(logHandler: LogHandlerInterface, appModuleLoader: AppModuleLoader);
-    run(args: any): Promise<ExitCodeEnum | number>;
+    run(args: any): Promise<ExitCode | number>;
 }

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

@@ -1,8 +1,14 @@
 /**
- * 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.
+ * The shape of `pristine.config.ts` (or `pristine.config.js`). Two top-level blocks:
+ *
+ *   - **`cli:`** — CLI tool–specific configuration. Where the AppModule lives, which
+ *     plugins to load, build/start options. Read by `@pristine-ts/cli` before the kernel
+ *     exists, since this is what tells the CLI which app to assemble.
+ *   - **`config:`** — runtime configuration values keyed by
+ *     `configurationDefinition.parameterName`. Read by `@pristine-ts/configuration` during
+ *     kernel boot. Sits in the resolver precedence chain *above* per-key
+ *     `defaultResolvers` (env vars, secrets) and *below* explicit overrides passed to
+ *     `kernel.start()`.
  *
  * Authored as a `.ts` file by default; use `defineConfig()` (re-exported from
  * `@pristine-ts/cli`) for full IDE autocomplete:
@@ -11,9 +17,15 @@
  * import {defineConfig} from "@pristine-ts/cli";
  *
  * export default defineConfig({
- *   appModule: {
- *     sourcePath: "src/app.module.ts",
- *     outputPath: "dist/app.module.js",
+ *   cli: {
+ *     appModule: {
+ *       sourcePath: "src/app.module.ts",
+ *       outputPath: "dist/app.module.js",
+ *     },
+ *   },
+ *   config: {
+ *     "pristine.environment": "dev",
+ *     "pristine.logging.consoleLoggerActivated": true,
  *   },
  * });
  * ```
@@ -21,6 +33,25 @@
  * Run `pristine init` to generate this file interactively.
  */
 export interface PristineConfig {
+    /**
+     * CLI tool–specific configuration. Tells the CLI where to find the user's AppModule,
+     * which plugins to layer in, and how `pristine build` / `pristine start` should behave.
+     * Read by `@pristine-ts/cli` before the kernel exists.
+     */
+    cli?: PristineCliConfig;
+    /**
+     * Runtime configuration values keyed by `configurationDefinition.parameterName`. Read
+     * by `@pristine-ts/configuration` during kernel boot. A key here overrides the owning
+     * module's resolver chain and `defaultValue`, but loses to explicit overrides passed
+     * to `kernel.start()`.
+     */
+    config?: Record<string, unknown>;
+}
+/**
+ * Inner shape of the `cli:` block. Owned by `@pristine-ts/cli`; the framework's
+ * configuration system never inspects these fields.
+ */
+export interface PristineCliConfig {
     /**
      * Where the AppModule lives. Both `sourcePath` and `outputPath` are required when
      * `appModule` is set. Paths are resolved relative to the directory containing the
@@ -59,9 +90,4 @@ export interface PristineConfig {
         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

@@ -10,9 +10,8 @@ export declare class ResolvedPristineConfig {
     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.
+     * top-level fields of `PristineConfig` (`cli`, `config`); values are the
+     * `ConfigProvenanceEnum` describing where each came from.
      */
     readonly provenance: Record<string, ConfigProvenanceEnum>;
     constructor(config: PristineConfig, 
@@ -20,9 +19,8 @@ export declare class ResolvedPristineConfig {
     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.
+     * top-level fields of `PristineConfig` (`cli`, `config`); values are the
+     * `ConfigProvenanceEnum` describing where each came from.
      */
     provenance: Record<string, ConfigProvenanceEnum>);
 }

package/dist/types/errors/cli-error-code.enum.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error-code catalog owned by `@pristine-ts/cli`. Surfaced via `PristineErrorOptions.code`
+ * (typed `PristineErrorCode | string`, so any enum value is accepted).
+ *
+ * Codes here describe CLI-specific failures — command resolution, argument mapping,
+ * and argument validation.
+ */
+export declare enum CliErrorCode {
+    CommandNotFound = "COMMAND_NOT_FOUND",
+    ArgumentMappingFailed = "ARGUMENT_MAPPING_FAILED",
+    ArgumentValidationFailed = "ARGUMENT_VALIDATION_FAILED"
+}

package/dist/types/errors/command-not-found.error.d.ts

@@ -1,12 +1,13 @@
-import { LoggableError } from "@pristine-ts/common";
+import { UsageError } from "@pristine-ts/common";
 /**
- * The CommandNotFoundError error when the command specified is not implemented.
+ * Thrown when the user invokes a CLI command name that isn't registered with the kernel.
+ *
+ * Extends `UsageError` (which carries `exitCode: 64` / `EX_USAGE`, `kind: PristineErrorKind.UserError`) so
+ * the `CliErrorReporter` renders it as a clean one-line stderr message rather than a
+ * crash dump. The unknown command name is preserved as a structured `details.commandName`
+ * field, which surfaces under the error code in the stderr output.
  */
-export declare class CommandNotFoundError extends LoggableError {
+export declare class CommandNotFoundError extends UsageError {
     readonly commandName: string;
-    /**
-     * This Error is the base class for CommandNotFoundError errors.
-     * @param commandName The name of the command that could not be found
-     */
     constructor(commandName: string);
 }