@electron/asar 3.4.1: uncache

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 @electron/asar.uncache in 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.uncache

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:b56c3e00ee2ea341d0faea06a17acb3ecc17614e89c5fe04335570cce23872f2","contract":["@electron/asar.uncache removes the cached filesystem entry for the specified archive path and returns true if cached","@electron/asar.uncache returns false when called for an archive path that is not currently cached","@electron/asar.uncache returns false when called multiple times consecutively for the same archive path","@electron/asar.uncache invalidates cached filesystem after archive inspection via statFile or listPackage"],"goal":"verify @electron/asar.uncache in pkg:npm/%40electron/asar@3.4.1","kind":"HOW","packages":["pkg:npm/%40electron/asar@3.4.1"],"schemaVersion":1,"symbols":["@electron/asar.uncache"]},"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.uncache"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

function uncacheArchive(archivePath) {
  return asar.uncache(archivePath);
}

function uncacheAllArchives() {
  asar.uncacheAll();
}

module.exports = {
  uncacheArchive,
  uncacheAllArchives,
  asar
};

{
  "name": "sample-electron-asar-uncache",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-electron-asar-uncache",
      "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-uncache",
  "version": "1.0.0",
  "private": true,
  "description": "verify @electron/asar.uncache 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 @electron/asar.uncache in pkg:npm/%40electron/asar@3.4.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40electron/asar@3.4.1"
  ],
  "symbols": [
    "@electron/asar.uncache"
  ]
}

'use strict';

const assert = require('assert');
const fs = require('fs');
const path = require('path');
const os = require('os');
const asar = require('@electron/asar');
const { uncacheArchive, uncacheAllArchives } = require('../index.js');

async function run() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'asar-uncache-contract-'));
  const srcDir = path.join(tmpDir, 'source');
  const asarPath = path.join(tmpDir, 'test-archive.asar');
  const nonExistentPath = path.join(tmpDir, 'non-existent.asar');

  try {
    fs.mkdirSync(path.join(srcDir, 'subdir'), { recursive: true });
    fs.writeFileSync(path.join(srcDir, 'hello.txt'), 'Hello ASAR uncache test', 'utf8');
    fs.writeFileSync(
      path.join(srcDir, 'subdir', 'data.json'),
      JSON.stringify({ active: true }),
      'utf8'
    );

    await asar.createPackage(srcDir, asarPath);
    assert.strictEqual(fs.existsSync(asarPath), true, 'ASAR file must be created');

    // 1. @electron/asar.uncache returns false when called for an archive path that is not currently cached
    const uncacheInitial = asar.uncache(asarPath);
    assert.strictEqual(
      uncacheInitial,
      false,
      'uncache must return false before archive filesystem has been cached'
    );

    // Also verify non-existent archive path returns false
    const uncacheNonExistent = asar.uncache(nonExistentPath);
    assert.strictEqual(
      uncacheNonExistent,
      false,
      'uncache must return false for non-existent archive path'
    );

    // 2. @electron/asar.uncache removes the cached filesystem entry for the specified archive path and returns true if cached
    // Reading archive entries caches the filesystem
    const entries = asar.listPackage(asarPath);
    assert.ok(Array.isArray(entries), 'listPackage must return array of entries');
    assert.ok(entries.includes('/hello.txt'), 'listPackage must include hello.txt');

    const uncacheAfterList = asar.uncache(asarPath);
    assert.strictEqual(
      uncacheAfterList,
      true,
      'uncache must return true after listPackage populated the filesystem cache'
    );

    // 3. @electron/asar.uncache returns false when called multiple times consecutively for the same archive path
    const uncacheSecondCall = asar.uncache(asarPath);
    assert.strictEqual(
      uncacheSecondCall,
      false,
      'consecutive uncache call must return false since archive is no longer cached'
    );

    // 4. @electron/asar.uncache invalidates cached filesystem after archive inspection via statFile or listPackage
    // Inspecting file with statFile caches the filesystem again
    const statInfo = asar.statFile(asarPath, 'hello.txt');
    assert.strictEqual(typeof statInfo, 'object', 'statFile must return file info object');
    assert.strictEqual(
      statInfo.size,
      Buffer.byteLength('Hello ASAR uncache test'),
      'statFile must report correct file size'
    );

    // Helper uncacheArchive removes the cached filesystem entry
    const helperUncache = uncacheArchive(asarPath);
    assert.strictEqual(
      helperUncache,
      true,
      'helper uncacheArchive must return true for cached archive'
    );

    const helperUncacheAgain = uncacheArchive(asarPath);
    assert.strictEqual(
      helperUncacheAgain,
      false,
      'helper uncacheArchive must return false when already uncached'
    );

    // 5. Verify uncacheAll removes any cached archives without error
    asar.listPackage(asarPath);
    uncacheAllArchives();
    const uncacheAfterAll = asar.uncache(asarPath);
    assert.strictEqual(
      uncacheAfterAll,
      false,
      'uncache must return false after uncacheAll cleared all cached filesystems'
    );

    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 errors
    }
  }
}

run().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});