tinyexec 1.3.0: exec

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

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

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:3bd387014bcb835a038559cce470aa1a98af0055859481aa48e5f4b0f3a8f375","contract":["exec is exported as a function from tinyexec","exec executes a command asynchronously and returns stdout, stderr, and exitCode","exec passes command arguments and propagates custom environment variables","exec returns non-zero exit codes when throwOnError is false","exec throws NonZeroExitError on non-zero exit code when throwOnError is true","exec pipes stdout to another process via the pipe method","exec yields stdout lines via async iteration","exec aborts a running process and sets aborted and killed flags when AbortSignal triggers","exec terminates a running process when kill method is invoked"],"goal":"verify tinyexec.exec in pkg:npm/tinyexec@1.3.0","kind":"HOW","packages":["pkg:npm/tinyexec@1.3.0"],"schemaVersion":1,"symbols":["tinyexec.exec"]},"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":["tinyexec.exec"],"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.exec in pkg:npm/tinyexec@1.3.0",
  "type": "module",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "tinyexec": "1.3.0"
  }
}

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

import { exec, NonZeroExitError, ExecProcess } from 'tinyexec';

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

export { exec, NonZeroExitError, ExecProcess };

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

// 1. exec is exported as a function from tinyexec
assert.equal(typeof exec, 'function', 'exec must be exported as a function');
assert.equal(typeof runExec, 'function', 'runExec helper 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');

// 2. exec executes a command asynchronously and returns stdout, stderr, and exitCode
{
  const result = await exec('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. exec passes command arguments and propagates custom environment variables
{
  const result = await exec('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. exec returns non-zero exit codes when throwOnError is false
{
  const result = await exec('node', ['-e', 'process.exit(7);']);
  assert.equal(result.exitCode, 7);
}

// 5. exec throws NonZeroExitError on non-zero exit code when throwOnError is true
{
  await assert.rejects(
    async () => {
      await exec('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. exec pipes stdout to another process via the pipe method
{
  const first = exec('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. exec yields stdout lines via async iteration
{
  const proc = exec('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. exec aborts a running process and sets aborted and killed flags when AbortSignal triggers
{
  const controller = new AbortController();
  const proc = exec('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. exec terminates a running process when kill method is invoked
{
  const proc = exec('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);
}

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