tar-stream 3.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@3.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar-stream@3.2.0

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:49c95e3ee22fba44b3c28a34ea2efdeebaa8b44e5d9b7423f702e4cbc4a14ea4","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 files with custom modes, sizes, and binary payloads","extract supports async iteration over entries yielding readable entry streams with headers","pack.entry throws an error when called on a finalized pack stream","extract emits an error when supplied with invalid or corrupted tar stream data"],"goal":"verify pkg:npm/tar-stream@3.2.0","kind":"HOW","packages":["pkg:npm/tar-stream@3.2.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/tar-stream@3.2.0"],"schemaVersion":1,"subject":"pkg:npm/tar-stream@3.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": "3.2.0"
      }
    },
    "node_modules/b4a": {
      "version": "1.8.1",
      "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.1.tgz",
      "integrity": "sha512-aiqre1Nr0B/6DgE2N5vwTc+2/oQZ4Wh1t4NznYY4E00y8LCt6NqdRv81so00oo27D8MVKTpUa/MwUUtBLXCoDw==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "react-native-b4a": "*"
      },
      "peerDependenciesMeta": {
        "react-native-b4a": {
          "optional": true
        }
      }
    },
    "node_modules/bare-events": {
      "version": "2.9.1",
      "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.9.1.tgz",
      "integrity": "sha512-Z0oHEHAFDZkffN8Qc39zNZjQlMDkPJRyyyZieU1VH7u8c5S+qHZ2S8ixdKIAxEjfHO7FJxXmJWgteOghVanIsg==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "bare-abort-controller": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        }
      }
    },
    "node_modules/bare-fs": {
      "version": "4.8.0",
      "resolved": "https://registry.npmjs.org/bare-fs/-/bare-fs-4.8.0.tgz",
      "integrity": "sha512-fM+MhCvdQhZ7NV6S95a07gPSqjIYKn6mFaXfx266wN3ajZGl/+1AzH+ubkXQ0fFZvOe2nk9VHkzdYkQE5zMV3Q==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-events": "^2.5.4",
        "bare-path": "^3.0.0",
        "bare-stream": "^2.6.4",
        "bare-url": "^2.2.2",
        "fast-fifo": "^1.3.2"
      },
      "engines": {
        "bare": ">=1.28.0"
      },
      "peerDependencies": {
        "bare-buffer": "*"
      },
      "peerDependenciesMeta": {
        "bare-buffer": {
          "optional": true
        }
      }
    },
    "node_modules/bare-path": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/bare-path/-/bare-path-3.1.1.tgz",
      "integrity": "sha512-JprUlveX3QjApC1cTpsUOiscADftCGVWkzitbHsRqv84hzYwYHw2mbluddsq5TvI8mH/8Ov1f4BiMAdcB0oYnQ==",
      "license": "Apache-2.0"
    },
    "node_modules/bare-stream": {
      "version": "2.13.3",
      "resolved": "https://registry.npmjs.org/bare-stream/-/bare-stream-2.13.3.tgz",
      "integrity": "sha512-Kc+brLqvEqGkjyfiwJmImAOqLZL7OsoLKuavx+hJjgVV3nLTOjloJyPMFxjUPerGGHrNH0fLU06jjykMLWrERQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "b4a": "^1.8.1",
        "streamx": "^2.25.0",
        "teex": "^1.0.1"
      },
      "peerDependencies": {
        "bare-abort-controller": "*",
        "bare-buffer": "*",
        "bare-events": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        },
        "bare-buffer": {
          "optional": true
        },
        "bare-events": {
          "optional": true
        }
      }
    },
    "node_modules/bare-url": {
      "version": "2.5.2",
      "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.5.2.tgz",
      "integrity": "sha512-L13PCJzKG8RGvx8V1/DdMi12ERhC3tprr7/8a94BxpmnRsFqxh5XZNdhtMxu5HPkRshYOOWRGY8lDP7ZhpG9Cg==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-path": "^3.0.0"
      }
    },
    "node_modules/events-universal": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/events-universal/-/events-universal-1.0.1.tgz",
      "integrity": "sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-events": "^2.7.0"
      }
    },
    "node_modules/fast-fifo": {
      "version": "1.3.2",
      "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz",
      "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==",
      "license": "MIT"
    },
    "node_modules/streamx": {
      "version": "2.28.0",
      "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.28.0.tgz",
      "integrity": "sha512-1Yowhzjf0ivGMrTIkY9hav5TxobO9qIVqUE41fiCGMGgc3CLlf4MY+9AHmZqBWgDTue0fY9zWjYFVyf6Diuobw==",
      "license": "MIT",
      "dependencies": {
        "events-universal": "^1.0.0",
        "fast-fifo": "^1.3.2",
        "text-decoder": "^1.1.0"
      }
    },
    "node_modules/tar-stream": {
      "version": "3.2.0",
      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.2.0.tgz",
      "integrity": "sha512-ojzvCvVaNp6aOTFmG7jaRD0meowIAuPc3cMMhSgKiVWws1GyHbGd/xvnyuRKcKlMpt3qvxx6r0hreCNITP9hIg==",
      "license": "MIT",
      "dependencies": {
        "b4a": "^1.6.4",
        "bare-fs": "^4.5.5",
        "fast-fifo": "^1.2.0",
        "streamx": "^2.15.0"
      }
    },
    "node_modules/teex": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/teex/-/teex-1.0.1.tgz",
      "integrity": "sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==",
      "license": "MIT",
      "dependencies": {
        "streamx": "^2.12.5"
      }
    },
    "node_modules/text-decoder": {
      "version": "1.2.7",
      "resolved": "https://registry.npmjs.org/text-decoder/-/text-decoder-1.2.7.tgz",
      "integrity": "sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "b4a": "^1.6.4"
      }
    }
  }
}

{
  "name": "sample-tar-stream",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "tar-stream": "3.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/tar-stream@3.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tar-stream@3.2.0"
  ]
}

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 files with custom modes, sizes, and binary payloads
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. extract supports async iteration over entries yielding readable entry streams with headers
await (async () => {
	const pack = tar.pack();
	const extract = tar.extract();

	pack.pipe(extract);
	pack.entry({ name: 'async1.txt' }, 'first async');
	pack.entry({ name: 'async2.txt' }, 'second async', (err) => {
		if (err) throw err;
		pack.finalize();
	});

	const results = [];
	for await (const entry of extract) {
		const chunks = [];
		for await (const chunk of entry) {
			chunks.push(chunk);
		}
		results.push({
			name: entry.header.name,
			content: Buffer.concat(chunks).toString('utf8'),
		});
	}

	assert.equal(results.length, 2);
	assert.equal(results[0].name, 'async1.txt');
	assert.equal(results[0].content, 'first async');
	assert.equal(results[1].name, 'async2.txt');
	assert.equal(results[1].content, 'second async');
})();

// 5. pack.entry throws an error when called on a finalized pack stream
{
	const pack = tar.pack();
	pack.finalize();
	assert.throws(
		() => {
			pack.entry({ name: 'invalid.txt' }, 'content');
		},
		{
			name: 'Error',
			message: /already finalized or destroyed/,
		},
	);
}

// 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);
});