tar 6.2.1: create, extract, list

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

Use EXACTLY these public packages and versions:
  - pkg:npm/tar@6.2.1
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:1ce0e5d661c25c1071a393b710ba283ab01dbcf1845b1d237937bda939d238e9","constraints":{"executionContext":"node"},"contract":["tar.create packages files and nested directories into uncompressed and gzip-compressed tar archives","tar.extract unpacks archive contents restoring file hierarchy and data integrity","tar.create and tar.extract support synchronous operations via the sync option","tar.create and tar.extract filter entries using custom predicate functions","tar.extract supports stripping leading path components using the strip option","tar.list reads entries from tar archives and emits metadata","tar.replace appends or replaces entries in existing tar archives"],"goal":"verify pkg:npm/tar@6.2.1","kind":"HOW","packages":["pkg:npm/tar@6.2.1"],"schemaVersion":1,"symbols":["tar.create","tar.extract","tar.list","tar.replace"]},"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@6.2.1"],"schemaVersion":1,"subject":"pkg:npm/tar@6.2.1","symbols":["tar.create","tar.extract","tar.list","tar.replace"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tar": "6.2.1"
      }
    },
    "node_modules/chownr": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/chownr/-/chownr-2.0.0.tgz",
      "integrity": "sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==",
      "license": "ISC",
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/fs-minipass": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-2.1.0.tgz",
      "integrity": "sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==",
      "license": "ISC",
      "dependencies": {
        "minipass": "^3.0.0"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/fs-minipass/node_modules/minipass": {
      "version": "3.3.6",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
      "license": "ISC",
      "dependencies": {
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/minipass": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-5.0.0.tgz",
      "integrity": "sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==",
      "license": "ISC",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/minizlib": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz",
      "integrity": "sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==",
      "license": "MIT",
      "dependencies": {
        "minipass": "^3.0.0",
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">= 8"
      }
    },
    "node_modules/minizlib/node_modules/minipass": {
      "version": "3.3.6",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
      "license": "ISC",
      "dependencies": {
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/mkdirp": {
      "version": "1.0.4",
      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz",
      "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==",
      "license": "MIT",
      "bin": {
        "mkdirp": "bin/cmd.js"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/tar": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",
      "integrity": "sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==",
      "deprecated": "Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
      "license": "ISC",
      "dependencies": {
        "chownr": "^2.0.0",
        "fs-minipass": "^2.0.0",
        "minipass": "^5.0.0",
        "minizlib": "^2.1.1",
        "mkdirp": "^1.0.3",
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/yallist": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-tar",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for tar 6.2.1",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tar": "6.2.1"
  },
  "license": "MIT-0"
}

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

import * as tar from 'tar';

/**
 * Create a tar archive asynchronously.
 * @param {string} archivePath - Output path of the archive file.
 * @param {string[]} fileList - List of files or directories to include.
 * @param {object} [options={}] - Options for tar.create (cwd, gzip, filter, etc.).
 * @returns {Promise<void>}
 */
export async function createArchive(archivePath, fileList, options = {}) {
  return tar.create(
    {
      file: archivePath,
      ...options,
    },
    fileList
  );
}

/**
 * Extract a tar archive asynchronously.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string} targetDir - Destination directory to extract into.
 * @param {object} [options={}] - Options for tar.extract (strip, filter, etc.).
 * @returns {Promise<void>}
 */
export async function extractArchive(archivePath, targetDir, options = {}) {
  return tar.extract({
    file: archivePath,
    cwd: targetDir,
    ...options,
  });
}

/**
 * Create a tar archive synchronously.
 * @param {string} archivePath - Output path of the archive file.
 * @param {string[]} fileList - List of files or directories to include.
 * @param {object} [options={}] - Options for tar.create.
 */
export function createSyncArchive(archivePath, fileList, options = {}) {
  return tar.create(
    {
      file: archivePath,
      sync: true,
      ...options,
    },
    fileList
  );
}

/**
 * Extract a tar archive synchronously.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string} targetDir - Destination directory to extract into.
 * @param {object} [options={}] - Options for tar.extract.
 */
export function extractSyncArchive(archivePath, targetDir, options = {}) {
  return tar.extract({
    file: archivePath,
    cwd: targetDir,
    sync: true,
    ...options,
  });
}

/**
 * List entries from a tar archive.
 * @param {string} archivePath - Path to the tar archive.
 * @param {object} [options={}] - Options for tar.list.
 * @returns {Promise<string[]>} List of entry paths.
 */
export async function listArchiveEntries(archivePath, options = {}) {
  const entries = [];
  await tar.list({
    file: archivePath,
    onentry: (entry) => {
      entries.push(entry.path);
    },
    ...options,
  });
  return entries;
}

/**
 * Replace/append files into an existing uncompressed tar archive.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string[]} fileList - List of files to append/replace.
 * @param {object} [options={}] - Options for tar.replace.
 * @returns {Promise<void>}
 */
export async function replaceInArchive(archivePath, fileList, options = {}) {
  return tar.replace(
    {
      file: archivePath,
      ...options,
    },
    fileList
  );
}

import assert from 'node:assert';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import * as tar from 'tar';
import {
  createArchive,
  extractArchive,
  createSyncArchive,
  extractSyncArchive,
  listArchiveEntries,
  replaceInArchive
} from '../src/index.mjs';

const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tar-contract-test-'));

try {
  // Setup sample source files
  const fixturesDir = path.join(tempDir, 'fixtures');
  fs.mkdirSync(fixturesDir, { recursive: true });
  fs.writeFileSync(path.join(fixturesDir, 'hello.txt'), 'Hello, World!');
  fs.writeFileSync(path.join(fixturesDir, 'data.json'), JSON.stringify({ name: 'tar', version: '6.2.1' }));
  const subDir = path.join(fixturesDir, 'nested');
  fs.mkdirSync(subDir, { recursive: true });
  fs.writeFileSync(path.join(subDir, 'nested.txt'), 'Nested file content');

  // 1. Direct tar.create and tar.extract (Async uncompressed)
  const directArchive = path.join(tempDir, 'direct.tar');
  const directExtractDir = path.join(tempDir, 'direct-extract');
  fs.mkdirSync(directExtractDir, { recursive: true });

  await tar.create({ file: directArchive, cwd: fixturesDir }, ['hello.txt', 'data.json', 'nested']);
  assert.strictEqual(fs.existsSync(directArchive), true, 'direct.tar should be created');

  await tar.extract({ file: directArchive, cwd: directExtractDir });
  assert.strictEqual(fs.readFileSync(path.join(directExtractDir, 'hello.txt'), 'utf8'), 'Hello, World!');
  assert.strictEqual(fs.readFileSync(path.join(directExtractDir, 'nested', 'nested.txt'), 'utf8'), 'Nested file content');

  // 2. Direct tar.create and tar.extract with gzip compression
  const directGzipArchive = path.join(tempDir, 'direct.tar.gz');
  const directGzipExtractDir = path.join(tempDir, 'direct-gzip-extract');
  fs.mkdirSync(directGzipExtractDir, { recursive: true });

  await tar.create({ file: directGzipArchive, gzip: true, cwd: fixturesDir }, ['hello.txt', 'nested']);
  assert.strictEqual(fs.existsSync(directGzipArchive), true, 'direct.tar.gz should be created');

  await tar.extract({ file: directGzipArchive, cwd: directGzipExtractDir });
  assert.strictEqual(fs.readFileSync(path.join(directGzipExtractDir, 'hello.txt'), 'utf8'), 'Hello, World!');
  assert.strictEqual(fs.readFileSync(path.join(directGzipExtractDir, 'nested', 'nested.txt'), 'utf8'), 'Nested file content');

  // 3. Helper async createArchive and extractArchive
  const helperArchive = path.join(tempDir, 'helper.tar.gz');
  const helperExtractDir = path.join(tempDir, 'helper-extract');
  fs.mkdirSync(helperExtractDir, { recursive: true });

  await createArchive(helperArchive, ['hello.txt', 'data.json'], { cwd: fixturesDir, gzip: true });
  assert.strictEqual(fs.existsSync(helperArchive), true, 'helper.tar.gz should exist');

  await extractArchive(helperArchive, helperExtractDir);
  assert.strictEqual(fs.readFileSync(path.join(helperExtractDir, 'hello.txt'), 'utf8'), 'Hello, World!');
  const data = JSON.parse(fs.readFileSync(path.join(helperExtractDir, 'data.json'), 'utf8'));
  assert.strictEqual(data.name, 'tar');
  assert.strictEqual(data.version, '6.2.1');

  // 4. Synchronous tar.create and tar.extract with sync wrappers
  const syncArchive = path.join(tempDir, 'sync.tar');
  const syncExtractDir = path.join(tempDir, 'sync-extract');
  fs.mkdirSync(syncExtractDir, { recursive: true });

  createSyncArchive(syncArchive, ['hello.txt'], { cwd: fixturesDir });
  assert.strictEqual(fs.existsSync(syncArchive), true, 'sync.tar should exist');

  extractSyncArchive(syncArchive, syncExtractDir);
  assert.strictEqual(fs.readFileSync(path.join(syncExtractDir, 'hello.txt'), 'utf8'), 'Hello, World!');

  // 5. Filtering entries during creation and extraction
  const filteredArchive = path.join(tempDir, 'filtered.tar');
  const filteredExtractDir = path.join(tempDir, 'filtered-extract');
  fs.mkdirSync(filteredExtractDir, { recursive: true });

  await tar.create(
    {
      file: filteredArchive,
      cwd: fixturesDir,
      filter: (p) => !p.endsWith('data.json')
    },
    ['hello.txt', 'data.json']
  );

  await tar.extract({ file: filteredArchive, cwd: filteredExtractDir });
  assert.strictEqual(fs.existsSync(path.join(filteredExtractDir, 'hello.txt')), true);
  assert.strictEqual(fs.existsSync(path.join(filteredExtractDir, 'data.json')), false, 'filtered file should not be archived');

  // 6. Extraction with strip option
  const stripExtractDir = path.join(tempDir, 'strip-extract');
  fs.mkdirSync(stripExtractDir, { recursive: true });

  const nestedArchive = path.join(tempDir, 'nested.tar');
  await tar.create({ file: nestedArchive, cwd: fixturesDir }, ['nested/nested.txt']);

  await tar.extract({ file: nestedArchive, cwd: stripExtractDir, strip: 1 });
  assert.strictEqual(fs.existsSync(path.join(stripExtractDir, 'nested.txt')), true, 'strip 1 should extract nested.txt at root of target');

  // 7. tar.list listing entries
  const entries = await listArchiveEntries(directArchive);
  assert.ok(entries.includes('hello.txt'), 'list should include hello.txt');
  assert.ok(entries.includes('data.json'), 'list should include data.json');

  // 8. tar.replace appending new entry to archive
  const replaceFixture = path.join(tempDir, 'added.txt');
  fs.writeFileSync(replaceFixture, 'added content');
  await replaceInArchive(directArchive, ['added.txt'], { cwd: tempDir });
  const updatedEntries = await listArchiveEntries(directArchive);
  assert.ok(updatedEntries.includes('added.txt'), 'list should include added.txt after replacement');

  console.log('Contract tests passed successfully.');
} finally {
  fs.rmSync(tempDir, { recursive: true, force: true });
}