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 tinyexec.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:
  - tinyexec.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:829adca27ee5985e1df7e85853d5a2db1ba762884a469fb5f37820fe09d26091","contract":["tinyexec exports x as a function matching the tinyexec.x API","tinyexec.x executes a process and returns stdout, stderr, and exitCode upon completion","tinyexec.x supports command options including custom environment variables","tinyexec.x returns non-zero exit codes when throwOnError is disabled","tinyexec.x throws NonZeroExitError on non-zero exit code when throwOnError is enabled","tinyexec.x pipes stdout to another process via the pipe method","tinyexec.x yields stdout and stderr lines via async iteration","tinyexec.x aborts a running process and sets aborted and killed flags when AbortSignal triggers","tinyexec.x terminates a running process when kill method is invoked"],"goal":"verify tinyexec.x in pkg:npm/tinyexec@0.3.2","kind":"HOW","packages":["pkg:npm/tinyexec@0.3.2"],"schemaVersion":1,"symbols":["tinyexec.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":["tinyexec.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.x",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "tinyexec": "0.3.2"
  }
}

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

'use strict';

const tinyexec = require('tinyexec');
const { x, NonZeroExitError } = 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}
 */
function runCommand(command, args, options) {
  return tinyexec.x(command, args, options);
}

module.exports = {
  tinyexec,
  x,
  NonZeroExitError,
  runCommand
};

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

const require = createRequire(import.meta.url);
const {
  tinyexec,
  runCommand
} = require('../src/index.js');

const { x, NonZeroExitError } = tinyexec;

// 1. tinyexec exports x as a function matching the tinyexec.x API
assert.equal(typeof tinyexec.x, 'function', 'tinyexec.x must be exported as a function');
assert.equal(typeof x, 'function', 'x must be exported as a function');
assert.equal(typeof NonZeroExitError, 'function', 'NonZeroExitError must be exported as a class');
assert.equal(typeof runCommand, 'function', 'runCommand helper must be exported as a function');

// 2. tinyexec.x executes a process and returns stdout, stderr, and exitCode upon completion
{
  const result = await tinyexec.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. tinyexec.x supports command options including custom environment variables
{
  const result = await tinyexec.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. tinyexec.x returns non-zero exit codes when throwOnError is disabled
{
  const result = await tinyexec.x('node', ['-e', 'process.exit(7);']);
  assert.equal(result.exitCode, 7);
}

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

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