tar 6.2.1: r

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

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:223d5dfe90bd551d61e20790fd62212cbb609d47a18fed2bbb207aab5dd9b5f2","contract":["tar.r is an alias for tar.replace","tar.r appends files to an existing uncompressed tar archive asynchronously","tar.r appends files to an existing uncompressed tar archive synchronously when sync option is true","tar.r supports callback notification on completion","tar.r resolves files relative to cwd option","tar.r throws a TypeError when file option is omitted"],"goal":"verify tar.r in pkg:npm/tar@6.2.1","kind":"HOW","packages":["pkg:npm/tar@6.2.1"],"schemaVersion":1,"symbols":["tar.r"]},"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@6.2.1"],"schemaVersion":1,"subject":"pkg:npm/tar@6.2.1","symbols":["tar.r"],"verifierAdapter":"node-typescript@1"}

import * as tar from 'tar';

export const { r, replace, create, c, list, t, extract, x } = tar;

/**
 * Appends files to an existing uncompressed tar archive asynchronously.
 *
 * @param {string} archivePath - Path to the target archive file.
 * @param {string[]} fileList - Array of file paths to append.
 * @param {object} [options={}] - Additional tar options.
 * @returns {Promise<void>} Resolves when the append operation completes.
 */
export async function appendToArchive(archivePath, fileList, options = {}) {
  return tar.r({ file: archivePath, ...options }, fileList);
}

/**
 * Appends files to an existing uncompressed tar archive synchronously.
 *
 * @param {string} archivePath - Path to the target archive file.
 * @param {string[]} fileList - Array of file paths to append.
 * @param {object} [options={}] - Additional tar options.
 */
export function appendToArchiveSync(archivePath, fileList, options = {}) {
  tar.r({ file: archivePath, sync: true, ...options }, fileList);
}

/**
 * Appends files to an existing uncompressed tar archive using callback style.
 *
 * @param {string} archivePath - Path to the target archive file.
 * @param {string[]} fileList - Array of file paths to append.
 * @param {Function} callback - Completion callback function.
 * @param {object} [options={}] - Additional tar options.
 */
export function appendToArchiveWithCallback(archivePath, fileList, callback, options = {}) {
  tar.r({ file: archivePath, ...options }, fileList, callback);
}

export default {
  r: tar.r,
  replace: tar.replace,
  appendToArchive,
  appendToArchiveSync,
  appendToArchiveWithCallback,
};

{
  "name": "sample-tar-r",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-r",
      "version": "1.0.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-r",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "tar": "6.2.1"
  }
}

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

import assert from 'node:assert/strict';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import * as tar from 'tar';
import {
  r,
  replace,
  appendToArchive,
  appendToArchiveSync,
  appendToArchiveWithCallback,
} from '../index.mjs';

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

try {
  // Helper to list entries from a tar archive
  const listEntries = (archivePath) => {
    const entries = [];
    tar.t({
      file: archivePath,
      sync: true,
      onentry: (entry) => entries.push(entry.path),
    });
    return entries;
  };

  // Helper to read file content from a tar archive
  const readEntryContent = async (archivePath, targetPath) => {
    let content = null;
    await tar.t({
      file: archivePath,
      onentry: (entry) => {
        if (entry.path === targetPath) {
          const chunks = [];
          entry.on('data', (c) => chunks.push(c));
          entry.on('end', () => {
            content = Buffer.concat(chunks).toString('utf8');
          });
        }
      },
    });
    return content;
  };

  // Contract 1: tar.r is an alias for tar.replace
  {
    assert.strictEqual(typeof r, 'function', 'r must be a function');
    assert.strictEqual(typeof replace, 'function', 'replace must be a function');
    assert.strictEqual(r, replace, 'r must be identical to replace');
    assert.strictEqual(r, tar.r, 'exported r must be tar.r');
  }

  // Contract 2: tar.r appends files to an existing uncompressed tar archive asynchronously
  {
    const fileA = path.join(tmpDir, 'fileA.txt');
    const fileB = path.join(tmpDir, 'fileB.txt');
    const archive = path.join(tmpDir, 'async-archive.tar');

    fs.writeFileSync(fileA, 'content A');
    fs.writeFileSync(fileB, 'content B');

    // Create initial archive with fileA
    tar.c({ file: archive, sync: true, cwd: tmpDir }, ['fileA.txt']);
    assert.deepStrictEqual(listEntries(archive), ['fileA.txt']);

    // Append fileB asynchronously using appendToArchive (tar.r)
    const resultPromise = appendToArchive(archive, ['fileB.txt'], { cwd: tmpDir });
    assert.ok(resultPromise instanceof Promise, 'appendToArchive should return a Promise');
    await resultPromise;

    const entries = listEntries(archive);
    assert.deepStrictEqual(entries, ['fileA.txt', 'fileB.txt']);

    const contentB = await readEntryContent(archive, 'fileB.txt');
    assert.strictEqual(contentB, 'content B');
  }

  // Contract 3: tar.r appends files to an existing uncompressed tar archive synchronously when sync option is true
  {
    const file1 = path.join(tmpDir, 'sync1.txt');
    const file2 = path.join(tmpDir, 'sync2.txt');
    const archive = path.join(tmpDir, 'sync-archive.tar');

    fs.writeFileSync(file1, 'initial sync data');
    fs.writeFileSync(file2, 'appended sync data');

    tar.c({ file: archive, sync: true, cwd: tmpDir }, ['sync1.txt']);
    assert.deepStrictEqual(listEntries(archive), ['sync1.txt']);

    appendToArchiveSync(archive, ['sync2.txt'], { cwd: tmpDir });

    const entries = listEntries(archive);
    assert.deepStrictEqual(entries, ['sync1.txt', 'sync2.txt']);

    const content2 = await readEntryContent(archive, 'sync2.txt');
    assert.strictEqual(content2, 'appended sync data');
  }

  // Contract 4: tar.r supports callback notification on completion
  {
    const fileInit = path.join(tmpDir, 'cb-init.txt');
    const fileCb = path.join(tmpDir, 'cb-append.txt');
    const archive = path.join(tmpDir, 'cb-archive.tar');

    fs.writeFileSync(fileInit, 'init');
    fs.writeFileSync(fileCb, 'callback data');

    tar.c({ file: archive, sync: true, cwd: tmpDir }, ['cb-init.txt']);

    let callbackInvoked = false;
    await new Promise((resolve, reject) => {
      appendToArchiveWithCallback(archive, ['cb-append.txt'], (err) => {
        if (err) return reject(err);
        callbackInvoked = true;
        resolve();
      }, { cwd: tmpDir });
    });

    assert.strictEqual(callbackInvoked, true, 'callback should be called on completion');
    const entries = listEntries(archive);
    assert.deepStrictEqual(entries, ['cb-init.txt', 'cb-append.txt']);
  }

  // Contract 5: tar.r resolves files relative to cwd option
  {
    const subDir = path.join(tmpDir, 'subdir');
    fs.mkdirSync(subDir, { recursive: true });
    const subFile = path.join(subDir, 'nested.txt');
    const archive = path.join(tmpDir, 'cwd-archive.tar');

    fs.writeFileSync(subFile, 'nested data');
    const baseFile = path.join(tmpDir, 'base.txt');
    fs.writeFileSync(baseFile, 'base data');

    tar.c({ file: archive, sync: true, cwd: tmpDir }, ['base.txt']);

    // Append using cwd pointing to subDir
    tar.r({ file: archive, sync: true, cwd: subDir }, ['nested.txt']);

    const entries = listEntries(archive);
    assert.deepStrictEqual(entries, ['base.txt', 'nested.txt']);
  }

  // Contract 6: tar.r throws a TypeError when file option is omitted
  {
    assert.throws(
      () => {
        tar.r({ sync: true }, ['test.txt']);
      },
      {
        name: 'TypeError',
      },
      'tar.r should throw a TypeError when file option is missing'
    );
  }

  console.log('All contracts passed.');
} finally {
  fs.rmSync(tmpDir, { recursive: true, force: true });
}