tar-fs 3.1.3

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-fs@3.1.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar-fs@3.1.3

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:ad81e2b36fb7dbb5ce05659eafdf11201b9d8b07b55a4951f49750fa85eabed1","contract":["tarFs exports pack and extract functions","tarFs.pack returns a readable stream and tarFs.extract returns a writable stream","tarFs.pack creates a tar archive of directory contents and tarFs.extract unpacks files preserving hierarchy","tarFs.pack with entries option archives only specified files","tarFs.pack with ignore option excludes matching files from archive","tarFs.pack with map option transforms tar entry headers","tarFs.extract with strip option removes leading directory path components","copyDirectory helper copies directory contents via piped pack and extract streams"],"goal":"verify pkg:npm/tar-fs@3.1.3","kind":"HOW","packages":["pkg:npm/tar-fs@3.1.3"],"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-fs@3.1.3"],"schemaVersion":1,"subject":"pkg:npm/tar-fs@3.1.3","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-fs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-fs",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tar-fs": "3.1.3"
      }
    },
    "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/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/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/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/pump": {
      "version": "3.0.4",
      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
      "license": "MIT",
      "dependencies": {
        "end-of-stream": "^1.1.0",
        "once": "^1.3.1"
      }
    },
    "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-fs": {
      "version": "3.1.3",
      "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-3.1.3.tgz",
      "integrity": "sha512-/hU4AXnIdZu+Gvl1pk0oI5f5HxWsCJRtY2aFaJdk9VvyL48DWU6iU5WAIPG+wIi1YvWA6eTJvIviP/tMAZZNwQ==",
      "license": "MIT",
      "dependencies": {
        "pump": "^3.0.0",
        "tar-stream": "^3.1.5"
      },
      "optionalDependencies": {
        "bare-fs": "^4.0.1",
        "bare-path": "^3.0.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"
      }
    },
    "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-fs",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for tar-fs@3.1.3",
  "main": "src/index.mjs",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "tar-fs": "3.1.3"
  }
}

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

import { pipeline } from "node:stream/promises";
import tarFs from "tar-fs";

/**
 * Packs a directory or files into a tar stream.
 *
 * @param {string} cwd - Source directory path.
 * @param {object} [opts={}] - Options for tar packing.
 * @returns {import("node:stream").Readable} Readable tar stream.
 */
export function pack(cwd, opts = {}) {
  return tarFs.pack(cwd, opts);
}

/**
 * Extracts a tar stream into a destination directory.
 *
 * @param {string} cwd - Destination directory path.
 * @param {object} [opts={}] - Options for tar extraction.
 * @returns {import("node:stream").Writable} Writable tar extract stream.
 */
export function extract(cwd, opts = {}) {
  return tarFs.extract(cwd, opts);
}

/**
 * Packs source directory to a destination directory by piping pack and extract streams.
 *
 * @param {string} srcDir - Source directory to pack.
 * @param {string} destDir - Destination directory to extract into.
 * @param {object} [packOpts={}] - Pack options.
 * @param {object} [extractOpts={}] - Extract options.
 * @returns {Promise<void>} Resolves when the copy completes.
 */
export async function copyDirectory(srcDir, destDir, packOpts = {}, extractOpts = {}) {
  const packStream = tarFs.pack(srcDir, packOpts);
  const extractStream = tarFs.extract(destDir, extractOpts);
  await pipeline(packStream, extractStream);
}

export { tarFs };
export default tarFs;

import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { pipeline } from "node:stream/promises";
import tarFs, { pack, extract, copyDirectory } from "../src/index.mjs";

const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), "csx-tarfs-contract-"));

try {
  // 1. Export structure verification
  assert.strictEqual(typeof tarFs.pack, "function", "tarFs.pack must be a function");
  assert.strictEqual(typeof tarFs.extract, "function", "tarFs.extract must be a function");
  assert.strictEqual(typeof pack, "function", "pack helper must be a function");
  assert.strictEqual(typeof extract, "function", "extract helper must be a function");
  assert.strictEqual(typeof copyDirectory, "function", "copyDirectory helper must be a function");

  // Setup test directories
  const srcDir = path.join(tmpBase, "src");
  fs.mkdirSync(srcDir, { recursive: true });
  fs.writeFileSync(path.join(srcDir, "file1.txt"), "Content of file 1\n");
  fs.writeFileSync(path.join(srcDir, "ignore.tmp"), "Temporary file\n");

  const nestedDir = path.join(srcDir, "sub");
  fs.mkdirSync(nestedDir, { recursive: true });
  fs.writeFileSync(path.join(nestedDir, "nested.txt"), "Nested file content\n");

  // 2. tarFs.pack creates a readable stream and tarFs.extract creates a writable stream
  {
    const pStream = tarFs.pack(srcDir);
    const eStream = tarFs.extract(path.join(tmpBase, "dummy"));
    assert.strictEqual(typeof pStream.pipe, "function", "pack() should return a readable stream");
    assert.strictEqual(typeof eStream.write, "function", "extract() should return a writable stream");
    pStream.destroy();
    eStream.destroy();
  }

  // 3. tarFs.pack packs directory contents and tarFs.extract restores directory hierarchy and files
  {
    const dest1 = path.join(tmpBase, "dest1");
    fs.mkdirSync(dest1, { recursive: true });

    await pipeline(tarFs.pack(srcDir), tarFs.extract(dest1));

    assert.strictEqual(
      fs.readFileSync(path.join(dest1, "file1.txt"), "utf8"),
      "Content of file 1\n",
      "File 1 content must match"
    );
    assert.strictEqual(
      fs.readFileSync(path.join(dest1, "sub", "nested.txt"), "utf8"),
      "Nested file content\n",
      "Nested file content must match"
    );
  }

  // 4. tarFs.pack with entries option packs only specified entries
  {
    const destEntries = path.join(tmpBase, "dest_entries");
    fs.mkdirSync(destEntries, { recursive: true });

    await pipeline(
      tarFs.pack(srcDir, { entries: ["file1.txt"] }),
      tarFs.extract(destEntries)
    );

    assert.strictEqual(fs.existsSync(path.join(destEntries, "file1.txt")), true);
    assert.strictEqual(fs.existsSync(path.join(destEntries, "sub")), false);
    assert.strictEqual(fs.existsSync(path.join(destEntries, "ignore.tmp")), false);
  }

  // 5. tarFs.pack with ignore option excludes matching files
  {
    const destIgnore = path.join(tmpBase, "dest_ignore");
    fs.mkdirSync(destIgnore, { recursive: true });

    await pipeline(
      tarFs.pack(srcDir, {
        ignore: (filepath) => path.basename(filepath).endsWith(".tmp")
      }),
      tarFs.extract(destIgnore)
    );

    assert.strictEqual(fs.existsSync(path.join(destIgnore, "file1.txt")), true);
    assert.strictEqual(fs.existsSync(path.join(destIgnore, "sub", "nested.txt")), true);
    assert.strictEqual(fs.existsSync(path.join(destIgnore, "ignore.tmp")), false, "Ignored file should not be packed");
  }

  // 6. tarFs.pack with map option modifies entry headers during packing
  {
    const destMap = path.join(tmpBase, "dest_map");
    fs.mkdirSync(destMap, { recursive: true });

    await pipeline(
      tarFs.pack(srcDir, {
        entries: ["file1.txt"],
        map: (header) => {
          header.name = "prefix_" + header.name;
          return header;
        }
      }),
      tarFs.extract(destMap)
    );

    assert.strictEqual(fs.existsSync(path.join(destMap, "prefix_file1.txt")), true);
    assert.strictEqual(
      fs.readFileSync(path.join(destMap, "prefix_file1.txt"), "utf8"),
      "Content of file 1\n"
    );
  }

  // 7. tarFs.extract with strip option removes leading path components
  {
    const destStrip = path.join(tmpBase, "dest_strip");
    fs.mkdirSync(destStrip, { recursive: true });

    await pipeline(
      tarFs.pack(srcDir, { entries: ["sub/nested.txt"] }),
      tarFs.extract(destStrip, { strip: 1 })
    );

    assert.strictEqual(fs.existsSync(path.join(destStrip, "nested.txt")), true);
    assert.strictEqual(
      fs.readFileSync(path.join(destStrip, "nested.txt"), "utf8"),
      "Nested file content\n"
    );
  }

  // 8. copyDirectory helper function copies directory contents via pack and extract streams
  {
    const destHelper = path.join(tmpBase, "dest_helper");
    fs.mkdirSync(destHelper, { recursive: true });

    await copyDirectory(srcDir, destHelper, {
      ignore: (filepath) => path.basename(filepath).endsWith(".tmp")
    });

    assert.strictEqual(
      fs.readFileSync(path.join(destHelper, "file1.txt"), "utf8"),
      "Content of file 1\n"
    );
    assert.strictEqual(
      fs.readFileSync(path.join(destHelper, "sub", "nested.txt"), "utf8"),
      "Nested file content\n"
    );
    assert.strictEqual(fs.existsSync(path.join(destHelper, "ignore.tmp")), false);
  }

  console.log("All tar-fs contract assertions passed successfully.");
} finally {
  fs.rmSync(tmpBase, { recursive: true, force: true });
}