tinyexec 0.3.2: 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@0.3.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tinyexec@0.3.2
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:e0564f1f1abbbcaa89e33ae8edeed812cf7e5797ad2e4e0dd64d3b0218430bd6","contract":["exec is exported as a function that spawns a process and returns a Result","exec resolves to an output object containing stdout, stderr, and exitCode","exec populates pid and process properties upon invocation","exec passes command arguments and propagates custom environment variables","exec supports line-by-line asynchronous iteration over process output","exec pipes process stdout to another command via pipe method","exec process can be terminated using kill method","exec supports aborting via AbortSignal","exec rejects with NonZeroExitError when throwOnError is enabled on non-zero exit code"],"goal":"verify tinyexec.exec in pkg:npm/tinyexec@0.3.2","kind":"HOW","packages":["pkg:npm/tinyexec@0.3.2"],"schemaVersion":1,"symbols":["tinyexec.exec"]},"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.exec"],"verifierAdapter":"node-typescript@1"}

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

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

'use strict';

const { exec } = require('tinyexec');

/**
 * Executes a command with optional arguments and options.
 * @param {string} command - Command name or executable path
 * @param {string[]} [args] - Command arguments
 * @param {object} [options] - Execution options
 * @returns {import('tinyexec').Result}
 */
function execute(command, args, options) {
  return exec(command, args, options);
}

/**
 * Executes a command with throwOnError enabled, rejecting on non-zero exit code.
 * @param {string} command - Command name or executable path
 * @param {string[]} [args] - Command arguments
 * @param {object} [options] - Execution options
 * @returns {import('tinyexec').Result}
 */
function executeStrict(command, args, options) {
  return exec(command, args, {
    ...options,
    throwOnError: true
  });
}

/**
 * Pipes output from one command into another command using tinyexec.exec.
 * @param {string} cmd1 - First command
 * @param {string[]} args1 - First command arguments
 * @param {string} cmd2 - Second command
 * @param {string[]} args2 - Second command arguments
 * @returns {import('tinyexec').Result}
 */
function pipeCommands(cmd1, args1, cmd2, args2) {
  const proc = exec(cmd1, args1);
  return proc.pipe(cmd2, args2);
}

module.exports = {
  exec,
  execute,
  executeStrict,
  pipeCommands
};

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

const require = createRequire(import.meta.url);
const { NonZeroExitError } = require('tinyexec');
const {
  exec,
  execute,
  executeStrict,
  pipeCommands
} = require('../src/index.js');

// 1. exec is exported as a function that spawns a process and returns a Result
assert.equal(typeof exec, 'function', 'exec must be exported as a function');
assert.equal(typeof execute, 'function', 'execute helper must be exported');
assert.equal(typeof executeStrict, 'function', 'executeStrict helper must be exported');
assert.equal(typeof pipeCommands, 'function', 'pipeCommands helper must be exported');

// 2. exec resolves to an output object containing stdout, stderr, and exitCode
{
  const result = await exec(process.execPath, [
    '-e',
    'process.stdout.write("hello stdout"); process.stderr.write("hello stderr");'
  ]);
  assert.equal(result.stdout, 'hello stdout', 'stdout must match expected output');
  assert.equal(result.stderr, 'hello stderr', 'stderr must match expected output');
  assert.equal(result.exitCode, 0, 'exitCode must be 0');
}

// 3. exec populates pid and process properties upon invocation
{
  const proc = exec(process.execPath, ['-e', 'process.stdout.write("pid check");']);
  assert.notEqual(proc.process, undefined, 'proc.process must be defined immediately');
  assert.equal(typeof proc.pid, 'number', 'proc.pid must be a number');
  assert(proc.pid > 0, 'proc.pid must be positive');
  assert.equal(proc.aborted, false, 'proc.aborted must initially be false');
  assert.equal(proc.killed, false, 'proc.killed must initially be false');
  const result = await proc;
  assert.equal(result.stdout, 'pid check');
}

// 4. exec passes command arguments and propagates custom environment variables
{
  const proc = exec(
    process.execPath,
    ['-e', 'process.stdout.write(process.argv[1] + ":" + process.env.CSX_TEST_VAR);', 'ARG1'],
    {
      nodeOptions: {
        env: {
          ...process.env,
          CSX_TEST_VAR: 'TEST_SUCCESS'
        }
      }
    }
  );
  const result = await proc;
  assert.equal(result.stdout, 'ARG1:TEST_SUCCESS', 'args and env must be passed correctly');
  assert.equal(result.exitCode, 0);
}

// 5. exec supports line-by-line asynchronous iteration over process output
{
  const proc = exec(process.execPath, [
    '-e',
    'console.log("line-one"); console.log("line-two"); console.log("line-three");'
  ]);
  const lines = [];
  for await (const line of proc) {
    lines.push(line.trim());
  }
  assert.deepEqual(lines, ['line-one', 'line-two', 'line-three'], 'async iterator must yield each line');
}

// 6. exec pipes process stdout to another command via pipe method
{
  const piped = pipeCommands(
    process.execPath,
    ['-e', 'process.stdout.write("lowercase text");'],
    process.execPath,
    [
      '-e',
      'let buf = ""; process.stdin.on("data", (d) => { buf += d; }); process.stdin.on("end", () => { process.stdout.write(buf.toUpperCase()); });'
    ]
  );
  const result = await piped;
  assert.equal(result.stdout, 'LOWERCASE TEXT', 'piped command must transform input');
  assert.equal(result.exitCode, 0);
}

// 7. exec process can be terminated using kill method
{
  const proc = exec(process.execPath, ['-e', 'setInterval(() => {}, 1000);']);
  await new Promise((resolve) => setTimeout(resolve, 30));
  const killed = proc.kill('SIGTERM');
  assert.equal(killed, true, 'proc.kill() must return true');
  await proc;
  assert.equal(proc.killed, true, 'proc.killed must be true');
}

// 8. exec supports aborting via AbortSignal
{
  const controller = new AbortController();
  const proc = exec(
    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. exec rejects with NonZeroExitError when throwOnError is enabled on non-zero exit code
{
  await assert.rejects(
    async () => {
      await executeStrict(process.execPath, [
        '-e',
        'process.stderr.write("deliberate-err"); process.exit(42);'
      ]);
    },
    (err) => {
      assert(err instanceof NonZeroExitError, 'must reject with NonZeroExitError');
      assert.equal(err.exitCode, 42, 'exitCode must match 42');
      assert.equal(err.output?.stderr, 'deliberate-err', 'stderr must match');
      return true;
    }
  );
}

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