tar 7.5.22: gz

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

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

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:a8b7380f14a2e34de6623bf632094adcab0cc8cdcbe1fdd9d66f2e94c03ad337","contract":["tar.create with gzip: true produces valid gzip-compressed tar.gz archives with 0x1f8b header","tar.extract automatically decompresses and unpacks gzip-compressed tar.gz archives","tar.list inspects headers and paths inside gzip-compressed tar.gz archives directly","tar.create and tar.extract support synchronous tar.gz operations via sync: true","tar.create accepts gzip configuration options including compression level"],"goal":"verify tar.gz in pkg:npm/tar@7.5.22","kind":"HOW","packages":["pkg:npm/tar@7.5.22"],"schemaVersion":1,"symbols":["tar.gz"]},"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@7.5.22"],"schemaVersion":1,"subject":"pkg:npm/tar@7.5.22","symbols":["tar.gz"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-gz",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-gz",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "tar": "7.5.22"
      }
    },
    "node_modules/@isaacs/fs-minipass": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/@isaacs/fs-minipass/-/fs-minipass-4.0.1.tgz",
      "integrity": "sha512-wgm9Ehl2jpeqP3zw/7mo3kRHFp5MEDhqAdwy1fTGkHAwnkGOVsgpvQhL8B5n1qlb01jV3n/bI0ZfZp5lWA1k4w==",
      "license": "ISC",
      "dependencies": {
        "minipass": "^7.0.4"
      },
      "engines": {
        "node": ">=18.0.0"
      }
    },
    "node_modules/chownr": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
      "integrity": "sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/minipass": {
      "version": "7.1.3",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=16 || 14 >=14.17"
      }
    },
    "node_modules/minizlib": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
      "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
      "license": "MIT",
      "dependencies": {
        "minipass": "^7.1.2"
      },
      "engines": {
        "node": ">= 18"
      }
    },
    "node_modules/tar": {
      "version": "7.5.22",
      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.22.tgz",
      "integrity": "sha512-MFO/QzvtAOmJbkhOaCTvbGcFN9L9b+JunIsDwaKljSOdcLMea3NJ1k9Usz/rjdfSXTq4dfzfeS7W4p4YOAAHeA==",
      "license": "BlueOak-1.0.0",
      "dependencies": {
        "@isaacs/fs-minipass": "^4.0.0",
        "chownr": "^3.0.0",
        "minipass": "^7.1.2",
        "minizlib": "^3.1.0",
        "yallist": "^5.0.0"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/yallist": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-5.0.0.tgz",
      "integrity": "sha512-YgvUTfwqyc7UXVMrB+SImsVYSmTS8X/tSrtdNZMImM+n7+QTriRXyXim0mBrTXNeqzVF0KWGgHPeiyViFFrNDw==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=18"
      }
    }
  }
}

{
  "name": "sample-tar-gz",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for tar.gz handling in tar",
  "type": "module",
  "main": "src/index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tar": "7.5.22"
  },
  "license": "MIT-0"
}

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

import * as tar from 'tar';

/**
 * Creates a gzip-compressed tar archive (.tar.gz).
 * @param {string} archivePath - Output path for the .tar.gz archive.
 * @param {string[]} files - List of files or directories to archive.
 * @param {object} [options={}] - Additional options for tar.create.
 * @returns {Promise<void>}
 */
export async function createTarGz(archivePath, files, options = {}) {
  return tar.create(
    {
      file: archivePath,
      gzip: true,
      ...options,
    },
    files
  );
}

/**
 * Extracts a gzip-compressed tar archive (.tar.gz).
 * tar automatically detects gzip compression, but gzip: true can also be explicit.
 * @param {string} archivePath - Path to the .tar.gz archive.
 * @param {string} targetDir - Destination directory to extract into.
 * @param {object} [options={}] - Additional options for tar.extract.
 * @returns {Promise<void>}
 */
export async function extractTarGz(archivePath, targetDir, options = {}) {
  return tar.extract({
    file: archivePath,
    cwd: targetDir,
    ...options,
  });
}

/**
 * Lists entries contained within a gzip-compressed tar archive (.tar.gz).
 * @param {string} archivePath - Path to the .tar.gz archive.
 * @param {object} [options={}] - Additional options for tar.list.
 * @returns {Promise<string[]>} List of archive entry paths.
 */
export async function listTarGz(archivePath, options = {}) {
  const entries = [];
  await tar.list({
    file: archivePath,
    onReadEntry: (entry) => entries.push(entry.path),
    ...options,
  });
  return entries;
}

/**
 * Synchronously creates a gzip-compressed tar archive (.tar.gz).
 * @param {string} archivePath - Output path for the .tar.gz archive.
 * @param {string[]} files - List of files or directories to archive.
 * @param {object} [options={}] - Additional options for tar.create.
 */
export function createTarGzSync(archivePath, files, options = {}) {
  return tar.create(
    {
      file: archivePath,
      gzip: true,
      sync: true,
      ...options,
    },
    files
  );
}

/**
 * Synchronously extracts a gzip-compressed tar archive (.tar.gz).
 * @param {string} archivePath - Path to the .tar.gz archive.
 * @param {string} targetDir - Destination directory to extract into.
 * @param {object} [options={}] - Additional options for tar.extract.
 */
export function extractTarGzSync(archivePath, targetDir, options = {}) {
  return tar.extract({
    file: archivePath,
    cwd: targetDir,
    sync: true,
    ...options,
  });
}

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 {
  createTarGz,
  extractTarGz,
  listTarGz,
  createTarGzSync,
  extractTarGzSync,
} from '../src/index.mjs';

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

try {
  // 1. Prepare fixture directory and sample files
  const fixturesDir = path.join(tempDir, 'fixtures');
  fs.mkdirSync(fixturesDir, { recursive: true });
  fs.writeFileSync(path.join(fixturesDir, 'a.txt'), 'Alpha payload');
  fs.writeFileSync(path.join(fixturesDir, 'b.json'), JSON.stringify({ item: 'bravo', count: 42 }));
  const subDir = path.join(fixturesDir, 'deep');
  fs.mkdirSync(subDir, { recursive: true });
  fs.writeFileSync(path.join(subDir, 'c.txt'), 'Deep payload');

  // 2. Direct tar.create with gzip: true produces valid gzip magic header (0x1f8b)
  const archivePath = path.join(tempDir, 'archive.tar.gz');
  await tar.create({ file: archivePath, gzip: true, cwd: fixturesDir }, ['a.txt', 'b.json', 'deep']);
  assert.strictEqual(fs.existsSync(archivePath), true, 'archive.tar.gz should be created');

  const archiveHeader = Buffer.alloc(2);
  const fd = fs.openSync(archivePath, 'r');
  fs.readSync(fd, archiveHeader, 0, 2, 0);
  fs.closeSync(fd);
  assert.strictEqual(archiveHeader[0], 0x1f, 'Gzip header byte 0 must be 0x1f');
  assert.strictEqual(archiveHeader[1], 0x8b, 'Gzip header byte 1 must be 0x8b');

  // 3. tar.list reads entries from gzip-compressed tar.gz archive directly
  const listedEntries = [];
  await tar.list({
    file: archivePath,
    onReadEntry: (entry) => listedEntries.push(entry.path),
  });
  assert.strictEqual(listedEntries.includes('a.txt'), true, 'archive must contain a.txt');
  assert.strictEqual(listedEntries.includes('b.json'), true, 'archive must contain b.json');
  assert.strictEqual(listedEntries.some((e) => e.startsWith('deep')), true, 'archive must contain deep entries');

  // 4. tar.extract automatically detects gzip and unpacks contents
  const extractDir = path.join(tempDir, 'extract');
  fs.mkdirSync(extractDir, { recursive: true });
  await tar.extract({ file: archivePath, cwd: extractDir });

  assert.strictEqual(fs.readFileSync(path.join(extractDir, 'a.txt'), 'utf8'), 'Alpha payload');
  const bData = JSON.parse(fs.readFileSync(path.join(extractDir, 'b.json'), 'utf8'));
  assert.strictEqual(bData.item, 'bravo');
  assert.strictEqual(bData.count, 42);
  assert.strictEqual(fs.readFileSync(path.join(extractDir, 'deep', 'c.txt'), 'utf8'), 'Deep payload');

  // 5. Helper functions createTarGz, listTarGz, extractTarGz
  const helperArchive = path.join(tempDir, 'helper.tar.gz');
  await createTarGz(helperArchive, ['a.txt', 'b.json'], { cwd: fixturesDir });
  assert.strictEqual(fs.existsSync(helperArchive), true, 'helper.tar.gz should exist');

  const helperEntries = await listTarGz(helperArchive);
  assert.deepStrictEqual(helperEntries.sort(), ['a.txt', 'b.json']);

  const helperExtractDir = path.join(tempDir, 'helper-extract');
  fs.mkdirSync(helperExtractDir, { recursive: true });
  await extractTarGz(helperArchive, helperExtractDir);
  assert.strictEqual(fs.readFileSync(path.join(helperExtractDir, 'a.txt'), 'utf8'), 'Alpha payload');

  // 6. Synchronous creation and extraction with sync: true
  const syncArchive = path.join(tempDir, 'sync.tar.gz');
  createTarGzSync(syncArchive, ['a.txt'], { cwd: fixturesDir });
  assert.strictEqual(fs.existsSync(syncArchive), true, 'sync.tar.gz should exist');

  const syncExtractDir = path.join(tempDir, 'sync-extract');
  fs.mkdirSync(syncExtractDir, { recursive: true });
  extractTarGzSync(syncArchive, syncExtractDir);
  assert.strictEqual(fs.readFileSync(path.join(syncExtractDir, 'a.txt'), 'utf8'), 'Alpha payload');

  // 7. Gzip options customization (compression level)
  const optArchive = path.join(tempDir, 'opt.tar.gz');
  await tar.create(
    {
      file: optArchive,
      cwd: fixturesDir,
      gzip: { level: 9 },
    },
    ['a.txt']
  );
  assert.strictEqual(fs.existsSync(optArchive), true, 'custom gzip level archive created');

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