@malept/cross-spawn-promise 2.0.0: ExitCodeError

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @malept/cross-spawn-promise.ExitCodeError in pkg:npm/%40malept/cross-spawn-promise@2.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40malept/cross-spawn-promise@2.0.0
Demonstrate these symbols/APIs:
  - @malept/cross-spawn-promise.ExitCodeError

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:60cf4a5a0d5bb59101442c11603ea03211e26bab4e8e305f8e7b89208afa5cc9","contract":["assert ExitCodeError inherits from ExitError and Error","assert ExitCodeError constructor stores cmd, args, code, stdout, and stderr properties","assert ExitCodeError formats error message with non-zero exit code and command line details","assert spawn rejects with an ExitCodeError instance when spawned command exits non-zero","assert ExitCodeError from rejected spawn preserves exact non-zero exit code, stdout, and stderr","assert spawn resolves standard output string when process exits with code 0"],"goal":"verify @malept/cross-spawn-promise.ExitCodeError in pkg:npm/%40malept/cross-spawn-promise@2.0.0","kind":"HOW","packages":["pkg:npm/%40malept/cross-spawn-promise@2.0.0"],"schemaVersion":1,"symbols":["@malept/cross-spawn-promise.ExitCodeError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40malept/cross-spawn-promise@2.0.0"],"schemaVersion":1,"subject":"pkg:npm/%40malept/cross-spawn-promise@2.0.0","symbols":["@malept/cross-spawn-promise.ExitCodeError"],"verifierAdapter":"node-typescript@1"}

import { spawn, ExitCodeError, ExitError } from '@malept/cross-spawn-promise';

export { spawn, ExitCodeError, ExitError };

/**
 * Executes a command and captures any ExitCodeError thrown when the process exits non-zero.
 *
 * @param {string} cmd
 * @param {string[]} [args]
 * @param {object} [options]
 * @returns {Promise<{ success: boolean, stdout?: string, error?: ExitCodeError }>}
 */
export async function runCommandSafe(cmd, args, options) {
  try {
    const stdout = await spawn(cmd, args, options);
    return { success: true, stdout };
  } catch (err) {
    if (err instanceof ExitCodeError) {
      return { success: false, error: err };
    }
    throw err;
  }
}

/**
 * Creates an instance of ExitCodeError directly.
 *
 * @param {string} cmd
 * @param {string[]} args
 * @param {number} code
 * @param {string} stdout
 * @param {string} stderr
 * @returns {ExitCodeError}
 */
export function createExitCodeError(cmd, args, code, stdout, stderr) {
  return new ExitCodeError(cmd, args, code, stdout, stderr);
}

{
  "name": "sample-malept-cross-spawn-promise-exit-code-error",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-malept-cross-spawn-promise-exit-code-error",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@malept/cross-spawn-promise": "2.0.0"
      }
    },
    "node_modules/@malept/cross-spawn-promise": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/@malept/cross-spawn-promise/-/cross-spawn-promise-2.0.0.tgz",
      "integrity": "sha512-1DpKU0Z5ThltBwjNySMC14g0CkbyhCaz9FkhxqNsZI6uAPJXFS8cMXlBKo26FJ8ZuW6S9GCMcR9IO5k2X5/9Fg==",
      "license": "Apache-2.0",
      "dependencies": {
        "cross-spawn": "^7.0.1"
      },
      "engines": {
        "node": ">= 12.13.0"
      }
    },
    "node_modules/cross-spawn": {
      "version": "7.0.6",
      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
      "license": "MIT",
      "dependencies": {
        "path-key": "^3.1.0",
        "shebang-command": "^2.0.0",
        "which": "^2.0.1"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/isexe": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
      "license": "ISC"
    },
    "node_modules/path-key": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/shebang-command": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
      "license": "MIT",
      "dependencies": {
        "shebang-regex": "^3.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/shebang-regex": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/which": {
      "version": "2.0.2",
      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
      "license": "ISC",
      "dependencies": {
        "isexe": "^2.0.0"
      },
      "bin": {
        "node-which": "bin/node-which"
      },
      "engines": {
        "node": ">= 8"
      }
    }
  }
}

{
  "name": "sample-malept-cross-spawn-promise-exit-code-error",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "dependencies": {
    "@malept/cross-spawn-promise": "2.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @malept/cross-spawn-promise.ExitCodeError in pkg:npm/%40malept/cross-spawn-promise@2.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40malept/cross-spawn-promise@2.0.0"
  ],
  "symbols": [
    "@malept/cross-spawn-promise.ExitCodeError"
  ]
}

import assert from 'node:assert/strict';
import {
  spawn,
  ExitCodeError,
  ExitError,
  runCommandSafe,
  createExitCodeError,
} from '../index.js';

// 1. assert ExitCodeError inherits from ExitError and Error
assert.equal(typeof ExitCodeError, 'function');
assert.ok(ExitCodeError.prototype instanceof ExitError);
assert.ok(ExitCodeError.prototype instanceof Error);

// 2. assert ExitCodeError constructor stores cmd, args, code, stdout, and stderr properties
const directErr = createExitCodeError('sample-cmd', ['--flag', 'value'], 42, 'sample stdout', 'sample stderr');
assert.ok(directErr instanceof ExitCodeError);
assert.ok(directErr instanceof ExitError);
assert.ok(directErr instanceof Error);
assert.equal(directErr.cmd, 'sample-cmd');
assert.deepEqual(directErr.args, ['--flag', 'value']);
assert.equal(directErr.code, 42);
assert.equal(directErr.stdout, 'sample stdout');
assert.equal(directErr.stderr, 'sample stderr');

// 3. assert ExitCodeError formats error message with non-zero exit code and command line details
assert.match(directErr.message, /Command failed with a non-zero return code \(42\)/);
assert.match(directErr.message, /sample-cmd --flag value/);
assert.match(directErr.message, /sample stdout/);
assert.match(directErr.message, /sample stderr/);

// 4. assert spawn rejects with an ExitCodeError instance when spawned command exits non-zero
const failedResult = await runCommandSafe(process.execPath, [
  '-e',
  'process.stdout.write("custom stdout"); process.stderr.write("custom stderr"); process.exit(9);',
]);
assert.equal(failedResult.success, false);
assert.ok(failedResult.error instanceof ExitCodeError);
assert.ok(failedResult.error instanceof ExitError);

// 5. assert ExitCodeError from rejected spawn preserves exact non-zero exit code, stdout, and stderr
assert.equal(failedResult.error.code, 9);
assert.equal(failedResult.error.cmd, process.execPath);
assert.equal(failedResult.error.stdout, 'custom stdout');
assert.equal(failedResult.error.stderr, 'custom stderr');
assert.match(failedResult.error.message, /Command failed with a non-zero return code \(9\)/);

// 6. assert spawn resolves standard output string when process exits with code 0
const successResult = await runCommandSafe(process.execPath, [
  '-e',
  'process.stdout.write("process succeeded"); process.exit(0);',
]);
assert.equal(successResult.success, true);
assert.equal(successResult.stdout, 'process succeeded');

console.log('All ExitCodeError contract assertions passed.');