tar 6.2.1: u

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.u 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.u

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:f6c727bbda5dd76b01b95fb910147f3cdb23ee06027fc448119e45dd104e5b55","contract":["tar.u asynchronously appends new files to an existing uncompressed tar archive","tar.u updates existing archive entries when source files have updated mtime timestamps","tar.u supports synchronous archive updates when sync option is set to true","tar.u respects custom filter functions to selectively exclude files from archive updates","tar.u preserves relative file hierarchies and directory paths when updating archives"],"goal":"verify tar.u in pkg:npm/tar@6.2.1","kind":"HOW","packages":["pkg:npm/tar@6.2.1"],"schemaVersion":1,"symbols":["tar.u"]},"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.u"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-update",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-update",
      "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-update",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for tar.u in tar 6.2.1",
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "tar": "6.2.1"
  },
  "license": "MIT-0"
}

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

import * as tar from 'tar';

/**
 * Update an existing uncompressed tar archive asynchronously using tar.u.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string[]} fileList - List of files or directories to update/append.
 * @param {object} [options={}] - Additional options for tar.u (cwd, filter, etc.).
 * @returns {Promise<void>}
 */
export async function updateArchive(archivePath, fileList, options = {}) {
  return tar.u(
    {
      file: archivePath,
      ...options,
    },
    fileList
  );
}

/**
 * Update an existing uncompressed tar archive synchronously using tar.u.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string[]} fileList - List of files or directories to update/append.
 * @param {object} [options={}] - Additional options for tar.u (cwd, filter, etc.).
 */
export function updateArchiveSync(archivePath, fileList, options = {}) {
  return tar.u(
    {
      file: archivePath,
      sync: true,
      ...options,
    },
    fileList
  );
}

/**
 * Helper to create an initial uncompressed archive using tar.c.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string[]} fileList - List of files or directories.
 * @param {object} [options={}] - Options for tar.c.
 * @returns {Promise<void>}
 */
export async function createArchive(archivePath, fileList, options = {}) {
  return tar.c(
    {
      file: archivePath,
      ...options,
    },
    fileList
  );
}

/**
 * Helper to extract an archive using tar.x.
 * @param {string} archivePath - Path to the tar archive.
 * @param {string} targetDir - Extraction target directory.
 * @param {object} [options={}] - Options for tar.x.
 * @returns {Promise<void>}
 */
export async function extractArchive(archivePath, targetDir, options = {}) {
  return tar.x({
    file: archivePath,
    cwd: targetDir,
    ...options,
  });
}

/**
 * Helper to list archive entries using tar.t.
 * @param {string} archivePath - Path to the tar archive.
 * @returns {Promise<string[]>}
 */
export async function listArchive(archivePath) {
  const entries = [];
  await tar.t({
    file: archivePath,
    onentry: (entry) => {
      entries.push(entry.path);
    },
  });
  return entries;
}

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 {
  updateArchive,
  updateArchiveSync,
  createArchive,
  extractArchive,
  listArchive
} from '../src/index.mjs';

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

try {
  const fixturesDir = path.join(tempDir, 'fixtures');
  fs.mkdirSync(fixturesDir, { recursive: true });

  const fileA = path.join(fixturesDir, 'fileA.txt');
  const fileB = path.join(fixturesDir, 'fileB.txt');
  const fileC = path.join(fixturesDir, 'fileC.txt');
  const subDir = path.join(fixturesDir, 'sub');
  fs.mkdirSync(subDir, { recursive: true });
  const fileSub = path.join(subDir, 'subfile.txt');

  fs.writeFileSync(fileA, 'Initial file A content');
  fs.writeFileSync(fileB, 'Initial file B content');
  fs.writeFileSync(fileC, 'Initial file C content');
  fs.writeFileSync(fileSub, 'Nested subfile content');

  const archivePath = path.join(tempDir, 'test-archive.tar');

  // 1. Direct tar.u: append new file to archive asynchronously
  await tar.c({ file: archivePath, cwd: fixturesDir }, ['fileA.txt']);
  assert.strictEqual(fs.existsSync(archivePath), true, 'Initial archive should exist');

  await tar.u({ file: archivePath, cwd: fixturesDir }, ['fileB.txt']);
  const entriesAfterAdd = await listArchive(archivePath);
  assert.ok(entriesAfterAdd.includes('fileA.txt'), 'Archive should contain fileA.txt');
  assert.ok(entriesAfterAdd.includes('fileB.txt'), 'Archive should contain appended fileB.txt');

  // Verify extraction of appended file
  const extractDir1 = path.join(tempDir, 'extract1');
  fs.mkdirSync(extractDir1, { recursive: true });
  await extractArchive(archivePath, extractDir1);
  assert.strictEqual(fs.readFileSync(path.join(extractDir1, 'fileA.txt'), 'utf8'), 'Initial file A content');
  assert.strictEqual(fs.readFileSync(path.join(extractDir1, 'fileB.txt'), 'utf8'), 'Initial file B content');

  // 2. Direct tar.u: update file with newer mtime
  const futureTime = new Date(Date.now() + 10000);
  fs.writeFileSync(fileA, 'Updated file A content');
  fs.utimesSync(fileA, futureTime, futureTime);

  await tar.u({ file: archivePath, cwd: fixturesDir }, ['fileA.txt']);
  const extractDir2 = path.join(tempDir, 'extract2');
  fs.mkdirSync(extractDir2, { recursive: true });
  await extractArchive(archivePath, extractDir2);
  assert.strictEqual(
    fs.readFileSync(path.join(extractDir2, 'fileA.txt'), 'utf8'),
    'Updated file A content',
    'Extracted file A should reflect updated content after tar.u'
  );

  // 3. Helper updateArchive (async)
  await updateArchive(archivePath, ['sub/subfile.txt'], { cwd: fixturesDir });
  const entriesAfterNested = await listArchive(archivePath);
  assert.ok(
    entriesAfterNested.includes('sub/subfile.txt'),
    'Archive should include nested file path after updateArchive'
  );

  const extractDir3 = path.join(tempDir, 'extract3');
  fs.mkdirSync(extractDir3, { recursive: true });
  await extractArchive(archivePath, extractDir3);
  assert.strictEqual(
    fs.readFileSync(path.join(extractDir3, 'sub', 'subfile.txt'), 'utf8'),
    'Nested subfile content'
  );

  // 4. Synchronous update via updateArchiveSync (tar.u with sync: true)
  const syncArchive = path.join(tempDir, 'sync-archive.tar');
  await createArchive(syncArchive, ['fileA.txt'], { cwd: fixturesDir });
  updateArchiveSync(syncArchive, ['fileC.txt'], { cwd: fixturesDir });

  const syncEntries = await listArchive(syncArchive);
  assert.ok(syncEntries.includes('fileA.txt'), 'Sync archive should contain fileA.txt');
  assert.ok(syncEntries.includes('fileC.txt'), 'Sync archive should contain fileC.txt after synchronous tar.u');

  // 5. Filtering entries during tar.u
  const fileExcluded = path.join(fixturesDir, 'excluded.txt');
  const fileIncluded = path.join(fixturesDir, 'included.txt');
  fs.writeFileSync(fileExcluded, 'Should be excluded');
  fs.writeFileSync(fileIncluded, 'Should be included');

  await tar.u(
    {
      file: archivePath,
      cwd: fixturesDir,
      filter: (filePath) => !filePath.includes('excluded')
    },
    ['excluded.txt', 'included.txt']
  );

  const entriesAfterFilter = await listArchive(archivePath);
  assert.ok(entriesAfterFilter.includes('included.txt'), 'Archive should contain filtered included file');
  assert.ok(!entriesAfterFilter.includes('excluded.txt'), 'Archive should not contain excluded file');

  console.log('All tar.u contract assertions passed.');
} finally {
  fs.rmSync(tempDir, { recursive: true, force: true });
}