unzipper 0.12.5: Extract, Open.buffer, Open.file

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/unzipper@0.12.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/unzipper@0.12.5
Demonstrate these symbols/APIs:
  - unzipper.Extract
  - unzipper.Open.buffer
  - unzipper.Open.file

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:1294089154e6c925cccd413e8ccef46ae33fc5828fad2be2766e8e177f2bc7ed","constraints":{"executionContext":"node"},"contract":["unzipper.Open.buffer reads a ZIP archive from a Buffer and resolves a Directory with file entries","unzipper.Open.file reads a ZIP archive from disk and resolves a Directory with file entries","unzipper.Extract creates a writable stream that extracts archive contents to a target directory","unzipper directory entries provide a buffer() method returning entry content Buffer"],"goal":"verify pkg:npm/unzipper@0.12.5","kind":"HOW","packages":["pkg:npm/unzipper@0.12.5"],"schemaVersion":1,"symbols":["unzipper.Extract","unzipper.Open.buffer","unzipper.Open.file"]},"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/unzipper@0.12.5"],"schemaVersion":1,"subject":"pkg:npm/unzipper@0.12.5","symbols":["unzipper.Extract","unzipper.Open.buffer","unzipper.Open.file"],"verifierAdapter":"node-typescript@1"}

'use strict';

const fs = require('fs');
const unzipper = require('unzipper');

/**
 * Opens a zip archive from an in-memory buffer.
 * @param {Buffer} buffer - Buffer containing zip archive data.
 * @returns {Promise<unzipper.Directory>}
 */
async function openBuffer(buffer) {
  return await unzipper.Open.buffer(buffer);
}

/**
 * Opens a zip archive from a file path on disk.
 * @param {string} filePath - Path to zip archive.
 * @returns {Promise<unzipper.Directory>}
 */
async function openFile(filePath) {
  return await unzipper.Open.file(filePath);
}

/**
 * Extracts a zip archive from a file to a destination directory.
 * @param {string} zipPath - Path to zip archive.
 * @param {string} targetDir - Destination directory.
 * @returns {Promise<void>}
 */
function extractToDirectory(zipPath, targetDir) {
  return new Promise((resolve, reject) => {
    fs.createReadStream(zipPath)
      .pipe(unzipper.Extract({ path: targetDir }))
      .on('close', resolve)
      .on('error', reject);
  });
}

module.exports = {
  openBuffer,
  openFile,
  extractToDirectory,
  unzipper
};

{
  "name": "sample-unzipper",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-unzipper",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "unzipper": "0.12.5"
      }
    },
    "node_modules/bluebird": {
      "version": "3.7.2",
      "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz",
      "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==",
      "license": "MIT"
    },
    "node_modules/core-util-is": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
      "license": "MIT"
    },
    "node_modules/duplexer2": {
      "version": "0.1.4",
      "resolved": "https://registry.npmjs.org/duplexer2/-/duplexer2-0.1.4.tgz",
      "integrity": "sha512-asLFVfWWtJ90ZyOUHMqk7/S2w2guQKxUI2itj3d92ADHhxUSbCMGi1f1cBcJ7xM1To+pE/Khbwo1yuNbMEPKeA==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "readable-stream": "^2.0.2"
      }
    },
    "node_modules/fs-extra": {
      "version": "11.3.1",
      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.1.tgz",
      "integrity": "sha512-eXvGGwZ5CL17ZSwHWd3bbgk7UUpF6IFHtP57NYYakPvHOs8GDgDe5KJI36jIJzDkJ6eJjuzRA8eBQb6SkKue0g==",
      "license": "MIT",
      "dependencies": {
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
        "universalify": "^2.0.0"
      },
      "engines": {
        "node": ">=14.14"
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.11",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    },
    "node_modules/inherits": {
      "version": "2.0.4",
      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
      "license": "ISC"
    },
    "node_modules/isarray": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
      "license": "MIT"
    },
    "node_modules/jsonfile": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
      "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
      "license": "MIT",
      "dependencies": {
        "universalify": "^2.0.0"
      },
      "optionalDependencies": {
        "graceful-fs": "^4.1.6"
      }
    },
    "node_modules/node-int64": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/node-int64/-/node-int64-0.4.0.tgz",
      "integrity": "sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw==",
      "license": "MIT"
    },
    "node_modules/process-nextick-args": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==",
      "license": "MIT"
    },
    "node_modules/readable-stream": {
      "version": "2.3.8",
      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
      "license": "MIT",
      "dependencies": {
        "core-util-is": "~1.0.0",
        "inherits": "~2.0.3",
        "isarray": "~1.0.0",
        "process-nextick-args": "~2.0.0",
        "safe-buffer": "~5.1.1",
        "string_decoder": "~1.1.1",
        "util-deprecate": "~1.0.1"
      }
    },
    "node_modules/safe-buffer": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
      "license": "MIT"
    },
    "node_modules/string_decoder": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
      "license": "MIT",
      "dependencies": {
        "safe-buffer": "~5.1.0"
      }
    },
    "node_modules/universalify": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
      "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
      "license": "MIT",
      "engines": {
        "node": ">= 10.0.0"
      }
    },
    "node_modules/unzipper": {
      "version": "0.12.5",
      "resolved": "https://registry.npmjs.org/unzipper/-/unzipper-0.12.5.tgz",
      "integrity": "sha512-tXYOi9R57Uj/2Z25SOs5RRSzq886MBQj2gY8dPL+xl/kv6s6SvByoKfAtvfVeEuhntWDgjd2o9p2lb4TVPAz0A==",
      "license": "MIT",
      "dependencies": {
        "bluebird": "~3.7.2",
        "duplexer2": "~0.1.4",
        "fs-extra": "11.3.1",
        "graceful-fs": "^4.2.2",
        "node-int64": "^0.4.0"
      }
    },
    "node_modules/util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-unzipper",
  "version": "1.0.0",
  "private": true,
  "description": "verify pkg:npm/unzipper@0.12.5",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "unzipper": "0.12.5"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/unzipper@0.12.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/unzipper@0.12.5"
  ],
  "symbols": [
    "unzipper.Extract",
    "unzipper.Open.buffer",
    "unzipper.Open.file"
  ]
}

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const zlib = require('zlib');
const unzipper = require('unzipper');
const { openBuffer, openFile, extractToDirectory } = require('../index.js');

/**
 * Creates a valid in-memory zip archive buffer without external dependencies.
 * @param {Array<{name: string, content: string}>} entries
 * @returns {Buffer}
 */
function createZipBuffer(entries) {
  const localHeaders = [];
  const cdHeaders = [];
  let offset = 0;

  for (const entry of entries) {
    const nameBuf = Buffer.from(entry.name, 'utf8');
    const dataBuf = Buffer.from(entry.content, 'utf8');
    const crc = zlib.crc32(dataBuf);
    const size = dataBuf.length;

    // Local file header (30 bytes + name + data)
    const lh = Buffer.alloc(30 + nameBuf.length + size);
    lh.writeUInt32LE(0x04034b50, 0); // signature
    lh.writeUInt16LE(10, 4); // version needed to extract
    lh.writeUInt16LE(0, 6); // flags
    lh.writeUInt16LE(0, 8); // compression method (0 = stored)
    lh.writeUInt16LE(0, 10); // mod time
    lh.writeUInt16LE(0, 12); // mod date
    lh.writeUInt32LE(crc, 14); // crc-32
    lh.writeUInt32LE(size, 18); // compressed size
    lh.writeUInt32LE(size, 22); // uncompressed size
    lh.writeUInt16LE(nameBuf.length, 26); // filename length
    lh.writeUInt16LE(0, 28); // extra field length
    nameBuf.copy(lh, 30);
    dataBuf.copy(lh, 30 + nameBuf.length);
    localHeaders.push(lh);

    // Central directory header (46 bytes + name)
    const cdh = Buffer.alloc(46 + nameBuf.length);
    cdh.writeUInt32LE(0x02014b50, 0); // signature
    cdh.writeUInt16LE(20, 4); // version made by
    cdh.writeUInt16LE(10, 6); // version needed to extract
    cdh.writeUInt16LE(0, 8); // flags
    cdh.writeUInt16LE(0, 10); // compression method
    cdh.writeUInt16LE(0, 12); // mod time
    cdh.writeUInt16LE(0, 14); // mod date
    cdh.writeUInt32LE(crc, 16); // crc-32
    cdh.writeUInt32LE(size, 20); // compressed size
    cdh.writeUInt32LE(size, 24); // uncompressed size
    cdh.writeUInt16LE(nameBuf.length, 28); // filename length
    cdh.writeUInt16LE(0, 30); // extra field length
    cdh.writeUInt16LE(0, 32); // comment length
    cdh.writeUInt16LE(0, 34); // disk number start
    cdh.writeUInt16LE(0, 36); // internal attributes
    cdh.writeUInt32LE(0, 38); // external attributes
    cdh.writeUInt32LE(offset, 42); // relative offset of local header
    nameBuf.copy(cdh, 46);
    cdHeaders.push(cdh);

    offset += lh.length;
  }

  const cdOffset = offset;
  const cdSize = cdHeaders.reduce((acc, b) => acc + b.length, 0);

  // End of central directory record (22 bytes)
  const eocd = Buffer.alloc(22);
  eocd.writeUInt32LE(0x06054b50, 0); // signature
  eocd.writeUInt16LE(0, 4); // disk number
  eocd.writeUInt16LE(0, 6); // disk number of CD start
  eocd.writeUInt16LE(entries.length, 8); // entries on disk
  eocd.writeUInt16LE(entries.length, 10); // total entries
  eocd.writeUInt32LE(cdSize, 12); // size of CD
  eocd.writeUInt32LE(cdOffset, 16); // offset of CD
  eocd.writeUInt16LE(0, 20); // comment length

  return Buffer.concat([...localHeaders, ...cdHeaders, eocd]);
}

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'unzipper-contract-test-'));
  const zipFilePath = path.join(tmpDir, 'test-archive.zip');
  const extractDirPath = path.join(tmpDir, 'extracted');

  try {
    const fileEntries = [
      { name: 'hello.txt', content: 'Hello, World!' },
      { name: 'nested/config.json', content: '{"active":true,"count":42}' }
    ];

    const zipBuffer = createZipBuffer(fileEntries);
    fs.writeFileSync(zipFilePath, zipBuffer);

    // 1. Contract: unzipper.Open.buffer
    const dirFromBuffer = await unzipper.Open.buffer(zipBuffer);
    assert(dirFromBuffer !== null && typeof dirFromBuffer === 'object', 'Open.buffer must return Directory object');
    assert.strictEqual(dirFromBuffer.files.length, 2, 'Open.buffer must find 2 files in archive');

    const file1 = dirFromBuffer.files.find(f => f.path === 'hello.txt');
    assert(file1 !== undefined, 'hello.txt must exist in Directory.files');
    const content1 = await file1.buffer();
    assert.strictEqual(content1.toString('utf8'), 'Hello, World!', 'hello.txt content must match');

    const file2 = dirFromBuffer.files.find(f => f.path === 'nested/config.json');
    assert(file2 !== undefined, 'nested/config.json must exist in Directory.files');
    const content2 = await file2.buffer();
    assert.strictEqual(content2.toString('utf8'), '{"active":true,"count":42}', 'nested/config.json content must match');

    // 2. Contract: unzipper.Open.file
    const dirFromFile = await unzipper.Open.file(zipFilePath);
    assert(dirFromFile !== null && typeof dirFromFile === 'object', 'Open.file must return Directory object');
    assert.strictEqual(dirFromFile.files.length, 2, 'Open.file must find 2 files in archive');

    const diskFile1 = dirFromFile.files.find(f => f.path === 'hello.txt');
    assert(diskFile1 !== undefined, 'diskFile1 must exist in Directory.files');
    const diskContent1 = await diskFile1.buffer();
    assert.strictEqual(diskContent1.toString('utf8'), 'Hello, World!', 'Open.file content must match');

    // 3. Contract: unzipper.Extract
    await new Promise((resolve, reject) => {
      fs.createReadStream(zipFilePath)
        .pipe(unzipper.Extract({ path: extractDirPath }))
        .on('close', resolve)
        .on('error', reject);
    });

    const extractedFile1 = path.join(extractDirPath, 'hello.txt');
    const extractedFile2 = path.join(extractDirPath, 'nested', 'config.json');
    assert.strictEqual(fs.existsSync(extractedFile1), true, 'Extracted hello.txt must exist on disk');
    assert.strictEqual(fs.existsSync(extractedFile2), true, 'Extracted nested/config.json must exist on disk');
    assert.strictEqual(fs.readFileSync(extractedFile1, 'utf8'), 'Hello, World!', 'Extracted file content must match');
    assert.strictEqual(fs.readFileSync(extractedFile2, 'utf8'), '{"active":true,"count":42}', 'Extracted nested content must match');

    // 4. Contract: module helpers (openBuffer, openFile, extractToDirectory)
    const helperBufferDir = await openBuffer(zipBuffer);
    assert.strictEqual(helperBufferDir.files.length, 2, 'openBuffer helper must return directory with 2 files');

    const helperFileDir = await openFile(zipFilePath);
    assert.strictEqual(helperFileDir.files.length, 2, 'openFile helper must return directory with 2 files');

    const helperExtractDir = path.join(tmpDir, 'extracted-helper');
    await extractToDirectory(zipFilePath, helperExtractDir);
    assert.strictEqual(fs.existsSync(path.join(helperExtractDir, 'hello.txt')), true, 'extractToDirectory helper must extract files');

    console.log('Contract tests 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);
});