@driftengine/package 3.61.0

package/bin/drift-package.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * The `drift-package` executable.
+ *
+ * JavaScript because npm's `bin` runs under plain Node, starting a CLI that is TypeScript because
+ * everything else in this repository is. `tsx` is the same bridge `scripts/` uses.
+ *
+ * **`tsx` is launched with this Node and never through `npx`, and that is not a preference.** On
+ * Windows `npx` is `npx.cmd`, and a `.cmd` is not something `CreateProcess` knows how to launch: it
+ * needs `cmd.exe`, that is `shell: true`, which reopens quoting on the one platform where paths
+ * contain spaces as a matter of course. Without it `spawnSync` fails with `ENOENT`, leaves `status`
+ * at `null`, and a bare `status ?? 1` exits 1 **printing nothing at all** — because the reason is in
+ * `result.error`, which nothing read. Reported from a Windows VM, where it presented as
+ *
+ *     > node scripts/package.mjs doctor
+ *     npm run package:doctor failed with exit code 1.
+ *
+ * and above that line, the nothing that invited you to read. It cost a consumer half a day and is
+ * most of why they wrote a launcher of their own instead of using this one.
+ *
+ * Launching the Node that is already running answers all of it: no shell, no `.cmd`, no npx
+ * resolution, and the copy of `tsx` is the one this project locked rather than whichever npx finds.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const cli = fileURLToPath(new URL('../src/cli.ts', import.meta.url));
+
+/**
+ * `tsx`'s own entry point, read from the `bin` it declares.
+ *
+ * Not a path written here: a version of tsx that moves its entry would then break this file
+ * silently, and this is the layer whose failures are hardest to see.
+ */
+function tsxEntry() {
+  let manifest;
+  try {
+    manifest = require.resolve('tsx/package.json');
+  } catch {
+    console.error(
+      'tsx is not installed. drift-package runs its TypeScript CLI through it; install the ' +
+        "packager's dependencies and try again.",
+    );
+    process.exit(1);
+  }
+  const bin = JSON.parse(readFileSync(manifest, 'utf8')).bin;
+  const relative = typeof bin === 'string' ? bin : bin?.tsx;
+  if (typeof relative !== 'string') {
+    console.error(`${manifest} declares no \`bin\` that can be launched.`);
+    process.exit(1);
+  }
+  const entry = path.join(path.dirname(manifest), relative);
+  if (!existsSync(entry)) {
+    console.error(`${entry} is missing, so tsx is installed but incomplete. Reinstall it.`);
+    process.exit(1);
+  }
+  return entry;
+}
+
+const result = spawnSync(process.execPath, [tsxEntry(), cli, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+/*
+ * **`spawnSync` does not throw**, and leaving this out is what made the bug above invisible. A
+ * process that never starts leaves `status` at `null` and puts the reason in `result.error`, so a
+ * bare `process.exit(status ?? 1)` turns "I could not launch anything" into "it failed with 1" —
+ * the same exit as a real failure, with nothing above it to read.
+ */
+if (result.error !== undefined) {
+  console.error(`drift-package could not launch ${process.execPath}: ${String(result.error)}`);
+  process.exit(1);
+}
+if (result.signal !== null && result.signal !== undefined) {
+  console.error(`drift-package was terminated by signal ${result.signal}.`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/dist/android.d.ts

@@ -0,0 +1,18 @@
+import type { PackageManifest } from './manifest.ts';
+import type { ResourceOptions } from './resources.ts';
+/**
+ * An installable APK, from the same web build the desktop shell runs.
+ *
+ * **The Gradle project is a template that is copied, never built in place.** A consumer's game is
+ * tens of megabytes of assets; copying it into `packages/package/android/` would put it in this
+ * repository's working tree, and a `git status` after one build would be unreadable. So the
+ * template is staged into `out/android/project` and the build happens there.
+ *
+ * **Signed with a throwaway key, on purpose and stated loudly.** Android refuses to install an
+ * unsigned APK at all, so there is no "unsigned" option to offer — the choice is between a key
+ * this generates and a key a person owns. A generated one installs on a device with developer mode
+ * on, which is what this is for; it cannot go to the Play Store, and an upgrade signed with a
+ * *different* generated key is refused by the device as an impostor. `DRIFT_ANDROID_KEYSTORE` and
+ * its two passwords take over the moment somebody has a real one.
+ */
+export declare function buildAndroid(manifest: PackageManifest, projectDir: string, outDir: string, options?: ResourceOptions): Promise<void>;

package/dist/android.js

@@ -0,0 +1,207 @@
+import { spawn } from 'node:child_process';
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { build as esbuild } from 'esbuild';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resourceDir } from './resources.js';
+import { missingReferences } from './mobile/assetCheck.js';
+import { versionCodeFor } from './mobile/versionCode.js';
+import { androidToolchain, toolchainHome } from './toolchain.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * An installable APK, from the same web build the desktop shell runs.
+ *
+ * **The Gradle project is a template that is copied, never built in place.** A consumer's game is
+ * tens of megabytes of assets; copying it into `packages/package/android/` would put it in this
+ * repository's working tree, and a `git status` after one build would be unreadable. So the
+ * template is staged into `out/android/project` and the build happens there.
+ *
+ * **Signed with a throwaway key, on purpose and stated loudly.** Android refuses to install an
+ * unsigned APK at all, so there is no "unsigned" option to offer — the choice is between a key
+ * this generates and a key a person owns. A generated one installs on a device with developer mode
+ * on, which is what this is for; it cannot go to the Play Store, and an upgrade signed with a
+ * *different* generated key is refused by the device as an impostor. `DRIFT_ANDROID_KEYSTORE` and
+ * its two passwords take over the moment somebody has a real one.
+ */
+export async function buildAndroid(manifest, projectDir, outDir, options = {}) {
+    const toolchain = await androidToolchain();
+    if (toolchain === null) {
+        throw new Error('the Android toolchain is not here yet. Run `drift-package bootstrap --target=android`, ' +
+            'which fetches a JDK, the SDK and Gradle into a cache; or set JAVA_HOME and ANDROID_HOME ' +
+            'to ones you already have.');
+    }
+    const projectRoot = join(outDir, 'project');
+    await rm(projectRoot, { recursive: true, force: true });
+    await mkdir(projectRoot, { recursive: true });
+    await cp(await resourceDir('android', options.resourceRoot), projectRoot, { recursive: true });
+    /*
+     * **The game goes at the asset root**, because that is where its own absolute references point.
+     * See the comment in `MainActivity.java`: a build served from a subdirectory loads its HTML and
+     * nothing else.
+     */
+    const assets = join(projectRoot, 'app', 'src', 'main', 'assets');
+    await mkdir(assets, { recursive: true });
+    const distDir = resolve(projectDir, dirname(manifest.entry));
+    await cp(distDir, assets, { recursive: true });
+    await checkAssetReferences(assets, basename(manifest.entry));
+    /*
+     * The shim is bundled as an IIFE rather than a module: it is evaluated as a document-start
+     * script by the WebView, which is a bare script rather than a module context.
+     */
+    await esbuild({
+        stdin: {
+            contents: `import { attachShim } from ${JSON.stringify(join(HERE, 'mobile', 'bridgeShim.ts'))};\nattachShim('__driftHost');\n`,
+            resolveDir: HERE,
+            loader: 'ts',
+        },
+        outfile: join(assets, 'drift-host', 'shim.js'),
+        bundle: true,
+        format: 'iife',
+        platform: 'browser',
+        target: 'es2022',
+        logLevel: 'warning',
+    });
+    if (manifest.icon !== null) {
+        /* One PNG at one density: Android scales it for the rest, and a game that wants a full set
+           supplies its own `res/` through its own build rather than through this. */
+        await cp(resolve(projectDir, manifest.icon), join(projectRoot, 'app', 'src', 'main', 'res', 'mipmap-xxhdpi', 'ic_launcher.png'));
+    }
+    const keystore = await ensureKeystore(manifest.id, toolchain.javaHome);
+    await writeFile(join(projectRoot, 'local.properties'), `sdk.dir=${toolchain.sdkRoot}\n`, 'utf8');
+    const version = await consumerVersion(projectDir);
+    console.log(`[drift-package] android: building ${manifest.name} ${version}`);
+    console.log(`[drift-package] android: signing ${keystore.describe}`);
+    await gradle(toolchain, projectRoot, [
+        'assembleRelease',
+        `-PdriftAppId=${manifest.id}`,
+        `-PdriftAppName=${manifest.name}`,
+        `-PdriftVersionName=${version}`,
+        `-PdriftVersionCode=${versionCodeFor(version)}`,
+        `-PdriftKeystore=${keystore.path}`,
+        `-PdriftKeystorePassword=${keystore.password}`,
+        `-PdriftKeyAlias=${keystore.alias}`,
+        `-PdriftKeyPassword=${keystore.password}`,
+    ]);
+    const apk = join(projectRoot, 'app', 'build', 'outputs', 'apk', 'release', 'app-release.apk');
+    const delivered = join(outDir, `${manifest.name.replace(/[^\w.-]+/g, '-')}-${version}.apk`);
+    await cp(apk, delivered);
+    console.log(`[drift-package] android: ${delivered}`);
+}
+/**
+ * A signing key: the one in the environment, or a throwaway generated once and kept.
+ *
+ * **Kept, and kept outside the project.** Android identifies an application by its signing key: a
+ * device refuses to upgrade an installed app whose new copy is signed with a different one, and
+ * the only way out on the device is to uninstall and lose the saves. So a generated key lives in
+ * the toolchain cache, keyed by application id — where `git clean` cannot reach it, where the
+ * build output being gitignored cannot lose it, and where two games on one machine do not share
+ * one identity.
+ */
+async function ensureKeystore(appId, javaHome) {
+    const real = process.env.DRIFT_ANDROID_KEYSTORE;
+    if (typeof real === 'string' && real.length > 0) {
+        return {
+            path: real,
+            password: process.env.DRIFT_ANDROID_KEYSTORE_PASSWORD ?? '',
+            alias: process.env.DRIFT_ANDROID_KEY_ALIAS ?? 'drift',
+            describe: `with the keystore in DRIFT_ANDROID_KEYSTORE`,
+        };
+    }
+    const dir = join(toolchainHome(), 'keystores');
+    const path = join(dir, `${appId}.jks`);
+    const keystore = {
+        path,
+        password: 'driftengine',
+        alias: 'drift',
+        describe: 'with a generated throwaway key, kept in the toolchain cache — installable with developer ' +
+            'mode on, not publishable, and an upgrade signed with a different key is refused by the ' +
+            'device, which is why it is kept rather than made fresh',
+    };
+    try {
+        await readFile(path);
+        return keystore;
+    }
+    catch {
+        /* Not there yet. */
+    }
+    await mkdir(dir, { recursive: true });
+    await runTool(join(javaHome, 'bin', process.platform === 'win32' ? 'keytool.exe' : 'keytool'), [
+        '-genkeypair',
+        '-keystore',
+        path,
+        '-alias',
+        keystore.alias,
+        '-storepass',
+        keystore.password,
+        '-keypass',
+        keystore.password,
+        '-keyalg',
+        'RSA',
+        '-keysize',
+        '2048',
+        /* Twenty-seven years, which is what Google asks of an upload key, and long enough that a
+           throwaway key is never the reason a build stops working. */
+        '-validity',
+        '10000',
+        '-dname',
+        'CN=DriftEngine, OU=Development, O=DriftEngine, C=GB',
+    ], {});
+    return keystore;
+}
+async function consumerVersion(projectDir) {
+    try {
+        const raw = JSON.parse(await readFile(join(projectDir, 'package.json'), 'utf8'));
+        const version = raw.version;
+        return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function gradle(toolchain, projectRoot, args) {
+    await runTool(toolchain.gradle, ['--project-dir', projectRoot, '--no-daemon', ...args], {
+        JAVA_HOME: toolchain.javaHome,
+        ANDROID_HOME: toolchain.sdkRoot,
+        ANDROID_SDK_ROOT: toolchain.sdkRoot,
+    });
+}
+async function runTool(command, args, env) {
+    await new Promise((done, fail) => {
+        const child = spawn(command, [...args], {
+            stdio: 'inherit',
+            env: { ...process.env, ...env },
+        });
+        child.on('error', fail);
+        child.on('close', (code) => code === 0 ? done() : fail(new Error(`${command} exited with ${String(code)}`)));
+    });
+}
+/**
+ * Refuse a build whose entry page points at files that will not be there.
+ *
+ * **The check that would have saved a device round trip.** A game whose HTML references
+ * `/assets/index-abc.js` served from the wrong root loads its markup and none of its code, and
+ * nothing in the build says so — the APK is valid, installs, launches, and shows unstyled text.
+ * Here it is a build failure naming the first few references that do not resolve.
+ */
+async function checkAssetReferences(assetsRoot, entryName) {
+    const html = await readFile(join(assetsRoot, entryName), 'utf8');
+    const present = new Set(await listRelative(assetsRoot, assetsRoot));
+    const missing = missingReferences(html, present);
+    if (missing.length === 0)
+        return;
+    throw new Error(`the entry page references ${missing.length} file(s) that are not in the bundle: ` +
+        `${missing.slice(0, 5).join(', ')}. Those are absolute paths, so they resolve from the root ` +
+        'the game is served at — which is where the packager puts it. A game built with a `base` ' +
+        'other than `/` needs that base to match, or a relative one.');
+}
+async function listRelative(root, dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await listRelative(root, full)));
+        else
+            out.push(relative(root, full).split('\\').join('/'));
+    }
+    return out;
+}

package/dist/bootstrap.d.ts

@@ -0,0 +1,17 @@
+import type { Target } from './manifest.ts';
+/**
+ * Fetch everything a target needs to be built, so nobody has to install seven things by hand.
+ *
+ * **This is the command that makes the other ones work on a fresh machine.** A packaging toolchain
+ * is a JDK, an Android SDK, a Gradle distribution and an Electron runtime, in pinned versions;
+ * every one of those is a download and a licence prompt, and a README that lists them is a README
+ * somebody follows wrongly at two in the morning.
+ *
+ * **Nothing is installed system-wide and nothing needs a password.** Everything lands under a
+ * cache directory this owns, and a machine that already has a working toolchain — `JAVA_HOME`,
+ * `ANDROID_HOME` — is used as it is rather than duplicated.
+ *
+ * **Only what is actually downloadable is downloaded.** Xcode is not: it is a sign-in and an App
+ * Store install on a Mac, so the iOS branch prints what to get rather than pretending.
+ */
+export declare function bootstrap(targets: readonly Target[]): Promise<void>;

package/dist/bootstrap.js

@@ -0,0 +1,326 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { chmod, readdir, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { PINS, ensureDir, findAndroidSdk, findGradle, findJavaHome, findRcodesign, findXcodeGen, needsRcodesign, toolchainHome, } from './toolchain.js';
+/**
+ * Fetch everything a target needs to be built, so nobody has to install seven things by hand.
+ *
+ * **This is the command that makes the other ones work on a fresh machine.** A packaging toolchain
+ * is a JDK, an Android SDK, a Gradle distribution and an Electron runtime, in pinned versions;
+ * every one of those is a download and a licence prompt, and a README that lists them is a README
+ * somebody follows wrongly at two in the morning.
+ *
+ * **Nothing is installed system-wide and nothing needs a password.** Everything lands under a
+ * cache directory this owns, and a machine that already has a working toolchain — `JAVA_HOME`,
+ * `ANDROID_HOME` — is used as it is rather than duplicated.
+ *
+ * **Only what is actually downloadable is downloaded.** Xcode is not: it is a sign-in and an App
+ * Store install on a Mac, so the iOS branch prints what to get rather than pretending.
+ */
+export async function bootstrap(targets) {
+    const wantsAndroid = targets.includes('android');
+    const wantsIos = targets.includes('ios');
+    const wantsDesktop = targets.some((target) => target !== 'android' && target !== 'ios');
+    if (wantsDesktop)
+        await bootstrapElectron();
+    if (targets.some((target) => needsRcodesign(target)))
+        await bootstrapRcodesign();
+    if (wantsAndroid)
+        await bootstrapAndroid();
+    if (wantsIos)
+        await bootstrapIos();
+}
+/**
+ * `rcodesign`, which signs a Mac target on a machine that has no `codesign`.
+ *
+ * **Fetched only when a Mac target is asked for off a Mac**, because that is the only situation
+ * where the platform's own signer is missing. On a Mac this is never downloaded: `codesign` ships
+ * with the command line tools and electron-builder drives it directly.
+ *
+ * A single static musl binary, so unlike the JDK there is nothing to discover in the archive and
+ * nothing that cares which distribution it lands on.
+ */
+async function bootstrapRcodesign() {
+    const existing = await findRcodesign();
+    if (existing !== null) {
+        console.log(`ok: rcodesign is present at ${existing}`);
+        return;
+    }
+    const asset = rcodesignAsset();
+    if (asset === null) {
+        throw new Error(`there is no published rcodesign for ${process.platform}/${process.arch}. ` +
+            '`cargo install apple-codesign` builds one, and the build will find it in ~/.cargo/bin');
+    }
+    const home = toolchainHome();
+    await ensureDir(home);
+    console.log(`fetching ${PINS.rcodesign.label}…`);
+    const archive = join(home, asset.archive);
+    await download('https://github.com/indygreg/apple-platform-rs/releases/download/' +
+        `apple-codesign%2F${PINS.rcodesign.version}/${asset.archive}`, archive);
+    const staging = join(home, 'rcodesign-unpack');
+    await rm(staging, { recursive: true, force: true });
+    await ensureDir(staging);
+    await extract(archive, staging);
+    /* The archive unpacks one directory named for the triple, holding the binary and its licences.
+       The binary is searched for rather than assumed at that path: the name of the wrapper
+       directory is the one part of a release asset that has changed before. */
+    const found = await findFile(staging, process.platform === 'win32' ? 'rcodesign.exe' : 'rcodesign');
+    if (found === null)
+        throw new Error('the rcodesign archive did not contain a binary');
+    const target = join(home, `rcodesign-${PINS.rcodesign.version}`);
+    await rm(target, { recursive: true, force: true });
+    await ensureDir(target);
+    const binary = join(target, 'rcodesign');
+    await rename(found, binary);
+    await chmod(binary, 0o755).catch(() => undefined);
+    await rm(staging, { recursive: true, force: true });
+    await rm(archive, { force: true });
+    console.log(`ok: rcodesign is at ${binary}`);
+}
+/** Which published rcodesign asset this machine can run, or null if the release page has none. */
+function rcodesignAsset() {
+    const version = PINS.rcodesign.version;
+    if (process.platform === 'linux') {
+        /* musl rather than gnu: the release publishes only the static build, which is the one that
+           does not care about the host's glibc. */
+        const arch = process.arch === 'arm64' ? 'aarch64' : 'x86_64';
+        return { archive: `apple-codesign-${version}-${arch}-unknown-linux-musl.tar.gz` };
+    }
+    if (process.platform === 'win32') {
+        return { archive: `apple-codesign-${version}-x86_64-pc-windows-msvc.zip` };
+    }
+    return null;
+}
+/** The first file with this name anywhere under a directory, or null. */
+async function findFile(root, name) {
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory()) {
+            const nested = await findFile(full, name);
+            if (nested !== null)
+                return nested;
+        }
+        else if (entry.name === name) {
+            return full;
+        }
+    }
+    return null;
+}
+/**
+ * The Electron runtime, which npm sometimes does not fetch.
+ *
+ * Its binary arrives through a postinstall script, and an install run with scripts disabled —
+ * which several sandboxes, CI images and corporate setups do by default — leaves the package
+ * present and the runtime missing. The failure that produces is `Electron failed to install
+ * correctly` at the moment somebody first tries to run a game.
+ */
+async function bootstrapElectron() {
+    const require = (await import('node:module')).createRequire(import.meta.url);
+    let installer;
+    try {
+        installer = require.resolve('electron/install.js');
+    }
+    catch {
+        throw new Error('electron is not installed; run npm install first');
+    }
+    const dist = join(installer, '..', 'dist');
+    if (await pathExists(dist)) {
+        console.log('ok: the Electron runtime is present');
+        return;
+    }
+    console.log('fetching the Electron runtime…');
+    await run(process.execPath, [installer], {});
+    console.log('ok: the Electron runtime is present');
+}
+async function bootstrapAndroid() {
+    const home = toolchainHome();
+    await ensureDir(home);
+    const javaHome = (await findJavaHome()) ?? (await installJdk(home));
+    const sdkRoot = (await findAndroidSdk()) ?? (await installAndroidSdk(home, javaHome));
+    await installAndroidPackages(sdkRoot, javaHome);
+    const gradle = (await findGradle()) ?? (await installGradle(home));
+    console.log(`ok: android toolchain ready`);
+    console.log(`  JDK:     ${javaHome}`);
+    console.log(`  SDK:     ${sdkRoot}`);
+    console.log(`  Gradle:  ${gradle}`);
+}
+async function bootstrapIos() {
+    if (process.platform !== 'darwin') {
+        console.log('ios: this is not a Mac, and an iOS build needs one. Nothing to fetch here.');
+        return;
+    }
+    const home = toolchainHome();
+    await ensureDir(home);
+    if ((await findXcodeGen()) === null) {
+        console.log(`fetching ${PINS.xcodegen.label}…`);
+        const archive = join(home, 'xcodegen.zip');
+        await download(`https://github.com/yonaskolb/XcodeGen/releases/download/${PINS.xcodegen.version}/xcodegen.zip`, archive);
+        const target = join(home, `xcodegen-${PINS.xcodegen.version}`);
+        await rm(target, { recursive: true, force: true });
+        await ensureDir(target);
+        await extract(archive, target);
+        /* The archive unpacks a `xcodegen/` directory containing bin and share; flattened so the
+           path this file resolves is the path `findXcodeGen` looks for. */
+        const [inner] = await readdir(target);
+        if (inner !== undefined && inner === 'xcodegen') {
+            await rename(join(target, 'xcodegen', 'bin'), join(target, 'bin'));
+            await rename(join(target, 'xcodegen', 'share'), join(target, 'share')).catch(() => undefined);
+        }
+        await chmod(join(target, 'bin', 'xcodegen'), 0o755).catch(() => undefined);
+        await rm(archive, { force: true });
+    }
+    /* Xcode itself cannot be fetched, so it is checked for and named rather than installed. */
+    try {
+        await run('xcodebuild', ['-version'], { quiet: true });
+        console.log('ok: Xcode is here, and so is XcodeGen');
+    }
+    catch {
+        console.log('ios: XcodeGen is ready; Xcode is not.');
+        console.log('  - install Xcode from the App Store, then `xcode-select --install`');
+        console.log('  - a free Apple ID installs to your own device for seven days at a time;');
+        console.log('    the paid Developer Program is what makes a build last and reach TestFlight');
+    }
+}
+/** Temurin, from the Adoptium API, which redirects to the current build of the pinned feature. */
+async function installJdk(home) {
+    const os = process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'mac' : 'linux';
+    const arch = process.arch === 'arm64' ? 'aarch64' : 'x64';
+    const url = `https://api.adoptium.net/v3/binary/latest/${PINS.jdk.feature}/ga/${os}/${arch}` +
+        '/jdk/hotspot/normal/eclipse';
+    console.log(`fetching ${PINS.jdk.label}…`);
+    const archive = join(home, os === 'windows' ? 'jdk.zip' : 'jdk.tar.gz');
+    await download(url, archive);
+    const staging = join(home, 'jdk-unpack');
+    await rm(staging, { recursive: true, force: true });
+    await ensureDir(staging);
+    await extract(archive, staging);
+    /* Every JDK archive unpacks into one versioned directory; the pin is on the feature release, so
+       the exact name changes with each patch and is discovered rather than assumed. */
+    const [inner] = await readdir(staging);
+    if (inner === undefined)
+        throw new Error('the JDK archive unpacked into nothing');
+    const target = join(home, 'jdk');
+    await rm(target, { recursive: true, force: true });
+    await rename(join(staging, inner), target);
+    await rm(staging, { recursive: true, force: true });
+    await rm(archive, { force: true });
+    return target;
+}
+async function installAndroidSdk(home, javaHome) {
+    const os = process.platform === 'win32' ? 'win' : process.platform === 'darwin' ? 'mac' : 'linux';
+    const url = `https://dl.google.com/android/repository/commandlinetools-${os}-${PINS.androidTools.build}_latest.zip`;
+    console.log(`fetching ${PINS.androidTools.label}…`);
+    const archive = join(home, 'cmdline-tools.zip');
+    await download(url, archive);
+    const sdkRoot = join(home, 'android-sdk');
+    const staging = join(home, 'cmdline-unpack');
+    await rm(staging, { recursive: true, force: true });
+    await ensureDir(staging);
+    await extract(archive, staging);
+    /* sdkmanager insists on living at `cmdline-tools/latest/`, and the archive unpacks a directory
+       called `cmdline-tools`. Getting this wrong produces a tool that refuses to run and blames the
+       SDK root rather than its own location. */
+    await ensureDir(join(sdkRoot, 'cmdline-tools'));
+    await rm(join(sdkRoot, 'cmdline-tools', 'latest'), { recursive: true, force: true });
+    await rename(join(staging, 'cmdline-tools'), join(sdkRoot, 'cmdline-tools', 'latest'));
+    await rm(staging, { recursive: true, force: true });
+    await rm(archive, { force: true });
+    await acceptLicences(sdkRoot, javaHome);
+    return sdkRoot;
+}
+/**
+ * Accept the SDK licences, which is a prompt that cannot be skipped and can be answered.
+ *
+ * Google requires an explicit acceptance per licence before any package installs. Answering it by
+ * piping `y` is what every CI image does; it is recorded here rather than hidden because accepting
+ * a licence on somebody's behalf is a thing they should be able to see in a diff.
+ */
+async function acceptLicences(sdkRoot, javaHome) {
+    console.log('accepting the Android SDK licences…');
+    await run(sdkManager(sdkRoot), [`--sdk_root=${sdkRoot}`, '--licenses'], {
+        env: { JAVA_HOME: javaHome },
+        stdin: `${'y\n'.repeat(64)}`,
+        quiet: true,
+    });
+}
+async function installAndroidPackages(sdkRoot, javaHome) {
+    console.log(`installing ${PINS.androidPackages.join(', ')}…`);
+    await run(sdkManager(sdkRoot), [`--sdk_root=${sdkRoot}`, ...PINS.androidPackages], {
+        env: { JAVA_HOME: javaHome },
+        quiet: true,
+    });
+}
+async function installGradle(home) {
+    console.log(`fetching ${PINS.gradle.label}…`);
+    const archive = join(home, 'gradle.zip');
+    await download(`https://services.gradle.org/distributions/gradle-${PINS.gradle.version}-bin.zip`, archive);
+    await extract(archive, home);
+    await rm(archive, { force: true });
+    const binary = join(home, `gradle-${PINS.gradle.version}`, 'bin', process.platform === 'win32' ? 'gradle.bat' : 'gradle');
+    if (!(await pathExists(binary)))
+        throw new Error('the Gradle archive did not contain a launcher');
+    return binary;
+}
+function sdkManager(sdkRoot) {
+    const name = process.platform === 'win32' ? 'sdkmanager.bat' : 'sdkmanager';
+    return join(sdkRoot, 'cmdline-tools', 'latest', 'bin', name);
+}
+async function download(url, to) {
+    const response = await fetch(url, { redirect: 'follow' });
+    if (!response.ok || response.body === null) {
+        throw new Error(`could not download ${url}: ${response.status} ${response.statusText}`);
+    }
+    /* The DOM's `ReadableStream` and Node's are structurally the same and typed apart; the cast is
+       at the one line where the two type worlds meet rather than spread through the signature. */
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(to));
+}
+/**
+ * Unpack an archive with whatever this machine has.
+ *
+ * `tar` handles both formats on macOS and on Windows, where it is bsdtar; GNU tar on Linux cannot
+ * read a zip, so `unzip` is tried first for those. Two attempts rather than a dependency: an
+ * archive extractor is a large amount of code to carry for a step that runs once per machine.
+ */
+async function extract(archive, into) {
+    if (archive.endsWith('.zip')) {
+        try {
+            await run('unzip', ['-q', '-o', archive, '-d', into], { quiet: true });
+            return;
+        }
+        catch {
+            await run('tar', ['-xf', archive, '-C', into], { quiet: true });
+            return;
+        }
+    }
+    await run('tar', ['-xzf', archive, '-C', into], { quiet: true });
+}
+async function pathExists(path) {
+    try {
+        await (await import('node:fs/promises')).access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function run(command, args, options) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            env: { ...process.env, ...options.env },
+            stdio: [
+                options.stdin === undefined ? 'ignore' : 'pipe',
+                options.quiet === true ? 'ignore' : 'inherit',
+                'inherit',
+            ],
+        });
+        if (options.stdin !== undefined && child.stdin !== null) {
+            child.stdin.write(options.stdin);
+            child.stdin.end();
+        }
+        child.on('error', reject);
+        child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`${command} exited with ${String(code)}`)));
+    });
+}

package/dist/build.d.ts

@@ -0,0 +1,11 @@
+import type { PackageManifest, Target } from './manifest.ts';
+import type { ResourceOptions } from './resources.ts';
+export declare function build(manifest: PackageManifest, cwd: string, targets: readonly Target[], options?: ResourceOptions): Promise<void>;
+/**
+ * The Electron the artifact will carry, read from what is installed rather than declared.
+ *
+ * The staged application has no dependencies of its own — both entry points are bundled — so
+ * electron-builder has nothing to infer a version from and would refuse. Reading the installed
+ * one keeps the artifact and this repository on the same runtime by construction.
+ */
+export declare function installedElectronVersion(): Promise<string>;