@electron/asar 3.4.1: createPackage, extractAll, extractFile

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/%40electron/asar@3.4.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40electron/asar@3.4.1
Demonstrate these symbols/APIs:
  - @electron/asar.createPackage
  - @electron/asar.extractAll
  - @electron/asar.extractFile
  - @electron/asar.listPackage
  - @electron/asar.statFile

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:be646b456110b8fa3e833368345c170eee86682bf727d92e3606e140adb90dc8","constraints":{"executionContext":"node"},"contract":["@electron/asar.createPackage asynchronously archives a directory into an ASAR file","@electron/asar.listPackage lists all entry paths inside an ASAR archive","@electron/asar.statFile returns metadata including size and offset for a file entry in an ASAR archive","@electron/asar.extractFile extracts a single file from an ASAR archive as a Buffer","@electron/asar.extractAll extracts all files and directories from an ASAR archive to a destination directory"],"goal":"verify pkg:npm/%40electron/asar@3.4.1","kind":"HOW","packages":["pkg:npm/%40electron/asar@3.4.1"],"schemaVersion":1,"symbols":["@electron/asar.createPackage","@electron/asar.extractAll","@electron/asar.extractFile","@electron/asar.listPackage","@electron/asar.statFile"]},"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/%40electron/asar@3.4.1"],"schemaVersion":1,"subject":"pkg:npm/%40electron/asar@3.4.1","symbols":["@electron/asar.createPackage","@electron/asar.extractAll","@electron/asar.extractFile","@electron/asar.listPackage","@electron/asar.statFile"],"verifierAdapter":"node-typescript@1"}

'use strict';

const asar = require('@electron/asar');

async function createArchive(srcPath, destPath) {
  await asar.createPackage(srcPath, destPath);
}

function listArchive(archivePath) {
  return asar.listPackage(archivePath);
}

function statArchiveFile(archivePath, filename) {
  return asar.statFile(archivePath, filename);
}

function extractArchiveFile(archivePath, filename) {
  return asar.extractFile(archivePath, filename);
}

function extractArchiveAll(archivePath, destPath) {
  asar.extractAll(archivePath, destPath);
}

module.exports = {
  createArchive,
  listArchive,
  statArchiveFile,
  extractArchiveFile,
  extractArchiveAll,
  asar
};

{
  "name": "sample-electron-asar",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-electron-asar",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@electron/asar": "3.4.1"
      }
    },
    "node_modules/@electron/asar": {
      "version": "3.4.1",
      "resolved": "https://registry.npmjs.org/@electron/asar/-/asar-3.4.1.tgz",
      "integrity": "sha512-i4/rNPRS84t0vSRa2HorerGRXWyF4vThfHesw0dmcWHp+cspK743UanA0suA5Q5y8kzY2y6YKrvbIUn69BCAiA==",
      "license": "MIT",
      "dependencies": {
        "commander": "^5.0.0",
        "glob": "^7.1.6",
        "minimatch": "^3.0.4"
      },
      "bin": {
        "asar": "bin/asar.js"
      },
      "engines": {
        "node": ">=10.12.0"
      }
    },
    "node_modules/balanced-match": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
      "license": "MIT"
    },
    "node_modules/brace-expansion": {
      "version": "1.1.18",
      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
      }
    },
    "node_modules/commander": {
      "version": "5.1.0",
      "resolved": "https://registry.npmjs.org/commander/-/commander-5.1.0.tgz",
      "integrity": "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==",
      "license": "MIT",
      "engines": {
        "node": ">= 6"
      }
    },
    "node_modules/concat-map": {
      "version": "0.0.1",
      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
      "license": "MIT"
    },
    "node_modules/fs.realpath": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
      "license": "ISC"
    },
    "node_modules/glob": {
      "version": "7.2.3",
      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
      "license": "ISC",
      "dependencies": {
        "fs.realpath": "^1.0.0",
        "inflight": "^1.0.4",
        "inherits": "2",
        "minimatch": "^3.1.1",
        "once": "^1.3.0",
        "path-is-absolute": "^1.0.0"
      },
      "engines": {
        "node": "*"
      }
    },
    "node_modules/inflight": {
      "version": "1.0.6",
      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
      "license": "ISC",
      "dependencies": {
        "once": "^1.3.0",
        "wrappy": "1"
      }
    },
    "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/minimatch": {
      "version": "3.1.5",
      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
      "license": "ISC",
      "dependencies": {
        "brace-expansion": "^1.1.7"
      },
      "engines": {
        "node": "*"
      }
    },
    "node_modules/once": {
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
      "license": "ISC",
      "dependencies": {
        "wrappy": "1"
      }
    },
    "node_modules/path-is-absolute": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/wrappy": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-electron-asar",
  "version": "1.0.0",
  "private": true,
  "description": "verify @electron/asar in pkg:npm/%40electron/asar@3.4.1",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "@electron/asar": "3.4.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40electron/asar@3.4.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40electron/asar@3.4.1"
  ],
  "symbols": [
    "@electron/asar.createPackage",
    "@electron/asar.extractAll",
    "@electron/asar.extractFile",
    "@electron/asar.listPackage",
    "@electron/asar.statFile"
  ]
}

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const asar = require('@electron/asar');
const {
  createArchive,
  listArchive,
  statArchiveFile,
  extractArchiveFile,
  extractArchiveAll
} = require('../index.js');

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'asar-contract-test-'));
  const srcDir = path.join(tmpDir, 'source');
  const destDir = path.join(tmpDir, 'extracted');
  const asarPath = path.join(tmpDir, 'app.asar');

  try {
    // Setup test source files
    fs.mkdirSync(path.join(srcDir, 'nested'), { recursive: true });
    fs.writeFileSync(path.join(srcDir, 'hello.txt'), 'Hello ASAR archive!', 'utf8');
    fs.writeFileSync(
      path.join(srcDir, 'nested', 'config.json'),
      JSON.stringify({ enabled: true, count: 42 }),
      'utf8'
    );

    // 1. Contract: @electron/asar.createPackage asynchronously archives a directory into an ASAR file
    await asar.createPackage(srcDir, asarPath);
    assert.strictEqual(fs.existsSync(asarPath), true, 'ASAR file should be created');
    assert.ok(fs.statSync(asarPath).size > 0, 'ASAR file should not be empty');

    // Also test helper function
    const helperAsarPath = path.join(tmpDir, 'helper.asar');
    await createArchive(srcDir, helperAsarPath);
    assert.strictEqual(fs.existsSync(helperAsarPath), true, 'Helper createArchive should create ASAR');

    // 2. Contract: @electron/asar.listPackage lists all entry paths inside an ASAR archive
    const entries = asar.listPackage(asarPath);
    assert.ok(Array.isArray(entries), 'listPackage must return an array');
    assert.ok(entries.includes('/hello.txt'), 'listPackage should include root file /hello.txt');
    assert.ok(entries.includes('/nested'), 'listPackage should include nested directory /nested');
    assert.ok(
      entries.includes('/nested/config.json'),
      'listPackage should include nested file /nested/config.json'
    );

    const helperEntries = listArchive(asarPath);
    assert.deepStrictEqual(helperEntries, entries, 'Helper listArchive must return identical entries');

    // 3. Contract: @electron/asar.statFile returns metadata including size and offset for a file entry in an ASAR archive
    const statRoot = asar.statFile(asarPath, 'hello.txt');
    assert.strictEqual(typeof statRoot, 'object', 'statFile should return an object');
    assert.strictEqual(statRoot.size, Buffer.byteLength('Hello ASAR archive!'), 'statFile should report correct size');
    assert.ok(typeof statRoot.offset === 'string' || typeof statRoot.offset === 'number', 'statFile should include offset');

    const statNested = asar.statFile(asarPath, 'nested/config.json');
    assert.strictEqual(typeof statNested, 'object', 'statFile should return object for nested path');
    assert.strictEqual(
      statNested.size,
      Buffer.byteLength(JSON.stringify({ enabled: true, count: 42 })),
      'statFile should report correct nested file size'
    );

    const helperStat = statArchiveFile(asarPath, 'hello.txt');
    assert.deepStrictEqual(helperStat, statRoot, 'Helper statArchiveFile should return identical stat info');

    // 4. Contract: @electron/asar.extractFile extracts a single file from an ASAR archive as a Buffer
    const bufferRoot = asar.extractFile(asarPath, 'hello.txt');
    assert.ok(Buffer.isBuffer(bufferRoot), 'extractFile must return a Buffer');
    assert.strictEqual(bufferRoot.toString('utf8'), 'Hello ASAR archive!', 'extractFile content must match');

    const bufferNested = asar.extractFile(asarPath, 'nested/config.json');
    assert.ok(Buffer.isBuffer(bufferNested), 'extractFile for nested file must return a Buffer');
    assert.deepStrictEqual(
      JSON.parse(bufferNested.toString('utf8')),
      { enabled: true, count: 42 },
      'extractFile nested content must match JSON data'
    );

    const helperBuffer = extractArchiveFile(asarPath, 'hello.txt');
    assert.deepStrictEqual(helperBuffer, bufferRoot, 'Helper extractArchiveFile must return identical buffer');

    // 5. Contract: @electron/asar.extractAll extracts all files and directories from an ASAR archive to a destination directory
    asar.extractAll(asarPath, destDir);
    assert.strictEqual(
      fs.existsSync(path.join(destDir, 'hello.txt')),
      true,
      'extractAll should extract hello.txt'
    );
    assert.strictEqual(
      fs.readFileSync(path.join(destDir, 'hello.txt'), 'utf8'),
      'Hello ASAR archive!',
      'Extracted hello.txt content should match'
    );
    assert.strictEqual(
      fs.existsSync(path.join(destDir, 'nested', 'config.json')),
      true,
      'extractAll should extract nested/config.json'
    );
    assert.strictEqual(
      fs.readFileSync(path.join(destDir, 'nested', 'config.json'), 'utf8'),
      JSON.stringify({ enabled: true, count: 42 }),
      'Extracted nested/config.json content should match'
    );

    // Also test helper function for extractAll
    const helperDestDir = path.join(tmpDir, 'helper-extracted');
    extractArchiveAll(asarPath, helperDestDir);
    assert.strictEqual(
      fs.readFileSync(path.join(helperDestDir, 'hello.txt'), 'utf8'),
      'Hello ASAR archive!',
      'Helper extractArchiveAll should extract files correctly'
    );

    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);
});