@pristine-ts/cli 2.0.16 → 2.0.18

package/dist/lib/esm/types/command-parameter-choices-list.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command-parameter-choices-list.type.js.map

package/dist/lib/esm/types/command-parameter-choices-list.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parameter-choices-list.type.js","sourceRoot":"","sources":["../../../../src/types/command-parameter-choices-list.type.ts"],"names":[],"mappings":""}

package/dist/lib/esm/types/command-parameter-choices-resolver.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command-parameter-choices-resolver.type.js.map

package/dist/lib/esm/types/command-parameter-choices-resolver.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parameter-choices-resolver.type.js","sourceRoot":"","sources":["../../../../src/types/command-parameter-choices-resolver.type.ts"],"names":[],"mappings":""}

package/dist/lib/esm/types/command-parameter-choices.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=command-parameter-choices.type.js.map

package/dist/lib/esm/types/command-parameter-choices.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-parameter-choices.type.js","sourceRoot":"","sources":["../../../../src/types/command-parameter-choices.type.ts"],"names":[],"mappings":""}

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

@@ -1,4 +1,7 @@
 export * from "./command-event.type";
 export * from "./command-event-response.type";
+export * from "./command-parameter-choices-list.type";
+export * from "./command-parameter-choices-resolver.type";
+export * from "./command-parameter-choices.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;AAC9C,cAAc,kCAAkC,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,uCAAuC,CAAC;AACtD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC"}

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

@@ -17,6 +17,12 @@ export declare const CliConfigurationKeys: {
      * input is not an interactive terminal, regardless of this value.
      */
     readonly InteractiveParameters: "pristine.cli.interactiveParameters";
+    /**
+     * Explicit program name shown in generated `Usage:` lines (e.g. `myapp`). Optional: when unset,
+     * the CLI derives the name from `argv[1]`, falling back to `pristine`. Set it for launch shapes
+     * where `argv[1]` isn't the friendly name (e.g. `node dist/bin/cli.cjs`).
+     */
+    readonly BinName: "pristine.cli.binName";
 };
 /**
  * The expected runtime types for each configuration value defined by `@pristine-ts/cli`. The
@@ -25,6 +31,7 @@ export declare const CliConfigurationKeys: {
  */
 export interface CliConfigurationValueMap {
     "pristine.cli.interactiveParameters": boolean;
+    "pristine.cli.binName": string;
 }
 declare module "@pristine-ts/common" {
     interface PristineConfigurationValueMap extends CliConfigurationValueMap {

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

@@ -9,6 +9,16 @@ export declare enum CliErrorCode {
     CommandNotFound = "COMMAND_NOT_FOUND",
     ArgumentMappingFailed = "ARGUMENT_MAPPING_FAILED",
     ArgumentValidationFailed = "ARGUMENT_VALIDATION_FAILED",
+    /**
+     * A required command-line argument was missing. Reported with the command's `Usage:` synopsis
+     * (exit 64). Distinct from a value supplied but invalid (`InvalidArgument`).
+     */
+    MissingRequiredArgument = "MISSING_REQUIRED_ARGUMENT",
+    /**
+     * A supplied command-line argument failed validation. Reported as a clean
+     * `Invalid <flag> '<value>'. …` line (exit 64).
+     */
+    InvalidArgument = "INVALID_ARGUMENT",
     /**
      * 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.

package/dist/types/interfaces/command-parameter-choice.interface.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A single selectable choice for a `@commandParameter` whose value comes from a fixed or
+ * runtime-resolved set. `name` is what the interactive menu shows; `value` is what gets bound
+ * to the parameter (and validated) when the choice is picked.
+ *
+ * A bare `string` is accepted anywhere a `CommandParameterChoice` is — it expands to
+ * `{name: value, value: value}`.
+ */
+export interface CommandParameterChoice {
+    /** Human-readable label rendered in the selection menu. */
+    name: string;
+    /** Value bound to the parameter when this choice is selected. */
+    value: string;
+}

package/dist/types/interfaces/command-parameter-choices-context.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Passed to a dynamic choices resolver (a function or a
+ * `CommandParameterChoicesProviderInterface`) so it can compute the allowed values from the
+ * arguments resolved so far — e.g. list the tables of whichever `--database` was already
+ * answered.
+ */
+export interface CommandParameterChoicesContext {
+    /**
+     * The arguments known so far: flags passed on the command line plus any values already
+     * answered interactively earlier in the same prompt pass. Keyed by property name.
+     */
+    args: Record<string, any>;
+    /** The options-class property whose choices are being resolved. */
+    propertyKey: string;
+    /** The effective CLI flag for that property (the `flag` override, or the property name). */
+    flag: string;
+}

package/dist/types/interfaces/command-parameter-choices-provider.interface.d.ts

@@ -0,0 +1,20 @@
+import { CommandParameterChoicesContext } from "./command-parameter-choices-context.interface";
+import { CommandParameterChoicesList } from "../types/command-parameter-choices-list.type";
+/**
+ * A dependency-injected provider of dynamic `@commandParameter` choices. Reference the
+ * provider *class* from `@commandParameter({choices: MyProvider})`; the CLI resolves it from
+ * the container at prompt time (so it can inject a `FileManager`, `HttpClient`, …) and calls
+ * `getChoices`. Use this form when choice resolution needs framework services; use a plain
+ * resolver function when it doesn't.
+ *
+ * The provider class must be registered with DI (`@injectable()`, and `@moduleScoped` to the
+ * consuming module as usual).
+ */
+export interface CommandParameterChoicesProviderInterface {
+    /**
+     * Returns the allowed choices, optionally narrowed by the already-resolved arguments in
+     * `context`. May be async (the resolver awaits it). Returning an empty list disables the
+     * menu — the value then falls through to the normal free-text prompt + validation.
+     */
+    getChoices(context: CommandParameterChoicesContext): CommandParameterChoicesList | Promise<CommandParameterChoicesList>;
+}

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

@@ -1,2 +1,5 @@
 export * from "./command.interface";
+export * from "./command-parameter-choice.interface";
+export * from "./command-parameter-choices-context.interface";
+export * from "./command-parameter-choices-provider.interface";
 export * from "./terminal-key.interface";

package/dist/types/options/command-parameter.options.d.ts

@@ -1,3 +1,4 @@
+import { CommandParameterChoices } from "../types/command-parameter-choices.type";
 /**
  * Options accepted by the `@commandParameter` decorator. Every field is optional: an empty
  * `@commandParameter()` is valid and simply marks the property as a known command-line
@@ -26,4 +27,33 @@ export interface CommandParameterOptions {
      * never trimmed or printed back in any re-ask/validation feedback.
      */
     sensitive?: boolean;
+    /**
+     * The set of allowed values for this parameter (single-select). When present and the value is
+     * asked for interactively, the CLI shows an arrow-key menu instead of a free-text prompt.
+     *
+     * Three shapes:
+     *   - a **static** list — `["dev", "staging", "prod"]` or `[{name, value}, …]`;
+     *   - a **resolver function** — `(ctx) => […]` (sync or async), for values computed at prompt
+     *     time with no framework services;
+     *   - a **provider class** — a `CommandParameterChoicesProviderInterface` constructor, resolved
+     *     from DI so it can inject services (e.g. list files, query an API).
+     *
+     * Dynamic choices (function / provider) drive the interactive menu only; a value passed as a
+     * flag is taken as-is (the resolver isn't run off the prompt path). Pair with `@IsIn(...)` if a
+     * dynamic value must also be validated when supplied non-interactively. A *static* list is not
+     * itself a validator — add `@IsIn(...)` / `@IsEnum(...)` to enforce it everywhere.
+     */
+    choices?: CommandParameterChoices;
+    /**
+     * The placeholder shown for this parameter in the generated `Usage:` line — e.g. `key-or-file`
+     * renders `[--pubkey=<key-or-file>]`. Defaults to the property name.
+     */
+    valueHint?: string;
+    /**
+     * Overrides the *entire* message shown when a supplied value fails validation — used verbatim,
+     * with `%value%` and `%flag%` placeholders substituted (the value is `<hidden>` for a
+     * `sensitive` parameter). When omitted, the message is generated as
+     * `Invalid <flag> '<value>'. <validator message>`.
+     */
+    errorMessage?: string;
 }

package/dist/types/services/command-argument-error-formatter.d.ts

@@ -0,0 +1,64 @@
+import { ClassConstructor } from "class-transformer";
+import { UsageError } from "@pristine-ts/common";
+import { CommandUsageRenderer } from "./command-usage-renderer";
+/**
+ * Turns `@pristine-ts/class-validator`'s raw per-property validation output into a single,
+ * clean, user-facing `UsageError` (exit 64, rendered verbatim via `options.plain`) instead of
+ * a `[CONSTRAINT_KEY]`-prefixed dump:
+ *
+ *   - if any *required* parameter is missing → the command's `Usage:` synopsis, so the user
+ *     sees what to pass (and not a wall of "is not a string" noise for an absent value);
+ *   - otherwise (values present but invalid) → one line per offending value: the parameter's
+ *     `errorMessage` (verbatim, `%value%`/`%flag%` filled), or a generated
+ *     `Invalid <flag> '<value>'. <validator message>` with the constraint-key prefix and
+ *     definedness noise stripped.
+ *
+ * Returns the error rather than throwing it, so the resolver keeps the `throw` (clean control
+ * flow) and tests can assert on the built error directly.
+ */
+export declare class CommandArgumentErrorFormatter {
+    private readonly usageRenderer;
+    /**
+     * Constraint keynames that only trip because a value is *absent*. For a present-but-invalid
+     * value these never fire, so we drop them and surface the semantic constraint (e.g.
+     * `MATCHES`) the user actually needs — never "is not a string" for a value they gave.
+     */
+    private static readonly DefinednessConstraints;
+    constructor(usageRenderer: CommandUsageRenderer);
+    /**
+     * Builds the `UsageError` for a set of validation errors. `mapped` is the (failed) options
+     * instance — read to get each property's effective value and to tell "missing" (undefined /
+     * empty) from "present but invalid".
+     */
+    buildValidationError(optionsType: ClassConstructor<any>, mapped: Record<string, any>, validationErrors: any[], context: {
+        commandName: string;
+        binName: string;
+    }): UsageError;
+    /** A value counts as "missing" when it never arrived — undefined/null or an empty string. */
+    private isMissing;
+    /**
+     * One line for an offending value. A parameter's `errorMessage` is the *entire* line, used
+     * verbatim (with `%value%`/`%flag%` filled); otherwise we generate
+     * `Invalid <flag> '<value>'. <validator message>`. Sensitive parameters never echo the value
+     * (it is `<hidden>`, even inside a custom template).
+     * @private
+     */
+    private invalidLine;
+    /**
+     * The validator's own message for a present-but-invalid value: the first *semantic* constraint
+     * message (definedness noise dropped), falling back to the first message present.
+     * @private
+     */
+    private validatorMessage;
+    /**
+     * Splits an error's constraint messages into the first *semantic* one (not a definedness
+     * constraint) and a plain first-seen fallback. Reads `@pristine-ts/class-validator`'s
+     * `{keyname, message}` constraint objects defensively.
+     * @private
+     */
+    private constraintMessages;
+    /** Pulls the human message out of a `{keyname, message}` constraint (or a bare string). */
+    private extractMessage;
+    private optionsFor;
+    private flagFor;
+}

package/dist/types/services/command-options-resolver.d.ts

@@ -2,15 +2,17 @@ import { ClassConstructor } from "class-transformer";
 import { Validator } from "@pristine-ts/class-validator";
 import { DataMapper } from "@pristine-ts/data-mapping";
 import { CommandParameterPrompter } from "./command-parameter-prompter";
+import { CommandArgumentErrorFormatter } from "./command-argument-error-formatter";
+import { ProgramNameResolver } from "./program-name-resolver";
 /**
  * Resolves a typed, validated options instance from raw arguments: it fills any missing
- * `@commandParameter` values by prompting, maps the result onto a real `optionsType`
- * instance (prototype + decorator metadata intact, so `class-validator` finds its rules),
- * and validates it.
+ * `@commandParameter` values by prompting, maps the result onto a real `optionsType` instance
+ * (prototype + decorator metadata intact, so `class-validator` finds its rules), and validates
+ * it.
  *
- * This is the reusable core behind command dispatch — `CommandArgumentResolver` delegates
- * here — exposed so commands and dynamic flows can fill an options class from prompts on
- * demand, including ones not tied to a registered command:
+ * This is the reusable core behind command dispatch — `CommandArgumentResolver` delegates here
+ * — exposed so commands and dynamic flows can fill an options class from prompts on demand,
+ * including ones not tied to a registered command:
  *
  * ```ts
  * constructor(private readonly optionsResolver: CommandOptionsResolver) {}
@@ -18,18 +20,26 @@ import { CommandParameterPrompter } from "./command-parameter-prompter";
  * const options = await this.optionsResolver.resolve(MyOptions, {region: "us"});
  * ```
  *
- * Throws `UsageError` for mapping failures and `ValidationError` for validation failures —
- * both carry structured `details` for `CliErrorReporter`.
+ * Argument problems throw a `UsageError` (exit 64): mapping failures directly, and validation
+ * failures via `CommandArgumentErrorFormatter`, which renders a clean `Usage:` synopsis (for a
+ * missing required value) or `Invalid <flag> '<value>'. …` lines (for a supplied-but-invalid
+ * value) rather than a raw constraint dump.
  */
 export declare class CommandOptionsResolver {
     private readonly validator;
     private readonly dataMapper;
     private readonly commandParameterPrompter;
-    constructor(validator: Validator, dataMapper: DataMapper, commandParameterPrompter: CommandParameterPrompter);
+    private readonly argumentErrorFormatter;
+    private readonly programNameResolver;
+    constructor(validator: Validator, dataMapper: DataMapper, commandParameterPrompter: CommandParameterPrompter, argumentErrorFormatter: CommandArgumentErrorFormatter, programNameResolver: ProgramNameResolver);
     /**
-     * Prompts for any missing parameters declared on `optionsType`, then maps `rawArgs` (plus
-     * the prompted answers) onto a real instance and validates it. `rawArgs` seeds the values
-     * already known — anything absent that carries a `question` is asked for interactively.
+     * Prompts for any missing parameters declared on `optionsType`, then maps `rawArgs` (plus the
+     * prompted answers) onto a real instance and validates it. `rawArgs` seeds the values already
+     * known — anything absent that carries a `question` is asked for interactively.
+     * `context.commandName` is woven into the `Usage:` line shown when a required value is missing
+     * (defaults to a neutral placeholder for direct, command-less callers).
      */
-    resolve<T>(optionsType: ClassConstructor<T>, rawArgs?: Record<string, any>): Promise<T>;
+    resolve<T>(optionsType: ClassConstructor<T>, rawArgs?: Record<string, any>, context?: {
+        commandName?: string;
+    }): Promise<T>;
 }

package/dist/types/services/command-parameter-prompter.d.ts

@@ -1,25 +1,27 @@
 import "reflect-metadata";
+import { DependencyContainer } from "tsyringe";
 import { ClassConstructor } from "class-transformer";
 import { Validator } from "@pristine-ts/class-validator";
 import { DataMapper } from "@pristine-ts/data-mapping";
 import { CliPrompt } from "../managers/cli-prompt.manager";
 import { CliOutput } from "../managers/cli-output.manager";
 /**
- * Applies a command's `@commandParameter` metadata to its raw, parsed arguments before they
- * are mapped onto the options instance and validated. Two things happen here:
+ * Applies a command's `@commandParameter` metadata to its raw, parsed arguments before they are
+ * mapped onto the options instance and validated. Two things happen here:
  *
- *   1. **Flag binding** — a parameter whose `flag` differs from its property name is copied
- *      from the flag key onto the property key, so the by-property-name data mapper picks it
- *      up. Two parameters resolving to the same flag is a programming error and throws.
- *   2. **Interactive fill** — a parameter that is absent and declares a `question` is asked
- *      for interactively. Answers are rendered and checked against the property's declared
- *      type (booleans as `(y/n)`, enum-constrained values list their choices) and coerced +
- *      validated through the same mapper/validator the command pipeline uses, re-asking on an
- *      invalid answer. Gated by the `InteractiveParameters` configuration and only run against
- *      an interactive terminal; otherwise the absent value is left for validation to report.
+ *   1. **Flag binding** — a parameter whose `flag` differs from its property name is copied from
+ *      the flag key onto the property key, so the by-property-name data mapper picks it up. Two
+ *      parameters resolving to the same flag is a programming error and throws.
+ *   2. **Interactive fill** — a parameter that is absent and declares a `question` is asked for
+ *      interactively. Values constrained to a set — an explicit `choices`, or an `@IsIn` /
+ *      `@IsEnum` — are picked from an arrow-key menu; booleans answer `(y/n)`; everything else is
+ *      a free-text answer coerced + validated through the same mapper/validator the command
+ *      pipeline uses, re-asking on an invalid answer. Gated by the `InteractiveParameters`
+ *      configuration and only run against an interactive terminal; otherwise the absent value is
+ *      left for validation to report.
  *
- * Parameters without a `@commandParameter` decorator are untouched, so commands that don't
- * use it pay nothing.
+ * Parameters without a `@commandParameter` decorator are untouched, so commands that don't use
+ * it pay nothing.
  */
 export declare class CommandParameterPrompter {
     private readonly cliPrompt;
@@ -27,6 +29,7 @@ export declare class CommandParameterPrompter {
     private readonly validator;
     private readonly dataMapper;
     private readonly interactiveParametersEnabled;
+    private readonly container;
     /**
      * `@pristine-ts/class-validator` stores its instantiated validators (one per `@IsX`
      * decorator) as an array under this property-metadata key. We read it only to surface enum
@@ -39,35 +42,62 @@ export declare class CommandParameterPrompter {
      * unbounded loop) keeps a misconfigured validator that can never pass from hanging the CLI.
      */
     private static readonly MaxAttempts;
-    constructor(cliPrompt: CliPrompt, cliOutput: CliOutput, validator: Validator, dataMapper: DataMapper, interactiveParametersEnabled: boolean);
+    constructor(cliPrompt: CliPrompt, cliOutput: CliOutput, validator: Validator, dataMapper: DataMapper, interactiveParametersEnabled: boolean, container: DependencyContainer);
     /**
      * Returns a copy of `rawArgs` with aliased flags bound to their property and any missing,
-     * question-carrying parameters filled in interactively. The input object is never mutated
-     * — the original command event payload stays intact.
+     * question-carrying parameters filled in interactively. The input object is never mutated —
+     * the original command event payload stays intact.
      */
     fillMissingParameters(optionsType: ClassConstructor<any>, rawArgs: Record<string, any>): Promise<Record<string, any>>;
     /**
-     * Reads every `@commandParameter` off `optionsType`, resolving each to its effective flag
-     * and detecting two parameters that would claim the same flag (a programming error).
+     * Reads every `@commandParameter` off `optionsType`, resolving each to its effective flag and
+     * detecting two parameters that would claim the same flag (a programming error).
      * @private
      */
     private collectParameters;
     /**
-     * Asks for a single parameter's value, rendering and validating it according to the
-     * property's declared type:
+     * Asks for a single parameter's value, rendering and validating it according to the property's
+     * declared type:
      *
      *   - sensitive values are read with the input masked and never trimmed;
+     *   - a constrained value (explicit `choices`, or `@IsIn` / `@IsEnum`) is picked from an
+     *     arrow-key menu, then coerced + validated like any typed value;
      *   - booleans render as `(y/n)` and accept y/yes/true/1 & n/no/false/0;
-     *   - enum-constrained values (`@IsIn` / `@IsEnum`) list their choices;
      *   - every other answer is coerced (via the data mapper) and validated (via the validator)
      *     exactly as a typed flag would be, re-asking with the real constraint message when it
      *     doesn't pass.
      *
-     * Returns the coerced value, or `undefined` when the user enters nothing or the attempt
-     * budget is exhausted — in which case the absent value falls through to validation.
+     * Returns the coerced value, or `undefined` when the user enters nothing or the attempt budget
+     * is exhausted — in which case the absent value falls through to validation.
      * @private
      */
     private promptForValue;
+    /**
+     * Resolves this parameter's selectable choices to a `{name, value}[]` menu, or `undefined`
+     * when it has none (free-text). Sources, in order: an explicit `@commandParameter({choices})`
+     * — a static list, a resolver function, or a DI provider class — else the `@IsIn` / `@IsEnum`
+     * set. An empty result is treated as "no menu".
+     * @private
+     */
+    private resolveChoices;
+    /**
+     * The raw choices list from the declared `choices` (static array / resolver function / DI
+     * provider class), falling back to the enum/`@IsIn` set when none is declared. Dynamic
+     * resolution failures degrade to free-text rather than crashing the prompt.
+     * @private
+     */
+    private resolveChoicesList;
+    /**
+     * Whether `candidate` is a provider *class* (vs a plain resolver function): a class carries a
+     * prototype with a `getChoices` method; an arrow/plain resolver does not.
+     * @private
+     */
+    private isChoicesProviderClass;
+    /**
+     * The menu heading: the parameter's `question` when set, else a neutral `Select <flag>`.
+     * @private
+     */
+    private menuMessage;
     /**
      * Maps a single raw answer onto a probe instance of `optionsType` and validates just that
      * property, returning the coerced value when it passes or the constraint messages when it
@@ -77,18 +107,17 @@ export declare class CommandParameterPrompter {
      */
     private coerceAndValidate;
     /**
-     * Flattens `class-validator`'s per-property constraint objects into plain, user-facing
-     * lines. `@pristine-ts/class-validator` stores each constraint as `{keyname, message}`
-     * rather than a bare string, so prefer `.message`, falling back so we never print
-     * `[object Object]`.
+     * Flattens `class-validator`'s per-property constraint objects into plain, user-facing lines.
+     * `@pristine-ts/class-validator` stores each constraint as `{keyname, message}` rather than a
+     * bare string, so prefer `.message`, falling back so we never print `[object Object]`.
      * @private
      */
     private describeErrors;
     /**
      * The allowed values declared by an `@IsIn([...])` or `@IsEnum(Enum)` on the property, for
      * display in the prompt. Reads `@pristine-ts/class-validator`'s stored validator instances
-     * defensively — any shape mismatch just yields no menu (validation still rejects bad input
-     * and re-asks). Returns undefined when the property isn't enum-constrained.
+     * defensively — any shape mismatch just yields no menu (validation still rejects bad input and
+     * re-asks). Returns undefined when the property isn't enum-constrained.
      * @private
      */
     private getChoices;
@@ -105,8 +134,8 @@ export declare class CommandParameterPrompter {
      */
     private isInputInteractive;
     /**
-     * Ensures the rendered question ends with a trailing space so the typed answer doesn't butt
-     * up against the prompt text.
+     * Ensures the rendered question ends with a trailing space so the typed answer doesn't butt up
+     * against the prompt text.
      * @private
      */
     private formatQuestion;

package/dist/types/services/command-usage-renderer.d.ts

@@ -0,0 +1,35 @@
+import "reflect-metadata";
+import { ClassConstructor } from "class-transformer";
+/**
+ * Builds the one-line `Usage:` synopsis for a command from its options class, e.g.
+ *
+ *   Usage: myapp key:add --name=<name> [--pubkey=<key-or-file>] [--rotate]
+ *
+ * Every declared option property becomes a token: required values render as `--flag=<hint>`,
+ * optional values as `[--flag=<hint>]`, and booleans as `[--flag]` (presence flags take no
+ * value). The placeholder defaults to the property name and can be overridden per parameter
+ * with `@commandParameter({valueHint})`; the flag honors `@commandParameter({flag})`.
+ *
+ * "Required" means the absence of an `@IsOptional()` condition on the property — the same
+ * signal the validator uses to decide whether a missing value is an error.
+ */
+export declare class CommandUsageRenderer {
+    /** `@pristine-ts/class-validator` stores each `@IsOptional()` as a condition here. */
+    private static readonly ConditionMetadataKey;
+    /**
+     * Renders `Usage: <bin> <command> <tokens…>`. `binName` is the resolved program name (see
+     * `ProgramNameResolver`); `commandName` is the command's `name`.
+     */
+    render(optionsType: ClassConstructor<any>, commandName: string, binName: string): string;
+    /**
+     * One synopsis token per declared option property, in declaration order.
+     * @private
+     */
+    private collectTokens;
+    /**
+     * A property is required unless it carries an `@IsOptional()` condition. Read defensively: an
+     * unexpected metadata shape is treated as required (the safer default for a usage hint).
+     * @private
+     */
+    private isRequired;
+}

package/dist/types/services/program-name-resolver.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resolves the program name shown in generated `Usage:` lines — the name the user actually
+ * typed, e.g. `myapp`, not the framework's `pristine`. Resolution is a hybrid, in priority
+ * order:
+ *
+ *   1. the `pristine.cli.binName` configuration, when set (an explicit override for odd launch
+ *      shapes like `node dist/bin/cli.cjs`, where argv carries a file name);
+ *   2. otherwise `basename(argv[1])` with any `.cjs`/`.js`/`.mjs` extension stripped — the bin
+ *      the user invoked, robust across global installs, `npx`, and local `.bin` shims;
+ *   3. otherwise the framework default `pristine`.
+ */
+export declare class ProgramNameResolver {
+    private readonly configuredBinName;
+    private static readonly Fallback;
+    constructor(configuredBinName: string);
+    /**
+     * Returns the resolved program name. `argv` defaults to `process.argv`; it is a parameter so
+     * the REPL (and tests) can resolve a name from a synthetic argv.
+     */
+    resolve(argv?: readonly string[]): string;
+}

package/dist/types/services/services.d.ts

@@ -1,3 +1,6 @@
+export * from "./command-argument-error-formatter";
 export * from "./command-argument-resolver";
 export * from "./command-options-resolver";
 export * from "./command-parameter-prompter";
+export * from "./command-usage-renderer";
+export * from "./program-name-resolver";

package/dist/types/types/command-parameter-choices-list.type.d.ts

@@ -0,0 +1,6 @@
+import { CommandParameterChoice } from "../interfaces/command-parameter-choice.interface";
+/**
+ * The result of resolving a parameter's choices: an ordered list where each entry is either a
+ * `{name, value}` pair or a bare `string` (shorthand for `{name: s, value: s}`).
+ */
+export type CommandParameterChoicesList = ReadonlyArray<string | CommandParameterChoice>;

package/dist/types/types/command-parameter-choices-resolver.type.d.ts

@@ -0,0 +1,9 @@
+import { CommandParameterChoicesContext } from "../interfaces/command-parameter-choices-context.interface";
+import { CommandParameterChoicesList } from "./command-parameter-choices-list.type";
+/**
+ * A plain function that computes a parameter's choices at prompt time, optionally narrowed by
+ * the already-resolved arguments. Use this when resolution needs no framework services (env
+ * vars, a captured closure, simple computation); reach for
+ * `CommandParameterChoicesProviderInterface` when it needs DI.
+ */
+export type CommandParameterChoicesResolver = (context: CommandParameterChoicesContext) => CommandParameterChoicesList | Promise<CommandParameterChoicesList>;

package/dist/types/types/command-parameter-choices.type.d.ts

@@ -0,0 +1,19 @@
+import { ClassConstructor } from "class-transformer";
+import { CommandParameterChoicesList } from "./command-parameter-choices-list.type";
+import { CommandParameterChoicesResolver } from "./command-parameter-choices-resolver.type";
+import { CommandParameterChoicesProviderInterface } from "../interfaces/command-parameter-choices-provider.interface";
+/**
+ * What `@commandParameter({choices})` accepts. Three shapes, one behavior (single-select):
+ *
+ *   - **static** — a `CommandParameterChoicesList` (array of `{name, value}` or bare strings)
+ *     known at decoration time;
+ *   - **dynamic, no DI** — a `CommandParameterChoicesResolver` function resolved at prompt
+ *     time;
+ *   - **dynamic, with DI** — the *class* of a `CommandParameterChoicesProviderInterface`,
+ *     resolved from the container at prompt time so it can inject framework services.
+ *
+ * Dynamic choices are resolved only on the interactive path (an arrow-key menu); a value
+ * passed as a flag is taken as-is. Add `@IsIn(...)` if a dynamic value must also be validated
+ * when supplied non-interactively.
+ */
+export type CommandParameterChoices = CommandParameterChoicesList | CommandParameterChoicesResolver | ClassConstructor<CommandParameterChoicesProviderInterface>;

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

@@ -1,3 +1,6 @@
 export * from "./command-event.type";
 export * from "./command-event-response.type";
+export * from "./command-parameter-choices-list.type";
+export * from "./command-parameter-choices-resolver.type";
+export * from "./command-parameter-choices.type";
 export * from "./start-repl-event-response.type";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/cli",
-  "version": "2.0.16",
+  "version": "2.0.18",
   "description": "",
   "module": "dist/lib/esm/cli.module.js",
   "main": "dist/lib/cjs/cli.module.js",
@@ -27,17 +27,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@pristine-ts/common": "^2.0.16",
-    "@pristine-ts/configuration": "^2.0.16",
-    "@pristine-ts/core": "^2.0.16",
-    "@pristine-ts/data-mapping": "^2.0.16",
-    "@pristine-ts/data-mapping-common": "^2.0.16",
-    "@pristine-ts/file": "^2.0.16",
-    "@pristine-ts/logging": "^2.0.16",
+    "@pristine-ts/common": "^2.0.18",
+    "@pristine-ts/configuration": "^2.0.18",
+    "@pristine-ts/core": "^2.0.18",
+    "@pristine-ts/data-mapping": "^2.0.18",
+    "@pristine-ts/data-mapping-common": "^2.0.18",
+    "@pristine-ts/file": "^2.0.18",
+    "@pristine-ts/logging": "^2.0.18",
     "@pristine-ts/metadata": "^1.0.16",
-    "@pristine-ts/observability": "^2.0.16",
-    "@pristine-ts/telemetry": "^2.0.16",
-    "@pristine-ts/validation": "^2.0.16"
+    "@pristine-ts/observability": "^2.0.18",
+    "@pristine-ts/telemetry": "^2.0.18",
+    "@pristine-ts/validation": "^2.0.18"
   },
   "devDependencies": {
     "esbuild": "^0.24.0"
@@ -76,7 +76,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "a55d7d59862672a8cbbca4088fed090779b37705",
+  "gitHead": "2a2c5dbb9b5060b30528335ad17a174fae43f87c",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",