@rzl-zone/build-tools 0.0.5

package/dist/index.d.ts

@@ -0,0 +1,2193 @@
+/*!
+* ========================================================================
+*  @rzl-zone/build-tools
+* ------------------------------------------------------------------------
+*  Version: `0.0.5`
+*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
+* ========================================================================
+*/
+
+import { a as OmitStrict, c as PrettifyOptions, r as DefaultPrettifyOptions, s as Prettify } from "./extra-CVuXMpEw.js";
+import { n as generatePackageBanner, r as PackageJson, t as GeneratePackageBannerOptions } from "./index-PXsb85LI.js";
+import { t as CommandIdentity } from "./index-CzxZta4Z.js";
+import { n as PatternOptions, t as PatternConfig } from "./fast-globe-options-6r2aj6UC.js";
+import * as acorn from "acorn";
+import { ChildProcess, SpawnOptions, StdioOptions, spawn } from "node:child_process";
+
+/** ----------------------------------------------------------------
+* * ***Flexible input type for value collections.***
+* ----------------------------------------------------------------
+*
+* Represents a value that can be provided either as a single item
+* or as a collection of items.
+*
+* This enables APIs to accept both singular and multiple values
+* without requiring callers to normalize the input beforehand.
+*
+* ----------------------------------------------------------------
+* Supported Forms
+*
+* - A single value (`T`)
+* - An array of values (`T[]`)
+* - A `Set` containing values (`Set<T>`)
+*
+* ----------------------------------------------------------------
+* Type Behavior
+*
+* - Wrapped with `Exclude<..., never>` to prevent accidental
+*   `never` propagation in complex generic transformations.
+*
+* - Uses `Prettify` to normalize and simplify the resulting type
+*   for improved readability.
+*
+* ----------------------------------------------------------------
+* @template T The base value type.
+*
+* @template Options
+*   Configuration options for the `Prettify` utility.
+*   Controls how the resulting type is normalized and displayed
+*   in editor tooltips.
+*
+* ----------------------------------------------------------------
+*
+* @example
+* ```ts
+* // default behavior
+* const a: Collection<string> = "value";
+* const b: Collection<string> = ["a", "b", "c"];
+* const c: Collection<string> = new Set(["x", "y", "z"]);
+*
+* // with custom Prettify options
+* type Custom = Collection<string, { skipPrettify: true }>;
+* ```
+*/
+type Collection<T, Options extends PrettifyOptions = DefaultPrettifyOptions> = Prettify<Exclude<T | Prettify<T, Options>[] | Set<Prettify<T, Options>>, never>, Options>;
+/** ----------------------------------------------------------------
+* * ***Flexible input type for string collections.***
+* ----------------------------------------------------------------
+*
+* Convenience alias for `Collection<string>`.
+*
+* Useful for APIs that accept either a single string or multiple
+* strings in array or `Set` form.
+*
+* ----------------------------------------------------------------
+*
+* @example
+* ```ts
+* const a: StringCollection = "value";
+* const b: StringCollection = ["a", "b", "c"];
+* const c: StringCollection = new Set(["x", "y", "z"]);
+* ```
+*/
+type StringCollection = Collection<string>;
+/** ----------------------------------------------------------------
+* * ***Special Internal options props.***
+* ----------------------------------------------------------------
+*/
+interface InternalOptions {}
+/** ----------------------------------------------------------------
+* * ***Supported log verbosity levels.***
+* ----------------------------------------------------------------
+*/
+type LogLevel = "silent" | "error" | "info" | "debug";
+/** ----------------------------------------------------------------
+* * ***Common logging configuration options.***
+* ----------------------------------------------------------------
+*/
+type LoggingOptions = {
+  /** ----------------------------------------------------------------
+  * * ***Logging verbosity level.***
+  * ----------------------------------------------------------------
+  *
+  * Controls how verbose the logger output should be.
+  *
+  * - **Supported values:**
+  *      - `silent` ➔ no output.
+  *      - `error`  ➔ errors only.
+  *      - `info` **(default)** ➔ standard informational logs (include `error`).
+  *      - `debug`  ➔ verbose / debug logs (include `error`).
+  *
+  * - **Notes:**
+  *      - If an invalid value is provided, it will be **silently coerced**
+  *        to the default log level.
+  *
+  * @default "info"
+  */
+  logLevel?: LogLevel;
+};
+/** ----------------------------------------------------------------
+* * ***Base configuration options.***
+* ----------------------------------------------------------------
+*
+* Shared option structure used across internal utilities.
+*
+* This type composes several configuration layers commonly required
+* by file-processing utilities:
+*
+* - ***Logging options*** from {@link LoggingOptions | `LoggingOptions`}.
+* - ***Pattern matching configuration*** from {@link PatternConfig | `PatternConfig`}.
+*
+* ----------------------------------------------------------------
+*
+* @template FilesOnly
+* When `true`, directory-related pattern options (`onlyFiles`,
+* `onlyDirectories`) are removed from the public configuration.
+*
+* This is typically used by utilities that must operate strictly
+* on files and should not allow directory matches.
+*
+* @template ForceUnique
+* When `true`, the `unique` option from the underlying
+* {@link PatternOptions | `PatternOptions`} is removed to enforce
+* internally deduplicated glob results.
+*
+* ----------------------------------------------------------------
+*
+* These generics allow higher-level utilities to enforce
+* stricter pattern resolution behavior while still exposing
+* a flexible configuration surface to consumers.
+*/
+type BaseOptions<FilesOnly extends boolean = false, ForceUnique extends boolean = false> = Prettify<LoggingOptions & InternalOptions & PatternConfig<FilesOnly, ForceUnique>>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **clean build artifact** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link cleanJsBuildArtifacts | `clean-js-build-artifacts`}.
+* - {@link cleanTypesBuildArtifacts | `clean-types-build-artifacts`}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_CLEAN_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **clean build artifact** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link cleanJsBuildArtifacts | `clean-js-build-artifacts`}.
+* - {@link cleanTypesBuildArtifacts | `clean-types-build-artifacts`}.
+*/
+declare const resolvedCleanPatternOption: PatternOptions<true, true>;
+/** Type Options for {@link cleanJsBuildArtifacts | `clean-js-build-artifacts`} and {@link cleanTypesBuildArtifacts | `clean-types-build-artifacts`}. */
+type CleanCoreOptions = Prettify<{
+  /** ----------------------------------------------------------------
+  * * ***Whether to remove `sourceMappingURL` comments.***
+  * ----------------------------------------------------------------
+  *
+  * @default false
+  */
+  removeSourceMap?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***Whether to remove `region` comments.***
+  * ----------------------------------------------------------------
+  *
+  * @default true
+  */
+  removeRegion?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***Whether to remove empty lines adjacent to removed comments.***
+  * ----------------------------------------------------------------
+  * Useful for keeping output files compact and visually clean.
+  *
+  * @default false
+  */
+  removeAdjacentEmptyLines?: boolean;
+} & BaseOptions<typeof DEFAULT_CLEAN_PATTERN_POLICY.filesOnly, typeof DEFAULT_CLEAN_PATTERN_POLICY.forceUnique>>;
+/** Command identity associated with {@link cleanJsBuildArtifacts | **`clean-js-build-artifacts`**}. */
+declare const commandCjbaIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link cleanJsBuildArtifacts | `clean-js-build-artifacts`}.***
+* ----------------------------------------------------------------
+*/
+type CleanJsArtifactsOptions = CleanCoreOptions;
+/** ----------------------------------------------------------------
+* * ***Removes build artifact comments from compiled JavaScript files.***
+* ----------------------------------------------------------------
+*
+* This function scans files matching the provided glob pattern(s) and removes:
+* - Source path comments.
+* - Source region comments.
+* - ESLint directive comments.
+* - Optional source map references.
+*
+* It can also remove empty lines adjacent to those comments to keep
+* output files tidy.
+*
+* @param {string | string[] | Set<string>} pattern - Glob pattern or list of patterns pointing to JS output files.
+* @param {CleanJsArtifactsOptions} options - Cleanup configuration options, see {@link CleanJsArtifactsOptions | **`CleanJsArtifactsOptions`**}.
+*
+* @example
+* ```ts
+* await cleanJsBuildArtifacts("dist/**\/*.js");
+* await cleanJsBuildArtifacts("dist/**\/*.{js,cjs,mjs}");
+* ```
+*
+* @example
+* ```ts
+* await cleanJsBuildArtifacts(["dist/**\/*.js", "build/*\/*.mjs"], {
+*   removeSourceMap: false,
+*   removeRegionComment: false,
+*   removeAdjacentEmptyLines: true
+* });
+* ```
+*/
+declare const cleanJsBuildArtifacts: (pattern: StringCollection, options?: CleanJsArtifactsOptions) => Promise<void>;
+/** Command identity associated with {@link cleanTypesBuildArtifacts | **`clean-types-build-artifacts`**}. */
+declare const commandCtbaIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link cleanTypesBuildArtifacts | **`cleanTypesBuildArtifacts`**}.***
+* ----------------------------------------------------------------
+*/
+type CleanTypesArtifactsOptions = CleanCoreOptions;
+/** ----------------------------------------------------------------
+* * ***Removes build artifact comments from compiled Types files.***
+* ----------------------------------------------------------------
+*
+* This function scans files matching the provided glob pattern(s) and removes:
+* - Source path comments.
+* - ESLint directive comments.
+* - Optional source map references.
+*
+* It can also remove empty lines adjacent to those comments to keep
+* output files tidy.
+*
+* @param pattern - Glob pattern or list of patterns pointing to Types output files.
+* @param options - Cleanup configuration options, see {@link CleanTypesArtifactsOptions | **`CleanTypesArtifactsOptions`**}.
+*
+* @example
+* ```ts
+* await cleanTypesBuildArtifacts("dist/**\/*.d.ts");
+* await cleanTypesBuildArtifacts("dist/**\/*.d.{ts,cts,mts}");
+* ```
+*
+* @example
+* ```ts
+* await cleanTypesBuildArtifacts(["dist/**\/*.d.ts", "build/*\/*.mts"], {
+*   removeSourceMap: false,
+*   removeAdjacentEmptyLines: true
+* });
+* ```
+*/
+declare const cleanTypesBuildArtifacts: (pattern: StringCollection, options?: CleanTypesArtifactsOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Creates a `Set` of parameters for {@link copyFileToDest | **`copy-file-to-dest`**}.***
+* ----------------------------------------------------------------
+*
+* Utility helper to construct a `Set` of {@link CopyFileToDestParam | `CopyFileToDestParam`}
+* with proper type inference and editor autocomplete support.
+*
+* This is primarily useful when passing parameters as a `Set`,
+* since directly using `new Set([...])` may result in poor
+* TypeScript inference and missing autocomplete for object literals.
+*
+* ----------------------------------------------------------------
+* Behavior
+*
+* - Accepts a single parameter or an array of parameters.
+* - Automatically normalizes the input into a `Set`.
+*
+* ----------------------------------------------------------------
+*
+* @param items
+* A single {@link CopyFileToDestParam | `CopyFileToDestParam`} or an array of parameters.
+*
+* @returns
+* A `Set` containing the provided parameters.
+*
+* @example
+* ```ts
+* // single item
+* const setA = createCopyFileToDestParameterSet({
+*   source: "dist/index.d.ts",
+*   target: "dist"
+* });
+*
+* // multiple items
+* const setB = createCopyFileToDestParameterSet([
+*   {
+*     source: "dist/a.d.ts",
+*     target: "dist"
+*   },
+*   {
+*     source: "dist/b.d.ts",
+*     target: "dist"
+*   }
+* ]);
+*
+* // usage with copyFileToDest
+* await copyFileToDest(setB);
+* ```
+*/
+declare function createCopyFileToDestParameterSet(items: CopyFileToDestParam | CopyFileToDestParam[]): Set<CopyFileToDestParam>;
+/** Command identity associated with {@link copyFileToDest | **`copy-file-to-dest`**}. */
+declare const commandCftdIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link copyFileToDest | **`copy-file-to-dest`**}.***
+* ----------------------------------------------------------------
+*/
+type CopyFileToDestOptions = OmitStrict<BaseOptions, "patternOptions">;
+/** ----------------------------------------------------------------
+* * ***Describes the parameter options for copying a single file to a destination path of {@link copyFileToDest | **`copy-file-to-dest`**}.***
+* ----------------------------------------------------------------
+*/
+type CopyFileToDestParam = {
+  /** ----------------------------------------------------------------
+  * * ***Path to the source file to be copied.***
+  * ----------------------------------------------------------------
+  * Can be either an absolute path or a path relative to the project root.
+  *
+  * @example "src/assets/logo.png"
+  */
+  source: string;
+  /** ----------------------------------------------------------------
+  * * ***Target directory where the file will be copied.***
+  * ----------------------------------------------------------------
+  *
+  * - When `absoluteTarget` is `false` **(default)**, this path is resolved relative to `outputRoot`.
+  * - When `absoluteTarget` is `true`, this path is treated as an absolute path relative to the project root.
+  *
+  * @example "assets/images"
+  */
+  target: string;
+  /** ----------------------------------------------------------------
+  * * ***Optional custom file name for the copied file.***
+  * ----------------------------------------------------------------
+  *
+  * If omitted, the original file name from `source` will be preserved.
+  *
+  * @example "logo-new.png"
+  *
+  * @default undefined
+  */
+  fileName?: string;
+  /** ----------------------------------------------------------------
+  * * ***Output root directory used when resolving the `target` path.***
+  * ----------------------------------------------------------------
+  *
+  * When `absoluteTarget` is `false`, the final copy destination will be
+  * `<project-root>/<outputRoot>/<target>`.
+  *
+  * @default "dist"
+  * @example "build"
+  */
+  outputRoot?: string;
+  /** ----------------------------------------------------------------
+  * * ***When `true`, disables `outputRoot` prefixing and treats `target`
+  * as an absolute path relative to the project root.***
+  * ----------------------------------------------------------------
+  *
+  * Use this when you want to copy directly to an absolute path inside the project,
+  * bypassing the `outputRoot` prefix.
+  *
+  * @default false
+  */
+  absoluteTarget?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***When `true`, suppresses errors when the source file does not exist.***
+  * ----------------------------------------------------------------
+  *
+  * - Instead of throwing or logging an error, the operation will be skipped.
+  * - Useful in development or watch mode where build outputs may not be immediately available.
+  *
+  * @default false
+  */
+  ignoreMissingSourceError?: boolean;
+};
+/** ----------------------------------------------------------------
+* * ***Copy one or more files of any type into destination directories.***
+* ----------------------------------------------------------------
+*
+* This utility is **file-type agnostic** and can be used to copy any kind of asset,
+* including CSS, JavaScript, JSON, images, fonts, or other static files.
+*
+* - *The function supports:*
+*      - Copying a **single file** using a single configuration object.
+*      - Copying **multiple files** using an ***array*** or a ***Set*** of configuration objects.
+*
+* - When using a `Set`, it is recommended to use
+*   {@link createCopyFileToDestParameterSet | **`createCopyFileToDestParameterSet`**}
+*   to ensure proper TypeScript inference and autocomplete support.
+*
+* - By default, files are copied into a `dist` directory relative to the project root.
+* - This behavior can be customized per item via `outputRoot` or bypassed entirely
+*   using `absoluteTarget`.
+*
+* ----------------------------------------------------------------
+*
+* @param parameter
+* A single {@link CopyFileToDestParam | **`CopyFileToDestParam`**} object,
+* an array, or a `Set` of {@link CopyFileToDestParam | **`CopyFileToDestParam`**}.
+*
+* - *When a collection is provided:*
+*     - Each item is validated independently.
+*     - Files are copied sequentially.
+*     - Logging reflects the cumulative copy progress.
+*
+* ----------------------------------------------------------------
+*
+* @example
+* // Copy a single CSS file into "dist/".
+* // Result: "dist/main.css".
+* await copyFileToDest({
+*   source: "src/styles/main.css",
+*   target: "."
+* });
+*
+* @example
+* // Copy a single CSS file into "dist/styles/".
+* await copyFileToDest({
+*   source: "src/styles/main.css",
+*   target: "styles"
+* });
+*
+* @example
+* // Copy multiple files into "dist/config/" (using array).
+* // Result: "dist/config/a.json" and "dist/config/b.json".
+* await copyFileToDest([
+*   {
+*     source: "src/config/a.json",
+*     target: "config"
+*   },
+*   {
+*     source: "src/config/b.json",
+*     target: "config"
+*   }
+* ]);
+*
+* @example
+* // Copy multiple files into "dist/config/" (using Set).
+* // ⚠️ Requires explicit typing for proper inference.
+* await copyFileToDest(new Set<CopyFileToDestParam>([
+*   {
+*     source: "src/config/a.json",
+*     target: "config"
+*   },
+*   {
+*     source: "src/config/b.json",
+*     target: "config"
+*   }
+* ]));
+*
+* @example
+* // Recommended: using helper for Set (better DX).
+* await copyFileToDest(
+*   createCopyFileToDestParameterSet([
+*     {
+*       source: "src/config/a.json",
+*       target: "config"
+*     },
+*     {
+*       source: "src/config/b.json",
+*       target: "config"
+*     }
+*   ])
+* );
+*
+* @example
+* // Copy multiple files with a custom output root.
+* // Result: "build/scripts/setup.js" and "build/scripts/runtime.js".
+* await copyFileToDest([
+*   {
+*     source: "src/scripts/setup.js",
+*     target: "scripts",
+*     outputRoot: "build"
+*   },
+*   {
+*     source: "src/scripts/runtime.js",
+*     target: "scripts",
+*     outputRoot: "build"
+*   }
+* ]);
+*
+* @example
+* // Copy and rename a single file.
+* // Result: "dist/config/app.json".
+* await copyFileToDest({
+*   source: "src/config/app.config.json",
+*   target: "config",
+*   fileName: "app.json"
+* });
+*
+* @example
+* ```ts
+* // Copy using an absolute target path (no outputRoot prefix).
+* // Result: "<project-root>/config/runtime/config.json".
+* await copyFileToDest({
+*   source: "src/runtime/config.json",
+*   target: "config/runtime",
+*   absoluteTarget: true
+* });
+* ```
+*
+* ----------------------------------------------------------------
+*
+* @remarks
+* - The function ensures that all target directories exist before copying.
+* - Each item is validated to be a plain object with valid fields.
+* - The original file contents are copied without transformation.
+* - Errors during copying are caught and reported via the logger.
+*/
+declare function copyFileToDest(parameter: CopyFileToDestParam, options?: CopyFileToDestOptions): Promise<void>;
+declare function copyFileToDest(parameter: CopyFileToDestParam[], options?: CopyFileToDestOptions): Promise<void>;
+declare function copyFileToDest(parameter: Set<CopyFileToDestParam>, options?: CopyFileToDestOptions): Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **ensure css import** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link ensureCssImport | **`ensure-css-import`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_ECI_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **ensure css import** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link ensureCssImport | **`ensure-css-import`**}.
+*/
+declare const resolvedEciPatternOption: PatternOptions<true, true>;
+/** Command identity associated with {@link ensureCssImport | **`ensure-css-import`**}. */
+declare const commandEciIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link ensureCssImport | **`ensure-css-import`**}.***
+* ----------------------------------------------------------------
+*/
+type EnsureCssImportOptions = {
+  /** ----------------------------------------------------------------
+  * * ***CSS import path(s) to ensure exist in JS output.***
+  * ----------------------------------------------------------------
+  *
+  * Accepts a single path or multiple paths.
+  *
+  * @example
+  * ```ts
+  * "./search.css"
+  * ```
+  *
+  * @example
+  * ```ts
+  * ["./search.css", "./theme.css"]
+  * ```
+  */
+  cssImportPath: string | readonly (string | readonly string[])[] | Set<string>;
+  /** ----------------------------------------------------------------
+  * * ***Remove duplicate CSS imports (recommended).***
+  * ----------------------------------------------------------------
+  *
+  * @default true
+  */
+  dedupe?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***Sort CSS imports alphabetically before inserting.***
+  * ----------------------------------------------------------------
+  *
+  * @default false
+  */
+  sort?: boolean;
+  /** --------------------------------------------------------
+  * * ***Minify JS output (except directive prologue).***
+  * --------------------------------------------------------
+  *
+  * - Keeps `"use client"` / `"use strict"` on separate lines.
+  * - Everything else is collapsed into a single line.
+  *
+  * @default false
+  */
+  minify?: boolean;
+} & BaseOptions<typeof DEFAULT_ECI_PATTERN_POLICY.filesOnly, typeof DEFAULT_ECI_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Ensures CSS import(s) exist in compiled JavaScript files.***
+* ----------------------------------------------------------------
+* - *Behavior:*
+*     - Supports **multiple CSS imports**.
+*     - Fully **idempotent**.
+*     - Optional **dedupe & sorting**.
+*
+* @param {string | string[] | Set<string>} pattern
+* Glob pattern(s) pointing to compiled JS files.
+*
+* @param {EnsureCssImportOptions} options
+* Configuration options.
+*
+* @example
+* ```ts
+* await ensureCssImport("dist/**\/*.js", {
+*   cssImportPath: ["./search.css", "./theme.css"],
+*   dedupe: true,
+*   sort: true,
+*   minify: true
+* });
+* ```
+*/
+declare const ensureCssImport: (pattern: StringCollection, options: EnsureCssImportOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **ensure final newline** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link ensureFinalNewline | **`ensure-final-newline`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_EFN_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **ensure final newline** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link ensureFinalNewline | **`ensure-final-newline`**}.
+*/
+declare const resolvedEfnPatternOption: PatternOptions<true, true>;
+/** Command identity associated with {@link ensureFinalNewline | **`ensure-final-newline`**}. */
+declare const commandEfnIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link ensureFinalNewline | **`ensure-final-newline`**}.***
+* ----------------------------------------------------------------
+*/
+type EnsureFinalNewlineOptions = BaseOptions<typeof DEFAULT_EFN_PATTERN_POLICY.filesOnly, typeof DEFAULT_EFN_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Ensure files end with exactly one final newline.***
+* ----------------------------------------------------------------
+*
+* Scans files matching the provided glob pattern(s) and ensures that
+* **each file ends with exactly one newline character**.
+*
+* - *Behavior:*
+*     - Removes **all trailing newline characters** at the end of the file.
+*     - Appends **exactly one** platform-consistent newline (`EOL`).
+*     - Preserves all internal formatting and whitespace.
+*     - Does **not** modify files that are already compliant.
+*
+* - *Newline handling:*
+*     - Supports both `LF` (`\n`) and `CRLF` (`\r\n`).
+*     - Uses **`EOL`** to ensure consistent output across the project.
+*
+* - *Safety:*
+*     - Skips non-existent paths.
+*     - Skips non-file entries (directories, symlinks, etc.).
+*     - Writes only when the file content actually changes.
+*
+* @param {string | string[] | Set<string>} pattern
+* Glob pattern(s) pointing to files that should be checked and normalized.
+*
+* @param {EnsureFinalNewlineOptions} [options]
+* Internal execution options (CLI vs utility context).
+*
+* @example
+* ```ts
+* await ensureFinalNewline("dist/**\/*.{js,cjs,mjs,d.ts}");
+* ```
+*
+* @example
+* ```ts
+* await ensureFinalNewline(["dist/**\/*.js", "dist/**\/*.d.ts"]);
+* ```
+*
+* @remarks
+* This utility is typically executed **post-build** to ensure output
+* files follow POSIX tooling expectations and common formatting conventions.
+*/
+declare const ensureFinalNewline: (pattern: StringCollection, options?: EnsureFinalNewlineOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **generate reference index** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link generateReferenceIndex | **`generate-reference-index`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_GRI_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **generate reference index** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link generateReferenceIndex | **`generate-reference-index`**}.
+*/
+declare const resolvedGriPatternOption: PatternOptions<true, true>;
+/** Command identity associated with {@link generateReferenceIndex | **`generate-reference-index`**}. */
+declare const commandGriIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link generateReferenceIndex | **`generate-reference-index`**}.***
+* ----------------------------------------------------------------
+*/
+type GenerateReferenceOptions = {
+  /** --------------------------------------------------------------
+  * * ***Output directory.***
+  * --------------------------------------------------------------
+  *
+  * Directory where the generated index file will be written.
+  *
+  * @default "dist/.references"
+  */
+  outDir?: string;
+  /** --------------------------------------------------------------
+  * * ***Output index file name.***
+  * --------------------------------------------------------------
+  *
+  * Name of the generated `.d.ts` index file.
+  *
+  * @default "index.d.ts"
+  */
+  outFileName?: string;
+  /** --------------------------------------------------------------
+  * * ***Enable exported type aggregation.***
+  * --------------------------------------------------------------
+  *
+  * When enabled, generates:
+  *
+  * ```ts
+  * export * from "./module";
+  * ```
+  *
+  * for each unique declaration entry.
+  *
+  * @default false
+  */
+  withExportTypes?: boolean;
+  /** --------------------------------------------------------------
+  * * ***Base directory for resolving reference paths.***
+  * --------------------------------------------------------------
+  *
+  * Used to compute relative paths inside the generated index file.
+  *
+  * @default "dist"
+  */
+  inputDirReference?: string;
+  /** --------------------------------------------------------------
+  * * ***Restrict input to TypeScript declaration files only.***
+  * --------------------------------------------------------------
+  *
+  * When enabled (`true`), this option filters the input files to include **only**
+  * TypeScript declaration files with extensions `.d.ts`, `.d.mts`, and `.d.cts`.
+  *
+  * This filtering is applied **after** matching files by the provided glob patterns,
+  * effectively excluding all other file types, including JavaScript outputs
+  * (`.js`, `.mjs`, `.cjs`) and TypeScript source files (`.ts`, `.mts`, `.cts`).
+  *
+  * - *Examples:*
+  *     - With a pattern like `"dist/**\/*.d.ts"`, enabling this option has no practical effect,
+  *       since the pattern already matches only declaration files.
+  *     - With a broader pattern such as `"dist/**\/*"` or `"dist/**\/*.ts"`,
+  *       enabling this option will exclude non-declaration files (e.g., `.ts` source files),
+  *       resulting in only declaration files being included.
+  *     - If your patterns include JavaScript outputs (`.js`, `.mjs`, `.cjs`),
+  *       enabling this option will exclude those files as well.
+  *
+  * When disabled (`false`), all matched files are included regardless of extension,
+  * so JavaScript outputs and source files matching the patterns will be part of
+  * the reference and export generation.
+  *
+  * Use this option and set to `true`, when you want to guarantee that only TypeScript declaration files
+  * are included in the generated references and exports, preventing accidental
+  * inclusion of source or JavaScript build output files.
+  *
+  * @default true
+  */
+  onlyDeclarations?: boolean;
+  /** --------------------------------------------------------------
+  * * ***Output banner configuration.***
+  * --------------------------------------------------------------
+  *
+  * Controls the banner text prepended to the generated output file.
+  *
+  * - `true` **(default)** ➔ automatically generates banner from `package.json`
+  *    using {@link generatePackageBanner | `generatePackageBanner`}.
+  * - `false` ➔ disables banner injection entirely.
+  * - `string` ➔ uses the provided custom banner text.
+  * - `Promise<string>` ➔ resolved and used as banner text.
+  *
+  * @default true
+  */
+  banner?: BannerInput;
+} & BaseOptions<typeof DEFAULT_GRI_PATTERN_POLICY.filesOnly, typeof DEFAULT_GRI_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Generates a TypeScript reference index file (.d.ts).***
+* ----------------------------------------------------------------
+*
+* This function resolves files from the given glob pattern(s) and generates
+* a single declaration index file containing:
+*
+* - `/// \<reference path="..." />` directives.
+* - optional `export * from "..."` statements.
+*
+* Supported input files include declaration and JavaScript module outputs:
+* - `.d.ts`.
+* - `.js`.
+* - `.cjs`.
+* - `.mjs`.
+*
+* The output is typically used to aggregate multiple declaration or build
+* artifacts into a single entry point.
+*
+* @param pattern - Glob pattern or list of patterns used to match output files, supports `.d.ts`, `.js`, `.cjs`, and `.mjs` extensions.
+*
+* @param options - Reference index generation options, see {@link GenerateReferenceOptions | **`GenerateReferenceOptions`**}.
+*
+* @example
+* Basic usage with declaration files only:
+* ```ts
+* await generateReferenceIndex("dist/**\/*.d.ts");
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../types/user.d.ts" />
+* /// \<reference path="../types/post.d.ts" />
+* ```
+*
+* @example
+* Restrict to declaration files even if pattern matches other files,
+* by default `onlyDeclarations` options is `true`:
+* ```ts
+* await generateReferenceIndex("dist/**\/*", { onlyDeclarations: true });
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../types/user.d.ts" />
+* /// \<reference path="../types/post.d.cts" />
+* ```
+*
+* @example
+* Include all matched files (source `.ts` and JS outputs) without filtering declaration files only:
+* ```ts
+* await generateReferenceIndex("dist/**\/*", { onlyDeclarations: false });
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../models/order.ts" />
+* /// \<reference path="../models/user.js" />
+* /// \<reference path="../models/another.cjs" />
+* ```
+*
+* (Here, both `.ts` source files and declaration files are
+* included if matched, because `onlyDeclarations` is `false`).
+*
+* @example
+* Include JavaScript build outputs with no declaration-only restriction:
+* ```ts
+* await generateReferenceIndex("dist/**\/*.js", { onlyDeclarations: false });
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../runtime/helpers.js" />
+* /// \<reference path="../runtime/constants.js" />
+* ```
+*
+* (JavaScript files are included because `onlyDeclarations` is `false`).
+*
+* @example
+* Restrict to declaration files when pattern includes source `.ts` and JS files:
+* ```ts
+* await generateReferenceIndex("dist/**\/*.ts");
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../models/user.d.ts" />
+* /// \<reference path="../models/order.d.ts" />
+* ```
+*
+* (Here `.ts` source files are ignored; only `.d.ts` declarations are included).
+*
+* ----------------------------------------------------------------
+*
+* ***--- Existing examples below remain unchanged ---***
+*
+* @example
+* Generate references from types JavaScript build outputs:
+* ```ts
+* await generateReferenceIndex("dist/**\/*.d.{js,cjs,mjs}");
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../runtime/helpers.d.js" />
+* /// \<reference path="../runtime/constants.d.mjs" />
+* ```
+*
+* @example
+* Mix declaration and JavaScript module outputs:
+* ```ts
+* await generateReferenceIndex([
+*   "dist/**\/*.d.ts",
+*   "dist/**\/*.d.{js,cjs,mjs}"
+* ]);
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../types/user.d.ts" />
+* /// \<reference path="../types/post.d.mts" />
+* /// \<reference path="../runtime/helpers.d.cjs" />
+* ```
+*
+* @example
+* Generate reference index and export all resolved modules:
+* ```ts
+* await generateReferenceIndex(
+*   "dist/**\/*",
+*   { withExportTypes: true }
+* );
+* ```
+*
+* Result (`dist/.references/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../types/user.d.ts" />
+* /// \<reference path="../types/user.d.cts" />
+* /// \<reference path="../types/post.d.ts" />
+* /// \<reference path="../types/post.d.cts" />
+*
+* // Exported Types:
+* export * from "../types/user";
+* export * from "../types/post";
+* ```
+*
+* @example
+* Use multiple input directories with a shared reference base:
+* ```ts
+* await generateReferenceIndex(
+*   [
+*     "dist/types/**\/*.d.ts",
+*     "dist/generated/**\/*.d.{js,cjs,mjs}"
+*   ],
+*   {
+*     inputDirReference: "dist",
+*     withExportTypes: true
+*   }
+* );
+* ```
+*
+* Result (`dist/index.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../types/user.d.ts" />
+* /// \<reference path="../data/config.d.cjs" />
+* /// \<reference path="../generated/schema.d.js" />
+*
+* // Exported Types:
+* export * from "../types/user";
+* export * from "../generated/schema";
+* ```
+*
+* @example
+* Customize output location and file name:
+* ```ts
+* await generateReferenceIndex(
+*   "build/**\/*",
+*   {
+*     outDir: "build/types",
+*     outFileName: "references-types.d.ts"
+*   }
+* );
+* ```
+*
+* Result (`build/types/references-types.d.ts`):
+* ```ts
+* // References Paths:
+* /// \<reference path="../models/user.d.ts" />
+* /// \<reference path="../models/order.d.cts" />
+* /// \<reference path="../models/account.d.mts" />
+* ```
+*/
+declare const generateReferenceIndex: (pattern: StringCollection, options?: GenerateReferenceOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link getPackageJson | **`get-package-json`**}.***
+* ----------------------------------------------------------------
+*/
+type GetPackageJsonOptions = {
+  /** ----------------------------------------------------------------
+  * * ***Working directory of the target project.***
+  * ----------------------------------------------------------------
+  *
+  * This determines where the lookup for `package.json`
+  * will start.
+  *
+  * - If provided, resolution begins from this directory.
+  * - If omitted, defaults to `process.cwd()`.
+  *
+  * - ***Typical use cases:***
+  *       - CLI tools executed in a project directory.
+  *       - Monorepo root resolution.
+  *       - Custom build pipelines.
+  *
+  * @default process.cwd()
+  *
+  * @remarks
+  * This should be the directory containing your project's
+  * `package.json`, not the directory of this package.
+  */
+  cwd?: string;
+};
+/** ----------------------------------------------------------------
+* * ***Resolve and read the nearest `package.json`.***
+* ----------------------------------------------------------------
+*
+* This utility locates and loads the closest `package.json`
+* by walking up the directory tree starting from a given
+* working directory.
+*
+* - *Key characteristics:*
+*     - Works in **Node ESM and CJS**.
+*     - Compatible with **tsdown, rolldown, tsup, esbuild, vite, tsx, ts-node, and others**.
+*     - Does **not** rely on JSON module imports.
+*     - Fully typed via {@link PackageJson | **PackageJson**}.
+*
+* - *This function is intended for:*
+*     - Build tools.
+*     - Bundler configuration.
+*     - CLI utilities.
+*     - Monorepo-aware infrastructure code.
+*
+* @param options Optional resolution configuration.
+*
+* @returns The parsed contents of the resolved `package.json`.
+*
+* @example
+* ```ts
+* const pkg = await getPackageJson();
+* console.log(pkg.name, pkg.version);
+* ```
+*
+* @example
+* ```ts
+* const pkg = await getPackageJson({
+*   cwd: process.cwd()
+* });
+* ```
+*
+* @throws If no `package.json` can be found.
+* @throws If the located `package.json` is invalid JSON.
+*
+* @remarks
+* - Resolution always starts from `cwd` or `process.cwd()`.
+* - Results are not cached by default.
+* - Designed for infrastructure-level usage, not hot paths.
+*/
+declare const getPackageJson: (options?: GetPackageJsonOptions) => Promise<PackageJson>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **inject banner** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link injectBanner | **`inject-banner`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_IB_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **inject banner** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link injectBanner | **`inject-banner`**}.
+*/
+declare const resolvedIbPatternOption: PatternOptions<true, true>;
+/** Command identity associated with {@link injectBanner | **`inject-banner`**}. */
+declare const commandIbIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link injectBanner | `inject-banner`}.***
+* ----------------------------------------------------------------
+*/
+type InjectBannerOptions = {
+  /** Replace existing banner block(s).
+  *
+  * - `false` ➔ Preserve existing banners.
+  * - `true` ➔ Replace banners matching default `/^(?:\/\*![\s\S]*?\*\/\s*)+/`.
+  * - `RegExp` ➔ Replace banners matching provided pattern.
+  *
+  * Note:
+  * The provided RegExp will be internally cloned without the `g` flag
+  * to ensure safe `.test()` execution.
+  *
+  * @default false
+  */
+  replaceBanner?: boolean | RegExp;
+  /** Remove duplicated banner blocks.
+  *
+  * Deduplication is performed using `trim()` comparison.
+  *
+  * @default true
+  */
+  removeDuplicate?: boolean;
+  /** Control where new banner block(s) are injected.
+  *
+  * - `"top"` ➔ Place new banner before existing banner blocks.
+  * - `"after-existing"` ➔ Append new banner after existing blocks.
+  *
+  * @default "after-existing"
+  */
+  bannerPosition?: "top" | "after-existing";
+} & BaseOptions<typeof DEFAULT_IB_PATTERN_POLICY.filesOnly, typeof DEFAULT_IB_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Injects banner comments into JavaScript output files.***
+* ----------------------------------------------------------------
+*
+* Scans files that match the provided glob pattern(s) and injects one or
+* more banner comment blocks at the top of each file when applicable.
+*
+* - ***Injection Rules:***
+*       - Skips files that:
+*          - Are empty after trimming.
+*          - Contain no executable JavaScript code.
+*          - Match `NON_COMMENTABLE_FILE_RE`.
+*       - Preserves existing shebang (`#!`) at the very top of the file.
+*       - Existing banner blocks are detected using `BANNER_RE`.
+*
+* - ***Replace Mode:***
+*       - If `options.replaceBanner` is:
+*          - `true` ➔ uses default `BANNER_RE`.
+*          - `RegExp` ➔ uses the provided pattern.
+*       - If the existing banner matches the replace pattern,
+*         it will be fully replaced with the new banner block(s).
+*       - The replace pattern is executed without the `g` flag internally
+*         to avoid stateful RegExp side effects.
+*
+* - ***Banner Ordering:***
+*       Controlled by `options.bannerPosition`:
+*       - `"top"` ➔ new banner is placed before existing banner blocks.
+*       - `"after-existing"` ➔ new banner is appended after existing blocks.
+*
+* - ***Deduplication:***
+*       If `options.removeDuplicate` is `true` (default):
+*       - Banner blocks are deduplicated based on `trim()` comparison.
+*       - Order is preserved.
+*
+* - ***Normalization:***
+*       - Line endings are normalized to the internal `EOL` constant.
+*       - Each banner block is ensured to end with exactly two `EOL`s.
+*       - The operation is idempotent — running multiple times
+*         will not change the file further.
+*
+* @example
+* Basic usage:
+* ```ts
+* await injectBanner(
+*   "dist/**\/*.js",
+*   `
+*   /**
+*    * My Library v1.0.0
+*    * (c) 2026 Your Name
+*    *\/
+*   `
+* );
+* ```
+*
+* @example
+* Inject multiple banner blocks:
+* ```ts
+* await injectBanner(
+*   ["dist/**\/*.js", "build/**\/*.mjs"],
+*   [
+*     `/** Project: MyApp *\/`,
+*     `/** License: MIT *\/`
+*   ]
+* );
+* ```
+*
+* @example
+* Replace existing banner entirely:
+* ```ts
+* await injectBanner(
+*   "dist/**\/*.js",
+*   `/** Updated License Banner *\/`,
+*   { replaceBanner: true }
+* );
+* ```
+*
+* @example
+* Replace using custom RegExp:
+* ```ts
+* await injectBanner(
+*   "dist/**\/*.js",
+*   `/** New Banner *\/`,
+*   {
+*     replaceBanner: /^\/\*\*![\s\S]*?\*\/\s*\/,
+*   }
+* );
+* ```
+*
+* @example
+* Always place banner at very top (after shebang):
+* ```ts
+* await injectBanner(
+*   "dist/**\/*.js",
+*   `/** Build: Production *\/`,
+*   {
+*     bannerPosition: "top"
+*   }
+* );
+* ```
+*
+* @param pattern - Glob pattern(s) pointing to target JavaScript files.
+* @param bannerText - Banner string(s) to inject.
+* @param options - Injection configuration options.
+*/
+declare const injectBanner: (pattern: StringCollection, bannerText: StringCollection, options?: InjectBannerOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **inject directive** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link injectDirective | **`inject-directive`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_ID_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **inject directive** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link injectDirective | **`inject-directive`**}.
+*/
+declare const resolvedIdPatternOption: PatternOptions<true, true>;
+/** Command identity associated with {@link injectDirective | **`inject-directive`**}. */
+declare const commandIdIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link injectDirective | **`inject-directive`**}.***
+* ----------------------------------------------------------------
+*/
+type InjectDirectiveOptions = BaseOptions<typeof DEFAULT_ID_PATTERN_POLICY.filesOnly, typeof DEFAULT_ID_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Injects directive statements into JavaScript output files.***
+* ----------------------------------------------------------------
+*
+* This function scans files matching the provided glob pattern(s) and
+* injects one or more directive statements (e.g. `"use strict"`,
+* `"use client"`) at the top of each file when applicable.
+*
+* - *Injection behavior:*
+*     - Skips empty files.
+*     - Skips files that only contain directive statements.
+*     - Avoids duplicating existing directives.
+*     - Preserves existing file content order.
+*
+* - *Each directive is normalized and injected as a standalone statement:*
+*     ```js
+*     "directive-name";
+*     ```
+*
+* @param pattern - Glob pattern or list of patterns pointing to JS output files.
+* @param directive - Directive string(s) to inject.
+* @param options - Injection configuration options, see {@link InjectDirectiveOptions | **`InjectDirectiveOptions`**}.
+*
+* @example
+* ```ts
+* await injectDirective("dist/**\/*.js", "use strict");
+* ```
+*
+* @example
+* ```ts
+* await injectDirective("dist/**\/*.js", "use client");
+* ```
+*
+* @example
+* ```ts
+* await injectDirective(
+*   ["dist/**\/*.js", "build/*\/*.mjs"],
+*   ["use strict", "use client"]
+* );
+* ```
+*/
+declare const injectDirective: (pattern: StringCollection, directive: StringCollection, options?: InjectDirectiveOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **normalize js build newlines** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link normalizeJsBuildNewlines | **`normalize-js-build-newlines`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_NJBN_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **normalize js build newlines** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link normalizeJsBuildNewlines | **`normalize-js-build-newlines`**}.
+*/
+declare const resolvedNjbnPatternOption: PatternOptions<true, true>;
+/** Generated Command Identity For {@link normalizeJsBuildNewlines | **`normalize-js-build-newlines`**}. */
+declare const commandNjbnIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link normalizeJsBuildNewlines | **`normalizeJsBuildNewlines`**}.***
+* ----------------------------------------------------------------
+*/
+type NormalizeJsBuildNewlinesOptions = BaseOptions<typeof DEFAULT_NJBN_PATTERN_POLICY.filesOnly, typeof DEFAULT_NJBN_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Normalizes excessive blank lines in compiled JavaScript files.***
+* ----------------------------------------------------------------
+*
+* This function scans JavaScript build output files and normalizes
+* excessive consecutive newlines.
+*
+* Any occurrence of **three or more consecutive line breaks**
+* (`\n` or `\r\n`) will be collapsed into exactly **two newlines**,
+* ensuring cleaner and more readable build artifacts.
+*
+* - *The process is **non-destructive**:*
+*     - Files are only rewritten if normalization is actually needed.
+*     - Duplicate file paths are automatically deduplicated using {@link Set | `Set`}.
+*
+* - *Supported JavaScript output extensions:*
+*     - `.js`.
+*     - `.cjs`.
+*     - `.mjs`.
+*     - `.esm.js`.
+*     - `.module.js`.
+*
+* @param pattern - Glob pattern(s) or a set of file paths pointing to JS build outputs.
+* @param options - Normalization configuration options.
+*
+* @example
+* ```ts
+* await normalizeJsBuildNewlines("dist/**\/*.js");
+* ```
+*
+* @example
+* ```ts
+* await normalizeJsBuildNewlines("dist/**\/*.{js,cjs,mjs}");
+* ```
+*
+* @example
+* ```ts
+* await normalizeJsBuildNewlines(
+*   ["dist/**\/*.js", "build/**\/*.mjs", "out/**\/*.{js,mjs}"],
+* );
+* ```
+*
+* @remarks
+* - This utility is intended for **post-build cleanup** and is safe to run
+* multiple times.
+* - Re-running it on already normalized files will result
+* in no changes.
+*/
+declare const normalizeJsBuildNewlines: (pattern: StringCollection, options?: NormalizeJsBuildNewlinesOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Default Pattern Policy for **strip js comments** operations.***
+* ----------------------------------------------------------------
+*
+* Defines the runtime behavior for pattern resolution used by:
+* - {@link stripJsComments | **`strip-js-comments`**}.
+*
+* @remarks
+* - `filesOnly`: Ensures only files are matched.
+* - `forceUnique`: Deduplicates matched results.
+*/
+declare const DEFAULT_SJC_PATTERN_POLICY: {
+  readonly filesOnly: true;
+  readonly forceUnique: true;
+};
+/** ----------------------------------------------------------------
+* * ***Resolved Pattern Options for **strip js comments** operations.***
+* ----------------------------------------------------------------
+*
+* Pattern options used by:
+* - {@link stripJsComments | **`strip-js-comments`**}.
+*/
+declare const resolvedSjcPatternOption: PatternOptions<true, true>;
+/** Command identity associated with {@link stripJsComments | **`strip-js-comments`**}. */
+declare const commandSjcIdentity: CommandIdentity;
+/** ----------------------------------------------------------------
+* * ***Configuration options for {@link stripJsComments | `strip-js-comment`}.***
+* ----------------------------------------------------------------
+*/
+type StripJsCommentsOptions = {
+  /** ----------------------------------------------------------------
+  * * ***Whether to remove `sourceMappingURL` comments.***
+  * ----------------------------------------------------------------
+  *
+  * @default false
+  */
+  removeSourceMap?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***Whether to remove `region` comments.***
+  * ----------------------------------------------------------------
+  *
+  * @default true
+  */
+  removeRegion?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***Parsing mode used when analyzing JavaScript code.***
+  * ----------------------------------------------------------------
+  *
+  * Determines how the source file should be interpreted by the parser.
+  * This affects strict mode behavior and how `import` / `export`
+  * statements are handled.
+  *
+  *
+  * Possible values:
+  *
+  * - `"module"` **(default)** ➔ Parse as an ES module.
+  * - `"script"` ➔ Parse as a classic script.
+  * - `"commonjs"` ➔ Parse using CommonJS semantics.
+  *
+  * ----------------------------------------------------------------
+  *
+  *  ⚠️ Fallback to default, is invalid input.
+  *
+  *
+  * @default "module"
+  *
+  */
+  sourceType?: acorn.Options["sourceType"];
+  /** ----------------------------------------------------------------
+  * * ***ECMAScript version used for parsing.***
+  * ----------------------------------------------------------------
+  *
+  * Specifies the ECMAScript syntax version supported by the parser.
+  * This determines which language features are recognized during parsing.
+  *
+  * Examples:
+  *
+  * - `5` ➔ ES5
+  * - `2020` ➔ ES2020
+  * - `"latest"` ➔ Latest supported version
+  *
+  * ----------------------------------------------------------------
+  *
+  * ⚠️ Invalid values will fallback to the default behavior.
+  *
+  * @default "latest"
+  */
+  ecmaVersion?: acorn.ecmaVersion;
+} & BaseOptions<typeof DEFAULT_SJC_PATTERN_POLICY.filesOnly, typeof DEFAULT_SJC_PATTERN_POLICY.forceUnique>;
+/** ----------------------------------------------------------------
+* * ***Strip comments from JavaScript output files.***
+* ----------------------------------------------------------------
+*
+* Scans files matching the provided glob pattern(s) and removes
+* non-essential comments from JavaScript output.
+*
+* The process preserves important comments such as:
+*
+* - `/*! ... *\/` (bang / license comments)
+* - `@license`
+* - `@preserve`
+* - `@copyright`
+* - `@cc_on`
+* - `@__PURE__`
+* - `@__INLINE__`
+* - `@__NOINLINE__`
+* - `@__NO_SIDE_EFFECTS__`
+*
+* unless explicitly overridden by the `@removeDocRuntime` directive.
+*
+* ----------------------------------------------------------------
+*
+* **Supported Features**
+*
+* - Removes regular block comments from compiled JS files.
+* - Optionally removes `sourceMappingURL` comments.
+* - Optionally removes `region` comments such as:
+*    - `// #region`
+*    - `// #endregion`
+* - Supports runtime directives inside comments:
+*    - `@keepDocRuntime`
+*    - `@removeDocRuntime`
+*
+* ----------------------------------------------------------------
+*
+* @param pattern - Glob pattern(s) or a set of patterns pointing to
+* files whose comments should be stripped.
+*
+* @param options - Optional configuration controlling how comments
+* are removed.
+*
+* ----------------------------------------------------------------
+*
+* @example
+* ```ts
+* await stripJsComments("dist/**\/*.js");
+* ```
+*
+* @example
+* ```ts
+* await stripJsComments(["dist/**\/*.js", "build/**\/*.mjs"], {
+*   removeSourceMap: true,
+*   removeRegion: true
+* });
+* ```
+*
+* ----------------------------------------------------------------
+*
+* @removeDocRuntime
+*/
+declare const stripJsComments: (pattern: StringCollection, options?: StripJsCommentsOptions) => Promise<void>;
+/** ----------------------------------------------------------------
+* * ***Base Options for `runCommand` or `runCommandCapture`.***
+* ----------------------------------------------------------------
+*/
+type BaseRunCommandOptions = {
+  /** ----------------------------------------------------------------
+  * * ***Standard input/output configuration for the spawned process.***
+  * ----------------------------------------------------------------
+  * Controls how `stdin`, `stdout`, and `stderr` are handled.
+  *
+  * - *Can be set to:*
+  *     - `"pipe"` – create a pipe between parent and child.
+  *     - `"inherit"` – inherit the parent process streams.
+  *     - `"overlapped"` – use overlapped I/O (Windows only).
+  *     - `"ignore"` – discard the stream.
+  *
+  * - *An array form may be used to configure each stream individually:*
+  *     - Index `0` ➔ `stdin`.
+  *     - Index `1` ➔ `stdout`.
+  *     - Index `2` ➔ `stderr`.
+  *     - Index `3` ➔ additional custom stream (optional).
+  *
+  * If passed as an array, the first element is used for `stdin`, the second for
+  * `stdout`, and the third for `stderr`.
+  *
+  * A fourth element can be used to
+  * specify the `stdio` behavior beyond the standard streams.
+  *
+  * @See {@link ChildProcess.stdio | **`ChildProcess.stdio`**} for more information.
+  *
+  * @default "inherit"
+  */
+  stdio?: StdioOptions;
+  /** ----------------------------------------------------------------
+  * * ***Working directory for the spawned process.***
+  * ----------------------------------------------------------------
+  *
+  * Equivalent to `process.cwd()` when not provided.
+  */
+  cwd?: string | URL;
+  /** ----------------------------------------------------------------
+  * * ***Environment variables passed to the spawned process.***
+  * ----------------------------------------------------------------
+  *
+  * Defaults to `process.env`.
+  */
+  env?: NodeJS.ProcessEnv;
+  /** ----------------------------------------------------------------
+  * * ***Disable execution inside a system shell.***
+  * ----------------------------------------------------------------
+  *
+  * By default, commands are executed inside a system shell:
+  * - `sh` on Unix-based systems.
+  * - `cmd.exe` on Windows.
+  *
+  * Set this option to `false` to bypass the shell and execute
+  * the command directly.
+  *
+  * This is useful for:
+  * - Strict argument handling.
+  * - Avoiding shell interpretation.
+  *
+  * @default true (shell is enabled)
+  */
+  shell?: false;
+  /** ----------------------------------------------------------------
+  * * ***Abort signal for cancelling the spawned process.***
+  * ----------------------------------------------------------------
+  *
+  * When the signal is aborted:
+  * - The child process will be terminated using `SIGTERM`.
+  * - The returned promise will be rejected with an abort error.
+  *
+  * If the signal is already aborted before execution,
+  * the command will not be started.
+  *
+  * @default undefined
+  *
+  * @example
+  * ```ts
+  * const controller = new AbortController();
+  * runCommand("pnpm", ["dev"], { signal: controller.signal });
+  * controller.abort();
+  * ```
+  */
+  signal?: AbortSignal;
+  /** ----------------------------------------------------------------
+  * * ***Maximum execution time before forcefully terminating the process.***
+  * ----------------------------------------------------------------
+  *
+  * When the timeout is reached:
+  * - The child process will be terminated using `SIGTERM`.
+  * - The returned promise will be rejected with a timeout error.
+  *
+  * This is useful for preventing hanging processes
+  * or enforcing execution limits in automation scripts.
+  *
+  * @default undefined (no timeout)
+  *
+  * @note ⚠️ Setting to `0` will cause immediate termination.
+  */
+  timeout?: number;
+  /** ----------------------------------------------------------------
+  * * ***Forcefully terminate the spawned process (Windows only).***
+  * ----------------------------------------------------------------
+  *
+  * When enabled, the process will be terminated using:
+  * - `taskkill /f /t` on Windows (kills the entire process tree).
+  *
+  * This ensures that all child processes are also terminated,
+  * preventing orphaned or zombie processes.
+  *
+  * - This option is useful for:
+  *    - Long-running processes.
+  *    - Dev servers or watchers.
+  *    - Ensuring clean shutdown in CI environments.
+  *
+  * @default false
+  */
+  forceKill?: boolean;
+  /** ----------------------------------------------------------------
+  * * ***Enable colored output for logs and error messages.***
+  * ----------------------------------------------------------------
+  *
+  * When enabled:
+  * - Commands will be formatted with colors.
+  * - Error messages will include highlighted command strings.
+  *
+  * This is useful for:
+  * - CLI tools.
+  * - Developer-friendly logs.
+  *
+  * @default true
+  */
+  useColors?: boolean;
+} & Omit<SpawnOptions, "cwd" | "env" | "shell" | "stdio" | "argv0" | "timeout">;
+/** ----------------------------------------------------------------
+* * ***Represents a command execution failure.***
+* ----------------------------------------------------------------
+*
+* This error is thrown when a spawned process fails during execution
+* via {@link runCommand | **`runCommand`**}, {@link runCommandCapture | **`runCommandCapture`**} or related utilities.
+*
+* It extends the native {@link Error | `Error`} class and provides structured
+* metadata describing the failure.
+*
+* ---
+*
+* - *Failure reasons:*
+*     - `"timeout"` ➔ The process exceeded the configured timeout.
+*     - `"abort"` ➔ The process was aborted via an `AbortSignal`.
+*     - `"signal"` ➔ The process was terminated by an OS signal.
+*     - `"non-zero exit code"` ➔ The process exited with a non-zero code.
+*
+* ---
+*
+* - *Metadata:*
+*     - `reason` ➔ Reason for failure.
+*     - `exitCode` ➔ Exit code (if available).
+*     - `signal` ➔ Termination signal (if any).
+*     - `command` ➔ Executed command (plain string, no colors).
+*
+* ---
+*
+* - *Behavior:*
+*     - Thrown when a process fails in {@link runCommand | `runCommand`}.
+*     - May also be thrown in {@link runCommandCapture | `runCommandCapture`} for:
+*        - Spawn errors.
+*        - Abort signals.
+*        - Timeouts.
+*        - Signal termination.
+*     - Includes formatted stack output for CLI readability.
+*     - Metadata is available for programmatic handling.
+*
+* ----------------------------------------------------------------
+* @example
+* ```ts
+* try {
+*   await runCommand("pnpm", ["build"]);
+* } catch (err) {
+*   if (err instanceof CommandProcessError) {
+*     console.error("Reason:", err.reason);
+*     console.error("Exit code:", err.exitCode);
+*   }
+* }
+* ```
+*
+* OR with `isCommandProcessError`.
+*
+* @example
+* ```ts
+* try {
+*   await runCommand("pnpm", ["build"]);
+* } catch (err) {
+*   if (isCommandProcessError(err)) {
+*     console.error("Reason:", err.reason);
+*     console.error("Exit code:", err.exitCode);
+*   }
+* }
+* ```
+*
+* @remarks
+* - This error is designed for both:
+*    - Human-readable CLI output.
+*    - Programmatic error handling.
+*
+* - Metadata properties are non-enumerable to avoid duplicate
+*   output when logged via `console.error`.
+*/
+declare class CommandProcessError extends Error {
+  reason: "timeout" | "abort" | "signal" | "non-zero exit code";
+  exitCode?: number;
+  signal?: NodeJS.Signals | null;
+  command: string;
+  constructor(message: string, meta: {
+    reason: CommandProcessError["reason"];
+    exitCode?: number;
+    signal?: NodeJS.Signals | null;
+    command: string;
+  });
+}
+/** ----------------------------------------------------------------
+* * ***Type guard for `CommandProcessError`.***
+* ----------------------------------------------------------------
+*
+* Utility to check whether a given value is an instance of
+* {@link CommandProcessError | `CommandProcessError`}.
+*
+* Useful when handling unknown errors in `try/catch` blocks.
+*
+* ----------------------------------------------------------------
+* @param err
+* The unknown error value to check.
+*
+* @returns
+* `true` if the value is a `CommandProcessError`, otherwise `false`.
+*
+* ----------------------------------------------------------------
+* @example
+* ```ts
+* try {
+*   await runCommand("pnpm", ["build"]);
+* } catch (err) {
+*   if (isCommandProcessError(err)) {
+*     console.error(err.reason);
+*     console.error(err.exitCode);
+*   }
+* }
+* ```
+*/
+declare function isCommandProcessError(err: unknown): err is CommandProcessError;
+/** ----------------------------------------------------------------
+* * ***Result returned by {@link runCommandCapture | `runCommandCapture`}.***
+* ----------------------------------------------------------------
+*
+* Represents the captured output and execution status of a command.
+*
+* - *Behavior:*
+*     - `stdout` and `stderr` are fully buffered as UTF-8 strings.
+*     - `exitCode` reflects the process exit status.
+*     - `ok` indicates whether the command succeeded (`exitCode === 0`).
+*/
+type RunCommandCaptureResult = {
+  /** ----------------------------------------------------------------
+  * * ***Captured standard output.***
+  * ----------------------------------------------------------------
+  *
+  * The complete `stdout` output of the process as a UTF-8 string.
+  *
+  * - Trailing newlines may be trimmed depending on implementation.
+  */
+  stdout: string;
+  /** ----------------------------------------------------------------
+  * * ***Captured standard error output.***
+  * ----------------------------------------------------------------
+  *
+  * The complete `stderr` output of the process as a UTF-8 string.
+  *
+  * - Useful for debugging or logging failures.
+  */
+  stderr: string;
+  /** ----------------------------------------------------------------
+  * * ***Process exit code.***
+  * ----------------------------------------------------------------
+  *
+  * The numeric exit code returned by the process.
+  *
+  * - `0` usually indicates success.
+  * - Non-zero values usually indicate failure.
+  */
+  exitCode: number;
+  /** ----------------------------------------------------------------
+  * * ***Execution success flag.***
+  * ----------------------------------------------------------------
+  *
+  * Indicates whether the command completed successfully.
+  *
+  * Equivalent to:
+  * ```ts
+  * exitCode === 0
+  * ```
+  */
+  ok: boolean;
+};
+/** ----------------------------------------------------------------
+* * ***Options for executing a shell command via {@link runCommandCapture | **`runCommandCapture`**}.***
+* ----------------------------------------------------------------
+*/
+type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
+/** ----------------------------------------------------------------
+* * ***Execute a command and capture its output.***
+* ----------------------------------------------------------------
+*
+* This utility spawns a child process using
+* {@link spawn | **`child_process.spawn`**} and buffers its output.
+*
+* Unlike {@link runCommand | **`runCommand`**}, this function:
+* - Captures `stdout` and `stderr` into strings.
+* - Does **not** stream output to the parent process.
+* - Always resolves (even for non-zero exit codes).
+*
+* - *Behavior:*
+*     - Uses `stdio: "pipe"` (output is buffered).
+*     - Collects `stdout` and `stderr` as UTF-8 strings.
+*     - Resolves when the process exits (regardless of exit code).
+*     - Rejects only on:
+*        - Spawn errors.
+*        - Abort signals.
+*        - Timeouts.
+*        - Process termination by signal.
+*
+* - *This function is designed for:*
+*     - Capturing CLI output.
+*     - Running commands programmatically.
+*     - Parsing results (JSON, text, etc.).
+*     - Testing and scripting utilities.
+*
+* @param {string} command
+* The executable or command to run.
+*
+* @param {readonly string[]} [args]
+* Arguments passed to the command.
+*
+* @param {RunCommandCaptureOptions} [options]
+* Optional execution configuration.
+*
+* @returns {Promise<RunCommandCaptureResult>}
+* Resolves with an object containing:
+* - `stdout` ➔ captured standard output.
+* - `stderr` ➔ captured standard error.
+* - `exitCode` ➔ process exit code.
+* - `ok` ➔ `true` if exit code is `0`.
+*
+* ----------------------------------------------------------------
+* #### Error handling.
+*
+* This function does NOT reject on non-zero exit codes.
+* - Instead, use:
+*    - `result.ok`.
+*    - `result.exitCode`.
+*
+* - However, the promise WILL reject for:
+*    - spawn errors.
+*    - abort signals.
+*    - timeouts.
+*    - termination by signal.
+*
+* In those cases, the promise is rejected with a
+* {@link CommandProcessError | **`CommandProcessError`**}.
+*
+* - *Error metadata:*
+*     - `reason` ➔ `"timeout" | "abort" | "signal" | "non-zero exit code"`.
+*     - `exitCode` ➔ Exit code (if available).
+*     - `signal` ➔ Termination signal (if any).
+*     - `command` ➔ Executed command (plain string, no colors).
+*
+* - *Type narrowing:*
+*     - Use `instanceof CommandProcessError` to safely access metadata.
+*     - Or use {@link isCommandProcessError | **`isCommandProcessError`**} as a type guard.
+*
+* - *Notes:*
+*     - `"non-zero exit code"` is NOT treated as an error in this function.
+*     - Metadata is available programmatically (e.g. `err.reason`).
+*     - Metadata is also included in the formatted stack output
+*       for CLI readability.
+*
+* @example
+* ```ts
+* try {
+*   await runCommandCapture("pnpm", ["build"]);
+* } catch (err) {
+*   if (err instanceof CommandProcessError) {
+*     console.error("Command failed:", err.reason);
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* try {
+*   await runCommandCapture("pnpm", ["dev"]);
+* } catch (err) {
+*   if (isCommandProcessError(err)) {
+*     console.error(err.reason);
+*   }
+* }
+* ```
+* ----------------------------------------------------------------
+* @example
+* ```ts
+* const result = await runCommandCapture("node", ["--version"]);
+*
+* console.log(result.stdout);
+* ```
+*
+* @example
+* ```ts
+* const { stdout, ok } = await runCommandCapture("pnpm", ["build"]);
+*
+* if (!ok) {
+*   console.error("Build failed");
+* }
+* ```
+*
+* @example
+* ```ts
+* const controller = new AbortController();
+*
+* runCommandCapture("pnpm", ["dev"], {
+*   signal: controller.signal
+* });
+*
+* controller.abort();
+* ```
+*
+* @remarks
+* - **Execution model:**
+*    - Uses {@link spawn | **`spawn`**} to avoid output size limits
+*      imposed by `exec`.
+*
+* - **Output handling:**
+*    - Always uses `stdio: "pipe"` (cannot be overridden).
+*    - Output is buffered entirely in memory.
+*
+* - **Exit behavior:**
+*    - Does NOT reject on non-zero exit codes.
+*    - Use `result.ok` or `result.exitCode` to handle failures.
+*
+* - **Shell execution:**
+*    - Defaults to `shell: true`.
+*    - Same behavior and constraints as {@link runCommand | `runCommand`}.
+*
+* - **Abort & timeout:**
+*    - Abort signals and timeouts will terminate the process
+*      and reject the promise.
+*
+* - **When NOT to use this utility:**
+*    - When output needs to be streamed in real-time
+*    - When handling very large outputs (risk of high memory usage)
+*
+* ***In those cases, use {@link runCommand | `runCommand`}.***
+*/
+declare function runCommandCapture(command: string, args: readonly string[]): Promise<RunCommandCaptureResult>;
+declare function runCommandCapture(command: string, options: RunCommandCaptureOptions): Promise<RunCommandCaptureResult>;
+declare function runCommandCapture(command: string, args: readonly string[], options: RunCommandCaptureOptions): Promise<RunCommandCaptureResult>;
+/** ----------------------------------------------------------------
+* * ***Options for executing a shell command via {@link runCommand | **`runCommand`**}.***
+* ----------------------------------------------------------------
+*/
+type RunCommandOptions = BaseRunCommandOptions;
+/** ----------------------------------------------------------------
+* * ***Execute a command and stream output to the current process.***
+* ----------------------------------------------------------------
+*
+* This utility spawns a child process using
+* {@link spawn | **`child_process.spawn`**}.
+*
+* By default, it forwards `stdout` and `stderr` directly to the parent
+* process using `stdio: "inherit"` (real-time streaming, no buffering).
+*
+* - *Behavior:*
+*     - Uses `stdio: "inherit"` by default (can be overridden).
+*     - Does **not** buffer output.
+*     - Resolves only when the process exits with code `0`.
+*     - Rejects if the process exits with a non-zero code,
+*       is terminated by a signal, aborted, or times out.
+*
+* - *This function is designed for:*
+*     - Build steps.
+*     - Post-build hooks.
+*     - CLI tooling.
+*     - Long-running tasks (bundlers, compilers, CSS processors).
+*
+* @param {string} command
+* The executable or command to run.
+*
+* @param {readonly string[]} [args]
+* Arguments passed to the command.
+*
+* @param {RunCommandOptions} [options]
+* Optional execution configuration.
+*
+* @returns {Promise<ChildProcess>}
+* Resolves with the spawned {@link ChildProcess | **`ChildProcess`**} instance
+* **after the process exits successfully (exit code `0`)**.
+*
+* ----------------------------------------------------------------
+* #### Error handling
+*
+* When the process fails, the promise is rejected with a
+* {@link CommandProcessError | **`CommandProcessError`**}.
+*
+* - *Error metadata:*
+*     - `reason` ➔ `"timeout" | "abort" | "signal" | "non-zero exit code"`.
+*     - `exitCode` ➔ Exit code (if available).
+*     - `signal` ➔ Termination signal (if any).
+*     - `command` ➔ Executed command (plain string, no colors).
+*
+* - *Type narrowing:*
+*     - Use `instanceof CommandProcessError` to safely access metadata.
+*     - Or use {@link isCommandProcessError | **`isCommandProcessError`**} as a type guard.
+*
+* - *Notes:*
+*     - Metadata is available programmatically (e.g. `err.reason`).
+*     - Metadata is also included in the formatted stack output
+*       for CLI readability.
+*
+* @example
+* ```ts
+* try {
+*   await runCommand("pnpm", ["build"]);
+* } catch (err) {
+*   if (err instanceof CommandProcessError) {
+*     if (err.reason === "non-zero exit code") {
+*       console.error("Build failed with code:", err.exitCode);
+*     }
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* try {
+*   await runCommand("pnpm", ["build"]);
+* } catch (err) {
+*   if (isCommandProcessError(err)) {
+*     console.error(err.reason);
+*   }
+* }
+* ```
+* ----------------------------------------------------------------
+*
+* @example
+* ```ts
+* await runCommand("pnpm", ["build"]);
+* ```
+*
+* @example
+* ```ts
+* const child = await runCommand("node", ["script.js"]);
+* console.log(child.pid);
+* ```
+*
+* @example
+* ```ts
+* const controller = new AbortController();
+*
+* runCommand("pnpm", ["dev"], {
+*   signal: controller.signal
+* });
+*
+* controller.abort();
+* ```
+*
+* @example
+* ```ts
+* await runCommand("npm", ["run", "build"], {
+*   timeout: 5000
+* });
+* ```
+*
+* @remarks
+* - **Execution model:**
+*      - Uses {@link spawn | **`spawn`**} instead of `exec` to avoid
+*        output buffering and support long-running processes.
+*
+* - **Output handling:**
+*      - Defaults to `stdio: "inherit"` (streams output to parent).
+*      - If `stdio` is overridden (e.g. `"pipe"`), output will NOT be auto-forwarded.
+*
+* - **Shell execution:**
+*      - Defaults to {@link RunCommandOptions.shell | **`shell: true`**}.
+*      - Required on Windows to resolve commands like `pnpm`, `npm`, `git`, etc.
+*      - When `shell: false`, the command must be:
+*         - An absolute path, or
+*         - A directly executable binary.
+*
+* - **Abort handling:**
+*      - When `signal` is provided, the process will be terminated
+*        with `SIGTERM` if aborted.
+*
+* - **Timeout handling:**
+*      - When `timeout` is set, the process will be terminated
+*        after the specified duration.
+*      - `undefined` ➔ no timeout.
+*      - ⚠️ `0` ➔ immediate termination.
+*
+* - **Common errors:**
+*      - **`ENOENT`** ➔ command not found:
+*          - Not installed
+*          - Not in `PATH`
+*          - `shell: false` with non-absolute command
+*
+* - **When NOT to use this utility:**
+*      - When you need to capture output programmatically.
+*      - When you need advanced shell features (`|`, `>`, `&&`).
+*
+* ***In those cases, consider using `exec` or a dedicated process runner.***
+*/
+declare function runCommand(command: string, args: readonly string[]): Promise<ChildProcess>;
+declare function runCommand(command: string, options: RunCommandOptions): Promise<ChildProcess>;
+declare function runCommand(command: string, args: readonly string[], options: RunCommandOptions): Promise<ChildProcess>;
+export { type BaseOptions, type CleanJsArtifactsOptions, type CleanTypesArtifactsOptions, type Collection, CommandProcessError, type CopyFileToDestOptions, type CopyFileToDestParam, DEFAULT_CLEAN_PATTERN_POLICY, DEFAULT_ECI_PATTERN_POLICY, DEFAULT_EFN_PATTERN_POLICY, DEFAULT_GRI_PATTERN_POLICY, DEFAULT_IB_PATTERN_POLICY, DEFAULT_ID_PATTERN_POLICY, DEFAULT_NJBN_PATTERN_POLICY, DEFAULT_SJC_PATTERN_POLICY, type EnsureCssImportOptions, type EnsureFinalNewlineOptions, type GeneratePackageBannerOptions, type GenerateReferenceOptions, type GetPackageJsonOptions, type InjectBannerOptions, type InjectDirectiveOptions, type InternalOptions, type LogLevel, type LoggingOptions, type NormalizeJsBuildNewlinesOptions, type PatternConfig, type PatternOptions, type RunCommandCaptureOptions, type RunCommandCaptureResult, type RunCommandOptions, type StringCollection, type StripJsCommentsOptions, cleanJsBuildArtifacts, cleanTypesBuildArtifacts, commandCftdIdentity, commandCjbaIdentity, commandCtbaIdentity, commandEciIdentity, commandEfnIdentity, commandGriIdentity, commandIbIdentity, commandIdIdentity, commandNjbnIdentity, commandSjcIdentity, copyFileToDest, createCopyFileToDestParameterSet, ensureCssImport, ensureFinalNewline, generatePackageBanner, generateReferenceIndex, getPackageJson, injectBanner, injectDirective, isCommandProcessError, normalizeJsBuildNewlines, resolvedCleanPatternOption, resolvedEciPatternOption, resolvedEfnPatternOption, resolvedGriPatternOption, resolvedIbPatternOption, resolvedIdPatternOption, resolvedNjbnPatternOption, resolvedSjcPatternOption, runCommand, runCommandCapture, stripJsComments };
+//# sourceMappingURL=index.d.ts.map