@driftengine/package 3.61.0

package/dist/build.js

@@ -0,0 +1,248 @@
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildAndroid } from './android.js';
+import { buildIos } from './ios.js';
+import { crossSignMacApp, zipMacApp } from './macCrossSign.js';
+import { outFor } from './outDir.js';
+import { resourceFile } from './resources.js';
+import { ensureElectronRuntime } from './runtime.js';
+import { planSigning } from './signing.js';
+import { consumerVersion, stageApp } from './stage.js';
+import { findRcodesign } from './toolchain.js';
+/**
+ * An installable artifact per target.
+ *
+ * **The builder configuration is derived, not authored.** Every value it needs is already in
+ * `drift.package.json`, and a second configuration file would be a second place for the
+ * application id to be wrong — which is the failure that is silent until saves land in a directory
+ * nobody looks in.
+ *
+ * **Linux gets a native artifact and that is a Steam Deck decision**, recorded here because it
+ * looks like an ordinary target otherwise: a Windows build under Proton is the default assumption
+ * and it carries a known regression — gamepads undetected in Electron under Proton after 26.6.10,
+ * where the same build works natively. Valve's own guidance points the same way.
+ *
+ * **A target is refused where this machine cannot honestly produce it**, and the interesting word
+ * is *honestly*: the danger was never a build error, it is an artifact that looks finished and
+ * will not launch, or one that cannot be signed. `scripts/` carries the Windows and macOS hosts.
+ *
+ * **macOS is the one target that moved off that rule, and only from Linux.** Nothing in a Mac
+ * build is compiled — Electron ships a prebuilt darwin runtime and packing it is file copying and
+ * a plist — so the artifact itself was never the problem. The signature was: electron-builder
+ * skips signing off darwin, and an unsigned binary is refused by Apple Silicon's loader. With
+ * `rcodesign` putting an ad-hoc signature on afterwards, the two things a Linux host still cannot
+ * do are named rather than worked around — there is no `.dmg`, because that is `hdiutil`, and
+ * there is no proof it launches, because that needs the machine it runs on. See `macCrossSign.ts`.
+ */
+const HOST_FOR = {
+    'win-x64': 'win32',
+    'mac-arm64': 'darwin',
+    'mac-x64': 'darwin',
+    'linux-x64': 'linux',
+    /* Android's toolchain is Java and it runs anywhere; iOS needs Xcode, which is a Mac. */
+    android: null,
+    ios: 'darwin',
+};
+/**
+ * Why this machine cannot build that target, or null.
+ *
+ * A Mac target is allowed from Linux and still refused from Windows — that second refusal is
+ * electron-builder's own and would fire a few seconds later anyway, so it is stated here where
+ * the reason can be given.
+ */
+function refuseHost(target, platform) {
+    const host = HOST_FOR[target];
+    if (host === null || platform === host)
+        return null;
+    if ((target === 'mac-arm64' || target === 'mac-x64') && platform === 'linux')
+        return null;
+    if (target === 'mac-arm64' || target === 'mac-x64') {
+        return (`${target} is cross-built from Linux and built natively on a Mac, and this is ${platform}. ` +
+            'electron-builder refuses a Mac target on Windows outright, so there is nothing to work ' +
+            'around here.');
+    }
+    return (`${target} is built on ${String(host)}, and this is ${platform}. ` +
+        'See packages/package/scripts for the Windows and macOS hosts; cross-building under ' +
+        'Wine cannot reach a certificate store, which is the one platform where that matters.');
+}
+export async function build(manifest, cwd, targets, options = {}) {
+    const { build: run, Arch, Platform } = await import('electron-builder');
+    /* One artifact per target, and the architecture is named rather than inherited: a build on an
+       Apple Silicon machine defaults to arm64, so `mac-x64` asked for on one would quietly produce
+       the wrong slice. */
+    const targetFor = (name) => name === 'win-x64'
+        ? Platform.WINDOWS.createTarget(undefined, Arch.x64)
+        : name === 'linux-x64'
+            ? Platform.LINUX.createTarget(undefined, Arch.x64)
+            : Platform.MAC.createTarget(undefined, name === 'mac-x64' ? Arch.x64 : Arch.arm64);
+    const electronVersion = await installedElectronVersion();
+    for (const target of targets) {
+        if (target === 'android') {
+            await buildAndroid(manifest, cwd, outFor(cwd, target, options), options);
+            continue;
+        }
+        if (target === 'ios') {
+            await buildIos(manifest, cwd, outFor(cwd, target, options), options);
+            continue;
+        }
+        const refusal = refuseHost(target, process.platform);
+        if (refusal !== null)
+            throw new Error(refusal);
+        /*
+         * **The runtime, before anything is staged.** `installedElectronVersion` below reads a version
+         * out of `electron/package.json`, which is in the npm tarball — so it answers even when the
+         * postinstall that downloads the actual binary never finished, and electron-builder then finds
+         * nothing to package several steps and several minutes later. Measured in this repository on
+         * 2026-08-29: a version of 43.4.1 against no `dist`. See `runtime.ts`.
+         */
+        await ensureElectronRuntime();
+        const signing = planSigning(target, process.env, process.platform);
+        if (signing.refusal !== null)
+            throw new Error(`${target}: ${signing.refusal}`);
+        console.log(`[drift-package] ${target}: signing ${signing.mode} — ${signing.reason}`);
+        /*
+         * **Looked up before anything is staged.** Signing is the last step of a build that takes
+         * minutes, and a missing signer discovered there costs the whole thing — so the tool is
+         * resolved while the failure is still cheap.
+         */
+        const rcodesign = signing.crossSign ? await findRcodesign() : null;
+        if (signing.crossSign && rcodesign === null) {
+            throw new Error(`${target} is signed here by rcodesign, and there is none on this machine. ` +
+                `Run \`drift-package bootstrap --target=${target}\`, which fetches it into a cache.`);
+        }
+        const outDir = outFor(cwd, target, options);
+        const stageDir = join(outDir, 'stage');
+        await stageApp(manifest, cwd, stageDir, { development: false, ...options });
+        /* Where the signing step found the `.app`, so the archive below does not have to guess at
+           electron-builder's own naming for the packed directory. */
+        const signed = { app: null };
+        await run({
+            targets: targetFor(target),
+            /*
+             * **The staged directory is the project, not just the application.** Pointed at the
+             * consumer's own directory instead, electron-builder looks for *their* `package.json`,
+             * tries to install *their* dependencies into the artifact, and fails on a project that
+             * has neither — which a game built by any other toolchain may well not.
+             */
+            projectDir: stageDir,
+            config: {
+                appId: manifest.id,
+                productName: manifest.name,
+                electronVersion,
+                /* One 1024px PNG for all three platforms: electron-builder derives an `.ico` and an
+                   `.icns` from it, and a game that supplies its own replaces exactly this line. */
+                icon: manifest.icon === null
+                    ? await resourceFile('assets', 'icon.png', options.resourceRoot)
+                    : resolve(cwd, manifest.icon),
+                directories: { output: outDir },
+                /* The staged directory is the application, whole. Nothing is filtered here because
+                   nothing that should not ship was put there: see `stage.ts` for what it contains. */
+                files: ['**/*'],
+                /*
+                 * **A native module cannot be loaded from inside an asar archive.** `steamworks.js` is a
+                 * `.node` binary, and one packed into the archive fails at `require` with a message about
+                 * a path that does not exist — which reads as a missing dependency rather than as a
+                 * packing decision. Unpacked, and only it.
+                 */
+                asarUnpack: ['**/node_modules/steamworks.js/**'],
+                /*
+                 * **The signature goes on between packing and archiving, and that ordering is the whole
+                 * point.** `afterPack` runs once the `.app` is complete and before any target wraps it, so
+                 * the signed bundle is the one that ends up inside the `.zip`. Signing afterwards would
+                 * leave the artifact people download carrying the unsigned copy.
+                 */
+                afterPack: rcodesign === null ? undefined : macSignStep(rcodesign, target, signed),
+                mac: {
+                    hardenedRuntime: signing.mode === 'real',
+                    category: 'public.app-category.games',
+                    /*
+                     * `'-'` is `codesign`'s own spelling of an ad-hoc identity. `null` means *do not sign*,
+                     * which on Apple Silicon means *does not run* — and is exactly right when this build
+                     * signs the app itself a few lines below, because electron-builder would otherwise log
+                     * a warning about skipping a step that is not being skipped.
+                     */
+                    identity: signing.crossSign ? null : signing.mode === 'adhoc' ? '-' : undefined,
+                    notarize: signing.notarise,
+                    /*
+                     * **Both of electron-builder's Mac archives are macOS-only, for different reasons.** A
+                     * `.dmg` is built by `hdiutil`, which exists nowhere else. Its `.zip` is worse than
+                     * unavailable: it is produced by 7-Zip off darwin, which dereferences the symlinks every
+                     * `.framework` is made of, and the result is a corrupt bundle rather than an error.
+                     *
+                     * So a cross-build asks for `dir` — pack the `.app` and stop — and the archive is made
+                     * afterwards by `zipMacApp`, which keeps the links.
+                     */
+                    target: signing.crossSign ? ['dir'] : ['dmg', 'zip'],
+                },
+                win: {
+                    target: ['nsis', 'zip'],
+                    /* Nothing is named here: electron-builder reads `WIN_CSC_LINK`/`CSC_LINK` from the
+                       environment itself, and repeating them is a second place for them to be wrong. */
+                },
+                linux: { target: ['AppImage', 'tar.gz'], category: 'Game' },
+            },
+        });
+        /*
+         * **The archive, for a cross-build only.** electron-builder was asked for `dir` above because
+         * neither of its Mac archives can be produced correctly off a Mac, so the artifact somebody
+         * downloads is made here — see `zipMacApp` for what 7-Zip does to a framework.
+         *
+         * The name matches what electron-builder would have written, so a Mac-built release and a
+         * Linux-built one are the same file under the same name.
+         */
+        if (signed.app !== null) {
+            const version = await consumerVersion(cwd);
+            const arch = target === 'mac-x64' ? 'x64' : 'arm64';
+            await zipMacApp(signed.app, join(outDir, `${manifest.name}-${version}-${arch}-mac.zip`));
+        }
+    }
+}
+/**
+ * The `afterPack` hook that ad-hoc signs a cross-built `.app`, or nothing on a Mac.
+ *
+ * A factory rather than an inline closure so the resolved signer is a `string` inside it: the
+ * lookup and the refusal happen once, before a build starts, and this cannot be reached without
+ * one. `electronPlatformName` is checked because the hook is called for whatever is being packed.
+ */
+function macSignStep(rcodesign, target, signed) {
+    return async (context) => {
+        if (context.electronPlatformName !== 'darwin')
+            return;
+        const app = await packedApp(context.appOutDir);
+        console.log(`[drift-package] ad-hoc signing ${app} with rcodesign`);
+        await crossSignMacApp({
+            app,
+            rcodesign,
+            arch: target === 'mac-x64' ? 'x64' : 'arm64',
+        });
+        console.log('[drift-package] signed, and every nested bundle checked');
+        signed.app = app;
+    };
+}
+/** The `.app` electron-builder just wrote, found rather than named after the product. */
+async function packedApp(appOutDir) {
+    const { readdir } = await import('node:fs/promises');
+    const found = (await readdir(appOutDir)).filter((entry) => entry.endsWith('.app'));
+    if (found.length !== 1) {
+        throw new Error(`expected one .app in ${appOutDir} and found ${found.length ? found.join(', ') : 'none'}`);
+    }
+    return join(appOutDir, found[0]);
+}
+/**
+ * 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 async function installedElectronVersion() {
+    const require = createRequire(import.meta.url);
+    const manifestPath = require.resolve('electron/package.json');
+    const raw = JSON.parse(await readFile(manifestPath, 'utf8'));
+    const version = raw.version;
+    if (typeof version !== 'string')
+        throw new Error('electron is installed without a version');
+    return version;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { bootstrap } from './bootstrap.js';
+import { build, installedElectronVersion } from './build.js';
+import { planFlags } from './flags.js';
+import { refuseLyingFilesystem } from './identity.js';
+import { init } from './init.js';
+import { outFor } from './outDir.js';
+import { parseManifest } from './manifest.js';
+import { planSigning } from './signing.js';
+import { electronMajor } from './runtimeVersion.js';
+import { depotScripts } from './steam/depot.js';
+import { androidToolchain, findRcodesign, needsRcodesign, requirementsFor } from './toolchain.js';
+import { stageApp } from './stage.js';
+import { resourceDir } from './resources.js';
+/*
+ * **`ELECTRON_RUN_AS_NODE` is removed from this process before anything else happens.**
+ *
+ * Any terminal that is itself an Electron application — an editor's built-in one is the ordinary
+ * case, and a developer's own shell had it set — exports the variable to everything it spawns.
+ * Inherited, it turns Electron into plain Node: a packaged build dies on `Cannot find module
+ * 'electron'` under a Node banner, which looks nothing like its cause, and in that mode the
+ * built-in module genuinely is not there.
+ *
+ * **It used to be removed for `run` alone**, in `launchEnv` below, which left `build` and every
+ * other subcommand inheriting it — and `build` is the one that spends twenty minutes before
+ * anything can go wrong. Deleted rather than set empty: Electron treats the variable as set
+ * whatever its value.
+ */
+delete process.env.ELECTRON_RUN_AS_NODE;
+/**
+ * `drift-package` — the command a consumer runs to get an installable application.
+ *
+ * Four subcommands, and `verify` is the one that is not obvious. An artifact that was never
+ * rebuilt is byte-identical in every respect a build log can see, so the only honest check is to
+ * look inside the shipped thing for a string from the change. This repository already learned that
+ * about deploys: an asset hash proves nothing.
+ *
+ * Every failure exits non-zero with the reason on stderr. A packaging command that prints a
+ * complaint and exits 0 is a command that passes in a script.
+ */
+function loadManifest(cwd) {
+    const path = join(cwd, 'drift.package.json');
+    try {
+        return parseManifest(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch (cause) {
+        throw new Error(`could not read ${path}: ${String(cause)}`);
+    }
+}
+function walk(dir, out = []) {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory())
+            walk(full, out);
+        else
+            out.push(full);
+    }
+    return out;
+}
+async function doctor(cwd, options = {}) {
+    /*
+     * **Before anything is read, downloaded or staged**, because the failure it replaces arrives ten
+     * minutes in and talks about copying a file into a subdirectory of itself. See `identity.ts`:
+     * a share that invents a file index makes Node refuse a copy that is perfectly legitimate.
+     */
+    refuseLyingFilesystem(cwd, options.outRoot);
+    const manifest = loadManifest(cwd);
+    /*
+     * **The packager's own three directories, checked here rather than met mid-build.** `assets/`
+     * becomes every desktop artifact's `drift://shell/` origin, and a copy of the engine that
+     * flattened its packages has moved all three out of reach — which used to arrive as `ENOENT` on a
+     * path that is not in the project, after esbuild had already run. `doctor` is where this file
+     * already refuses what a build cannot do, before anything is downloaded or staged.
+     *
+     * `assets` alone: it is the one every target needs, and naming `android/` or `ios/` on a machine
+     * building for Linux would refuse a build that was never going to touch them. The two mobile
+     * builders check their own.
+     */
+    await resourceDir('assets', options.resourceRoot);
+    /*
+     * **Against the Electron this machine would actually package**, not the one the package declares.
+     * A switch written for one Chromium and applied to another is ignored without a word, so doctor
+     * is where a runtime too old for it is named — before a build spends its minutes and ships a
+     * game that silently has no WebGPU.
+     */
+    const electron = electronMajor(await installedElectronVersion().catch(() => null));
+    for (const target of manifest.targets) {
+        const plan = planFlags(manifest, target, electron);
+        if (plan.refusal !== null)
+            throw new Error(`${target}: ${plan.refusal}`);
+        for (const note of plan.notes)
+            console.log(`  ${target}: ${note}`);
+    }
+    console.log(`ok: ${manifest.name} (${manifest.id}) for ${manifest.targets.join(', ')}`);
+    for (const target of manifest.targets) {
+        const signing = planSigning(target, process.env, process.platform);
+        console.log(`  ${target}: signing ${signing.mode} — ${signing.reason}`);
+    }
+    console.log(`  splash: ${manifest.splash.show ? `the engine badge, held ${manifest.splash.minMs} ms` : 'off'}`);
+    /*
+     * **What each target still needs, and the command that fetches it.** A `doctor` that only
+     * validated a manifest would pass on a machine with no Java and no SDK, and the failure would
+     * arrive twenty minutes later from Gradle.
+     */
+    for (const target of manifest.targets) {
+        const ready = await toolchainReady(target);
+        if (ready)
+            continue;
+        console.log(`  ${target}: needs ${requirementsFor(target).join(', ')} — ` +
+            `run \`drift-package bootstrap --target=${target}\``);
+    }
+    return manifest;
+}
+function verify(cwd, needle) {
+    const manifest = loadManifest(cwd);
+    const root = join(cwd, dirname(manifest.entry));
+    const found = walk(root).some((file) => readFileSync(file, 'utf8').includes(needle));
+    if (!found) {
+        throw new Error(`verify: "${needle}" is in no file under ${root}. That is what a build that did not rerun ` +
+            'looks like — the artifact exists and is stale.');
+    }
+    console.log(`ok: "${needle}" is in the built bundle`);
+}
+/**
+ * The packaged application, run from source without producing an installer.
+ *
+ * **The whole point is that it is the same code path.** It stages exactly what a build stages and
+ * starts Electron on it, so the window, the flags, the `drift://` origin and the badge are the
+ * ones that will ship. A `run` that took a shortcut would be a rehearsal of something else.
+ */
+async function run(cwd, options) {
+    const manifest = await doctor(cwd, options);
+    const stageDir = mkdtempSync(join(tmpdir(), 'drift-run-'));
+    /* A development run: developer tools open, warnings forwarded. `build` stages the other kind. */
+    await stageApp(manifest, cwd, stageDir, { development: true, ...options });
+    const electron = await import('electron');
+    const binary = electron.default;
+    console.log(`[drift-package] running from ${stageDir}`);
+    return new Promise((resolve) => {
+        const child = spawn(binary, [stageDir], { stdio: 'inherit', env: launchEnv() });
+        child.on('close', (code) => {
+            /* The staging directory holds a whole copy of the game's build — tens of megabytes for a
+               real one — and a `run` per iteration would leave one of each in the temp directory. */
+            rmSync(stageDir, { recursive: true, force: true });
+            resolve(code ?? 0);
+        });
+    });
+}
+/**
+ * The environment Electron is started in, with one variable removed.
+ *
+ * **`ELECTRON_RUN_AS_NODE` turns Electron into plain Node**, and any Electron-based terminal sets
+ * it for the processes it spawns — an editor's integrated terminal is the common case, and this
+ * workspace's own shell had it set. Inherited, it produces a failure that looks nothing like its
+ * cause: the binary starts, prints a Node banner and dies on `Cannot find module 'electron'`,
+ * because in that mode the built-in module genuinely is not there.
+ *
+ * Deleted rather than overridden with an empty string: Electron treats the variable as set
+ * whatever its value.
+ *
+ * **This is now the second place it is removed** and it stays: the top of this file clears it for
+ * the whole process, and this clears it for the child. The reason is written twice because it is
+ * the reason somebody will come here looking for, and a copy of `process.env` taken elsewhere
+ * would not inherit the first deletion.
+ */
+function launchEnv() {
+    const env = { ...process.env };
+    delete env.ELECTRON_RUN_AS_NODE;
+    return env;
+}
+/**
+ * Whether this machine can build that target today.
+ *
+ * Desktop targets need the Electron runtime, which is present unless an install skipped its
+ * postinstall; Android needs a whole toolchain; iOS needs Xcode, which nothing here can check for
+ * beyond the platform it would have to be on.
+ */
+async function toolchainReady(target) {
+    if (target === 'android')
+        return (await androidToolchain()) !== null;
+    if (target === 'ios')
+        return process.platform === 'darwin';
+    /* A Mac target built anywhere else is signed by rcodesign, and an unsigned .app will not
+       launch — so a machine without it is not ready for that target, however well it packs. */
+    if (needsRcodesign(target))
+        return (await findRcodesign()) !== null;
+    return true;
+}
+/**
+ * The two files `steamcmd` uploads a build with, written beside the artifacts they describe.
+ *
+ * A separate command rather than part of `build`, because uploading is a decision: the scripts
+ * name an app id that costs money to get wrong, and a build is often made several times before one
+ * of them is the one that ships.
+ */
+async function writeSteamScripts(cwd, args, options) {
+    const manifest = loadManifest(cwd);
+    if (manifest.steam.appId === null) {
+        throw new Error('steam: `steam.appId` is null in drift.package.json. Set it to the app id Valve gave you; ' +
+            "a depot script with the wrong one uploads into somebody else's game.");
+    }
+    const target = (args.find((entry) => entry.startsWith('--target=')) ?? '--target=linux-x64').slice('--target='.length);
+    const depotArg = args.find((entry) => entry.startsWith('--depot='));
+    /* A first depot is conventionally the app id plus one, which is how Valve numbers them. */
+    const depotId = depotArg === undefined ? manifest.steam.appId + 1 : Number.parseInt(depotArg.slice(8), 10);
+    const branchArg = args.find((entry) => entry.startsWith('--branch='));
+    const outDir = outFor(cwd, target, options);
+    const content = target === 'linux-x64' ? 'linux-unpacked' : target === 'win-x64' ? 'win-unpacked' : 'mac';
+    const scripts = depotScripts({
+        appId: manifest.steam.appId,
+        depotId,
+        description: `${manifest.name} ${target}`,
+        contentRoot: content,
+        branch: branchArg === undefined ? null : branchArg.slice('--branch='.length),
+    });
+    await writeFile(join(outDir, scripts.appFileName), scripts.app, 'utf8');
+    await writeFile(join(outDir, scripts.depotFileName), scripts.depot, 'utf8');
+    console.log(`ok: ${join(outDir, scripts.appFileName)}`);
+    console.log(`ok: ${join(outDir, scripts.depotFileName)}`);
+    console.log(`  upload with: steamcmd +login <user> +run_app_build "${join(outDir, scripts.appFileName)}" +quit`);
+    console.log("  nothing is set live: the build waits in Steam's admin for a person");
+}
+/** What this machine builds for itself, used when nothing has said otherwise. */
+function hostTarget() {
+    if (process.platform === 'win32')
+        return 'win-x64';
+    if (process.platform === 'darwin')
+        return process.arch === 'x64' ? 'mac-x64' : 'mac-arm64';
+    return 'linux-x64';
+}
+function targetsFrom(manifest, args) {
+    const asked = args.find((entry) => entry.startsWith('--target='));
+    if (asked === undefined)
+        return manifest.targets;
+    const name = asked.slice('--target='.length);
+    const found = manifest.targets.find((target) => target === name);
+    if (found === undefined) {
+        throw new Error(`--target=${name} is not in this manifest's targets (${manifest.targets.join(', ')})`);
+    }
+    return [found];
+}
+const [command, ...rest] = process.argv.slice(2);
+/**
+ * The project being packaged, which is the working directory unless `--project=` says otherwise.
+ *
+ * **Because the packager and the game are often not the same repository.** A game that keeps its
+ * `drift.package.json` and nothing else — no Electron, no electron-builder, no Android SDK in its
+ * own `node_modules` — is packaged by pointing this at it from wherever the tool lives, and that
+ * is the arrangement most consumers actually want: half a gigabyte of build tooling does not
+ * belong in a game's dependency tree.
+ */
+const projectFlag = rest.find((entry) => entry.startsWith('--project='));
+const cwd = projectFlag === undefined
+    ? process.cwd()
+    : resolve(process.cwd(), projectFlag.slice('--project='.length));
+/**
+ * Where the packager's own `assets/`, `android/` and `ios/` are, if not beside its sources.
+ *
+ * **For a consumer that vendors engine source** rather than installing it: such a vendor copies
+ * `packages/<name>/src/**` to `<name>/**` and the flattening moves
+ * the three out of reach of anything this package can compute. Reported from outside, where the
+ * workaround was a layout exception in the vendor script for this one package. See `resources.ts`
+ * for why this is a flag rather than an environment variable.
+ */
+const resourcesFlag = rest.find((entry) => entry.startsWith('--resources='));
+/**
+ * Where builds write, if not `out/` inside the project.
+ *
+ * **For a project on a filesystem that misreports file identity**, where the first staging copy
+ * of a build refuses itself: `fs.cp` compares `dev` and `ino` up the destination's ancestors, and
+ * a shared or network folder can answer the same pair for a file and a directory. `outDir.ts`
+ * carries the measurement. Absolute here, or relative to wherever the command was run, which is
+ * not necessarily `--project=`.
+ */
+const outFlag = rest.find((entry) => entry.startsWith('--out='));
+const resources = {
+    ...(resourcesFlag === undefined
+        ? {}
+        : { resourceRoot: resourcesFlag.slice('--resources='.length) }),
+    ...(outFlag === undefined ? {} : { outRoot: outFlag.slice('--out='.length) }),
+};
+try {
+    if (command === 'doctor') {
+        await doctor(cwd, resources);
+    }
+    else if (command === 'verify') {
+        const arg = rest.find((entry) => entry.startsWith('--contains='));
+        if (arg === undefined)
+            throw new Error('verify needs --contains=<string>');
+        verify(cwd, arg.slice('--contains='.length));
+    }
+    else if (command === 'run') {
+        process.exitCode = await run(cwd, resources);
+    }
+    else if (command === 'bootstrap') {
+        /* Deliberately does not need a manifest: a machine is prepared before a project exists on it,
+           and `--target=` names what to prepare for. */
+        const asked = rest.find((entry) => entry.startsWith('--target='));
+        const targets = asked === undefined
+            ? (() => {
+                try {
+                    return loadManifest(cwd).targets;
+                }
+                catch {
+                    /* No manifest here: prepare for this desktop, which is the useful default on a
+                       machine somebody is setting up. */
+                    return [hostTarget()];
+                }
+            })()
+            : [asked.slice('--target='.length)];
+        await bootstrap(targets);
+    }
+    else if (command === 'init') {
+        /*
+         * Scaffolds a *project*, where `bootstrap` prepares a *machine*. Two commands because a
+         * machine is prepared once and a project once per project, and conflating them would make the
+         * one that writes files into your repository the one you run to install a JDK.
+         */
+        await init(cwd, loadManifest(cwd), rest.includes('--force'));
+    }
+    else if (command === 'steam') {
+        await writeSteamScripts(cwd, rest, resources);
+    }
+    else if (command === 'build') {
+        /* Checked before anything is downloaded or staged: a build that would be refused must be
+           refused first, not after twenty minutes of Electron. */
+        const manifest = await doctor(cwd, resources);
+        await build(manifest, cwd, targetsFrom(manifest, rest), resources);
+    }
+    else {
+        throw new Error('usage: drift-package <init|bootstrap|doctor|build|run|verify|steam> [--project=<dir>] ' +
+            `[--target=<target>] [--resources=<dir>] [--out=<dir>] [--force] — got "${String(command)}"`);
+    }
+}
+catch (cause) {
+    console.error(String(cause instanceof Error ? cause.message : cause));
+    process.exit(1);
+}

package/dist/flags.d.ts

@@ -0,0 +1,57 @@
+import type { PackageManifest, Target } from './manifest.ts';
+/**
+ * The Chromium switches a shipped build launches with.
+ *
+ * **This is most of why the packager exists.** Every switch below was paid for once already, in
+ * this repository or by a consumer, and a game that wraps Electron by hand rediscovers each of
+ * them — two of them only by measuring a frame nobody thought to measure.
+ *
+ * **What this costs**: the flags are ours rather than the platform's defaults, so a Chromium
+ * change can invalidate one and nothing will say so. **What would make it wrong**: Electron
+ * enabling Vulkan on Linux by default, at which point the first block below becomes a no-op worth
+ * deleting rather than a fix worth keeping.
+ *
+ * **Checked 2026-09-09 and still needed**, on Electron 43.4.1 / Chromium 150.0.7871.224 with an
+ * RX 9070 XT: launched with no switches at all, `navigator.gpu` is present and `requestAdapter`
+ * answers **null**. With the interop feature it hands back an `amd`/`rdna-4` adapter and a device.
+ * So the block below is doing the work rather than riding along, six Chromium majors after it was
+ * written.
+ *
+ * **And a switch is now only asked for on a runtime it has been seen to work on**, because the
+ * other half of "nothing will say so" is a name Chromium does not recognise: unknown features in
+ * `--enable-features` are dropped in silence, and the build that results is indistinguishable from
+ * a machine with no adapter to offer. See `WEBGPU_INTEROP_ELECTRON`.
+ */
+export interface FlagPlan {
+    readonly switches: readonly (readonly [string, string])[];
+    /** Non-null means refuse to build, and this is what to print. */
+    readonly refusal: string | null;
+    /**
+     * What a caller must print, having decided nothing.
+     *
+     * **A switch that names a feature the runtime has never heard of is worse than no switch**, and
+     * that is what these exist for: Chromium ignores an unknown name in `--enable-features` without a
+     * word, so a build that cannot deliver WebGPU looks exactly like a machine whose driver had no
+     * adapter to offer. Where this plan declines to ask for something, it says so out loud.
+     */
+    readonly notes: readonly string[];
+}
+/**
+ * The Electron the Linux WebGPU switch below is written against, and measured on.
+ *
+ * **Not the version the feature was introduced in, which nobody here has established.** It is the
+ * version this repository has run the switch against and watched WebGPU come up: Electron 43.4.1,
+ * Chromium 150.0.7871.224, an RX 9070 XT, where `requestAdapter` answers null without the switch
+ * and hands back an `amd`/`rdna-4` adapter with it. Reported from outside against Electron 33.4.11,
+ * Chromium 130: the feature name is not in that binary at all, and the switch is inert there.
+ *
+ * So a runtime older than this is *unverified*, not known-broken — and the plan declines to ship an
+ * unverified switch rather than shipping one that may do nothing silently.
+ */
+export declare const WEBGPU_INTEROP_ELECTRON = 43;
+/**
+ * @param electronMajor The major version of the Electron these switches will be applied to, or
+ *   `null` where a caller genuinely cannot know. Both callers in this package can: the build reads
+ *   it out of the installed package, and the main process reads it out of `process.versions`.
+ */
+export declare function planFlags(manifest: PackageManifest, target: Target, electronMajor?: number | null): FlagPlan;