@quatrain/cli 1.1.8 → 1.1.10

package/README.md

@@ -1,60 +1,103 @@
-# @quatrain/core-cli
+# @quatrain/cli
 
-The official Command Line Interface (CLI) for the Quatrain ecosystem.
-This CLI provides tools to scaffold projects, generate normalized bootloader configurations, and create migration files.
+The official Command Line Interface (CLI) and script utility library for the Quatrain ecosystem. 
 
-## Installation
+This package serves two distinct purposes:
+1. **Programmatic Utilities (Library API):** Exported classes and prompt helpers to build interactive scripts and run system subprocesses (e.g. within agent skills).
+2. **Core Command-Line Executable (`core`):** A global terminal command runner to scaffold projects, generate configurations, and manage deployments.
 
-You can install the CLI globally via NPM or Yarn, or run it on the fly using `npx` or `bunx`.
+---
 
-### Global Installation
+## 1. Programmatic Utilities (Library API)
 
-```bash
-npm install -g @quatrain/core-cli
-# or
-yarn global add @quatrain/core-cli
-# or via Bun
-bun add -g @quatrain/core-cli
-```
+Import these utilities directly in your TypeScript/JavaScript scripts to interact with the user or run external processes.
 
-### On-the-fly Execution
+### A. Fluent Command Executor (`Command`)
 
-```bash
-npx @quatrain/core-cli <command>
-# or
-bunx @quatrain/core-cli <command>
+The `Command` class provides a cross-platform, fluent builder-pattern interface to execute system subprocesses. It simplifies spawning commands, passing arguments, setting working directories, extending environment variables, and supports PowerShell routing.
+
+```typescript
+import { Command } from '@quatrain/cli';
+
+const result = await Command.create('kubectl')
+  .arg('apply')
+  .arg('-f')
+  .arg('deployment.yaml')
+  .cwd('/path/to/project')
+  .env({ KUBECONFIG: '/path/to/config' })
+  .execute();
+
+if (result.success) {
+  console.log(`Success: ${result.stdout}`);
+} else {
+  console.error(`Exit code: ${result.code}, Error: ${result.stderr}`);
+}
 ```
 
-## Commands
+**Fluent Methods:**
+- `Command.create(bin)` / `new Command(bin)`: Start building a command for the given binary.
+- `.arg(value)` / `.args([values])`: Append command-line arguments.
+- `.cwd(dir)`: Set the execution working directory.
+- `.env({ KEY: VALUE })`: Set or extend environment variables.
+- `.inherit()`: Direct stdout and stderr to the parent process terminal.
+- `.usePowerShell(use, type)`: Force process execution through PowerShell (`powershell.exe` or `pwsh`) with safe quote escaping.
+- `.execute()`: Run the process asynchronously and return `{ stdout, stderr, code, success }`.
 
-### `core generate scaffold <project-name>`
-Quickly initializes a new Quatrain project.
-- Creates a base directory.
-- Sets up the `apps/`, `data/`, `config/`, `packages/`, and `migrations/` folders.
-- Generates a monorepo-ready `package.json` utilizing Yarn workspaces.
-- Generates a `tsconfig.json` pre-configured with the required path mappings.
+### B. Interactive Prompt Helpers
 
-### `core generate config`
-Starts an interactive wizard to generate a `quatrain.json` configuration file.
-- Prompts for Backend, Auth, Queue, Storage, and Messaging adapters.
-- Generates a normalized JSON configuration.
-- The generated `env(...)` tokens will be resolved at runtime by the `AppBootloader`.
+Helpers wrapping `inquirer` to prompt user inputs cleanly:
 
-### `core generate migration <name>`
-Scaffolds a new migration file.
-- Creates a `migrations/` directory if it does not exist.
-- Generates a timestamped TypeScript file (e.g., `20260427184500_init.ts`).
-- Provides boilerplate `up()` and `down()` methods.
+```typescript
+import { askConfirm, askInput, askChoice } from '@quatrain/cli';
 
-## Language Guidelines
-> **Recommendation:** All text contents (such as console logs, commit messages, and comments) within the Quatrain ecosystem must be written in **International English**. This ensures accessibility and maintainability for developers worldwide.
+// Yes/No Confirmations
+const proceed = await askConfirm('Do you want to deploy now?');
+
+// String Inputs
+const name = await askInput('Enter your username:', 'default_user');
+
+// Multi-choice select lists
+const selected = await askChoice('Select action:', [
+  { name: 'Sync Google Calendar', value: 'sync' },
+  { name: 'Reset Database', value: 'reset' }
+]);
+```
+
+---
+
+## 2. Core Command-Line Executable
 
-## HOWTO / Usage Examples
+A global CLI tool invoked via the `core` command (or `quatrain` depending on symlinks).
+
+### Installation
+
+Install globally or run on-the-fly:
 
 ```bash
-# Example of scaffolding a new project
-yarn global add @quatrain/core-cli
-quatrain generate scaffold my-app
-cd my-app
-yarn install
+# Global
+bun add -g @quatrain/cli
+
+# Run on the fly
+bunx @quatrain/cli <command>
 ```
+
+### Commands Reference
+
+#### `core deploy`
+Manage Kubernetes deployments (create, list, modify, promote, delete namespaces and manifests).
+
+#### `core generate scaffold <project-name>`
+Initialize a new Quatrain project structure:
+- Sets up directories: `apps/`, `data/`, `config/`, `packages/`, `migrations/`.
+- Generates a monorepo-ready workspace `package.json` and a pre-configured `tsconfig.json`.
+
+#### `core generate config`
+Start an interactive wizard to generate the `quatrain.json` bootloader configuration file.
+
+#### `core generate migration <name>`
+Scaffold a timestamped TypeScript migration file (e.g., `migrations/20260427_name.ts`) with template `up()` and `down()` blocks.
+
+---
+
+## Language Guidelines
+> **Recommendation:** All text contents (logs, console prints, commit messages, comments) within the Quatrain ecosystem must be written in **International English** to ensure global team maintainability.

package/dist/Command.d.ts

@@ -0,0 +1,25 @@
+export declare class Command {
+    private bin;
+    private argsList;
+    private workingDir?;
+    private envVars;
+    private stdoutBehavior;
+    private stderrBehavior;
+    private useShell;
+    private shellType?;
+    constructor(bin: string);
+    static create(bin: string): Command;
+    arg(value: string): this;
+    args(values: string[]): this;
+    cwd(dir: string): this;
+    env(vars: Record<string, string>): this;
+    inherit(): this;
+    usePowerShell(use?: boolean, type?: 'powershell' | 'pwsh'): this;
+    execute(): Promise<{
+        stdout: string;
+        stderr: string;
+        code: number | null;
+        success: boolean;
+    }>;
+}
+//# sourceMappingURL=Command.d.ts.map

package/dist/Command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Command.d.ts","sourceRoot":"","sources":["../src/Command.ts"],"names":[],"mappings":"AAMA,qBAAa,OAAO;IAClB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAC,CAAwB;gBAM9B,GAAG,EAAE,MAAM;IAQvB,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQnC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IASxB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAS5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAStB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAQvC,OAAO,IAAI,IAAI;IAWf,aAAa,CAAC,GAAG,UAAO,EAAE,IAAI,GAAE,YAAY,GAAG,MAAqB,GAAG,IAAI;IAUrE,OAAO,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CA4DpG"}

package/dist/Command.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = void 0;
+const node_child_process_1 = require("node:child_process");
+class Command {
+    bin;
+    argsList = [];
+    workingDir;
+    envVars = {};
+    stdoutBehavior = 'pipe';
+    stderrBehavior = 'pipe';
+    useShell = false;
+    shellType;
+    constructor(bin) {
+        this.bin = bin;
+    }
+    static create(bin) {
+        return new Command(bin);
+    }
+    arg(value) {
+        this.argsList.push(value);
+        return this;
+    }
+    args(values) {
+        this.argsList.push(...values);
+        return this;
+    }
+    cwd(dir) {
+        this.workingDir = dir;
+        return this;
+    }
+    env(vars) {
+        Object.assign(this.envVars, vars);
+        return this;
+    }
+    inherit() {
+        this.stdoutBehavior = 'inherit';
+        this.stderrBehavior = 'inherit';
+        return this;
+    }
+    usePowerShell(use = true, type = 'powershell') {
+        this.useShell = use;
+        this.shellType = type;
+        return this;
+    }
+    async execute() {
+        return new Promise((resolve, reject) => {
+            let spawnBin = this.bin;
+            let spawnArgs = [...this.argsList];
+            const isWin = process.platform === 'win32';
+            if (this.useShell || (isWin && this.shellType)) {
+                const shell = this.shellType || (isWin ? 'powershell.exe' : 'pwsh');
+                const cmdString = [this.bin, ...this.argsList]
+                    .map((arg) => {
+                    if (arg.includes(' ') || arg.includes('"') || arg.includes("'")) {
+                        return `"${arg.replace(/"/g, '`"')}"`;
+                    }
+                    return arg;
+                })
+                    .join(' ');
+                spawnBin = shell;
+                spawnArgs = ['-NoProfile', '-NonInteractive', '-Command', cmdString];
+            }
+            const child = (0, node_child_process_1.spawn)(spawnBin, spawnArgs, {
+                cwd: this.workingDir,
+                env: { ...process.env, ...this.envVars },
+                stdio: ['inherit', this.stdoutBehavior, this.stderrBehavior],
+            });
+            let stdout = '';
+            let stderr = '';
+            if (child.stdout) {
+                child.stdout.on('data', (data) => {
+                    stdout += data.toString();
+                });
+            }
+            if (child.stderr) {
+                child.stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+            }
+            child.on('close', (code) => {
+                resolve({
+                    stdout,
+                    stderr,
+                    code,
+                    success: code === 0,
+                });
+            });
+            child.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+}
+exports.Command = Command;
+//# sourceMappingURL=Command.js.map

package/dist/Command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Command.js","sourceRoot":"","sources":["../src/Command.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -9,4 +9,5 @@ export declare function askChoice<T = string>(message: string, choices: (string
 import { Command } from 'commander';
 export declare class CliCommand extends Command {
 }
+export { Command } from './Command';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAKpB,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,UAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAUrF;AAKD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpF;AAKD,wBAAsB,SAAS,CAAC,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC,EAAE,GAC/C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,qBAAa,UAAW,SAAQ,OAAO;CAAG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,UAAU,CAAC;AAEhC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAKpB,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,UAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAUrF;AAKD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpF;AAKD,wBAAsB,SAAS,CAAC,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC,EAAE,GAC/C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,qBAAa,UAAW,SAAQ,OAAO;CAAG;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CliCommand = exports.inquirer = void 0;
+exports.Command = exports.CliCommand = exports.inquirer = void 0;
 exports.askConfirm = askConfirm;
 exports.askInput = askInput;
 exports.askChoice = askChoice;
@@ -46,4 +46,6 @@ const commander_1 = require("commander");
 class CliCommand extends commander_1.Command {
 }
 exports.CliCommand = CliCommand;
+var Command_1 = require("./Command");
+Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return Command_1.Command; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAOA,gCAUC;AAKD,4BAUC;AAKD,8BAaC;AAlDD,wDAAgC;AAEvB,mBAFF,kBAAQ,CAEE;AAKV,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,UAAU,GAAG,IAAI;IACjE,MAAM,MAAM,GAAG,MAAM,kBAAQ,CAAC,MAAM,CAAC;QACnC;YACE,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,OAAO;YACb,OAAO;YACP,OAAO,EAAE,UAAU;SACpB;KACF,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAKM,KAAK,UAAU,QAAQ,CAAC,OAAe,EAAE,UAAmB;IACjE,MAAM,MAAM,GAAG,MAAM,kBAAQ,CAAC,MAAM,CAAC;QACnC;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,OAAO;YACb,OAAO;YACP,OAAO,EAAE,UAAU;SACpB;KACF,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAKM,KAAK,UAAU,SAAS,CAC7B,OAAe,EACf,OAAgD;IAEhD,MAAM,MAAM,GAAG,MAAM,kBAAQ,CAAC,MAAM,CAAC;QACnC;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,OAAO;YACb,OAAO;YACP,OAAO;SACR;KACF,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,yCAAoC;AAKpC,MAAa,UAAW,SAAQ,mBAAO;CAAG;AAA1C,gCAA0C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAOA,gCAUC;AAKD,4BAUC;AAKD,8BAaC;AAlDD,wDAAgC;AAEvB,mBAFF,kBAAQ,CAEE;AAKV,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,UAAU,GAAG,IAAI;IACjE,MAAM,MAAM,GAAG,MAAM,kBAAQ,CAAC,MAAM,CAAC;QACnC;YACE,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,OAAO;YACb,OAAO;YACP,OAAO,EAAE,UAAU;SACpB;KACF,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAKM,KAAK,UAAU,QAAQ,CAAC,OAAe,EAAE,UAAmB;IACjE,MAAM,MAAM,GAAG,MAAM,kBAAQ,CAAC,MAAM,CAAC;QACnC;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,OAAO;YACb,OAAO;YACP,OAAO,EAAE,UAAU;SACpB;KACF,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAKM,KAAK,UAAU,SAAS,CAC7B,OAAe,EACf,OAAgD;IAEhD,MAAM,MAAM,GAAG,MAAM,kBAAQ,CAAC,MAAM,CAAC;QACnC;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,OAAO;YACb,OAAO;YACP,OAAO;SACR;KACF,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,yCAAoC;AAKpC,MAAa,UAAW,SAAQ,mBAAO;CAAG;AAA1C,gCAA0C;AAE1C,qCAAoC;AAA3B,kGAAA,OAAO,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/cli",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "license": "AGPL-3.0-only",
   "description": "Quatrain Core CLI for generating configurations and migrations",
   "main": "dist/index.js",

package/src/Command.test.ts

@@ -0,0 +1,62 @@
+import { Command } from './Command';
+import path from 'node:path';
+
+describe('Command', () => {
+  test('should construct and return static instance', () => {
+    const cmd = Command.create('node');
+    expect(cmd).toBeInstanceOf(Command);
+  });
+
+  test('should execute system echo command and retrieve stdout', async () => {
+    const cmd = Command.create('echo')
+      .arg('hello world');
+
+    const result = await cmd.execute();
+    expect(result.success).toBe(true);
+    expect(result.code).toBe(0);
+    expect(result.stdout.trim()).toBe('hello world');
+  });
+
+  test('should pass environment variables correctly', async () => {
+    // Run a node script that prints the environment variable
+    const cmd = Command.create('node')
+      .args(['-e', 'console.log(process.env.TEST_VAR)'])
+      .env({ TEST_VAR: 'quatrain-cli' });
+
+    const result = await cmd.execute();
+    expect(result.success).toBe(true);
+    expect(result.stdout.trim()).toBe('quatrain-cli');
+  });
+
+  test('should execute within specified working directory', async () => {
+    const targetDir = path.resolve(__dirname);
+    const cmd = Command.create('node')
+      .args(['-e', 'console.log(process.cwd())'])
+      .cwd(targetDir);
+
+    const result = await cmd.execute();
+    expect(result.success).toBe(true);
+    // CWD returned from subprocess should match our targetDir
+    // Note: On Mac, /var/folders can resolve to /private/var/folders, so we resolve both paths
+    const resolvedPath = fsResolve(result.stdout.trim());
+    const expectedPath = fsResolve(targetDir);
+    expect(resolvedPath).toBe(expectedPath);
+  });
+
+  test('should report process failure on bad commands', async () => {
+    const cmd = Command.create('node')
+      .args(['-e', 'process.exit(5)']);
+
+    const result = await cmd.execute();
+    expect(result.success).toBe(false);
+    expect(result.code).toBe(5);
+  });
+});
+
+function fsResolve(p: string): string {
+  try {
+    return path.resolve(p);
+  } catch {
+    return p;
+  }
+}

package/src/Command.ts

@@ -0,0 +1,153 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Fluent builder for launching and managing system subprocesses.
+ * Supports cross-platform execution and shell redirection (e.g. PowerShell).
+ */
+export class Command {
+  private bin: string;
+  private argsList: string[] = [];
+  private workingDir?: string;
+  private envVars: Record<string, string> = {};
+  private stdoutBehavior: 'pipe' | 'inherit' | 'ignore' = 'pipe';
+  private stderrBehavior: 'pipe' | 'inherit' | 'ignore' = 'pipe';
+  private useShell = false;
+  private shellType?: 'powershell' | 'pwsh';
+
+  /**
+   * Instantiate a new Command.
+   * @param bin Name or path of the binary/command.
+   */
+  constructor(bin: string) {
+    this.bin = bin;
+  }
+
+  /**
+   * Static factory to instantiate a new Command.
+   * @param bin Name or path of the binary/command.
+   */
+  static create(bin: string): Command {
+    return new Command(bin);
+  }
+
+  /**
+   * Add a single command-line argument.
+   * @param value Argument string.
+   */
+  arg(value: string): this {
+    this.argsList.push(value);
+    return this;
+  }
+
+  /**
+   * Add multiple command-line arguments.
+   * @param values List of argument strings.
+   */
+  args(values: string[]): this {
+    this.argsList.push(...values);
+    return this;
+  }
+
+  /**
+   * Set the working directory for the subprocess.
+   * @param dir Absolute or relative directory path.
+   */
+  cwd(dir: string): this {
+    this.workingDir = dir;
+    return this;
+  }
+
+  /**
+   * Set or extend environment variables for the subprocess.
+   * @param vars Key-value dictionary of environment variables.
+   */
+  env(vars: Record<string, string>): this {
+    Object.assign(this.envVars, vars);
+    return this;
+  }
+
+  /**
+   * Configure the subprocess to inherit stdout and stderr from the parent process.
+   */
+  inherit(): this {
+    this.stdoutBehavior = 'inherit';
+    this.stderrBehavior = 'inherit';
+    return this;
+  }
+
+  /**
+   * Enable executing the command via PowerShell (powershell.exe or pwsh).
+   * @param use Whether to use PowerShell.
+   * @param type Shell binary choice ('powershell' or 'pwsh').
+   */
+  usePowerShell(use = true, type: 'powershell' | 'pwsh' = 'powershell'): this {
+    this.useShell = use;
+    this.shellType = type;
+    return this;
+  }
+
+  /**
+   * Execute the configured command and return a Promise resolving on process exit.
+   * @returns Promise resolving with standard output, error streams, and status.
+   */
+  async execute(): Promise<{ stdout: string; stderr: string; code: number | null; success: boolean }> {
+    return new Promise((resolve, reject) => {
+      let spawnBin = this.bin;
+      let spawnArgs = [...this.argsList];
+
+      const isWin = process.platform === 'win32';
+
+      // Route execution via PowerShell if configured or if on Windows with shellType set
+      if (this.useShell || (isWin && this.shellType)) {
+        const shell = this.shellType || (isWin ? 'powershell.exe' : 'pwsh');
+        
+        // Assemble argument list safely escaping quotes for PowerShell Command parsing
+        const cmdString = [this.bin, ...this.argsList]
+          .map((arg) => {
+            if (arg.includes(' ') || arg.includes('"') || arg.includes("'")) {
+              return `"${arg.replace(/"/g, '`"')}"`;
+            }
+            return arg;
+          })
+          .join(' ');
+
+        spawnBin = shell;
+        spawnArgs = ['-NoProfile', '-NonInteractive', '-Command', cmdString];
+      }
+
+      const child = spawn(spawnBin, spawnArgs, {
+        cwd: this.workingDir,
+        env: { ...process.env, ...this.envVars },
+        stdio: ['inherit', this.stdoutBehavior, this.stderrBehavior],
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      if (child.stdout) {
+        child.stdout.on('data', (data) => {
+          stdout += data.toString();
+        });
+      }
+
+      if (child.stderr) {
+        child.stderr.on('data', (data) => {
+          stderr += data.toString();
+        });
+      }
+
+      child.on('close', (code) => {
+        resolve({
+          stdout,
+          stderr,
+          code,
+          success: code === 0,
+        });
+      });
+
+      child.on('error', (err) => {
+        reject(err);
+      });
+    });
+  }
+}

package/src/index.ts

@@ -57,3 +57,5 @@ import { Command } from 'commander';
  */
 export class CliCommand extends Command {}
 
+export { Command } from './Command';
+