tinyexec 0.3.2: x

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 x 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:
  - x
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:607727f471b6a13e97ce7a9a4163130c99d3bdfaf3432c3d443b21d6b1796d50","constraints":{"executionContext":"node"},"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 x in pkg:npm/tinyexec@0.3.2","kind":"HOW","packages":["pkg:npm/tinyexec@0.3.2"],"schemaVersion":1,"symbols":["x"]},"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":["x"],"verifierAdapter":"node-typescript@1"}

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

{
  "schemaVersion": 1,
  "goal": "verify x in pkg:npm/tinyexec@0.3.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tinyexec@0.3.2"
  ],
  "symbols": [
    "x"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

'use strict';

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

/**
 * Execute a command asynchronously using tinyexec.
 * @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}
 */
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}
 */
function runExec(command, args, options) {
  return exec(command, args, options);
}

module.exports = {
  x,
  exec,
  NonZeroExitError,
  ExecProcess,
  runCommand,
  runExec
};

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

const require = createRequire(import.meta.url);
const {
  x,
  exec,
  NonZeroExitError,
  ExecProcess,
  runCommand,
  runExec
} = require('../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 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');

// 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("item1\\nitem2\\nitem3");']);
  const second = first.pipe('grep', ['item2']);
  const result = await second;
  assert.equal(result.exitCode, 0);
  assert.equal(result.stdout.trim(), 'item2');
}

// 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, 30));
  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, 30));
  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.');