@quatrain/cli 1.1.8 → 1.1.9

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.9",
   "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';
+