tar 6.2.1: x

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.x in pkg:npm/tar@6.2.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar@6.2.1
Demonstrate these symbols/APIs:
  - tar.x

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:47129fda1ef8a65ee8ade1203464033036a0491543467dc7ef3ef964e7bf8d3b","contract":["tar.x extracts archive files asynchronously to a target directory and returns a Promise","tar.x with sync option set to true extracts archive files synchronously","tar.x returns a writable stream to parse and unpack tar streams when file option is omitted","tar.x filters extracted archive entries using a predicate function passed to the filter option","tar.x strips leading path components from extracted files using the strip option"],"goal":"verify tar.x in pkg:npm/tar@6.2.1","kind":"HOW","packages":["pkg:npm/tar@6.2.1"],"schemaVersion":1,"symbols":["tar.x"]},"contractCommand":["node","test/contract.cjs"],"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.x"],"verifierAdapter":"node-typescript@1"}

'use strict';

const tar = require('tar');

async function extractArchive(archiveFile, targetDir, options = {}) {
  return await tar.x({
    file: archiveFile,
    cwd: targetDir,
    ...options
  });
}

function extractArchiveSync(archiveFile, targetDir, options = {}) {
  return tar.x({
    sync: true,
    file: archiveFile,
    cwd: targetDir,
    ...options
  });
}

function createExtractStream(targetDir, options = {}) {
  return tar.x({
    cwd: targetDir,
    ...options
  });
}

module.exports = {
  extractArchive,
  extractArchiveSync,
  createExtractStream,
  tar
};

{
  "name": "sample-tar-extract",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-extract",
      "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==",
      "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-extract",
  "version": "1.0.0",
  "private": true,
  "description": "verify tar.x in pkg:npm/tar@6.2.1",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "tar": "6.2.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify tar.x in pkg:npm/tar@6.2.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tar@6.2.1"
  ],
  "symbols": [
    "tar.x"
  ]
}

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const tar = require('tar');
const { extractArchive, extractArchiveSync, createExtractStream } = require('../index.js');

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tar-contract-test-'));
  const srcDir = path.join(tmpDir, 'source');
  const archivePath = path.join(tmpDir, 'archive.tar');
  const destDirAsync = path.join(tmpDir, 'dest-async');
  const destDirSync = path.join(tmpDir, 'dest-sync');
  const destDirStream = path.join(tmpDir, 'dest-stream');
  const destDirFilter = path.join(tmpDir, 'dest-filter');
  const destDirStrip = path.join(tmpDir, 'dest-strip');
  const destDirHelperAsync = path.join(tmpDir, 'dest-helper-async');
  const destDirHelperSync = path.join(tmpDir, 'dest-helper-sync');

  try {
    fs.mkdirSync(srcDir, { recursive: true });
    fs.mkdirSync(path.join(srcDir, 'subfolder'), { recursive: true });
    fs.writeFileSync(path.join(srcDir, 'file1.txt'), 'Content of file 1', 'utf8');
    fs.writeFileSync(path.join(srcDir, 'file2.json'), '{"valid":true}', 'utf8');
    fs.writeFileSync(path.join(srcDir, 'subfolder', 'nested.txt'), 'Nested file content', 'utf8');

    // Create test archive for contract verification
    await tar.c({ file: archivePath, cwd: srcDir }, ['file1.txt', 'file2.json', 'subfolder']);
    assert(fs.existsSync(archivePath), 'Archive file must be created');

    // 1. tar.x asynchronous extraction via Promise
    fs.mkdirSync(destDirAsync, { recursive: true });
    const asyncResult = await tar.x({ file: archivePath, cwd: destDirAsync });
    assert.strictEqual(fs.readFileSync(path.join(destDirAsync, 'file1.txt'), 'utf8'), 'Content of file 1');
    assert.strictEqual(fs.readFileSync(path.join(destDirAsync, 'file2.json'), 'utf8'), '{"valid":true}');
    assert.strictEqual(fs.readFileSync(path.join(destDirAsync, 'subfolder', 'nested.txt'), 'utf8'), 'Nested file content');

    // 2. tar.x synchronous extraction
    fs.mkdirSync(destDirSync, { recursive: true });
    tar.x({ sync: true, file: archivePath, cwd: destDirSync });
    assert.strictEqual(fs.readFileSync(path.join(destDirSync, 'file1.txt'), 'utf8'), 'Content of file 1');
    assert.strictEqual(fs.readFileSync(path.join(destDirSync, 'file2.json'), 'utf8'), '{"valid":true}');
    assert.strictEqual(fs.readFileSync(path.join(destDirSync, 'subfolder', 'nested.txt'), 'utf8'), 'Nested file content');

    // 3. tar.x streaming extraction
    fs.mkdirSync(destDirStream, { recursive: true });
    const extractStream = tar.x({ cwd: destDirStream });
    await new Promise((resolve, reject) => {
      fs.createReadStream(archivePath)
        .pipe(extractStream)
        .on('finish', resolve)
        .on('error', reject);
    });
    assert.strictEqual(fs.readFileSync(path.join(destDirStream, 'file1.txt'), 'utf8'), 'Content of file 1');
    assert.strictEqual(fs.readFileSync(path.join(destDirStream, 'subfolder', 'nested.txt'), 'utf8'), 'Nested file content');

    // 4. tar.x entry filtering
    fs.mkdirSync(destDirFilter, { recursive: true });
    await tar.x({
      file: archivePath,
      cwd: destDirFilter,
      filter: (filePath) => filePath.endsWith('.json')
    });
    assert.strictEqual(fs.existsSync(path.join(destDirFilter, 'file2.json')), true);
    assert.strictEqual(fs.existsSync(path.join(destDirFilter, 'file1.txt')), false);

    // 5. tar.x path component stripping
    fs.mkdirSync(destDirStrip, { recursive: true });
    await tar.x({
      file: archivePath,
      cwd: destDirStrip,
      strip: 1
    }, ['subfolder/nested.txt']);
    assert.strictEqual(fs.readFileSync(path.join(destDirStrip, 'nested.txt'), 'utf8'), 'Nested file content');

    // 6. Helper functions verification
    fs.mkdirSync(destDirHelperAsync, { recursive: true });
    await extractArchive(archivePath, destDirHelperAsync);
    assert.strictEqual(fs.readFileSync(path.join(destDirHelperAsync, 'file1.txt'), 'utf8'), 'Content of file 1');

    fs.mkdirSync(destDirHelperSync, { recursive: true });
    extractArchiveSync(archivePath, destDirHelperSync);
    assert.strictEqual(fs.readFileSync(path.join(destDirHelperSync, 'file1.txt'), 'utf8'), 'Content of file 1');

    console.log('Contract test passed successfully.');
    process.exit(0);
  } finally {
    try {
      if (fs.existsSync(tmpDir)) {
        fs.rmSync(tmpDir, { recursive: true, force: true });
      }
    } catch (e) {
      // Ignore cleanup error
    }
  }
}

run().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});