tinyexec 0.3.2: NonZeroExitError

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 tinyexec.NonZeroExitError in pkg:npm/tinyexec@0.3.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyexec@0.3.2
Demonstrate these symbols/APIs:
  - tinyexec.NonZeroExitError

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:0802e0ca013ed224b97de3ef67a2261261e1729827f011534e4d1f2348a1c1ed","contract":["NonZeroExitError is exported as an Error subclass","NonZeroExitError is thrown when throwOnError is true and process exits with non-zero code","NonZeroExitError exposes exitCode matching the process exit status","NonZeroExitError exposes result and output containing stdout and stderr","NonZeroExitError can be directly instantiated with result and output objects","x does not throw NonZeroExitError when throwOnError is false or omitted","x resolves without throwing NonZeroExitError when throwOnError is true and process exits with 0"],"goal":"verify tinyexec.NonZeroExitError in pkg:npm/tinyexec@0.3.2","kind":"HOW","packages":["pkg:npm/tinyexec@0.3.2"],"schemaVersion":1,"symbols":["tinyexec.NonZeroExitError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/tinyexec@0.3.2"],"schemaVersion":1,"subject":"pkg:npm/tinyexec@0.3.2","symbols":["tinyexec.NonZeroExitError"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyexec-nonzeroexiterror",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyexec-nonzeroexiterror",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tinyexec": "0.3.2"
      }
    },
    "node_modules/tinyexec": {
      "version": "0.3.2",
      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
      "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-tinyexec-nonzeroexiterror",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of tinyexec.NonZeroExitError",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "tinyexec": "0.3.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify tinyexec.NonZeroExitError in pkg:npm/tinyexec@0.3.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyexec@0.3.2"
  ],
  "symbols": [
    "tinyexec.NonZeroExitError"
  ]
}

'use strict';

const { x, NonZeroExitError } = require('tinyexec');

/**
 * Executes a command with throwOnError enabled, throwing NonZeroExitError on non-zero exit.
 * @param {string} command - Command name or path
 * @param {string[]} [args] - Command arguments
 * @param {object} [options] - Additional options passed to x
 * @returns {Promise<import('tinyexec').Result>}
 */
async function executeStrict(command, args = [], options = {}) {
  return x(command, args, {
    ...options,
    throwOnError: true
  });
}

/**
 * Creates an instance of NonZeroExitError directly.
 * @param {object} result - ExecProcess or result object containing exitCode
 * @param {object} output - Output object containing stdout and stderr
 * @returns {NonZeroExitError}
 */
function createNonZeroExitError(result, output) {
  return new NonZeroExitError(result, output);
}

module.exports = {
  x,
  NonZeroExitError,
  executeStrict,
  createNonZeroExitError
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  x,
  NonZeroExitError,
  executeStrict,
  createNonZeroExitError
} = require('../src/index.js');

// 1. NonZeroExitError is exported as an Error subclass
assert.equal(typeof NonZeroExitError, 'function', 'NonZeroExitError must be a function/class');
assert(NonZeroExitError.prototype instanceof Error, 'NonZeroExitError must inherit from Error');

// 2. NonZeroExitError is thrown when throwOnError is true and process exits with non-zero code
await assert.rejects(
  async () => {
    await executeStrict('node', ['-e', 'process.stderr.write("failed with exit code 9"); process.exit(9);']);
  },
  (err) => {
    assert(err instanceof NonZeroExitError, 'Thrown error must be instance of NonZeroExitError');
    assert(err instanceof Error, 'Thrown error must be instance of Error');
    assert.equal(err.exitCode, 9, 'err.exitCode must match exit status');
    assert.equal(err.message, 'Process exited with non-zero status (9)');
    return true;
  }
);

// 3. NonZeroExitError exposes exitCode matching the process exit status
{
  let caught = null;
  try {
    await x('node', ['-e', 'process.exit(17);'], { throwOnError: true });
  } catch (err) {
    caught = err;
  }
  assert(caught !== null, 'Should have caught NonZeroExitError');
  assert(caught instanceof NonZeroExitError);
  assert.equal(caught.exitCode, 17);
}

// 4. NonZeroExitError exposes result and output containing stdout and stderr
{
  let caught = null;
  try {
    await x('node', ['-e', 'process.stdout.write("standard out"); process.stderr.write("standard err"); process.exit(3);'], { throwOnError: true });
  } catch (err) {
    caught = err;
  }
  assert(caught !== null, 'Should have caught NonZeroExitError');
  assert.equal(caught.result.exitCode, 3);
  assert.equal(caught.output.stdout, 'standard out');
  assert.equal(caught.output.stderr, 'standard err');
}

// 5. NonZeroExitError can be directly instantiated with result and output objects
{
  const mockResult = { exitCode: 12 };
  const mockOutput = { stdout: 'custom stdout', stderr: 'custom stderr' };
  const customErr = createNonZeroExitError(mockResult, mockOutput);
  assert(customErr instanceof NonZeroExitError);
  assert(customErr instanceof Error);
  assert.equal(customErr.exitCode, 12);
  assert.equal(customErr.result, mockResult);
  assert.equal(customErr.output, mockOutput);
  assert.equal(customErr.message, 'Process exited with non-zero status (12)');
}

// 6. x does not throw NonZeroExitError when throwOnError is false or omitted
{
  const resultDefault = await x('node', ['-e', 'process.exit(5);']);
  assert.equal(resultDefault.exitCode, 5);

  const resultExplicit = await x('node', ['-e', 'process.exit(6);'], { throwOnError: false });
  assert.equal(resultExplicit.exitCode, 6);
}

// 7. x resolves without throwing NonZeroExitError when throwOnError is true and process exits with 0
{
  const result = await executeStrict('node', ['-e', 'process.stdout.write("success"); process.exit(0);']);
  assert.equal(result.exitCode, 0);
  assert.equal(result.stdout, 'success');
}

console.log('Contract assertions passed.');