@rzl-zone/build-tools 0.0.10 → 0.0.11

package/dist/{identity-D192lL-_.cjs.map → identity-Crq3bzhv.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"identity-D192lL-_.cjs","names":["packageJson.name","packageJson.version","isNonEmptyString","ICONS","picocolors"],"sources":["../package.json","../src/_internal/constants/package-meta.ts","../src/commander-kit/identity/index.ts"],"sourcesContent":["","import packageJson from \"../../../package.json\";\n\n/** ----------------------------------------------------------------\n * * ***Shared package metadata derived from the package manifest.***\n * ----------------------------------------------------------------\n *\n * Centralized access to metadata sourced from the root\n * `package.json` file.\n *\n * - *This utility exists to:*\n *      - Avoid repeated `package.json` imports across Node.js entry points.\n *      - Ensure consistent versioning and naming.\n *      - Provide a single source of truth for package-level metadata.\n *\n * - ⚠️ **Important:**\n *      - This file MUST only be imported in Node.js environments.\n *      - Not intended for browser or edge runtimes.\n *\n * @internal\n *\n */\nexport const PACKAGE_META = Object.freeze({\n  /** Package name. */\n  name: packageJson.name,\n\n  /** Current package version. */\n  version: packageJson.version\n});\n","import \"@rzl-zone/node-only\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { PACKAGE_META } from \"@/_internal/constants/package-meta\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { picocolors } from \"@/utils/client\";\n\n/** ----------------------------------------------------------------\n * * ***Options for generating a utility command title.***\n * ----------------------------------------------------------------\n *\n * Used by `CommandIdentity.utility()`.\n */\ntype CommandUtilityTitleOptions = {\n  /** ----------------------------------------------------------------\n   * * ***Command name displayed in the title.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides the default command name provided in the constructor.\n   *\n   * @example\n   * ```ts\n   * { commandName: \"fix-dts-react-import\" }\n   * ```\n   */\n  commandName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Optional arrow icon override.***\n   * ----------------------------------------------------------------\n   *\n   * If provided, this icon replaces the generator's\n   * `defaultIconArrow` for this call only.\n   *\n   * @example\n   * ```ts\n   * { iconArrow: \"⇒\" }\n   * ```\n   */\n  iconArrow?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package name prefix.***\n   * ----------------------------------------------------------------\n   *\n   * Displayed at the beginning of every generated title.\n   *\n   * @default \"@rzl-zone/build-tools\"\n   */\n  packageName?: string;\n};\n\n/** ----------------------------------------------------------------\n * * ***Options for generating a CLI command title.***\n * ----------------------------------------------------------------\n *\n * Used by `CommandIdentity.cli()`\n */\ntype CommandCliTitleOptions = Omit<\n  CommandUtilityTitleOptions,\n  \"packageName\"\n> & {\n  /** ----------------------------------------------------------------\n   * * ***Package name prefix.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides the resolved CLI package name for this call only.\n   *\n   * @default \"@rzl-zone/build-tools-cli\"\n   */\n  packageName?: string;\n};\n\n/** ----------------------------------------------------------------\n * * ***Global configuration for command identity formatting.***\n * ----------------------------------------------------------------\n *\n * Defines the default identity behavior applied to\n * all generated CLI and utility titles.\n */\ntype CommandIdentityOptions = {\n  /** ----------------------------------------------------------------\n   * * ***Default command name.***\n   * ----------------------------------------------------------------\n   *\n   * Used when a command name is not provided in the respective in method `CommandIdentity.cli()` and `CommandIdentity.utility()` options.\n   *\n   * @example\n   * ```ts\n   * defaultCommandName: \"fix-dts-react-import\"\n   * ```\n   */\n  defaultCommandName: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package name prefix.***\n   * ----------------------------------------------------------------\n   *\n   * Optional base package name used for title generation.\n   *\n   * If not provided, an internal default will be resolved\n   * depending on the title type (`CLI` or `utility`).\n   */\n  packageName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package version.***\n   * ----------------------------------------------------------------\n   *\n   * Optional version displayed alongside the package name\n   * in generated titles.\n   *\n   * If not provided, a default version will be resolved internally.\n   *\n   * @example\n   * ```ts\n   * version: \"1.2.0\"\n   * ```\n   */\n  version?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Label for CLI commands.***\n   * ----------------------------------------------------------------\n   *\n   * Optional label displayed between\n   * the package name and arrow icon for CLI titles.\n   */\n  cliLabel?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Label for utility commands.***\n   * ----------------------------------------------------------------\n   *\n   * Optional label displayed between\n   * the package name and arrow icon for utility titles.\n   */\n  utilityLabel?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Default arrow icon.***\n   * ----------------------------------------------------------------\n   *\n   * Icon displayed between the label and command name.\n   *\n   * @default\n   * \"▶️\"\n   * // or\n   * \"▶\"\n   */\n  defaultIconArrow?: string;\n};\n\n/** ----------------------------------------------------------------\n * * ***Command identity formatter with consistent CLI styling.***\n * ----------------------------------------------------------------\n *\n * Responsible for generating formatted and colorized\n * command titles for CLI and utility commands.\n *\n * - ***Each generated title may include:***\n *      - Package name.\n *      - Optional label (CLI / utility).\n *      - Arrow icon.\n *      - Command name.\n *      - Package version.\n *\n * ---\n *\n * @example\n * ```ts\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"fix-dts-react-import\"\n * });\n *\n * identity.cli();\n * // => \"@rzl-zone/build-tools-cli@<version> ➔ fix-dts-react-import\"\n *\n * identity.utility({ commandName: \"clean-dist\" });\n * // => \"@rzl-zone/build-tools@<version> ➔ clean-dist\"\n * ```\n *\n * @example\n * ```ts\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"build\",\n *   version: \"2.1.0\"\n * });\n *\n * identity.cli();\n * // => \"@rzl-zone/build-tools-cli@2.1.0 ➔ build\"\n *\n * identity.utility({ commandName: \"clean-dist\" });\n * // => \"@rzl-zone/build-tools@2.1.0 ➔ clean-dist\"\n * ```\n */\nexport class CommandIdentity {\n  /** Default command name.\n   *\n   * @internal\n   */\n  private _commandName: string;\n\n  /** Package name.\n   *\n   * @internal\n   */\n  private _packageName: string | undefined;\n\n  /** Package version.\n   *\n   * @internal\n   */\n  private _version: string;\n\n  /** Label for CLI commands.\n   *\n   * @internal\n   */\n  private cliLabel: string | undefined;\n\n  /** Label for utility commands.\n   *\n   * @internal\n   */\n  private utilityLabel: string | undefined;\n\n  /** Default arrow icon.\n   *\n   * @internal\n   */\n  private defaultIconArrow: string;\n\n  /** @internal */\n  private static readonly DEFAULT_UTILITY_PACKAGE = \"@rzl-zone/build-tools\";\n  /** @internal */\n  private static readonly DEFAULT_CLI_PACKAGE = \"@rzl-zone/build-tools-cli\";\n\n  /** ----------------------------------------------------------------\n   * * ***Create a new command identity instance.***\n   * ----------------------------------------------------------------\n   *\n   * Initializes global identity configuration\n   * used by `CommandIdentity.cli()` and `CommandIdentity.utility()`.\n   *\n   * ---\n   *\n   * @param {CommandIdentityOptions} options - Global identity configuration.\n   * @throws {Error} If `options.defaultCommandName` is missing or empty.\n   *\n   * ---\n   *\n   * @example\n   * ```ts\n   * const identity = new CommandIdentity({\n   *   defaultCommandName: \"fix-dts-react-import\"\n   * });\n   *\n   * identity.cli();\n   * // => \"@rzl-zone/build-tools-cli@<version> ➔ fix-dts-react-import\"\n   *\n   * identity.utility({ commandName: \"clean-dist\" });\n   * // => \"@rzl-zone/build-tools@<version> ➔ clean-dist\"\n   * ```\n   *\n   * @example\n   * ```ts\n   * const identity = new CommandIdentity({\n   *   defaultCommandName: \"build\",\n   *   version: \"2.1.0\"\n   * });\n   *\n   * identity.cli();\n   * // => \"@rzl-zone/build-tools-cli@2.1.0 ➔ build\"\n   *\n   * identity.utility({ commandName: \"clean-dist\" });\n   * // => \"@rzl-zone/build-tools@2.1.0 ➔ clean-dist\"\n   * ```\n   */\n  constructor(options: CommandIdentityOptions) {\n    if (!isNonEmptyString(options.defaultCommandName)) {\n      throw new Error(\n        \"CommandIdentity: Default command name is missing, please provide in constructor method options, eg: ({ defaultCommandName: 'inject-directive' }).\"\n      );\n    }\n\n    this._commandName = options.defaultCommandName;\n    this._packageName = options.packageName;\n    this._version = isNonEmptyString(options.version)\n      ? options.version\n      : PACKAGE_META.version;\n\n    this.cliLabel = options.cliLabel;\n    this.utilityLabel = options.utilityLabel;\n    this.defaultIconArrow = options.defaultIconArrow ?? ICONS.arrowRight;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Internal title formatter.***\n   * ----------------------------------------------------------------\n   *\n   * Shared formatter used by `CommandIdentity.cli()` and `CommandIdentity.utility()`.\n   *\n   * @internal\n   */\n  private format(props: {\n    packageName: string;\n    label?: string;\n    name?: string;\n    iconArrow?: string;\n  }): string {\n    const { label, name, iconArrow, packageName } = props;\n    const finalName = isNonEmptyString(name) ? name : this._commandName;\n    const finalLabel = isNonEmptyString(label) ? ` ${label} ` : \" \";\n\n    if (!finalName) {\n      throw new Error(\n        \"CommandIdentity: Command name is missing. \" +\n          \"Provide `defaultCommandName` in constructor or `name` in method options.\"\n      );\n    }\n\n    const versionSuffix = isNonEmptyString(this._version)\n      ? `@${this._version}`\n      : \"\";\n\n    return (\n      `${picocolors.bold(picocolors.blue(packageName + versionSuffix))}` +\n      `${picocolors.whiteBright(finalLabel)}` +\n      `${picocolors.bold(picocolors.magentaBright(isNonEmptyString(iconArrow) ? iconArrow : this.defaultIconArrow))} ` +\n      `${picocolors.underline(picocolors.italic(picocolors.yellowBright(finalName)))}`\n    );\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Generate a CLI command title.***\n   * ----------------------------------------------------------------\n   *\n   * Uses the CLI default package (unless overridden)\n   * and applies CLI-specific labeling.\n   *\n   * @param {CommandCliTitleOptions} options - CLI title configuration.\n   *\n   * @example\n   * ```ts\n   * identity.cli();\n   * identity.cli({ commandName: \"build\" });\n   * ```\n   */\n  public cli(options: CommandCliTitleOptions = {}): string {\n    const packageName = isNonEmptyString(options.packageName)\n      ? options.packageName\n      : (this._packageName ?? CommandIdentity.DEFAULT_CLI_PACKAGE);\n\n    return this.format({\n      packageName,\n      label: this.cliLabel,\n      name: options.commandName,\n      iconArrow: options.iconArrow\n    });\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Generate a utility command title.***\n   * ----------------------------------------------------------------\n   *\n   * Uses the utility default package (unless overridden)\n   * and applies utility-specific labeling.\n   *\n   * @param {CommandUtilityTitleOptions} options - Utility title configuration.\n   *\n   * @example\n   * ```ts\n   * identity.utility();\n   * identity.utility({ commandName: \"clean-dist\", iconArrow: \"⇒\" });\n   * ```\n   */\n  public utility(options: CommandUtilityTitleOptions = {}): string {\n    const packageName = isNonEmptyString(options.packageName)\n      ? options.packageName\n      : (this._packageName ?? CommandIdentity.DEFAULT_UTILITY_PACKAGE);\n\n    return this.format({\n      packageName,\n      label: this.utilityLabel,\n      name: options.commandName,\n      iconArrow: options.iconArrow\n    });\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Package name.***\n   * ----------------------------------------------------------------\n   *\n   * Returns the effective package name used for title generation.\n   *\n   * If a custom package name has been provided via the constructor\n   * or `CommandIdentity.setPackageName()`, that value will be returned.\n   * Otherwise, an internal default package name (as utility) is used.\n   *\n   * @readonly\n   */\n  public get packageName(): string {\n    return this._packageName ?? CommandIdentity.DEFAULT_UTILITY_PACKAGE;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Set package name.***\n   * ----------------------------------------------------------------\n   *\n   * Assigns a custom package name to be used for title generation.\n   *\n   * - *This value overrides:*\n   *     - Any package name provided in the constructor.\n   *     - The internal default package name.\n   *\n   * Once set, this value will be returned by the `CommandIdentity.packageName`\n   * getter and used by `CommandIdentity.cli()` and\n   * `CommandIdentity.utility()` unless explicitly\n   * overridden per method call.\n   *\n   * @param value - The new package name to assign.\n   * @returns The current instance for fluent chaining.\n   */\n  public setPackageName(value: string): this {\n    this._packageName = value;\n    return this;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Command name.***\n   * ----------------------------------------------------------------\n   *\n   * Returns the current command name used for title generation.\n   *\n   * This value is initialized via the constructor and may be\n   * updated later using\n   * `CommandIdentity.setCommandName()`.\n   *\n   * @readonly\n   */\n  public get commandName(): string {\n    return this._commandName;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Set command name.***\n   * ----------------------------------------------------------------\n   *\n   * Updates the command name used for title generation.\n   *\n   * This overrides the command name provided in the constructor\n   * and affects subsequent calls to\n   * `CommandIdentity.cli()`\n   * and `CommandIdentity.utility()`,\n   * unless a command name is explicitly provided per method call.\n   *\n   * @param value - The new command name to assign.\n   * @returns The current instance for fluent chaining.\n   */\n  public setCommandName(value: string): this {\n    this._commandName = value;\n    return this;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Package version.***\n   * ----------------------------------------------------------------\n   *\n   * Returns the effective version used for title generation.\n   *\n   * - *Resolution order:*\n   *    1. If a custom version has been provided via the constructor\n   *       or `CommandIdentity.setVersion()`,\n   *       that value will be returned.\n   *    2. Otherwise, the version falls back to the internally\n   *       resolved default package version.\n   *\n   * A version value is always guaranteed to be present.\n   *\n   * @readonly\n   */\n  public get version(): string {\n    return this._version;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Set package version.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides the version used for title generation.\n   *\n   * If an empty or invalid value is provided,\n   * the version will remain unchanged.\n   *\n   * @param value - The new version to assign.\n   * @returns The current instance for fluent chaining.\n   */\n  public setVersion(value: string): this {\n    if (isNonEmptyString(value)) this._version = value;\n\n    return this;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACqBA,MAAa,eAAe,OAAO,OAAO;CAElCA;CAGGC;CACV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC0KF,IAAa,kBAAb,MAAa,gBAAgB;;;;;CAK3B,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;CAGR,OAAwB,0BAA0B;;CAElD,OAAwB,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2C9C,YAAY,SAAiC;AAC3C,MAAI,CAACC,gCAAiB,QAAQ,mBAAmB,CAC/C,OAAM,IAAI,MACR,oJACD;AAGH,OAAK,eAAe,QAAQ;AAC5B,OAAK,eAAe,QAAQ;AAC5B,OAAK,WAAWA,gCAAiB,QAAQ,QAAQ,GAC7C,QAAQ,UACR,aAAa;AAEjB,OAAK,WAAW,QAAQ;AACxB,OAAK,eAAe,QAAQ;AAC5B,OAAK,mBAAmB,QAAQ,oBAAoBC,qBAAM;;;;;;;;;;CAW5D,AAAQ,OAAO,OAKJ;EACT,MAAM,EAAE,OAAO,MAAM,WAAW,gBAAgB;EAChD,MAAM,YAAYD,gCAAiB,KAAK,GAAG,OAAO,KAAK;EACvD,MAAM,aAAaA,gCAAiB,MAAM,GAAG,IAAI,MAAM,KAAK;AAE5D,MAAI,CAAC,UACH,OAAM,IAAI,MACR,qHAED;EAGH,MAAM,gBAAgBA,gCAAiB,KAAK,SAAS,GACjD,IAAI,KAAK,aACT;AAEJ,SACE,GAAGE,0BAAW,KAAKA,0BAAW,KAAK,cAAc,cAAc,CAAC,GAC7DA,0BAAW,YAAY,WAAW,GAClCA,0BAAW,KAAKA,0BAAW,cAAcF,gCAAiB,UAAU,GAAG,YAAY,KAAK,iBAAiB,CAAC,CAAC,GAC3GE,0BAAW,UAAUA,0BAAW,OAAOA,0BAAW,aAAa,UAAU,CAAC,CAAC;;;;;;;;;;;;;;;;;CAmBlF,AAAO,IAAI,UAAkC,EAAE,EAAU;EACvD,MAAM,cAAcF,gCAAiB,QAAQ,YAAY,GACrD,QAAQ,cACP,KAAK,gBAAgB,gBAAgB;AAE1C,SAAO,KAAK,OAAO;GACjB;GACA,OAAO,KAAK;GACZ,MAAM,QAAQ;GACd,WAAW,QAAQ;GACpB,CAAC;;;;;;;;;;;;;;;;;CAkBJ,AAAO,QAAQ,UAAsC,EAAE,EAAU;EAC/D,MAAM,cAAcA,gCAAiB,QAAQ,YAAY,GACrD,QAAQ,cACP,KAAK,gBAAgB,gBAAgB;AAE1C,SAAO,KAAK,OAAO;GACjB;GACA,OAAO,KAAK;GACZ,MAAM,QAAQ;GACd,WAAW,QAAQ;GACpB,CAAC;;;;;;;;;;;;;;CAeJ,IAAW,cAAsB;AAC/B,SAAO,KAAK,gBAAgB,gBAAgB;;;;;;;;;;;;;;;;;;;;CAqB9C,AAAO,eAAe,OAAqB;AACzC,OAAK,eAAe;AACpB,SAAO;;;;;;;;;;;;;;CAeT,IAAW,cAAsB;AAC/B,SAAO,KAAK;;;;;;;;;;;;;;;;;CAkBd,AAAO,eAAe,OAAqB;AACzC,OAAK,eAAe;AACpB,SAAO;;;;;;;;;;;;;;;;;;;CAoBT,IAAW,UAAkB;AAC3B,SAAO,KAAK;;;;;;;;;;;;;;CAed,AAAO,WAAW,OAAqB;AACrC,MAAIA,gCAAiB,MAAM,CAAE,MAAK,WAAW;AAE7C,SAAO"}
+{"version":3,"file":"identity-Crq3bzhv.cjs","names":["packageJson.name","packageJson.version","isNonEmptyString","ICONS","picocolors"],"sources":["../package.json","../src/_internal/constants/package-meta.ts","../src/commander-kit/identity/index.ts"],"sourcesContent":["","import packageJson from \"../../../package.json\";\n\n/** ----------------------------------------------------------------\n * * ***Shared package metadata derived from the package manifest.***\n * ----------------------------------------------------------------\n *\n * Centralized access to metadata sourced from the root\n * `package.json` file.\n *\n * - *This utility exists to:*\n *      - Avoid repeated `package.json` imports across Node.js entry points.\n *      - Ensure consistent versioning and naming.\n *      - Provide a single source of truth for package-level metadata.\n *\n * - ⚠️ **Important:**\n *      - This file MUST only be imported in Node.js environments.\n *      - Not intended for browser or edge runtimes.\n *\n * @internal\n *\n */\nexport const PACKAGE_META = Object.freeze({\n  /** Package name. */\n  name: packageJson.name,\n\n  /** Current package version. */\n  version: packageJson.version\n});\n","import \"@rzl-zone/node-only\";\n\nimport { isNonEmptyString } from \"@/_internal/utils/helper\";\nimport { PACKAGE_META } from \"@/_internal/constants/package-meta\";\n\nimport { ICONS } from \"@/utils/server\";\nimport { picocolors } from \"@/utils/client\";\n\n/** ----------------------------------------------------------------\n * * ***Options for generating a utility command title.***\n * ----------------------------------------------------------------\n *\n * Used by `CommandIdentity.utility()`.\n */\ntype CommandUtilityTitleOptions = {\n  /** ----------------------------------------------------------------\n   * * ***Command name displayed in the title.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides the default command name provided in the constructor.\n   *\n   * @example\n   * ```ts\n   * { commandName: \"fix-dts-react-import\" }\n   * ```\n   */\n  commandName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Optional arrow icon override.***\n   * ----------------------------------------------------------------\n   *\n   * If provided, this icon replaces the generator's\n   * `defaultIconArrow` for this call only.\n   *\n   * @example\n   * ```ts\n   * { iconArrow: \"⇒\" }\n   * ```\n   */\n  iconArrow?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package name prefix.***\n   * ----------------------------------------------------------------\n   *\n   * Displayed at the beginning of every generated title.\n   *\n   * @default \"@rzl-zone/build-tools\"\n   */\n  packageName?: string;\n};\n\n/** ----------------------------------------------------------------\n * * ***Options for generating a CLI command title.***\n * ----------------------------------------------------------------\n *\n * Used by `CommandIdentity.cli()`\n */\ntype CommandCliTitleOptions = Omit<\n  CommandUtilityTitleOptions,\n  \"packageName\"\n> & {\n  /** ----------------------------------------------------------------\n   * * ***Package name prefix.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides the resolved CLI package name for this call only.\n   *\n   * @default \"@rzl-zone/build-tools-cli\"\n   */\n  packageName?: string;\n};\n\n/** ----------------------------------------------------------------\n * * ***Global configuration for command identity formatting.***\n * ----------------------------------------------------------------\n *\n * Defines the default identity behavior applied to\n * all generated CLI and utility titles.\n */\ntype CommandIdentityOptions = {\n  /** ----------------------------------------------------------------\n   * * ***Default command name.***\n   * ----------------------------------------------------------------\n   *\n   * Used when a command name is not provided in the respective in method `CommandIdentity.cli()` and `CommandIdentity.utility()` options.\n   *\n   * @example\n   * ```ts\n   * defaultCommandName: \"fix-dts-react-import\"\n   * ```\n   */\n  defaultCommandName: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package name prefix.***\n   * ----------------------------------------------------------------\n   *\n   * Optional base package name used for title generation.\n   *\n   * If not provided, an internal default will be resolved\n   * depending on the title type (`CLI` or `utility`).\n   */\n  packageName?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Package version.***\n   * ----------------------------------------------------------------\n   *\n   * Optional version displayed alongside the package name\n   * in generated titles.\n   *\n   * If not provided, a default version will be resolved internally.\n   *\n   * @example\n   * ```ts\n   * version: \"1.2.0\"\n   * ```\n   */\n  version?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Label for CLI commands.***\n   * ----------------------------------------------------------------\n   *\n   * Optional label displayed between\n   * the package name and arrow icon for CLI titles.\n   */\n  cliLabel?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Label for utility commands.***\n   * ----------------------------------------------------------------\n   *\n   * Optional label displayed between\n   * the package name and arrow icon for utility titles.\n   */\n  utilityLabel?: string;\n\n  /** ----------------------------------------------------------------\n   * * ***Default arrow icon.***\n   * ----------------------------------------------------------------\n   *\n   * Icon displayed between the label and command name.\n   *\n   * @default\n   * \"▶️\"\n   * // or\n   * \"▶\"\n   */\n  defaultIconArrow?: string;\n};\n\n/** ----------------------------------------------------------------\n * * ***Command identity formatter with consistent CLI styling.***\n * ----------------------------------------------------------------\n *\n * Responsible for generating formatted and colorized\n * command titles for CLI and utility commands.\n *\n * - ***Each generated title may include:***\n *      - Package name.\n *      - Optional label (CLI / utility).\n *      - Arrow icon.\n *      - Command name.\n *      - Package version.\n *\n * ---\n *\n * @example\n * ```ts\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"fix-dts-react-import\"\n * });\n *\n * identity.cli();\n * // => \"@rzl-zone/build-tools-cli@<version> ➔ fix-dts-react-import\"\n *\n * identity.utility({ commandName: \"clean-dist\" });\n * // => \"@rzl-zone/build-tools@<version> ➔ clean-dist\"\n * ```\n *\n * @example\n * ```ts\n * const identity = new CommandIdentity({\n *   defaultCommandName: \"build\",\n *   version: \"2.1.0\"\n * });\n *\n * identity.cli();\n * // => \"@rzl-zone/build-tools-cli@2.1.0 ➔ build\"\n *\n * identity.utility({ commandName: \"clean-dist\" });\n * // => \"@rzl-zone/build-tools@2.1.0 ➔ clean-dist\"\n * ```\n */\nexport class CommandIdentity {\n  /** Default command name.\n   *\n   * @internal\n   */\n  private _commandName: string;\n\n  /** Package name.\n   *\n   * @internal\n   */\n  private _packageName: string | undefined;\n\n  /** Package version.\n   *\n   * @internal\n   */\n  private _version: string;\n\n  /** Label for CLI commands.\n   *\n   * @internal\n   */\n  private cliLabel: string | undefined;\n\n  /** Label for utility commands.\n   *\n   * @internal\n   */\n  private utilityLabel: string | undefined;\n\n  /** Default arrow icon.\n   *\n   * @internal\n   */\n  private defaultIconArrow: string;\n\n  /** @internal */\n  private static readonly DEFAULT_UTILITY_PACKAGE = \"@rzl-zone/build-tools\";\n  /** @internal */\n  private static readonly DEFAULT_CLI_PACKAGE = \"@rzl-zone/build-tools-cli\";\n\n  /** ----------------------------------------------------------------\n   * * ***Create a new command identity instance.***\n   * ----------------------------------------------------------------\n   *\n   * Initializes global identity configuration\n   * used by `CommandIdentity.cli()` and `CommandIdentity.utility()`.\n   *\n   * ---\n   *\n   * @param {CommandIdentityOptions} options - Global identity configuration.\n   * @throws {Error} If `options.defaultCommandName` is missing or empty.\n   *\n   * ---\n   *\n   * @example\n   * ```ts\n   * const identity = new CommandIdentity({\n   *   defaultCommandName: \"fix-dts-react-import\"\n   * });\n   *\n   * identity.cli();\n   * // => \"@rzl-zone/build-tools-cli@<version> ➔ fix-dts-react-import\"\n   *\n   * identity.utility({ commandName: \"clean-dist\" });\n   * // => \"@rzl-zone/build-tools@<version> ➔ clean-dist\"\n   * ```\n   *\n   * @example\n   * ```ts\n   * const identity = new CommandIdentity({\n   *   defaultCommandName: \"build\",\n   *   version: \"2.1.0\"\n   * });\n   *\n   * identity.cli();\n   * // => \"@rzl-zone/build-tools-cli@2.1.0 ➔ build\"\n   *\n   * identity.utility({ commandName: \"clean-dist\" });\n   * // => \"@rzl-zone/build-tools@2.1.0 ➔ clean-dist\"\n   * ```\n   */\n  constructor(options: CommandIdentityOptions) {\n    if (!isNonEmptyString(options.defaultCommandName)) {\n      throw new Error(\n        \"CommandIdentity: Default command name is missing, please provide in constructor method options, eg: ({ defaultCommandName: 'inject-directive' }).\"\n      );\n    }\n\n    this._commandName = options.defaultCommandName;\n    this._packageName = options.packageName;\n    this._version = isNonEmptyString(options.version)\n      ? options.version\n      : PACKAGE_META.version;\n\n    this.cliLabel = options.cliLabel;\n    this.utilityLabel = options.utilityLabel;\n    this.defaultIconArrow = options.defaultIconArrow ?? ICONS.arrowRight;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Internal title formatter.***\n   * ----------------------------------------------------------------\n   *\n   * Shared formatter used by `CommandIdentity.cli()` and `CommandIdentity.utility()`.\n   *\n   * @internal\n   */\n  private format(props: {\n    packageName: string;\n    label?: string;\n    name?: string;\n    iconArrow?: string;\n  }): string {\n    const { label, name, iconArrow, packageName } = props;\n    const finalName = isNonEmptyString(name) ? name : this._commandName;\n    const finalLabel = isNonEmptyString(label) ? ` ${label} ` : \" \";\n\n    if (!finalName) {\n      throw new Error(\n        \"CommandIdentity: Command name is missing. \" +\n          \"Provide `defaultCommandName` in constructor or `name` in method options.\"\n      );\n    }\n\n    const versionSuffix = isNonEmptyString(this._version)\n      ? `@${this._version}`\n      : \"\";\n\n    return (\n      `${picocolors.bold(picocolors.blue(packageName + versionSuffix))}` +\n      `${picocolors.whiteBright(finalLabel)}` +\n      `${picocolors.bold(picocolors.magentaBright(isNonEmptyString(iconArrow) ? iconArrow : this.defaultIconArrow))} ` +\n      `${picocolors.underline(picocolors.italic(picocolors.yellowBright(finalName)))}`\n    );\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Generate a CLI command title.***\n   * ----------------------------------------------------------------\n   *\n   * Uses the CLI default package (unless overridden)\n   * and applies CLI-specific labeling.\n   *\n   * @param {CommandCliTitleOptions} options - CLI title configuration.\n   *\n   * @example\n   * ```ts\n   * identity.cli();\n   * identity.cli({ commandName: \"build\" });\n   * ```\n   */\n  public cli(options: CommandCliTitleOptions = {}): string {\n    const packageName = isNonEmptyString(options.packageName)\n      ? options.packageName\n      : (this._packageName ?? CommandIdentity.DEFAULT_CLI_PACKAGE);\n\n    return this.format({\n      packageName,\n      label: this.cliLabel,\n      name: options.commandName,\n      iconArrow: options.iconArrow\n    });\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Generate a utility command title.***\n   * ----------------------------------------------------------------\n   *\n   * Uses the utility default package (unless overridden)\n   * and applies utility-specific labeling.\n   *\n   * @param {CommandUtilityTitleOptions} options - Utility title configuration.\n   *\n   * @example\n   * ```ts\n   * identity.utility();\n   * identity.utility({ commandName: \"clean-dist\", iconArrow: \"⇒\" });\n   * ```\n   */\n  public utility(options: CommandUtilityTitleOptions = {}): string {\n    const packageName = isNonEmptyString(options.packageName)\n      ? options.packageName\n      : (this._packageName ?? CommandIdentity.DEFAULT_UTILITY_PACKAGE);\n\n    return this.format({\n      packageName,\n      label: this.utilityLabel,\n      name: options.commandName,\n      iconArrow: options.iconArrow\n    });\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Package name.***\n   * ----------------------------------------------------------------\n   *\n   * Returns the effective package name used for title generation.\n   *\n   * If a custom package name has been provided via the constructor\n   * or `CommandIdentity.setPackageName()`, that value will be returned.\n   * Otherwise, an internal default package name (as utility) is used.\n   *\n   * @readonly\n   */\n  public get packageName(): string {\n    return this._packageName ?? CommandIdentity.DEFAULT_UTILITY_PACKAGE;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Set package name.***\n   * ----------------------------------------------------------------\n   *\n   * Assigns a custom package name to be used for title generation.\n   *\n   * - *This value overrides:*\n   *     - Any package name provided in the constructor.\n   *     - The internal default package name.\n   *\n   * Once set, this value will be returned by the `CommandIdentity.packageName`\n   * getter and used by `CommandIdentity.cli()` and\n   * `CommandIdentity.utility()` unless explicitly\n   * overridden per method call.\n   *\n   * @param value - The new package name to assign.\n   * @returns The current instance for fluent chaining.\n   */\n  public setPackageName(value: string): this {\n    this._packageName = value;\n    return this;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Command name.***\n   * ----------------------------------------------------------------\n   *\n   * Returns the current command name used for title generation.\n   *\n   * This value is initialized via the constructor and may be\n   * updated later using\n   * `CommandIdentity.setCommandName()`.\n   *\n   * @readonly\n   */\n  public get commandName(): string {\n    return this._commandName;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Set command name.***\n   * ----------------------------------------------------------------\n   *\n   * Updates the command name used for title generation.\n   *\n   * This overrides the command name provided in the constructor\n   * and affects subsequent calls to\n   * `CommandIdentity.cli()`\n   * and `CommandIdentity.utility()`,\n   * unless a command name is explicitly provided per method call.\n   *\n   * @param value - The new command name to assign.\n   * @returns The current instance for fluent chaining.\n   */\n  public setCommandName(value: string): this {\n    this._commandName = value;\n    return this;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Package version.***\n   * ----------------------------------------------------------------\n   *\n   * Returns the effective version used for title generation.\n   *\n   * - *Resolution order:*\n   *    1. If a custom version has been provided via the constructor\n   *       or `CommandIdentity.setVersion()`,\n   *       that value will be returned.\n   *    2. Otherwise, the version falls back to the internally\n   *       resolved default package version.\n   *\n   * A version value is always guaranteed to be present.\n   *\n   * @readonly\n   */\n  public get version(): string {\n    return this._version;\n  }\n\n  /** ----------------------------------------------------------------\n   * * ***Set package version.***\n   * ----------------------------------------------------------------\n   *\n   * Overrides the version used for title generation.\n   *\n   * If an empty or invalid value is provided,\n   * the version will remain unchanged.\n   *\n   * @param value - The new version to assign.\n   * @returns The current instance for fluent chaining.\n   */\n  public setVersion(value: string): this {\n    if (isNonEmptyString(value)) this._version = value;\n\n    return this;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACqBA,MAAa,eAAe,OAAO,OAAO;CAElCA;CAGGC;CACV,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC0KF,IAAa,kBAAb,MAAa,gBAAgB;;;;;CAK3B,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;;;;CAMR,AAAQ;;CAGR,OAAwB,0BAA0B;;CAElD,OAAwB,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2C9C,YAAY,SAAiC;AAC3C,MAAI,CAACC,gCAAiB,QAAQ,mBAAmB,CAC/C,OAAM,IAAI,MACR,oJACD;AAGH,OAAK,eAAe,QAAQ;AAC5B,OAAK,eAAe,QAAQ;AAC5B,OAAK,WAAWA,gCAAiB,QAAQ,QAAQ,GAC7C,QAAQ,UACR,aAAa;AAEjB,OAAK,WAAW,QAAQ;AACxB,OAAK,eAAe,QAAQ;AAC5B,OAAK,mBAAmB,QAAQ,oBAAoBC,qBAAM;;;;;;;;;;CAW5D,AAAQ,OAAO,OAKJ;EACT,MAAM,EAAE,OAAO,MAAM,WAAW,gBAAgB;EAChD,MAAM,YAAYD,gCAAiB,KAAK,GAAG,OAAO,KAAK;EACvD,MAAM,aAAaA,gCAAiB,MAAM,GAAG,IAAI,MAAM,KAAK;AAE5D,MAAI,CAAC,UACH,OAAM,IAAI,MACR,qHAED;EAGH,MAAM,gBAAgBA,gCAAiB,KAAK,SAAS,GACjD,IAAI,KAAK,aACT;AAEJ,SACE,GAAGE,0BAAW,KAAKA,0BAAW,KAAK,cAAc,cAAc,CAAC,GAC7DA,0BAAW,YAAY,WAAW,GAClCA,0BAAW,KAAKA,0BAAW,cAAcF,gCAAiB,UAAU,GAAG,YAAY,KAAK,iBAAiB,CAAC,CAAC,GAC3GE,0BAAW,UAAUA,0BAAW,OAAOA,0BAAW,aAAa,UAAU,CAAC,CAAC;;;;;;;;;;;;;;;;;CAmBlF,AAAO,IAAI,UAAkC,EAAE,EAAU;EACvD,MAAM,cAAcF,gCAAiB,QAAQ,YAAY,GACrD,QAAQ,cACP,KAAK,gBAAgB,gBAAgB;AAE1C,SAAO,KAAK,OAAO;GACjB;GACA,OAAO,KAAK;GACZ,MAAM,QAAQ;GACd,WAAW,QAAQ;GACpB,CAAC;;;;;;;;;;;;;;;;;CAkBJ,AAAO,QAAQ,UAAsC,EAAE,EAAU;EAC/D,MAAM,cAAcA,gCAAiB,QAAQ,YAAY,GACrD,QAAQ,cACP,KAAK,gBAAgB,gBAAgB;AAE1C,SAAO,KAAK,OAAO;GACjB;GACA,OAAO,KAAK;GACZ,MAAM,QAAQ;GACd,WAAW,QAAQ;GACpB,CAAC;;;;;;;;;;;;;;CAeJ,IAAW,cAAsB;AAC/B,SAAO,KAAK,gBAAgB,gBAAgB;;;;;;;;;;;;;;;;;;;;CAqB9C,AAAO,eAAe,OAAqB;AACzC,OAAK,eAAe;AACpB,SAAO;;;;;;;;;;;;;;CAeT,IAAW,cAAsB;AAC/B,SAAO,KAAK;;;;;;;;;;;;;;;;;CAkBd,AAAO,eAAe,OAAqB;AACzC,OAAK,eAAe;AACpB,SAAO;;;;;;;;;;;;;;;;;;;CAoBT,IAAW,UAAkB;AAC3B,SAAO,KAAK;;;;;;;;;;;;;;CAed,AAAO,WAAW,OAAqB;AACrC,MAAIA,gCAAiB,MAAM,CAAE,MAAK,WAAW;AAE7C,SAAO"}

package/dist/{index-DW1JFluR.d.cts → index-BdtMQyzF.d.cts}

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.11`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
@@ -353,4 +353,4 @@ declare class CommandIdentity {
   setVersion(value: string): this;
 }
 export { CommandIdentity as t };
-//# sourceMappingURL=index-DW1JFluR.d.cts.map
+//# sourceMappingURL=index-BdtMQyzF.d.cts.map

package/dist/{index-qft-a5kh.d.ts → index-CwHGSras.d.ts}

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.11`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
@@ -679,4 +679,4 @@ type GeneratePackageBannerOptions = {
 */
 declare const generatePackageBanner: (options?: GeneratePackageBannerOptions) => Promise<string>;
 export { generatePackageBanner as n, PackageJson as r, GeneratePackageBannerOptions as t };
-//# sourceMappingURL=index-qft-a5kh.d.ts.map
+//# sourceMappingURL=index-CwHGSras.d.ts.map

package/dist/{index-1FKLQ7ah.d.cts → index-DlH2PDPD.d.cts}

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.11`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
@@ -679,4 +679,4 @@ type GeneratePackageBannerOptions = {
 */
 declare const generatePackageBanner: (options?: GeneratePackageBannerOptions) => Promise<string>;
 export { generatePackageBanner as n, PackageJson as r, GeneratePackageBannerOptions as t };
-//# sourceMappingURL=index-1FKLQ7ah.d.cts.map
+//# sourceMappingURL=index-DlH2PDPD.d.cts.map

package/dist/{index-CEsO_rxz.d.ts → index-NLQcJJFO.d.ts}

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.11`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
@@ -353,4 +353,4 @@ declare class CommandIdentity {
   setVersion(value: string): this;
 }
 export { CommandIdentity as t };
-//# sourceMappingURL=index-CEsO_rxz.d.ts.map
+//# sourceMappingURL=index-NLQcJJFO.d.ts.map

package/dist/index.cjs

@@ -2,7 +2,7 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.10`
+*  Version: `0.0.11`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
@@ -10,11 +10,11 @@
 
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_helper = require('./helper-DvCvgDxy.cjs');
-const require_server = require('./server-DZvrqlyy.cjs');
-const require_identity = require('./identity-D192lL-_.cjs');
-const require_client = require('./client-DnTjQyyo.cjs');
-const require_package_banner = require('./package-banner-BHyF8RdG.cjs');
+const require_helper = require('./helper-DNj9Sj4w.cjs');
+const require_server = require('./server-CvLC0e2m.cjs');
+const require_identity = require('./identity-Crq3bzhv.cjs');
+const require_client = require('./client-CuivP4z0.cjs');
+const require_package_banner = require('./package-banner-BoS7Lbi9.cjs');
 require("@rzl-zone/node-only");
 let _babel_types = require("@babel/types");
 _babel_types = require_helper.__toESM(_babel_types, 1);
@@ -23,6 +23,7 @@ let _babel_traverse = require("@babel/traverse");
 _babel_traverse = require_helper.__toESM(_babel_traverse, 1);
 let node_path = require("node:path");
 node_path = require_helper.__toESM(node_path, 1);
+let shell_quote = require("shell-quote");
 let node_child_process = require("node:child_process");
 let acorn = require("acorn");
 acorn = require_helper.__toESM(acorn, 1);
@@ -1161,31 +1162,44 @@ const normalizeJsBuildNewlines = async (pattern, options = {}) => {
 	}
 };
 function runCommand(command, argsOrOptions = [], maybeOptions = {}) {
-	assertValidCommand(command);
-	let args;
-	let options;
-	if (Array.isArray(argsOrOptions)) {
-		args = argsOrOptions;
-		options = maybeOptions;
-	} else {
-		args = [];
-		options = argsOrOptions;
-	}
 	return new Promise((resolve, reject) => {
-		const { shell = true, stdio = "inherit", argv0: _argv0, useColors = true, ...restOption } = options;
-		const { child, setupLifecycle, cmdStringPlain } = spawnWithLifecycle(command, args, {
-			...restOption,
-			stdio,
-			useColors,
-			shell
-		}, { rejectOnNonZero: true });
-		setupLifecycle({
-			onSuccess: (code) => {
-				if (code === 0) resolve(child);
-				else reject(/* @__PURE__ */ new Error(`${cmdStringPlain} exited with code ${code}`));
-			},
-			onError: reject
-		});
+		try {
+			let args;
+			let options;
+			const isArgsArray = require_helper.isArray(argsOrOptions);
+			if (isArgsArray) {
+				args = argsOrOptions;
+				options = maybeOptions;
+			} else {
+				args = [];
+				options = argsOrOptions;
+			}
+			assertValidCommand(command, {
+				apiType: "runCommand",
+				useColors: options.useColors,
+				allowInline: !isArgsArray
+			});
+			const { shell = true, stdio = "inherit", argv0: _argv0, useColors = true, ...restOption } = options;
+			const { child, setupLifecycle, cmdStringPlain } = spawnWithLifecycle(command, args, {
+				...restOption,
+				stdio,
+				useColors,
+				shell
+			}, { rejectOnNonZero: true });
+			setupLifecycle({
+				onSuccess: (code) => {
+					if (code === 0) resolve(child);
+					else reject(/* @__PURE__ */ new Error(`${cmdStringPlain} exited with code ${code}`));
+				},
+				onError: reject
+			});
+		} catch (err) {
+			const e = err instanceof Error ? err : new Error(String(err));
+			const cleanedBase = stripInternalStack(((/* @__PURE__ */ new Error()).stack?.split(require_client.EOL).slice(1) ?? []).filter((line) => !line.includes("runCommand")));
+			e.stack = [e.message, ...cleanedBase].join(require_client.EOL);
+			reject(e);
+			return;
+		}
 	});
 }
 function normalizeChunk(chunk) {
@@ -1194,74 +1208,89 @@ function normalizeChunk(chunk) {
 	return String(chunk);
 }
 function runCommandCapture(command, argsOrOptions = [], maybeOptions = {}) {
-	assertValidCommand(command);
-	let args;
-	let options;
-	if (Array.isArray(argsOrOptions)) {
-		args = argsOrOptions;
-		options = maybeOptions;
-	} else {
-		args = [];
-		options = argsOrOptions;
-	}
-	const { shell = true, signal, timeout, forceKill, useColors = true, argv0: _argv0, ...restOption } = options;
 	return new Promise((resolve, reject) => {
-		const { child, setupLifecycle } = spawnWithLifecycle(command, args, {
-			...restOption,
-			stdio: "pipe",
-			shell,
-			signal,
-			timeout,
-			forceKill,
-			useColors
-		}, { rejectOnNonZero: false });
-		let stdout = "";
-		let stderr = "";
-		child.stdout?.on("data", (chunk) => {
-			stdout += normalizeChunk(chunk);
-		});
-		child.stderr?.on("data", (chunk) => {
-			stderr += normalizeChunk(chunk);
-		});
-		setupLifecycle({
-			onSuccess: (code) => {
-				resolve({
-					stdout: stdout.trimEnd(),
-					stderr: stderr.trimEnd(),
-					exitCode: code,
-					ok: code === 0
-				});
-			},
-			onError: reject
-		});
+		try {
+			let args;
+			let options;
+			const isArgsArray = require_helper.isArray(argsOrOptions);
+			if (isArgsArray) {
+				args = argsOrOptions;
+				options = maybeOptions;
+			} else {
+				args = [];
+				options = argsOrOptions;
+			}
+			assertValidCommand(command, {
+				apiType: "runCommandCapture",
+				useColors: options.useColors,
+				allowInline: !isArgsArray
+			});
+			const { shell = true, signal, timeout, forceKill, useColors = true, argv0: _argv0, ...restOption } = options;
+			const { child, setupLifecycle } = spawnWithLifecycle(command, args, {
+				...restOption,
+				stdio: "pipe",
+				shell,
+				signal,
+				timeout,
+				forceKill,
+				useColors
+			}, { rejectOnNonZero: false });
+			let stdout = "";
+			let stderr = "";
+			child.stdout?.on("data", (chunk) => {
+				stdout += normalizeChunk(chunk);
+			});
+			child.stderr?.on("data", (chunk) => {
+				stderr += normalizeChunk(chunk);
+			});
+			setupLifecycle({
+				onSuccess: (code) => {
+					resolve({
+						stdout: stdout.trimEnd(),
+						stderr: formatMessageColor(stderr.trimEnd(), useColors),
+						exitCode: code,
+						ok: code === 0
+					});
+				},
+				onError: reject
+			});
+		} catch (err) {
+			const e = err instanceof Error ? err : new Error(String(err));
+			const cleanedBase = stripInternalStack(((/* @__PURE__ */ new Error()).stack?.split(require_client.EOL).slice(1) ?? []).filter((line) => !line.includes("runCommandCapture")));
+			e.stack = [e.message, ...cleanedBase].join(require_client.EOL);
+			reject(e);
+			return;
+		}
 	});
 }
+const formatMessageColor = (message, useColors = true) => {
+	return useColors ? require_client.picocolors.redBright(message) : message;
+};
 function formatCommand(command, args, { useColors = true } = {}) {
 	const hasArgs = args.length > 0;
 	const argsString = hasArgs ? args.map((a) => require_helper.safeStableStringify(a)).join(" ") : "";
-	if (useColors) {
-		const cmd = require_client.picocolors.cyanBright(command);
-		return hasArgs ? `${cmd} ${require_client.picocolors.gray(argsString)}` : cmd;
-	}
-	return hasArgs ? `${command} ${argsString}` : command;
+	if (!hasArgs) return formatMessageColor(command, useColors);
+	if (useColors) return `${require_client.picocolors.cyanBright(command)} ${require_client.picocolors.gray(argsString)}`;
+	return `${command} ${argsString}`;
 }
-function assertValidCommand(command, { useColors = true } = {}) {
-	if (typeof command !== "string") {
+function assertValidCommand(command, options) {
+	const { useColors = true, allowInline = false, apiType } = options || {};
+	if (!require_helper.isString(command)) {
 		const errorMsg = `Invalid command: expected a string, received ${require_helper.safeStableStringify(command)}`;
-		throw new TypeError(useColors ? require_client.picocolors.redBright(errorMsg) : errorMsg);
+		throw new TypeError(formatMessageColor(errorMsg, useColors));
 	}
 	const trimmed = command.trim();
-	if (trimmed.length === 0) {
-		const errorMsg = "Invalid command: command cannot be empty";
-		throw new Error(useColors ? require_client.picocolors.redBright(errorMsg) : errorMsg);
+	if (trimmed.length === 0) throw new Error(formatMessageColor("Invalid command: command cannot be empty", useColors));
+	const hasSpace = /\s/.test(trimmed);
+	if (hasShellSyntax(trimmed)) {
+		const errorMsg = require_client.joinLinesLoose(`Invalid command: "${trimmed}"`, "Shell operators are not supported in this context (e.g. &&, ||, |, >).", "This utility only supports a single command with arguments.");
+		throw new Error(formatMessageColor(errorMsg, useColors));
 	}
-	const hasSpace = trimmed.includes(" ");
-	const hasQuotes = /['"`]/.test(trimmed);
-	const hasShellOps = /[|&;<>(){}$]/.test(trimmed);
-	if (hasSpace || hasQuotes || hasShellOps) {
+	if (!allowInline && hasSpace) {
 		const [cmd, ...rest] = trimmed.split(/\s+/);
-		const errorMsg = require_client.joinLinesLoose(`Invalid command: "${trimmed}"`, "Do not pass a full shell command.", `Use arguments instead: runCommand("${cmd}", ${require_helper.safeStableStringify(rest)})`);
-		throw new Error(useColors ? require_client.picocolors.redBright(errorMsg) : errorMsg);
+		if (!cmd) throw new Error("Invalid command: unable to resolve executable.");
+		const errorMsg = require_client.joinLinesLoose(`Invalid command: "${trimmed}"`, "Do not include arguments in the command when passing them separately.", `Use: ${apiType}("${cmd}", ${require_helper.safeStableStringify(rest)})`);
+		throw new Error(formatMessageColor(errorMsg, useColors));
 	}
 }
 function stripInternalStack(lines) {
@@ -1273,8 +1302,10 @@ function stripInternalStack(lines) {
 		"createProcessError",
 		"formatError",
 		"spawnWithLifecycle",
+		"assertValidCommand",
 		"setupLifecycle",
-		"node:internal"
+		"node:internal",
+		"node:internal/process/promises"
 	];
 	return lines.filter((line) => {
 		if (blacklist.some((key) => line.includes(key))) return false;
@@ -1341,29 +1372,70 @@ var CommandProcessError = class extends Error {
 function isCommandProcessError(err) {
 	return err instanceof CommandProcessError;
 }
+function hasShellSyntax(str) {
+	return /(\|\||&&|[|&;<>\n])/.test(str);
+}
+function resolveCommand(input, useColors = true) {
+	const tokens = (0, shell_quote.parse)(input);
+	const normalized = [];
+	for (const t of tokens) {
+		if (typeof t === "string") {
+			normalized.push(t);
+			continue;
+		}
+		if ("comment" in t) continue;
+		if ("pattern" in t) {
+			normalized.push(t.pattern);
+			continue;
+		}
+		if ("op" in t) throw new Error(formatMessageColor("Unsupported shell operator detected.", useColors));
+		throw new Error(formatMessageColor("Unknown token in command.", useColors));
+	}
+	if (normalized.length === 0) throw new Error(formatMessageColor("Invalid command: empty after parsing.", useColors));
+	const [cmd, ...args] = normalized;
+	if (!cmd) throw new Error(formatMessageColor("Invalid command: empty after parsing.", useColors));
+	return {
+		command: cmd,
+		args
+	};
+}
 function spawnWithLifecycle(command, args, options, config) {
-	const { useColors = true, timeout, forceKill, signal: abortSignal, ...restOption } = options;
+	const { useColors = true, timeout, forceKill, signal: abortSignal, shell = false, ...restOption } = options;
+	let cmd = command;
+	let finalArgs = [...args];
+	const isInline = finalArgs.length === 0 && /\s/.test(cmd);
 	const baseStack = (/* @__PURE__ */ new Error()).stack;
-	const cmdString = formatCommand(command, args, { useColors });
-	const cmdStringPlain = formatCommand(command, args, { useColors: false });
 	const formatError = config?.formatError ?? ((msg, meta) => {
 		const metaCommand = meta.command.trim();
-		const argsString = meta.args.length > 0 ? meta.args.map((a) => require_helper.safeStableStringify(a).trim()).join(" ") : "";
+		const hasArgs = meta.args.length > 0;
+		const argsString = hasArgs ? meta.args.map((a) => require_helper.safeStableStringify(a).trim()).join(" ") : "";
+		const commandString = hasArgs ? `${metaCommand} ${argsString}` : metaCommand;
 		if (meta.useColors) {
 			const cmd = require_client.picocolors.magentaBright(metaCommand);
-			const args = argsString ? require_client.picocolors.yellowBright(argsString) : "";
+			const args = hasArgs ? require_client.picocolors.yellowBright(argsString) : "";
 			return createProcessError(`${cmd}${args ? " " + args : ""} ${require_client.picocolors.redBright(msg)}`, {
 				...meta,
-				command: `${metaCommand} ${argsString}`
+				command: commandString
 			}, baseStack);
 		}
-		return createProcessError(`${metaCommand}${require_helper.isNonEmptyString(argsString) ? " " + argsString : ""} ${msg}`, {
+		return createProcessError(`${commandString} ${msg}`, {
 			...meta,
-			command: `${metaCommand} ${argsString}`
+			command: commandString
 		}, baseStack);
 	});
 	const rejectOnNonZero = config?.rejectOnNonZero ?? false;
-	const child = (0, node_child_process.spawn)(command, [...args], restOption);
+	if (isInline) {
+		const resolved = resolveCommand(cmd, useColors);
+		cmd = resolved.command;
+		finalArgs = resolved.args;
+	}
+	for (const arg of finalArgs) if (hasShellSyntax(arg)) throw new Error(formatMessageColor(`Invalid argument: "${arg}" contains unsupported shell syntax`, useColors));
+	const cmdString = formatCommand(cmd, finalArgs, { useColors });
+	const cmdStringPlain = formatCommand(cmd, finalArgs, { useColors: false });
+	const child = (0, node_child_process.spawn)(cmd, finalArgs, {
+		shell,
+		...restOption
+	});
 	let finished = false;
 	const kill = () => {
 		try {
@@ -1388,8 +1460,8 @@ function spawnWithLifecycle(command, args, options, config) {
 				kill();
 				fail(formatError(`timed out after ${timeout}ms`, {
 					reason: "timeout",
-					command,
-					args,
+					command: cmd,
+					args: finalArgs,
 					useColors
 				}));
 			}, timeout) : null;
@@ -1413,8 +1485,8 @@ function spawnWithLifecycle(command, args, options, config) {
 				kill();
 				fail(formatError("aborted by signal", {
 					reason: "abort",
-					command,
-					args,
+					command: cmd,
+					args: finalArgs,
 					useColors
 				}));
 			};
@@ -1432,8 +1504,8 @@ function spawnWithLifecycle(command, args, options, config) {
 						reason: "signal",
 						signal,
 						exitCode: code ?? void 0,
-						command,
-						args,
+						command: cmd,
+						args: finalArgs,
 						useColors
 					}));
 					return;
@@ -1443,8 +1515,8 @@ function spawnWithLifecycle(command, args, options, config) {
 					fail(formatError(`exited with code ${exitCode}`, {
 						reason: "non-zero exit code",
 						exitCode,
-						command,
-						args,
+						command: cmd,
+						args: finalArgs,
 						useColors
 					}));
 					return;