@electron/get 5.1.0

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/get@5.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40electron/get@5.1.0

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:348ad1e1b07fdf409b60974244dc32140b707026938a9716a21c9762f1a0962b","contract":["getHostArch returns non-empty host architecture string","initializeProxy initializes proxy configuration without error","ElectronDownloadCacheMode provides enum constants for cache control","downloadArtifact downloads platform artifacts via custom downloader and verifies checksums","downloadArtifact reuses cached artifact on repeated calls","downloadArtifact rejects on checksum mismatch","downloadArtifact supports generic artifact downloads with isGeneric flag","downloadArtifact supports mirrorOptions with custom resolveAssetURL"],"goal":"verify pkg:npm/%40electron/get@5.1.0","kind":"HOW","packages":["pkg:npm/%40electron/get@5.1.0"],"schemaVersion":1},"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/%40electron/get@5.1.0"],"schemaVersion":1,"subject":"pkg:npm/%40electron/get@5.1.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-electron-get",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-electron-get",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@electron/get": "5.1.0"
      }
    },
    "node_modules/@electron/get": {
      "version": "5.1.0",
      "resolved": "https://registry.npmjs.org/@electron/get/-/get-5.1.0.tgz",
      "integrity": "sha512-3kSBtG8ObcTVfXanm5vVJ6UnBLEVmVsRk1M+vGqCuMBV+XLCbJYuWQful+yIy0GQDsSlK0kHEriEHn7SPk4EnA==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.1.1",
        "env-paths": "^3.0.0",
        "graceful-fs": "^4.2.11",
        "progress": "^2.0.3",
        "semver": "^7.6.3",
        "sumchecker": "^3.0.1"
      },
      "engines": {
        "node": ">=22.12.0"
      },
      "optionalDependencies": {
        "undici": "^7.24.4"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/env-paths": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/env-paths/-/env-paths-3.0.0.tgz",
      "integrity": "sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A==",
      "license": "MIT",
      "engines": {
        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "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/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/progress": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/progress/-/progress-2.0.3.tgz",
      "integrity": "sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==",
      "license": "MIT",
      "engines": {
        "node": ">=0.4.0"
      }
    },
    "node_modules/semver": {
      "version": "7.8.5",
      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
      "license": "ISC",
      "bin": {
        "semver": "bin/semver.js"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/sumchecker": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/sumchecker/-/sumchecker-3.0.1.tgz",
      "integrity": "sha512-MvjXzkz/BOfyVDkG0oFOtBxHX2u3gKbMHIF/dXblZsgD3BWOFLmHovIpZY7BykJdAjcqRCBi1WYBNdEC9yI7vg==",
      "license": "Apache-2.0",
      "dependencies": {
        "debug": "^4.1.0"
      },
      "engines": {
        "node": ">= 8.0"
      }
    },
    "node_modules/undici": {
      "version": "7.29.0",
      "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.0.tgz",
      "integrity": "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==",
      "license": "MIT",
      "optional": true,
      "engines": {
        "node": ">=20.18.1"
      }
    }
  }
}

{
  "name": "sample-electron-get",
  "version": "1.0.0",
  "private": true,
  "license": "MIT-0",
  "main": "src/index.js",
  "dependencies": {
    "@electron/get": "5.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40electron/get@5.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40electron/get@5.1.0"
  ]
}

const {
  downloadArtifact,
  download,
  getHostArch,
  initializeProxy,
  ElectronDownloadCacheMode,
  FetchDownloader
} = require('@electron/get');

/**
 * Downloads an Electron platform artifact with custom options.
 *
 * @param {object} options - Options including version, artifactName, platform, arch, downloader, checksums, etc.
 * @returns {Promise<string>} Absolute path to downloaded artifact file.
 */
async function fetchArtifact(options) {
  return downloadArtifact(options);
}

/**
 * Downloads a generic Electron artifact by setting isGeneric to true.
 *
 * @param {object} options - Generic artifact options.
 * @returns {Promise<string>} Absolute path to downloaded artifact file.
 */
async function fetchGenericArtifact(options) {
  return downloadArtifact({
    ...options,
    isGeneric: true
  });
}

/**
 * Downloads the Electron binary for a specific version.
 *
 * @param {string} version - Electron version to download.
 * @param {object} [options] - Download options.
 * @returns {Promise<string>} Absolute path to downloaded zip file.
 */
async function fetchElectron(version, options) {
  return download(version, options);
}

module.exports = {
  downloadArtifact,
  download,
  getHostArch,
  initializeProxy,
  ElectronDownloadCacheMode,
  FetchDownloader,
  fetchArtifact,
  fetchGenericArtifact,
  fetchElectron
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import crypto from 'node:crypto';

const require = createRequire(import.meta.url);
const {
  downloadArtifact,
  download,
  getHostArch,
  initializeProxy,
  ElectronDownloadCacheMode,
  FetchDownloader,
  fetchArtifact,
  fetchGenericArtifact,
  fetchElectron
} = require('../src/index.js');

// 1. getHostArch returns non-empty host architecture string
const hostArch = getHostArch();
assert.equal(typeof hostArch, 'string', 'getHostArch must return a string');
assert.ok(hostArch.length > 0, 'getHostArch must return non-empty string');

// 2. initializeProxy initializes proxy configuration without error
assert.equal(typeof initializeProxy, 'function', 'initializeProxy must be a function');
assert.doesNotThrow(() => {
  initializeProxy();
}, 'initializeProxy should execute without throwing');

// 3. ElectronDownloadCacheMode provides enum constants for cache control
assert.strictEqual(ElectronDownloadCacheMode.ReadWrite, 0, 'ReadWrite must be 0');
assert.strictEqual(ElectronDownloadCacheMode.ReadOnly, 1, 'ReadOnly must be 1');
assert.strictEqual(ElectronDownloadCacheMode.WriteOnly, 2, 'WriteOnly must be 2');
assert.strictEqual(ElectronDownloadCacheMode.Bypass, 3, 'Bypass must be 3');

const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'electron-get-contract-'));
const cacheRoot = path.join(tempDir, 'cache');
const tempRoot = path.join(tempDir, 'temp');
fs.mkdirSync(cacheRoot, { recursive: true });
fs.mkdirSync(tempRoot, { recursive: true });

const dummyPayload = Buffer.from('offline test electron binary payload');
const dummyChecksum = crypto.createHash('sha256').update(dummyPayload).digest('hex');
const filename = 'electron-v5.1.0-linux-x64.zip';

let downloadCount = 0;
class TestDownloader {
  async download(url, targetPath, options) {
    downloadCount++;
    fs.writeFileSync(targetPath, dummyPayload);
  }
}

try {
  // 4. downloadArtifact downloads platform artifacts via custom downloader and verifies checksums
  const downloadedPath = await fetchArtifact({
    version: '5.1.0',
    artifactName: 'electron',
    platform: 'linux',
    arch: 'x64',
    cacheRoot,
    tempDirectory: tempRoot,
    downloader: new TestDownloader(),
    checksums: {
      [filename]: dummyChecksum
    },
    mirrorOptions: {
      mirror: 'https://example.com/download'
    }
  });

  assert.equal(downloadCount, 1, 'Downloader should be called once');
  assert.ok(fs.existsSync(downloadedPath), 'Downloaded file must exist');
  assert.ok(downloadedPath.endsWith(filename), 'Downloaded path must end with filename');
  assert.deepEqual(fs.readFileSync(downloadedPath), dummyPayload, 'Downloaded payload must match');

  // 5. downloadArtifact reuses cached artifact on repeated calls
  const cachedPath = await fetchArtifact({
    version: '5.1.0',
    artifactName: 'electron',
    platform: 'linux',
    arch: 'x64',
    cacheRoot,
    tempDirectory: tempRoot,
    downloader: new TestDownloader(),
    checksums: {
      [filename]: dummyChecksum
    },
    mirrorOptions: {
      mirror: 'https://example.com/download'
    }
  });
  assert.equal(downloadCount, 1, 'Downloader should not be called again when cached');
  assert.strictEqual(cachedPath, downloadedPath, 'Cached path must match downloaded path');

  // 6. downloadArtifact rejects on checksum mismatch
  const badChecksumDownloader = {
    async download(url, targetPath) {
      fs.writeFileSync(targetPath, Buffer.from('corrupt'));
    }
  };
  const badTemp = path.join(tempDir, 'bad-temp');
  fs.mkdirSync(badTemp, { recursive: true });
  await assert.rejects(
    async () => {
      await fetchArtifact({
        version: '5.1.0',
        artifactName: 'electron',
        platform: 'linux',
        arch: 'x64',
        cacheMode: ElectronDownloadCacheMode.Bypass,
        cacheRoot: path.join(tempDir, 'bad-cache'),
        tempDirectory: badTemp,
        downloader: badChecksumDownloader,
        checksums: {
          [filename]: dummyChecksum
        }
      });
    },
    (err) => err instanceof Error,
    'downloadArtifact must reject when checksum mismatches'
  );

  // 7. downloadArtifact supports generic artifact downloads with isGeneric flag
  const genericFilename = 'chromedriver-v5.1.0-linux-x64.zip';
  const genericTemp = path.join(tempDir, 'generic-temp');
  fs.mkdirSync(genericTemp, { recursive: true });
  const genericPath = await fetchGenericArtifact({
    version: '5.1.0',
    artifactName: genericFilename,
    cacheRoot,
    tempDirectory: genericTemp,
    downloader: new TestDownloader(),
    unsafelyDisableChecksums: true
  });
  assert.equal(downloadCount, 2, 'Downloader should be called for generic artifact');
  assert.ok(fs.existsSync(genericPath), 'Generic artifact file must exist');
  assert.ok(genericPath.endsWith(genericFilename), 'Generic artifact path must match artifactName');

  // 8. downloadArtifact supports mirrorOptions with custom resolveAssetURL
  let resolvedUrl = null;
  const urlCaptureDownloader = {
    async download(url, targetPath) {
      resolvedUrl = url;
      fs.writeFileSync(targetPath, dummyPayload);
    }
  };
  const mirrorTemp = path.join(tempDir, 'mirror-temp');
  fs.mkdirSync(mirrorTemp, { recursive: true });
  await fetchArtifact({
    version: '5.1.0',
    artifactName: 'electron',
    platform: 'linux',
    arch: 'x64',
    cacheMode: ElectronDownloadCacheMode.Bypass,
    cacheRoot: path.join(tempDir, 'mirror-cache'),
    tempDirectory: mirrorTemp,
    downloader: urlCaptureDownloader,
    unsafelyDisableChecksums: true,
    mirrorOptions: {
      resolveAssetURL: async (opts) => `https://example.com/custom/${opts.version}/${opts.artifactName}`
    }
  });
  assert.strictEqual(resolvedUrl, 'https://example.com/custom/v5.1.0/electron', 'Custom URL resolver should be called');

  console.log('Contract tests passed successfully.');
} finally {
  fs.rmSync(tempDir, { recursive: true, force: true });
}