tinyexec 1.3.0: verify process execution with streaming, piping, and signal handling

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 pkg:npm/tinyexec@1.3.0 process execution with streaming, piping, and signal handling
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyexec@1.3.0
Demonstrate these symbols/APIs:
  - exec
  - x

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:f83997ae5aacde6507fc36bba314864850e08232c009d4901f6a82c70c16d3d5","contract":["x executes a process and returns stdout, stderr, and exitCode upon completion","x supports command options including custom environment variables","x returns non-zero exit codes when throwOnError is disabled","x throws NonZeroExitError on non-zero exit code when throwOnError is enabled","x pipes stdout to another process via the pipe method","x yields stdout and stderr lines via async iteration","x aborts a running process and sets aborted and killed flags when AbortSignal triggers","x terminates a running process when kill method is invoked","exec function alias behaves identically to x"],"goal":"verify pkg:npm/tinyexec@1.3.0 process execution with streaming, piping, and signal handling","kind":"HOW","packages":["pkg:npm/tinyexec@1.3.0"],"schemaVersion":1,"symbols":["exec","x"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","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@1.3.0"],"schemaVersion":1,"subject":"pkg:npm/tinyexec@1.3.0","symbols":["exec","x"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tinyexec",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tinyexec",
      "version": "1.0.0",
      "dependencies": {
        "tinyexec": "1.3.0"
      }
    },
    "node_modules/tinyexec": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.0.tgz",
      "integrity": "sha512-QKAl9m8gWWGHV8jZcPeym6j+XULi6tOf1mT83WYJ4Lk2ytW/uwAWkrP0uFsdoYMdueVJ0qs26wZ+23xeB4ibNQ==",
      "license": "MIT",
      "engines": {
        "node": ">=18"
      }
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/tinyexec@1.3.0 process execution with streaming, piping, and signal handling",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyexec@1.3.0"
  ],
  "symbols": [
    "exec",
    "x"
  ]
}

import { x, exec, xSync, execSync, NonZeroExitError, ExecProcess } from 'tinyexec';

/**
 * Execute a command asynchronously using tinyexec x.
 * @param {string} command - The command to execute
 * @param {string[]} [args] - Arguments to pass to the command
 * @param {object} [options] - Options for execution
 * @returns {import('tinyexec').Result}
 */
export function runCommand(command, args, options) {
  return x(command, args, options);
}

/**
 * Execute a command using the exec alias.
 * @param {string} command - The command to execute
 * @param {string[]} [args] - Arguments to pass to the command
 * @param {object} [options] - Options for execution
 * @returns {import('tinyexec').Result}
 */
export function runExec(command, args, options) {
  return exec(command, args, options);
}

/**
 * Execute a command synchronously using xSync.
 * @param {string} command - The command to execute
 * @param {string[]} [args] - Arguments to pass to the command
 * @param {object} [options] - Options for execution
 * @returns {import('tinyexec').SyncResult}
 */
export function runSync(command, args, options) {
  return xSync(command, args, options);
}

export { x, exec, xSync, execSync, NonZeroExitError, ExecProcess };

import assert from 'node:assert/strict';
import {
  x,
  exec,
  xSync,
  execSync,
  NonZeroExitError,
  ExecProcess,
  runCommand,
  runExec,
  runSync
} from '../src/index.js';

// 1. Export verification
assert.equal(typeof x, 'function', 'x must be exported as a function');
assert.equal(typeof exec, 'function', 'exec must be exported as a function');
assert.equal(typeof xSync, 'function', 'xSync must be exported as a function');
assert.equal(typeof execSync, 'function', 'execSync must be exported as a function');
assert.equal(typeof NonZeroExitError, 'function', 'NonZeroExitError must be exported as a class');
assert.equal(typeof ExecProcess, 'function', 'ExecProcess must be exported as a class');
assert.equal(typeof runCommand, 'function', 'runCommand helper must be exported as a function');
assert.equal(typeof runExec, 'function', 'runExec helper must be exported as a function');
assert.equal(typeof runSync, 'function', 'runSync helper must be exported as a function');

// 2. x executes a process and returns stdout, stderr, and exitCode upon completion
{
  const result = await x('node', ['-e', 'console.log("stdout message"); console.error("stderr message");']);
  assert.equal(result.exitCode, 0);
  assert.equal(result.stdout.trim(), 'stdout message');
  assert.equal(result.stderr.trim(), 'stderr message');
}

// 3. x supports command options including custom environment variables
{
  const result = await x('node', ['-e', 'console.log(process.env.SAMPLE_KEY);'], {
    nodeOptions: {
      env: {
        ...process.env,
        SAMPLE_KEY: 'contract-test-val'
      }
    }
  });
  assert.equal(result.exitCode, 0);
  assert.equal(result.stdout.trim(), 'contract-test-val');
}

// 4. x returns non-zero exit codes when throwOnError is disabled
{
  const result = await x('node', ['-e', 'process.exit(7);']);
  assert.equal(result.exitCode, 7);
}

// 5. x throws NonZeroExitError on non-zero exit code when throwOnError is enabled
{
  await assert.rejects(
    async () => {
      await x('node', ['-e', 'process.stderr.write("failure details"); process.exit(5);'], {
        throwOnError: true
      });
    },
    (err) => {
      assert(err instanceof NonZeroExitError, 'Error must be an instance of NonZeroExitError');
      assert.equal(err.exitCode, 5);
      assert.equal(err.output?.stderr, 'failure details');
      return true;
    }
  );
}

// 6. x pipes stdout to another process via the pipe method
{
  const first = x('node', ['-e', 'console.log("pipe-source-data");']);
  const second = first.pipe('node', ['-e', 'let b="";process.stdin.on("data",c=>b+=c);process.stdin.on("end",()=>console.log(b.trim().toUpperCase()));']);
  const result = await second;
  assert.equal(result.exitCode, 0);
  assert.equal(result.stdout.trim(), 'PIPE-SOURCE-DATA');
}

// 7. x yields stdout and stderr lines via async iteration
{
  const proc = x('node', ['-e', 'console.log("line-a"); console.log("line-b");']);
  const collected = [];
  for await (const line of proc) {
    collected.push(line.trim());
  }
  assert.deepEqual(collected, ['line-a', 'line-b']);
}

// 8. x aborts a running process and sets aborted and killed flags when AbortSignal triggers
{
  const controller = new AbortController();
  const proc = x('node', ['-e', 'setInterval(() => {}, 1000);'], {
    signal: controller.signal
  });

  await new Promise((resolve) => setTimeout(resolve, 50));
  controller.abort();

  await proc;
  assert.equal(proc.aborted, true);
  assert.equal(proc.killed, true);
}

// 9. x terminates a running process when kill method is invoked
{
  const proc = x('node', ['-e', 'setInterval(() => {}, 1000);']);
  await new Promise((resolve) => setTimeout(resolve, 50));
  const killed = proc.kill('SIGTERM');
  assert.equal(killed, true);
  await proc;
  assert.equal(proc.killed, true);
}

// 10. exec function alias behaves identically to x
{
  const result = await exec('node', ['-e', 'console.log("exec-alias-output");']);
  assert.equal(result.exitCode, 0);
  assert.equal(result.stdout.trim(), 'exec-alias-output');
}

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