tar-fs 3.1.3: pack

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 tar-fs.pack in pkg:npm/tar-fs@3.1.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar-fs@3.1.3
Demonstrate these symbols/APIs:
  - tar-fs.pack
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:e94652529f8c3644f296c06c7e2da6c7e04fed050756e73fb274e7266a062581","constraints":{"executionContext":"node"},"contract":["tarFs exports pack function and pack helpers","tarFs.pack returns a readable stream when given a directory","tarFs.pack archives directory contents and nested files into a valid tar stream","tarFs.pack with entries option includes only specified file paths","tarFs.pack with ignore option excludes matching files from the archive","tarFs.pack with map option transforms tar entry headers","packEntries helper archives only selected files","packWithFilter helper ignores files matching the predicate","packWithMap helper modifies entry headers during packing"],"goal":"verify tar-fs.pack in pkg:npm/tar-fs@3.1.3","kind":"HOW","packages":["pkg:npm/tar-fs@3.1.3"],"schemaVersion":1,"symbols":["tar-fs.pack"]},"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-fs@3.1.3"],"schemaVersion":1,"subject":"pkg:npm/tar-fs@3.1.3","symbols":["tar-fs.pack"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-fs-pack",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-fs-pack",
      "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-pack",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for tar-fs.pack in tar-fs@3.1.3",
  "main": "src/index.mjs",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "tar-fs": "3.1.3"
  }
}

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

import tarFs from "tar-fs";

/**
 * Creates a tar archive stream from a directory.
 *
 * @param {string} cwd - Base directory to pack.
 * @param {object} [opts={}] - Pack options.
 * @returns {import("node:stream").Readable} Readable tar stream.
 */
export function pack(cwd, opts = {}) {
  return tarFs.pack(cwd, opts);
}

/**
 * Packs specific entries relative to cwd.
 *
 * @param {string} cwd - Base directory.
 * @param {string[]} entries - Relative paths to include in the archive.
 * @param {object} [opts={}] - Additional pack options.
 * @returns {import("node:stream").Readable} Readable tar stream.
 */
export function packEntries(cwd, entries, opts = {}) {
  return tarFs.pack(cwd, { ...opts, entries });
}

/**
 * Packs directory while ignoring files based on a predicate function.
 *
 * @param {string} cwd - Base directory.
 * @param {(name: string, header: object) => boolean} ignore - Ignore predicate function.
 * @param {object} [opts={}] - Additional pack options.
 * @returns {import("node:stream").Readable} Readable tar stream.
 */
export function packWithFilter(cwd, ignore, opts = {}) {
  return tarFs.pack(cwd, { ...opts, ignore });
}

/**
 * Packs directory while transforming tar entry headers.
 *
 * @param {string} cwd - Base directory.
 * @param {(header: object) => object} map - Header transformation function.
 * @param {object} [opts={}] - Additional pack options.
 * @returns {import("node:stream").Readable} Readable tar stream.
 */
export function packWithMap(cwd, map, opts = {}) {
  return tarFs.pack(cwd, { ...opts, map });
}

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, packEntries, packWithFilter, packWithMap } from "../src/index.mjs";

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

try {
  // Verify function exports
  assert.strictEqual(typeof tarFs.pack, "function", "tarFs.pack must be a function");
  assert.strictEqual(typeof pack, "function", "pack helper must be a function");
  assert.strictEqual(typeof packEntries, "function", "packEntries helper must be a function");
  assert.strictEqual(typeof packWithFilter, "function", "packWithFilter helper must be a function");
  assert.strictEqual(typeof packWithMap, "function", "packWithMap helper must be a function");

  // Create sample directory fixture
  const fixtureDir = path.join(tmpBase, "fixture");
  fs.mkdirSync(fixtureDir, { recursive: true });
  fs.writeFileSync(path.join(fixtureDir, "file1.txt"), "Hello from file 1\n");
  fs.writeFileSync(path.join(fixtureDir, "file2.log"), "Log entry 2\n");

  const subDir = path.join(fixtureDir, "nested");
  fs.mkdirSync(subDir, { recursive: true });
  fs.writeFileSync(path.join(subDir, "file3.txt"), "Deep content\n");

  // 1. tarFs.pack returns a readable stream when given a directory
  {
    const stream = tarFs.pack(fixtureDir);
    assert.ok(stream, "pack stream must be returned");
    assert.strictEqual(typeof stream.pipe, "function", "pack stream must be a readable stream");
    assert.strictEqual(typeof stream.on, "function", "pack stream must be an EventEmitter");
    stream.destroy();
  }

  // 2. tarFs.pack archives directory contents and nested files into a valid tar stream
  {
    const outDir = path.join(tmpBase, "out1");
    fs.mkdirSync(outDir, { recursive: true });

    await pipeline(tarFs.pack(fixtureDir), tarFs.extract(outDir));

    assert.strictEqual(fs.existsSync(path.join(outDir, "file1.txt")), true);
    assert.strictEqual(
      fs.readFileSync(path.join(outDir, "file1.txt"), "utf8"),
      "Hello from file 1\n"
    );
    assert.strictEqual(fs.existsSync(path.join(outDir, "file2.log")), true);
    assert.strictEqual(fs.existsSync(path.join(outDir, "nested", "file3.txt")), true);
    assert.strictEqual(
      fs.readFileSync(path.join(outDir, "nested", "file3.txt"), "utf8"),
      "Deep content\n"
    );
  }

  // 3. tarFs.pack with entries option includes only specified file paths
  {
    const outDir = path.join(tmpBase, "out_entries");
    fs.mkdirSync(outDir, { recursive: true });

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

    assert.strictEqual(fs.existsSync(path.join(outDir, "file1.txt")), true);
    assert.strictEqual(fs.existsSync(path.join(outDir, "file2.log")), false);
    assert.strictEqual(fs.existsSync(path.join(outDir, "nested")), false);
  }

  // 4. tarFs.pack with ignore option excludes matching files from the archive
  {
    const outDir = path.join(tmpBase, "out_ignore");
    fs.mkdirSync(outDir, { recursive: true });

    await pipeline(
      tarFs.pack(fixtureDir, {
        ignore: (filepath) => path.extname(filepath) === ".log"
      }),
      tarFs.extract(outDir)
    );

    assert.strictEqual(fs.existsSync(path.join(outDir, "file1.txt")), true);
    assert.strictEqual(fs.existsSync(path.join(outDir, "file2.log")), false);
    assert.strictEqual(fs.existsSync(path.join(outDir, "nested", "file3.txt")), true);
  }

  // 5. tarFs.pack with map option transforms tar entry headers
  {
    const outDir = path.join(tmpBase, "out_map");
    fs.mkdirSync(outDir, { recursive: true });

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

    assert.strictEqual(fs.existsSync(path.join(outDir, "renamed_file1.txt")), true);
    assert.strictEqual(
      fs.readFileSync(path.join(outDir, "renamed_file1.txt"), "utf8"),
      "Hello from file 1\n"
    );
  }

  // 6. packEntries helper archives only selected files
  {
    const outDir = path.join(tmpBase, "out_helper_entries");
    fs.mkdirSync(outDir, { recursive: true });

    await pipeline(
      packEntries(fixtureDir, ["file2.log"]),
      tarFs.extract(outDir)
    );

    assert.strictEqual(fs.existsSync(path.join(outDir, "file2.log")), true);
    assert.strictEqual(fs.existsSync(path.join(outDir, "file1.txt")), false);
  }

  // 7. packWithFilter helper ignores files matching the predicate
  {
    const outDir = path.join(tmpBase, "out_helper_filter");
    fs.mkdirSync(outDir, { recursive: true });

    await pipeline(
      packWithFilter(fixtureDir, (filepath) => path.basename(filepath) === "file1.txt"),
      tarFs.extract(outDir)
    );

    assert.strictEqual(fs.existsSync(path.join(outDir, "file1.txt")), false);
    assert.strictEqual(fs.existsSync(path.join(outDir, "file2.log")), true);
    assert.strictEqual(fs.existsSync(path.join(outDir, "nested", "file3.txt")), true);
  }

  // 8. packWithMap helper modifies entry headers during packing
  {
    const outDir = path.join(tmpBase, "out_helper_map");
    fs.mkdirSync(outDir, { recursive: true });

    await pipeline(
      packWithMap(fixtureDir, (header) => {
        if (header.name === "file1.txt") {
          header.name = "custom_dir/file1.txt";
        }
        return header;
      }, { entries: ["file1.txt"] }),
      tarFs.extract(outDir)
    );

    assert.strictEqual(fs.existsSync(path.join(outDir, "custom_dir", "file1.txt")), true);
    assert.strictEqual(
      fs.readFileSync(path.join(outDir, "custom_dir", "file1.txt"), "utf8"),
      "Hello from file 1\n"
    );
  }

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