@rzl-zone/build-tools 0.0.5

package/dist/commander-kit/index.d.ts

@@ -0,0 +1,1383 @@
+/*!
+* ========================================================================
+*  @rzl-zone/build-tools
+* ------------------------------------------------------------------------
+*  Version: `0.0.5`
+*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
+* ========================================================================
+*/
+
+import { t as AnyString } from "../extra-CVuXMpEw.js";
+import { t as CommandIdentity } from "../index-CzxZta4Z.js";
+import { AddHelpTextContext, AddHelpTextPosition, Argument, Command, CommandOptions, CommanderError, ErrorOptions, ExecutableCommandOptions, Help, HelpConfiguration, HelpContext, HookEvent, InvalidArgumentError, InvalidOptionArgumentError, Option, OptionValueSource, OptionValues, OutputConfiguration, ParseOptions, ParseOptionsResult } from "commander";
+
+/** ----------------------------------------------------------------
+* * ***CLI command definition class.***
+* ----------------------------------------------------------------
+*
+* Primary building block used to define CLI programs and
+* subcommands.
+*
+* This class extends Commander’s {@link Command | **`Command`**} class and
+* adds additional behavior and type safety used by
+* this library.
+*
+* Importing this class from this module ensures that
+* the additional type definitions and helpers provided
+* by this library are available.
+*
+* ----------------------------------------------------------------
+*
+* @example
+* ```ts
+* import { CliCommand } from "@rzl-zone/build-tools/commander-kit";
+*
+* const program = new CliCommand();
+*
+* program
+*   .name("my-cli")
+*   .description("Example CLI program");
+*
+* program.parse();
+* ```
+*/
+declare class CliCommand extends Command {
+  /** ----------------------------------------------------------------
+  * * ***Create a new CLI command instance.***
+  * ----------------------------------------------------------------
+  *
+  * @param name Optional command name.
+  *
+  * If the provided value is not a non-empty string,
+  * the command will be created without an explicit name.
+  */
+  constructor(name?: string);
+  /** Set or disable the command usage string.
+  *
+  * This overrides the default usage generated from the command
+  * metadata (such as the command name, arguments, and options).
+  *
+  * - Passing a **non-empty string** sets a custom usage value.
+  * - Passing **`false`** disables usage output entirely for this
+  *   command (including help and error rendering when supported
+  *   by the CLI framework integration).
+  *
+  * An **empty string is not allowed** and will cause a configuration
+  * error to be thrown.
+  *
+  * @param str A non-empty custom usage string, or `false`
+  * to disable usage output.
+  *
+  * @returns The current command instance for chaining.
+  *
+  * @throws Thrown if the provided usage value is an empty string or
+  * not a valid non-empty string.
+  *
+  * @example
+  * program.usage("build [options]");
+  *
+  * @example
+  * program.usage(false);
+  */
+  override usage(str: string | false): this;
+  /** Get the resolved command usage string.
+  *
+  * If a custom usage was previously set using {@link Command.usage | `usage`},
+  * that value will be returned. Otherwise the usage string
+  * generated by Commander will be returned.
+  *
+  * @returns The current usage string for this command.
+  */
+  override usage(): string;
+  /** Set or disable the program version.
+  *
+  * This method configures the version value for the CLI program and
+  * automatically registers the `"-v, --version"` flag which prints
+  * the version when invoked.
+  *
+  * Behavior depends on the value passed:
+  *
+  * - Passing a **non-empty string** sets the program version.
+  * - Passing **`false`** disables the version flag entirely.
+  *
+  * When providing custom `flags` or `description`, they must also be
+  * **non-empty strings**.
+  *
+  * An **empty string is not allowed** and will cause a configuration
+  * error to be thrown.
+  *
+  * @param str A non-empty version string, or `false` to disable
+  * the version flag.
+  *
+  * @param flags Optional custom version flags (e.g. `"-V, --version"`).
+  *
+  * @param description Optional description for the version flag.
+  *
+  * @returns The current program instance for chaining.
+  *
+  * @throws Thrown if `str`, `flags`, or `description` are provided
+  * as empty strings or invalid values.
+  *
+  * @example
+  * program.version("1.0.0");
+  *
+  * @example
+  * program.version("1.0.0", "-V, --version", "print version");
+  *
+  * @example
+  * program.version(false);
+  */
+  override version(str: string, flags?: string, description?: string): this;
+  /** Set or disable the program version.
+  *
+  * This method configures the version value for the CLI program and
+  * automatically registers the `"-v, --version"` flag which prints
+  * the version when invoked.
+  *
+  * Behavior depends on the value passed:
+  *
+  * - Passing a **non-empty string** sets the program version.
+  * - Passing **`false`** disables the version flag entirely.
+  *
+  * When providing custom `flags` or `description`, they must also be
+  * **non-empty strings**.
+  *
+  * An **empty string is not allowed** and will cause a configuration
+  * error to be thrown.
+  *
+  * @param str A non-empty version string, or `false` to disable
+  * the version flag.
+  *
+  * @param flags Optional custom version flags (e.g. `"-V, --version"`).
+  *
+  * @param description Optional description for the version flag.
+  *
+  * @returns The current program instance for chaining.
+  *
+  * @throws Thrown if `str`, `flags`, or `description` are provided
+  * as empty strings or invalid values.
+  *
+  * @example
+  * program.version("1.0.0");
+  *
+  * @example
+  * program.version("1.0.0", "-V, --version", "print version");
+  *
+  * @example
+  * program.version(false);
+  */
+  override version(str: false): this;
+  /** Set or disable the program version.
+  *
+  * This method configures the version value for the CLI program and
+  * automatically registers the `"-v, --version"` flag which prints
+  * the version when invoked.
+  *
+  * Behavior depends on the value passed:
+  *
+  * - Passing a **non-empty string** sets the program version.
+  * - Passing **`false`** disables the version flag entirely.
+  *
+  * When providing custom `flags` or `description`, they must also be
+  * **non-empty strings**.
+  *
+  * An **empty string is not allowed** and will cause a configuration
+  * error to be thrown.
+  *
+  * @param str A non-empty version string, or `false` to disable
+  * the version flag.
+  *
+  * @param flags Optional custom version flags (e.g. `"-V, --version"`).
+  *
+  * @param description Optional description for the version flag.
+  *
+  * @returns The current program instance for chaining.
+  *
+  * @throws Thrown if `str`, `flags`, or `description` are provided
+  * as empty strings or invalid values.
+  *
+  * @example
+  * program.version("1.0.0");
+  *
+  * @example
+  * program.version("1.0.0", "-V, --version", "print version");
+  *
+  * @example
+  * program.version(false);
+  */
+  override version(str: false, flags?: never): this;
+  /** Set or disable the program version.
+  *
+  * This method configures the version value for the CLI program and
+  * automatically registers the `"-v, --version"` flag which prints
+  * the version when invoked.
+  *
+  * Behavior depends on the value passed:
+  *
+  * - Passing a **non-empty string** sets the program version.
+  * - Passing **`false`** disables the version flag entirely.
+  *
+  * When providing custom `flags` or `description`, they must also be
+  * **non-empty strings**.
+  *
+  * An **empty string is not allowed** and will cause a configuration
+  * error to be thrown.
+  *
+  * @param str A non-empty version string, or `false` to disable
+  * the version flag.
+  *
+  * @param flags Optional custom version flags (e.g. `"-V, --version"`).
+  *
+  * @param description Optional description for the version flag.
+  *
+  * @returns The current program instance for chaining.
+  *
+  * @throws Thrown if `str`, `flags`, or `description` are provided
+  * as empty strings or invalid values.
+  *
+  * @example
+  * program.version("1.0.0");
+  *
+  * @example
+  * program.version("1.0.0", "-V, --version", "print version");
+  *
+  * @example
+  * program.version(false);
+  */
+  override version(str: false, flags?: never, description?: never): this;
+  /** Get the program version.
+  *
+  * Returns the currently configured version string.
+  *
+  * If the version was disabled using {@link Command.version | `version(false)`},
+  * this method returns `undefined`.
+  *
+  * @returns The current program version string if set.
+  */
+  override version(): string | undefined;
+}
+/** ----------------------------------------------------------------
+* * ***Internal base program implementation.***
+* ----------------------------------------------------------------
+*
+* Internal extension of {@link CliCommand | `CliCommand`}
+* used by {@link createBaseProgram | `createBaseProgram()`}.
+*
+* This class stores additional internal state required
+* for UI formatting, version injection, and command
+* lifecycle behavior.
+*/
+declare class CommandBaseProgram extends CliCommand {
+  constructor(name?: string);
+  override createCommand(name?: string): CommandBaseProgram;
+}
+/** ----------------------------------------------------------------
+* * ***Configuration options for `createBaseProgram()`.***
+* ----------------------------------------------------------------
+*
+* Defines the bootstrap configuration used when creating
+* a pre-configured Commander program instance.
+*
+* - ***This type supports:***
+*      - direct property overrides.
+*      - centralized configuration via
+*        {@link CommandIdentity | `CommandIdentity`}.
+*      - optional CLI UI customization.
+*
+* ----------------------------------------------------------------
+* #### Resolution Priority.
+* ----------------------------------------------------------------
+*
+* When both explicit fields and `commandIdentity` are provided,
+* values are resolved in the following order:
+*
+*  * `explicit option` ➔ {@link CreateBaseProgramOptions.commandIdentity |`commandIdentity`} ➔ `internal defaults`.
+*
+* This ensures predictable override behavior.
+*
+* ----------------------------------------------------------------
+*/
+type CreateBaseProgramOptions = {
+  /** ----------------------------------------------------------------
+  * * ***CLI program name.***
+  * ----------------------------------------------------------------
+  *
+  * Name assigned to the Commander instance.
+  *
+  * Overrides {@link CommandIdentity.commandName | `commandIdentity.commandName`} when provided.
+  *
+  * ----------------------------------------------------------------
+  */
+  cliName?: string;
+  /** ----------------------------------------------------------------
+  * * ***Package name.***
+  * ----------------------------------------------------------------
+  *
+  * Package name displayed in the version description.
+  *
+  * Overrides {@link CommandIdentity.packageName | `commandIdentity.packageName`} when provided.
+  *
+  * Defaults to the internally resolved package name
+  * when omitted.
+  *
+  * ----------------------------------------------------------------
+  */
+  packageName?: string;
+  /** ----------------------------------------------------------------
+  * * ***Package version.***
+  * ----------------------------------------------------------------
+  *
+  * Version string passed to {@link CliCommand.version `.version()`}.
+  *
+  * Overrides {@link CommandIdentity.version | `commandIdentity.version`} when provided.
+  *
+  * Defaults to the internally resolved package version
+  * when omitted.
+  *
+  * ----------------------------------------------------------------
+  */
+  packageVersion?: string;
+  /** ----------------------------------------------------------------
+  * * ***Commander UI configuration.***
+  * ----------------------------------------------------------------
+  *
+  * Inline UI configuration via `ui` option.
+  *
+  * UI initialization is resolved using the following priority:
+  *
+  * 1. When `ui.usage` is defined,
+  *    full UI customization is triggered and strict validation is enforced.
+  *
+  * 2. Otherwise, if {@link CommandIdentity | `commandIdentity`} is provided,
+  *    UI is initialized using the identity title.
+  *
+  * 3. Otherwise, if `ui.title` is defined and valid,
+  *    UI is initialized using the provided title only.
+  *
+  * When full UI customization is triggered (case #1),
+  * the following validations are enforced:
+  *
+  * - The UI object must be non-null.
+  * - `title` must be a non-empty string when provided.
+  * - `usage` must be a non-empty string when provided.
+  *
+  * In partial initialization cases (#2 and #3),
+  * usage falls back to {@link CliCommand | `CliCommand`} default resolution.
+  *
+  * @note
+  * ⚠️ If validation fails, a structured configuration error may be thrown.
+  *
+  * ----------------------------------------------------------------
+  */
+  ui?: CommanderUiOptions;
+  /** ----------------------------------------------------------------
+  * * ***Command identity source.***
+  * ----------------------------------------------------------------
+  *
+  * Optional {@link CommandIdentity | `CommandIdentity`} instance used as a centralized
+  * configuration source for:
+  *
+  * - Command name.
+  * - Package name.
+  * - Version metadata.
+  *
+  * When provided, this identity may also participate in UI initialization.
+  *
+  * If full UI configuration is not supplied via `ui`,
+  * the identity title may be used to bootstrap
+  * {@link applyCommanderUi | `applyCommanderUi()`}.
+  *
+  * This reduces the need for manual property mapping
+  * and provides a consistent identity-driven configuration pattern.
+  *
+  * @throws {TypeError}
+  * Thrown if the provided value is not an instance of
+  * {@link CommandIdentity | `CommandIdentity`}.
+  *
+  * ----------------------------------------------------------------
+  */
+  commandIdentity?: CommandIdentity;
+};
+/** ----------------------------------------------------------------
+* * ***Creates a pre-configured Commander.js program instance.***
+* ----------------------------------------------------------------
+*
+* Factory function that returns a fresh {@link CliCommand | `CliCommand`} instance
+* with shared base configuration applied.
+*
+* - *This helper centralizes common CLI setup to ensure:*
+*    - Consistent version formatting.
+*    - Standardized exit behavior.
+*    - No shared mutable state between entry points.
+*
+* The returned {@link CliCommand | `CliCommand`} instance is stateful and fully mutable.
+*
+* *Additional configuration (including UI customization) may be applied after creation.*
+*
+* ----------------------------------------------------------------
+* #### Configuration Resolution.
+* ----------------------------------------------------------------
+*
+* When both explicit options and {@link CommandIdentity | `CommandIdentity`} are provided,
+* values are resolved using the following priority:
+*
+*  * `explicit option` ➔ `commandIdentity` ➔ `internal defaults`.
+*
+* This allows granular overrides while still supporting
+* {@link CommandIdentity | `CommandIdentity`} as a single source of truth.
+*
+* ----------------------------------------------------------------
+* #### UI Configuration.
+* ----------------------------------------------------------------
+*
+* UI customization can be applied using two approaches:
+*
+* 1. Inline via the `ui` option.
+*      - During initialization, {@link applyCommanderUi | `applyCommanderUi()`}
+*        may be invoked automatically using the following priority:
+*         - Full UI override when `options.ui.usage` is defined.
+*         - Fallback to {@link CommandIdentity | `commandIdentity`} when provided.
+*         - Fallback to `options.ui.title` when provided or valid.
+*
+*      - In partial initialization cases, usage falls back to
+*        {@link CliCommand | `CliCommand`} default resolution.
+*
+* 2. Manually after creation.
+*      - You may call {@link applyCommanderUi | `applyCommanderUi()`}
+*      explicitly to override or apply custom UI behavior.
+*
+*      - Calling {@link applyCommanderUi | `applyCommanderUi()`} manually after initialization will
+*        override any previously applied UI configuration.
+*
+* ----------------------------------------------------------------
+*
+* @param options Optional bootstrap configuration.
+*
+* @returns A configured {@link CliCommand | `CliCommand`} instance with version,
+* exit override, and optional UI behavior applied.
+*
+* ----------------------------------------------------------------
+* @example
+*
+* **Using commandIdentity as primary source ***(recommended)***:**
+*
+* ```ts
+* import { joinInline, picocolors } from "@rzl-zone/build-tools/utils";
+* import { createBaseProgram, CommandIdentity } from "@rzl-zone/build-tools/utils/server";
+*
+* const identity = new CommandIdentity({
+*   defaultCommandName: "my-command-cli"
+* })
+*   // override to your-package-name, e.g:
+*   .setPackageName("your-package-name")
+*   // override to your-package-version, e.g:
+*   .setVersion("1.1.1");
+*
+* const program = createBaseProgram({
+*   commandIdentity: identity,
+*   ui: {
+*     title: identity.cli(),
+*     usage: joinInline(
+*       picocolors.cyan(identity.commandName),
+*       picocolors.gray("<glob...>"),
+*       picocolors.blueBright("[options]")
+*     )
+*   }
+* });
+*
+* program.parse();
+* ```
+* ----------------------------------------------------------------
+* @example
+*
+* **Automatic UI configuration ***(manual mapping)***:**
+*
+* ```ts
+* import { joinInline, picocolors } from "@rzl-zone/build-tools/utils";
+* import { createBaseProgram, CommandIdentity } from "@rzl-zone/build-tools/utils/server";
+*
+* const commandTitle = new CommandIdentity({
+*   defaultCommandName: "clean-js-build-artifacts"
+* })
+*   // override to your-package-name, e.g:
+*   .setPackageName("your-package-name")
+*   // override to your-package-version, e.g:
+*   .setVersion("1.1.1");
+*
+* const program = createBaseProgram({
+*   cliName: commandTitle.commandName,
+*   packageName: commandTitle.packageName,
+*   packageVersion: commandTitle.version,
+*   ui: {
+*     title: commandTitle.cli(),
+*     usage: joinInline(
+*       picocolors.cyan(commandTitle.commandName),
+*       picocolors.gray("<glob...>"),
+*       picocolors.blueBright("[options]")
+*     )
+*   }
+* });
+*
+* program.parse();
+* ```
+* ----------------------------------------------------------------
+* @example
+*
+* **Manual UI override after creation:**
+*
+* ```ts
+* import { joinInline, picocolors } from "@rzl-zone/build-tools/utils";
+* import { createBaseProgram, CommandIdentity } from "@rzl-zone/build-tools/utils/server";
+*
+* const identity = new CommandIdentity({
+*   defaultCommandName: "my-command-cli"
+* });
+*
+* const baseProgram = createBaseProgram({
+*   commandIdentity: identity
+* });
+*
+* const program = applyCommanderUi(baseProgram, {
+*   title: identity.cli(),
+*   usage: joinInline(
+*     picocolors.cyan(identity.commandName),
+*     picocolors.gray("<glob...>"),
+*     picocolors.blueBright("[options]")
+*   )
+* });
+*
+* program.parse();
+* ```
+* ----------------------------------------------------------------
+*/
+declare function createBaseProgram(options?: CreateBaseProgramOptions): CommandBaseProgram;
+/** ----------------------------------------------------------------
+* * ***Commander UI options.***
+* ----------------------------------------------------------------
+*
+* Configuration object consumed by {@link applyCommanderUi | `applyCommanderUi()`}.
+*
+* Both `title`, `usage`, `packageName`, and `version` are optional at the type level, but
+* at runtime, values must be non-empty strings to be considered valid if provided.
+*
+* If either field is missing or fails the non-empty string constraint,
+* UI customization will be ignored silently and default.
+*
+* No runtime error is thrown for invalid values to preserve CLI execution flow.
+*/
+type CommanderUiOptions = {
+  /** ----------------------------------------------------------------
+  * * ***UI title.***
+  * ----------------------------------------------------------------
+  *
+  * Title displayed in the CLI header output.
+  *
+  * Must be a non-empty string when provided, otherwise will return default.
+  *
+  * ----------------------------------------------------------------
+  */
+  title?: string;
+  /** ----------------------------------------------------------------
+  * * ***Usage description.***
+  * ----------------------------------------------------------------
+  *
+  * Usage information displayed in the help output, this optional, but when
+  * provided, the value must be a non-empty string.
+  *
+  * - *If omitted or invalid, the usage string is resolved using the following priority:*
+  *    1. A manually defined {@link CliCommand.usage | `.usage()`} override (if any),
+  *    2. Commander’s default usage resolution behavior.
+  * ----------------------------------------------------------------
+  * @note
+  * Calling {@link CliCommand.usage | `.usage("")`} or with empty-string, is treated as an invalid
+  * override and will throw a configuration error.
+  */
+  usage?: string;
+  /** ----------------------------------------------------------------
+  * * ***Package version.***
+  * ----------------------------------------------------------------
+  *
+  * Usage information displayed in the version package output, this
+  * property is optional, but when provided, the value must be a
+  * non-empty string.
+  *
+  * - *If omitted or invalid, the version string is resolved using the
+  *   following priority:*
+  *      1. A manually defined {@link CliCommand.version | `.version()`} override (if any).
+  *      2. Defaults to the internally resolved package version.
+  *
+  * ----------------------------------------------------------------
+  * #### ⚠️ Behavior Scope.
+  * ----------------------------------------------------------------
+  *
+  * This property is **ONLY RESPECTED** when using a native Commander
+  * instance (i.e., created directly via `new Command()` or an imported `program` singleton).
+  *
+  * If the program instance is created via `createBaseProgram()`,
+  * this property is intentionally ignored, since version resolution
+  * is fully managed by the base program factory lifecycle.
+  *
+  * ----------------------------------------------------------------
+  * @note
+  * Calling {@link CliCommand.version | `.version("")`} or providing an
+  * empty string is treated as an invalid override and will throw a
+  * configuration error.
+  */
+  version?: string;
+  /** ----------------------------------------------------------------
+  * * ***Package name.***
+  * ----------------------------------------------------------------
+  *
+  * Package name displayed as part of the CLI version output, when version
+  * information is printed, this value is rendered alongside the version string.
+  *
+  * This property is optional, but when provided,
+  * the value must be a non-empty string.
+  *
+  * *If omitted or invalid, the package name string is resolved using the
+  * defaults internally resolved package name.*
+  *
+  * ----------------------------------------------------------------
+  * #### ⚠️ Behavior Scope.
+  * ----------------------------------------------------------------
+  *
+  * This property is **ONLY RESPECTED** when using a native Commander
+  * instance (i.e., created directly via `new Command()` or an imported `program` singleton).
+  *
+  * If the program instance is created via `createBaseProgram()`,
+  * this property is intentionally ignored, since `packageName` resolution
+  * is fully managed by the base program factory lifecycle.
+  */
+  packageName?: string;
+};
+/** ----------------------------------------------------------------
+* * ***Commander Error Code.***
+* ----------------------------------------------------------------
+*
+* Union type representing known error codes emitted by
+* {@link CommanderError | `CommanderError`} instances.
+*
+* The union includes all standard error identifiers produced by
+* Commander during command parsing, validation, and execution.
+*
+* The type also allows additional string values through
+* {@link AnyString | `AnyString`} to support custom error codes
+* defined by integrations, plugins, or higher-level frameworks.
+*
+* ----------------------------------------------------------------
+* #### Purpose
+* ----------------------------------------------------------------
+*
+* - Provides autocomplete for built-in Commander error codes.
+* - Enables safer error handling logic.
+* - Allows custom framework-specific error codes without
+*   restricting the type to a closed union.
+*
+* ----------------------------------------------------------------
+*/
+type CommanderErrorCode = "commander.help" | "commander.helpDisplayed" | "commander.version" | "commander.executeSubCommandAsync" | "commander.invalidArgument" | "commander.error" | "commander.missingArgument" | "commander.optionMissingArgument" | "commander.missingMandatoryOptionValue" | "commander.conflictingOption" | "commander.unknownOption" | "commander.excessArguments" | "commander.unknownCommand" | AnyString;
+/** ----------------------------------------------------------------
+* * ***Typed Commander Error.***
+* ----------------------------------------------------------------
+*
+* Strongly-typed variant of {@link CommanderError | `CommanderError`}
+* with a refined `code` property.
+*
+* This type replaces the original `string`-based `code` field with
+* {@link CommanderErrorCode | `CommanderErrorCode`}, providing
+* improved type safety and autocomplete when working with
+* Commander error handling logic.
+*
+* The error code union includes all known Commander error identifiers
+* while still allowing additional custom string codes defined by
+* integrations or higher-level frameworks.
+*
+* ----------------------------------------------------------------
+* #### Purpose
+* ----------------------------------------------------------------
+*
+* - Provides autocomplete for standard Commander error codes.
+* - Improves type safety when inspecting `CommanderError` values.
+* - Allows custom error codes without restricting extensibility.
+*
+* This type is typically used when intercepting, transforming,
+* or re-throwing errors emitted by Commander.
+*
+* ----------------------------------------------------------------
+*/
+type TypedCommanderError = Omit<CommanderError, "code"> & {
+  /** Typed Commander error identifier. */code: CommanderErrorCode;
+};
+/** ----------------------------------------------------------------
+* * ***Command Execution Context Type.***
+* ----------------------------------------------------------------
+*
+* Alias type representing the runtime command instance used as
+* the execution context during command handling.
+*
+* This abstraction standardizes command typing across the codebase
+* while avoiding tight coupling to a specific Commander class.
+*
+* The type includes all supported command-like instances used by
+* the framework:
+*
+* - {@link CliCommand | `CliCommand`}
+* - {@link Command | `Command`}
+* - {@link CommandBaseProgram | `CommandBaseProgram`}
+*
+* These values represent **instantiated command objects**
+* (for example `new Command()`), not constructor types.
+*
+* ----------------------------------------------------------------
+*
+* #### Purpose
+*
+* - Provides a common command instance type for utilities.
+* - Improves semantic clarity in function signatures.
+* - Avoids repeating union types across the codebase.
+*/
+type CommandContext = CliCommand | Command | CommandBaseProgram;
+/** ------------------------------------------------------------------------
+* * Runtime type guard for {@link CommanderError | `CommanderError`}.
+* ------------------------------------------------------------------------
+*
+* Determines whether a given unknown value is an instance of
+* {@link CommanderError | `CommanderError`} and **narrows the `code` property** to the
+* library-specific {@link CommanderErrorCode | `CommanderErrorCode`} union type.
+*
+* This helper exists because the upstream Commander type defines
+* `CommanderError.code` as a plain `string`.
+*
+* As a result, TypeScript cannot automatically infer the narrowed error code type when using
+* `instanceof CommanderError`.
+*
+* By using this guard, consumers can safely treat the error as a
+* `CommanderError` with a strongly typed `code` value.
+*
+* ------------------------------------------------------------------------
+* #### Behavior
+* ------------------------------------------------------------------------
+*
+* - Returns **`true`** if `err` is an instance of {@link CommanderError | `CommanderError`}.
+* - When `true`, the value is narrowed to:
+*    `CommanderError & { code: CommanderErrorCode }`
+*
+* - Returns **`false`** for all other values.
+*
+* This enables safe access to `err.code` with the expected
+* {@link CommanderErrorCode | `CommanderErrorCode`} union type.
+*
+* ------------------------------------------------------------------------
+* @param err - The value to test.
+*
+* @returns `true` if the value is a {@link CommanderError | `CommanderError`}; otherwise `false`.
+*
+* ------------------------------------------------------------------------
+* @example
+* ```ts
+* try {
+*   program.parse();
+* } catch (err) {
+*   if (isCommanderError(err)) {
+*     // err.code is now typed as CommanderErrorCode
+*     return err.code;
+*   }
+*
+*   console.error(String(err));
+*   process.exit(1);
+* }
+* ```
+*/
+declare function isCommanderError(err: unknown): err is TypedCommanderError;
+/** ------------------------------------------------------------------------
+* * Formats a Commander error into a human-readable message.
+* ------------------------------------------------------------------------
+*
+* Converts an unknown error value into a formatted CLI-friendly
+* message string.
+*
+* If the value is a {@link CommanderError | `CommanderError`}, the message is extracted
+* directly from the error instance. Otherwise, the value is converted
+* to a string representation.
+*
+* This helper is typically used when rendering CLI error output before
+* terminating the process.
+*
+* ------------------------------------------------------------------------
+* #### Behavior
+* ------------------------------------------------------------------------
+*
+* - If the value is a {@link CommanderError | `CommanderError`}, returns `err.message`.
+* - Otherwise returns `String(err)`.
+*
+* ------------------------------------------------------------------------
+* @param err - The error value to format.
+*
+* @returns A human-readable message string.
+*
+* ------------------------------------------------------------------------
+* @example
+* ```ts
+* console.error(formatCommanderError(err));
+* process.exit(1);
+* ```
+*/
+declare function formatCommanderError(err: unknown): string;
+/** ------------------------------------------------------------------------
+* * Extracts the Commander error code from an unknown value.
+* ------------------------------------------------------------------------
+*
+* Safely resolves the {@link CommanderErrorCode | `CommanderErrorCode`} from a value that may
+* or may not be a {@link CommanderError | `CommanderError`}.
+*
+* This helper is useful when handling errors originating from the
+* Commander CLI runtime, where the error code indicates the type of
+* internal CLI condition (for example help display or version output).
+*
+* If the provided value is not a {@link CommanderError | `CommanderError`}, `null`
+* is returned.
+*
+* ------------------------------------------------------------------------
+* #### Behavior
+* ------------------------------------------------------------------------
+*
+* - Returns the narrowed {@link CommanderErrorCode | `CommanderErrorCode`} if the value is a
+*   {@link CommanderError | `CommanderError`}.
+* - Returns `null` for all other values.
+*
+* ------------------------------------------------------------------------
+* @param err - The value to inspect.
+*
+* @returns The resolved {@link CommanderErrorCode | `CommanderErrorCode`}, or `null`
+* if the value is not a {@link CommanderError | `CommanderError`}.
+*
+* ------------------------------------------------------------------------
+* @example
+* ```ts
+* const code = getCommanderErrorCode(err);
+*
+* if (code) {
+*   return code;
+* }
+* ```
+*/
+declare function getCommanderErrorCode(err: unknown): CommanderErrorCode | null;
+/** ----------------------------------------------------------------
+* * ***Centralized exit handler for Commander.js ({@link CliCommand.exitOverride | `exitOverride`}).***
+* ----------------------------------------------------------------
+*
+* Handles all process termination logic when using Commander’s {@link CliCommand.exitOverride | `.exitOverride()`}  method.
+*
+* This helper normalizes Commander’s exception-based control flow
+* into predictable and user-friendly CLI behavior.
+*
+* ----------------------------------------------------------------
+* - *Behavior:*
+*     - Exits the process with code `0` when:
+*        - Commander triggers `helpDisplayed`.
+*        - Commander triggers `version`.
+*     - Prints error messages for real CLI or runtime failures.
+*     - Ensures correct and consistent exit codes.
+* ----------------------------------------------------------------
+* - *This prevents:*
+*     - Duplicate output (e.g. version printed twice).
+*     - Treating help/version as fatal errors.
+*     - Copy-pasted exit logic across multiple CLI entry points.
+* ----------------------------------------------------------------
+* - ⚠️ **Important:**
+*     - This function **always terminates the process**.
+*     - Intended to be passed directly into `program.exitOverride`.
+*     - Should NOT be used outside a CLI execution context.
+* ----------------------------------------------------------------
+*
+* @param err - The error object thrown by Commander or runtime logic.
+*
+* ----------------------------------------------------------------
+* @example
+* Using existing commander program instance:
+* ```ts
+* import { Command, program } from "commander"
+*
+* program.exitOverride(handleCommanderExit);
+* program.parse(process.argv);
+* ```
+*
+* @example
+* Using manually created command instance:
+* ```ts
+* import { Command } from "commander"
+*
+* const cmd = new Command();
+* cmd.exitOverride(handleCommanderExit);
+* cmd.parse(process.argv);
+* ```
+* @example
+* Using factory helper:
+* ```ts
+* import { createBaseProgram } from "@rzl-zone/build-tools/commander-kit";
+*
+* // Recommended usage (factory pattern)
+* const program = createBaseProgram();
+* program.parse(process.argv);
+* ```
+*/
+declare function handleCommanderExit(err: unknown): never;
+/** ------------------------------------------------------------------------
+* * Applies a structured UI layer to a Commander.js program instance.
+* ------------------------------------------------------------------------
+*
+* Enhances a Commander program by installing a standardized UI layer
+* for error rendering and presentation formatting.
+*
+* This function is primarily intended for native
+* {@link Command | `Command`} instances created directly
+* from Commander (e.g. `new Command()` or an imported `program` singleton).
+*
+* Programs created via
+* {@link createBaseProgram | `createBaseProgram()`}
+* already include the structured UI layer by default, in such cases, calling
+* this function is typically unnecessary and **redundant interception** also
+* is **not recommended**.
+*
+* ------------------------------------------------------------------------
+* #### Supported Program Types.
+* ------------------------------------------------------------------------
+*
+* **1.** Factory-based:
+*  ```ts
+*    import {
+*      applyCommanderUi,
+*      createBaseProgram
+*    } from "@rzl-zone/build-tools/commander-kit";
+*
+*    const programFactory = createBaseProgram();
+*    const program = applyCommanderUi(programFactory);
+*  ```
+*
+* **2.** Native Commander instance:
+*  ```ts
+*    import { Command } from "commander"
+*    import { applyCommanderUi } from "@rzl-zone/build-tools/commander-kit";
+*
+*    const nativeProgram = new Command();
+*    const program = applyCommanderUi(nativeProgram);
+*  ```
+*
+* When used with {@link createBaseProgram | `createBaseProgram`}, certain
+* interception steps are skipped because the factory already installs baseline
+* behavior and internal state wiring.
+*
+* When used with a plain {@link Command | `Command`} instance created directly
+* from Commander (e.g. `new Command()` or an imported `program` singleton), this
+* function installs all required interception and metadata tracking layers.
+*
+* - *In short:*
+*       - Programs created via `createBaseProgram()` already include
+*         foundational behavior.
+*       - Native Commander instances are fully instrumented by this function.
+*
+* ------------------------------------------------------------------------
+* #### Factory Integration.
+* ------------------------------------------------------------------------
+*
+* Programs created via {@link createBaseProgram | `createBaseProgram()`}
+* already include the structured UI layer by default.
+*
+* In such cases, calling `applyCommanderUi()` manually is unnecessary
+* and generally not recommended.
+*
+* - ***The factory installs:***
+*       - Internal state wiring.
+*       - Error interception.
+*       - Help customization.
+*       - Version handling lifecycle.
+*
+* ***`applyCommanderUi()` primarily exists to instrument native
+* {@link Command | `Command`}, or {@link CliCommand | `CliCommand`}
+* instances that were not created through the factory.***
+*
+* If the program instance was created via **`createBaseProgram()`**,
+* the **UI layer** is **already installed**, **reapplying** this function may
+* result in **redundant interception** and is **not recommended**.
+*
+* ------------------------------------------------------------------------
+* #### Installed UI Layer.
+* ------------------------------------------------------------------------
+*
+* This function standardizes:
+*
+* - Error message formatting.
+* - Header rendering.
+* - Usage resolution.
+* - Help hint presentation.
+* - Version interception.
+*
+* The goal is to provide a consistent, styled CLI output surface
+* independent of Commander’s default formatting.
+*
+* ------------------------------------------------------------------------
+* #### Internal Mutations.
+* ------------------------------------------------------------------------
+*
+* This function performs the following mutations on the provided
+* `program` instance:
+*
+* - Overrides `.error()`.
+* - Installs `.exitOverride()`.
+* - Replaces `.createHelp()`.
+* - Intercepts manual:
+*    - `.usage()` calls.
+*    - `.helpOption()` calls.
+*    - `.version()` calls.
+*
+* These interceptions allow internal metadata tracking without
+* relying on Commander private properties.
+*
+* ------------------------------------------------------------------------
+* #### Usage Resolution Order.
+* ------------------------------------------------------------------------
+*
+* When rendering usage inside error output, the value is resolved
+* in the following priority:
+*
+*   1. Manual `.usage()` override (intercepted internally).
+*   2. UI `options.usage`.
+*   3. Commander default usage string.
+*
+* ------------------------------------------------------------------------
+* #### ℹ️ Help Hint Handling.
+* ------------------------------------------------------------------------
+*
+* If `.helpOption(false)` is used, the help hint line
+* (`Run -h, --help`) will not be displayed.
+*
+* Help metadata is internally tracked and does not depend on
+* Commander private state.
+*
+* ------------------------------------------------------------------------
+* #### ⚠️ Important Behavior Notes.
+* ------------------------------------------------------------------------
+*
+* - This function **mutates** the provided program instance.
+* - It replaces Commander’s default error handler.
+* - The process exits with code `1` after rendering an error.
+* - The function is not strictly idempotent and should only be
+*   applied once per program instance.
+*
+* ------------------------------------------------------------------------
+*
+* @param program - A Commander program instance, this can be either:
+* - A program created via {@link createBaseProgram | `createBaseProgram`}, or
+* - A native {@link Command | `Command`}, or {@link CliCommand | `CliCommand`} instance (e.g. `new Command()`. `new CliCommand()` or an imported `program`/`cliProgram` singleton).
+*
+* @param options - Optional UI configuration.
+*
+* @throws {ConfigurationError}
+* Thrown when `program` is not a valid Commander program instance.
+*
+* ------------------------------------------------------------------------
+*
+* @example
+* Using a native Commander instance (manual installation required):
+* ```ts
+* import { Command } from "commander"
+* import { applyCommanderUi } from "@rzl-zone/build-tools/commander-kit";
+*
+* const nativeProgram = new Command();
+*
+* const program = applyCommanderUi(nativeProgram, {
+*   title: "Custom CLI",
+*   version: "1.1.0",
+*   packageName: "my-package-name"
+* });
+*
+* program.parse();
+* ```
+*
+* @example
+* Using the factory (UI layer already installed):
+* ```ts
+* import { createBaseProgram } from "@rzl-zone/build-tools/commander-kit";
+*
+* const program = createBaseProgram({
+*   commandIdentity: identity,
+*   ui: {
+*     title: "My CLI Tool",
+*     usage: "my-cli <command> [options]"
+*   }
+* });
+*
+* program.parse();
+* ```
+*
+* @example
+* Manual usage override takes priority:
+* ```ts
+* import { CliCommand, applyCommanderUi } from "@rzl-zone/build-tools/commander-kit";
+*
+* const programCli = new CliCommand();
+*
+* programCli
+*   .name("my-cli")
+*   .usage("<input> [options]");
+*
+* // Apply default UI helpers
+* const program = applyCommanderUi(programCli, {
+*   usage: "fallback usage (will NOT be used)",
+* });
+*
+* // Rendered usage will be:
+* // my-cli <input> [options]
+*
+* // In this case the manual `.usage()` call defined before
+* // `applyCommanderUi()` takes precedence.
+*
+* // The usage string provided to `applyCommanderUi()` will
+* // be ignored if a custom usage has already been configured.
+* ```
+*
+* @example
+* Disable help hint line:
+* ```ts
+* import { Command } from "commander"
+* import { applyCommanderUi } from "@rzl-zone/build-tools/commander-kit";
+*
+* const nativeProgram = new Command();
+*
+* const program = applyCommanderUi(nativeProgram);
+*
+* program.helpOption(false);
+* // Disables the help option and prevents the "Run -h, --help" hint
+* // from appearing in error messages.
+*
+* program.version(false);
+* // Disables the version command automatically configured by
+* // `applyCommanderUi()` or `createBaseProgram()`.
+* ```
+*
+* @example
+* Minimal setup for native Commander:
+* ```ts
+* import { Command } from "commander"
+* import { applyCommanderUi } from "@rzl-zone/build-tools/commander-kit";
+*
+* const nativeProgram = new Command();
+* const program = applyCommanderUi(nativeProgram);
+*
+* program.parse();
+* ```
+*/
+declare function applyCommanderUi(program: CommandBaseProgram, options: CommanderUiOptions): CommandBaseProgram;
+declare function applyCommanderUi(program: CliCommand | Command, options: CommanderUiOptions): CliCommand;
+declare function applyCommanderUi(program: unknown, options: CommanderUiOptions): never;
+/** ----------------------------------------------------------------
+* * ***Command-line argument definition class.***
+* ----------------------------------------------------------------
+*
+* Represents a positional CLI argument definition.
+*
+* This class extends Commander’s {@link Argument | **`Argument`**}
+* and is provided to ensure compatibility with the
+* additional types and utilities exposed by this library.
+*/
+declare class CliArgument extends Argument {
+  constructor(arg: string, description?: string);
+}
+/** ----------------------------------------------------------------
+* * ***Commander help system class.***
+* ----------------------------------------------------------------
+*
+* Extends Commander’s {@link Help | **`Help`**} class
+* and allows customization of CLI help output,
+* formatting behavior, and command listing.
+*
+* This class can be used to override the default
+* help renderer used by {@link CliCommand | `CliCommand`}.
+*/
+declare class CliHelp extends Help {
+  constructor();
+}
+/** ----------------------------------------------------------------
+* * ***Command-line option definition class.***
+* ----------------------------------------------------------------
+*
+* Represents a CLI option or flag definition.
+*
+* This class extends Commander’s {@link Option | **`Option`**}
+* and provides the standard option behavior used
+* by {@link CliCommand | `CliCommand`}.
+*
+* - ***Supports:***
+*       - short and long flags.
+*       - default values.
+*       - variadic arguments.
+*       - custom parsing logic.
+*/
+declare class CliOption extends Option {
+  constructor(arg: string, description?: string);
+}
+/** ----------------------------------------------------------------
+* * ***Default CLI program instance.***
+* ----------------------------------------------------------------
+*
+* Shared CLI program instance created from
+* {@link CliCommand | **`CliCommand`**}.
+*
+* This module-level singleton provides a convenient
+* default program object for simple CLI tools without
+* manually creating a command instance.
+*
+* ----------------------------------------------------------------
+*
+* Equivalent to:
+*
+* ```ts
+* import { CliCommand } from "@rzl-zone/build-tools/commander-kit";
+*
+* const cliProgram = new CliCommand();
+* ```
+*/
+declare const cliProgram: CliCommand;
+/** ----------------------------------------------------------------
+* * ***Commander base error class.***
+* ----------------------------------------------------------------
+*
+* Base error thrown internally by Commander when CLI
+* parsing or execution fails.
+*/
+declare class CliCommanderError extends CommanderError {
+  constructor(exitCode: number, code: CommanderErrorCode, message: string);
+}
+/** ----------------------------------------------------------------
+* * ***Error thrown when an argument fails validation.***
+* ----------------------------------------------------------------
+*/
+declare class CliInvalidArgumentError extends InvalidArgumentError {
+  constructor(message: string);
+}
+/** ----------------------------------------------------------------
+* * ***Error thrown when an option argument fails validation.***
+* ----------------------------------------------------------------
+*/
+declare class CliInvalidOptionArgumentError extends InvalidOptionArgumentError {
+  constructor(message: string);
+}
+/** ----------------------------------------------------------------
+* * ***CLI Argument Factory.***
+* ----------------------------------------------------------------
+*
+* Creates a new {@link CliArgument | **`CliArgument`**} instance.
+*
+* This helper constructs a CLI argument definition compatible with
+* Commander argument parsing while providing a consistent creation
+* entry point within the framework.
+*
+* @param name Argument definition string (e.g. `<file>` or `[dir]`).
+* @param description Optional argument description used in help output.
+*
+* @returns A newly created {@link CliArgument | **`CliArgument`**} instance.
+*/
+declare const cliCreateArgument: (name: string, description?: string) => CliArgument;
+/** ----------------------------------------------------------------
+* * ***CLI Command Factory.***
+* ----------------------------------------------------------------
+*
+* Creates a new {@link CliCommand | **`CliCommand`**} instance.
+*
+* This helper acts as a small factory for constructing command
+* objects used by the CLI framework. It ensures all commands are
+* created through the same entry point, which allows future
+* extensions (such as internal metadata attachment or lifecycle
+* hooks) without changing call sites.
+*
+* @param name Optional command name.
+*
+* @returns A newly created {@link CliCommand | **`CliCommand`**} instance.
+*/
+declare const cliCreateCommand: (name?: string) => CliCommand;
+/** ----------------------------------------------------------------
+* * ***CLI Option Factory.***
+* ----------------------------------------------------------------
+*
+* Creates a new {@link CliOption | **`CliOption`**} instance.
+*
+* This helper constructs a CLI option definition compatible with
+* Commander option parsing while ensuring a consistent factory
+* entry point for option creation within the framework.
+*
+* @param arg Option flags definition
+* (e.g. `"-p, --port <number>"`).
+*
+* @param description Optional description displayed in help output.
+*
+* @returns A newly created {@link CliOption | **`CliOption`**} instance.
+*/
+declare const cliCreateOption: (arg: string, description?: string) => CliOption;
+/** ----------------------------------------------------------------
+* * ***Context object provided when injecting custom help text.***
+* ----------------------------------------------------------------
+*/
+interface CliAddHelpTextContext extends AddHelpTextContext {}
+/** ----------------------------------------------------------------
+* * ***Position where custom help text should be injected.***
+* ----------------------------------------------------------------
+*/
+type CliAddHelpTextPosition = AddHelpTextPosition;
+/** ----------------------------------------------------------------
+* * ***Configuration options for a CLI command.***
+* ----------------------------------------------------------------
+*/
+interface CliCommandOptions extends CommandOptions {}
+/** ----------------------------------------------------------------
+* * ***Additional options attached to Commander errors.***
+* ----------------------------------------------------------------
+*/
+interface CliErrorOptions extends ErrorOptions {}
+/** ----------------------------------------------------------------
+* * ***Configuration for executable subcommands.***
+* ----------------------------------------------------------------
+*/
+interface CliExecutableCommandOptions extends ExecutableCommandOptions {}
+/** ----------------------------------------------------------------
+* * ***Configuration options for the Commander help system.***
+* ----------------------------------------------------------------
+*/
+type CliHelpConfiguration = HelpConfiguration;
+/** ----------------------------------------------------------------
+* * ***Context information available during help rendering.***
+* ----------------------------------------------------------------
+*/
+interface CliHelpContext extends HelpContext {}
+/** ----------------------------------------------------------------
+* * ***Lifecycle hook event names supported by Commander.***
+* ----------------------------------------------------------------
+*/
+type CliHookEvent = HookEvent;
+/** ----------------------------------------------------------------
+* * ***Indicates where an option value originated from.***
+* ----------------------------------------------------------------
+*/
+type CliOptionValueSource = OptionValueSource;
+/** ----------------------------------------------------------------
+* * ***Resolved option values object.***
+* ----------------------------------------------------------------
+*/
+type CliOptionValues = OptionValues;
+/** ----------------------------------------------------------------
+* * ***Configuration controlling Commander output behavior.***
+* ----------------------------------------------------------------
+*/
+interface CliOutputConfiguration extends OutputConfiguration {}
+/** ----------------------------------------------------------------
+* * ***Options controlling the parsing behavior.***
+* ----------------------------------------------------------------
+*/
+interface CliParseOptions extends ParseOptions {}
+/** ----------------------------------------------------------------
+* * ***Result object returned when parsing arguments manually.***
+* ----------------------------------------------------------------
+*/
+interface CliParseOptionsResult extends ParseOptionsResult {}
+export { type CliAddHelpTextContext, type CliAddHelpTextPosition, CliArgument, CliCommand, type CliCommandOptions, CliCommanderError, type CliErrorOptions, type CliExecutableCommandOptions, CliHelp, type CliHelpConfiguration, type CliHelpContext, type CliHookEvent, CliInvalidArgumentError, CliInvalidOptionArgumentError, CliOption, type CliOptionValueSource, type CliOptionValues, type CliOutputConfiguration, type CliParseOptions, type CliParseOptionsResult, type CommandContext, CommandIdentity, type CommanderErrorCode, type CommanderUiOptions, type CreateBaseProgramOptions, type TypedCommanderError, applyCommanderUi, cliCreateArgument, cliCreateCommand, cliCreateOption, cliProgram, createBaseProgram, formatCommanderError, getCommanderErrorCode, handleCommanderExit, isCommanderError };
+//# sourceMappingURL=index.d.ts.map