tar-stream 2.2.0

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/tar-stream@2.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar-stream@2.2.0
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:50cd82b432dff508af3376261c2d368b7574c936f4b9b08e8f537629e8561e19","constraints":{"executionContext":"node"},"contract":["pack.entry appends a file entry with header metadata and content buffer, emitting valid tar chunks until finalize","extract parses entries from a tar stream emitting entry events with header info and readable content stream","pack and extract roundtrip preserves multiple entries with directory, binary payload, and file permissions","pack.entry returns a writable stream when no data is provided, allowing streaming content into the entry","pack.entry throws an error when called while another entry stream is still piping","extract emits an error when supplied with invalid or corrupted tar stream data"],"goal":"verify pkg:npm/tar-stream@2.2.0","kind":"HOW","packages":["pkg:npm/tar-stream@2.2.0"],"schemaVersion":1},"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/tar-stream@2.2.0"],"schemaVersion":1,"subject":"pkg:npm/tar-stream@2.2.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-stream",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-stream",
      "version": "1.0.0",
      "dependencies": {
        "tar-stream": "2.2.0"
      }
    },
    "node_modules/base64-js": {
      "version": "1.5.1",
      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/bl": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
      "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
      "license": "MIT",
      "dependencies": {
        "buffer": "^5.5.0",
        "inherits": "^2.0.4",
        "readable-stream": "^3.4.0"
      }
    },
    "node_modules/buffer": {
      "version": "5.7.1",
      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "base64-js": "^1.3.1",
        "ieee754": "^1.1.13"
      }
    },
    "node_modules/end-of-stream": {
      "version": "1.4.5",
      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
      "license": "MIT",
      "dependencies": {
        "once": "^1.4.0"
      }
    },
    "node_modules/fs-constants": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
      "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
      "license": "MIT"
    },
    "node_modules/ieee754": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "BSD-3-Clause"
    },
    "node_modules/inherits": {
      "version": "2.0.4",
      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
      "license": "ISC"
    },
    "node_modules/once": {
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
      "license": "ISC",
      "dependencies": {
        "wrappy": "1"
      }
    },
    "node_modules/readable-stream": {
      "version": "3.6.2",
      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
      "license": "MIT",
      "dependencies": {
        "inherits": "^2.0.3",
        "string_decoder": "^1.1.1",
        "util-deprecate": "^1.0.1"
      },
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/safe-buffer": {
      "version": "5.2.1",
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/string_decoder": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
      "license": "MIT",
      "dependencies": {
        "safe-buffer": "~5.2.0"
      }
    },
    "node_modules/tar-stream": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
      "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
      "license": "MIT",
      "dependencies": {
        "bl": "^4.0.3",
        "end-of-stream": "^1.4.1",
        "fs-constants": "^1.0.0",
        "inherits": "^2.0.3",
        "readable-stream": "^3.1.1"
      },
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
      "license": "MIT"
    },
    "node_modules/wrappy": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-tar-stream",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "tar-stream": "2.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/tar-stream@2.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tar-stream@2.2.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import tar from 'tar-stream';

// 1. pack.entry appends a file entry with header metadata and content buffer, emitting valid tar chunks until finalize
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const chunks = [];

	pack.on('data', (chunk) => chunks.push(chunk));
	pack.on('end', () => {
		try {
			const tarBuffer = Buffer.concat(chunks);
			assert.ok(tarBuffer.length > 0);
			assert.equal(tarBuffer.length % 512, 0);
			resolve();
		} catch (err) {
			reject(err);
		}
	});
	pack.on('error', reject);

	pack.entry(
		{ name: 'hello.txt', size: 11, mtime: new Date(1700000000000) },
		'hello world',
		(err) => {
			if (err) return reject(err);
			pack.finalize();
		},
	);
});

// 2. extract parses entries from a tar stream emitting entry events with header info and readable content stream
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	let entryReceived = false;

	extract.on('entry', (header, stream, next) => {
		const chunks = [];
		stream.on('data', (chunk) => chunks.push(chunk));
		stream.on('end', () => {
			try {
				assert.equal(header.name, 'test.txt');
				assert.equal(Buffer.concat(chunks).toString('utf8'), 'sample content');
				entryReceived = true;
				next();
			} catch (err) {
				reject(err);
			}
		});
		stream.resume();
	});

	extract.on('finish', () => {
		try {
			assert.equal(entryReceived, true);
			resolve();
		} catch (err) {
			reject(err);
		}
	});
	extract.on('error', reject);

	pack.pipe(extract);
	pack.entry({ name: 'test.txt' }, 'sample content', (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 3. pack and extract roundtrip preserves multiple entries with directory, binary payload, and file permissions
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();
	const entries = [];

	extract.on('entry', (header, stream, next) => {
		const chunks = [];
		stream.on('data', (chunk) => chunks.push(chunk));
		stream.on('end', () => {
			entries.push({
				header,
				data: Buffer.concat(chunks),
			});
			next();
		});
		stream.resume();
	});

	extract.on('finish', () => {
		try {
			assert.equal(entries.length, 3);

			assert.equal(entries[0].header.name, 'dir/');
			assert.equal(entries[0].header.type, 'directory');
			assert.equal(entries[0].data.length, 0);

			assert.equal(entries[1].header.name, 'dir/file.bin');
			assert.equal(entries[1].header.type, 'file');
			assert.equal(entries[1].header.mode & 0o777, 0o644);
			assert.deepEqual(entries[1].data, Buffer.from([1, 2, 3, 4, 5]));

			assert.equal(entries[2].header.name, 'script.sh');
			assert.equal(entries[2].header.type, 'file');
			assert.equal(entries[2].header.mode & 0o777, 0o755);
			assert.equal(entries[2].data.toString('utf8'), '#!/bin/sh\necho ok\n');

			resolve();
		} catch (err) {
			reject(err);
		}
	});
	extract.on('error', reject);

	pack.pipe(extract);

	pack.entry({ name: 'dir/', type: 'directory', mode: 0o755 });
	pack.entry(
		{ name: 'dir/file.bin', mode: 0o644 },
		Buffer.from([1, 2, 3, 4, 5]),
	);
	pack.entry(
		{ name: 'script.sh', mode: 0o755 },
		'#!/bin/sh\necho ok\n',
		(err) => {
			if (err) return reject(err);
			pack.finalize();
		},
	);
});

// 4. pack.entry returns a writable stream when no data is provided, allowing streaming content into the entry
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	extract.on('entry', (header, stream, next) => {
		const chunks = [];
		stream.on('data', (chunk) => chunks.push(chunk));
		stream.on('end', () => {
			try {
				assert.equal(header.name, 'streamed.txt');
				assert.equal(Buffer.concat(chunks).toString('utf8'), 'streamed file data');
				next();
			} catch (err) {
				reject(err);
			}
		});
		stream.resume();
	});

	extract.on('finish', resolve);
	extract.on('error', reject);

	pack.pipe(extract);

	const entryStream = pack.entry({ name: 'streamed.txt', size: 18 }, (err) => {
		if (err) return reject(err);
		pack.finalize();
	});

	entryStream.write('streamed ');
	entryStream.end('file data');
});

// 5. pack.entry throws an error when called while another entry stream is still piping
{
	const pack = tar.pack();
	pack.entry({ name: 'first.txt', size: 10 });
	assert.throws(
		() => {
			pack.entry({ name: 'second.txt', size: 5 });
		},
		{
			name: 'Error',
			message: /already piping an entry/,
		},
	);
}

// 6. extract emits an error when supplied with invalid or corrupted tar stream data
await new Promise((resolve, reject) => {
	const extract = tar.extract();

	extract.on('error', (err) => {
		try {
			assert.ok(err instanceof Error);
			assert.match(err.message, /Invalid tar header/);
			resolve();
		} catch (e) {
			reject(e);
		}
	});

	// Write 512 bytes of invalid header data with corrupted magic and checksum
	const corruptHeader = Buffer.alloc(512, 0xff);
	extract.write(corruptHeader);
});