tinyexec 0.3.2: ExecProcess

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.ExecProcess 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.ExecProcess

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:1151557cf404df5c40d4098c2d6a4ae12b68e5fc854fa3f8a06d8a0270249a5b","contract":["ExecProcess constructor creates an unspawned process where process and pid are undefined","ExecProcess spawn launches the process and populates process object and pid","ExecProcess resolves with stdout, stderr, and exitCode when awaited","ExecProcess streams output line by line via Symbol.asyncIterator","ExecProcess pipe method chains stdout to another command stdin","ExecProcess kill method terminates the underlying child process","ExecProcess aborts with aborted and killed flags when AbortSignal fires","ExecProcess rejects with NonZeroExitError when throwOnError is enabled on non-zero exit"],"goal":"verify tinyexec.ExecProcess in pkg:npm/tinyexec@0.3.2","kind":"HOW","packages":["pkg:npm/tinyexec@0.3.2"],"schemaVersion":1,"symbols":["tinyexec.ExecProcess"]},"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.ExecProcess"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyexec-execprocess",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyexec-execprocess",
      "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-execprocess",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of tinyexec.ExecProcess",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "tinyexec": "0.3.2"
  }
}

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

'use strict';

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

/**
 * Creates an unspawned ExecProcess instance.
 * @param {string} command - Command name or path
 * @param {string[]} [args] - Command arguments
 * @param {object} [options] - Process execution options
 * @returns {ExecProcess}
 */
function createProcess(command, args, options) {
  return new ExecProcess(command, args, options);
}

/**
 * Creates and immediately spawns an ExecProcess.
 * @param {string} command - Command name or path
 * @param {string[]} [args] - Command arguments
 * @param {object} [options] - Process execution options
 * @returns {ExecProcess}
 */
function spawnProcess(command, args, options) {
  const proc = new ExecProcess(command, args, options);
  proc.spawn();
  return proc;
}

module.exports = {
  ExecProcess,
  NonZeroExitError,
  createProcess,
  spawnProcess
};

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

const require = createRequire(import.meta.url);
const {
  ExecProcess,
  NonZeroExitError,
  createProcess,
  spawnProcess
} = require('../src/index.js');

// 1. Export type verification
assert.equal(typeof ExecProcess, 'function', 'ExecProcess must be exported as a constructor/class');
assert.equal(typeof NonZeroExitError, 'function', 'NonZeroExitError must be exported as an error class');
assert.equal(typeof createProcess, 'function', 'createProcess helper must be exported');
assert.equal(typeof spawnProcess, 'function', 'spawnProcess helper must be exported');

// 2. ExecProcess constructor creates an unspawned process where process and pid are undefined
{
  const proc = createProcess(process.execPath, ['-e', 'process.stdout.write("hello-init");']);
  assert.equal(proc.process, undefined, 'process must be undefined before spawn');
  assert.equal(proc.pid, undefined, 'pid must be undefined before spawn');
  assert.equal(proc.exitCode, undefined, 'exitCode must be undefined before spawn');
  assert.equal(proc.aborted, false, 'aborted must be false before spawn');
  assert.equal(proc.killed, false, 'killed must be false before spawn');
}

// 3. ExecProcess spawn launches the process and populates process object and pid
{
  const proc = createProcess(process.execPath, ['-e', 'process.stdout.write("hello-spawned");']);
  proc.spawn();
  assert.notEqual(proc.process, undefined, 'process must be populated after spawn');
  assert.equal(typeof proc.pid, 'number', 'pid must be a number after spawn');
  assert(proc.pid > 0, 'pid must be positive');

  const output = await proc;
  assert.equal(output.stdout, 'hello-spawned', 'stdout must match expected output');
  assert.equal(output.exitCode, 0, 'exitCode must be 0');
}

// 4. ExecProcess resolves with stdout, stderr, and exitCode when awaited
{
  const proc = spawnProcess(process.execPath, [
    '-e',
    'process.stdout.write("standard-out"); process.stderr.write("standard-err");'
  ]);
  const output = await proc;
  assert.equal(output.stdout, 'standard-out', 'stdout must match');
  assert.equal(output.stderr, 'standard-err', 'stderr must match');
  assert.equal(output.exitCode, 0, 'exitCode must be 0');
  assert.equal(proc.exitCode, 0, 'proc.exitCode getter must return 0');
}

// 5. ExecProcess streams output line by line via Symbol.asyncIterator
{
  const proc = spawnProcess(process.execPath, [
    '-e',
    'console.log("chunk-1"); console.log("chunk-2");'
  ]);
  const lines = [];
  for await (const line of proc) {
    lines.push(line.trim());
  }
  assert.deepEqual(lines, ['chunk-1', 'chunk-2'], 'async iterator must yield all lines');
}

// 6. ExecProcess pipe method chains stdout to another command stdin
{
  const first = spawnProcess(process.execPath, [
    '-e',
    'console.log("alpha\\nbeta\\ngamma");'
  ]);
  const piped = first.pipe(process.execPath, [
    '-e',
    'let data = ""; process.stdin.on("data", (d) => data += d); process.stdin.on("end", () => process.stdout.write(data.toUpperCase()));'
  ]);
  const result = await piped;
  assert.equal(result.exitCode, 0, 'piped process exitCode must be 0');
  assert.equal(result.stdout.trim(), 'ALPHA\nBETA\nGAMMA', 'piped process must process stdin');
}

// 7. ExecProcess kill method terminates the underlying child process
{
  const proc = spawnProcess(process.execPath, ['-e', 'setInterval(() => {}, 1000);']);
  await new Promise((resolve) => setTimeout(resolve, 30));
  const killed = proc.kill('SIGTERM');
  assert.equal(killed, true, 'kill must return true on success');
  await proc;
  assert.equal(proc.killed, true, 'proc.killed must be true');
}

// 8. ExecProcess aborts with aborted and killed flags when AbortSignal fires
{
  const controller = new AbortController();
  const proc = spawnProcess(process.execPath, ['-e', 'setInterval(() => {}, 1000);'], {
    signal: controller.signal
  });
  await new Promise((resolve) => setTimeout(resolve, 30));
  controller.abort();
  await proc;
  assert.equal(proc.aborted, true, 'proc.aborted must be true after abort signal');
  assert.equal(proc.killed, true, 'proc.killed must be true after abort signal');
}

// 9. ExecProcess rejects with NonZeroExitError when throwOnError is enabled on non-zero exit
{
  await assert.rejects(
    async () => {
      const proc = spawnProcess(
        process.execPath,
        ['-e', 'process.stderr.write("explicit-failure"); process.exit(9);'],
        { throwOnError: true }
      );
      await proc;
    },
    (err) => {
      assert(err instanceof NonZeroExitError, 'must reject with NonZeroExitError instance');
      assert.equal(err.exitCode, 9, 'error exitCode must match');
      assert.equal(err.output?.stderr, 'explicit-failure', 'error stderr must match');
      return true;
    }
  );
}

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