@rzl-zone/build-tools 0.0.9 → 0.0.11

package/dist/index.d.cts

@@ -2,16 +2,16 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.9`
+*  Version: `0.0.11`
 *  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-CsRmdXC4.cjs";
-import { n as generatePackageBanner, r as PackageJson, t as GeneratePackageBannerOptions } from "./index-TgjbNRWB.cjs";
-import { t as CommandIdentity } from "./index-xAz8brx-.cjs";
-import { n as PatternOptions, t as PatternConfig } from "./fast-globe-options-PH-bHWVK.cjs";
+import { a as OmitStrict, c as PrettifyOptions, r as DefaultPrettifyOptions, s as Prettify } from "./extra-C8r3KWjP.cjs";
+import { n as generatePackageBanner, r as PackageJson, t as GeneratePackageBannerOptions } from "./index-DlH2PDPD.cjs";
+import { t as CommandIdentity } from "./index-BdtMQyzF.cjs";
+import { n as PatternOptions, t as PatternConfig } from "./fast-globe-options-D7S2fQZZ.cjs";
 import { ChildProcess, SpawnOptions, StdioOptions } from "node:child_process";
 import * as acorn from "acorn";
 
@@ -1464,7 +1464,7 @@ type BaseRunCommandOptions = {
   */
   env?: NodeJS.ProcessEnv;
   /** ----------------------------------------------------------------
-  * * ***Disable execution inside a system shell.***
+  * * ***Control whether the command is executed inside a system shell.***
   * ----------------------------------------------------------------
   *
   * By default, commands are executed inside a system shell:
@@ -1474,13 +1474,18 @@ type BaseRunCommandOptions = {
   * Set this option to `false` to bypass the shell and execute
   * the command directly.
   *
-  * This is useful for:
-  * - Strict argument handling.
-  * - Avoiding shell interpretation.
+  * - This is useful for:
+  *    - Strict argument handling.
+  *    - Avoiding shell interpretation.
+  *
+  *    - ⚠️ Note:
+  *        - Shell operators and advanced shell syntax (e.g. `&&`, `||`, `|`, `>`)
+  *          are **not supported**, regardless of this option.
+  *        - This utility always executes a single command with arguments.
   *
   * @default true (shell is enabled)
   */
-  shell?: false;
+  shell?: boolean;
   /** ----------------------------------------------------------------
   * * ***Abort signal for cancelling the spawned process.***
   * ----------------------------------------------------------------
@@ -1552,6 +1557,7 @@ type BaseRunCommandOptions = {
   */
   useColors?: boolean;
 } & Omit<SpawnOptions, "cwd" | "env" | "shell" | "stdio" | "argv0" | "timeout">;
+type Reason = "timeout" | "abort" | "signal" | "non-zero exit code" | "validation";
 /** ----------------------------------------------------------------
 * * ***Represents a command execution failure.***
 * ----------------------------------------------------------------
@@ -1626,7 +1632,7 @@ type BaseRunCommandOptions = {
 *   output when logged via `console.error`.
 */
 declare class CommandProcessError extends Error {
-  reason: "timeout" | "abort" | "signal" | "non-zero exit code";
+  reason: Reason;
   exitCode?: number;
   signal?: NodeJS.Signals | null;
   command: string;
@@ -1753,6 +1759,18 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 *     - Parsing results (JSON, text, etc.).
 *     - Testing and scripting utilities.
 *
+* ----------------------------------------------------------------
+* #### Limitations
+*
+* - Only a **single command** is supported.
+* - Shell syntax is **NOT allowed**, including:
+*    - `&&`, `||`
+*    - `|`
+*    - `>`, `<`
+*    - command chaining or piping of any kind
+*
+* Commands must represent a single executable with arguments.
+*
 * @param {string} command
 * The executable or command to run.
 *
@@ -1774,33 +1792,34 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 *
 * This function does NOT reject on non-zero exit codes.
 * - Instead, use:
-*    - `result.ok`.
-*    - `result.exitCode`.
+*    - `result.ok`
+*    - `result.exitCode`
 *
-* - However, the promise WILL reject for:
-*    - spawn errors.
-*    - abort signals.
-*    - timeouts.
-*    - termination by signal.
+* The promise will reject in the following cases:
+* - validation errors (invalid command or arguments)
+* - 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).
+*     - `reason` ➔ `"timeout" | "abort" | "signal" | "validation"`
+*     - `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.
+*     - 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`).
+*     - Non-zero exit codes are NOT treated as errors
+*     - Metadata is available programmatically (e.g. `err.reason`)
 *     - Metadata is also included in the formatted stack output
-*       for CLI readability.
+*       for CLI readability
 *
 * @example
 * ```ts
@@ -1824,6 +1843,7 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 * }
 * ```
 * ----------------------------------------------------------------
+*
 * @example
 * ```ts
 * const result = await runCommandCapture("node", ["--version"]);
@@ -1853,28 +1873,29 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 *
 * @remarks
 * - **Execution model:**
-*    - Uses {@link spawn | **`spawn`**} to avoid output size limits
-*      imposed by `exec`.
+*     - 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.
+*     - 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.
+*     - 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`}.
+*     - Defaults to `shell: true` for cross-platform compatibility
+*     - However, shell operators and advanced shell syntax are NOT supported
+*     - This utility always executes a single command only
 *
 * - **Abort & timeout:**
-*    - Abort signals and timeouts will terminate the process
-*      and reject the promise.
+*     - 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)
+*     - 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`}.***
 */
@@ -1909,6 +1930,18 @@ type RunCommandOptions = BaseRunCommandOptions;
 *     - CLI tooling.
 *     - Long-running tasks (bundlers, compilers, CSS processors).
 *
+* ----------------------------------------------------------------
+* #### Limitations
+*
+* - Only a **single command** is supported.
+* - Shell syntax is **NOT allowed**, including:
+*     - `&&`, `||`
+*     - `|`
+*     - `>`, `<`
+*     - command chaining or piping of any kind
+*
+* Commands must represent a single executable with arguments.
+*
 * @param {string} command
 * The executable or command to run.
 *
@@ -1929,13 +1962,13 @@ type RunCommandOptions = BaseRunCommandOptions;
 * {@link CommandProcessError | **`CommandProcessError`**}.
 *
 * - *Error metadata:*
-*     - `reason` ➔ `"timeout" | "abort" | "signal" | "non-zero exit code"`.
+*     - `reason` ➔ `"timeout" | "abort" | "signal" | "non-zero exit code" | "validation"`.
 *     - `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.
+*     - Use ***instanceof {@link CommandProcessError | **`CommandProcessError`**}*** to safely access metadata.
 *     - Or use {@link isCommandProcessError | **`isCommandProcessError`**} as a type guard.
 *
 * - *Notes:*
@@ -1966,6 +1999,7 @@ type RunCommandOptions = BaseRunCommandOptions;
 *   }
 * }
 * ```
+*
 * ----------------------------------------------------------------
 *
 * @example
@@ -2007,11 +2041,10 @@ type RunCommandOptions = BaseRunCommandOptions;
 *      - 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.
+*      - Defaults to {@link RunCommandOptions.shell | **`shell: true`**}
+*        for cross-platform compatibility (especially on Windows).
+*      - However, shell operators and advanced shell syntax are **NOT supported**.
+*      - This utility always executes a **single command only**.
 *
 * - **Abort handling:**
 *      - When `signal` is provided, the process will be terminated
@@ -2031,9 +2064,9 @@ type RunCommandOptions = BaseRunCommandOptions;
 *
 * - **When NOT to use this utility:**
 *      - When you need to capture output programmatically.
-*      - When you need advanced shell features (`|`, `>`, `&&`).
+*      - When you need advanced shell features (`|`, `>`, `&&`, piping, chaining).
 *
-* ***In those cases, consider using `exec` or a dedicated process runner.***
+* ***In those cases, use `exec` or a dedicated shell runner instead.***
 */
 declare function runCommand(command: string, args: readonly string[]): Promise<ChildProcess>;
 declare function runCommand(command: string, options: RunCommandOptions): Promise<ChildProcess>;

package/dist/index.d.ts

@@ -2,16 +2,16 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.9`
+*  Version: `0.0.11`
 *  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-DxvrBev9.js";
-import { n as generatePackageBanner, r as PackageJson, t as GeneratePackageBannerOptions } from "./index-Dvmmz0f_.js";
-import { t as CommandIdentity } from "./index-B1t7Xs3T.js";
-import { n as PatternOptions, t as PatternConfig } from "./fast-globe-options-Cz8KJqKc.js";
+import { a as OmitStrict, c as PrettifyOptions, r as DefaultPrettifyOptions, s as Prettify } from "./extra-BleSbKJp.js";
+import { n as generatePackageBanner, r as PackageJson, t as GeneratePackageBannerOptions } from "./index-CwHGSras.js";
+import { t as CommandIdentity } from "./index-NLQcJJFO.js";
+import { n as PatternOptions, t as PatternConfig } from "./fast-globe-options-DnV58KJc.js";
 import { ChildProcess, SpawnOptions, StdioOptions, spawn } from "node:child_process";
 import * as acorn from "acorn";
 
@@ -1464,7 +1464,7 @@ type BaseRunCommandOptions = {
   */
   env?: NodeJS.ProcessEnv;
   /** ----------------------------------------------------------------
-  * * ***Disable execution inside a system shell.***
+  * * ***Control whether the command is executed inside a system shell.***
   * ----------------------------------------------------------------
   *
   * By default, commands are executed inside a system shell:
@@ -1474,13 +1474,18 @@ type BaseRunCommandOptions = {
   * Set this option to `false` to bypass the shell and execute
   * the command directly.
   *
-  * This is useful for:
-  * - Strict argument handling.
-  * - Avoiding shell interpretation.
+  * - This is useful for:
+  *    - Strict argument handling.
+  *    - Avoiding shell interpretation.
+  *
+  *    - ⚠️ Note:
+  *        - Shell operators and advanced shell syntax (e.g. `&&`, `||`, `|`, `>`)
+  *          are **not supported**, regardless of this option.
+  *        - This utility always executes a single command with arguments.
   *
   * @default true (shell is enabled)
   */
-  shell?: false;
+  shell?: boolean;
   /** ----------------------------------------------------------------
   * * ***Abort signal for cancelling the spawned process.***
   * ----------------------------------------------------------------
@@ -1552,6 +1557,7 @@ type BaseRunCommandOptions = {
   */
   useColors?: boolean;
 } & Omit<SpawnOptions, "cwd" | "env" | "shell" | "stdio" | "argv0" | "timeout">;
+type Reason = "timeout" | "abort" | "signal" | "non-zero exit code" | "validation";
 /** ----------------------------------------------------------------
 * * ***Represents a command execution failure.***
 * ----------------------------------------------------------------
@@ -1626,7 +1632,7 @@ type BaseRunCommandOptions = {
 *   output when logged via `console.error`.
 */
 declare class CommandProcessError extends Error {
-  reason: "timeout" | "abort" | "signal" | "non-zero exit code";
+  reason: Reason;
   exitCode?: number;
   signal?: NodeJS.Signals | null;
   command: string;
@@ -1753,6 +1759,18 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 *     - Parsing results (JSON, text, etc.).
 *     - Testing and scripting utilities.
 *
+* ----------------------------------------------------------------
+* #### Limitations
+*
+* - Only a **single command** is supported.
+* - Shell syntax is **NOT allowed**, including:
+*    - `&&`, `||`
+*    - `|`
+*    - `>`, `<`
+*    - command chaining or piping of any kind
+*
+* Commands must represent a single executable with arguments.
+*
 * @param {string} command
 * The executable or command to run.
 *
@@ -1774,33 +1792,34 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 *
 * This function does NOT reject on non-zero exit codes.
 * - Instead, use:
-*    - `result.ok`.
-*    - `result.exitCode`.
+*    - `result.ok`
+*    - `result.exitCode`
 *
-* - However, the promise WILL reject for:
-*    - spawn errors.
-*    - abort signals.
-*    - timeouts.
-*    - termination by signal.
+* The promise will reject in the following cases:
+* - validation errors (invalid command or arguments)
+* - 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).
+*     - `reason` ➔ `"timeout" | "abort" | "signal" | "validation"`
+*     - `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.
+*     - 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`).
+*     - Non-zero exit codes are NOT treated as errors
+*     - Metadata is available programmatically (e.g. `err.reason`)
 *     - Metadata is also included in the formatted stack output
-*       for CLI readability.
+*       for CLI readability
 *
 * @example
 * ```ts
@@ -1824,6 +1843,7 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 * }
 * ```
 * ----------------------------------------------------------------
+*
 * @example
 * ```ts
 * const result = await runCommandCapture("node", ["--version"]);
@@ -1853,28 +1873,29 @@ type RunCommandCaptureOptions = Omit<BaseRunCommandOptions, "stdio">;
 *
 * @remarks
 * - **Execution model:**
-*    - Uses {@link spawn | **`spawn`**} to avoid output size limits
-*      imposed by `exec`.
+*     - 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.
+*     - 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.
+*     - 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`}.
+*     - Defaults to `shell: true` for cross-platform compatibility
+*     - However, shell operators and advanced shell syntax are NOT supported
+*     - This utility always executes a single command only
 *
 * - **Abort & timeout:**
-*    - Abort signals and timeouts will terminate the process
-*      and reject the promise.
+*     - 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)
+*     - 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`}.***
 */
@@ -1909,6 +1930,18 @@ type RunCommandOptions = BaseRunCommandOptions;
 *     - CLI tooling.
 *     - Long-running tasks (bundlers, compilers, CSS processors).
 *
+* ----------------------------------------------------------------
+* #### Limitations
+*
+* - Only a **single command** is supported.
+* - Shell syntax is **NOT allowed**, including:
+*     - `&&`, `||`
+*     - `|`
+*     - `>`, `<`
+*     - command chaining or piping of any kind
+*
+* Commands must represent a single executable with arguments.
+*
 * @param {string} command
 * The executable or command to run.
 *
@@ -1929,13 +1962,13 @@ type RunCommandOptions = BaseRunCommandOptions;
 * {@link CommandProcessError | **`CommandProcessError`**}.
 *
 * - *Error metadata:*
-*     - `reason` ➔ `"timeout" | "abort" | "signal" | "non-zero exit code"`.
+*     - `reason` ➔ `"timeout" | "abort" | "signal" | "non-zero exit code" | "validation"`.
 *     - `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.
+*     - Use ***instanceof {@link CommandProcessError | **`CommandProcessError`**}*** to safely access metadata.
 *     - Or use {@link isCommandProcessError | **`isCommandProcessError`**} as a type guard.
 *
 * - *Notes:*
@@ -1966,6 +1999,7 @@ type RunCommandOptions = BaseRunCommandOptions;
 *   }
 * }
 * ```
+*
 * ----------------------------------------------------------------
 *
 * @example
@@ -2007,11 +2041,10 @@ type RunCommandOptions = BaseRunCommandOptions;
 *      - 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.
+*      - Defaults to {@link RunCommandOptions.shell | **`shell: true`**}
+*        for cross-platform compatibility (especially on Windows).
+*      - However, shell operators and advanced shell syntax are **NOT supported**.
+*      - This utility always executes a **single command only**.
 *
 * - **Abort handling:**
 *      - When `signal` is provided, the process will be terminated
@@ -2031,9 +2064,9 @@ type RunCommandOptions = BaseRunCommandOptions;
 *
 * - **When NOT to use this utility:**
 *      - When you need to capture output programmatically.
-*      - When you need advanced shell features (`|`, `>`, `&&`).
+*      - When you need advanced shell features (`|`, `>`, `&&`, piping, chaining).
 *
-* ***In those cases, consider using `exec` or a dedicated process runner.***
+* ***In those cases, use `exec` or a dedicated shell runner instead.***
 */
 declare function runCommand(command: string, args: readonly string[]): Promise<ChildProcess>;
 declare function runCommand(command: string, options: RunCommandOptions): Promise<ChildProcess>;