@rzl-zone/build-tools 0.0.8 → 0.0.10

package/dist/commander-kit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["DESCRIPTIONS","FLAGS","FLAGS","DESCRIPTIONS","FLAGS"],"sources":["../../src/commander-kit/errors/isCommanderError.ts","../../src/commander-kit/errors/format-commander-error.ts","../../src/commander-kit/errors/get-commander-error-code.ts","../../src/commander-kit/core/command.ts","../../src/commander-kit/lifecycle/handle-commander-exit.ts","../../src/utils/helper/class-check.ts","../../src/commander-kit/core/help.ts","../../src/commander-kit/core/option.ts","../../src/_internal/utils/symbol/index.ts","../../src/commander-kit/_internal/state.ts","../../src/commander-kit/_internal/helpers/usages.ts","../../src/commander-kit/_internal/help/styled-help.ts","../../src/commander-kit/_internal/helpers/error-formatters.ts","../../src/commander-kit/_internal/interceptor/usage.ts","../../src/commander-kit/constants/index.ts","../../src/commander-kit/_internal/interceptor/help.ts","../../src/commander-kit/_internal/interceptor/version.ts","../../src/commander-kit/core/argument.ts","../../src/commander-kit/_internal/helpers/versions.ts","../../src/commander-kit/_internal/helpers/base-program.ts","../../src/commander-kit/_internal/interceptor/install-parse-version.ts","../../src/commander-kit/factories/create-base-program.ts","../../src/commander-kit/_internal/helpers/apply-commander-ui.ts","../../src/commander-kit/ui/apply-commander-ui.ts","../../src/commander-kit/core/program.ts","../../src/commander-kit/errors/cli/commander-error.ts","../../src/commander-kit/errors/cli/invalid-argument-error.ts","../../src/commander-kit/errors/cli/invalid-option-argument-error.ts","../../src/commander-kit/factories/create-argument.ts","../../src/commander-kit/factories/create-command.ts","../../src/commander-kit/factories/create-option.ts"],"sourcesContent":["import type { TypedCommanderError } from \"@/commander-kit/types\";\n\nimport { CommanderError } from \"commander\";\n\n/** ------------------------------------------------------------------------\n * * Runtime type guard for {@link CommanderError | `CommanderError`}.\n * ------------------------------------------------------------------------\n *\n * Determines whether a given unknown value is an instance of\n * {@link CommanderError | `CommanderError`} and **narrows the `code` property** to the\n * library-specific {@link CommanderErrorCode | `CommanderErrorCode`} union type.\n *\n * This helper exists because the upstream Commander type defines\n * `CommanderError.code` as a plain `string`.\n *\n * As a result, TypeScript cannot automatically infer the narrowed error code type when using\n * `instanceof CommanderError`.\n *\n * By using this guard, consumers can safely treat the error as a\n * `CommanderError` with a strongly typed `code` value.\n *\n * ------------------------------------------------------------------------\n * #### Behavior\n * ------------------------------------------------------------------------\n *\n * - Returns **`true`** if `err` is an instance of {@link CommanderError | `CommanderError`}.\n * - When `true`, the value is narrowed to:\n *    `CommanderError & { code: CommanderErrorCode }`\n *\n * - Returns **`false`** for all other values.\n *\n * This enables safe access to `err.code` with the expected\n * {@link CommanderErrorCode | `CommanderErrorCode`} union type.\n *\n * ------------------------------------------------------------------------\n * @param err - The value to test.\n *\n * @returns `true` if the value is a {@link CommanderError | `CommanderError`}; otherwise `false`.\n *\n * ------------------------------------------------------------------------\n * @example\n * ```ts\n * try {\n *   program.parse();\n * } catch (err) {\n *   if (isCommanderError(err)) {\n *     // err.code is now typed as CommanderErrorCode\n *     return err.code;\n *   }\n *\n *   console.error(String(err));\n *   process.exit(1);\n * }\n * ```\n */\nexport function isCommanderError(err: unknown): err is TypedCommanderError {\n  return err instanceof CommanderError;\n}\n\n/** @deprecated */\nexport type CommanderErrorInstanceType = CommanderError;\n","import { CommanderError } from \"commander\";\n\n/** ------------------------------------------------------------------------\n * * Formats a Commander error into a human-readable message.\n * ------------------------------------------------------------------------\n *\n * Converts an unknown error value into a formatted CLI-friendly\n * message string.\n *\n * If the value is a {@link CommanderError | `CommanderError`}, the message is extracted\n * directly from the error instance. Otherwise, the value is converted\n * to a string representation.\n *\n * This helper is typically used when rendering CLI error output before\n * terminating the process.\n *\n * ------------------------------------------------------------------------\n * #### Behavior\n * ------------------------------------------------------------------------\n *\n * - If the value is a {@link CommanderError | `CommanderError`}, returns `err.message`.\n * - Otherwise returns `String(err)`.\n *\n * ------------------------------------------------------------------------\n * @param err - The error value to format.\n *\n * @returns A human-readable message string.\n *\n * ------------------------------------------------------------------------\n * @example\n * ```ts\n * console.error(formatCommanderError(err));\n * process.exit(1);\n * ```\n */\nexport function formatCommanderError(err: unknown): string {\n  if (err instanceof CommanderError) return err.message;\n\n  return String(err);\n}\n","import type { CommanderErrorCode } from \"@/commander-kit/types\";\n\nimport { CommanderError } from \"commander\";\n\n/** ------------------------------------------------------------------------\n * * Extracts the Commander error code from an unknown value.\n * ------------------------------------------------------------------------\n *\n * Safely resolves the {@link CommanderErrorCode | `CommanderErrorCode`} from a value that may\n * or may not be a {@link CommanderError | `CommanderError`}.\n *\n * This helper is useful when handling errors originating from the\n * Commander CLI runtime, where the error code indicates the type of\n * internal CLI condition (for example help display or version output).\n *\n * If the provided value is not a {@link CommanderError | `CommanderError`}, `null`\n * is returned.\n *\n * ------------------------------------------------------------------------\n * #### Behavior\n * ------------------------------------------------------------------------\n *\n * - Returns the narrowed {@link CommanderErrorCode | `CommanderErrorCode`} if the value is a\n *   {@link CommanderError | `CommanderError`}.\n * - Returns `null` for all other values.\n *\n * ------------------------------------------------------------------------\n * @param err - The value to inspect.\n *\n * @returns The resolved {@link CommanderErrorCode | `CommanderErrorCode`}, or `null`\n * if the value is not a {@link CommanderError | `CommanderError`}.\n *\n * ------------------------------------------------------------------------\n * @example\n * ```ts\n * const code = getCommanderErrorCode(err);\n *\n * if (code) {\n *   return code;\n * }\n * ```\n */\nexport function getCommanderErrorCode(err: unknown): CommanderErrorCode | null {\n  if (err instanceof CommanderError) return err.code;\n\n  return null;\n}\n","import { Command } from \"commander\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\n/** ----------------------------------------------------------------\n * * ***CLI command definition class.***\n * ----------------------------------------------------------------\n *\n * Primary building block used to define CLI programs and\n * subcommands.\n *\n * This class extends Commander’s {@link Command | **`Command`**} class and\n * adds additional behavior and type safety used by\n * this library.\n *\n * Importing this class from this module ensures that\n * the additional type definitions and helpers provided\n * by this library are available.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * import { CliCommand } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const program = new CliCommand();\n *\n * program\n *   .name(\"my-cli\")\n *   .description(\"Example CLI program\");\n *\n * program.parse();\n * ```\n */\nexport class CliCommand extends Command {\n  /** ----------------------------------------------------------------\n   * * ***Create a new CLI command instance.***\n   * ----------------------------------------------------------------\n   *\n   * @param name Optional command name.\n   *\n   * If the provided value is not a non-empty string,\n   * the command will be created without an explicit name.\n   */\n  constructor(name?: string) {\n    name = isNonEmptyString(name) ? name : undefined;\n    super(name);\n  }\n\n  /** Set or disable the command usage string.\n   *\n   * This overrides the default usage generated from the command\n   * metadata (such as the command name, arguments, and options).\n   *\n   * - Passing a **non-empty string** sets a custom usage value.\n   * - Passing **`false`** disables usage output entirely for this\n   *   command (including help and error rendering when supported\n   *   by the CLI framework integration).\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty custom usage string, or `false`\n   * to disable usage output.\n   *\n   * @returns The current command instance for chaining.\n   *\n   * @throws Thrown if the provided usage value is an empty string or\n   * not a valid non-empty string.\n   *\n   * @example\n   * program.usage(\"build [options]\");\n   *\n   * @example\n   * program.usage(false);\n   */\n  override usage(str: string | false): this;\n  /** Get the resolved command usage string.\n   *\n   * If a custom usage was previously set using {@link Command.usage | `usage`},\n   * that value will be returned. Otherwise the usage string\n   * generated by Commander will be returned.\n   *\n   * @returns The current usage string for this command.\n   */\n  override usage(): string;\n  override usage(str?: string | false): this | string {\n    if (str === false) {\n      super.usage(\"\");\n      return this;\n    }\n\n    if (!isNonEmptyString(str)) {\n      return super.usage();\n    }\n\n    return super.usage(str);\n  }\n\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: string, flags?: string, description?: string): this;\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: false): this;\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: false, flags?: never): this;\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: false, flags?: never, description?: never): this;\n  /** Get the program version.\n   *\n   * Returns the currently configured version string.\n   *\n   * If the version was disabled using {@link Command.version | `version(false)`},\n   * this method returns `undefined`.\n   *\n   * @returns The current program version string if set.\n   */\n  override version(): string | undefined;\n  override version(str?: string | false, flags?: string, description?: string) {\n    if (str === false) {\n      super.version(\"\");\n      return this;\n    }\n\n    if (!isNonEmptyString(str)) {\n      return super.version();\n    }\n\n    return super.version(str, flags, description);\n  }\n}\n","import \"@rzl-zone/node-only\";\n\nimport { CliCommand } from \"../core/command\";\nimport { isCommanderError } from \"../errors/isCommanderError\";\n\n/** ----------------------------------------------------------------\n * * ***Centralized exit handler for Commander.js ({@link CliCommand.exitOverride | `exitOverride`}).***\n * ----------------------------------------------------------------\n *\n * Handles all process termination logic when using Commander’s {@link CliCommand.exitOverride | `.exitOverride()`}  method.\n *\n * This helper normalizes Commander’s exception-based control flow\n * into predictable and user-friendly CLI behavior.\n *\n * ----------------------------------------------------------------\n * - *Behavior:*\n *     - Exits the process with code `0` when:\n *        - Commander triggers `helpDisplayed`.\n *        - Commander triggers `version`.\n *     - Prints error messages for real CLI or runtime failures.\n *     - Ensures correct and consistent exit codes.\n * ----------------------------------------------------------------\n * - *This prevents:*\n *     - Duplicate output (e.g. version printed twice).\n *     - Treating help/version as fatal errors.\n *     - Copy-pasted exit logic across multiple CLI entry points.\n * ----------------------------------------------------------------\n * - ⚠️ **Important:**\n *     - This function **always terminates the process**.\n *     - Intended to be passed directly into `program.exitOverride`.\n *     - Should NOT be used outside a CLI execution context.\n * ----------------------------------------------------------------\n *\n * @param err - The error object thrown by Commander or runtime logic.\n *\n * ----------------------------------------------------------------\n * @example\n * Using existing commander program instance:\n * ```ts\n * import { Command, program } from \"commander\"\n *\n * program.exitOverride(handleCommanderExit);\n * program.parse(process.argv);\n * ```\n *\n * @example\n * Using manually created command instance:\n * ```ts\n * import { Command } from \"commander\"\n *\n * const cmd = new Command();\n * cmd.exitOverride(handleCommanderExit);\n * cmd.parse(process.argv);\n * ```\n * @example\n * Using factory helper:\n * ```ts\n * import { createBaseProgram } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * // Recommended usage (factory pattern)\n * const program = createBaseProgram();\n * program.parse(process.argv);\n * ```\n */\nexport function handleCommanderExit(err: unknown): never {\n  // Commander or runtime error\n  if (isCommanderError(err)) {\n    const code = err.code;\n\n    // Non-error exits (help / version)\n    if (code === \"commander.helpDisplayed\" || code === \"commander.version\") {\n      process.exit(0);\n    }\n\n    // console.error(err.message);\n    process.exit(err.exitCode ?? 1);\n  }\n\n  // Unknown thrown value\n  console.error(err);\n  process.exit(1);\n}\n\n/** @deprecated Used for `tsDoc` only. */\nexport type CliCommandInstance = CliCommand;\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** -------------------------------------------------------\n * * ***Utility Type: `AnyConstructor`.***\n * -------------------------------------------------------\n *\n * Represents any constructable type (class or abstract class).\n *\n * This type matches values that can be invoked with `new`\n * and produce an instance of type `T`.\n *\n * - ***Behavior summary:***\n *       - Supports concrete classes.\n *       - Supports abstract classes.\n *       - Does NOT match non-constructable functions.\n *\n * ----------------------------------------------------------------\n *\n * @template T - The instance type produced by the constructor.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * class A {}\n * abstract class B {}\n *\n * type C1 = AnyConstructor<A>;\n * type C2 = AnyConstructor<B>;\n *\n * function create<T>(ctor: AnyConstructor<T>): T {\n *   return new ctor();\n * }\n * ```\n */\ntype AnyConstructor<T = any> = abstract new (...args: any[]) => T;\n\n/** -------------------------------------------------------\n * * ***Utility Type: `ConcreteConstructor`.***\n * -------------------------------------------------------\n *\n * Represents a concrete constructable type (class constructor).\n *\n * This type matches values that can be invoked with `new`\n * and produce an instance of type `T`.\n *\n * - ***Behavior summary:***\n *       - Supports standard class constructors.\n *       - Does NOT include abstract constructors.\n *       - Does NOT match non-constructable functions.\n *\n * ----------------------------------------------------------------\n *\n * @template T - The instance type produced by the constructor.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * class A {}\n *\n * function create<T>(ctor: ConcreteConstructor<T>): T {\n *   return new ctor();\n * }\n * ```\n */\ntype ConcreteConstructor<T = any> = new (...args: any[]) => T;\n\n/** ----------------------------------------------------------------\n * * ***Checks whether a value shares a prototype in its chain.***\n * ----------------------------------------------------------------\n *\n * Determines whether the prototype derived from `target`\n * exists anywhere within `value`'s prototype chain.\n *\n * This function performs a manual prototype-chain walk and\n * does NOT rely on native `instanceof`.\n *\n * - Ignores custom `Symbol.hasInstance` overrides.\n * - Uses strict reference equality (`===`) for comparison.\n * - Fully deterministic and unaffected by constructor property changes.\n *\n * ----------------------------------------------------------------\n * #### Supported Target Types:\n * ----------------------------------------------------------------\n * - Constructor functions ➔ uses `ctor.prototype`.\n * - Object instances      ➔ uses `Object.getPrototypeOf(target)`.\n *\n * If `target` itself has a null prototype\n * (e.g., `Object.create(null)`), the function returns `false`.\n *\n * ----------------------------------------------------------------\n * #### Important Behavior:\n * ----------------------------------------------------------------\n * - Primitive values (`string`, `number`, `boolean`, `symbol`,\n *   `bigint`, `null`, `undefined`) always return `false`.\n *\n * - Values with a null prototype (e.g., `Object.create(null)`)\n *   always return `false`.\n *\n * - Passing `{}` as `target` effectively checks for\n *   `Object.prototype` in the prototype chain.\n *\n * ----------------------------------------------------------------\n *\n * @param value  - The value whose prototype chain will be inspected.\n * @param target - A constructor or object whose derived prototype\n *                 will be searched for in `value`'s prototype chain.\n *\n * @returns `true` if the prototype derived from `target`\n * exists anywhere in `value`'s prototype chain.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A {}\n * class B extends A {}\n *\n * const b = new B();\n *\n * hasSamePrototype(b, A);         // ➔ true\n * hasSamePrototype(b, new A());   // ➔ true\n * hasSamePrototype(b, URL);       // ➔ false\n * hasSamePrototype(b, new URL()); // ➔ false\n *\n * // Matches Object.prototype\n * hasSamePrototype(b, {});        // ➔ true\n *\n * // Null-prototype object\n * const nullObj = Object.create(null);\n * hasSamePrototype(nullObj, {});  // ➔ false\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n * This check relies on strict prototype reference equality.\n *\n * Objects created in a different JavaScript realm\n * (e.g., iframe, VM context, worker) will NOT match,\n * even if they appear structurally identical.\n */\nexport function hasSamePrototype(\n  value: unknown,\n  target: object | AnyConstructor<any>\n): boolean {\n  //! Reject primitive values: prototype chains only exist on object-like entities\n  if (\n    value === null ||\n    (typeof value !== \"object\" && typeof value !== \"function\")\n  ) {\n    return false;\n  }\n\n  //todo: Normalize target prototype reference:\n  //? If function, use .prototype; if instance, use its direct prototype via Object.getPrototypeOf.\n  const targetProto =\n    typeof target === \"function\"\n      ? target.prototype\n      : Object.getPrototypeOf(target);\n\n  //! Safety guard: If target has no prototype (e.g., Object.create(null)), match is impossible\n  if (!targetProto) return false;\n\n  //? Initial Step: Access the immediate prototype of the input value\n  let proto = Object.getPrototypeOf(value);\n\n  //todo: Traversal Loop: Walk the prototype chain until the end (null) is reached\n  while (proto !== null) {\n    //? Identity Match: Check if the current prototype in the chain strictly equals the target prototype\n    if (proto === targetProto) return true;\n\n    //todo: Link Propagation: Move upward to the next parent prototype in the inheritance hierarchy\n    //todo: This effectively performs a manual recursive search without using the stack.\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  //? Termination: The entire chain was exhausted without finding a reference match\n  return false;\n}\n\n/** ----------------------------------------------------------------\n * * ***Deterministic alternative to `instanceof`.***\n * ----------------------------------------------------------------\n *\n * Checks whether `ctor.prototype` exists anywhere in\n * `value`'s prototype chain.\n *\n * - ***Unlike native `instanceof`, this implementation:***\n *       - Does NOT use `instanceof`.\n *       - Ignores `Symbol.hasInstance`.\n *       - Cannot be affected by overriding Symbol.hasInstance.\n *\n * - ***Subclasses are allowed.***\n *\n * - Values with a null prototype (e.g., `Object.create(null)`) will\n * always return false.\n *\n * ----------------------------------------------------------------\n *\n * @param value - The value to test.\n * @param ctor - The constructor to compare against.\n *\n * @returns `true` if `value` is an instance of `ctor`\n * or any subclass of it.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A extends Error {}\n * class B extends A {}\n *\n * const b = new B();\n *\n * isInstanceOf(b, A); // ➔ true\n * isInstanceOf(b, B); // ➔ true\n * isInstanceOf(b, Error); // ➔ true\n * isInstanceOf(b, URL); // ➔ false\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *  This check relies on strict prototype reference equality.\n *\n *  Objects created in a different JavaScript realm\n *  (e.g., iframe, VM context, worker) will NOT match,\n *  even if they appear structurally identical.\n */\nexport function isInstanceOf<T>(\n  value: unknown,\n  ctor: AnyConstructor<T>\n): value is T {\n  //! Constraint: Primitives do not have prototype chains and cannot be instances\n  if (\n    value === null ||\n    (typeof value !== \"object\" && typeof value !== \"function\")\n  ) {\n    return false;\n  }\n\n  //? Initial Step: Access the immediate prototype of the instance\n  let proto = Object.getPrototypeOf(value);\n\n  //? Reference Point: Capture the constructor's prototype to search for in the chain also\n  //? take for ensures check is unaffected by Symbol.hasInstance overrides\n  const targetProto = ctor.prototype;\n\n  //todo: Traversal Loop: Walk the prototype chain manually to bypass Symbol.hasInstance overrides\n  while (proto !== null) {\n    //? Identity Match: Check if any link in the chain strictly equals the constructor's prototype\n    if (proto === targetProto) return true;\n\n    //todo: Link Propagation: Move upward to the next parent prototype in the inheritance hierarchy\n    //todo: This continues until a match is found or the chain terminates at null.\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  //? Termination: The target prototype was not found within the value's inheritance chain\n  return false;\n}\n\n/** ----------------------------------------------------------------\n * * ***Checks whether one constructor extends another.***\n * ----------------------------------------------------------------\n *\n * Determines whether `child` inherits from `parent`\n * by walking the prototype chain of `child.prototype`.\n *\n * This implementation is deterministic and does NOT rely\n * on `instanceof`.\n *\n * ----------------------------------------------------------------\n *\n * @param child - The derived constructor.\n * @param parent - The base constructor.\n *\n * @returns `true` if `child` extends `parent`.\n *\n * A constructor is NOT considered a subclass of itself.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A extends URL {}\n * class B extends A {}\n *\n * isSubclassOf(B, A); // ➔ true\n * isSubclassOf(B, URL); // ➔ true\n * isSubclassOf(A, B); // ➔ false\n * isSubclassOf(A, A); // ➔ false\n * isSubclassOf(B, B); // ➔ false\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *  This check relies on strict prototype reference equality.\n *\n *  Objects created in a different JavaScript realm\n *  (e.g., iframe, VM context, worker) will NOT match,\n *  even if they appear structurally identical.\n */\nexport function isSubclassOf<T, U>(\n  child: AnyConstructor<T>,\n  parent: AnyConstructor<U>\n): boolean {\n  //? Entry point: Start from the child constructor's prototype parent.\n  //? This ensures a constructor is NOT considered a subclass of itself.\n  let proto = Object.getPrototypeOf(child.prototype);\n\n  //todo: Inheritance Traversal: Walk the prototype chain to find the parent's prototype.\n  while (proto !== null) {\n    //? Inheritance Match: Check if the parent's prototype is an ancestor of the child's prototype.\n    if (proto === parent.prototype) return true;\n    //todo: Link Propagation: Move upward to the next parent prototype in the inheritance hierarchy.\n    //todo: This continues until a match is found or the chain terminates at null.\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  //? Termination: The parent prototype was not found in the child's inheritance chain.\n  return false;\n}\n\n/** ----------------------------------------------------------------\n * * ***Checks for an exact constructor match.***\n * ----------------------------------------------------------------\n *\n * Determines whether `value` was created directly by `ctor`.\n *\n * - ***Unlike `isInstanceOf`, this function:***\n *       - Does NOT allow subclasses.\n *       - Requires the immediate prototype of `value`\n *         to strictly equal `ctor.prototype`.\n *\n * - ***This check is deterministic and immune to:***\n *       - `Symbol.hasInstance`.\n *       - `.constructor` property manipulation.\n *\n * Values with a null prototype (e.g., `Object.create(null)`) will\n * always return false.\n *\n * ----------------------------------------------------------------\n *\n * @param value - The value to test.\n * @param ctor - The constructor to match exactly.\n *\n * @returns `true` if `value` is an exact instance of `ctor`.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A {}\n * class B extends A {}\n *\n * const b = new B();\n *\n * isExactInstanceOf(b, B); // ➔ true\n * isExactInstanceOf(b, A); // ➔ false\n *\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *  This check relies on strict prototype reference equality.\n *\n *  Objects created in a different JavaScript realm\n *  (e.g., iframe, VM context, worker) will NOT match,\n *  even if they appear structurally identical.\n */\nexport function isExactInstanceOf<T>(\n  value: unknown,\n  ctor: AnyConstructor<T>\n): value is T {\n  //! Constraint: Immediately reject primitives\n  if (\n    value === null ||\n    (typeof value !== \"object\" && typeof value !== \"function\")\n  ) {\n    return false;\n  }\n\n  //todo: Strict Direct Comparison: Verify if the immediate prototype is exactly the constructor's prototype.\n  //todo: This effectively ignores parent classes in the chain, preventing subclass matches.\n  return Object.getPrototypeOf(value) === ctor.prototype;\n}\n\n/** ----------------------------------------------------------------\n * * ***Checks whether a value is a class constructor.***\n * ----------------------------------------------------------------\n *\n * Determines whether the provided value is highly likely to be an\n * ES6 class constructor using multi-layer structural heuristics.\n *\n * - Uses `Function.prototype.toString` signature inspection.\n * - Validates prototype structural integrity.\n * - Supports native class constructors and standard class syntax.\n * ----------------------------------------------------------------\n * #### ⚠️ Important Behavior:\n * ----------------------------------------------------------------\n * - This function is a heuristic classifier, not a cryptographic or\n *   mathematically provable validator.\n *\n * - Runtime JavaScript does not provide a perfect mechanism to\n *   distinguish class constructors from function constructors.\n *\n * - Proxy-wrapped constructors or maliciously monkey-patched functions\n *   may bypass detection under adversarial environments.\n *\n * ----------------------------------------------------------------\n * #### Supported Class Forms:\n * ----------------------------------------------------------------\n * - Native ES6 class syntax:\n *   ```ts\n *      class A {}\n *   ```\n *\n * - Native built-in constructors:\n *    - `Map`.\n *    - `Set`.\n *    - `Error`.\n *    - `Promise`.\n *\n * - Transpiled class outputs (if structural signals remain intact).\n *\n * ----------------------------------------------------------------\n *\n * #### Detection Strategy Summary:\n *\n * - Checks function construct-ability.\n * - Inspects source signature via `Function.prototype.toString`.\n * - Validates prototype linkage consistency.\n * - Ensures constructor reflexive integrity.\n * - Verifies prototype descriptor identity.\n *\n * ----------------------------------------------------------------\n *\n * @param value - The value to be tested.\n *\n * @returns `true` if the value is likely a class constructor.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * class A {}\n * function B() {}\n *\n * isClass(A); // ➔ true\n * isClass(B); // ➔ false\n *\n * const arr = Array;\n * isClass(arr); // ➔ true (native constructor)\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *\n * This function is intended for runtime utility validation and should\n * not be used as the sole security boundary in adversarial systems.\n *\n * Objects created in different JavaScript realms (e.g., iframe,\n * worker, VM context) may not be detected even if structurally similar.\n */\n//? Overload 1: Preserve original type when variable type is already known\nexport function isClass<T>(value: T): value is T & ConcreteConstructor;\n//? Overload 2: For unknown/any input type\nexport function isClass(value: unknown): value is ConcreteConstructor;\n//? Implementation\nexport function isClass(value: unknown): boolean {\n  //! Requirement: Must be a function to even be a candidate for a constructor\n  if (typeof value !== \"function\") return false;\n\n  let fnStr: string;\n\n  //todo: Source Acquisition: Safely obtain the function's source code representation\n  try {\n    fnStr = Function.prototype.toString.call(value);\n  } catch {\n    //! Safety Guard: If toString fails (e.g. on certain Proxy types), reject immediately\n    return false;\n  }\n\n  //? Signature Detection: Look for explicit 'class' keyword or engine-level native signatures also\n  //? detect ES6 class syntax or native constructor signature\n  const isClassSyntax = /^class[\\s{]/.test(fnStr);\n  const isNative = fnStr.includes(\"[native code]\");\n\n  //! Logic Boundary: If it lacks both ES6 class syntax and native constructor markers, reject as regular function\n  //! also Reject ordinary functions that are not constructable class-like entities\n  if (!isClassSyntax && !isNative) return false;\n\n  //? Integrity Check: Every constructor must have a valid prototype object linkage\n  const proto = value.prototype;\n\n  //! Validity constructor must have valid prototype object\n  if (!proto || typeof proto !== \"object\") return false;\n\n  try {\n    //todo - Reflexive Integrity: Ensure the prototype has a 'constructor' property pointing back to itself\n    if (!Object.prototype.hasOwnProperty.call(proto, \"constructor\"))\n      return false;\n\n    //! Identity Verification: The back-reference must strictly equal the original function\n    if (proto.constructor !== value) return false;\n  } catch {\n    //! Panic Guard: Catch errors from potential 'poisoned' prototypes or proxy traps\n    return false;\n  }\n\n  //? Descriptor Validation: Retrieve the underlying property configuration for 'prototype' and structural integrity\n  const descriptor = Object.getOwnPropertyDescriptor(value, \"prototype\");\n\n  //! Reference Matching: Ensure the descriptor's value is the exact same object as the prototype link\n  if (!descriptor || descriptor.value !== proto) return false;\n\n  //! NOTE:\n  //! Native class constructors (e.g. Map, Set, Promise, Error)\n  //! may have non-writable prototype properties.\n  //!\n  //! Therefore, checking descriptor.value identity is sufficient\n  //! to confirm structural integrity without enforcing write-ability.\n  return true;\n}\n","import { Help } from \"commander\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { CliCommand } from \"./command\";\n\n/** ----------------------------------------------------------------\n * * ***Commander help system class.***\n * ----------------------------------------------------------------\n *\n * Extends Commander’s {@link Help | **`Help`**} class\n * and allows customization of CLI help output,\n * formatting behavior, and command listing.\n *\n * This class can be used to override the default\n * help renderer used by {@link CliCommand | `CliCommand`}.\n */\nexport class CliHelp extends Help {\n  constructor() {\n    super();\n  }\n}\n","import { Option } from \"commander\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { CliCommand } from \"./command\";\n\n/** ----------------------------------------------------------------\n * * ***Command-line option definition class.***\n * ----------------------------------------------------------------\n *\n * Represents a CLI option or flag definition.\n *\n * This class extends Commander’s {@link Option | **`Option`**}\n * and provides the standard option behavior used\n * by {@link CliCommand | `CliCommand`}.\n *\n * - ***Supports:***\n *       - short and long flags.\n *       - default values.\n *       - variadic arguments.\n *       - custom parsing logic.\n */\nexport class CliOption extends Option {\n  constructor(arg: string, description?: string) {\n    super(arg, description);\n  }\n}\n","import type { SymbolRegistry, SymbolSafeConstructor } from \"./types\";\n\nconst hasSymbolConstructor =\n  typeof Symbol === \"function\" &&\n  typeof Symbol(\"x\") === \"symbol\" &&\n  typeof Symbol.for === \"function\" &&\n  typeof Symbol.keyFor === \"function\";\n\n/** ------------------------------------------------------------------------\n * * Global registry key used to store fallback symbol mappings.\n * ------------------------------------------------------------------------\n *\n * In environments where native `Symbol.for()` is unavailable,\n * a shared registry object is attached to the global scope.\n *\n * This constant represents the property name used to store that\n * registry on the global object.\n *\n * The registry ensures that multiple calls to `SymbolSafe.for(key)`\n * return the same value across modules.\n *\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nconst REGISTRY_KEY = \"__rzl_global_symbol_registry__\";\n\n/** ------------------------------------------------------------------------\n * * Resolves the current global execution context.\n * ------------------------------------------------------------------------\n *\n * Returns a reference to the global object regardless of runtime\n * environment.\n *\n * This helper supports multiple JavaScript environments:\n *\n * - `globalThis` (modern standard)\n * - `self` (Web Workers)\n * - `window` (browsers)\n * - `global` (Node.js)\n *\n * If none are available, a new object is returned as a fallback.\n *\n * ------------------------------------------------------------------------\n *\n * @returns The detected global object.\n *\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction getGlobal(): any {\n  if (typeof globalThis !== \"undefined\") return globalThis;\n  if (typeof self !== \"undefined\") return self;\n  if (typeof window !== \"undefined\") return window;\n  if (typeof global !== \"undefined\") return global;\n  return {};\n}\n\n/** ------------------------------------------------------------------------\n * * Generates a pseudo-unique identifier.\n * ------------------------------------------------------------------------\n *\n * Creates a collision-resistant identifier used internally when\n * generating fallback symbol-like keys in environments without\n * native `Symbol` support.\n *\n * The identifier combines:\n *\n * - two randomized base36 segments\n * - a timestamp component\n *\n * This ensures a sufficiently unique value for runtime property keys.\n *\n * ------------------------------------------------------------------------\n *\n * @returns A pseudo-unique identifier string.\n *\n * @internal\n */\nfunction createUID() {\n  return (\n    Math.random().toString(36).slice(2) +\n    Math.random().toString(36).slice(2) +\n    Date.now().toString(36)\n  );\n}\n\n/** ------------------------------------------------------------------------\n * * Creates a unique symbol-like key.\n * ------------------------------------------------------------------------\n *\n * Generates a **unique property key** similar to `Symbol(description)`.\n *\n * Runtime behavior depends on environment support:\n *\n * **Modern environments**\n * - Delegates to `Symbol(description)`.\n *\n * **Legacy environments (ES5)**\n * - Returns a unique string identifier in the format:\n *\n * ```\n * `@@rzl/local/<description>/<unique-id>`\n * ```\n *\n * Each invocation returns a **distinct value**.\n *\n * ------------------------------------------------------------------------\n *\n * @param desc - Optional symbol description used for debugging.\n *\n * @returns A unique `PropertyKey`.\n *\n * @internal\n */\nfunction createLocalSymbol(desc?: string | number) {\n  if (hasSymbolConstructor) {\n    return Symbol(desc);\n  }\n\n  return \"@@rzl/local/\" + (desc ?? \"\") + \"/\" + createUID();\n}\n\n/** ------------------------------------------------------------------------\n * * Resolves or creates a global symbol-like key.\n * ------------------------------------------------------------------------\n *\n * Provides behavior equivalent to `Symbol.for(key)`.\n *\n * Runtime strategy:\n *\n * **Modern environments**\n * - Delegates directly to `Symbol.for(key)`.\n *\n * **Legacy environments**\n * - Uses a shared registry stored on the global object.\n * - The registry ensures stable key reuse across modules.\n *\n * Fallback format:\n *\n * ```\n * `@@rzl/global/<key>/<unique-id>`\n * ```\n *\n * Subsequent calls with the same `key` return the same value.\n *\n * ------------------------------------------------------------------------\n *\n * @param key - Global registry identifier.\n *\n * @returns A stable `PropertyKey`.\n *\n * @internal\n */\nfunction createGlobalSymbol(key: string) {\n  if (hasSymbolConstructor) {\n    return Symbol.for(key);\n  }\n\n  const registry = getRegistry();\n\n  if (registry.byKey[key]) {\n    return registry.byKey[key] as unknown as symbol;\n  }\n  const value = \"@@rzl/global/\" + key + \"/\" + createUID();\n\n  registry.byKey[key] = value;\n  registry.byValue.set(value, key);\n\n  return value as unknown as symbol;\n}\n\n/** ------------------------------------------------------------------------\n * * Retrieves or initializes the global symbol registry store.\n * ------------------------------------------------------------------------\n *\n * The registry is stored on the global execution context and is used to\n * maintain stable mappings between registry keys and symbol-like property\n * values.\n *\n * Registry Structure:\n *\n * ```ts\n * interface SymbolRegistry {\n *   byKey: Record<string, PropertyKey>;\n *   byValue: Map<PropertyKey, string>;\n * }\n * ```\n *\n * - `byKey`\n *     - Maps registry identifier strings ➔ generated property keys.\n *     - Enables O(1) lookup when resolving global symbols by name.\n *\n * - `byValue`\n *     - Reverse mapping from property key ➔ registry identifier.\n *     - Enables O(1) implementation of `keyFor()`-style resolution.\n *\n * Behavior:\n *\n * - If the registry does not exist on the global object, it will be\n *   initialized automatically.\n *\n * - The registry is shared across modules within the same runtime\n *   context.\n *\n * - The registry uses `Object.create(null)` to avoid prototype pollution\n *   and accidental key shadowing.\n *\n * ------------------------------------------------------------------------\n *\n * @returns\n * The global symbol registry instance.\n *\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nfunction getRegistry() {\n  const g = getGlobal();\n\n  if (!g[REGISTRY_KEY]) {\n    g[REGISTRY_KEY] = {\n      byKey: Object.create(null),\n      byValue: new Map()\n    } as SymbolRegistry;\n  }\n\n  return g[REGISTRY_KEY] as SymbolRegistry;\n}\n\n/** ------------------------------------------------------------------------\n * * ***SymbolSafe runtime implementation.***\n * ------------------------------------------------------------------------\n *\n * TypeScript identity preservation note:\n *\n * When using SymbolSafe, consumers may optionally apply self-referential\n * assertions to preserve symbol identity narrowing.\n *\n * Recommended pattern example:\n *\n * ```ts\n * const KEY: unique symbol = SymbolSafe(\"key\") as typeof KEY;\n * const MySimbol: unique symbol = SymbolSafe(\"my-symbol\") as typeof MySimbol;\n * const MyGlobalSimbol: unique symbol = SymbolSafe.for(\"my-global-symbol\") as typeof MyGlobalSimbol;\n * ```\n *\n * This pattern allows TypeScript to approximate native `Symbol` intrinsic\n * inference behavior for custom symbol factory functions.\n *\n * Usage of explicit `unique symbol` annotations is optional and should\n * only be used when strict identity narrowing is required.\n *\n * ------------------------------------------------------------------------\n *\n * The exported `SymbolSafe` object behaves like a function while exposing\n * the `for()` method for global registry access.\n *\n * This mirrors the behavior of the native `Symbol` API.\n *\n * ------------------------------------------------------------------------\n *\n * @example\n *\n * Creating unique symbol-like values\n *\n * ```ts\n * const INTERNAL: unique symbol = SymbolSafe(\"internal\") as typeof INTERNAL;\n *\n * const obj: Record<PropertyKey, unknown> = {};\n *\n * obj[INTERNAL] = { debug: true };\n *\n * console.log(obj[INTERNAL]);\n * ```\n *\n * ------------------------------------------------------------------------\n *\n * @example\n *\n * Using global registry symbols\n *\n * ```ts\n * const ROUTER_KEY: unique symbol = SymbolSafe.for(\"rzl:router.instance\") as typeof ROUTER_KEY;\n * const CACHE_KEY: unique symbol = SymbolSafe.for(\"rzl:cache.token\") as typeof CACHE_KEY;\n *\n * console.log(ROUTER_KEY === CACHE_KEY); // false\n *\n * const ROUTER_A: unique symbol = SymbolSafe.for(\"rzl:router.instance\") as typeof ROUTER_A;\n * const ROUTER_B: unique symbol = SymbolSafe.for(\"rzl:router.instance\") as typeof ROUTER_B;\n *\n * console.log(ROUTER_A === ROUTER_B); // true\n * ```\n *\n * ------------------------------------------------------------------------\n */\nexport const SymbolSafe: SymbolSafeConstructor = Object.assign(\n  function SymbolSafe(description?: string | number) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return createLocalSymbol(description) as any;\n  },\n  {\n    for(key: string) {\n      return createGlobalSymbol(key);\n    },\n\n    keyFor(sym: symbol) {\n      if (hasSymbolConstructor && typeof sym === \"symbol\") {\n        return Symbol.keyFor(sym);\n      }\n\n      const registry = getRegistry();\n      return registry.byValue.get(sym);\n    }\n  }\n);\n","// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { Command } from \"commander\";\n\nimport type {\n  CommandContext,\n  CommanderInternalState,\n  CommanderUiOptions\n} from \"@/commander-kit/types\";\nimport type { OmitStrict } from \"@/_internal/types/extra\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { applyCommanderUi } from \"@/commander-kit/ui/apply-commander-ui\";\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { createBaseProgram } from \"@/commander-kit/factories/create-base-program\";\n\nimport { SymbolSafe } from \"@/_internal/utils/symbol\";\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { CommandBaseProgram } from \"@/commander-kit/factories/create-base-program\";\n\n/** ------------------------------------------------------------------------\n * * Internal Commander state marker symbol.\n * ------------------------------------------------------------------------\n *\n * Unique symbol used to attach and retrieve internal metadata\n * from Commander program instances.\n *\n * This symbol serves as a hidden state key for native\n * {@link Command | `Command`} instances, allowing the library\n * to store internal lifecycle data without relying on\n * Commander private properties.\n *\n * For {@link createBaseProgram | `createBaseProgram()`} instances and {@link applyCommanderUi | `applyCommanderUi`},\n * internal state is managed directly by the factory and does not\n * rely on symbol attachment.\n *\n * ------------------------------------------------------------------------\n * #### **🔒 Visibility.**\n * ------------------------------------------------------------------------\n *\n * This symbol is strictly internal and is not part of the public API,\n * consumers must not access, mutate, or depend on it.\n *\n * ------------------------------------------------------------------------\n * @internal\n */\nexport const COMMANDER_INTERNAL_SYMBOL: unique symbol = SymbolSafe(\n  \"rzl-built-tools:commander.internal\"\n) as typeof COMMANDER_INTERNAL_SYMBOL;\n\n/** ------------------------------------------------------------------------\n * * Creates a fresh Commander internal state object.\n * ------------------------------------------------------------------------\n *\n * Generates a fully initialized internal state container used to\n * track UI configuration, help metadata, usage overrides,\n * and version interception flags.\n *\n * This state object is attached to a Commander instance\n * (either native or factory-based) and acts as the single source\n * of truth for runtime UI lifecycle behavior.\n *\n * ------------------------------------------------------------------------\n * #### State Responsibilities.\n * ------------------------------------------------------------------------\n *\n * The returned object stores:\n *\n * - UI configuration metadata.\n * - Help option interception data.\n * - Manual `.usage()` overrides.\n * - Version string overrides.\n * - Version injection flags.\n *\n * All properties are initialized to safe defaults.\n *\n * ------------------------------------------------------------------------\n *\n * @returns A fresh {@link CommanderInternalState | `CommanderInternalState`} object.\n *\n * @internal\n */\nexport function createDefaultInternalState() {\n  return {\n    ui: undefined,\n    help: undefined,\n    packageName: undefined,\n    manualUsage: undefined,\n    disableUsage: false,\n    versionMeta: undefined,\n    versionInjected: false,\n    versionDisable: false,\n    versionOriginal: undefined,\n    versionSetByUser: false\n  } satisfies CommanderInternalState;\n}\n\n/** ------------------------------------------------------------------------\n * * Resets and reinitializes a program's internal Commander state.\n * ------------------------------------------------------------------------\n *\n * Discards any existing internal metadata attached to the provided\n * program instance and replaces it with a newly created default state.\n *\n * This ensures a clean lifecycle baseline.\n *\n * ------------------------------------------------------------------------\n * #### Behavior.\n * ------------------------------------------------------------------------\n *\n * - If the program is a {@link CommandBaseProgram | `CommandBaseProgram`},\n *   the state is set via its internal setter.\n *\n * - If the program is a native {@link Command | `Command`},\n *   the state is attached using the internal symbol marker.\n *\n * The previous state (if any) is permanently discarded.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - A Commander program instance.\n * @returns The newly created internal state object.\n *\n * @internal\n */\nexport const resetAllCommandInternal = (\n  cmd: CommandContext\n): CommanderInternalState => {\n  const fresh = createDefaultInternalState();\n\n  // Factory program\n  if (\"_internalState\" in cmd && \"_setInternalState\" in cmd) {\n    cmd._setInternalState(fresh);\n    return fresh;\n  }\n\n  // Commander / CliCommand\n  cmd[COMMANDER_INTERNAL_SYMBOL] = fresh;\n\n  return fresh;\n};\n\n/** ------------------------------------------------------------------------\n * * Retrieves the internal Commander state for a program instance.\n * ------------------------------------------------------------------------\n *\n * Returns the internal state associated with the provided program.\n *\n * If no state is currently attached, a new one is created,\n * attached to the program, and returned automatically.\n *\n * This guarantees that a valid internal state object\n * is always returned.\n *\n * ------------------------------------------------------------------------\n * #### 🔄 Lazy Initialization.\n * ------------------------------------------------------------------------\n *\n * This function performs lazy state installation:\n *\n * - If a state exists ➔ it is returned as-is.\n * - If no state exists ➔ a new state is created and attached.\n *\n * This avoids reliance on Commander private internals\n * while ensuring consistent metadata tracking.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - A Commander program instance.\n * @returns The resolved {@link CommanderInternalState | `CommanderInternalState`}.\n *\n * @internal\n */\nexport function getInternalState(cmd: CommandContext): CommanderInternalState {\n  // Factory program\n  if (\"_internalState\" in cmd && \"_setInternalState\" in cmd) {\n    let state = cmd._internalState;\n\n    if (!state) {\n      state = resetAllCommandInternal(cmd);\n      cmd._setInternalState(state);\n    }\n\n    return state;\n  }\n\n  // Commander / CliCommand\n  if (!cmd[COMMANDER_INTERNAL_SYMBOL]) {\n    cmd[COMMANDER_INTERNAL_SYMBOL] = resetAllCommandInternal(cmd);\n  }\n\n  return cmd[COMMANDER_INTERNAL_SYMBOL];\n}\n\ntype CreateUIState = OmitStrict<CommanderUiOptions, \"__commandName\">;\n\n/** ------------------------------------------------------------------------\n * * ***Safely patches internal `ui` state on a Commander instance.***\n * ------------------------------------------------------------------------\n *\n * Applies sanitized UI configuration (via {@link createUIState | `createUIState`})\n * directly into the command's internal state.\n *\n * - *This function:*\n *    - Delegates validation to `createUIState`.\n *    - Preserves existing `ui` properties.\n *    - Lazily initializes `ui` if missing.\n *    - Does NOT overwrite unrelated fields.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - Command instance.\n * @param input - Raw UI configuration.\n *\n * @example\n * ```ts\n * setInternalUiState(cmd, { title, usage });\n * ```\n *\n * @internal\n */\nexport function setInternalUiState(\n  cmd: CommandContext,\n  input: CreateUIState\n): void {\n  const internal = getInternalState(cmd);\n  const sanitized = createUIState(input);\n\n  if (!internal.ui) {\n    internal.ui = sanitized;\n    return;\n  }\n\n  Object.assign(internal.ui, sanitized);\n}\n\n/** ------------------------------------------------------------------------\n * * ***Creates a sanitized `UI` configuration object.***\n * ------------------------------------------------------------------------\n *\n * Builds a partial `UI` state object by conditionally including only\n * valid non-empty string values.\n *\n * - *This helper is intended for internal CLI framework usage where\n * `title` and `usage` must:*\n *    - Be a non-empty string.\n *    - Exclude empty string values.\n *    - Exclude `undefined`.\n *\n * - *Unlike naive object spreading with ternaries, this function ensures:*\n *    - No `undefined` properties are injected.\n *    - No accidental overwrites occur due to falsy values.\n *    - Output object only contains valid keys.\n *\n * ------------------------------------------------------------------------\n *\n * @param input - Partial UI input configuration.\n *\n * @returns A sanitized partial UI object containing only valid properties.\n *\n * @example\n * ```ts\n * const ui = createUIState({ title, usage });\n *\n * internal.ui = {\n *   ...internal.ui,\n *   ...ui\n * };\n * ```\n *\n * @remarks\n * This function performs validation using `isNonEmptyString`, it does\n * not mutate input.\n *\n * @throws Nothing.\n *\n * @internal\n */\nexport function createUIState(input: CreateUIState): CreateUIState {\n  const result: CreateUIState = {};\n\n  if (isNonEmptyString(input.title)) {\n    result.title = input.title;\n  }\n\n  if (isNonEmptyString(input.usage)) {\n    result.usage = input.usage;\n  }\n\n  if (isNonEmptyString(input.packageName)) {\n    result.packageName = input.packageName;\n  }\n\n  if (isNonEmptyString(input.version)) {\n    result.version = input.version;\n  }\n\n  return result;\n}\n","import { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { ConfigurationError, picocolors } from \"@/utils/client\";\n\n/** ----------------------------------------------------------------\n * * Styles a Commander-generated usage string.\n * ----------------------------------------------------------------\n *\n * Applies color formatting to tokens produced by the default\n * Commander `.usage()` output.\n *\n * The input string is tokenized by whitespace and each segment\n * is conditionally styled based on its semantic role.\n *\n * Styling rules:\n *\n * - The first token (typically the command name) is highlighted\n *   when `fromHelpCommandUsage` is enabled.\n * - `[options]` tokens are styled to indicate optional flags.\n * - `[command]` tokens are styled to indicate subcommands.\n * - Required arguments (`<arg>`) are dimmed.\n * - Optional arguments (`[arg]`) are dimmed.\n *\n * Tokens that do not match any rule are returned unchanged.\n *\n * ----------------------------------------------------------------\n * @param raw - The raw usage string generated by Commander.\n *\n * @param options - Optional formatting configuration.\n *\n * @param options.fromHelpCommandUsage\n * If `true`, the first token will be highlighted to represent\n * the command name in help output.\n *\n * @param options.errorConfig\n * Optional configuration used when constructing a\n * {@link ConfigurationError} if validation fails.\n *\n * ----------------------------------------------------------------\n * @returns The styled usage string with ANSI color formatting.\n *\n * @throws {ConfigurationError}\n * Thrown when `raw` is not a non-empty string.\n *\n * @internal\n */\nexport function styleUsage(\n  raw: string,\n  {\n    fromHelpCommandUsage,\n    errorConfig: {\n      field = \"raw\",\n      expected = \"a non-empty string\",\n      context = \"styleUsage\"\n    } = {}\n  }: {\n    /** @default false */\n    fromHelpCommandUsage?: true;\n    errorConfig?: {\n      /** @default \"raw\" */\n      field?: string;\n      /** @default \"a non-empty string\" */\n      expected?: string;\n      /** @default \"styleUsage\" */\n      context?: string;\n    };\n  } = {}\n) {\n  if (!isNonEmptyString(raw)) {\n    throw ConfigurationError.type(field, expected, raw, context);\n  }\n\n  return raw\n    .split(/\\s+/)\n    .map((token, index) => {\n      if (!!fromHelpCommandUsage && index === 0) {\n        return picocolors.cyanBright(token);\n      }\n\n      if (token === \"[options]\") {\n        return picocolors.blueBright(token);\n      }\n\n      if (token === \"[command]\") {\n        return picocolors.magentaBright(token);\n      }\n\n      if (token.startsWith(\"<\") && token.endsWith(\">\")) {\n        return picocolors.gray(token);\n      }\n\n      if (token.startsWith(\"[\") && token.endsWith(\"]\")) {\n        return picocolors.gray(token);\n      }\n\n      return token;\n    })\n    .join(\" \");\n}\n\n/** ----------------------------------------------------------------\n * * Normalizes Commander usage token order.\n * ----------------------------------------------------------------\n *\n * Reorders usage tokens so that the `[options]` segment\n * always appears **at the end of the usage string**.\n *\n * Commander may sometimes place `[options]` before other\n * tokens such as arguments or subcommands. This function\n * ensures a consistent ordering for CLI help output.\n *\n * Example:\n *\n * ```\n * input:  \"cli [options] <file>\"\n * output: \"cli <file> [options]\"\n * ```\n *\n * The function preserves the relative ordering of all\n * non-option tokens.\n *\n * ----------------------------------------------------------------\n * @param raw - The raw usage string generated by Commander.\n *\n * @param options - Optional validation configuration.\n *\n * @param options.errorConfig\n * Configuration used when constructing a\n * {@link ConfigurationError} if validation fails.\n *\n * ----------------------------------------------------------------\n * @returns The normalized usage string with `[options]`\n * positioned at the end.\n *\n * @throws {ConfigurationError}\n * Thrown when `raw` is not a non-empty string.\n *\n * @internal\n */\nexport function reorderUsage(\n  raw: string,\n  {\n    errorConfig: {\n      field = \"raw\",\n      expected = \"a non-empty string\",\n      context = \"reorderUsage\"\n    } = {}\n  }: {\n    errorConfig?: {\n      /** @default \"raw\" */\n      field?: string;\n      /** @default \"a non-empty string\" */\n      expected?: string;\n      /** @default \"reorderUsage\" */\n      context?: string;\n    };\n  } = {}\n) {\n  if (!isNonEmptyString(raw)) {\n    throw ConfigurationError.type(field, expected, raw, context);\n  }\n\n  const tokens = raw.match(/\\S+/g) ?? []; //raw.split(/\\s+/);\n\n  const optionTokens = tokens.filter((t) => t === \"[options]\");\n  const otherTokens = tokens.filter((t) => t !== \"[options]\");\n\n  return [...otherTokens, ...optionTokens].join(\" \");\n}\n","import type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport {\n  EOL,\n  formatOptionValue,\n  joinLinesLoose,\n  picocolors\n} from \"@/utils/client\";\n\nimport { CliHelp } from \"@/commander-kit/core/help\";\nimport { CliOption } from \"@/commander-kit/core/option\";\n\nimport { getInternalState } from \"../state\";\nimport { reorderUsage, styleUsage } from \"../helpers/usages\";\n\n/** Internal for `.createHelp()`.\n *\n * @returns {CliHelp}\n *\n * @internal\n */\nexport class StyledHelp extends CliHelp {\n  constructor() {\n    super();\n  }\n\n  /** ----------------------------------------------------------------\n   * * Resolves the final usage string for a command.\n   * ----------------------------------------------------------------\n   *\n   * Determines the usage output by applying the following\n   * **priority order**:\n   *  1. Disabled usage (`disableUsage`).\n   *  2. Manually defined `.usage()` override.\n   *  3. UI configuration override (`ui.usage`).\n   *  4. Commander default usage formatting.\n   *\n   * If no manual or UI override is provided, the usage string\n   * returned by Commander is normalized and styled before being\n   * returned.\n   *\n   * ----------------------------------------------------------------\n   * @param cmd - The command instance whose usage should be resolved.\n   *\n   * @returns The resolved usage string, or an empty string if usage\n   * output is disabled.\n   */\n  commandUsage(cmd: CommandContext): string {\n    const { manualUsage, ui, disableUsage } = getInternalState(cmd);\n\n    if (disableUsage) return \"\";\n\n    // manual .usage()\n    if (isNonEmptyString(manualUsage)) return manualUsage;\n\n    // UI override\n    if (isNonEmptyString(ui?.usage)) return ui.usage;\n\n    // default Commander behavior\n    return styleUsage(\n      reorderUsage(super.commandUsage(cmd), {\n        errorConfig: {\n          field: \"`super.commandUsage(cmd)`\",\n          context: \"StyledHelp.commandUsage\"\n        }\n      }),\n      {\n        fromHelpCommandUsage: true,\n        errorConfig: {\n          field: \"`reorderUsage(super.commandUsage(cmd))`\",\n          context:\n            \"StyledHelp.commandUsage (by `reorderUsage(super.commandUsage(cmd))`)\"\n        }\n      }\n    );\n  }\n\n  /** ----------------------------------------------------------------\n   * - ***Custom Help formatter that:***\n   *       - Applies usage resolution priority.\n   *       - Ensures styled \"Usage:\" block replaces Commander default.\n   *\n   * This prevents conflicts between manual `.usage()` overrides\n   * and UI-defined usage formatting.\n   */\n  formatHelp(cmd: CommandContext, helper: CliHelp): string {\n    const usage = this.commandUsage(cmd);\n    const usageBlock = joinLinesLoose(picocolors.reset(\"Usage:\"), `  ${usage}`);\n    const rest = super.formatHelp(cmd, helper);\n\n    if (!usage) {\n      return rest.replace(/^Usage:[\\s\\S]*?\\n(?=\\S)/, \"\");\n    }\n\n    return rest.replace(/^Usage:[\\s\\S]*?\\n(?=\\S)/, usageBlock + EOL + EOL);\n  }\n\n  /** ----------------------------------------------------------------\n   * * Resolves the final usage string for a command.\n   * ----------------------------------------------------------------\n   *\n   * Determines the usage output by applying the following\n   * **priority order**:\n   *  1. Disabled usage (`disableUsage`).\n   *  2. Manually defined `.usage()` override.\n   *  3. UI configuration override (`ui.usage`).\n   *  4. Commander default usage formatting.\n   *\n   * If no manual or UI override is provided, the usage string\n   * returned by Commander is normalized and styled before being\n   * returned.\n   *\n   * ----------------------------------------------------------------\n   * @param cmd - The command instance whose usage should be resolved.\n   *\n   * @returns The resolved usage string, or an empty string if usage\n   * output is disabled.\n   */\n  optionDescription(option: CliOption) {\n    let desc = option.description || \"\";\n\n    const hasDefault = option.defaultValue !== undefined;\n\n    if (isNonEmptyString(desc)) {\n      desc = desc.trim();\n\n      if (hasDefault) {\n        if (desc.endsWith(\".\")) {\n          desc = desc.slice(0, -1) + \"\";\n        } else if (!desc.endsWith(\",\")) {\n          desc += \"\";\n        }\n\n        desc += ` ${picocolors.italic(`(default: ${formatOptionValue(option.defaultValue)})`)}.`;\n      } else {\n        if (!desc.trim().endsWith(\".\")) {\n          desc += \".\";\n        }\n      }\n    }\n\n    return desc;\n  }\n}\n","import type { CommandContext } from \"@/commander-kit/types\";\n\nimport { Command } from \"commander\";\n\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\n\nimport { CliCommand } from \"@/commander-kit/core/command\";\nimport { CommandBaseProgram } from \"@/commander-kit/factories/create-base-program\";\n\n/** ------------------------------------------------------------------------\n * * Resolves factory-origin error message suffix.\n * ------------------------------------------------------------------------\n *\n * Returns an additional error message suffix when the provided command\n * instance originates from the `createBaseProgram` factory.\n *\n * This helper is used to enrich internal error messages with contextual\n * information about how the command instance was constructed.\n *\n * If the command is not an instance of {@link CommandBaseProgram | `CommandBaseProgram`},\n * an empty string is returned.\n *\n * ------------------------------------------------------------------------\n *\n * @param programCommand - The command instance to inspect.\n *\n * @returns A formatted error message suffix indicating factory origin,\n * or an empty string if not applicable.\n *\n * @example\n * ```ts\n * throw new Error(\n *   `Invalid configuration${resolveFactoryOriginErrorSuffix(programCommand)}`\n * );\n * ```\n *\n * @internal\n */\nexport function resolveFactoryOriginErrorSuffix(\n  programCommand: CommandContext\n): string {\n  return isExactInstanceOf(programCommand, CommandBaseProgram)\n    ? \" by 'createBaseProgram' factory function\"\n    : \"\";\n}\n\n/** ------------------------------------------------------------------------\n * * Resolves an error message suffix based on the command instance type.\n * ------------------------------------------------------------------------\n *\n * Determines the concrete command class used to construct the provided\n * command instance and returns a short string identifier that can be\n * appended to error messages.\n *\n * This helper is primarily used internally to improve diagnostic output\n * by indicating which command implementation produced the error.\n *\n * The returned value is determined using strict runtime checks via\n * {@link isExactInstanceOf | `isExactInstanceOf`}.\n *\n * ------------------------------------------------------------------------\n * #### Resolution rules\n * ------------------------------------------------------------------------\n *\n * - Returns `\"Command\"` if the instance is exactly {@link Command | `Command`}.\n * - Returns `\"CliCommand\"` if the instance is exactly {@link CliCommand | `CliCommand`}.\n * - Returns an empty string (`\"\"`) for all other cases.\n *\n * ------------------------------------------------------------------------\n *\n * @param programCommand - The command instance to inspect.\n *\n * @returns\n * A string identifier representing the command class, or an empty\n * string if the instance does not match any supported command types.\n *\n * @example\n * ```ts\n * throw new Error(\n *   `Invalid configuration (${resolveInstanceOriginErrorSuffix(programCommand)})`\n * );\n * ```\n *\n * @internal\n */\nexport function resolveInstanceOriginErrorSuffix(\n  programCommand: CommandContext\n): string {\n  return isExactInstanceOf(programCommand, Command)\n    ? \"Command\"\n    : isExactInstanceOf(programCommand, CliCommand)\n      ? \"CliCommand\"\n      : \"\";\n}\n","import type { Command } from \"commander\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isNil, isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { ConfigurationError } from \"@/utils/errors\";\n\nimport {\n  resolveFactoryOriginErrorSuffix,\n  resolveInstanceOriginErrorSuffix\n} from \"@/commander-kit/_internal/helpers/error-formatters\";\nimport { getInternalState } from \"@/commander-kit/_internal/state\";\n\n/** ----------------------------------------------------------------\n * Intercepts `.usage()` calls to capture manual overrides\n * for later resolution inside `Help` and error output.\n *\n * This preserves original Commander behavior while allowing\n * custom resolution priority.\n *\n * ----------------------------------------------------------------\n * @internal\n */\nexport function interceptUsage(cmd: CommandContext) {\n  const originalUsage = cmd.usage.bind(cmd);\n\n  function usage(str: string | false): Command;\n  function usage(): string;\n  function usage(str?: string | false): string | Command {\n    if (!isNil(str)) {\n      // disable manual usage override\n      if (str === false) {\n        getInternalState(cmd).manualUsage = undefined;\n        getInternalState(cmd).disableUsage = true;\n\n        return cmd;\n      }\n\n      if (!isNonEmptyString(str)) {\n        const errorMessageByFactory = resolveFactoryOriginErrorSuffix(cmd);\n        const errorMessageInstance = resolveInstanceOriginErrorSuffix(cmd);\n\n        throw ConfigurationError.type(\n          \"usage\",\n          \"a non-empty string or `false` only\",\n          str,\n          `'${errorMessageInstance}.usage'${errorMessageByFactory}`\n        );\n      }\n\n      getInternalState(cmd).manualUsage = str;\n      return originalUsage(str);\n    }\n\n    return originalUsage();\n  }\n\n  cmd.usage = usage;\n}\n","import { deepFreeze } from \"@/_internal/utils/helper\";\n\n/** ------------------------------------------------------------------------\n * * ***Internal default configuration for the Commander UI layer.***\n * ------------------------------------------------------------------------\n *\n * Centralized constant registry containing baseline values used by\n * the structured UI system when enhancing Commander program instances.\n *\n * - **This object acts as the single source of truth for:**\n *    - Default flag signatures.\n *    - Default help descriptions.\n *    - Any future UI-level fallback values.\n *\n * - **These values are used when:**\n *    - The user does not explicitly override version flags.\n *    - The user does not explicitly override help flags.\n *    - Internal rendering requires safe fallback strings.\n *\n * ------------------------------------------------------------------------\n * #### ⚠️ Internal Contract.\n * ------------------------------------------------------------------------\n *\n * - This constant is not part of the public API.\n * - Its structure may change without notice.\n * - Consumers must not rely on its shape or values.\n *\n * Any external customization should be performed via the\n * public configuration surface (e.g. applyCommanderUi options),\n * not by mutating this object.\n *\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nexport const COMMANDER_UI_DEFAULTS = deepFreeze({\n  FLAGS: {\n    /** Default version flag signature.\n     *\n     * @returns `\"-v, --version\"`.\n     */\n    VERSION: \"-v, --version\",\n\n    /** Default help flag signature.\n     *\n     * @returns `\"-h, --help\"`.\n     */\n    HELP: \"-h, --help\"\n  },\n\n  DESCRIPTIONS: {\n    /** Default help option description text.\n     *\n     * @returns `\"To display help for this command.\"`.\n     */\n    HELP: \"To display help for this command.\",\n    /** Default version option description text.\n     *\n     * @returns `\"The version package of this command.\"`.\n     */\n    VERSION: \"The version package of this command.\"\n  }\n});\n","import type { Command } from \"commander\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isBoolean, isNil, isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport { ConfigurationError } from \"@/utils/errors\";\n\nimport {\n  resolveFactoryOriginErrorSuffix,\n  resolveInstanceOriginErrorSuffix\n} from \"@/commander-kit/_internal/helpers/error-formatters\";\nimport { getInternalState } from \"@/commander-kit/_internal/state\";\n\nimport { CliCommand } from \"@/commander-kit/core/command\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nconst { DESCRIPTIONS, FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** ----------------------------------------------------------------\n * Intercepts `.helpOption()` to track:\n *  - custom flags.\n *  - custom description.\n *  - disabled state.\n *\n * This enables UI-aware error rendering without accessing\n * Commander private properties.\n *\n * ----------------------------------------------------------------\n * @internal\n */\nexport function interceptHelp(cmd: CommandContext) {\n  function resetInternalHelpState(cmd: CommandContext) {\n    getInternalState(cmd).help = undefined;\n  }\n\n  const original = cmd.helpOption.bind(cmd);\n\n  cmd.helpOption = function (\n    flags?: string | boolean,\n    description?: string\n  ): CliCommand | Command {\n    const errorMessageByFactory = resolveFactoryOriginErrorSuffix(cmd);\n    const errorMessageInstance = resolveInstanceOriginErrorSuffix(cmd);\n\n    if (!isNil(flags) && !isNonEmptyString(flags) && !isBoolean(flags)) {\n      resetInternalHelpState(cmd);\n\n      throw ConfigurationError.type(\n        \"flags\",\n        \"a non-empty string or a boolean\",\n        flags,\n        `'${errorMessageInstance}.helpOption'${errorMessageByFactory}`\n      );\n    }\n\n    if (!isNil(description) && !isNonEmptyString(description)) {\n      resetInternalHelpState(cmd);\n\n      throw ConfigurationError.type(\n        \"description\",\n        \"a non-empty string if provided\",\n        description,\n        `'${errorMessageInstance}.helpOption'${errorMessageByFactory}`\n      );\n    }\n\n    const _decs = isNonEmptyString(description)\n      ? description\n      : DESCRIPTIONS.HELP;\n\n    if (flags === false) {\n      getInternalState(cmd).help = {\n        disabled: true\n      };\n      return original(flags);\n    }\n\n    if (flags === true) {\n      getInternalState(cmd).help = {\n        flags: FLAGS.HELP,\n        description: _decs,\n        disabled: false\n      };\n      return original(flags, _decs);\n    }\n\n    if (isNonEmptyString(flags)) {\n      getInternalState(cmd).help = {\n        flags,\n        description: _decs,\n        disabled: false\n      };\n      return original(flags, _decs);\n    }\n\n    return original(flags, _decs);\n  };\n}\n","import type { Command } from \"commander\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isNil, isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport { ConfigurationError } from \"@/utils/errors\";\n\nimport {\n  resolveFactoryOriginErrorSuffix,\n  resolveInstanceOriginErrorSuffix\n} from \"@/commander-kit/_internal/helpers/error-formatters\";\nimport { getInternalState } from \"@/commander-kit/_internal/state\";\n\nimport { CliCommand } from \"@/commander-kit/core/command\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nconst { FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** ------------------------------------------------------------------------\n * * Intercepts `.version()` to capture manual overrides.\n * ------------------------------------------------------------------------\n *\n * Wraps the original Commander {@link CliCommand.version | `Command.version`}\n * method in order to:\n *\n * - Capture user-provided version metadata.\n * - Store it inside internal state.\n * - Preserve original Commander behavior.\n * - Enable custom resolution priority during presentation rendering.\n *\n * This interceptor allows `createBaseProgram`, `CliHelp`, and\n * error rendering layers to resolve version information lazily\n * and consistently — without relying on Commander’s internal\n * state alone.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Behavior:***\n *    - Preserves the original `.version()` binding.\n *    - Stores the original method reference in internal state as\n *      `versionOriginal`.\n *    - Supports both Commander overload signatures:\n *\n *      - Getter: `command.version()`.\n *      - Setter: `command.version(value, flags?, description?)`.\n *\n *    - Validates input types before delegating to Commander.\n *    - Injects default flags and description when omitted.\n *    - Marks `versionSetByUser = true` to influence resolution priority.\n *    - Delegates to the original Commander `.version()` implementation.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Resolution Priority Impact:***\n *    - **When this interceptor is installed, version resolution\n *      priority becomes:**\n *        1. User-set version via intercepted `.version()`.\n *        2. Factory-level version (from `createBaseProgram`).\n *        3. `package.json` version fallback.\n *\n *    - **This enables consistent and predictable version display across:**\n *        - Styled help output.\n *        - Header rendering.\n *        - Error messages.\n *        - Manual version flag execution.\n *\n * ------------------------------------------------------------------------\n *\n * - ***⚠️ Important Notes:***\n *    - Mutates the provided command instance.\n *    - Should only be installed once per command.\n *    - Designed strictly for internal orchestration.\n *    - Does not change Commander execution semantics.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - Internal command instance to intercept.\n * @param versionDescription - Default description used when the user\n * does not provide one explicitly.\n *\n * @internal\n */\nexport function interceptVersion(\n  cmd: CommandContext,\n  versionDescription: string\n) {\n  const originalVersion = cmd.version.bind(cmd);\n\n  getInternalState(cmd).versionOriginal = originalVersion;\n\n  function version(\n    value: string,\n    flags?: string,\n    description?: string\n  ): CliCommand | Command;\n  function version(value: false): CliCommand | Command;\n  function version(): string | undefined;\n  function version(\n    value?: string | false,\n    flags?: string,\n    description?: string\n  ): CliCommand | Command | string | undefined {\n    if (arguments.length === 0) return originalVersion();\n\n    if (value === false) {\n      getInternalState(cmd).versionDisable = true;\n      // getInternalState(cmd).versionSetByUser = true;\n      getInternalState(cmd).versionOriginal = undefined;\n\n      return cmd;\n    }\n\n    const errorMessageByFactory = resolveFactoryOriginErrorSuffix(cmd);\n    const errorMessageInstance = resolveInstanceOriginErrorSuffix(cmd);\n\n    if (!isNonEmptyString(value)) {\n      throw ConfigurationError.type(\n        \"str\",\n        \"a non-empty string\",\n        value,\n        `'${errorMessageInstance}.version'${errorMessageByFactory}`\n      );\n    }\n\n    if (!isNil(flags) && !isNonEmptyString(flags)) {\n      throw ConfigurationError.type(\n        \"flags\",\n        \"a non-empty string if provided\",\n        flags,\n        `'${errorMessageInstance}.version'${errorMessageByFactory}`\n      );\n    }\n\n    if (!isNil(description) && !isNonEmptyString(description)) {\n      throw ConfigurationError.type(\n        \"description\",\n        \"a non-empty string if provided\",\n        description,\n        `'${errorMessageInstance}.version'${errorMessageByFactory}`\n      );\n    }\n\n    const _flag = isNonEmptyString(flags) ? flags : FLAGS.VERSION;\n    const _decs = isNonEmptyString(description)\n      ? description\n      : versionDescription;\n\n    getInternalState(cmd).versionMeta = {\n      value,\n      flags: _flag,\n      description: _decs\n    };\n\n    getInternalState(cmd).versionSetByUser = true;\n\n    return originalVersion(value, _flag, _decs);\n  }\n\n  cmd.version = version;\n}\n","import { Argument } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Command-line argument definition class.***\n * ----------------------------------------------------------------\n *\n * Represents a positional CLI argument definition.\n *\n * This class extends Commander’s {@link Argument | **`Argument`**}\n * and is provided to ensure compatibility with the\n * additional types and utilities exposed by this library.\n */\nexport class CliArgument extends Argument {\n  constructor(arg: string, description?: string) {\n    super(arg, description);\n  }\n}\n","import \"@rzl-zone/node-only\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { Argument } from \"commander\";\n\nimport {\n  isUndefined,\n  isNonEmptyString,\n  isNull,\n  isNil\n} from \"@/_internal/utils/helper\";\n\nimport {\n  ConfigurationError,\n  joinInline,\n  joinLinesLoose,\n  picocolors\n} from \"@/utils/client\";\nimport { ICONS } from \"@/utils/server\";\n\nimport { CliArgument } from \"@/commander-kit/core/argument\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nimport { getInternalState } from \"../state\";\n\nconst { DESCRIPTIONS, FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** ------------------------------------------------------------------------\n * * Composes a normalized version description string.\n * ------------------------------------------------------------------------\n *\n * Generates a standardized version description sentence.\n *\n * If a valid `packageName` is provided, the resulting string will follow:\n *\n *   \"The version package of \\<packageName\\>.\"\n *\n * Otherwise, a fallback description from `DESCRIPTIONS.VERSION`\n * from {@link COMMANDER_UI_DEFAULTS| `COMMANDER_UI_DEFAULTS`}\n * will be used.\n *\n * ------------------------------------------------------------------------\n * #### 🔎 Normalization Rules.\n * ------------------------------------------------------------------------\n *\n * - **The returned string is always:**\n *      - Trimmed.\n *      - Guaranteed to end with exactly one trailing period.\n *      - Normalized to prevent duplicate trailing dots.\n *\n * ------------------------------------------------------------------------\n *\n * @param packageName - Optional package name used to compose\n * a contextual version description.\n *\n * @returns A normalized sentence ending with a single period.\n *\n * @throws {ConfigurationError}\n * Thrown when `packageName` is provided but is not a non-empty string.\n *\n * ------------------------------------------------------------------------\n *\n * @example\n * ```ts\n * composeVersionDescription(\"my-cli\");\n * // ➔ \"The version package of my-cli.\"\n * ```\n *\n * @example\n * ```ts\n * composeVersionDescription();\n * // ➔ Falls back to `DESCRIPTIONS.VERSION` from `COMMANDER_UI_DEFAULTS` (normalized)\n * ```\n *\n * @internal\n */\nexport const composeVersionDescription = (packageName?: string): string => {\n  const isPkgNameEmptyString = !isNonEmptyString(packageName);\n\n  if (!isUndefined(packageName) && isPkgNameEmptyString) {\n    throw ConfigurationError.type(\n      \"packageName\",\n      \"a non-empty string\",\n      packageName,\n      \"composeVersionDescription\"\n    );\n  }\n\n  const text = !isPkgNameEmptyString\n    ? `The version package of ${packageName}.`\n    : DESCRIPTIONS.VERSION;\n\n  const trimmed = text.trim().replace(/\\.*$/, \"\");\n  return trimmed + \".\";\n};\n\n/** Takes an argument and returns its human readable equivalent for help usage command.\n *\n * @internal\n */\nexport function humanReadableArgName(arg: Argument | CliArgument): string {\n  if (!(arg instanceof Argument)) {\n    throw ConfigurationError.type(\n      \"arg\",\n      \"instanceof Argument or CliArgument\",\n      arg,\n      \"humanReadableArgName\"\n    );\n  }\n\n  const nameOutput = arg.name() + (arg.variadic === true ? \"...\" : \"\");\n\n  return arg.required ? \"<\" + nameOutput + \">\" : \"[\" + nameOutput + \"]\";\n}\n\n/** Removes a leading `\"v\"` from a version string only if it is\n * immediately followed by a digit.\n *\n * - ***This safely normalizes common semver formats like:***\n *    - `v1.2.3` ➔ `1.2.3`.\n *    - `1.2.3`  ➔ unchanged.\n *    - `vbeta`  ➔ unchanged.\n *    - `null` | `undefined`  ➔ unchanged.\n *\n * The function avoids naive slicing and ensures\n * non-semver strings are not modified.\n *\n * @param version - The version string to normalize.\n * @returns The normalized version string.\n *\n * @internal\n */\nexport function normalizeVersionPrefix(version: string): string;\nexport function normalizeVersionPrefix(version: string | null): string | null;\nexport function normalizeVersionPrefix(version?: string): string | undefined;\nexport function normalizeVersionPrefix(version?: null): null | undefined;\nexport function normalizeVersionPrefix(version: null): null;\nexport function normalizeVersionPrefix(\n  version?: string | null\n): string | null | undefined;\nexport function normalizeVersionPrefix(\n  version: string | null | undefined\n): string | null | undefined {\n  if (!isNil(version) && !isNonEmptyString(version)) {\n    throw ConfigurationError.type(\n      \"version\",\n      \"a non-empty string, null or undefined\",\n      version,\n      \"composeVersionDescription\"\n    );\n  }\n\n  if (isNull(version)) return null;\n  return version?.replace(/^v(?=\\d)/, \"\");\n}\n\n/** Options for {@link ensureVersionInjected | `ensureVersionInjected`}.\n *\n * @internal\n */\nexport type EnsureVersionInjectedOptions = {\n  /** Pre-formatted package name used in the styled version output. */\n  pkgNameFormatted?: string;\n\n  /** Normalized package version (without leading `\"v\"`). */\n  normalizedVersion: string;\n};\n\n/** Ensures the version option is lazily injected into the command\n * before parsing occurs.\n *\n * - **This helper mirrors the default `.version()` behavior but allows\n *   custom styled output to be injected only if:**\n *      - The user did NOT explicitly call `.version()`.\n *      - The version has NOT already been injected.\n *\n * The injection is intentionally deferred until `parse()` /\n * `parseAsync()` time to avoid interfering with user-land\n * configuration order.\n *\n * This function is idempotent and safe to call multiple times.\n *\n * @internal\n */\nexport function ensureVersionInjected(\n  cmd: CommandContext,\n  options: EnsureVersionInjectedOptions\n): void {\n  const { pkgNameFormatted, normalizedVersion } = options;\n  const _internal = getInternalState(cmd);\n\n  if (!_internal.versionSetByUser && !_internal.versionInjected) {\n    const _isNonEmptyString = isNonEmptyString(pkgNameFormatted);\n\n    const _pkgName = _isNonEmptyString ? pkgNameFormatted : undefined;\n\n    const _subTitle = _isNonEmptyString\n      ? `${pkgNameFormatted} ${picocolors.reset(\"version\")}:`\n      : `${picocolors.blueBright(\"Version\")}:`;\n\n    _internal.versionOriginal?.(\n      joinLinesLoose(\n        _subTitle,\n        joinInline(\n          `${picocolors.magentaBright(ICONS.arrowRight)}`,\n          `${picocolors.gray(`v${normalizedVersion}`)}`\n        )\n      ),\n      FLAGS.VERSION,\n      composeVersionDescription(_pkgName)\n    );\n\n    _internal.versionInjected = true;\n  }\n}\n","import \"@rzl-zone/node-only\";\n\nimport type { CreateBaseProgramOptions } from \"@/commander-kit/types\";\n\nimport { parse } from \"node:path\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { PACKAGE_META } from \"@/_internal/constants/package-meta\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { joinInline, picocolors } from \"@/utils/client\";\n\nimport { normalizeVersionPrefix } from \"./versions\";\n\n/** Parameters accepted by\n * {@link resolveBaseProgramPresentationMeta | `resolveBaseProgramPresentationMeta`}.\n *\n * @internal\n */\nexport type ResolveBaseProgramPresentationParams = CreateBaseProgramOptions;\n\n/** Fully resolved presentation metadata returned by\n * {@link resolveBaseProgramPresentationMeta | `resolveBaseProgramPresentationMeta`}.\n *\n * - **This object is immutable and safe to reuse across:**\n *    - Header rendering.\n *    - Version wiring.\n *    - Title formatting.\n * ----------------------------------------------------------------\n * @internal\n */\nexport type BaseProgramPresentationMeta = Readonly<{\n  /** Resolved CLI name from override, identity, or argv. */\n  readonly resolvedCliName: string | undefined;\n\n  /** Resolved display title. */\n  readonly commandTitle: string | undefined;\n\n  /** Resolved package name. */\n  readonly resolvedPackageName: string;\n\n  /** Resolved (raw) package version before normalization. */\n  readonly resolvedPackageVersion: string;\n\n  /** Normalized version (prefixed if needed). */\n  readonly normalizedVersion: string;\n\n  /** Whether CLI name differs from package.json name. */\n  readonly isDiffCommandName: boolean;\n\n  /** Formatted package name with optional CLI alias. */\n  readonly pkgNameFormatted: string;\n\n  /** Default formatted title (package@version + alias arrow). */\n  readonly defaultTitleFormatted: string;\n}>;\n\n/** ------------------------------------------------------------------------\n * * Resolves normalized presentation metadata for `createBaseProgram`.\n * ------------------------------------------------------------------------\n *\n * Computes and returns all derived identity and presentation values\n * required during base program construction.\n *\n * - **This helper centralizes resolution logic for:**\n *    - CLI name detection.\n *    - Command title fallback.\n *    - Package name resolution.\n *    - Package version normalization.\n *    - Presentation formatting (colored output).\n *\n * Unlike `resolveCliPresentationMeta`, this resolver operates purely\n * on factory-level inputs and does not depend on Commander internal state.\n *\n * The returned object is immutable.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Resolution Priority:***\n *\n *    - *CLI Name:*\n *        1. Explicit `cliName`.\n *        2. `commandIdentity.commandName`.\n *        3. `process.argv[1]` basename.\n *        4. `undefined`.\n *\n *    - *Command Title:*\n *        1. `commandIdentity.cli()`.\n *        2. UI `title`.\n *        3. `undefined`.\n *\n *    - *Package Name:*\n *        1. Explicit `packageName`.\n *        2. `commandIdentity.packageName`.\n *        3. `package.json` name.\n *\n *    - *Package Version:*\n *        1. Explicit `packageVersion`.\n *        2. `commandIdentity.version`.\n *        3. `package.json` version.\n *\n * ------------------------------------------------------------------------\n *\n * @param params - Resolution parameters.\n * @returns Immutable base program presentation metadata.\n *\n * ------------------------------------------------------------------------\n * @internal\n */\nexport function resolveBaseProgramPresentationMeta(\n  params: ResolveBaseProgramPresentationParams\n): BaseProgramPresentationMeta {\n  const { cliName, packageName, packageVersion, commandIdentity, ui } = params;\n\n  /** Resolve CLI name. */\n  const resolvedCliName = isNonEmptyString(cliName)\n    ? cliName\n    : isNonEmptyString(commandIdentity?.commandName)\n      ? commandIdentity!.commandName\n      : isNonEmptyString(process.argv[1])\n        ? parse(process.argv[1]).name\n        : undefined;\n\n  /** Resolve command title. */\n  const identityTitle = commandIdentity?.cli?.();\n  const commandTitle = isNonEmptyString(identityTitle)\n    ? identityTitle\n    : isNonEmptyString(ui?.title)\n      ? ui.title\n      : undefined;\n\n  /** Resolve package name. */\n  const resolvedPackageName = isNonEmptyString(packageName)\n    ? packageName\n    : isNonEmptyString(commandIdentity?.packageName)\n      ? commandIdentity.packageName\n      : PACKAGE_META.name;\n\n  /** Resolve package version (raw). */\n  const resolvedPackageVersion = isNonEmptyString(packageVersion)\n    ? packageVersion\n    : isNonEmptyString(commandIdentity?.version)\n      ? commandIdentity.version\n      : PACKAGE_META.version;\n\n  /** Normalize version prefix. */\n  const normalizedVersion = normalizeVersionPrefix(resolvedPackageVersion);\n\n  /** Determine CLI/package name difference. */\n  const isDiffCommandName =\n    !!resolvedCliName && resolvedCliName !== PACKAGE_META.name;\n\n  /** Build formatted package name. */\n  const pkgNameFormatted = `${picocolors.blueBright(resolvedPackageName)}${\n    isDiffCommandName ? ` ${picocolors.cyanBright(`(${resolvedCliName})`)}` : \"\"\n  }`;\n\n  /** Build formatted default title. */\n  const defaultTitleFormatted = joinInline(\n    picocolors.blueBright(PACKAGE_META.name + \"@\" + normalizedVersion),\n    isDiffCommandName\n      ? `${picocolors.magentaBright(ICONS.arrowRight)} ${picocolors.yellowBright(resolvedCliName)}`\n      : false\n  );\n\n  return Object.freeze({\n    resolvedCliName,\n    commandTitle,\n    resolvedPackageName,\n    resolvedPackageVersion,\n    normalizedVersion,\n    isDiffCommandName,\n    pkgNameFormatted,\n    defaultTitleFormatted\n  });\n}\n","import type { CommandContext } from \"@/commander-kit/types\";\n\nimport {\n  ensureVersionInjected,\n  type EnsureVersionInjectedOptions\n} from \"@/commander-kit/_internal/helpers/versions\";\n\n/** ------------------------------------------------------------------------\n * * Installs a version injection interceptor on a Commander program.\n * ------------------------------------------------------------------------\n *\n * Wraps the program's `Command` instance `.parse()` and `.parseAsync()` methods to ensure\n * that version metadata is injected immediately before execution begins.\n *\n * This enables lazy version wiring, meaning version configuration\n * is applied at parse-time rather than during initial setup.\n *\n * ------------------------------------------------------------------------\n * #### Behavior.\n * ------------------------------------------------------------------------\n *\n * - Preserves the original `Command` instance `.parse()` and `.parseAsync()` method bindings.\n * - Invokes {@link ensureVersionInjected | `ensureVersionInjected()`} before delegating to the original method.\n * - Does not alter Commander’s execution semantics.\n * - Transparently returns the original method results.\n *\n * ------------------------------------------------------------------------\n * #### ⚠️ Important Notes.\n * ------------------------------------------------------------------------\n *\n * - This function mutates the provided `program` instance.\n * - It should only be installed once per program instance.\n * - Intended strictly for internal UI-layer lifecycle orchestration.\n *\n * ------------------------------------------------------------------------\n *\n * @param program - A Commander program instance, this may be either:\n * - A program created via `createBaseProgram()`, or\n * - A native `Command` instance created directly from Commander.\n *\n * @param options - Configuration object controlling version injection.\n * @param options.versionInjection - Options forwarded to\n * `ensureVersionInjected()` prior to parsing.\n *\n * @internal\n */\nexport function installParseVersionInterceptor(\n  program: CommandContext,\n  options: { versionInjection: EnsureVersionInjectedOptions }\n): void {\n  const { versionInjection } = options;\n\n  const originalParse = program.parse.bind(program);\n  const originalParseAsync = program.parseAsync.bind(program);\n\n  program.parse = function (...args) {\n    ensureVersionInjected(program, versionInjection);\n    return originalParse(...args);\n  };\n\n  program.parseAsync = async function (...args) {\n    ensureVersionInjected(program, versionInjection);\n    return originalParseAsync(...args);\n  };\n}\n","import \"@rzl-zone/node-only\";\n\nimport type {\n  CommanderInternalState,\n  CommanderUiOptions\n} from \"@/commander-kit/types\";\n\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\nimport { joinLinesLoose, ConfigurationError } from \"@/utils/client\";\n\nimport { StyledHelp } from \"../_internal/help/styled-help\";\nimport { interceptUsage } from \"../_internal/interceptor/usage\";\nimport { interceptHelp } from \"../_internal/interceptor/help\";\nimport { interceptVersion } from \"../_internal/interceptor/version\";\nimport { composeVersionDescription } from \"../_internal/helpers/versions\";\nimport { createDefaultInternalState, createUIState } from \"../_internal/state\";\nimport { resolveBaseProgramPresentationMeta } from \"../_internal/helpers/base-program\";\nimport { installParseVersionInterceptor } from \"../_internal/interceptor/install-parse-version\";\n\nimport { CliCommand } from \"../core/command\";\nimport { CommandIdentity } from \"../identity\";\nimport { applyCommanderUi } from \"../ui/apply-commander-ui\";\nimport { handleCommanderExit } from \"../lifecycle/handle-commander-exit\";\n\n/** ----------------------------------------------------------------\n * * ***Internal base program implementation.***\n * ----------------------------------------------------------------\n *\n * Internal extension of {@link CliCommand | `CliCommand`}\n * used by {@link createBaseProgram | `createBaseProgram()`}.\n *\n * This class stores additional internal state required\n * for UI formatting, version injection, and command\n * lifecycle behavior.\n */\nexport class CommandBaseProgram extends CliCommand {\n  /** ----------------------------------------------------------------\n   * * ***Internal mutable state container used by the CLI runtime.***\n   * ----------------------------------------------------------------\n   *\n   * Stores metadata required during program bootstrap and\n   * command execution such as UI configuration, version\n   * injection, and identity metadata.\n   *\n   * This state should only be modified through\n   * {@link _setInternalState | `_setInternalState`}.\n   *\n   * @internal\n   */\n  private _internalStateData: CommanderInternalState;\n\n  constructor(name?: string) {\n    super(name);\n\n    this._internalStateData = createDefaultInternalState();\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Access the internal CLI state container.***\n   * ----------------------------------------------------------------\n   *\n   * Returns a readonly view of the internal state used\n   * by the program runtime.\n   *\n   * This accessor is intended for internal helpers and\n   * framework utilities.\n   *\n   * @internal\n   */\n  get _internalState(): Readonly<CommanderInternalState> {\n    return this._internalStateData;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Replace the current internal state container.***\n   * ----------------------------------------------------------------\n   *\n   * This method is primarily used during program bootstrap\n   * to initialize or update runtime metadata.\n   *\n   * External consumers should never call this method directly.\n   *\n   * @internal\n   */\n  _setInternalState(state: CommanderInternalState) {\n    this._internalStateData = state;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Create subcommand instance.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides Commander’s internal command factory so\n   * all nested commands are instances of\n   * {@link CommandBaseProgram | `CommandBaseProgram`}.\n   *\n   * This ensures that internal state and runtime\n   * extensions propagate to all subcommands.\n   *\n   * @internal\n   */\n  override createCommand(name?: string): CommandBaseProgram;\n  override createCommand(name?: string): CommandBaseProgram {\n    const sub = new CommandBaseProgram(name);\n\n    sub._setInternalState({\n      ...this._internalState\n    });\n\n    return sub;\n  }\n}\n\n/** ----------------------------------------------------------------\n * * ***Configuration options for `createBaseProgram()`.***\n * ----------------------------------------------------------------\n *\n * Defines the bootstrap configuration used when creating\n * a pre-configured Commander program instance.\n *\n * - ***This type supports:***\n *      - direct property overrides.\n *      - centralized configuration via\n *        {@link CommandIdentity | `CommandIdentity`}.\n *      - optional CLI UI customization.\n *\n * ----------------------------------------------------------------\n * #### Resolution Priority.\n * ----------------------------------------------------------------\n *\n * When both explicit fields and `commandIdentity` are provided,\n * values are resolved in the following order:\n *\n *  * `explicit option` ➔ {@link CreateBaseProgramOptions.commandIdentity |`commandIdentity`} ➔ `internal defaults`.\n *\n * This ensures predictable override behavior.\n *\n * ----------------------------------------------------------------\n */\nexport type CreateBaseProgramOptions = {\n  /** ----------------------------------------------------------------\n   * * ***CLI program name.***\n   * ----------------------------------------------------------------\n   *\n   * Name assigned to the Commander instance.\n   *\n   * Overrides {@link CommandIdentity.commandName | `commandIdentity.commandName`} when provided.\n   *\n   * ----------------------------------------------------------------\n   */\n  cliName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package name.***\n   * ----------------------------------------------------------------\n   *\n   * Package name displayed in the version description.\n   *\n   * Overrides {@link CommandIdentity.packageName | `commandIdentity.packageName`} when provided.\n   *\n   * Defaults to the internally resolved package name\n   * when omitted.\n   *\n   * ----------------------------------------------------------------\n   */\n  packageName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package version.***\n   * ----------------------------------------------------------------\n   *\n   * Version string passed to {@link CliCommand.version `.version()`}.\n   *\n   * Overrides {@link CommandIdentity.version | `commandIdentity.version`} when provided.\n   *\n   * Defaults to the internally resolved package version\n   * when omitted.\n   *\n   * ----------------------------------------------------------------\n   */\n  packageVersion?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Commander UI configuration.***\n   * ----------------------------------------------------------------\n   *\n   * Inline UI configuration via `ui` option.\n   *\n   * UI initialization is resolved using the following priority:\n   *\n   * 1. When `ui.usage` is defined,\n   *    full UI customization is triggered and strict validation is enforced.\n   *\n   * 2. Otherwise, if {@link CommandIdentity | `commandIdentity`} is provided,\n   *    UI is initialized using the identity title.\n   *\n   * 3. Otherwise, if `ui.title` is defined and valid,\n   *    UI is initialized using the provided title only.\n   *\n   * When full UI customization is triggered (case #1),\n   * the following validations are enforced:\n   *\n   * - The UI object must be non-null.\n   * - `title` must be a non-empty string when provided.\n   * - `usage` must be a non-empty string when provided.\n   *\n   * In partial initialization cases (#2 and #3),\n   * usage falls back to {@link CliCommand | `CliCommand`} default resolution.\n   *\n   * @note\n   * ⚠️ If validation fails, a structured configuration error may be thrown.\n   *\n   * ----------------------------------------------------------------\n   */\n  ui?: CommanderUiOptions;\n\n  /** ----------------------------------------------------------------\n   * * ***Command identity source.***\n   * ----------------------------------------------------------------\n   *\n   * Optional {@link CommandIdentity | `CommandIdentity`} instance used as a centralized\n   * configuration source for:\n   *\n   * - Command name.\n   * - Package name.\n   * - Version metadata.\n   *\n   * When provided, this identity may also participate in UI initialization.\n   *\n   * If full UI configuration is not supplied via `ui`,\n   * the identity title may be used to bootstrap\n   * {@link applyCommanderUi | `applyCommanderUi()`}.\n   *\n   * This reduces the need for manual property mapping\n   * and provides a consistent identity-driven configuration pattern.\n   *\n   * @throws {TypeError}\n   * Thrown if the provided value is not an instance of\n   * {@link CommandIdentity | `CommandIdentity`}.\n   *\n   * ----------------------------------------------------------------\n   */\n  commandIdentity?: CommandIdentity;\n};\n\n/** ----------------------------------------------------------------\n * * ***Creates a pre-configured Commander.js program instance.***\n * ----------------------------------------------------------------\n *\n * Factory function that returns a fresh {@link CliCommand | `CliCommand`} instance\n * with shared base configuration applied.\n *\n * - *This helper centralizes common CLI setup to ensure:*\n *    - Consistent version formatting.\n *    - Standardized exit behavior.\n *    - No shared mutable state between entry points.\n *\n * The returned {@link CliCommand | `CliCommand`} instance is stateful and fully mutable.\n *\n * *Additional configuration (including UI customization) may be applied after creation.*\n *\n * ----------------------------------------------------------------\n * #### Configuration Resolution.\n * ----------------------------------------------------------------\n *\n * When both explicit options and {@link CommandIdentity | `CommandIdentity`} are provided,\n * values are resolved using the following priority:\n *\n *  * `explicit option` ➔ `commandIdentity` ➔ `internal defaults`.\n *\n * This allows granular overrides while still supporting\n * {@link CommandIdentity | `CommandIdentity`} as a single source of truth.\n *\n * ----------------------------------------------------------------\n * #### UI Configuration.\n * ----------------------------------------------------------------\n *\n * UI customization can be applied using two approaches:\n *\n * 1. Inline via the `ui` option.\n *      - During initialization, {@link applyCommanderUi | `applyCommanderUi()`}\n *        may be invoked automatically using the following priority:\n *         - Full UI override when `options.ui.usage` is defined.\n *         - Fallback to {@link CommandIdentity | `commandIdentity`} when provided.\n *         - Fallback to `options.ui.title` when provided or valid.\n *\n *      - In partial initialization cases, usage falls back to\n *        {@link CliCommand | `CliCommand`} default resolution.\n *\n * 2. Manually after creation.\n *      - You may call {@link applyCommanderUi | `applyCommanderUi()`}\n *      explicitly to override or apply custom UI behavior.\n *\n *      - Calling {@link applyCommanderUi | `applyCommanderUi()`} manually after initialization will\n *        override any previously applied UI configuration.\n *\n * ----------------------------------------------------------------\n *\n * @param options Optional bootstrap configuration.\n *\n * @returns A configured {@link CliCommand | `CliCommand`} instance with version,\n * exit override, and optional UI behavior applied.\n *\n * ----------------------------------------------------------------\n * @example\n *\n * **Using commandIdentity as primary source ***(recommended)***:**\n *\n * ```ts\n * import { joinInline, picocolors } from \"@rzl-zone/build-tools/utils\";\n * import { createBaseProgram, CommandIdentity } from \"@rzl-zone/build-tools/utils/server\";\n *\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"my-command-cli\"\n * })\n *   // override to your-package-name, e.g:\n *   .setPackageName(\"your-package-name\")\n *   // override to your-package-version, e.g:\n *   .setVersion(\"1.1.1\");\n *\n * const program = createBaseProgram({\n *   commandIdentity: identity,\n *   ui: {\n *     title: identity.cli(),\n *     usage: joinInline(\n *       picocolors.cyan(identity.commandName),\n *       picocolors.gray(\"<glob...>\"),\n *       picocolors.blueBright(\"[options]\")\n *     )\n *   }\n * });\n *\n * program.parse();\n * ```\n * ----------------------------------------------------------------\n * @example\n *\n * **Automatic UI configuration ***(manual mapping)***:**\n *\n * ```ts\n * import { joinInline, picocolors } from \"@rzl-zone/build-tools/utils\";\n * import { createBaseProgram, CommandIdentity } from \"@rzl-zone/build-tools/utils/server\";\n *\n * const commandTitle = new CommandIdentity({\n *   defaultCommandName: \"clean-js-build-artifacts\"\n * })\n *   // override to your-package-name, e.g:\n *   .setPackageName(\"your-package-name\")\n *   // override to your-package-version, e.g:\n *   .setVersion(\"1.1.1\");\n *\n * const program = createBaseProgram({\n *   cliName: commandTitle.commandName,\n *   packageName: commandTitle.packageName,\n *   packageVersion: commandTitle.version,\n *   ui: {\n *     title: commandTitle.cli(),\n *     usage: joinInline(\n *       picocolors.cyan(commandTitle.commandName),\n *       picocolors.gray(\"<glob...>\"),\n *       picocolors.blueBright(\"[options]\")\n *     )\n *   }\n * });\n *\n * program.parse();\n * ```\n * ----------------------------------------------------------------\n * @example\n *\n * **Manual UI override after creation:**\n *\n * ```ts\n * import { joinInline, picocolors } from \"@rzl-zone/build-tools/utils\";\n * import { createBaseProgram, CommandIdentity } from \"@rzl-zone/build-tools/utils/server\";\n *\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"my-command-cli\"\n * });\n *\n * const baseProgram = createBaseProgram({\n *   commandIdentity: identity\n * });\n *\n * const program = applyCommanderUi(baseProgram, {\n *   title: identity.cli(),\n *   usage: joinInline(\n *     picocolors.cyan(identity.commandName),\n *     picocolors.gray(\"<glob...>\"),\n *     picocolors.blueBright(\"[options]\")\n *   )\n * });\n *\n * program.parse();\n * ```\n * ----------------------------------------------------------------\n */\nexport function createBaseProgram(\n  options: CreateBaseProgramOptions = {}\n): CommandBaseProgram {\n  if (\n    options.commandIdentity &&\n    !isExactInstanceOf(options.commandIdentity, CommandIdentity)\n  ) {\n    throw ConfigurationError.type(\n      \"options.commandIdentity\",\n      \"instanceof CommandIdentity\",\n      options.commandIdentity,\n      \"createBaseProgram\"\n    );\n  }\n\n  const {\n    commandTitle,\n    defaultTitleFormatted,\n    normalizedVersion,\n    pkgNameFormatted,\n    resolvedCliName,\n    resolvedPackageName\n  } = resolveBaseProgramPresentationMeta(options);\n\n  const cmd = new CommandBaseProgram(resolvedCliName);\n\n  cmd._setInternalState({\n    ...createDefaultInternalState(),\n    ui: createUIState(options.ui || {}),\n    packageName: resolvedPackageName\n  });\n\n  //todo: Intercept manual .usage()\n  interceptUsage(cmd);\n  //todo: Intercept manual .helpOption()\n  interceptHelp(cmd);\n  //todo: Intercept manual .version()\n  interceptVersion(cmd, composeVersionDescription(pkgNameFormatted));\n\n  cmd.createHelp = () => new StyledHelp();\n\n  cmd.addHelpText(\n    \"before\",\n    joinLinesLoose(\"\", commandTitle ?? defaultTitleFormatted, \"\")\n  );\n\n  cmd.exitOverride(handleCommanderExit);\n\n  const cmdApplyUi = applyCommanderUi(cmd, {\n    title: commandTitle,\n    usage: options.ui?.usage,\n    __commandName: resolvedCliName\n  });\n\n  installParseVersionInterceptor(cmdApplyUi, {\n    versionInjection: { normalizedVersion, pkgNameFormatted }\n  });\n\n  return cmdApplyUi;\n}\n","import \"@rzl-zone/node-only\";\n\nimport type {\n  CommandContext,\n  CommanderInternalState\n} from \"@/commander-kit/types\";\n\nimport { parse } from \"node:path\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { joinInline, picocolors } from \"@/utils/client\";\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { PACKAGE_META } from \"@/_internal/constants/package-meta\";\n\nimport { CommandBaseProgram } from \"@/commander-kit/factories/create-base-program\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nimport { getInternalState } from \"../state\";\nimport { normalizeVersionPrefix } from \"./versions\";\nimport { reorderUsage, styleUsage } from \"./usages\";\n\nconst { DESCRIPTIONS, FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** Parameters accepted by\n * {@link resolveCliPresentationMeta | `resolveCliPresentationMeta`}.\n *\n * @internal\n */\nexport type ResolveCliPresentationParams = {\n  /** The command instance to resolve metadata from. */\n  program: CommandContext;\n\n  /** Optional explicit CLI name override. */\n  commandName?: string;\n\n  /** Optional fallback title. */\n  title?: string;\n\n  /** Optional explicit CLI version override. */\n  version?: string;\n\n  /** Optional explicit CLI package name override. */\n  packageName?: string;\n};\n\n/** Normalized help configuration returned by\n * {@link resolveCliPresentationMeta | `resolveCliPresentationMeta`}.\n *\n * @internal\n */\nexport type CliPresentationHelpMeta = Readonly<{\n  /** Raw internal help metadata reference. */\n  meta: CommanderInternalState[\"help\"] | undefined;\n\n  /** Whether help output is disabled. */\n  disabled: boolean;\n\n  /** Resolved help flags. */\n  flags: string;\n\n  /** Resolved help description. */\n  description: string;\n}>;\n\n/** Fully resolved CLI presentation metadata by\n * {@link resolveCliPresentationMeta | `resolveCliPresentationMeta`}.\n *\n * This object is derived, immutable, and safe to reuse across\n * render layers (header printer, help renderer, error handler, etc.).\n *\n * @internal\n */\nexport type CliPresentationMeta = Readonly<{\n  /** Resolve CLI name from override or runtime argv. */\n  resolvedCliName: string | undefined;\n  /** Resolve Package name. */\n  resolvedPackageName: string;\n  /** Resolve Package name with formatted colors. */\n  resolvedPackageNameFormatted: string;\n  /** Determine whether CLI name differs from package name. */\n  isDiffCommandName: boolean;\n  /** Resolve display title. */\n  commandTitle: string | undefined;\n  /** Normalize version with fallback. */\n  normalizedVersion: string;\n  /** Build default formatted CLI title. */\n  defaultTitleFormatted: string;\n  /** Resolve dynamic usage string. */\n  dynamicUsage: string;\n  /** Resolve help metadata. */\n  help: CliPresentationHelpMeta;\n}>;\n\n/** ------------------------------------------------------------------------\n * * Resolves normalized CLI presentation metadata for `applyCommander`.\n * ------------------------------------------------------------------------\n *\n * Computes and returns all derived CLI presentation values required for\n * rendering headers, titles, usage output, version labels, and help\n * configuration.\n *\n * - *This helper centralizes resolution logic that depends on:*\n *     - Explicit command name overrides.\n *     - Runtime `process.argv` inspection.\n *     - Internal command state.\n *     - Package metadata fallbacks.\n *\n * - *The function guarantees consistent priority ordering for:*\n *     - CLI identity resolution.\n *     - Version normalization.\n *     - Title formatting.\n *     - Usage fallback behavior.\n *     - Help metadata defaults.\n *\n * The returned object is fully derived and does not mutate the provided\n * command instance.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Resolution Priority:***\n *\n *    - *CLI Name:*\n *       1. Explicit `commandName`.\n *       2. `process.argv[1]` basename.\n *       3. `undefined`.\n *\n *    - *Command Title:*\n *       1. Explicit `commandName`.\n *       2. Provided `title`.\n *       3. `undefined`.\n *\n *    - *Version:*\n *       1. Manual version override.\n *       2. Internal command version.\n *       3. `package.json` version.\n *\n *    - *Usage:*\n *       1. Manual usage override.\n *       2. UI usage override.\n *       3. Styled program usage.\n *\n * ------------------------------------------------------------------------\n *\n * @param params - Configuration object.\n * @returns Immutable object of cli presentation metadata.\n * @example\n * ```ts\n * const meta = resolveCliPresentationMeta({\n *   program,\n *   commandName: \"my-cli\"\n * });\n *\n * console.log(meta.defaultTitleFormatted);\n * ```\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nexport function resolveCliPresentationMeta(\n  params: ResolveCliPresentationParams\n): CliPresentationMeta {\n  const { program, commandName, title, version, packageName } = params;\n\n  const _internal = getInternalState(program);\n\n  const isCommandBaseProgram = isExactInstanceOf(program, CommandBaseProgram);\n\n  /** Resolve CLI name from override or runtime argv. */\n  const resolvedCliName = isNonEmptyString(commandName)\n    ? commandName\n    : isNonEmptyString(process.argv[1])\n      ? parse(process.argv[1]).name\n      : undefined;\n\n  /** Determine whether CLI name differs from package name. */\n  const isDiffCommandName =\n    !!resolvedCliName && resolvedCliName !== PACKAGE_META.name;\n\n  /** Resolve display title. */\n  const commandTitle = isNonEmptyString(commandName)\n    ? commandName\n    : isNonEmptyString(title)\n      ? title\n      : undefined;\n\n  /** Resolve package version (raw). */\n  const resolvedPackageVersion =\n    !isCommandBaseProgram && isNonEmptyString(version)\n      ? version\n      : isNonEmptyString(_internal.versionMeta?.value)\n        ? _internal.versionMeta.value\n        : undefined;\n\n  /** Normalize version with fallback. */\n  let normalizedVersion = normalizeVersionPrefix(resolvedPackageVersion);\n\n  normalizedVersion = isNonEmptyString(normalizedVersion)\n    ? normalizedVersion\n    : normalizeVersionPrefix(PACKAGE_META.version);\n\n  /** Build default formatted CLI title. */\n  const defaultTitleFormatted = joinInline(\n    picocolors.blueBright(\n      (isNonEmptyString(_internal.packageName)\n        ? _internal.packageName\n        : PACKAGE_META.name) +\n        \"@\" +\n        normalizedVersion\n    ),\n    isDiffCommandName\n      ? `${picocolors.magentaBright(ICONS.arrowRight)} ${picocolors.yellowBright(resolvedCliName)}`\n      : false\n  );\n\n  /** Resolve dynamic usage string. */\n  const dynamicUsage = isNonEmptyString(_internal.manualUsage)\n    ? _internal.manualUsage\n    : isNonEmptyString(_internal.ui?.usage)\n      ? _internal.ui.usage\n      : (isDiffCommandName\n          ? `${picocolors.cyanBright(resolvedCliName)} `\n          : \"\") +\n        (isNonEmptyString(program.usage())\n          ? styleUsage(\n              reorderUsage(program.usage(), {\n                errorConfig: {\n                  field: \"`program.usage()`\",\n                  context:\n                    \"resolveCliPresentationMeta (by `program.usage()` at const variable 'dynamicUsage')\"\n                }\n              }),\n              {\n                errorConfig: {\n                  field: \"`reorderUsage(program.usage())`\",\n                  context:\n                    \"resolveCliPresentationMeta (by `reorderUsage(program.usage())` at const variable 'dynamicUsage')\"\n                }\n              }\n            )\n          : \"\");\n\n  /** Resolve Package name. */\n  const resolvedPackageName = isNonEmptyString(packageName)\n    ? packageName\n    : PACKAGE_META.name;\n\n  /** Resolve Package name with formatted colors. */\n  const resolvedPackageNameFormatted = `${picocolors.blueBright(resolvedPackageName)}${isDiffCommandName ? ` ${picocolors.cyanBright(`(${resolvedCliName})`)}` : \"\"}`;\n\n  /** Resolve help metadata. */\n  const helpMeta = _internal.help;\n  const isHelpDisabled = helpMeta?.disabled === true;\n  const helpFlags = helpMeta?.flags ?? FLAGS.HELP;\n  const helpDesc = helpMeta?.description ?? DESCRIPTIONS.HELP;\n\n  return Object.freeze({\n    resolvedCliName,\n    resolvedPackageName,\n    resolvedPackageNameFormatted,\n    isDiffCommandName,\n    commandTitle,\n    normalizedVersion,\n    defaultTitleFormatted,\n    dynamicUsage,\n    help: {\n      meta: helpMeta,\n      disabled: isHelpDisabled,\n      flags: helpFlags,\n      description: helpDesc\n    }\n  });\n}\n","import \"@rzl-zone/node-only\";\n\nimport type { CommandContext, CommanderUiOptions } from \"@/commander-kit/types\";\n\nimport { Command } from \"commander\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\nimport { joinLinesLoose, picocolors, ConfigurationError } from \"@/utils/client\";\n\nimport { resolveCliPresentationMeta } from \"../_internal/helpers/apply-commander-ui\";\nimport { composeVersionDescription } from \"../_internal/helpers/versions\";\n\nimport { interceptHelp } from \"../_internal/interceptor/help\";\nimport { installParseVersionInterceptor } from \"../_internal/interceptor/install-parse-version\";\nimport { interceptUsage } from \"../_internal/interceptor/usage\";\nimport { interceptVersion } from \"../_internal/interceptor/version\";\n\nimport { StyledHelp } from \"../_internal/help/styled-help\";\nimport { getInternalState, setInternalUiState } from \"../_internal/state\";\n\nimport { CliCommand } from \"../core/command\";\nimport { handleCommanderExit } from \"../lifecycle/handle-commander-exit\";\nimport {\n  CommandBaseProgram,\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  createBaseProgram\n} from \"../factories/create-base-program\";\n\n/** ------------------------------------------------------------------------\n * * Applies a structured UI layer to a Commander.js program instance.\n * ------------------------------------------------------------------------\n *\n * Enhances a Commander program by installing a standardized UI layer\n * for error rendering and presentation formatting.\n *\n * This function is primarily intended for native\n * {@link Command | `Command`} instances created directly\n * from Commander (e.g. `new Command()` or an imported `program` singleton).\n *\n * Programs created via\n * {@link createBaseProgram | `createBaseProgram()`}\n * already include the structured UI layer by default, in such cases, calling\n * this function is typically unnecessary and **redundant interception** also\n * is **not recommended**.\n *\n * ------------------------------------------------------------------------\n * #### Supported Program Types.\n * ------------------------------------------------------------------------\n *\n * **1.** Factory-based:\n *  ```ts\n *    import {\n *      applyCommanderUi,\n *      createBaseProgram\n *    } from \"@rzl-zone/build-tools/commander-kit\";\n *\n *    const programFactory = createBaseProgram();\n *    const program = applyCommanderUi(programFactory);\n *  ```\n *\n * **2.** Native Commander instance:\n *  ```ts\n *    import { Command } from \"commander\"\n *    import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n *    const nativeProgram = new Command();\n *    const program = applyCommanderUi(nativeProgram);\n *  ```\n *\n * When used with {@link createBaseProgram | `createBaseProgram`}, certain\n * interception steps are skipped because the factory already installs baseline\n * behavior and internal state wiring.\n *\n * When used with a plain {@link Command | `Command`} instance created directly\n * from Commander (e.g. `new Command()` or an imported `program` singleton), this\n * function installs all required interception and metadata tracking layers.\n *\n * - *In short:*\n *       - Programs created via `createBaseProgram()` already include\n *         foundational behavior.\n *       - Native Commander instances are fully instrumented by this function.\n *\n * ------------------------------------------------------------------------\n * #### Factory Integration.\n * ------------------------------------------------------------------------\n *\n * Programs created via {@link createBaseProgram | `createBaseProgram()`}\n * already include the structured UI layer by default.\n *\n * In such cases, calling `applyCommanderUi()` manually is unnecessary\n * and generally not recommended.\n *\n * - ***The factory installs:***\n *       - Internal state wiring.\n *       - Error interception.\n *       - Help customization.\n *       - Version handling lifecycle.\n *\n * ***`applyCommanderUi()` primarily exists to instrument native\n * {@link Command | `Command`}, or {@link CliCommand | `CliCommand`}\n * instances that were not created through the factory.***\n *\n * If the program instance was created via **`createBaseProgram()`**,\n * the **UI layer** is **already installed**, **reapplying** this function may\n * result in **redundant interception** and is **not recommended**.\n *\n * ------------------------------------------------------------------------\n * #### Installed UI Layer.\n * ------------------------------------------------------------------------\n *\n * This function standardizes:\n *\n * - Error message formatting.\n * - Header rendering.\n * - Usage resolution.\n * - Help hint presentation.\n * - Version interception.\n *\n * The goal is to provide a consistent, styled CLI output surface\n * independent of Commander’s default formatting.\n *\n * ------------------------------------------------------------------------\n * #### Internal Mutations.\n * ------------------------------------------------------------------------\n *\n * This function performs the following mutations on the provided\n * `program` instance:\n *\n * - Overrides `.error()`.\n * - Installs `.exitOverride()`.\n * - Replaces `.createHelp()`.\n * - Intercepts manual:\n *    - `.usage()` calls.\n *    - `.helpOption()` calls.\n *    - `.version()` calls.\n *\n * These interceptions allow internal metadata tracking without\n * relying on Commander private properties.\n *\n * ------------------------------------------------------------------------\n * #### Usage Resolution Order.\n * ------------------------------------------------------------------------\n *\n * When rendering usage inside error output, the value is resolved\n * in the following priority:\n *\n *   1. Manual `.usage()` override (intercepted internally).\n *   2. UI `options.usage`.\n *   3. Commander default usage string.\n *\n * ------------------------------------------------------------------------\n * #### ℹ️ Help Hint Handling.\n * ------------------------------------------------------------------------\n *\n * If `.helpOption(false)` is used, the help hint line\n * (`Run -h, --help`) will not be displayed.\n *\n * Help metadata is internally tracked and does not depend on\n * Commander private state.\n *\n * ------------------------------------------------------------------------\n * #### ⚠️ Important Behavior Notes.\n * ------------------------------------------------------------------------\n *\n * - This function **mutates** the provided program instance.\n * - It replaces Commander’s default error handler.\n * - The process exits with code `1` after rendering an error.\n * - The function is not strictly idempotent and should only be\n *   applied once per program instance.\n *\n * ------------------------------------------------------------------------\n *\n * @param program - A Commander program instance, this can be either:\n * - A program created via {@link createBaseProgram | `createBaseProgram`}, or\n * - A native {@link Command | `Command`}, or {@link CliCommand | `CliCommand`} instance (e.g. `new Command()`. `new CliCommand()` or an imported `program`/`cliProgram` singleton).\n *\n * @param options - Optional UI configuration.\n *\n * @throws {ConfigurationError}\n * Thrown when `program` is not a valid Commander program instance.\n *\n * ------------------------------------------------------------------------\n *\n * @example\n * Using a native Commander instance (manual installation required):\n * ```ts\n * import { Command } from \"commander\"\n * import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const nativeProgram = new Command();\n *\n * const program = applyCommanderUi(nativeProgram, {\n *   title: \"Custom CLI\",\n *   version: \"1.1.0\",\n *   packageName: \"my-package-name\"\n * });\n *\n * program.parse();\n * ```\n *\n * @example\n * Using the factory (UI layer already installed):\n * ```ts\n * import { createBaseProgram } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const program = createBaseProgram({\n *   commandIdentity: identity,\n *   ui: {\n *     title: \"My CLI Tool\",\n *     usage: \"my-cli <command> [options]\"\n *   }\n * });\n *\n * program.parse();\n * ```\n *\n * @example\n * Manual usage override takes priority:\n * ```ts\n * import { CliCommand, applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const programCli = new CliCommand();\n *\n * programCli\n *   .name(\"my-cli\")\n *   .usage(\"<input> [options]\");\n *\n * // Apply default UI helpers\n * const program = applyCommanderUi(programCli, {\n *   usage: \"fallback usage (will NOT be used)\",\n * });\n *\n * // Rendered usage will be:\n * // my-cli <input> [options]\n *\n * // In this case the manual `.usage()` call defined before\n * // `applyCommanderUi()` takes precedence.\n *\n * // The usage string provided to `applyCommanderUi()` will\n * // be ignored if a custom usage has already been configured.\n * ```\n *\n * @example\n * Disable help hint line:\n * ```ts\n * import { Command } from \"commander\"\n * import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const nativeProgram = new Command();\n *\n * const program = applyCommanderUi(nativeProgram);\n *\n * program.helpOption(false);\n * // Disables the help option and prevents the \"Run -h, --help\" hint\n * // from appearing in error messages.\n *\n * program.version(false);\n * // Disables the version command automatically configured by\n * // `applyCommanderUi()` or `createBaseProgram()`.\n * ```\n *\n * @example\n * Minimal setup for native Commander:\n * ```ts\n * import { Command } from \"commander\"\n * import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const nativeProgram = new Command();\n * const program = applyCommanderUi(nativeProgram);\n *\n * program.parse();\n * ```\n */\nexport function applyCommanderUi(\n  program: CommandBaseProgram,\n  options: CommanderUiOptions\n): CommandBaseProgram;\nexport function applyCommanderUi(\n  program: CliCommand | Command,\n  options: CommanderUiOptions\n): CliCommand;\nexport function applyCommanderUi(\n  program: unknown,\n  options: CommanderUiOptions\n): never;\nexport function applyCommanderUi(\n  program: unknown,\n  options: CommanderUiOptions\n): CommandContext {\n  const { title, usage, version, packageName, __commandName } = options;\n\n  if (\n    !isExactInstanceOf(program, Command) &&\n    !isExactInstanceOf(program, CliCommand) &&\n    !isExactInstanceOf(program, CommandBaseProgram)\n  ) {\n    throw ConfigurationError.type(\n      \"program\",\n      \"instanceof Command, CliCommand or create by factory function 'createBaseProgram'\",\n      program,\n      \"applyCommanderUi\"\n    );\n  }\n\n  setInternalUiState(program, { title, usage });\n\n  if (!isExactInstanceOf(program, CommandBaseProgram)) {\n    const {\n      commandTitle,\n      defaultTitleFormatted,\n      normalizedVersion,\n      resolvedPackageNameFormatted\n    } = resolveCliPresentationMeta({\n      program: program,\n      commandName: __commandName,\n      version,\n      packageName,\n      title\n    });\n\n    //todo: Intercept manual .usage()\n    interceptUsage(program);\n    //todo: Intercept manual .helpOption()\n    interceptHelp(program);\n    //todo: Intercept manual .version()\n    interceptVersion(\n      program,\n      composeVersionDescription(resolvedPackageNameFormatted)\n    );\n\n    program.createHelp = () => new StyledHelp();\n\n    program.addHelpText(\n      \"before\",\n      joinLinesLoose(\"\", commandTitle ?? defaultTitleFormatted, \"\")\n    );\n\n    program.exitOverride(handleCommanderExit);\n\n    installParseVersionInterceptor(program, {\n      versionInjection: {\n        normalizedVersion,\n        pkgNameFormatted: resolvedPackageNameFormatted\n      }\n    });\n  }\n\n  // Intercept ALL commander validation errors\n  program.error = function (message) {\n    let errMsg = message.replace(/^error:\\s*/i, \"\");\n    errMsg = errMsg.trim().replace(/\\.*$/, \"\") + \".\";\n\n    const { disableUsage } = getInternalState(program);\n\n    const { defaultTitleFormatted, dynamicUsage, help } =\n      resolveCliPresentationMeta({\n        program: program,\n        title,\n        commandName: __commandName\n      });\n\n    const printOut = [\n      isNonEmptyString(title) ? title : defaultTitleFormatted,\n      \"\",\n      `${picocolors.bold(`${picocolors.red(`${ICONS.error} Error`)}`)} ${picocolors.redBright(errMsg)}`\n    ];\n\n    if (!disableUsage && isNonEmptyString(dynamicUsage)) {\n      printOut.push(\n        \"\",\n        picocolors.bold(\"Usage:\"),\n        `  ${picocolors.reset(picocolors.gray(dynamicUsage))}`\n      );\n    }\n\n    if (!help.disabled) {\n      printOut.push(\n        \"\",\n        `${picocolors.dim(\"Run\")} ${picocolors.cyanBright(help.flags)} ${picocolors.dim(help.description)}`\n      );\n    }\n\n    console.error(joinLinesLoose(...printOut));\n\n    process.exit(1);\n  };\n\n  return program;\n}\n","import { CliCommand } from \"./command\";\n\n/** ----------------------------------------------------------------\n * * ***Default CLI program instance.***\n * ----------------------------------------------------------------\n *\n * Shared CLI program instance created from\n * {@link CliCommand | **`CliCommand`**}.\n *\n * This module-level singleton provides a convenient\n * default program object for simple CLI tools without\n * manually creating a command instance.\n *\n * ----------------------------------------------------------------\n *\n * Equivalent to:\n *\n * ```ts\n * import { CliCommand } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const cliProgram = new CliCommand();\n * ```\n */\nexport const cliProgram: CliCommand = new CliCommand();\n","import type { CommanderErrorCode } from \"@/commander-kit/types\";\n\nimport { CommanderError } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Commander base error class.***\n * ----------------------------------------------------------------\n *\n * Base error thrown internally by Commander when CLI\n * parsing or execution fails.\n */\nexport class CliCommanderError extends CommanderError {\n  constructor(exitCode: number, code: CommanderErrorCode, message: string) {\n    super(exitCode, code, message);\n  }\n}\n","import { InvalidArgumentError } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Error thrown when an argument fails validation.***\n * ----------------------------------------------------------------\n */\nexport class CliInvalidArgumentError extends InvalidArgumentError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n","import { InvalidOptionArgumentError } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Error thrown when an option argument fails validation.***\n * ----------------------------------------------------------------\n */\nexport class CliInvalidOptionArgumentError extends InvalidOptionArgumentError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n","import { Argument } from \"commander\";\n\nimport { CliArgument } from \"@/commander-kit/core/argument\";\n\n/** ----------------------------------------------------------------\n * * ***CLI Argument Factory.***\n * ----------------------------------------------------------------\n *\n * Creates a new {@link CliArgument | **`CliArgument`**} instance.\n *\n * This helper constructs a CLI argument definition compatible with\n * Commander argument parsing while providing a consistent creation\n * entry point within the framework.\n *\n * @param name Argument definition string (e.g. `<file>` or `[dir]`).\n * @param description Optional argument description used in help output.\n *\n * @returns A newly created {@link CliArgument | **`CliArgument`**} instance.\n */\nexport const cliCreateArgument = (\n  name: string,\n  description?: string\n): CliArgument => new CliArgument(name, description);\n\n/** @deprecated `Un-Used`. */\nexport type ArgumentType = Argument;\n","import { Command } from \"commander\";\n\nimport { CliCommand } from \"../core/command\";\n\n/** ----------------------------------------------------------------\n * * ***CLI Command Factory.***\n * ----------------------------------------------------------------\n *\n * Creates a new {@link CliCommand | **`CliCommand`**} instance.\n *\n * This helper acts as a small factory for constructing command\n * objects used by the CLI framework. It ensures all commands are\n * created through the same entry point, which allows future\n * extensions (such as internal metadata attachment or lifecycle\n * hooks) without changing call sites.\n *\n * @param name Optional command name.\n *\n * @returns A newly created {@link CliCommand | **`CliCommand`**} instance.\n */\nexport const cliCreateCommand = (name?: string): CliCommand =>\n  new CliCommand(name);\n\n/** @deprecated `Un-Used`. */\nexport type CommandType = Command;\n","import { Option } from \"commander\";\nimport { CliOption } from \"../core/option\";\n\n/** ----------------------------------------------------------------\n * * ***CLI Option Factory.***\n * ----------------------------------------------------------------\n *\n * Creates a new {@link CliOption | **`CliOption`**} instance.\n *\n * This helper constructs a CLI option definition compatible with\n * Commander option parsing while ensuring a consistent factory\n * entry point for option creation within the framework.\n *\n * @param arg Option flags definition\n * (e.g. `\"-p, --port <number>\"`).\n *\n * @param description Optional description displayed in help output.\n *\n * @returns A newly created {@link CliOption | **`CliOption`**} instance.\n */\nexport const cliCreateOption = (arg: string, description?: string): CliOption =>\n  new CliOption(arg, description);\n\n/** @deprecated `Un-Used`. */\nexport type OptionType = Option;\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["DESCRIPTIONS","FLAGS","FLAGS","DESCRIPTIONS","FLAGS"],"sources":["../../src/commander-kit/errors/isCommanderError.ts","../../src/commander-kit/errors/format-commander-error.ts","../../src/commander-kit/errors/get-commander-error-code.ts","../../src/commander-kit/core/command.ts","../../src/commander-kit/lifecycle/handle-commander-exit.ts","../../src/utils/helper/class-check.ts","../../src/commander-kit/core/help.ts","../../src/commander-kit/core/option.ts","../../src/_internal/utils/symbol/index.ts","../../src/commander-kit/_internal/state.ts","../../src/commander-kit/_internal/helpers/usages.ts","../../src/commander-kit/_internal/help/styled-help.ts","../../src/commander-kit/_internal/helpers/error-formatters.ts","../../src/commander-kit/_internal/interceptor/usage.ts","../../src/commander-kit/constants/index.ts","../../src/commander-kit/_internal/interceptor/help.ts","../../src/commander-kit/_internal/interceptor/version.ts","../../src/commander-kit/core/argument.ts","../../src/commander-kit/_internal/helpers/versions.ts","../../src/commander-kit/_internal/helpers/base-program.ts","../../src/commander-kit/_internal/interceptor/install-parse-version.ts","../../src/commander-kit/factories/create-base-program.ts","../../src/commander-kit/_internal/helpers/apply-commander-ui.ts","../../src/commander-kit/ui/apply-commander-ui.ts","../../src/commander-kit/core/program.ts","../../src/commander-kit/errors/cli/commander-error.ts","../../src/commander-kit/errors/cli/invalid-argument-error.ts","../../src/commander-kit/errors/cli/invalid-option-argument-error.ts","../../src/commander-kit/factories/create-argument.ts","../../src/commander-kit/factories/create-command.ts","../../src/commander-kit/factories/create-option.ts"],"sourcesContent":["import type { TypedCommanderError } from \"@/commander-kit/types\";\n\nimport { CommanderError } from \"commander\";\n\n/** ------------------------------------------------------------------------\n * * Runtime type guard for {@link CommanderError | `CommanderError`}.\n * ------------------------------------------------------------------------\n *\n * Determines whether a given unknown value is an instance of\n * {@link CommanderError | `CommanderError`} and **narrows the `code` property** to the\n * library-specific {@link CommanderErrorCode | `CommanderErrorCode`} union type.\n *\n * This helper exists because the upstream Commander type defines\n * `CommanderError.code` as a plain `string`.\n *\n * As a result, TypeScript cannot automatically infer the narrowed error code type when using\n * `instanceof CommanderError`.\n *\n * By using this guard, consumers can safely treat the error as a\n * `CommanderError` with a strongly typed `code` value.\n *\n * ------------------------------------------------------------------------\n * #### Behavior\n * ------------------------------------------------------------------------\n *\n * - Returns **`true`** if `err` is an instance of {@link CommanderError | `CommanderError`}.\n * - When `true`, the value is narrowed to:\n *    `CommanderError & { code: CommanderErrorCode }`\n *\n * - Returns **`false`** for all other values.\n *\n * This enables safe access to `err.code` with the expected\n * {@link CommanderErrorCode | `CommanderErrorCode`} union type.\n *\n * ------------------------------------------------------------------------\n * @param err - The value to test.\n *\n * @returns `true` if the value is a {@link CommanderError | `CommanderError`}; otherwise `false`.\n *\n * ------------------------------------------------------------------------\n * @example\n * ```ts\n * try {\n *   program.parse();\n * } catch (err) {\n *   if (isCommanderError(err)) {\n *     // err.code is now typed as CommanderErrorCode\n *     return err.code;\n *   }\n *\n *   console.error(String(err));\n *   process.exit(1);\n * }\n * ```\n */\nexport function isCommanderError(err: unknown): err is TypedCommanderError {\n  return err instanceof CommanderError;\n}\n\n/** @deprecated */\nexport type CommanderErrorInstanceType = CommanderError;\n","import { CommanderError } from \"commander\";\n\n/** ------------------------------------------------------------------------\n * * Formats a Commander error into a human-readable message.\n * ------------------------------------------------------------------------\n *\n * Converts an unknown error value into a formatted CLI-friendly\n * message string.\n *\n * If the value is a {@link CommanderError | `CommanderError`}, the message is extracted\n * directly from the error instance. Otherwise, the value is converted\n * to a string representation.\n *\n * This helper is typically used when rendering CLI error output before\n * terminating the process.\n *\n * ------------------------------------------------------------------------\n * #### Behavior\n * ------------------------------------------------------------------------\n *\n * - If the value is a {@link CommanderError | `CommanderError`}, returns `err.message`.\n * - Otherwise returns `String(err)`.\n *\n * ------------------------------------------------------------------------\n * @param err - The error value to format.\n *\n * @returns A human-readable message string.\n *\n * ------------------------------------------------------------------------\n * @example\n * ```ts\n * console.error(formatCommanderError(err));\n * process.exit(1);\n * ```\n */\nexport function formatCommanderError(err: unknown): string {\n  if (err instanceof CommanderError) return err.message;\n\n  return String(err);\n}\n","import type { CommanderErrorCode } from \"@/commander-kit/types\";\n\nimport { CommanderError } from \"commander\";\n\n/** ------------------------------------------------------------------------\n * * Extracts the Commander error code from an unknown value.\n * ------------------------------------------------------------------------\n *\n * Safely resolves the {@link CommanderErrorCode | `CommanderErrorCode`} from a value that may\n * or may not be a {@link CommanderError | `CommanderError`}.\n *\n * This helper is useful when handling errors originating from the\n * Commander CLI runtime, where the error code indicates the type of\n * internal CLI condition (for example help display or version output).\n *\n * If the provided value is not a {@link CommanderError | `CommanderError`}, `null`\n * is returned.\n *\n * ------------------------------------------------------------------------\n * #### Behavior\n * ------------------------------------------------------------------------\n *\n * - Returns the narrowed {@link CommanderErrorCode | `CommanderErrorCode`} if the value is a\n *   {@link CommanderError | `CommanderError`}.\n * - Returns `null` for all other values.\n *\n * ------------------------------------------------------------------------\n * @param err - The value to inspect.\n *\n * @returns The resolved {@link CommanderErrorCode | `CommanderErrorCode`}, or `null`\n * if the value is not a {@link CommanderError | `CommanderError`}.\n *\n * ------------------------------------------------------------------------\n * @example\n * ```ts\n * const code = getCommanderErrorCode(err);\n *\n * if (code) {\n *   return code;\n * }\n * ```\n */\nexport function getCommanderErrorCode(err: unknown): CommanderErrorCode | null {\n  if (err instanceof CommanderError) return err.code;\n\n  return null;\n}\n","import { Command } from \"commander\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\n/** ----------------------------------------------------------------\n * * ***CLI command definition class.***\n * ----------------------------------------------------------------\n *\n * Primary building block used to define CLI programs and\n * subcommands.\n *\n * This class extends Commander’s {@link Command | **`Command`**} class and\n * adds additional behavior and type safety used by\n * this library.\n *\n * Importing this class from this module ensures that\n * the additional type definitions and helpers provided\n * by this library are available.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * import { CliCommand } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const program = new CliCommand();\n *\n * program\n *   .name(\"my-cli\")\n *   .description(\"Example CLI program\");\n *\n * program.parse();\n * ```\n */\nexport class CliCommand extends Command {\n  /** ----------------------------------------------------------------\n   * * ***Create a new CLI command instance.***\n   * ----------------------------------------------------------------\n   *\n   * @param name Optional command name.\n   *\n   * If the provided value is not a non-empty string,\n   * the command will be created without an explicit name.\n   */\n  constructor(name?: string) {\n    name = isNonEmptyString(name) ? name : undefined;\n    super(name);\n  }\n\n  /** Set or disable the command usage string.\n   *\n   * This overrides the default usage generated from the command\n   * metadata (such as the command name, arguments, and options).\n   *\n   * - Passing a **non-empty string** sets a custom usage value.\n   * - Passing **`false`** disables usage output entirely for this\n   *   command (including help and error rendering when supported\n   *   by the CLI framework integration).\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty custom usage string, or `false`\n   * to disable usage output.\n   *\n   * @returns The current command instance for chaining.\n   *\n   * @throws Thrown if the provided usage value is an empty string or\n   * not a valid non-empty string.\n   *\n   * @example\n   * program.usage(\"build [options]\");\n   *\n   * @example\n   * program.usage(false);\n   */\n  override usage(str: string | false): this;\n  /** Get the resolved command usage string.\n   *\n   * If a custom usage was previously set using {@link Command.usage | `usage`},\n   * that value will be returned. Otherwise the usage string\n   * generated by Commander will be returned.\n   *\n   * @returns The current usage string for this command.\n   */\n  override usage(): string;\n  override usage(str?: string | false): this | string {\n    if (str === false) {\n      super.usage(\"\");\n      return this;\n    }\n\n    if (!isNonEmptyString(str)) {\n      return super.usage();\n    }\n\n    return super.usage(str);\n  }\n\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: string, flags?: string, description?: string): this;\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: false): this;\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: false, flags?: never): this;\n  /** Set or disable the program version.\n   *\n   * This method configures the version value for the CLI program and\n   * automatically registers the `\"-v, --version\"` flag which prints\n   * the version when invoked.\n   *\n   * Behavior depends on the value passed:\n   *\n   * - Passing a **non-empty string** sets the program version.\n   * - Passing **`false`** disables the version flag entirely.\n   *\n   * When providing custom `flags` or `description`, they must also be\n   * **non-empty strings**.\n   *\n   * An **empty string is not allowed** and will cause a configuration\n   * error to be thrown.\n   *\n   * @param str A non-empty version string, or `false` to disable\n   * the version flag.\n   *\n   * @param flags Optional custom version flags (e.g. `\"-V, --version\"`).\n   *\n   * @param description Optional description for the version flag.\n   *\n   * @returns The current program instance for chaining.\n   *\n   * @throws Thrown if `str`, `flags`, or `description` are provided\n   * as empty strings or invalid values.\n   *\n   * @example\n   * program.version(\"1.0.0\");\n   *\n   * @example\n   * program.version(\"1.0.0\", \"-V, --version\", \"print version\");\n   *\n   * @example\n   * program.version(false);\n   */\n  override version(str: false, flags?: never, description?: never): this;\n  /** Get the program version.\n   *\n   * Returns the currently configured version string.\n   *\n   * If the version was disabled using {@link Command.version | `version(false)`},\n   * this method returns `undefined`.\n   *\n   * @returns The current program version string if set.\n   */\n  override version(): string | undefined;\n  override version(str?: string | false, flags?: string, description?: string) {\n    if (str === false) {\n      super.version(\"\");\n      return this;\n    }\n\n    if (!isNonEmptyString(str)) {\n      return super.version();\n    }\n\n    return super.version(str, flags, description);\n  }\n}\n","import \"@rzl-zone/node-only\";\n\nimport { CliCommand } from \"../core/command\";\nimport { isCommanderError } from \"../errors/isCommanderError\";\n\n/** ----------------------------------------------------------------\n * * ***Centralized exit handler for Commander.js ({@link CliCommand.exitOverride | `exitOverride`}).***\n * ----------------------------------------------------------------\n *\n * Handles all process termination logic when using Commander’s {@link CliCommand.exitOverride | `.exitOverride()`}  method.\n *\n * This helper normalizes Commander’s exception-based control flow\n * into predictable and user-friendly CLI behavior.\n *\n * ----------------------------------------------------------------\n * - *Behavior:*\n *     - Exits the process with code `0` when:\n *        - Commander triggers `helpDisplayed`.\n *        - Commander triggers `version`.\n *     - Prints error messages for real CLI or runtime failures.\n *     - Ensures correct and consistent exit codes.\n * ----------------------------------------------------------------\n * - *This prevents:*\n *     - Duplicate output (e.g. version printed twice).\n *     - Treating help/version as fatal errors.\n *     - Copy-pasted exit logic across multiple CLI entry points.\n * ----------------------------------------------------------------\n * - ⚠️ **Important:**\n *     - This function **always terminates the process**.\n *     - Intended to be passed directly into `program.exitOverride`.\n *     - Should NOT be used outside a CLI execution context.\n * ----------------------------------------------------------------\n *\n * @param err - The error object thrown by Commander or runtime logic.\n *\n * ----------------------------------------------------------------\n * @example\n * Using existing commander program instance:\n * ```ts\n * import { Command, program } from \"commander\"\n *\n * program.exitOverride(handleCommanderExit);\n * program.parse(process.argv);\n * ```\n *\n * @example\n * Using manually created command instance:\n * ```ts\n * import { Command } from \"commander\"\n *\n * const cmd = new Command();\n * cmd.exitOverride(handleCommanderExit);\n * cmd.parse(process.argv);\n * ```\n * @example\n * Using factory helper:\n * ```ts\n * import { createBaseProgram } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * // Recommended usage (factory pattern)\n * const program = createBaseProgram();\n * program.parse(process.argv);\n * ```\n */\nexport function handleCommanderExit(err: unknown): never {\n  // Commander or runtime error\n  if (isCommanderError(err)) {\n    const code = err.code;\n\n    // Non-error exits (help / version)\n    if (code === \"commander.helpDisplayed\" || code === \"commander.version\") {\n      process.exit(0);\n    }\n\n    // console.error(err.message);\n    process.exit(err.exitCode ?? 1);\n  }\n\n  // Unknown thrown value\n  console.error(err);\n  process.exit(1);\n}\n\n/**\n * @deprecated Used for `tsDoc` only.\n */\nexport type CliCommandInstance = CliCommand;\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** -------------------------------------------------------\n * * ***Utility Type: `AnyConstructor`.***\n * -------------------------------------------------------\n *\n * Represents any constructable type (class or abstract class).\n *\n * This type matches values that can be invoked with `new`\n * and produce an instance of type `T`.\n *\n * - ***Behavior summary:***\n *       - Supports concrete classes.\n *       - Supports abstract classes.\n *       - Does NOT match non-constructable functions.\n *\n * ----------------------------------------------------------------\n *\n * @template T - The instance type produced by the constructor.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * class A {}\n * abstract class B {}\n *\n * type C1 = AnyConstructor<A>;\n * type C2 = AnyConstructor<B>;\n *\n * function create<T>(ctor: AnyConstructor<T>): T {\n *   return new ctor();\n * }\n * ```\n */\ntype AnyConstructor<T = any> = abstract new (...args: any[]) => T;\n\n/** -------------------------------------------------------\n * * ***Utility Type: `ConcreteConstructor`.***\n * -------------------------------------------------------\n *\n * Represents a concrete constructable type (class constructor).\n *\n * This type matches values that can be invoked with `new`\n * and produce an instance of type `T`.\n *\n * - ***Behavior summary:***\n *       - Supports standard class constructors.\n *       - Does NOT include abstract constructors.\n *       - Does NOT match non-constructable functions.\n *\n * ----------------------------------------------------------------\n *\n * @template T - The instance type produced by the constructor.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * class A {}\n *\n * function create<T>(ctor: ConcreteConstructor<T>): T {\n *   return new ctor();\n * }\n * ```\n */\ntype ConcreteConstructor<T = any> = new (...args: any[]) => T;\n\n/** ----------------------------------------------------------------\n * * ***Checks whether a value shares a prototype in its chain.***\n * ----------------------------------------------------------------\n *\n * Determines whether the prototype derived from `target`\n * exists anywhere within `value`'s prototype chain.\n *\n * This function performs a manual prototype-chain walk and\n * does NOT rely on native `instanceof`.\n *\n * - Ignores custom `Symbol.hasInstance` overrides.\n * - Uses strict reference equality (`===`) for comparison.\n * - Fully deterministic and unaffected by constructor property changes.\n *\n * ----------------------------------------------------------------\n * #### Supported Target Types:\n * ----------------------------------------------------------------\n * - Constructor functions ➔ uses `ctor.prototype`.\n * - Object instances      ➔ uses `Object.getPrototypeOf(target)`.\n *\n * If `target` itself has a null prototype\n * (e.g., `Object.create(null)`), the function returns `false`.\n *\n * ----------------------------------------------------------------\n * #### Important Behavior:\n * ----------------------------------------------------------------\n * - Primitive values (`string`, `number`, `boolean`, `symbol`,\n *   `bigint`, `null`, `undefined`) always return `false`.\n *\n * - Values with a null prototype (e.g., `Object.create(null)`)\n *   always return `false`.\n *\n * - Passing `{}` as `target` effectively checks for\n *   `Object.prototype` in the prototype chain.\n *\n * ----------------------------------------------------------------\n *\n * @param value  - The value whose prototype chain will be inspected.\n * @param target - A constructor or object whose derived prototype\n *                 will be searched for in `value`'s prototype chain.\n *\n * @returns `true` if the prototype derived from `target`\n * exists anywhere in `value`'s prototype chain.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A {}\n * class B extends A {}\n *\n * const b = new B();\n *\n * hasSamePrototype(b, A);         // ➔ true\n * hasSamePrototype(b, new A());   // ➔ true\n * hasSamePrototype(b, URL);       // ➔ false\n * hasSamePrototype(b, new URL()); // ➔ false\n *\n * // Matches Object.prototype\n * hasSamePrototype(b, {});        // ➔ true\n *\n * // Null-prototype object\n * const nullObj = Object.create(null);\n * hasSamePrototype(nullObj, {});  // ➔ false\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n * This check relies on strict prototype reference equality.\n *\n * Objects created in a different JavaScript realm\n * (e.g., iframe, VM context, worker) will NOT match,\n * even if they appear structurally identical.\n */\nexport function hasSamePrototype(\n  value: unknown,\n  target: object | AnyConstructor<any>\n): boolean {\n  //! Reject primitive values: prototype chains only exist on object-like entities\n  if (\n    value === null ||\n    (typeof value !== \"object\" && typeof value !== \"function\")\n  ) {\n    return false;\n  }\n\n  //todo: Normalize target prototype reference:\n  //? If function, use .prototype; if instance, use its direct prototype via Object.getPrototypeOf.\n  const targetProto =\n    typeof target === \"function\"\n      ? target.prototype\n      : Object.getPrototypeOf(target);\n\n  //! Safety guard: If target has no prototype (e.g., Object.create(null)), match is impossible\n  if (!targetProto) return false;\n\n  //? Initial Step: Access the immediate prototype of the input value\n  let proto = Object.getPrototypeOf(value);\n\n  //todo: Traversal Loop: Walk the prototype chain until the end (null) is reached\n  while (proto !== null) {\n    //? Identity Match: Check if the current prototype in the chain strictly equals the target prototype\n    if (proto === targetProto) return true;\n\n    //todo: Link Propagation: Move upward to the next parent prototype in the inheritance hierarchy\n    //todo: This effectively performs a manual recursive search without using the stack.\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  //? Termination: The entire chain was exhausted without finding a reference match\n  return false;\n}\n\n/** ----------------------------------------------------------------\n * * ***Deterministic alternative to `instanceof`.***\n * ----------------------------------------------------------------\n *\n * Checks whether `ctor.prototype` exists anywhere in\n * `value`'s prototype chain.\n *\n * - ***Unlike native `instanceof`, this implementation:***\n *       - Does NOT use `instanceof`.\n *       - Ignores `Symbol.hasInstance`.\n *       - Cannot be affected by overriding Symbol.hasInstance.\n *\n * - ***Subclasses are allowed.***\n *\n * - Values with a null prototype (e.g., `Object.create(null)`) will\n * always return false.\n *\n * ----------------------------------------------------------------\n *\n * @param value - The value to test.\n * @param ctor - The constructor to compare against.\n *\n * @returns `true` if `value` is an instance of `ctor`\n * or any subclass of it.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A extends Error {}\n * class B extends A {}\n *\n * const b = new B();\n *\n * isInstanceOf(b, A); // ➔ true\n * isInstanceOf(b, B); // ➔ true\n * isInstanceOf(b, Error); // ➔ true\n * isInstanceOf(b, URL); // ➔ false\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *  This check relies on strict prototype reference equality.\n *\n *  Objects created in a different JavaScript realm\n *  (e.g., iframe, VM context, worker) will NOT match,\n *  even if they appear structurally identical.\n */\nexport function isInstanceOf<T>(\n  value: unknown,\n  ctor: AnyConstructor<T>\n): value is T {\n  //! Constraint: Primitives do not have prototype chains and cannot be instances\n  if (\n    value === null ||\n    (typeof value !== \"object\" && typeof value !== \"function\")\n  ) {\n    return false;\n  }\n\n  //? Initial Step: Access the immediate prototype of the instance\n  let proto = Object.getPrototypeOf(value);\n\n  //? Reference Point: Capture the constructor's prototype to search for in the chain also\n  //? take for ensures check is unaffected by Symbol.hasInstance overrides\n  const targetProto = ctor.prototype;\n\n  //todo: Traversal Loop: Walk the prototype chain manually to bypass Symbol.hasInstance overrides\n  while (proto !== null) {\n    //? Identity Match: Check if any link in the chain strictly equals the constructor's prototype\n    if (proto === targetProto) return true;\n\n    //todo: Link Propagation: Move upward to the next parent prototype in the inheritance hierarchy\n    //todo: This continues until a match is found or the chain terminates at null.\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  //? Termination: The target prototype was not found within the value's inheritance chain\n  return false;\n}\n\n/** ----------------------------------------------------------------\n * * ***Checks whether one constructor extends another.***\n * ----------------------------------------------------------------\n *\n * Determines whether `child` inherits from `parent`\n * by walking the prototype chain of `child.prototype`.\n *\n * This implementation is deterministic and does NOT rely\n * on `instanceof`.\n *\n * ----------------------------------------------------------------\n *\n * @param child - The derived constructor.\n * @param parent - The base constructor.\n *\n * @returns `true` if `child` extends `parent`.\n *\n * A constructor is NOT considered a subclass of itself.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A extends URL {}\n * class B extends A {}\n *\n * isSubclassOf(B, A); // ➔ true\n * isSubclassOf(B, URL); // ➔ true\n * isSubclassOf(A, B); // ➔ false\n * isSubclassOf(A, A); // ➔ false\n * isSubclassOf(B, B); // ➔ false\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *  This check relies on strict prototype reference equality.\n *\n *  Objects created in a different JavaScript realm\n *  (e.g., iframe, VM context, worker) will NOT match,\n *  even if they appear structurally identical.\n */\nexport function isSubclassOf<T, U>(\n  child: AnyConstructor<T>,\n  parent: AnyConstructor<U>\n): boolean {\n  //? Entry point: Start from the child constructor's prototype parent.\n  //? This ensures a constructor is NOT considered a subclass of itself.\n  let proto = Object.getPrototypeOf(child.prototype);\n\n  //todo: Inheritance Traversal: Walk the prototype chain to find the parent's prototype.\n  while (proto !== null) {\n    //? Inheritance Match: Check if the parent's prototype is an ancestor of the child's prototype.\n    if (proto === parent.prototype) return true;\n    //todo: Link Propagation: Move upward to the next parent prototype in the inheritance hierarchy.\n    //todo: This continues until a match is found or the chain terminates at null.\n    proto = Object.getPrototypeOf(proto);\n  }\n\n  //? Termination: The parent prototype was not found in the child's inheritance chain.\n  return false;\n}\n\n/** ----------------------------------------------------------------\n * * ***Checks for an exact constructor match.***\n * ----------------------------------------------------------------\n *\n * Determines whether `value` was created directly by `ctor`.\n *\n * - ***Unlike `isInstanceOf`, this function:***\n *       - Does NOT allow subclasses.\n *       - Requires the immediate prototype of `value`\n *         to strictly equal `ctor.prototype`.\n *\n * - ***This check is deterministic and immune to:***\n *       - `Symbol.hasInstance`.\n *       - `.constructor` property manipulation.\n *\n * Values with a null prototype (e.g., `Object.create(null)`) will\n * always return false.\n *\n * ----------------------------------------------------------------\n *\n * @param value - The value to test.\n * @param ctor - The constructor to match exactly.\n *\n * @returns `true` if `value` is an exact instance of `ctor`.\n *\n * ----------------------------------------------------------------\n * @example\n * ```ts\n * class A {}\n * class B extends A {}\n *\n * const b = new B();\n *\n * isExactInstanceOf(b, B); // ➔ true\n * isExactInstanceOf(b, A); // ➔ false\n *\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *  This check relies on strict prototype reference equality.\n *\n *  Objects created in a different JavaScript realm\n *  (e.g., iframe, VM context, worker) will NOT match,\n *  even if they appear structurally identical.\n */\nexport function isExactInstanceOf<T>(\n  value: unknown,\n  ctor: AnyConstructor<T>\n): value is T {\n  //! Constraint: Immediately reject primitives\n  if (\n    value === null ||\n    (typeof value !== \"object\" && typeof value !== \"function\")\n  ) {\n    return false;\n  }\n\n  //todo: Strict Direct Comparison: Verify if the immediate prototype is exactly the constructor's prototype.\n  //todo: This effectively ignores parent classes in the chain, preventing subclass matches.\n  return Object.getPrototypeOf(value) === ctor.prototype;\n}\n\n/** ----------------------------------------------------------------\n * * ***Checks whether a value is a class constructor.***\n * ----------------------------------------------------------------\n *\n * Determines whether the provided value is highly likely to be an\n * ES6 class constructor using multi-layer structural heuristics.\n *\n * - Uses `Function.prototype.toString` signature inspection.\n * - Validates prototype structural integrity.\n * - Supports native class constructors and standard class syntax.\n * ----------------------------------------------------------------\n * #### ⚠️ Important Behavior:\n * ----------------------------------------------------------------\n * - This function is a heuristic classifier, not a cryptographic or\n *   mathematically provable validator.\n *\n * - Runtime JavaScript does not provide a perfect mechanism to\n *   distinguish class constructors from function constructors.\n *\n * - Proxy-wrapped constructors or maliciously monkey-patched functions\n *   may bypass detection under adversarial environments.\n *\n * ----------------------------------------------------------------\n * #### Supported Class Forms:\n * ----------------------------------------------------------------\n * - Native ES6 class syntax:\n *   ```ts\n *      class A {}\n *   ```\n *\n * - Native built-in constructors:\n *    - `Map`.\n *    - `Set`.\n *    - `Error`.\n *    - `Promise`.\n *\n * - Transpiled class outputs (if structural signals remain intact).\n *\n * ----------------------------------------------------------------\n *\n * #### Detection Strategy Summary:\n *\n * - Checks function construct-ability.\n * - Inspects source signature via `Function.prototype.toString`.\n * - Validates prototype linkage consistency.\n * - Ensures constructor reflexive integrity.\n * - Verifies prototype descriptor identity.\n *\n * ----------------------------------------------------------------\n *\n * @param value - The value to be tested.\n *\n * @returns `true` if the value is likely a class constructor.\n *\n * ----------------------------------------------------------------\n *\n * @example\n * ```ts\n * class A {}\n * function B() {}\n *\n * isClass(A); // ➔ true\n * isClass(B); // ➔ false\n *\n * const arr = Array;\n * isClass(arr); // ➔ true (native constructor)\n * ```\n *\n * ----------------------------------------------------------------\n *\n * @note\n *\n * This function is intended for runtime utility validation and should\n * not be used as the sole security boundary in adversarial systems.\n *\n * Objects created in different JavaScript realms (e.g., iframe,\n * worker, VM context) may not be detected even if structurally similar.\n */\n//? Overload 1: Preserve original type when variable type is already known\nexport function isClass<T>(value: T): value is T & ConcreteConstructor;\n//? Overload 2: For unknown/any input type\nexport function isClass(value: unknown): value is ConcreteConstructor;\n//? Implementation\nexport function isClass(value: unknown): boolean {\n  //! Requirement: Must be a function to even be a candidate for a constructor\n  if (typeof value !== \"function\") return false;\n\n  let fnStr: string;\n\n  //todo: Source Acquisition: Safely obtain the function's source code representation\n  try {\n    fnStr = Function.prototype.toString.call(value);\n  } catch {\n    //! Safety Guard: If toString fails (e.g. on certain Proxy types), reject immediately\n    return false;\n  }\n\n  //? Signature Detection: Look for explicit 'class' keyword or engine-level native signatures also\n  //? detect ES6 class syntax or native constructor signature\n  const isClassSyntax = /^class[\\s{]/.test(fnStr);\n  const isNative = fnStr.includes(\"[native code]\");\n\n  //! Logic Boundary: If it lacks both ES6 class syntax and native constructor markers, reject as regular function\n  //! also Reject ordinary functions that are not constructable class-like entities\n  if (!isClassSyntax && !isNative) return false;\n\n  //? Integrity Check: Every constructor must have a valid prototype object linkage\n  const proto = value.prototype;\n\n  //! Validity constructor must have valid prototype object\n  if (!proto || typeof proto !== \"object\") return false;\n\n  try {\n    //todo - Reflexive Integrity: Ensure the prototype has a 'constructor' property pointing back to itself\n    if (!Object.prototype.hasOwnProperty.call(proto, \"constructor\"))\n      return false;\n\n    //! Identity Verification: The back-reference must strictly equal the original function\n    if (proto.constructor !== value) return false;\n  } catch {\n    //! Panic Guard: Catch errors from potential 'poisoned' prototypes or proxy traps\n    return false;\n  }\n\n  //? Descriptor Validation: Retrieve the underlying property configuration for 'prototype' and structural integrity\n  const descriptor = Object.getOwnPropertyDescriptor(value, \"prototype\");\n\n  //! Reference Matching: Ensure the descriptor's value is the exact same object as the prototype link\n  if (!descriptor || descriptor.value !== proto) return false;\n\n  //! NOTE:\n  //! Native class constructors (e.g. Map, Set, Promise, Error)\n  //! may have non-writable prototype properties.\n  //!\n  //! Therefore, checking descriptor.value identity is sufficient\n  //! to confirm structural integrity without enforcing write-ability.\n  return true;\n}\n","import { Help } from \"commander\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { CliCommand } from \"./command\";\n\n/** ----------------------------------------------------------------\n * * ***Commander help system class.***\n * ----------------------------------------------------------------\n *\n * Extends Commander’s {@link Help | **`Help`**} class\n * and allows customization of CLI help output,\n * formatting behavior, and command listing.\n *\n * This class can be used to override the default\n * help renderer used by {@link CliCommand | `CliCommand`}.\n */\nexport class CliHelp extends Help {\n  constructor() {\n    super();\n  }\n}\n","import { Option } from \"commander\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { CliCommand } from \"./command\";\n\n/** ----------------------------------------------------------------\n * * ***Command-line option definition class.***\n * ----------------------------------------------------------------\n *\n * Represents a CLI option or flag definition.\n *\n * This class extends Commander’s {@link Option | **`Option`**}\n * and provides the standard option behavior used\n * by {@link CliCommand | `CliCommand`}.\n *\n * - ***Supports:***\n *       - short and long flags.\n *       - default values.\n *       - variadic arguments.\n *       - custom parsing logic.\n */\nexport class CliOption extends Option {\n  constructor(arg: string, description?: string) {\n    super(arg, description);\n  }\n}\n","import type { SymbolRegistry, SymbolSafeConstructor } from \"./types\";\n\nconst hasSymbolConstructor =\n  typeof Symbol === \"function\" &&\n  typeof Symbol(\"x\") === \"symbol\" &&\n  typeof Symbol.for === \"function\" &&\n  typeof Symbol.keyFor === \"function\";\n\n/** ------------------------------------------------------------------------\n * * Global registry key used to store fallback symbol mappings.\n * ------------------------------------------------------------------------\n *\n * In environments where native `Symbol.for()` is unavailable,\n * a shared registry object is attached to the global scope.\n *\n * This constant represents the property name used to store that\n * registry on the global object.\n *\n * The registry ensures that multiple calls to `SymbolSafe.for(key)`\n * return the same value across modules.\n *\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nconst REGISTRY_KEY = \"__rzl_global_symbol_registry__\";\n\n/** ------------------------------------------------------------------------\n * * Resolves the current global execution context.\n * ------------------------------------------------------------------------\n *\n * Returns a reference to the global object regardless of runtime\n * environment.\n *\n * This helper supports multiple JavaScript environments:\n *\n * - `globalThis` (modern standard)\n * - `self` (Web Workers)\n * - `window` (browsers)\n * - `global` (Node.js)\n *\n * If none are available, a new object is returned as a fallback.\n *\n * ------------------------------------------------------------------------\n *\n * @returns The detected global object.\n *\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction getGlobal(): any {\n  if (typeof globalThis !== \"undefined\") return globalThis;\n  if (typeof self !== \"undefined\") return self;\n  if (typeof window !== \"undefined\") return window;\n  if (typeof global !== \"undefined\") return global;\n  return {};\n}\n\n/** ------------------------------------------------------------------------\n * * Generates a pseudo-unique identifier.\n * ------------------------------------------------------------------------\n *\n * Creates a collision-resistant identifier used internally when\n * generating fallback symbol-like keys in environments without\n * native `Symbol` support.\n *\n * The identifier combines:\n *\n * - two randomized base36 segments\n * - a timestamp component\n *\n * This ensures a sufficiently unique value for runtime property keys.\n *\n * ------------------------------------------------------------------------\n *\n * @returns A pseudo-unique identifier string.\n *\n * @internal\n */\nfunction createUID() {\n  return (\n    Math.random().toString(36).slice(2) +\n    Math.random().toString(36).slice(2) +\n    Date.now().toString(36)\n  );\n}\n\n/** ------------------------------------------------------------------------\n * * Creates a unique symbol-like key.\n * ------------------------------------------------------------------------\n *\n * Generates a **unique property key** similar to `Symbol(description)`.\n *\n * Runtime behavior depends on environment support:\n *\n * **Modern environments**\n * - Delegates to `Symbol(description)`.\n *\n * **Legacy environments (ES5)**\n * - Returns a unique string identifier in the format:\n *\n * ```\n * `@@rzl/local/<description>/<unique-id>`\n * ```\n *\n * Each invocation returns a **distinct value**.\n *\n * ------------------------------------------------------------------------\n *\n * @param desc - Optional symbol description used for debugging.\n *\n * @returns A unique `PropertyKey`.\n *\n * @internal\n */\nfunction createLocalSymbol(desc?: string | number) {\n  if (hasSymbolConstructor) {\n    return Symbol(desc);\n  }\n\n  return \"@@rzl/local/\" + (desc ?? \"\") + \"/\" + createUID();\n}\n\n/** ------------------------------------------------------------------------\n * * Resolves or creates a global symbol-like key.\n * ------------------------------------------------------------------------\n *\n * Provides behavior equivalent to `Symbol.for(key)`.\n *\n * Runtime strategy:\n *\n * **Modern environments**\n * - Delegates directly to `Symbol.for(key)`.\n *\n * **Legacy environments**\n * - Uses a shared registry stored on the global object.\n * - The registry ensures stable key reuse across modules.\n *\n * Fallback format:\n *\n * ```\n * `@@rzl/global/<key>/<unique-id>`\n * ```\n *\n * Subsequent calls with the same `key` return the same value.\n *\n * ------------------------------------------------------------------------\n *\n * @param key - Global registry identifier.\n *\n * @returns A stable `PropertyKey`.\n *\n * @internal\n */\nfunction createGlobalSymbol(key: string) {\n  if (hasSymbolConstructor) {\n    return Symbol.for(key);\n  }\n\n  const registry = getRegistry();\n\n  if (registry.byKey[key]) {\n    return registry.byKey[key] as unknown as symbol;\n  }\n  const value = \"@@rzl/global/\" + key + \"/\" + createUID();\n\n  registry.byKey[key] = value;\n  registry.byValue.set(value, key);\n\n  return value as unknown as symbol;\n}\n\n/** ------------------------------------------------------------------------\n * * Retrieves or initializes the global symbol registry store.\n * ------------------------------------------------------------------------\n *\n * The registry is stored on the global execution context and is used to\n * maintain stable mappings between registry keys and symbol-like property\n * values.\n *\n * Registry Structure:\n *\n * ```ts\n * interface SymbolRegistry {\n *   byKey: Record<string, PropertyKey>;\n *   byValue: Map<PropertyKey, string>;\n * }\n * ```\n *\n * - `byKey`\n *     - Maps registry identifier strings ➔ generated property keys.\n *     - Enables O(1) lookup when resolving global symbols by name.\n *\n * - `byValue`\n *     - Reverse mapping from property key ➔ registry identifier.\n *     - Enables O(1) implementation of `keyFor()`-style resolution.\n *\n * Behavior:\n *\n * - If the registry does not exist on the global object, it will be\n *   initialized automatically.\n *\n * - The registry is shared across modules within the same runtime\n *   context.\n *\n * - The registry uses `Object.create(null)` to avoid prototype pollution\n *   and accidental key shadowing.\n *\n * ------------------------------------------------------------------------\n *\n * @returns\n * The global symbol registry instance.\n *\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nfunction getRegistry() {\n  const g = getGlobal();\n\n  if (!g[REGISTRY_KEY]) {\n    g[REGISTRY_KEY] = {\n      byKey: Object.create(null),\n      byValue: new Map()\n    } as SymbolRegistry;\n  }\n\n  return g[REGISTRY_KEY] as SymbolRegistry;\n}\n\n/** ------------------------------------------------------------------------\n * * ***SymbolSafe runtime implementation.***\n * ------------------------------------------------------------------------\n *\n * TypeScript identity preservation note:\n *\n * When using SymbolSafe, consumers may optionally apply self-referential\n * assertions to preserve symbol identity narrowing.\n *\n * Recommended pattern example:\n *\n * ```ts\n * const KEY: unique symbol = SymbolSafe(\"key\") as typeof KEY;\n * const MySimbol: unique symbol = SymbolSafe(\"my-symbol\") as typeof MySimbol;\n * const MyGlobalSimbol: unique symbol = SymbolSafe.for(\"my-global-symbol\") as typeof MyGlobalSimbol;\n * ```\n *\n * This pattern allows TypeScript to approximate native `Symbol` intrinsic\n * inference behavior for custom symbol factory functions.\n *\n * Usage of explicit `unique symbol` annotations is optional and should\n * only be used when strict identity narrowing is required.\n *\n * ------------------------------------------------------------------------\n *\n * The exported `SymbolSafe` object behaves like a function while exposing\n * the `for()` method for global registry access.\n *\n * This mirrors the behavior of the native `Symbol` API.\n *\n * ------------------------------------------------------------------------\n *\n * @example\n *\n * Creating unique symbol-like values\n *\n * ```ts\n * const INTERNAL: unique symbol = SymbolSafe(\"internal\") as typeof INTERNAL;\n *\n * const obj: Record<PropertyKey, unknown> = {};\n *\n * obj[INTERNAL] = { debug: true };\n *\n * console.log(obj[INTERNAL]);\n * ```\n *\n * ------------------------------------------------------------------------\n *\n * @example\n *\n * Using global registry symbols\n *\n * ```ts\n * const ROUTER_KEY: unique symbol = SymbolSafe.for(\"rzl:router.instance\") as typeof ROUTER_KEY;\n * const CACHE_KEY: unique symbol = SymbolSafe.for(\"rzl:cache.token\") as typeof CACHE_KEY;\n *\n * console.log(ROUTER_KEY === CACHE_KEY); // false\n *\n * const ROUTER_A: unique symbol = SymbolSafe.for(\"rzl:router.instance\") as typeof ROUTER_A;\n * const ROUTER_B: unique symbol = SymbolSafe.for(\"rzl:router.instance\") as typeof ROUTER_B;\n *\n * console.log(ROUTER_A === ROUTER_B); // true\n * ```\n *\n * ------------------------------------------------------------------------\n */\nexport const SymbolSafe: SymbolSafeConstructor = Object.assign(\n  function SymbolSafe(description?: string | number) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return createLocalSymbol(description) as any;\n  },\n  {\n    for(key: string) {\n      return createGlobalSymbol(key);\n    },\n\n    keyFor(sym: symbol) {\n      if (hasSymbolConstructor && typeof sym === \"symbol\") {\n        return Symbol.keyFor(sym);\n      }\n\n      const registry = getRegistry();\n      return registry.byValue.get(sym);\n    }\n  }\n);\n","// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { Command } from \"commander\";\n\nimport type {\n  CommandContext,\n  CommanderInternalState,\n  CommanderUiOptions\n} from \"@/commander-kit/types\";\nimport type { OmitStrict } from \"@/_internal/types/extra\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { applyCommanderUi } from \"@/commander-kit/ui/apply-commander-ui\";\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { createBaseProgram } from \"@/commander-kit/factories/create-base-program\";\n\nimport { SymbolSafe } from \"@/_internal/utils/symbol\";\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport { CommandBaseProgram } from \"@/commander-kit/factories/create-base-program\";\n\n/** ------------------------------------------------------------------------\n * * Internal Commander state marker symbol.\n * ------------------------------------------------------------------------\n *\n * Unique symbol used to attach and retrieve internal metadata\n * from Commander program instances.\n *\n * This symbol serves as a hidden state key for native\n * {@link Command | `Command`} instances, allowing the library\n * to store internal lifecycle data without relying on\n * Commander private properties.\n *\n * For {@link createBaseProgram | `createBaseProgram()`} instances and {@link applyCommanderUi | `applyCommanderUi`},\n * internal state is managed directly by the factory and does not\n * rely on symbol attachment.\n *\n * ------------------------------------------------------------------------\n * #### **🔒 Visibility.**\n * ------------------------------------------------------------------------\n *\n * This symbol is strictly internal and is not part of the public API,\n * consumers must not access, mutate, or depend on it.\n *\n * ------------------------------------------------------------------------\n * @internal\n */\nexport const COMMANDER_INTERNAL_SYMBOL: unique symbol = SymbolSafe(\n  \"rzl-built-tools:commander.internal\"\n) as typeof COMMANDER_INTERNAL_SYMBOL;\n\n/** ------------------------------------------------------------------------\n * * Creates a fresh Commander internal state object.\n * ------------------------------------------------------------------------\n *\n * Generates a fully initialized internal state container used to\n * track UI configuration, help metadata, usage overrides,\n * and version interception flags.\n *\n * This state object is attached to a Commander instance\n * (either native or factory-based) and acts as the single source\n * of truth for runtime UI lifecycle behavior.\n *\n * ------------------------------------------------------------------------\n * #### State Responsibilities.\n * ------------------------------------------------------------------------\n *\n * The returned object stores:\n *\n * - UI configuration metadata.\n * - Help option interception data.\n * - Manual `.usage()` overrides.\n * - Version string overrides.\n * - Version injection flags.\n *\n * All properties are initialized to safe defaults.\n *\n * ------------------------------------------------------------------------\n *\n * @returns A fresh {@link CommanderInternalState | `CommanderInternalState`} object.\n *\n * @internal\n */\nexport function createDefaultInternalState() {\n  return {\n    ui: undefined,\n    help: undefined,\n    packageName: undefined,\n    manualUsage: undefined,\n    disableUsage: false,\n    versionMeta: undefined,\n    versionInjected: false,\n    versionDisable: false,\n    versionOriginal: undefined,\n    versionSetByUser: false\n  } satisfies CommanderInternalState;\n}\n\n/** ------------------------------------------------------------------------\n * * Resets and reinitializes a program's internal Commander state.\n * ------------------------------------------------------------------------\n *\n * Discards any existing internal metadata attached to the provided\n * program instance and replaces it with a newly created default state.\n *\n * This ensures a clean lifecycle baseline.\n *\n * ------------------------------------------------------------------------\n * #### Behavior.\n * ------------------------------------------------------------------------\n *\n * - If the program is a {@link CommandBaseProgram | `CommandBaseProgram`},\n *   the state is set via its internal setter.\n *\n * - If the program is a native {@link Command | `Command`},\n *   the state is attached using the internal symbol marker.\n *\n * The previous state (if any) is permanently discarded.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - A Commander program instance.\n * @returns The newly created internal state object.\n *\n * @internal\n */\nexport const resetAllCommandInternal = (\n  cmd: CommandContext\n): CommanderInternalState => {\n  const fresh = createDefaultInternalState();\n\n  // Factory program\n  if (\"_internalState\" in cmd && \"_setInternalState\" in cmd) {\n    cmd._setInternalState(fresh);\n    return fresh;\n  }\n\n  // Commander / CliCommand\n  cmd[COMMANDER_INTERNAL_SYMBOL] = fresh;\n\n  return fresh;\n};\n\n/** ------------------------------------------------------------------------\n * * Retrieves the internal Commander state for a program instance.\n * ------------------------------------------------------------------------\n *\n * Returns the internal state associated with the provided program.\n *\n * If no state is currently attached, a new one is created,\n * attached to the program, and returned automatically.\n *\n * This guarantees that a valid internal state object\n * is always returned.\n *\n * ------------------------------------------------------------------------\n * #### 🔄 Lazy Initialization.\n * ------------------------------------------------------------------------\n *\n * This function performs lazy state installation:\n *\n * - If a state exists ➔ it is returned as-is.\n * - If no state exists ➔ a new state is created and attached.\n *\n * This avoids reliance on Commander private internals\n * while ensuring consistent metadata tracking.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - A Commander program instance.\n * @returns The resolved {@link CommanderInternalState | `CommanderInternalState`}.\n *\n * @internal\n */\nexport function getInternalState(cmd: CommandContext): CommanderInternalState {\n  // Factory program\n  if (\"_internalState\" in cmd && \"_setInternalState\" in cmd) {\n    let state = cmd._internalState;\n\n    if (!state) {\n      state = resetAllCommandInternal(cmd);\n      cmd._setInternalState(state);\n    }\n\n    return state;\n  }\n\n  // Commander / CliCommand\n  if (!cmd[COMMANDER_INTERNAL_SYMBOL]) {\n    cmd[COMMANDER_INTERNAL_SYMBOL] = resetAllCommandInternal(cmd);\n  }\n\n  return cmd[COMMANDER_INTERNAL_SYMBOL];\n}\n\ntype CreateUIState = OmitStrict<CommanderUiOptions, \"__commandName\">;\n\n/** ------------------------------------------------------------------------\n * * ***Safely patches internal `ui` state on a Commander instance.***\n * ------------------------------------------------------------------------\n *\n * Applies sanitized UI configuration (via {@link createUIState | `createUIState`})\n * directly into the command's internal state.\n *\n * - *This function:*\n *    - Delegates validation to `createUIState`.\n *    - Preserves existing `ui` properties.\n *    - Lazily initializes `ui` if missing.\n *    - Does NOT overwrite unrelated fields.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - Command instance.\n * @param input - Raw UI configuration.\n *\n * @example\n * ```ts\n * setInternalUiState(cmd, { title, usage });\n * ```\n *\n * @internal\n */\nexport function setInternalUiState(\n  cmd: CommandContext,\n  input: CreateUIState\n): void {\n  const internal = getInternalState(cmd);\n  const sanitized = createUIState(input);\n\n  if (!internal.ui) {\n    internal.ui = sanitized;\n    return;\n  }\n\n  Object.assign(internal.ui, sanitized);\n}\n\n/** ------------------------------------------------------------------------\n * * ***Creates a sanitized `UI` configuration object.***\n * ------------------------------------------------------------------------\n *\n * Builds a partial `UI` state object by conditionally including only\n * valid non-empty string values.\n *\n * - *This helper is intended for internal CLI framework usage where\n * `title` and `usage` must:*\n *    - Be a non-empty string.\n *    - Exclude empty string values.\n *    - Exclude `undefined`.\n *\n * - *Unlike naive object spreading with ternaries, this function ensures:*\n *    - No `undefined` properties are injected.\n *    - No accidental overwrites occur due to falsy values.\n *    - Output object only contains valid keys.\n *\n * ------------------------------------------------------------------------\n *\n * @param input - Partial UI input configuration.\n *\n * @returns A sanitized partial UI object containing only valid properties.\n *\n * @example\n * ```ts\n * const ui = createUIState({ title, usage });\n *\n * internal.ui = {\n *   ...internal.ui,\n *   ...ui\n * };\n * ```\n *\n * @remarks\n * This function performs validation using `isNonEmptyString`, it does\n * not mutate input.\n *\n * @throws Nothing.\n *\n * @internal\n */\nexport function createUIState(input: CreateUIState): CreateUIState {\n  const result: CreateUIState = {};\n\n  if (isNonEmptyString(input.title)) {\n    result.title = input.title;\n  }\n\n  if (isNonEmptyString(input.usage)) {\n    result.usage = input.usage;\n  }\n\n  if (isNonEmptyString(input.packageName)) {\n    result.packageName = input.packageName;\n  }\n\n  if (isNonEmptyString(input.version)) {\n    result.version = input.version;\n  }\n\n  return result;\n}\n","import { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { ConfigurationError, picocolors } from \"@/utils/client\";\n\n/** ----------------------------------------------------------------\n * * Styles a Commander-generated usage string.\n * ----------------------------------------------------------------\n *\n * Applies color formatting to tokens produced by the default\n * Commander `.usage()` output.\n *\n * The input string is tokenized by whitespace and each segment\n * is conditionally styled based on its semantic role.\n *\n * Styling rules:\n *\n * - The first token (typically the command name) is highlighted\n *   when `fromHelpCommandUsage` is enabled.\n * - `[options]` tokens are styled to indicate optional flags.\n * - `[command]` tokens are styled to indicate subcommands.\n * - Required arguments (`<arg>`) are dimmed.\n * - Optional arguments (`[arg]`) are dimmed.\n *\n * Tokens that do not match any rule are returned unchanged.\n *\n * ----------------------------------------------------------------\n * @param raw - The raw usage string generated by Commander.\n *\n * @param options - Optional formatting configuration.\n *\n * @param options.fromHelpCommandUsage\n * If `true`, the first token will be highlighted to represent\n * the command name in help output.\n *\n * @param options.errorConfig\n * Optional configuration used when constructing a\n * {@link ConfigurationError} if validation fails.\n *\n * ----------------------------------------------------------------\n * @returns The styled usage string with ANSI color formatting.\n *\n * @throws {ConfigurationError}\n * Thrown when `raw` is not a non-empty string.\n *\n * @internal\n */\nexport function styleUsage(\n  raw: string,\n  {\n    fromHelpCommandUsage,\n    errorConfig: {\n      field = \"raw\",\n      expected = \"a non-empty string\",\n      context = \"styleUsage\"\n    } = {}\n  }: {\n    /**\n     * @default false\n     */\n    fromHelpCommandUsage?: true;\n    errorConfig?: {\n      /**\n       * @default \"raw\"\n       */\n      field?: string;\n      /**\n       * @default \"a non-empty string\"\n       */\n      expected?: string;\n      /**\n       * @default \"styleUsage\"\n       */\n      context?: string;\n    };\n  } = {}\n) {\n  if (!isNonEmptyString(raw)) {\n    throw ConfigurationError.type(field, expected, raw, context);\n  }\n\n  return raw\n    .split(/\\s+/)\n    .map((token, index) => {\n      if (!!fromHelpCommandUsage && index === 0) {\n        return picocolors.cyanBright(token);\n      }\n\n      if (token === \"[options]\") {\n        return picocolors.blueBright(token);\n      }\n\n      if (token === \"[command]\") {\n        return picocolors.magentaBright(token);\n      }\n\n      if (token.startsWith(\"<\") && token.endsWith(\">\")) {\n        return picocolors.gray(token);\n      }\n\n      if (token.startsWith(\"[\") && token.endsWith(\"]\")) {\n        return picocolors.gray(token);\n      }\n\n      return token;\n    })\n    .join(\" \");\n}\n\n/** ----------------------------------------------------------------\n * * Normalizes Commander usage token order.\n * ----------------------------------------------------------------\n *\n * Reorders usage tokens so that the `[options]` segment\n * always appears **at the end of the usage string**.\n *\n * Commander may sometimes place `[options]` before other\n * tokens such as arguments or subcommands. This function\n * ensures a consistent ordering for CLI help output.\n *\n * Example:\n *\n * ```\n * input:  \"cli [options] <file>\"\n * output: \"cli <file> [options]\"\n * ```\n *\n * The function preserves the relative ordering of all\n * non-option tokens.\n *\n * ----------------------------------------------------------------\n * @param raw - The raw usage string generated by Commander.\n *\n * @param options - Optional validation configuration.\n *\n * @param options.errorConfig\n * Configuration used when constructing a\n * {@link ConfigurationError} if validation fails.\n *\n * ----------------------------------------------------------------\n * @returns The normalized usage string with `[options]`\n * positioned at the end.\n *\n * @throws {ConfigurationError}\n * Thrown when `raw` is not a non-empty string.\n *\n * @internal\n */\nexport function reorderUsage(\n  raw: string,\n  {\n    errorConfig: {\n      field = \"raw\",\n      expected = \"a non-empty string\",\n      context = \"reorderUsage\"\n    } = {}\n  }: {\n    errorConfig?: {\n      /**\n       * @default \"raw\"\n       */\n      field?: string;\n      /**\n       * @default \"a non-empty string\"\n       */\n      expected?: string;\n      /**\n       * @default \"reorderUsage\"\n       */\n      context?: string;\n    };\n  } = {}\n) {\n  if (!isNonEmptyString(raw)) {\n    throw ConfigurationError.type(field, expected, raw, context);\n  }\n\n  const tokens = raw.match(/\\S+/g) ?? []; //raw.split(/\\s+/);\n\n  const optionTokens = tokens.filter((t) => t === \"[options]\");\n  const otherTokens = tokens.filter((t) => t !== \"[options]\");\n\n  return [...otherTokens, ...optionTokens].join(\" \");\n}\n","import type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport {\n  EOL,\n  formatOptionValue,\n  joinLinesLoose,\n  picocolors\n} from \"@/utils/client\";\n\nimport { CliHelp } from \"@/commander-kit/core/help\";\nimport { CliOption } from \"@/commander-kit/core/option\";\n\nimport { getInternalState } from \"../state\";\nimport { reorderUsage, styleUsage } from \"../helpers/usages\";\n\n/** Internal for `.createHelp()`.\n *\n * @returns {CliHelp}\n *\n * @internal\n */\nexport class StyledHelp extends CliHelp {\n  constructor() {\n    super();\n  }\n\n  /** ----------------------------------------------------------------\n   * * Resolves the final usage string for a command.\n   * ----------------------------------------------------------------\n   *\n   * Determines the usage output by applying the following\n   * **priority order**:\n   *  1. Disabled usage (`disableUsage`).\n   *  2. Manually defined `.usage()` override.\n   *  3. UI configuration override (`ui.usage`).\n   *  4. Commander default usage formatting.\n   *\n   * If no manual or UI override is provided, the usage string\n   * returned by Commander is normalized and styled before being\n   * returned.\n   *\n   * ----------------------------------------------------------------\n   * @param cmd - The command instance whose usage should be resolved.\n   *\n   * @returns The resolved usage string, or an empty string if usage\n   * output is disabled.\n   */\n  commandUsage(cmd: CommandContext): string {\n    const { manualUsage, ui, disableUsage } = getInternalState(cmd);\n\n    if (disableUsage) return \"\";\n\n    // manual .usage()\n    if (isNonEmptyString(manualUsage)) return manualUsage;\n\n    // UI override\n    if (isNonEmptyString(ui?.usage)) return ui.usage;\n\n    // default Commander behavior\n    return styleUsage(\n      reorderUsage(super.commandUsage(cmd), {\n        errorConfig: {\n          field: \"`super.commandUsage(cmd)`\",\n          context: \"StyledHelp.commandUsage\"\n        }\n      }),\n      {\n        fromHelpCommandUsage: true,\n        errorConfig: {\n          field: \"`reorderUsage(super.commandUsage(cmd))`\",\n          context:\n            \"StyledHelp.commandUsage (by `reorderUsage(super.commandUsage(cmd))`)\"\n        }\n      }\n    );\n  }\n\n  /** ----------------------------------------------------------------\n   * - ***Custom Help formatter that:***\n   *       - Applies usage resolution priority.\n   *       - Ensures styled \"Usage:\" block replaces Commander default.\n   *\n   * This prevents conflicts between manual `.usage()` overrides\n   * and UI-defined usage formatting.\n   */\n  formatHelp(cmd: CommandContext, helper: CliHelp): string {\n    const usage = this.commandUsage(cmd);\n    const usageBlock = joinLinesLoose(picocolors.reset(\"Usage:\"), `  ${usage}`);\n    const rest = super.formatHelp(cmd, helper);\n\n    if (!usage) {\n      return rest.replace(/^Usage:[\\s\\S]*?\\n(?=\\S)/, \"\");\n    }\n\n    return rest.replace(/^Usage:[\\s\\S]*?\\n(?=\\S)/, usageBlock + EOL + EOL);\n  }\n\n  /** ----------------------------------------------------------------\n   * * Resolves the final usage string for a command.\n   * ----------------------------------------------------------------\n   *\n   * Determines the usage output by applying the following\n   * **priority order**:\n   *  1. Disabled usage (`disableUsage`).\n   *  2. Manually defined `.usage()` override.\n   *  3. UI configuration override (`ui.usage`).\n   *  4. Commander default usage formatting.\n   *\n   * If no manual or UI override is provided, the usage string\n   * returned by Commander is normalized and styled before being\n   * returned.\n   *\n   * ----------------------------------------------------------------\n   * @param cmd - The command instance whose usage should be resolved.\n   *\n   * @returns The resolved usage string, or an empty string if usage\n   * output is disabled.\n   */\n  optionDescription(option: CliOption) {\n    let desc = option.description || \"\";\n\n    const hasDefault = option.defaultValue !== undefined;\n\n    if (isNonEmptyString(desc)) {\n      desc = desc.trim();\n\n      if (hasDefault) {\n        if (desc.endsWith(\".\")) {\n          desc = desc.slice(0, -1) + \"\";\n        } else if (!desc.endsWith(\",\")) {\n          desc += \"\";\n        }\n\n        desc += ` ${picocolors.italic(`(default: ${formatOptionValue(option.defaultValue)})`)}.`;\n      } else {\n        if (!desc.trim().endsWith(\".\")) {\n          desc += \".\";\n        }\n      }\n    }\n\n    return desc;\n  }\n}\n","import type { CommandContext } from \"@/commander-kit/types\";\n\nimport { Command } from \"commander\";\n\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\n\nimport { CliCommand } from \"@/commander-kit/core/command\";\nimport { CommandBaseProgram } from \"@/commander-kit/factories/create-base-program\";\n\n/** ------------------------------------------------------------------------\n * * Resolves factory-origin error message suffix.\n * ------------------------------------------------------------------------\n *\n * Returns an additional error message suffix when the provided command\n * instance originates from the `createBaseProgram` factory.\n *\n * This helper is used to enrich internal error messages with contextual\n * information about how the command instance was constructed.\n *\n * If the command is not an instance of {@link CommandBaseProgram | `CommandBaseProgram`},\n * an empty string is returned.\n *\n * ------------------------------------------------------------------------\n *\n * @param programCommand - The command instance to inspect.\n *\n * @returns A formatted error message suffix indicating factory origin,\n * or an empty string if not applicable.\n *\n * @example\n * ```ts\n * throw new Error(\n *   `Invalid configuration${resolveFactoryOriginErrorSuffix(programCommand)}`\n * );\n * ```\n *\n * @internal\n */\nexport function resolveFactoryOriginErrorSuffix(\n  programCommand: CommandContext\n): string {\n  return isExactInstanceOf(programCommand, CommandBaseProgram)\n    ? \" by 'createBaseProgram' factory function\"\n    : \"\";\n}\n\n/** ------------------------------------------------------------------------\n * * Resolves an error message suffix based on the command instance type.\n * ------------------------------------------------------------------------\n *\n * Determines the concrete command class used to construct the provided\n * command instance and returns a short string identifier that can be\n * appended to error messages.\n *\n * This helper is primarily used internally to improve diagnostic output\n * by indicating which command implementation produced the error.\n *\n * The returned value is determined using strict runtime checks via\n * {@link isExactInstanceOf | `isExactInstanceOf`}.\n *\n * ------------------------------------------------------------------------\n * #### Resolution rules\n * ------------------------------------------------------------------------\n *\n * - Returns `\"Command\"` if the instance is exactly {@link Command | `Command`}.\n * - Returns `\"CliCommand\"` if the instance is exactly {@link CliCommand | `CliCommand`}.\n * - Returns an empty string (`\"\"`) for all other cases.\n *\n * ------------------------------------------------------------------------\n *\n * @param programCommand - The command instance to inspect.\n *\n * @returns\n * A string identifier representing the command class, or an empty\n * string if the instance does not match any supported command types.\n *\n * @example\n * ```ts\n * throw new Error(\n *   `Invalid configuration (${resolveInstanceOriginErrorSuffix(programCommand)})`\n * );\n * ```\n *\n * @internal\n */\nexport function resolveInstanceOriginErrorSuffix(\n  programCommand: CommandContext\n): string {\n  return isExactInstanceOf(programCommand, Command)\n    ? \"Command\"\n    : isExactInstanceOf(programCommand, CliCommand)\n      ? \"CliCommand\"\n      : \"\";\n}\n","import type { Command } from \"commander\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isNil, isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { ConfigurationError } from \"@/utils/errors\";\n\nimport {\n  resolveFactoryOriginErrorSuffix,\n  resolveInstanceOriginErrorSuffix\n} from \"@/commander-kit/_internal/helpers/error-formatters\";\nimport { getInternalState } from \"@/commander-kit/_internal/state\";\n\n/** ----------------------------------------------------------------\n * Intercepts `.usage()` calls to capture manual overrides\n * for later resolution inside `Help` and error output.\n *\n * This preserves original Commander behavior while allowing\n * custom resolution priority.\n *\n * ----------------------------------------------------------------\n * @internal\n */\nexport function interceptUsage(cmd: CommandContext) {\n  const originalUsage = cmd.usage.bind(cmd);\n\n  function usage(str: string | false): Command;\n  function usage(): string;\n  function usage(str?: string | false): string | Command {\n    if (!isNil(str)) {\n      // disable manual usage override\n      if (str === false) {\n        getInternalState(cmd).manualUsage = undefined;\n        getInternalState(cmd).disableUsage = true;\n\n        return cmd;\n      }\n\n      if (!isNonEmptyString(str)) {\n        const errorMessageByFactory = resolveFactoryOriginErrorSuffix(cmd);\n        const errorMessageInstance = resolveInstanceOriginErrorSuffix(cmd);\n\n        throw ConfigurationError.type(\n          \"usage\",\n          \"a non-empty string or `false` only\",\n          str,\n          `'${errorMessageInstance}.usage'${errorMessageByFactory}`\n        );\n      }\n\n      getInternalState(cmd).manualUsage = str;\n      return originalUsage(str);\n    }\n\n    return originalUsage();\n  }\n\n  cmd.usage = usage;\n}\n","import { deepFreeze } from \"@/_internal/utils/helper\";\n\n/** ------------------------------------------------------------------------\n * * ***Internal default configuration for the Commander UI layer.***\n * ------------------------------------------------------------------------\n *\n * Centralized constant registry containing baseline values used by\n * the structured UI system when enhancing Commander program instances.\n *\n * - **This object acts as the single source of truth for:**\n *    - Default flag signatures.\n *    - Default help descriptions.\n *    - Any future UI-level fallback values.\n *\n * - **These values are used when:**\n *    - The user does not explicitly override version flags.\n *    - The user does not explicitly override help flags.\n *    - Internal rendering requires safe fallback strings.\n *\n * ------------------------------------------------------------------------\n * #### ⚠️ Internal Contract.\n * ------------------------------------------------------------------------\n *\n * - This constant is not part of the public API.\n * - Its structure may change without notice.\n * - Consumers must not rely on its shape or values.\n *\n * Any external customization should be performed via the\n * public configuration surface (e.g. applyCommanderUi options),\n * not by mutating this object.\n *\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nexport const COMMANDER_UI_DEFAULTS = deepFreeze({\n  FLAGS: {\n    /** Default version flag signature.\n     *\n     * @returns `\"-v, --version\"`.\n     */\n    VERSION: \"-v, --version\",\n\n    /** Default help flag signature.\n     *\n     * @returns `\"-h, --help\"`.\n     */\n    HELP: \"-h, --help\"\n  },\n\n  DESCRIPTIONS: {\n    /** Default help option description text.\n     *\n     * @returns `\"To display help for this command.\"`.\n     */\n    HELP: \"To display help for this command.\",\n    /** Default version option description text.\n     *\n     * @returns `\"The version package of this command.\"`.\n     */\n    VERSION: \"The version package of this command.\"\n  }\n});\n","import type { Command } from \"commander\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isBoolean, isNil, isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport { ConfigurationError } from \"@/utils/errors\";\n\nimport {\n  resolveFactoryOriginErrorSuffix,\n  resolveInstanceOriginErrorSuffix\n} from \"@/commander-kit/_internal/helpers/error-formatters\";\nimport { getInternalState } from \"@/commander-kit/_internal/state\";\n\nimport { CliCommand } from \"@/commander-kit/core/command\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nconst { DESCRIPTIONS, FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** ----------------------------------------------------------------\n * Intercepts `.helpOption()` to track:\n *  - custom flags.\n *  - custom description.\n *  - disabled state.\n *\n * This enables UI-aware error rendering without accessing\n * Commander private properties.\n *\n * ----------------------------------------------------------------\n * @internal\n */\nexport function interceptHelp(cmd: CommandContext) {\n  function resetInternalHelpState(cmd: CommandContext) {\n    getInternalState(cmd).help = undefined;\n  }\n\n  const original = cmd.helpOption.bind(cmd);\n\n  cmd.helpOption = function (\n    flags?: string | boolean,\n    description?: string\n  ): CliCommand | Command {\n    const errorMessageByFactory = resolveFactoryOriginErrorSuffix(cmd);\n    const errorMessageInstance = resolveInstanceOriginErrorSuffix(cmd);\n\n    if (!isNil(flags) && !isNonEmptyString(flags) && !isBoolean(flags)) {\n      resetInternalHelpState(cmd);\n\n      throw ConfigurationError.type(\n        \"flags\",\n        \"a non-empty string or a boolean\",\n        flags,\n        `'${errorMessageInstance}.helpOption'${errorMessageByFactory}`\n      );\n    }\n\n    if (!isNil(description) && !isNonEmptyString(description)) {\n      resetInternalHelpState(cmd);\n\n      throw ConfigurationError.type(\n        \"description\",\n        \"a non-empty string if provided\",\n        description,\n        `'${errorMessageInstance}.helpOption'${errorMessageByFactory}`\n      );\n    }\n\n    const _decs = isNonEmptyString(description)\n      ? description\n      : DESCRIPTIONS.HELP;\n\n    if (flags === false) {\n      getInternalState(cmd).help = {\n        disabled: true\n      };\n      return original(flags);\n    }\n\n    if (flags === true) {\n      getInternalState(cmd).help = {\n        flags: FLAGS.HELP,\n        description: _decs,\n        disabled: false\n      };\n      return original(flags, _decs);\n    }\n\n    if (isNonEmptyString(flags)) {\n      getInternalState(cmd).help = {\n        flags,\n        description: _decs,\n        disabled: false\n      };\n      return original(flags, _decs);\n    }\n\n    return original(flags, _decs);\n  };\n}\n","import type { Command } from \"commander\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { isNil, isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport { ConfigurationError } from \"@/utils/errors\";\n\nimport {\n  resolveFactoryOriginErrorSuffix,\n  resolveInstanceOriginErrorSuffix\n} from \"@/commander-kit/_internal/helpers/error-formatters\";\nimport { getInternalState } from \"@/commander-kit/_internal/state\";\n\nimport { CliCommand } from \"@/commander-kit/core/command\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nconst { FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** ------------------------------------------------------------------------\n * * Intercepts `.version()` to capture manual overrides.\n * ------------------------------------------------------------------------\n *\n * Wraps the original Commander {@link CliCommand.version | `Command.version`}\n * method in order to:\n *\n * - Capture user-provided version metadata.\n * - Store it inside internal state.\n * - Preserve original Commander behavior.\n * - Enable custom resolution priority during presentation rendering.\n *\n * This interceptor allows `createBaseProgram`, `CliHelp`, and\n * error rendering layers to resolve version information lazily\n * and consistently — without relying on Commander’s internal\n * state alone.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Behavior:***\n *    - Preserves the original `.version()` binding.\n *    - Stores the original method reference in internal state as\n *      `versionOriginal`.\n *    - Supports both Commander overload signatures:\n *\n *      - Getter: `command.version()`.\n *      - Setter: `command.version(value, flags?, description?)`.\n *\n *    - Validates input types before delegating to Commander.\n *    - Injects default flags and description when omitted.\n *    - Marks `versionSetByUser = true` to influence resolution priority.\n *    - Delegates to the original Commander `.version()` implementation.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Resolution Priority Impact:***\n *    - **When this interceptor is installed, version resolution\n *      priority becomes:**\n *        1. User-set version via intercepted `.version()`.\n *        2. Factory-level version (from `createBaseProgram`).\n *        3. `package.json` version fallback.\n *\n *    - **This enables consistent and predictable version display across:**\n *        - Styled help output.\n *        - Header rendering.\n *        - Error messages.\n *        - Manual version flag execution.\n *\n * ------------------------------------------------------------------------\n *\n * - ***⚠️ Important Notes:***\n *    - Mutates the provided command instance.\n *    - Should only be installed once per command.\n *    - Designed strictly for internal orchestration.\n *    - Does not change Commander execution semantics.\n *\n * ------------------------------------------------------------------------\n *\n * @param cmd - Internal command instance to intercept.\n * @param versionDescription - Default description used when the user\n * does not provide one explicitly.\n *\n * @internal\n */\nexport function interceptVersion(\n  cmd: CommandContext,\n  versionDescription: string\n) {\n  const originalVersion = cmd.version.bind(cmd);\n\n  getInternalState(cmd).versionOriginal = originalVersion;\n\n  function version(\n    value: string,\n    flags?: string,\n    description?: string\n  ): CliCommand | Command;\n  function version(value: false): CliCommand | Command;\n  function version(): string | undefined;\n  function version(\n    value?: string | false,\n    flags?: string,\n    description?: string\n  ): CliCommand | Command | string | undefined {\n    if (arguments.length === 0) return originalVersion();\n\n    if (value === false) {\n      getInternalState(cmd).versionDisable = true;\n      // getInternalState(cmd).versionSetByUser = true;\n      getInternalState(cmd).versionOriginal = undefined;\n\n      return cmd;\n    }\n\n    const errorMessageByFactory = resolveFactoryOriginErrorSuffix(cmd);\n    const errorMessageInstance = resolveInstanceOriginErrorSuffix(cmd);\n\n    if (!isNonEmptyString(value)) {\n      throw ConfigurationError.type(\n        \"str\",\n        \"a non-empty string\",\n        value,\n        `'${errorMessageInstance}.version'${errorMessageByFactory}`\n      );\n    }\n\n    if (!isNil(flags) && !isNonEmptyString(flags)) {\n      throw ConfigurationError.type(\n        \"flags\",\n        \"a non-empty string if provided\",\n        flags,\n        `'${errorMessageInstance}.version'${errorMessageByFactory}`\n      );\n    }\n\n    if (!isNil(description) && !isNonEmptyString(description)) {\n      throw ConfigurationError.type(\n        \"description\",\n        \"a non-empty string if provided\",\n        description,\n        `'${errorMessageInstance}.version'${errorMessageByFactory}`\n      );\n    }\n\n    const _flag = isNonEmptyString(flags) ? flags : FLAGS.VERSION;\n    const _decs = isNonEmptyString(description)\n      ? description\n      : versionDescription;\n\n    getInternalState(cmd).versionMeta = {\n      value,\n      flags: _flag,\n      description: _decs\n    };\n\n    getInternalState(cmd).versionSetByUser = true;\n\n    return originalVersion(value, _flag, _decs);\n  }\n\n  cmd.version = version;\n}\n","import { Argument } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Command-line argument definition class.***\n * ----------------------------------------------------------------\n *\n * Represents a positional CLI argument definition.\n *\n * This class extends Commander’s {@link Argument | **`Argument`**}\n * and is provided to ensure compatibility with the\n * additional types and utilities exposed by this library.\n */\nexport class CliArgument extends Argument {\n  constructor(arg: string, description?: string) {\n    super(arg, description);\n  }\n}\n","import \"@rzl-zone/node-only\";\n\nimport type { CommandContext } from \"@/commander-kit/types\";\n\nimport { Argument } from \"commander\";\n\nimport {\n  isUndefined,\n  isNonEmptyString,\n  isNull,\n  isNil\n} from \"@/_internal/utils/helper\";\n\nimport {\n  ConfigurationError,\n  joinInline,\n  joinLinesLoose,\n  picocolors\n} from \"@/utils/client\";\nimport { ICONS } from \"@/utils/server\";\n\nimport { CliArgument } from \"@/commander-kit/core/argument\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nimport { getInternalState } from \"../state\";\n\nconst { DESCRIPTIONS, FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** ------------------------------------------------------------------------\n * * Composes a normalized version description string.\n * ------------------------------------------------------------------------\n *\n * Generates a standardized version description sentence.\n *\n * If a valid `packageName` is provided, the resulting string will follow:\n *\n *   \"The version package of \\<packageName\\>.\"\n *\n * Otherwise, a fallback description from `DESCRIPTIONS.VERSION`\n * from {@link COMMANDER_UI_DEFAULTS| `COMMANDER_UI_DEFAULTS`}\n * will be used.\n *\n * ------------------------------------------------------------------------\n * #### 🔎 Normalization Rules.\n * ------------------------------------------------------------------------\n *\n * - **The returned string is always:**\n *      - Trimmed.\n *      - Guaranteed to end with exactly one trailing period.\n *      - Normalized to prevent duplicate trailing dots.\n *\n * ------------------------------------------------------------------------\n *\n * @param packageName - Optional package name used to compose\n * a contextual version description.\n *\n * @returns A normalized sentence ending with a single period.\n *\n * @throws {ConfigurationError}\n * Thrown when `packageName` is provided but is not a non-empty string.\n *\n * ------------------------------------------------------------------------\n *\n * @example\n * ```ts\n * composeVersionDescription(\"my-cli\");\n * // ➔ \"The version package of my-cli.\"\n * ```\n *\n * @example\n * ```ts\n * composeVersionDescription();\n * // ➔ Falls back to `DESCRIPTIONS.VERSION` from `COMMANDER_UI_DEFAULTS` (normalized)\n * ```\n *\n * @internal\n */\nexport const composeVersionDescription = (packageName?: string): string => {\n  const isPkgNameEmptyString = !isNonEmptyString(packageName);\n\n  if (!isUndefined(packageName) && isPkgNameEmptyString) {\n    throw ConfigurationError.type(\n      \"packageName\",\n      \"a non-empty string\",\n      packageName,\n      \"composeVersionDescription\"\n    );\n  }\n\n  const text = !isPkgNameEmptyString\n    ? `The version package of ${packageName}.`\n    : DESCRIPTIONS.VERSION;\n\n  const trimmed = text.trim().replace(/\\.*$/, \"\");\n  return trimmed + \".\";\n};\n\n/** Takes an argument and returns its human readable equivalent for help usage command.\n *\n * @internal\n */\nexport function humanReadableArgName(arg: Argument | CliArgument): string {\n  if (!(arg instanceof Argument)) {\n    throw ConfigurationError.type(\n      \"arg\",\n      \"instanceof Argument or CliArgument\",\n      arg,\n      \"humanReadableArgName\"\n    );\n  }\n\n  const nameOutput = arg.name() + (arg.variadic === true ? \"...\" : \"\");\n\n  return arg.required ? \"<\" + nameOutput + \">\" : \"[\" + nameOutput + \"]\";\n}\n\n/** Removes a leading `\"v\"` from a version string only if it is\n * immediately followed by a digit.\n *\n * - ***This safely normalizes common semver formats like:***\n *    - `v1.2.3` ➔ `1.2.3`.\n *    - `1.2.3`  ➔ unchanged.\n *    - `vbeta`  ➔ unchanged.\n *    - `null` | `undefined`  ➔ unchanged.\n *\n * The function avoids naive slicing and ensures\n * non-semver strings are not modified.\n *\n * @param version - The version string to normalize.\n * @returns The normalized version string.\n *\n * @internal\n */\nexport function normalizeVersionPrefix(version: string): string;\nexport function normalizeVersionPrefix(version: string | null): string | null;\nexport function normalizeVersionPrefix(version?: string): string | undefined;\nexport function normalizeVersionPrefix(version?: null): null | undefined;\nexport function normalizeVersionPrefix(version: null): null;\nexport function normalizeVersionPrefix(\n  version?: string | null\n): string | null | undefined;\nexport function normalizeVersionPrefix(\n  version: string | null | undefined\n): string | null | undefined {\n  if (!isNil(version) && !isNonEmptyString(version)) {\n    throw ConfigurationError.type(\n      \"version\",\n      \"a non-empty string, null or undefined\",\n      version,\n      \"composeVersionDescription\"\n    );\n  }\n\n  if (isNull(version)) return null;\n  return version?.replace(/^v(?=\\d)/, \"\");\n}\n\n/** Options for {@link ensureVersionInjected | `ensureVersionInjected`}.\n *\n * @internal\n */\nexport type EnsureVersionInjectedOptions = {\n  /** Pre-formatted package name used in the styled version output. */\n  pkgNameFormatted?: string;\n\n  /** Normalized package version (without leading `\"v\"`). */\n  normalizedVersion: string;\n};\n\n/** Ensures the version option is lazily injected into the command\n * before parsing occurs.\n *\n * - **This helper mirrors the default `.version()` behavior but allows\n *   custom styled output to be injected only if:**\n *      - The user did NOT explicitly call `.version()`.\n *      - The version has NOT already been injected.\n *\n * The injection is intentionally deferred until `parse()` /\n * `parseAsync()` time to avoid interfering with user-land\n * configuration order.\n *\n * This function is idempotent and safe to call multiple times.\n *\n * @internal\n */\nexport function ensureVersionInjected(\n  cmd: CommandContext,\n  options: EnsureVersionInjectedOptions\n): void {\n  const { pkgNameFormatted, normalizedVersion } = options;\n  const _internal = getInternalState(cmd);\n\n  if (!_internal.versionSetByUser && !_internal.versionInjected) {\n    const _isNonEmptyString = isNonEmptyString(pkgNameFormatted);\n\n    const _pkgName = _isNonEmptyString ? pkgNameFormatted : undefined;\n\n    const _subTitle = _isNonEmptyString\n      ? `${pkgNameFormatted} ${picocolors.reset(\"version\")}:`\n      : `${picocolors.blueBright(\"Version\")}:`;\n\n    _internal.versionOriginal?.(\n      joinLinesLoose(\n        _subTitle,\n        joinInline(\n          `${picocolors.magentaBright(ICONS.arrowRight)}`,\n          `${picocolors.gray(`v${normalizedVersion}`)}`\n        )\n      ),\n      FLAGS.VERSION,\n      composeVersionDescription(_pkgName)\n    );\n\n    _internal.versionInjected = true;\n  }\n}\n","import \"@rzl-zone/node-only\";\n\nimport type { CreateBaseProgramOptions } from \"@/commander-kit/types\";\n\nimport { parse } from \"node:path\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { PACKAGE_META } from \"@/_internal/constants/package-meta\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { joinInline, picocolors } from \"@/utils/client\";\n\nimport { normalizeVersionPrefix } from \"./versions\";\n\n/** Parameters accepted by\n * {@link resolveBaseProgramPresentationMeta | `resolveBaseProgramPresentationMeta`}.\n *\n * @internal\n */\nexport type ResolveBaseProgramPresentationParams = CreateBaseProgramOptions;\n\n/** Fully resolved presentation metadata returned by\n * {@link resolveBaseProgramPresentationMeta | `resolveBaseProgramPresentationMeta`}.\n *\n * - **This object is immutable and safe to reuse across:**\n *    - Header rendering.\n *    - Version wiring.\n *    - Title formatting.\n * ----------------------------------------------------------------\n * @internal\n */\nexport type BaseProgramPresentationMeta = Readonly<{\n  /** Resolved CLI name from override, identity, or argv. */\n  readonly resolvedCliName: string | undefined;\n\n  /** Resolved display title. */\n  readonly commandTitle: string | undefined;\n\n  /** Resolved package name. */\n  readonly resolvedPackageName: string;\n\n  /** Resolved (raw) package version before normalization. */\n  readonly resolvedPackageVersion: string;\n\n  /** Normalized version (prefixed if needed). */\n  readonly normalizedVersion: string;\n\n  /** Whether CLI name differs from package.json name. */\n  readonly isDiffCommandName: boolean;\n\n  /** Formatted package name with optional CLI alias. */\n  readonly pkgNameFormatted: string;\n\n  /** Default formatted title (package@version + alias arrow). */\n  readonly defaultTitleFormatted: string;\n}>;\n\n/** ------------------------------------------------------------------------\n * * Resolves normalized presentation metadata for `createBaseProgram`.\n * ------------------------------------------------------------------------\n *\n * Computes and returns all derived identity and presentation values\n * required during base program construction.\n *\n * - **This helper centralizes resolution logic for:**\n *    - CLI name detection.\n *    - Command title fallback.\n *    - Package name resolution.\n *    - Package version normalization.\n *    - Presentation formatting (colored output).\n *\n * Unlike `resolveCliPresentationMeta`, this resolver operates purely\n * on factory-level inputs and does not depend on Commander internal state.\n *\n * The returned object is immutable.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Resolution Priority:***\n *\n *    - *CLI Name:*\n *        1. Explicit `cliName`.\n *        2. `commandIdentity.commandName`.\n *        3. `process.argv[1]` basename.\n *        4. `undefined`.\n *\n *    - *Command Title:*\n *        1. `commandIdentity.cli()`.\n *        2. UI `title`.\n *        3. `undefined`.\n *\n *    - *Package Name:*\n *        1. Explicit `packageName`.\n *        2. `commandIdentity.packageName`.\n *        3. `package.json` name.\n *\n *    - *Package Version:*\n *        1. Explicit `packageVersion`.\n *        2. `commandIdentity.version`.\n *        3. `package.json` version.\n *\n * ------------------------------------------------------------------------\n *\n * @param params - Resolution parameters.\n * @returns Immutable base program presentation metadata.\n *\n * ------------------------------------------------------------------------\n * @internal\n */\nexport function resolveBaseProgramPresentationMeta(\n  params: ResolveBaseProgramPresentationParams\n): BaseProgramPresentationMeta {\n  const { cliName, packageName, packageVersion, commandIdentity, ui } = params;\n\n  /** Resolve CLI name. */\n  const resolvedCliName = isNonEmptyString(cliName)\n    ? cliName\n    : isNonEmptyString(commandIdentity?.commandName)\n      ? commandIdentity!.commandName\n      : isNonEmptyString(process.argv[1])\n        ? parse(process.argv[1]).name\n        : undefined;\n\n  /** Resolve command title. */\n  const identityTitle = commandIdentity?.cli?.();\n  const commandTitle = isNonEmptyString(identityTitle)\n    ? identityTitle\n    : isNonEmptyString(ui?.title)\n      ? ui.title\n      : undefined;\n\n  /** Resolve package name. */\n  const resolvedPackageName = isNonEmptyString(packageName)\n    ? packageName\n    : isNonEmptyString(commandIdentity?.packageName)\n      ? commandIdentity.packageName\n      : PACKAGE_META.name;\n\n  /** Resolve package version (raw). */\n  const resolvedPackageVersion = isNonEmptyString(packageVersion)\n    ? packageVersion\n    : isNonEmptyString(commandIdentity?.version)\n      ? commandIdentity.version\n      : PACKAGE_META.version;\n\n  /** Normalize version prefix. */\n  const normalizedVersion = normalizeVersionPrefix(resolvedPackageVersion);\n\n  /** Determine CLI/package name difference. */\n  const isDiffCommandName =\n    !!resolvedCliName && resolvedCliName !== PACKAGE_META.name;\n\n  /** Build formatted package name. */\n  const pkgNameFormatted = `${picocolors.blueBright(resolvedPackageName)}${\n    isDiffCommandName ? ` ${picocolors.cyanBright(`(${resolvedCliName})`)}` : \"\"\n  }`;\n\n  /** Build formatted default title. */\n  const defaultTitleFormatted = joinInline(\n    picocolors.blueBright(PACKAGE_META.name + \"@\" + normalizedVersion),\n    isDiffCommandName\n      ? `${picocolors.magentaBright(ICONS.arrowRight)} ${picocolors.yellowBright(resolvedCliName)}`\n      : false\n  );\n\n  return Object.freeze({\n    resolvedCliName,\n    commandTitle,\n    resolvedPackageName,\n    resolvedPackageVersion,\n    normalizedVersion,\n    isDiffCommandName,\n    pkgNameFormatted,\n    defaultTitleFormatted\n  });\n}\n","import type { CommandContext } from \"@/commander-kit/types\";\n\nimport {\n  ensureVersionInjected,\n  type EnsureVersionInjectedOptions\n} from \"@/commander-kit/_internal/helpers/versions\";\n\n/** ------------------------------------------------------------------------\n * * Installs a version injection interceptor on a Commander program.\n * ------------------------------------------------------------------------\n *\n * Wraps the program's `Command` instance `.parse()` and `.parseAsync()` methods to ensure\n * that version metadata is injected immediately before execution begins.\n *\n * This enables lazy version wiring, meaning version configuration\n * is applied at parse-time rather than during initial setup.\n *\n * ------------------------------------------------------------------------\n * #### Behavior.\n * ------------------------------------------------------------------------\n *\n * - Preserves the original `Command` instance `.parse()` and `.parseAsync()` method bindings.\n * - Invokes {@link ensureVersionInjected | `ensureVersionInjected()`} before delegating to the original method.\n * - Does not alter Commander’s execution semantics.\n * - Transparently returns the original method results.\n *\n * ------------------------------------------------------------------------\n * #### ⚠️ Important Notes.\n * ------------------------------------------------------------------------\n *\n * - This function mutates the provided `program` instance.\n * - It should only be installed once per program instance.\n * - Intended strictly for internal UI-layer lifecycle orchestration.\n *\n * ------------------------------------------------------------------------\n *\n * @param program - A Commander program instance, this may be either:\n * - A program created via `createBaseProgram()`, or\n * - A native `Command` instance created directly from Commander.\n *\n * @param options - Configuration object controlling version injection.\n * @param options.versionInjection - Options forwarded to\n * `ensureVersionInjected()` prior to parsing.\n *\n * @internal\n */\nexport function installParseVersionInterceptor(\n  program: CommandContext,\n  options: { versionInjection: EnsureVersionInjectedOptions }\n): void {\n  const { versionInjection } = options;\n\n  const originalParse = program.parse.bind(program);\n  const originalParseAsync = program.parseAsync.bind(program);\n\n  program.parse = function (...args) {\n    ensureVersionInjected(program, versionInjection);\n    return originalParse(...args);\n  };\n\n  program.parseAsync = async function (...args) {\n    ensureVersionInjected(program, versionInjection);\n    return originalParseAsync(...args);\n  };\n}\n","import \"@rzl-zone/node-only\";\n\nimport type {\n  CommanderInternalState,\n  CommanderUiOptions\n} from \"@/commander-kit/types\";\n\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\nimport { joinLinesLoose, ConfigurationError } from \"@/utils/client\";\n\nimport { StyledHelp } from \"../_internal/help/styled-help\";\nimport { interceptUsage } from \"../_internal/interceptor/usage\";\nimport { interceptHelp } from \"../_internal/interceptor/help\";\nimport { interceptVersion } from \"../_internal/interceptor/version\";\nimport { composeVersionDescription } from \"../_internal/helpers/versions\";\nimport { createDefaultInternalState, createUIState } from \"../_internal/state\";\nimport { resolveBaseProgramPresentationMeta } from \"../_internal/helpers/base-program\";\nimport { installParseVersionInterceptor } from \"../_internal/interceptor/install-parse-version\";\n\nimport { CliCommand } from \"../core/command\";\nimport { CommandIdentity } from \"../identity\";\nimport { applyCommanderUi } from \"../ui/apply-commander-ui\";\nimport { handleCommanderExit } from \"../lifecycle/handle-commander-exit\";\n\n/** ----------------------------------------------------------------\n * * ***Internal base program implementation.***\n * ----------------------------------------------------------------\n *\n * Internal extension of {@link CliCommand | `CliCommand`}\n * used by {@link createBaseProgram | `createBaseProgram()`}.\n *\n * This class stores additional internal state required\n * for UI formatting, version injection, and command\n * lifecycle behavior.\n */\nexport class CommandBaseProgram extends CliCommand {\n  /** ----------------------------------------------------------------\n   * * ***Internal mutable state container used by the CLI runtime.***\n   * ----------------------------------------------------------------\n   *\n   * Stores metadata required during program bootstrap and\n   * command execution such as UI configuration, version\n   * injection, and identity metadata.\n   *\n   * This state should only be modified through\n   * {@link _setInternalState | `_setInternalState`}.\n   *\n   * @internal\n   */\n  private _internalStateData: CommanderInternalState;\n\n  constructor(name?: string) {\n    super(name);\n\n    this._internalStateData = createDefaultInternalState();\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Access the internal CLI state container.***\n   * ----------------------------------------------------------------\n   *\n   * Returns a readonly view of the internal state used\n   * by the program runtime.\n   *\n   * This accessor is intended for internal helpers and\n   * framework utilities.\n   *\n   * @internal\n   */\n  get _internalState(): Readonly<CommanderInternalState> {\n    return this._internalStateData;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Replace the current internal state container.***\n   * ----------------------------------------------------------------\n   *\n   * This method is primarily used during program bootstrap\n   * to initialize or update runtime metadata.\n   *\n   * External consumers should never call this method directly.\n   *\n   * @internal\n   */\n  _setInternalState(state: CommanderInternalState) {\n    this._internalStateData = state;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Create subcommand instance.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides Commander’s internal command factory so\n   * all nested commands are instances of\n   * {@link CommandBaseProgram | `CommandBaseProgram`}.\n   *\n   * This ensures that internal state and runtime\n   * extensions propagate to all subcommands.\n   *\n   * @internal\n   */\n  override createCommand(name?: string): CommandBaseProgram;\n  override createCommand(name?: string): CommandBaseProgram {\n    const sub = new CommandBaseProgram(name);\n\n    sub._setInternalState({\n      ...this._internalState\n    });\n\n    return sub;\n  }\n}\n\n/** ----------------------------------------------------------------\n * * ***Configuration options for `createBaseProgram()`.***\n * ----------------------------------------------------------------\n *\n * Defines the bootstrap configuration used when creating\n * a pre-configured Commander program instance.\n *\n * - ***This type supports:***\n *      - direct property overrides.\n *      - centralized configuration via\n *        {@link CommandIdentity | `CommandIdentity`}.\n *      - optional CLI UI customization.\n *\n * ----------------------------------------------------------------\n * #### Resolution Priority.\n * ----------------------------------------------------------------\n *\n * When both explicit fields and `commandIdentity` are provided,\n * values are resolved in the following order:\n *\n *  * `explicit option` ➔ {@link CreateBaseProgramOptions.commandIdentity |`commandIdentity`} ➔ `internal defaults`.\n *\n * This ensures predictable override behavior.\n *\n * ----------------------------------------------------------------\n */\nexport type CreateBaseProgramOptions = {\n  /** ----------------------------------------------------------------\n   * * ***CLI program name.***\n   * ----------------------------------------------------------------\n   *\n   * Name assigned to the Commander instance.\n   *\n   * Overrides {@link CommandIdentity.commandName | `commandIdentity.commandName`} when provided.\n   *\n   * ----------------------------------------------------------------\n   */\n  cliName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package name.***\n   * ----------------------------------------------------------------\n   *\n   * Package name displayed in the version description.\n   *\n   * Overrides {@link CommandIdentity.packageName | `commandIdentity.packageName`} when provided.\n   *\n   * Defaults to the internally resolved package name\n   * when omitted.\n   *\n   * ----------------------------------------------------------------\n   */\n  packageName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package version.***\n   * ----------------------------------------------------------------\n   *\n   * Version string passed to {@link CliCommand.version `.version()`}.\n   *\n   * Overrides {@link CommandIdentity.version | `commandIdentity.version`} when provided.\n   *\n   * Defaults to the internally resolved package version\n   * when omitted.\n   *\n   * ----------------------------------------------------------------\n   */\n  packageVersion?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Commander UI configuration.***\n   * ----------------------------------------------------------------\n   *\n   * Inline UI configuration via `ui` option.\n   *\n   * UI initialization is resolved using the following priority:\n   *\n   * 1. When `ui.usage` is defined,\n   *    full UI customization is triggered and strict validation is enforced.\n   *\n   * 2. Otherwise, if {@link CommandIdentity | `commandIdentity`} is provided,\n   *    UI is initialized using the identity title.\n   *\n   * 3. Otherwise, if `ui.title` is defined and valid,\n   *    UI is initialized using the provided title only.\n   *\n   * When full UI customization is triggered (case #1),\n   * the following validations are enforced:\n   *\n   * - The UI object must be non-null.\n   * - `title` must be a non-empty string when provided.\n   * - `usage` must be a non-empty string when provided.\n   *\n   * In partial initialization cases (#2 and #3),\n   * usage falls back to {@link CliCommand | `CliCommand`} default resolution.\n   *\n   * @note\n   * ⚠️ If validation fails, a structured configuration error may be thrown.\n   *\n   * ----------------------------------------------------------------\n   */\n  ui?: CommanderUiOptions;\n\n  /** ----------------------------------------------------------------\n   * * ***Command identity source.***\n   * ----------------------------------------------------------------\n   *\n   * Optional {@link CommandIdentity | `CommandIdentity`} instance used as a centralized\n   * configuration source for:\n   *\n   * - Command name.\n   * - Package name.\n   * - Version metadata.\n   *\n   * When provided, this identity may also participate in UI initialization.\n   *\n   * If full UI configuration is not supplied via `ui`,\n   * the identity title may be used to bootstrap\n   * {@link applyCommanderUi | `applyCommanderUi()`}.\n   *\n   * This reduces the need for manual property mapping\n   * and provides a consistent identity-driven configuration pattern.\n   *\n   * @throws {TypeError}\n   * Thrown if the provided value is not an instance of\n   * {@link CommandIdentity | `CommandIdentity`}.\n   *\n   * ----------------------------------------------------------------\n   */\n  commandIdentity?: CommandIdentity;\n};\n\n/** ----------------------------------------------------------------\n * * ***Creates a pre-configured Commander.js program instance.***\n * ----------------------------------------------------------------\n *\n * Factory function that returns a fresh {@link CliCommand | `CliCommand`} instance\n * with shared base configuration applied.\n *\n * - *This helper centralizes common CLI setup to ensure:*\n *    - Consistent version formatting.\n *    - Standardized exit behavior.\n *    - No shared mutable state between entry points.\n *\n * The returned {@link CliCommand | `CliCommand`} instance is stateful and fully mutable.\n *\n * *Additional configuration (including UI customization) may be applied after creation.*\n *\n * ----------------------------------------------------------------\n * #### Configuration Resolution.\n * ----------------------------------------------------------------\n *\n * When both explicit options and {@link CommandIdentity | `CommandIdentity`} are provided,\n * values are resolved using the following priority:\n *\n *  * `explicit option` ➔ `commandIdentity` ➔ `internal defaults`.\n *\n * This allows granular overrides while still supporting\n * {@link CommandIdentity | `CommandIdentity`} as a single source of truth.\n *\n * ----------------------------------------------------------------\n * #### UI Configuration.\n * ----------------------------------------------------------------\n *\n * UI customization can be applied using two approaches:\n *\n * 1. Inline via the `ui` option.\n *      - During initialization, {@link applyCommanderUi | `applyCommanderUi()`}\n *        may be invoked automatically using the following priority:\n *         - Full UI override when `options.ui.usage` is defined.\n *         - Fallback to {@link CommandIdentity | `commandIdentity`} when provided.\n *         - Fallback to `options.ui.title` when provided or valid.\n *\n *      - In partial initialization cases, usage falls back to\n *        {@link CliCommand | `CliCommand`} default resolution.\n *\n * 2. Manually after creation.\n *      - You may call {@link applyCommanderUi | `applyCommanderUi()`}\n *      explicitly to override or apply custom UI behavior.\n *\n *      - Calling {@link applyCommanderUi | `applyCommanderUi()`} manually after initialization will\n *        override any previously applied UI configuration.\n *\n * ----------------------------------------------------------------\n *\n * @param options Optional bootstrap configuration.\n *\n * @returns A configured {@link CliCommand | `CliCommand`} instance with version,\n * exit override, and optional UI behavior applied.\n *\n * ----------------------------------------------------------------\n * @example\n *\n * **Using commandIdentity as primary source ***(recommended)***:**\n *\n * ```ts\n * import { joinInline, picocolors } from \"@rzl-zone/build-tools/utils\";\n * import { createBaseProgram, CommandIdentity } from \"@rzl-zone/build-tools/utils/server\";\n *\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"my-command-cli\"\n * })\n *   // override to your-package-name, e.g:\n *   .setPackageName(\"your-package-name\")\n *   // override to your-package-version, e.g:\n *   .setVersion(\"1.1.1\");\n *\n * const program = createBaseProgram({\n *   commandIdentity: identity,\n *   ui: {\n *     title: identity.cli(),\n *     usage: joinInline(\n *       picocolors.cyan(identity.commandName),\n *       picocolors.gray(\"<glob...>\"),\n *       picocolors.blueBright(\"[options]\")\n *     )\n *   }\n * });\n *\n * program.parse();\n * ```\n * ----------------------------------------------------------------\n * @example\n *\n * **Automatic UI configuration ***(manual mapping)***:**\n *\n * ```ts\n * import { joinInline, picocolors } from \"@rzl-zone/build-tools/utils\";\n * import { createBaseProgram, CommandIdentity } from \"@rzl-zone/build-tools/utils/server\";\n *\n * const commandTitle = new CommandIdentity({\n *   defaultCommandName: \"clean-js-build-artifacts\"\n * })\n *   // override to your-package-name, e.g:\n *   .setPackageName(\"your-package-name\")\n *   // override to your-package-version, e.g:\n *   .setVersion(\"1.1.1\");\n *\n * const program = createBaseProgram({\n *   cliName: commandTitle.commandName,\n *   packageName: commandTitle.packageName,\n *   packageVersion: commandTitle.version,\n *   ui: {\n *     title: commandTitle.cli(),\n *     usage: joinInline(\n *       picocolors.cyan(commandTitle.commandName),\n *       picocolors.gray(\"<glob...>\"),\n *       picocolors.blueBright(\"[options]\")\n *     )\n *   }\n * });\n *\n * program.parse();\n * ```\n * ----------------------------------------------------------------\n * @example\n *\n * **Manual UI override after creation:**\n *\n * ```ts\n * import { joinInline, picocolors } from \"@rzl-zone/build-tools/utils\";\n * import { createBaseProgram, CommandIdentity } from \"@rzl-zone/build-tools/utils/server\";\n *\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"my-command-cli\"\n * });\n *\n * const baseProgram = createBaseProgram({\n *   commandIdentity: identity\n * });\n *\n * const program = applyCommanderUi(baseProgram, {\n *   title: identity.cli(),\n *   usage: joinInline(\n *     picocolors.cyan(identity.commandName),\n *     picocolors.gray(\"<glob...>\"),\n *     picocolors.blueBright(\"[options]\")\n *   )\n * });\n *\n * program.parse();\n * ```\n * ----------------------------------------------------------------\n */\nexport function createBaseProgram(\n  options: CreateBaseProgramOptions = {}\n): CommandBaseProgram {\n  if (\n    options.commandIdentity &&\n    !isExactInstanceOf(options.commandIdentity, CommandIdentity)\n  ) {\n    throw ConfigurationError.type(\n      \"options.commandIdentity\",\n      \"instanceof CommandIdentity\",\n      options.commandIdentity,\n      \"createBaseProgram\"\n    );\n  }\n\n  const {\n    commandTitle,\n    defaultTitleFormatted,\n    normalizedVersion,\n    pkgNameFormatted,\n    resolvedCliName,\n    resolvedPackageName\n  } = resolveBaseProgramPresentationMeta(options);\n\n  const cmd = new CommandBaseProgram(resolvedCliName);\n\n  cmd._setInternalState({\n    ...createDefaultInternalState(),\n    ui: createUIState(options.ui || {}),\n    packageName: resolvedPackageName\n  });\n\n  //todo: Intercept manual .usage()\n  interceptUsage(cmd);\n  //todo: Intercept manual .helpOption()\n  interceptHelp(cmd);\n  //todo: Intercept manual .version()\n  interceptVersion(cmd, composeVersionDescription(pkgNameFormatted));\n\n  cmd.createHelp = () => new StyledHelp();\n\n  cmd.addHelpText(\n    \"before\",\n    joinLinesLoose(\"\", commandTitle ?? defaultTitleFormatted, \"\")\n  );\n\n  cmd.exitOverride(handleCommanderExit);\n\n  const cmdApplyUi = applyCommanderUi(cmd, {\n    title: commandTitle,\n    usage: options.ui?.usage,\n    __commandName: resolvedCliName\n  });\n\n  installParseVersionInterceptor(cmdApplyUi, {\n    versionInjection: { normalizedVersion, pkgNameFormatted }\n  });\n\n  return cmdApplyUi;\n}\n","import \"@rzl-zone/node-only\";\n\nimport type {\n  CommandContext,\n  CommanderInternalState\n} from \"@/commander-kit/types\";\n\nimport { parse } from \"node:path\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { joinInline, picocolors } from \"@/utils/client\";\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { PACKAGE_META } from \"@/_internal/constants/package-meta\";\n\nimport { CommandBaseProgram } from \"@/commander-kit/factories/create-base-program\";\nimport { COMMANDER_UI_DEFAULTS } from \"@/commander-kit/constants\";\n\nimport { getInternalState } from \"../state\";\nimport { normalizeVersionPrefix } from \"./versions\";\nimport { reorderUsage, styleUsage } from \"./usages\";\n\nconst { DESCRIPTIONS, FLAGS } = COMMANDER_UI_DEFAULTS;\n\n/** Parameters accepted by\n * {@link resolveCliPresentationMeta | `resolveCliPresentationMeta`}.\n *\n * @internal\n */\nexport type ResolveCliPresentationParams = {\n  /** The command instance to resolve metadata from. */\n  program: CommandContext;\n\n  /** Optional explicit CLI name override. */\n  commandName?: string;\n\n  /** Optional fallback title. */\n  title?: string;\n\n  /** Optional explicit CLI version override. */\n  version?: string;\n\n  /** Optional explicit CLI package name override. */\n  packageName?: string;\n};\n\n/** Normalized help configuration returned by\n * {@link resolveCliPresentationMeta | `resolveCliPresentationMeta`}.\n *\n * @internal\n */\nexport type CliPresentationHelpMeta = Readonly<{\n  /** Raw internal help metadata reference. */\n  meta: CommanderInternalState[\"help\"] | undefined;\n\n  /** Whether help output is disabled. */\n  disabled: boolean;\n\n  /** Resolved help flags. */\n  flags: string;\n\n  /** Resolved help description. */\n  description: string;\n}>;\n\n/** Fully resolved CLI presentation metadata by\n * {@link resolveCliPresentationMeta | `resolveCliPresentationMeta`}.\n *\n * This object is derived, immutable, and safe to reuse across\n * render layers (header printer, help renderer, error handler, etc.).\n *\n * @internal\n */\nexport type CliPresentationMeta = Readonly<{\n  /** Resolve CLI name from override or runtime argv. */\n  resolvedCliName: string | undefined;\n  /** Resolve Package name. */\n  resolvedPackageName: string;\n  /** Resolve Package name with formatted colors. */\n  resolvedPackageNameFormatted: string;\n  /** Determine whether CLI name differs from package name. */\n  isDiffCommandName: boolean;\n  /** Resolve display title. */\n  commandTitle: string | undefined;\n  /** Normalize version with fallback. */\n  normalizedVersion: string;\n  /** Build default formatted CLI title. */\n  defaultTitleFormatted: string;\n  /** Resolve dynamic usage string. */\n  dynamicUsage: string;\n  /** Resolve help metadata. */\n  help: CliPresentationHelpMeta;\n}>;\n\n/** ------------------------------------------------------------------------\n * * Resolves normalized CLI presentation metadata for `applyCommander`.\n * ------------------------------------------------------------------------\n *\n * Computes and returns all derived CLI presentation values required for\n * rendering headers, titles, usage output, version labels, and help\n * configuration.\n *\n * - *This helper centralizes resolution logic that depends on:*\n *     - Explicit command name overrides.\n *     - Runtime `process.argv` inspection.\n *     - Internal command state.\n *     - Package metadata fallbacks.\n *\n * - *The function guarantees consistent priority ordering for:*\n *     - CLI identity resolution.\n *     - Version normalization.\n *     - Title formatting.\n *     - Usage fallback behavior.\n *     - Help metadata defaults.\n *\n * The returned object is fully derived and does not mutate the provided\n * command instance.\n *\n * ------------------------------------------------------------------------\n *\n * - ***Resolution Priority:***\n *\n *    - *CLI Name:*\n *       1. Explicit `commandName`.\n *       2. `process.argv[1]` basename.\n *       3. `undefined`.\n *\n *    - *Command Title:*\n *       1. Explicit `commandName`.\n *       2. Provided `title`.\n *       3. `undefined`.\n *\n *    - *Version:*\n *       1. Manual version override.\n *       2. Internal command version.\n *       3. `package.json` version.\n *\n *    - *Usage:*\n *       1. Manual usage override.\n *       2. UI usage override.\n *       3. Styled program usage.\n *\n * ------------------------------------------------------------------------\n *\n * @param params - Configuration object.\n * @returns Immutable object of cli presentation metadata.\n * @example\n * ```ts\n * const meta = resolveCliPresentationMeta({\n *   program,\n *   commandName: \"my-cli\"\n * });\n *\n * console.log(meta.defaultTitleFormatted);\n * ```\n * ------------------------------------------------------------------------\n *\n * @internal\n */\nexport function resolveCliPresentationMeta(\n  params: ResolveCliPresentationParams\n): CliPresentationMeta {\n  const { program, commandName, title, version, packageName } = params;\n\n  const _internal = getInternalState(program);\n\n  const isCommandBaseProgram = isExactInstanceOf(program, CommandBaseProgram);\n\n  /** Resolve CLI name from override or runtime argv. */\n  const resolvedCliName = isNonEmptyString(commandName)\n    ? commandName\n    : isNonEmptyString(process.argv[1])\n      ? parse(process.argv[1]).name\n      : undefined;\n\n  /** Determine whether CLI name differs from package name. */\n  const isDiffCommandName =\n    !!resolvedCliName && resolvedCliName !== PACKAGE_META.name;\n\n  /** Resolve display title. */\n  const commandTitle = isNonEmptyString(commandName)\n    ? commandName\n    : isNonEmptyString(title)\n      ? title\n      : undefined;\n\n  /** Resolve package version (raw). */\n  const resolvedPackageVersion =\n    !isCommandBaseProgram && isNonEmptyString(version)\n      ? version\n      : isNonEmptyString(_internal.versionMeta?.value)\n        ? _internal.versionMeta.value\n        : undefined;\n\n  /** Normalize version with fallback. */\n  let normalizedVersion = normalizeVersionPrefix(resolvedPackageVersion);\n\n  normalizedVersion = isNonEmptyString(normalizedVersion)\n    ? normalizedVersion\n    : normalizeVersionPrefix(PACKAGE_META.version);\n\n  /** Build default formatted CLI title. */\n  const defaultTitleFormatted = joinInline(\n    picocolors.blueBright(\n      (isNonEmptyString(_internal.packageName)\n        ? _internal.packageName\n        : PACKAGE_META.name) +\n        \"@\" +\n        normalizedVersion\n    ),\n    isDiffCommandName\n      ? `${picocolors.magentaBright(ICONS.arrowRight)} ${picocolors.yellowBright(resolvedCliName)}`\n      : false\n  );\n\n  /** Resolve dynamic usage string. */\n  const dynamicUsage = isNonEmptyString(_internal.manualUsage)\n    ? _internal.manualUsage\n    : isNonEmptyString(_internal.ui?.usage)\n      ? _internal.ui.usage\n      : (isDiffCommandName\n          ? `${picocolors.cyanBright(resolvedCliName)} `\n          : \"\") +\n        (isNonEmptyString(program.usage())\n          ? styleUsage(\n              reorderUsage(program.usage(), {\n                errorConfig: {\n                  field: \"`program.usage()`\",\n                  context:\n                    \"resolveCliPresentationMeta (by `program.usage()` at const variable 'dynamicUsage')\"\n                }\n              }),\n              {\n                errorConfig: {\n                  field: \"`reorderUsage(program.usage())`\",\n                  context:\n                    \"resolveCliPresentationMeta (by `reorderUsage(program.usage())` at const variable 'dynamicUsage')\"\n                }\n              }\n            )\n          : \"\");\n\n  /** Resolve Package name. */\n  const resolvedPackageName = isNonEmptyString(packageName)\n    ? packageName\n    : PACKAGE_META.name;\n\n  /** Resolve Package name with formatted colors. */\n  const resolvedPackageNameFormatted = `${picocolors.blueBright(resolvedPackageName)}${isDiffCommandName ? ` ${picocolors.cyanBright(`(${resolvedCliName})`)}` : \"\"}`;\n\n  /** Resolve help metadata. */\n  const helpMeta = _internal.help;\n  const isHelpDisabled = helpMeta?.disabled === true;\n  const helpFlags = helpMeta?.flags ?? FLAGS.HELP;\n  const helpDesc = helpMeta?.description ?? DESCRIPTIONS.HELP;\n\n  return Object.freeze({\n    resolvedCliName,\n    resolvedPackageName,\n    resolvedPackageNameFormatted,\n    isDiffCommandName,\n    commandTitle,\n    normalizedVersion,\n    defaultTitleFormatted,\n    dynamicUsage,\n    help: {\n      meta: helpMeta,\n      disabled: isHelpDisabled,\n      flags: helpFlags,\n      description: helpDesc\n    }\n  });\n}\n","import \"@rzl-zone/node-only\";\n\nimport type { CommandContext, CommanderUiOptions } from \"@/commander-kit/types\";\n\nimport { Command } from \"commander\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { isExactInstanceOf } from \"@/utils/helper/class-check\";\nimport { joinLinesLoose, picocolors, ConfigurationError } from \"@/utils/client\";\n\nimport { resolveCliPresentationMeta } from \"../_internal/helpers/apply-commander-ui\";\nimport { composeVersionDescription } from \"../_internal/helpers/versions\";\n\nimport { interceptHelp } from \"../_internal/interceptor/help\";\nimport { installParseVersionInterceptor } from \"../_internal/interceptor/install-parse-version\";\nimport { interceptUsage } from \"../_internal/interceptor/usage\";\nimport { interceptVersion } from \"../_internal/interceptor/version\";\n\nimport { StyledHelp } from \"../_internal/help/styled-help\";\nimport { getInternalState, setInternalUiState } from \"../_internal/state\";\n\nimport { CliCommand } from \"../core/command\";\nimport { handleCommanderExit } from \"../lifecycle/handle-commander-exit\";\nimport {\n  CommandBaseProgram,\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  createBaseProgram\n} from \"../factories/create-base-program\";\n\n/** ------------------------------------------------------------------------\n * * Applies a structured UI layer to a Commander.js program instance.\n * ------------------------------------------------------------------------\n *\n * Enhances a Commander program by installing a standardized UI layer\n * for error rendering and presentation formatting.\n *\n * This function is primarily intended for native\n * {@link Command | `Command`} instances created directly\n * from Commander (e.g. `new Command()` or an imported `program` singleton).\n *\n * Programs created via\n * {@link createBaseProgram | `createBaseProgram()`}\n * already include the structured UI layer by default, in such cases, calling\n * this function is typically unnecessary and **redundant interception** also\n * is **not recommended**.\n *\n * ------------------------------------------------------------------------\n * #### Supported Program Types.\n * ------------------------------------------------------------------------\n *\n * **1.** Factory-based:\n *  ```ts\n *    import {\n *      applyCommanderUi,\n *      createBaseProgram\n *    } from \"@rzl-zone/build-tools/commander-kit\";\n *\n *    const programFactory = createBaseProgram();\n *    const program = applyCommanderUi(programFactory);\n *  ```\n *\n * **2.** Native Commander instance:\n *  ```ts\n *    import { Command } from \"commander\"\n *    import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n *    const nativeProgram = new Command();\n *    const program = applyCommanderUi(nativeProgram);\n *  ```\n *\n * When used with {@link createBaseProgram | `createBaseProgram`}, certain\n * interception steps are skipped because the factory already installs baseline\n * behavior and internal state wiring.\n *\n * When used with a plain {@link Command | `Command`} instance created directly\n * from Commander (e.g. `new Command()` or an imported `program` singleton), this\n * function installs all required interception and metadata tracking layers.\n *\n * - *In short:*\n *       - Programs created via `createBaseProgram()` already include\n *         foundational behavior.\n *       - Native Commander instances are fully instrumented by this function.\n *\n * ------------------------------------------------------------------------\n * #### Factory Integration.\n * ------------------------------------------------------------------------\n *\n * Programs created via {@link createBaseProgram | `createBaseProgram()`}\n * already include the structured UI layer by default.\n *\n * In such cases, calling `applyCommanderUi()` manually is unnecessary\n * and generally not recommended.\n *\n * - ***The factory installs:***\n *       - Internal state wiring.\n *       - Error interception.\n *       - Help customization.\n *       - Version handling lifecycle.\n *\n * ***`applyCommanderUi()` primarily exists to instrument native\n * {@link Command | `Command`}, or {@link CliCommand | `CliCommand`}\n * instances that were not created through the factory.***\n *\n * If the program instance was created via **`createBaseProgram()`**,\n * the **UI layer** is **already installed**, **reapplying** this function may\n * result in **redundant interception** and is **not recommended**.\n *\n * ------------------------------------------------------------------------\n * #### Installed UI Layer.\n * ------------------------------------------------------------------------\n *\n * This function standardizes:\n *\n * - Error message formatting.\n * - Header rendering.\n * - Usage resolution.\n * - Help hint presentation.\n * - Version interception.\n *\n * The goal is to provide a consistent, styled CLI output surface\n * independent of Commander’s default formatting.\n *\n * ------------------------------------------------------------------------\n * #### Internal Mutations.\n * ------------------------------------------------------------------------\n *\n * This function performs the following mutations on the provided\n * `program` instance:\n *\n * - Overrides `.error()`.\n * - Installs `.exitOverride()`.\n * - Replaces `.createHelp()`.\n * - Intercepts manual:\n *    - `.usage()` calls.\n *    - `.helpOption()` calls.\n *    - `.version()` calls.\n *\n * These interceptions allow internal metadata tracking without\n * relying on Commander private properties.\n *\n * ------------------------------------------------------------------------\n * #### Usage Resolution Order.\n * ------------------------------------------------------------------------\n *\n * When rendering usage inside error output, the value is resolved\n * in the following priority:\n *\n *   1. Manual `.usage()` override (intercepted internally).\n *   2. UI `options.usage`.\n *   3. Commander default usage string.\n *\n * ------------------------------------------------------------------------\n * #### ℹ️ Help Hint Handling.\n * ------------------------------------------------------------------------\n *\n * If `.helpOption(false)` is used, the help hint line\n * (`Run -h, --help`) will not be displayed.\n *\n * Help metadata is internally tracked and does not depend on\n * Commander private state.\n *\n * ------------------------------------------------------------------------\n * #### ⚠️ Important Behavior Notes.\n * ------------------------------------------------------------------------\n *\n * - This function **mutates** the provided program instance.\n * - It replaces Commander’s default error handler.\n * - The process exits with code `1` after rendering an error.\n * - The function is not strictly idempotent and should only be\n *   applied once per program instance.\n *\n * ------------------------------------------------------------------------\n *\n * @param program - A Commander program instance, this can be either:\n * - A program created via {@link createBaseProgram | `createBaseProgram`}, or\n * - A native {@link Command | `Command`}, or {@link CliCommand | `CliCommand`} instance (e.g. `new Command()`. `new CliCommand()` or an imported `program`/`cliProgram` singleton).\n *\n * @param options - Optional UI configuration.\n *\n * @throws {ConfigurationError}\n * Thrown when `program` is not a valid Commander program instance.\n *\n * ------------------------------------------------------------------------\n *\n * @example\n * Using a native Commander instance (manual installation required):\n * ```ts\n * import { Command } from \"commander\"\n * import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const nativeProgram = new Command();\n *\n * const program = applyCommanderUi(nativeProgram, {\n *   title: \"Custom CLI\",\n *   version: \"1.1.0\",\n *   packageName: \"my-package-name\"\n * });\n *\n * program.parse();\n * ```\n *\n * @example\n * Using the factory (UI layer already installed):\n * ```ts\n * import { createBaseProgram } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const program = createBaseProgram({\n *   commandIdentity: identity,\n *   ui: {\n *     title: \"My CLI Tool\",\n *     usage: \"my-cli <command> [options]\"\n *   }\n * });\n *\n * program.parse();\n * ```\n *\n * @example\n * Manual usage override takes priority:\n * ```ts\n * import { CliCommand, applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const programCli = new CliCommand();\n *\n * programCli\n *   .name(\"my-cli\")\n *   .usage(\"<input> [options]\");\n *\n * // Apply default UI helpers\n * const program = applyCommanderUi(programCli, {\n *   usage: \"fallback usage (will NOT be used)\",\n * });\n *\n * // Rendered usage will be:\n * // my-cli <input> [options]\n *\n * // In this case the manual `.usage()` call defined before\n * // `applyCommanderUi()` takes precedence.\n *\n * // The usage string provided to `applyCommanderUi()` will\n * // be ignored if a custom usage has already been configured.\n * ```\n *\n * @example\n * Disable help hint line:\n * ```ts\n * import { Command } from \"commander\"\n * import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const nativeProgram = new Command();\n *\n * const program = applyCommanderUi(nativeProgram);\n *\n * program.helpOption(false);\n * // Disables the help option and prevents the \"Run -h, --help\" hint\n * // from appearing in error messages.\n *\n * program.version(false);\n * // Disables the version command automatically configured by\n * // `applyCommanderUi()` or `createBaseProgram()`.\n * ```\n *\n * @example\n * Minimal setup for native Commander:\n * ```ts\n * import { Command } from \"commander\"\n * import { applyCommanderUi } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const nativeProgram = new Command();\n * const program = applyCommanderUi(nativeProgram);\n *\n * program.parse();\n * ```\n */\nexport function applyCommanderUi(\n  program: CommandBaseProgram,\n  options: CommanderUiOptions\n): CommandBaseProgram;\nexport function applyCommanderUi(\n  program: CliCommand | Command,\n  options: CommanderUiOptions\n): CliCommand;\nexport function applyCommanderUi(\n  program: unknown,\n  options: CommanderUiOptions\n): never;\nexport function applyCommanderUi(\n  program: unknown,\n  options: CommanderUiOptions\n): CommandContext {\n  const { title, usage, version, packageName, __commandName } = options;\n\n  if (\n    !isExactInstanceOf(program, Command) &&\n    !isExactInstanceOf(program, CliCommand) &&\n    !isExactInstanceOf(program, CommandBaseProgram)\n  ) {\n    throw ConfigurationError.type(\n      \"program\",\n      \"instanceof Command, CliCommand or create by factory function 'createBaseProgram'\",\n      program,\n      \"applyCommanderUi\"\n    );\n  }\n\n  setInternalUiState(program, { title, usage });\n\n  if (!isExactInstanceOf(program, CommandBaseProgram)) {\n    const {\n      commandTitle,\n      defaultTitleFormatted,\n      normalizedVersion,\n      resolvedPackageNameFormatted\n    } = resolveCliPresentationMeta({\n      program: program,\n      commandName: __commandName,\n      version,\n      packageName,\n      title\n    });\n\n    //todo: Intercept manual .usage()\n    interceptUsage(program);\n    //todo: Intercept manual .helpOption()\n    interceptHelp(program);\n    //todo: Intercept manual .version()\n    interceptVersion(\n      program,\n      composeVersionDescription(resolvedPackageNameFormatted)\n    );\n\n    program.createHelp = () => new StyledHelp();\n\n    program.addHelpText(\n      \"before\",\n      joinLinesLoose(\"\", commandTitle ?? defaultTitleFormatted, \"\")\n    );\n\n    program.exitOverride(handleCommanderExit);\n\n    installParseVersionInterceptor(program, {\n      versionInjection: {\n        normalizedVersion,\n        pkgNameFormatted: resolvedPackageNameFormatted\n      }\n    });\n  }\n\n  // Intercept ALL commander validation errors\n  program.error = function (message) {\n    let errMsg = message.replace(/^error:\\s*/i, \"\");\n    errMsg = errMsg.trim().replace(/\\.*$/, \"\") + \".\";\n\n    const { disableUsage } = getInternalState(program);\n\n    const { defaultTitleFormatted, dynamicUsage, help } =\n      resolveCliPresentationMeta({\n        program: program,\n        title,\n        commandName: __commandName\n      });\n\n    const printOut = [\n      isNonEmptyString(title) ? title : defaultTitleFormatted,\n      \"\",\n      `${picocolors.bold(`${picocolors.red(`${ICONS.error} Error`)}`)} ${picocolors.redBright(errMsg)}`\n    ];\n\n    if (!disableUsage && isNonEmptyString(dynamicUsage)) {\n      printOut.push(\n        \"\",\n        picocolors.bold(\"Usage:\"),\n        `  ${picocolors.reset(picocolors.gray(dynamicUsage))}`\n      );\n    }\n\n    if (!help.disabled) {\n      printOut.push(\n        \"\",\n        `${picocolors.dim(\"Run\")} ${picocolors.cyanBright(help.flags)} ${picocolors.dim(help.description)}`\n      );\n    }\n\n    console.error(joinLinesLoose(...printOut));\n\n    process.exit(1);\n  };\n\n  return program;\n}\n","import { CliCommand } from \"./command\";\n\n/** ----------------------------------------------------------------\n * * ***Default CLI program instance.***\n * ----------------------------------------------------------------\n *\n * Shared CLI program instance created from\n * {@link CliCommand | **`CliCommand`**}.\n *\n * This module-level singleton provides a convenient\n * default program object for simple CLI tools without\n * manually creating a command instance.\n *\n * ----------------------------------------------------------------\n *\n * Equivalent to:\n *\n * ```ts\n * import { CliCommand } from \"@rzl-zone/build-tools/commander-kit\";\n *\n * const cliProgram = new CliCommand();\n * ```\n */\nexport const cliProgram: CliCommand = new CliCommand();\n","import type { CommanderErrorCode } from \"@/commander-kit/types\";\n\nimport { CommanderError } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Commander base error class.***\n * ----------------------------------------------------------------\n *\n * Base error thrown internally by Commander when CLI\n * parsing or execution fails.\n */\nexport class CliCommanderError extends CommanderError {\n  constructor(exitCode: number, code: CommanderErrorCode, message: string) {\n    super(exitCode, code, message);\n  }\n}\n","import { InvalidArgumentError } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Error thrown when an argument fails validation.***\n * ----------------------------------------------------------------\n */\nexport class CliInvalidArgumentError extends InvalidArgumentError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n","import { InvalidOptionArgumentError } from \"commander\";\n\n/** ----------------------------------------------------------------\n * * ***Error thrown when an option argument fails validation.***\n * ----------------------------------------------------------------\n */\nexport class CliInvalidOptionArgumentError extends InvalidOptionArgumentError {\n  constructor(message: string) {\n    super(message);\n  }\n}\n","import { Argument } from \"commander\";\n\nimport { CliArgument } from \"@/commander-kit/core/argument\";\n\n/** ----------------------------------------------------------------\n * * ***CLI Argument Factory.***\n * ----------------------------------------------------------------\n *\n * Creates a new {@link CliArgument | **`CliArgument`**} instance.\n *\n * This helper constructs a CLI argument definition compatible with\n * Commander argument parsing while providing a consistent creation\n * entry point within the framework.\n *\n * @param name Argument definition string (e.g. `<file>` or `[dir]`).\n * @param description Optional argument description used in help output.\n *\n * @returns A newly created {@link CliArgument | **`CliArgument`**} instance.\n */\nexport const cliCreateArgument = (\n  name: string,\n  description?: string\n): CliArgument => new CliArgument(name, description);\n\n/**\n * @deprecated `Un-Used`.\n */\nexport type ArgumentType = Argument;\n","import { Command } from \"commander\";\n\nimport { CliCommand } from \"../core/command\";\n\n/** ----------------------------------------------------------------\n * * ***CLI Command Factory.***\n * ----------------------------------------------------------------\n *\n * Creates a new {@link CliCommand | **`CliCommand`**} instance.\n *\n * This helper acts as a small factory for constructing command\n * objects used by the CLI framework. It ensures all commands are\n * created through the same entry point, which allows future\n * extensions (such as internal metadata attachment or lifecycle\n * hooks) without changing call sites.\n *\n * @param name Optional command name.\n *\n * @returns A newly created {@link CliCommand | **`CliCommand`**} instance.\n */\nexport const cliCreateCommand = (name?: string): CliCommand =>\n  new CliCommand(name);\n\n/**\n * @deprecated `Un-Used`.\n */\nexport type CommandType = Command;\n","import { Option } from \"commander\";\nimport { CliOption } from \"../core/option\";\n\n/** ----------------------------------------------------------------\n * * ***CLI Option Factory.***\n * ----------------------------------------------------------------\n *\n * Creates a new {@link CliOption | **`CliOption`**} instance.\n *\n * This helper constructs a CLI option definition compatible with\n * Commander option parsing while ensuring a consistent factory\n * entry point for option creation within the framework.\n *\n * @param arg Option flags definition\n * (e.g. `\"-p, --port <number>\"`).\n *\n * @param description Optional description displayed in help output.\n *\n * @returns A newly created {@link CliOption | **`CliOption`**} instance.\n */\nexport const cliCreateOption = (arg: string, description?: string): CliOption =>\n  new CliOption(arg, description);\n\n/**\n * @deprecated `Un-Used`.\n */\nexport type OptionType = Option;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,SAAgB,iBAAiB,KAA0C;AACzE,QAAO,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACrBxB,SAAgB,qBAAqB,KAAsB;AACzD,KAAI,eAAe,eAAgB,QAAO,IAAI;AAE9C,QAAO,OAAO,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACIpB,SAAgB,sBAAsB,KAAyC;AAC7E,KAAI,eAAe,eAAgB,QAAO,IAAI;AAE9C,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACXT,IAAa,aAAb,cAAgC,QAAQ;;;;;;;;;;CAUtC,YAAY,MAAe;AACzB,SAAO,iBAAiB,KAAK,GAAG,OAAO;AACvC,QAAM,KAAK;;CAwCb,AAAS,MAAM,KAAqC;AAClD,MAAI,QAAQ,OAAO;AACjB,SAAM,MAAM,GAAG;AACf,UAAO;;AAGT,MAAI,CAAC,iBAAiB,IAAI,CACxB,QAAO,MAAM,OAAO;AAGtB,SAAO,MAAM,MAAM,IAAI;;CAyKzB,AAAS,QAAQ,KAAsB,OAAgB,aAAsB;AAC3E,MAAI,QAAQ,OAAO;AACjB,SAAM,QAAQ,GAAG;AACjB,UAAO;;AAGT,MAAI,CAAC,iBAAiB,IAAI,CACxB,QAAO,MAAM,SAAS;AAGxB,SAAO,MAAM,QAAQ,KAAK,OAAO,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACnNjD,SAAgB,oBAAoB,KAAqB;AAEvD,KAAI,iBAAiB,IAAI,EAAE;EACzB,MAAM,OAAO,IAAI;AAGjB,MAAI,SAAS,6BAA6B,SAAS,oBACjD,SAAQ,KAAK,EAAE;AAIjB,UAAQ,KAAK,IAAI,YAAY,EAAE;;AAIjC,SAAQ,MAAM,IAAI;AAClB,SAAQ,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACmSjB,SAAgB,kBACd,OACA,MACY;;AAEZ,KACE,UAAU,QACT,OAAO,UAAU,YAAY,OAAO,UAAU,WAE/C,QAAO;AAKT,QAAO,OAAO,eAAe,MAAM,KAAK,KAAK;;;;;;;;;;;;;;;;ACjX/C,IAAa,UAAb,cAA6B,KAAK;CAChC,cAAc;AACZ,SAAO;;;;;;;;;;;;;;;;;;;;;;ACGX,IAAa,YAAb,cAA+B,OAAO;CACpC,YAAY,KAAa,aAAsB;AAC7C,QAAM,KAAK,YAAY;;;;;;ACrB3B,MAAM,uBACJ,OAAO,WAAW,cAClB,OAAO,OAAO,IAAI,KAAK,YACvB,OAAO,OAAO,QAAQ,cACtB,OAAO,OAAO,WAAW;;;;;;;;;;;;;;;;;;AAmB3B,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;AAyBrB,SAAS,YAAiB;AACxB,KAAI,OAAO,eAAe,YAAa,QAAO;AAC9C,KAAI,OAAO,SAAS,YAAa,QAAO;AACxC,KAAI,OAAO,WAAW,YAAa,QAAO;AAC1C,KAAI,OAAO,WAAW,YAAa,QAAO;AAC1C,QAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;AAwBX,SAAS,YAAY;AACnB,QACE,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,EAAE,GACnC,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,EAAE,GACnC,KAAK,KAAK,CAAC,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC3B,SAAS,kBAAkB,MAAwB;AACjD,KAAI,qBACF,QAAO,OAAO,KAAK;AAGrB,QAAO,kBAAkB,QAAQ,MAAM,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkC1D,SAAS,mBAAmB,KAAa;AACvC,KAAI,qBACF,QAAO,OAAO,IAAI,IAAI;CAGxB,MAAM,WAAW,aAAa;AAE9B,KAAI,SAAS,MAAM,KACjB,QAAO,SAAS,MAAM;CAExB,MAAM,QAAQ,kBAAkB,MAAM,MAAM,WAAW;AAEvD,UAAS,MAAM,OAAO;AACtB,UAAS,QAAQ,IAAI,OAAO,IAAI;AAEhC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDT,SAAS,cAAc;CACrB,MAAM,IAAI,WAAW;AAErB,KAAI,CAAC,EAAE,cACL,GAAE,gBAAgB;EAChB,OAAO,OAAO,OAAO,KAAK;EAC1B,yBAAS,IAAI,KAAK;EACnB;AAGH,QAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEX,MAAa,aAAoC,OAAO,OACtD,SAAS,WAAW,aAA+B;AAEjD,QAAO,kBAAkB,YAAY;GAEvC;CACE,IAAI,KAAa;AACf,SAAO,mBAAmB,IAAI;;CAGhC,OAAO,KAAa;AAClB,MAAI,wBAAwB,OAAO,QAAQ,SACzC,QAAO,OAAO,OAAO,IAAI;AAI3B,SADiB,aAAa,CACd,QAAQ,IAAI,IAAI;;CAEnC,CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC5QD,MAAa,4BAA2C,WACtD,qCACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCD,SAAgB,6BAA6B;AAC3C,QAAO;EACL,IAAI;EACJ,MAAM;EACN,aAAa;EACb,aAAa;EACb,cAAc;EACd,aAAa;EACb,iBAAiB;EACjB,gBAAgB;EAChB,iBAAiB;EACjB,kBAAkB;EACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BH,MAAa,2BACX,QAC2B;CAC3B,MAAM,QAAQ,4BAA4B;AAG1C,KAAI,oBAAoB,OAAO,uBAAuB,KAAK;AACzD,MAAI,kBAAkB,MAAM;AAC5B,SAAO;;AAIT,KAAI,6BAA6B;AAEjC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCT,SAAgB,iBAAiB,KAA6C;AAE5E,KAAI,oBAAoB,OAAO,uBAAuB,KAAK;EACzD,IAAI,QAAQ,IAAI;AAEhB,MAAI,CAAC,OAAO;AACV,WAAQ,wBAAwB,IAAI;AACpC,OAAI,kBAAkB,MAAM;;AAG9B,SAAO;;AAIT,KAAI,CAAC,IAAI,2BACP,KAAI,6BAA6B,wBAAwB,IAAI;AAG/D,QAAO,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8Bb,SAAgB,mBACd,KACA,OACM;CACN,MAAM,WAAW,iBAAiB,IAAI;CACtC,MAAM,YAAY,cAAc,MAAM;AAEtC,KAAI,CAAC,SAAS,IAAI;AAChB,WAAS,KAAK;AACd;;AAGF,QAAO,OAAO,SAAS,IAAI,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CvC,SAAgB,cAAc,OAAqC;CACjE,MAAM,SAAwB,EAAE;AAEhC,KAAI,iBAAiB,MAAM,MAAM,CAC/B,QAAO,QAAQ,MAAM;AAGvB,KAAI,iBAAiB,MAAM,MAAM,CAC/B,QAAO,QAAQ,MAAM;AAGvB,KAAI,iBAAiB,MAAM,YAAY,CACrC,QAAO,cAAc,MAAM;AAG7B,KAAI,iBAAiB,MAAM,QAAQ,CACjC,QAAO,UAAU,MAAM;AAGzB,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC7PT,SAAgB,WACd,KACA,EACE,sBACA,aAAa,EACX,QAAQ,OACR,WAAW,sBACX,UAAU,iBACR,EAAE,KAoBJ,EAAE,EACN;AACA,KAAI,CAAC,iBAAiB,IAAI,CACxB,OAAM,mBAAmB,KAAK,OAAO,UAAU,KAAK,QAAQ;AAG9D,QAAO,IACJ,MAAM,MAAM,CACZ,KAAK,OAAO,UAAU;AACrB,MAAI,CAAC,CAAC,wBAAwB,UAAU,EACtC,QAAO,WAAW,WAAW,MAAM;AAGrC,MAAI,UAAU,YACZ,QAAO,WAAW,WAAW,MAAM;AAGrC,MAAI,UAAU,YACZ,QAAO,WAAW,cAAc,MAAM;AAGxC,MAAI,MAAM,WAAW,IAAI,IAAI,MAAM,SAAS,IAAI,CAC9C,QAAO,WAAW,KAAK,MAAM;AAG/B,MAAI,MAAM,WAAW,IAAI,IAAI,MAAM,SAAS,IAAI,CAC9C,QAAO,WAAW,KAAK,MAAM;AAG/B,SAAO;GACP,CACD,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0Cd,SAAgB,aACd,KACA,EACE,aAAa,EACX,QAAQ,OACR,WAAW,sBACX,UAAU,mBACR,EAAE,KAgBJ,EAAE,EACN;AACA,KAAI,CAAC,iBAAiB,IAAI,CACxB,OAAM,mBAAmB,KAAK,OAAO,UAAU,KAAK,QAAQ;CAG9D,MAAM,SAAS,IAAI,MAAM,OAAO,IAAI,EAAE;CAEtC,MAAM,eAAe,OAAO,QAAQ,MAAM,MAAM,YAAY;AAG5D,QAAO,CAAC,GAFY,OAAO,QAAQ,MAAM,MAAM,YAAY,EAEnC,GAAG,aAAa,CAAC,KAAK,IAAI;;;;;;;;;;;AC7JpD,IAAa,aAAb,cAAgC,QAAQ;CACtC,cAAc;AACZ,SAAO;;;;;;;;;;;;;;;;;;;;;;;CAwBT,aAAa,KAA6B;EACxC,MAAM,EAAE,aAAa,IAAI,iBAAiB,iBAAiB,IAAI;AAE/D,MAAI,aAAc,QAAO;AAGzB,MAAI,iBAAiB,YAAY,CAAE,QAAO;AAG1C,MAAI,iBAAiB,IAAI,MAAM,CAAE,QAAO,GAAG;AAG3C,SAAO,WACL,aAAa,MAAM,aAAa,IAAI,EAAE,EACpC,aAAa;GACX,OAAO;GACP,SAAS;GACV,EACF,CAAC,EACF;GACE,sBAAsB;GACtB,aAAa;IACX,OAAO;IACP,SACE;IACH;GACF,CACF;;;;;;;;;;CAWH,WAAW,KAAqB,QAAyB;EACvD,MAAM,QAAQ,KAAK,aAAa,IAAI;EACpC,MAAM,aAAa,eAAe,WAAW,MAAM,SAAS,EAAE,KAAK,QAAQ;EAC3E,MAAM,OAAO,MAAM,WAAW,KAAK,OAAO;AAE1C,MAAI,CAAC,MACH,QAAO,KAAK,QAAQ,2BAA2B,GAAG;AAGpD,SAAO,KAAK,QAAQ,2BAA2B,aAAa,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;CAwBxE,kBAAkB,QAAmB;EACnC,IAAI,OAAO,OAAO,eAAe;EAEjC,MAAM,aAAa,OAAO,iBAAiB;AAE3C,MAAI,iBAAiB,KAAK,EAAE;AAC1B,UAAO,KAAK,MAAM;AAElB,OAAI,YAAY;AACd,QAAI,KAAK,SAAS,IAAI,CACpB,QAAO,KAAK,MAAM,GAAG,GAAG,GAAG;aAClB,CAAC,KAAK,SAAS,IAAI,CAC5B,SAAQ;AAGV,YAAQ,IAAI,WAAW,OAAO,aAAa,kBAAkB,OAAO,aAAa,CAAC,GAAG,CAAC;cAElF,CAAC,KAAK,MAAM,CAAC,SAAS,IAAI,CAC5B,SAAQ;;AAKd,SAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACzGX,SAAgB,gCACd,gBACQ;AACR,QAAO,kBAAkB,gBAAgB,mBAAmB,GACxD,6CACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CN,SAAgB,iCACd,gBACQ;AACR,QAAO,kBAAkB,gBAAgB,QAAQ,GAC7C,YACA,kBAAkB,gBAAgB,WAAW,GAC3C,eACA;;;;;;;;;;;;;;;ACrER,SAAgB,eAAe,KAAqB;CAClD,MAAM,gBAAgB,IAAI,MAAM,KAAK,IAAI;CAIzC,SAAS,MAAM,KAAwC;AACrD,MAAI,CAAC,MAAM,IAAI,EAAE;AAEf,OAAI,QAAQ,OAAO;AACjB,qBAAiB,IAAI,CAAC,cAAc;AACpC,qBAAiB,IAAI,CAAC,eAAe;AAErC,WAAO;;AAGT,OAAI,CAAC,iBAAiB,IAAI,EAAE;IAC1B,MAAM,wBAAwB,gCAAgC,IAAI;IAClE,MAAM,uBAAuB,iCAAiC,IAAI;AAElE,UAAM,mBAAmB,KACvB,SACA,sCACA,KACA,IAAI,qBAAqB,SAAS,wBACnC;;AAGH,oBAAiB,IAAI,CAAC,cAAc;AACpC,UAAO,cAAc,IAAI;;AAG3B,SAAO,eAAe;;AAGxB,KAAI,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACtBd,MAAa,wBAAwB,WAAW;CAC9C,OAAO;EAKL,SAAS;EAMT,MAAM;EACP;CAED,cAAc;EAKZ,MAAM;EAKN,SAAS;EACV;CACF,CAAC;;;;AC7CF,MAAM,EAAE,8BAAc,mBAAU;;;;;;;;;;;;;AAchC,SAAgB,cAAc,KAAqB;CACjD,SAAS,uBAAuB,KAAqB;AACnD,mBAAiB,IAAI,CAAC,OAAO;;CAG/B,MAAM,WAAW,IAAI,WAAW,KAAK,IAAI;AAEzC,KAAI,aAAa,SACf,OACA,aACsB;EACtB,MAAM,wBAAwB,gCAAgC,IAAI;EAClE,MAAM,uBAAuB,iCAAiC,IAAI;AAElE,MAAI,CAAC,MAAM,MAAM,IAAI,CAAC,iBAAiB,MAAM,IAAI,CAAC,UAAU,MAAM,EAAE;AAClE,0BAAuB,IAAI;AAE3B,SAAM,mBAAmB,KACvB,SACA,mCACA,OACA,IAAI,qBAAqB,cAAc,wBACxC;;AAGH,MAAI,CAAC,MAAM,YAAY,IAAI,CAAC,iBAAiB,YAAY,EAAE;AACzD,0BAAuB,IAAI;AAE3B,SAAM,mBAAmB,KACvB,eACA,kCACA,aACA,IAAI,qBAAqB,cAAc,wBACxC;;EAGH,MAAM,QAAQ,iBAAiB,YAAY,GACvC,cACAA,eAAa;AAEjB,MAAI,UAAU,OAAO;AACnB,oBAAiB,IAAI,CAAC,OAAO,EAC3B,UAAU,MACX;AACD,UAAO,SAAS,MAAM;;AAGxB,MAAI,UAAU,MAAM;AAClB,oBAAiB,IAAI,CAAC,OAAO;IAC3B,OAAOC,QAAM;IACb,aAAa;IACb,UAAU;IACX;AACD,UAAO,SAAS,OAAO,MAAM;;AAG/B,MAAI,iBAAiB,MAAM,EAAE;AAC3B,oBAAiB,IAAI,CAAC,OAAO;IAC3B;IACA,aAAa;IACb,UAAU;IACX;AACD,UAAO,SAAS,OAAO,MAAM;;AAG/B,SAAO,SAAS,OAAO,MAAM;;;;;;AC/EjC,MAAM,EAAE,mBAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkElB,SAAgB,iBACd,KACA,oBACA;CACA,MAAM,kBAAkB,IAAI,QAAQ,KAAK,IAAI;AAE7C,kBAAiB,IAAI,CAAC,kBAAkB;CASxC,SAAS,QACP,OACA,OACA,aAC2C;AAC3C,MAAI,UAAU,WAAW,EAAG,QAAO,iBAAiB;AAEpD,MAAI,UAAU,OAAO;AACnB,oBAAiB,IAAI,CAAC,iBAAiB;AAEvC,oBAAiB,IAAI,CAAC,kBAAkB;AAExC,UAAO;;EAGT,MAAM,wBAAwB,gCAAgC,IAAI;EAClE,MAAM,uBAAuB,iCAAiC,IAAI;AAElE,MAAI,CAAC,iBAAiB,MAAM,CAC1B,OAAM,mBAAmB,KACvB,OACA,sBACA,OACA,IAAI,qBAAqB,WAAW,wBACrC;AAGH,MAAI,CAAC,MAAM,MAAM,IAAI,CAAC,iBAAiB,MAAM,CAC3C,OAAM,mBAAmB,KACvB,SACA,kCACA,OACA,IAAI,qBAAqB,WAAW,wBACrC;AAGH,MAAI,CAAC,MAAM,YAAY,IAAI,CAAC,iBAAiB,YAAY,CACvD,OAAM,mBAAmB,KACvB,eACA,kCACA,aACA,IAAI,qBAAqB,WAAW,wBACrC;EAGH,MAAM,QAAQ,iBAAiB,MAAM,GAAG,QAAQC,QAAM;EACtD,MAAM,QAAQ,iBAAiB,YAAY,GACvC,cACA;AAEJ,mBAAiB,IAAI,CAAC,cAAc;GAClC;GACA,OAAO;GACP,aAAa;GACd;AAED,mBAAiB,IAAI,CAAC,mBAAmB;AAEzC,SAAO,gBAAgB,OAAO,OAAO,MAAM;;AAG7C,KAAI,UAAU;;;;;;;;;;;;;;;ACnJhB,IAAa,cAAb,cAAiC,SAAS;CACxC,YAAY,KAAa,aAAsB;AAC7C,QAAM,KAAK,YAAY;;;;;;ACY3B,MAAM,EAAE,8BAAc,mBAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDhC,MAAa,6BAA6B,gBAAiC;CACzE,MAAM,uBAAuB,CAAC,iBAAiB,YAAY;AAE3D,KAAI,CAAC,YAAY,YAAY,IAAI,qBAC/B,OAAM,mBAAmB,KACvB,eACA,sBACA,aACA,4BACD;AAQH,SALa,CAAC,uBACV,0BAA0B,YAAY,KACtCC,eAAa,SAEI,MAAM,CAAC,QAAQ,QAAQ,GAAG,GAC9B;;AA+CnB,SAAgB,uBACd,SAC2B;AAC3B,KAAI,CAAC,MAAM,QAAQ,IAAI,CAAC,iBAAiB,QAAQ,CAC/C,OAAM,mBAAmB,KACvB,WACA,yCACA,SACA,4BACD;AAGH,KAAI,OAAO,QAAQ,CAAE,QAAO;AAC5B,QAAO,SAAS,QAAQ,YAAY,GAAG;;;;;;;;;;;;;;;;;;AA+BzC,SAAgB,sBACd,KACA,SACM;CACN,MAAM,EAAE,kBAAkB,sBAAsB;CAChD,MAAM,YAAY,iBAAiB,IAAI;AAEvC,KAAI,CAAC,UAAU,oBAAoB,CAAC,UAAU,iBAAiB;EAC7D,MAAM,oBAAoB,iBAAiB,iBAAiB;EAE5D,MAAM,WAAW,oBAAoB,mBAAmB;EAExD,MAAM,YAAY,oBACd,GAAG,iBAAiB,GAAG,WAAW,MAAM,UAAU,CAAC,KACnD,GAAG,WAAW,WAAW,UAAU,CAAC;AAExC,YAAU,kBACR,eACE,WACA,WACE,GAAG,WAAW,cAAc,MAAM,WAAW,IAC7C,GAAG,WAAW,KAAK,IAAI,oBAAoB,GAC5C,CACF,EACDC,QAAM,SACN,0BAA0B,SAAS,CACpC;AAED,YAAU,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACxGhC,SAAgB,mCACd,QAC6B;CAC7B,MAAM,EAAE,SAAS,aAAa,gBAAgB,iBAAiB,OAAO;;CAGtE,MAAM,kBAAkB,iBAAiB,QAAQ,GAC7C,UACA,iBAAiB,iBAAiB,YAAY,GAC5C,gBAAiB,cACjB,iBAAiB,QAAQ,KAAK,GAAG,GAC/B,MAAM,QAAQ,KAAK,GAAG,CAAC,OACvB;;CAGR,MAAM,gBAAgB,iBAAiB,OAAO;CAC9C,MAAM,eAAe,iBAAiB,cAAc,GAChD,gBACA,iBAAiB,IAAI,MAAM,GACzB,GAAG,QACH;;CAGN,MAAM,sBAAsB,iBAAiB,YAAY,GACrD,cACA,iBAAiB,iBAAiB,YAAY,GAC5C,gBAAgB,cAChB,aAAa;;CAGnB,MAAM,yBAAyB,iBAAiB,eAAe,GAC3D,iBACA,iBAAiB,iBAAiB,QAAQ,GACxC,gBAAgB,UAChB,aAAa;;CAGnB,MAAM,oBAAoB,uBAAuB,uBAAuB;;CAGxE,MAAM,oBACJ,CAAC,CAAC,mBAAmB,oBAAoB,aAAa;;CAGxD,MAAM,mBAAmB,GAAG,WAAW,WAAW,oBAAoB,GACpE,oBAAoB,IAAI,WAAW,WAAW,IAAI,gBAAgB,GAAG,KAAK;;CAI5E,MAAM,wBAAwB,WAC5B,WAAW,WAAW,aAAa,OAAO,MAAM,kBAAkB,EAClE,oBACI,GAAG,WAAW,cAAc,MAAM,WAAW,CAAC,GAAG,WAAW,aAAa,gBAAgB,KACzF,MACL;AAED,QAAO,OAAO,OAAO;EACnB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AChIJ,SAAgB,+BACd,SACA,SACM;CACN,MAAM,EAAE,qBAAqB;CAE7B,MAAM,gBAAgB,QAAQ,MAAM,KAAK,QAAQ;CACjD,MAAM,qBAAqB,QAAQ,WAAW,KAAK,QAAQ;AAE3D,SAAQ,QAAQ,SAAU,GAAG,MAAM;AACjC,wBAAsB,SAAS,iBAAiB;AAChD,SAAO,cAAc,GAAG,KAAK;;AAG/B,SAAQ,aAAa,eAAgB,GAAG,MAAM;AAC5C,wBAAsB,SAAS,iBAAiB;AAChD,SAAO,mBAAmB,GAAG,KAAK;;;;;;;;;;;;;;;;;AC3BtC,IAAa,qBAAb,MAAa,2BAA2B,WAAW;;;;;;;;;;;;;;CAcjD,AAAQ;CAER,YAAY,MAAe;AACzB,QAAM,KAAK;AAEX,OAAK,qBAAqB,4BAA4B;;;;;;;;;;;;;;CAexD,IAAI,iBAAmD;AACrD,SAAO,KAAK;;;;;;;;;;;;;CAcd,kBAAkB,OAA+B;AAC/C,OAAK,qBAAqB;;CAiB5B,AAAS,cAAc,MAAmC;EACxD,MAAM,MAAM,IAAI,mBAAmB,KAAK;AAExC,MAAI,kBAAkB,EACpB,GAAG,KAAK,gBACT,CAAC;AAEF,SAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgSX,SAAgB,kBACd,UAAoC,EAAE,EAClB;AACpB,KACE,QAAQ,mBACR,CAAC,kBAAkB,QAAQ,iBAAiB,gBAAgB,CAE5D,OAAM,mBAAmB,KACvB,2BACA,8BACA,QAAQ,iBACR,oBACD;CAGH,MAAM,EACJ,cACA,uBACA,mBACA,kBACA,iBACA,wBACE,mCAAmC,QAAQ;CAE/C,MAAM,MAAM,IAAI,mBAAmB,gBAAgB;AAEnD,KAAI,kBAAkB;EACpB,GAAG,4BAA4B;EAC/B,IAAI,cAAc,QAAQ,MAAM,EAAE,CAAC;EACnC,aAAa;EACd,CAAC;AAGF,gBAAe,IAAI;AAEnB,eAAc,IAAI;AAElB,kBAAiB,KAAK,0BAA0B,iBAAiB,CAAC;AAElE,KAAI,mBAAmB,IAAI,YAAY;AAEvC,KAAI,YACF,UACA,eAAe,IAAI,gBAAgB,uBAAuB,GAAG,CAC9D;AAED,KAAI,aAAa,oBAAoB;CAErC,MAAM,aAAa,iBAAiB,KAAK;EACvC,OAAO;EACP,OAAO,QAAQ,IAAI;EACnB,eAAe;EAChB,CAAC;AAEF,gCAA+B,YAAY,EACzC,kBAAkB;EAAE;EAAmB;EAAkB,EAC1D,CAAC;AAEF,QAAO;;;;;AChbT,MAAM,EAAE,cAAc,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyIhC,SAAgB,2BACd,QACqB;CACrB,MAAM,EAAE,SAAS,aAAa,OAAO,SAAS,gBAAgB;CAE9D,MAAM,YAAY,iBAAiB,QAAQ;CAE3C,MAAM,uBAAuB,kBAAkB,SAAS,mBAAmB;;CAG3E,MAAM,kBAAkB,iBAAiB,YAAY,GACjD,cACA,iBAAiB,QAAQ,KAAK,GAAG,GAC/B,MAAM,QAAQ,KAAK,GAAG,CAAC,OACvB;;CAGN,MAAM,oBACJ,CAAC,CAAC,mBAAmB,oBAAoB,aAAa;;CAGxD,MAAM,eAAe,iBAAiB,YAAY,GAC9C,cACA,iBAAiB,MAAM,GACrB,QACA;;CAWN,IAAI,oBAAoB,uBAPtB,CAAC,wBAAwB,iBAAiB,QAAQ,GAC9C,UACA,iBAAiB,UAAU,aAAa,MAAM,GAC5C,UAAU,YAAY,QACtB,OAG8D;AAEtE,qBAAoB,iBAAiB,kBAAkB,GACnD,oBACA,uBAAuB,aAAa,QAAQ;;CAGhD,MAAM,wBAAwB,WAC5B,WAAW,YACR,iBAAiB,UAAU,YAAY,GACpC,UAAU,cACV,aAAa,QACf,MACA,kBACH,EACD,oBACI,GAAG,WAAW,cAAc,MAAM,WAAW,CAAC,GAAG,WAAW,aAAa,gBAAgB,KACzF,MACL;;CAGD,MAAM,eAAe,iBAAiB,UAAU,YAAY,GACxD,UAAU,cACV,iBAAiB,UAAU,IAAI,MAAM,GACnC,UAAU,GAAG,SACZ,oBACG,GAAG,WAAW,WAAW,gBAAgB,CAAC,KAC1C,OACH,iBAAiB,QAAQ,OAAO,CAAC,GAC9B,WACE,aAAa,QAAQ,OAAO,EAAE,EAC5B,aAAa;EACX,OAAO;EACP,SACE;EACH,EACF,CAAC,EACF,EACE,aAAa;EACX,OAAO;EACP,SACE;EACH,EACF,CACF,GACD;;CAGV,MAAM,sBAAsB,iBAAiB,YAAY,GACrD,cACA,aAAa;;CAGjB,MAAM,+BAA+B,GAAG,WAAW,WAAW,oBAAoB,GAAG,oBAAoB,IAAI,WAAW,WAAW,IAAI,gBAAgB,GAAG,KAAK;;CAG/J,MAAM,WAAW,UAAU;CAC3B,MAAM,iBAAiB,UAAU,aAAa;CAC9C,MAAM,YAAY,UAAU,SAAS,MAAM;CAC3C,MAAM,WAAW,UAAU,eAAe,aAAa;AAEvD,QAAO,OAAO,OAAO;EACnB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAM;GACJ,MAAM;GACN,UAAU;GACV,OAAO;GACP,aAAa;GACd;EACF,CAAC;;;;;ACgBJ,SAAgB,iBACd,SACA,SACgB;CAChB,MAAM,EAAE,OAAO,OAAO,SAAS,aAAa,kBAAkB;AAE9D,KACE,CAAC,kBAAkB,SAAS,QAAQ,IACpC,CAAC,kBAAkB,SAAS,WAAW,IACvC,CAAC,kBAAkB,SAAS,mBAAmB,CAE/C,OAAM,mBAAmB,KACvB,WACA,oFACA,SACA,mBACD;AAGH,oBAAmB,SAAS;EAAE;EAAO;EAAO,CAAC;AAE7C,KAAI,CAAC,kBAAkB,SAAS,mBAAmB,EAAE;EACnD,MAAM,EACJ,cACA,uBACA,mBACA,iCACE,2BAA2B;GACpB;GACT,aAAa;GACb;GACA;GACA;GACD,CAAC;AAGF,iBAAe,QAAQ;AAEvB,gBAAc,QAAQ;AAEtB,mBACE,SACA,0BAA0B,6BAA6B,CACxD;AAED,UAAQ,mBAAmB,IAAI,YAAY;AAE3C,UAAQ,YACN,UACA,eAAe,IAAI,gBAAgB,uBAAuB,GAAG,CAC9D;AAED,UAAQ,aAAa,oBAAoB;AAEzC,iCAA+B,SAAS,EACtC,kBAAkB;GAChB;GACA,kBAAkB;GACnB,EACF,CAAC;;AAIJ,SAAQ,QAAQ,SAAU,SAAS;EACjC,IAAI,SAAS,QAAQ,QAAQ,eAAe,GAAG;AAC/C,WAAS,OAAO,MAAM,CAAC,QAAQ,QAAQ,GAAG,GAAG;EAE7C,MAAM,EAAE,iBAAiB,iBAAiB,QAAQ;EAElD,MAAM,EAAE,uBAAuB,cAAc,SAC3C,2BAA2B;GAChB;GACT;GACA,aAAa;GACd,CAAC;EAEJ,MAAM,WAAW;GACf,iBAAiB,MAAM,GAAG,QAAQ;GAClC;GACA,GAAG,WAAW,KAAK,GAAG,WAAW,IAAI,GAAG,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,WAAW,UAAU,OAAO;GAChG;AAED,MAAI,CAAC,gBAAgB,iBAAiB,aAAa,CACjD,UAAS,KACP,IACA,WAAW,KAAK,SAAS,EACzB,KAAK,WAAW,MAAM,WAAW,KAAK,aAAa,CAAC,GACrD;AAGH,MAAI,CAAC,KAAK,SACR,UAAS,KACP,IACA,GAAG,WAAW,IAAI,MAAM,CAAC,GAAG,WAAW,WAAW,KAAK,MAAM,CAAC,GAAG,WAAW,IAAI,KAAK,YAAY,GAClG;AAGH,UAAQ,MAAM,eAAe,GAAG,SAAS,CAAC;AAE1C,UAAQ,KAAK,EAAE;;AAGjB,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;AC/WT,MAAa,aAAyB,IAAI,YAAY;;;;;;;;;;;ACZtD,IAAa,oBAAb,cAAuC,eAAe;CACpD,YAAY,UAAkB,MAA0B,SAAiB;AACvE,QAAM,UAAU,MAAM,QAAQ;;;;;;;;;;ACPlC,IAAa,0BAAb,cAA6C,qBAAqB;CAChE,YAAY,SAAiB;AAC3B,QAAM,QAAQ;;;;;;;;;;ACFlB,IAAa,gCAAb,cAAmD,2BAA2B;CAC5E,YAAY,SAAiB;AAC3B,QAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;ACWlB,MAAa,qBACX,MACA,gBACgB,IAAI,YAAY,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;ACFpD,MAAa,oBAAoB,SAC/B,IAAI,WAAW,KAAK;;;;;;;;;;;;;;;;;;;;;ACDtB,MAAa,mBAAmB,KAAa,gBAC3C,IAAI,UAAU,KAAK,YAAY"}