@driftengine/package 3.61.0

package/dist/steam/main.d.ts

@@ -0,0 +1,22 @@
+import type { SteamCloud } from './cloudStore.ts';
+/**
+ * Steam, opened in the only process that can hold it.
+ *
+ * **`steamworks.js` is a native Node module and the renderer has no Node.** It runs sandboxed with
+ * `contextIsolation` on, which is what keeps a game — and any third-party code, mod or shader it
+ * loads — away from the filesystem. So the SDK lives here, in the main process, and reaches a game
+ * through the same audited bridge as every other capability.
+ *
+ * **Every failure is `null`, and there are three ordinary ones**: the manifest named no app, the
+ * module is not installed, or the copy was launched outside Steam. A game must run in all three —
+ * that last one is every run during development — so none of them throws.
+ *
+ * `steamworks.js` rather than `greenworks`, whose own README describes itself as maintained on a
+ * best-effort basis. A store integration on a release's critical path is the wrong place for that.
+ */
+export interface SteamRuntime {
+    readonly cloud: SteamCloud;
+    unlockAchievement(id: string): void;
+    setRichPresence(text: string): void;
+}
+export declare function openSteam(appId: number | null, appRoot: string): SteamRuntime | null;

package/dist/steam/main.js

@@ -0,0 +1,41 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+export function openSteam(appId, appRoot) {
+    if (appId === null)
+        return null;
+    let client;
+    try {
+        /*
+         * Resolved from the packaged application's own `node_modules`, which is where `stage.ts` puts
+         * it — not from this file's location, which at run time is inside a bundle.
+         */
+        const require = createRequire(join(appRoot, 'package.json'));
+        const steamworks = require('steamworks.js');
+        client = steamworks.init(appId);
+    }
+    catch (cause) {
+        /* Named rather than silent: a developer who expected achievements and got none should be able
+           to see which of the three ordinary reasons it was. */
+        console.log(`[driftengine] Steam is not available: ${String(cause)}`);
+        return null;
+    }
+    return {
+        cloud: client.cloud,
+        unlockAchievement: (id) => {
+            try {
+                client.achievement.activate(id);
+            }
+            catch {
+                /* An achievement that fails to unlock is not a reason for a frame to stop. */
+            }
+        },
+        setRichPresence: (text) => {
+            try {
+                client.localplayer.setRichPresence('steam_display', text);
+            }
+            catch {
+                /* As above. */
+            }
+        },
+    };
+}

package/dist/templates/buildWindows.d.ts

@@ -0,0 +1,16 @@
+import type { PackageManifest } from '../manifest.ts';
+/**
+ * The PowerShell a consumer needs on the machine that builds their Windows artifacts.
+ *
+ * **This is a template and not a shipped script because it has to be a file in their repository**:
+ * something has to start Node on that machine, and that something cannot live inside a Node
+ * program. Everything in it that could have lived in `drift-package` already does — see
+ * `runtime.ts` and `identity.ts`.
+ *
+ * **Pure ASCII, and `scripts/packaging.test.mjs` asserts it.** Windows PowerShell 5.1, which is
+ * what a fresh Windows machine runs, reads a BOM-less `.ps1` in the system ANSI codepage rather
+ * than as UTF-8, so one typographic character in a comment arrives as mojibake and takes the
+ * *parser* with it — four errors deep, pointing at lines whose content is fine, and invisible from
+ * Linux.
+ */
+export declare function buildWindowsScript(manifest: PackageManifest): string;

package/dist/templates/buildWindows.js

@@ -0,0 +1,161 @@
+/**
+ * The PowerShell a consumer needs on the machine that builds their Windows artifacts.
+ *
+ * **This is a template and not a shipped script because it has to be a file in their repository**:
+ * something has to start Node on that machine, and that something cannot live inside a Node
+ * program. Everything in it that could have lived in `drift-package` already does — see
+ * `runtime.ts` and `identity.ts`.
+ *
+ * **Pure ASCII, and `scripts/packaging.test.mjs` asserts it.** Windows PowerShell 5.1, which is
+ * what a fresh Windows machine runs, reads a BOM-less `.ps1` in the system ANSI codepage rather
+ * than as UTF-8, so one typographic character in a comment arrives as mojibake and takes the
+ * *parser* with it — four errors deep, pointing at lines whose content is fine, and invisible from
+ * Linux.
+ */
+export function buildWindowsScript(manifest) {
+    const name = manifest.name;
+    const local = `${manifest.id.split('.').pop() ?? 'drift'}-build`;
+    return `# Build the Windows artifacts for ${name}, on Windows, because they are not cross-built.
+#
+# KEEP THIS FILE PURE ASCII. Windows PowerShell 5.1 -- what a fresh Windows machine runs -- reads a
+# .ps1 with no byte-order mark in the system ANSI codepage, not as UTF-8. A single typographic
+# character in a comment arrives as mojibake and takes the parser with it, four errors deep,
+# pointing at lines whose real content is fine. Nothing on Linux would ever show it.
+#
+# Wine can produce an NSIS installer from Linux and cannot reach a Windows certificate store, so
+# the one platform whose warnings are hardest to shake would be the one built with no way to sign
+# it properly.
+#
+#   .\\scripts\\build-windows.ps1
+#   $env:WIN_CSC_LINK = 'C:\\certs\\code.pfx'; $env:WIN_CSC_KEY_PASSWORD = '...'   # when there is one
+#
+# With no certificate the build succeeds and is unsigned: SmartScreen warns on first launch.
+#
+# Written by \`drift-package init\`. Edit it and it is yours; init will not overwrite it without
+# --force.
+
+$ErrorActionPreference = 'Stop'
+$ProjectDir = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$SourceDir = $ProjectDir
+
+function Require-Command($name, $hint) {
+  if ($null -eq (Get-Command $name -ErrorAction SilentlyContinue)) {
+    throw "$name is not on PATH. $hint"
+  }
+}
+
+Require-Command node 'Install Node 22.12 or newer from https://nodejs.org'
+Require-Command npm  'It ships with Node'
+
+$version = (node --version).TrimStart('v')
+if ([version]($version -split '-')[0] -lt [version]'22.12.0') {
+  throw "Node $version is too old; this project needs 22.12.0 or newer"
+}
+
+if (-not (Test-Path (Join-Path $ProjectDir 'drift.package.json'))) {
+  throw "No drift.package.json in $ProjectDir. That file is what a build is configured from."
+}
+
+# ELECTRON_RUN_AS_NODE turns Electron into plain Node, and an Electron-based terminal sets it for
+# everything it spawns. Inherited, the build produces an artifact that dies on 'Cannot find module
+# electron' with a Node banner, which looks nothing like its cause.
+Remove-Item Env:\\ELECTRON_RUN_AS_NODE -ErrorAction SilentlyContinue
+
+# A native command's exit code does not trip $ErrorActionPreference.
+#
+# That preference governs PowerShell cmdlets. npm is an external program: a non-zero exit sets
+# $LASTEXITCODE and otherwise does nothing. So a failing step could print a real, useful error, the
+# script would carry straight on, and the only thing left to read was a complaint about a directory
+# that was never going to exist. PowerShell 7.3 has $PSNativeCommandUseErrorActionPreference and
+# 5.1 does not, so it is checked by hand and each step says which step it was.
+function Invoke-Step($what, [scriptblock] $step) {
+  Write-Host "\`n== $what"
+  & $step
+  if ($LASTEXITCODE -ne 0) {
+    throw "$what failed with exit code $LASTEXITCODE. The reason is in the output above this line."
+  }
+}
+
+# A build on a mapped or network drive relocates itself to a local disk first.
+#
+# Node's fs.cp refuses to copy a thing into itself and decides that by comparing dev and ino of the
+# destination's parents against the source. A redirector that gets no file index from the server
+# invents one, and on Windows dev is already the volume serial number -- so a file and a directory
+# come back identical and the first staging copy fails, talking about subdirectories of itself.
+# \`drift-package doctor\` refuses that up front and names --out=<dir>; this relocates instead,
+# because the artifacts have to end up back in the checkout either way.
+#
+# node_modules is deliberately not copied: it is reinstalled locally, which is also what stops a
+# Windows npm ci from overwriting a Linux checkout's tree when the share is one in use.
+$root = [System.IO.Path]::GetPathRoot($ProjectDir)
+$driveType = $null
+try {
+  $driveType = (New-Object System.IO.DriveInfo($root)).DriveType
+} catch {
+  # An unusual root is not worth failing a build over; treat it as fixed and let the build speak.
+}
+
+if ($driveType -ne $null -and $driveType -ne 'Fixed') {
+  $local = Join-Path $env:LOCALAPPDATA '${local}'
+  Write-Warning ("$ProjectDir is on a $driveType drive, which cannot hold this build. Copying to " +
+    "$local and building there instead.")
+  Write-Host ''
+  Write-Host "== robocopy to $local"
+  robocopy $ProjectDir $local /E /XD node_modules out dist .git /NFL /NDL /NJH /NJS /NP
+  # robocopy's exit code is a bitmask, not a status: under 8 means it did its job, and 1 is "files
+  # were copied", which is the ordinary success and reads as failure to every other tool.
+  if ($LASTEXITCODE -ge 8) {
+    throw "robocopy failed with exit code $LASTEXITCODE while copying $ProjectDir to $local."
+  }
+  $global:LASTEXITCODE = 0
+  $ProjectDir = $local
+  Write-Host "Building from $ProjectDir"
+}
+
+Push-Location $ProjectDir
+try {
+  Invoke-Step 'npm ci' { npm ci }
+  Invoke-Step 'drift-package doctor' { node scripts/package.mjs doctor }
+  Invoke-Step 'drift-package build' { node scripts/package.mjs build --target=win-x64 }
+
+  # Built, said it succeeded, and produced nothing: worth its own sentence rather than an ENOENT
+  # from Get-ChildItem, which is what this looks like otherwise.
+  $out = Join-Path $ProjectDir 'out\\win-x64'
+  if (-not (Test-Path $out)) {
+    throw ('The build reported success and ' + $out + ' does not exist. Nothing was packaged. ' +
+      'Run the build step on its own and read what it prints.')
+  }
+
+  # The artifacts go back to the checkout this was run from.
+  #
+  # Relocating the build makes this necessary, and it is easy to miss: the build succeeds, says so,
+  # lists its files, and out\\ in the project is empty because the build happened somewhere else.
+  # robocopy and not fs.cp: this writes back onto the share, and fs.cp is exactly what will not
+  # cross it.
+  if ($SourceDir -ne $ProjectDir) {
+    $back = Join-Path $SourceDir 'out\\win-x64'
+    Write-Host ''
+    Write-Host "== copying the artifacts back to $back"
+    robocopy $out $back /E /NFL /NDL /NJH /NJS /NP
+    if ($LASTEXITCODE -ge 8) {
+      throw ("The build succeeded but copying the artifacts from $out back to $back failed with " +
+        "robocopy exit code $LASTEXITCODE. They are still in $out -- nothing is lost.")
+    }
+    $global:LASTEXITCODE = 0
+    $out = $back
+  }
+
+  Write-Host "\`nArtifacts:"
+  Get-ChildItem -Path $out -File | ForEach-Object { $_.FullName }
+
+  if (-not ($env:WIN_CSC_LINK -or $env:CSC_LINK)) {
+    Write-Host ""
+    Write-Host "This build is unsigned. Windows will run it; SmartScreen warns on first launch."
+    Write-Host "A Steam depot raises no warning, because the client delivering it is signed."
+    Write-Host "An OV certificate in WIN_CSC_LINK removes the warning for direct downloads."
+  }
+} finally {
+  Pop-Location
+}
+`;
+}

package/dist/templates/packageWrapper.d.ts

@@ -0,0 +1,9 @@
+import type { PackageManifest } from '../manifest.ts';
+/**
+ * The Node launcher a consumer puts in their own repository, and why it cannot be a line in
+ * `package.json`.
+ *
+ * Every line below is a failure somebody has already had on a Windows machine, where the person
+ * who wrote the script is not the person watching it fail.
+ */
+export declare function packageWrapperScript(manifest: PackageManifest): string;

package/dist/templates/packageWrapper.js

@@ -0,0 +1,80 @@
+/**
+ * The Node launcher a consumer puts in their own repository, and why it cannot be a line in
+ * `package.json`.
+ *
+ * Every line below is a failure somebody has already had on a Windows machine, where the person
+ * who wrote the script is not the person watching it fail.
+ */
+export function packageWrapperScript(manifest) {
+    return `#!/usr/bin/env node
+/**
+ * \`drift-package\` for ${manifest.name}.
+ *
+ *   node scripts/package.mjs doctor
+ *   node scripts/package.mjs build --target=win-x64
+ *
+ * Written by \`drift-package init\`. Edit it and it is yours; init will not overwrite it without
+ * --force.
+ *
+ * **The CLI is launched with this Node, never through npx.** 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 a platform where paths contain spaces. Launching the
+ * Node that is already running avoids the question, and uses the copy of the tool this project
+ * locked rather than whichever one npx decides to find.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+
+/*
+ * Where the packager's executable is.
+ *
+ * \`@driftengine/package\` declares no \`exports\`, so its \`package.json\` resolves by the old rules and
+ * the \`bin\` it names is read from there rather than guessed at. A copy of the engine that was
+ * vendored instead of installed will not resolve at all, and the message says which of the two
+ * situations you are in instead of a module-not-found.
+ */
+let bin;
+try {
+  const manifest = require.resolve('@driftengine/package/package.json');
+  const declared = JSON.parse(readFileSync(manifest, 'utf8')).bin;
+  const relative = typeof declared === 'string' ? declared : declared?.['drift-package'];
+  bin = path.join(path.dirname(manifest), relative);
+} catch {
+  console.error(
+    'Could not resolve @driftengine/package. If the engine is installed, run npm ci. If it is ' +
+      'vendored, point \`bin\` below at the vendored bin/drift-package.mjs and keep the rest of ' +
+      'this file as it is: what the rest of it does is report failures npm and Windows would ' +
+      'otherwise swallow.',
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, [bin, ...process.argv.slice(2)], {
+  cwd: REPO_ROOT,
+  stdio: 'inherit',
+});
+
+/*
+ * **spawnSync does not throw**, and this is the half that is easy to leave out. If the process
+ * never starts it puts the reason in \`result.error\` and leaves \`status\` at null, 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. On a Windows machine that looked like
+ * a bare "failed with exit code 1" and cost half a day.
+ */
+if (result.error !== undefined) {
+  console.error(\`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/toolchain.d.ts

@@ -0,0 +1,101 @@
+import type { Target } from './manifest.ts';
+/**
+ * Everything a build needs that is not a Node package, and where it goes.
+ *
+ * **Pinned, downloaded, and kept outside the repository.** A packaging toolchain is gigabytes of
+ * Java, an Android SDK and a Gradle distribution; none of it belongs in a git tree, and none of it
+ * should be a paragraph in a README telling somebody to install seven things by hand. `bootstrap`
+ * fetches exactly these versions into a cache, and a machine that already has a working toolchain
+ * is used as it is rather than duplicated.
+ *
+ * **Versions are pinned rather than tracked.** A build that quietly moved to a new Android build
+ * tools release is a build whose output changed for a reason nobody recorded. Moving one of these
+ * is a commit with a reason in it.
+ */
+export declare const PINS: {
+    /** Temurin 21. AGP 8.7 needs 17 or newer; 21 is the current long-term release. */
+    readonly jdk: {
+        readonly feature: '21';
+        readonly label: 'Temurin JDK 21';
+    };
+    /** Google's command-line tools bundle, which is what installs the rest of the SDK. */
+    readonly androidTools: {
+        readonly build: '13114758';
+        readonly label: 'Android command-line tools';
+    };
+    /** What an APK is actually compiled against. */
+    readonly androidPackages: readonly ['platform-tools', 'platforms;android-35', 'build-tools;35.0.0'];
+    /** AGP 8.7.3 requires Gradle 8.9 or newer. */
+    readonly gradle: {
+        readonly version: '8.9';
+        readonly label: 'Gradle 8.9';
+    };
+    /**
+     * XcodeGen, which turns a spec into an `.xcodeproj`.
+     *
+     * A `.xcodeproj` is a generated artefact full of absolute paths and a merge conflict in every
+     * pull request. Generating it means the repository holds a readable spec instead — and unlike
+     * Xcode itself, this is a single binary that can be downloaded.
+     */
+    readonly xcodegen: {
+        readonly version: '2.42.0';
+        readonly label: 'XcodeGen 2.42.0';
+    };
+    /**
+     * `rcodesign`, which is what signs a Mac target built anywhere but a Mac.
+     *
+     * Apple's `codesign` is macOS only and electron-builder silently skips signing without it, so
+     * without this a cross-built `.app` is unsigned and the loader on Apple Silicon refuses it.
+     * This is the one implementation of Apple's code signature format that runs on Linux.
+     *
+     * The Linux asset is linked against musl and is a single static binary, so it does not care
+     * which distribution it lands on and installs nothing system-wide.
+     */
+    readonly rcodesign: {
+        readonly version: '0.29.0';
+        readonly label: 'rcodesign 0.29.0 (apple-codesign)';
+    };
+};
+/**
+ * Where downloaded tools live.
+ *
+ * Outside the project on purpose: two games on one machine share one Android SDK, and a `git
+ * clean` must not cost half a gigabyte of downloads.
+ */
+export declare function toolchainHome(): string;
+export interface AndroidToolchain {
+    readonly javaHome: string;
+    readonly sdkRoot: string;
+    /** The `gradle` executable to invoke. */
+    readonly gradle: string;
+    /** Whether these came from the machine rather than from the cache. */
+    readonly system: boolean;
+}
+/** The JDK this machine will use, preferring one it already has. */
+export declare function findJavaHome(): Promise<string | null>;
+/** The Android SDK this machine will use, preferring one it already has. */
+export declare function findAndroidSdk(): Promise<string | null>;
+/** The Gradle this machine will use. A system one is taken at whatever version it is. */
+export declare function findGradle(): Promise<string | null>;
+/** XcodeGen, from the cache or from the machine. */
+export declare function findXcodeGen(): Promise<string | null>;
+/**
+ * The `rcodesign` this machine will use, from the cache or from the machine.
+ *
+ * A system one is taken at whatever version it is, the way Gradle and XcodeGen are: this signs
+ * with a format Apple has not changed in years, and a person who installed it deliberately has a
+ * reason. `cargo install apple-codesign` puts one in `~/.cargo/bin`, which is why that is looked
+ * at — it is the route on an architecture the release page has no asset for.
+ */
+export declare function findRcodesign(): Promise<string | null>;
+/**
+ * Whether a target signs with `rcodesign` rather than with the host's own signer.
+ *
+ * The one condition is a Mac target that is not being built on a Mac. Kept here beside the tool
+ * it decides about, so `doctor`, `bootstrap` and `build` cannot disagree about when it is needed.
+ */
+export declare function needsRcodesign(target: Target, platform?: NodeJS.Platform): boolean;
+export declare function androidToolchain(): Promise<AndroidToolchain | null>;
+/** Which of the pinned tools a target needs, in the words `doctor` prints. */
+export declare function requirementsFor(target: Target): readonly string[];
+export declare function ensureDir(path: string): Promise<void>;

package/dist/toolchain.js

@@ -0,0 +1,186 @@
+import { access, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Everything a build needs that is not a Node package, and where it goes.
+ *
+ * **Pinned, downloaded, and kept outside the repository.** A packaging toolchain is gigabytes of
+ * Java, an Android SDK and a Gradle distribution; none of it belongs in a git tree, and none of it
+ * should be a paragraph in a README telling somebody to install seven things by hand. `bootstrap`
+ * fetches exactly these versions into a cache, and a machine that already has a working toolchain
+ * is used as it is rather than duplicated.
+ *
+ * **Versions are pinned rather than tracked.** A build that quietly moved to a new Android build
+ * tools release is a build whose output changed for a reason nobody recorded. Moving one of these
+ * is a commit with a reason in it.
+ */
+export const PINS = {
+    /** Temurin 21. AGP 8.7 needs 17 or newer; 21 is the current long-term release. */
+    jdk: { feature: '21', label: 'Temurin JDK 21' },
+    /** Google's command-line tools bundle, which is what installs the rest of the SDK. */
+    androidTools: { build: '13114758', label: 'Android command-line tools' },
+    /** What an APK is actually compiled against. */
+    androidPackages: ['platform-tools', 'platforms;android-35', 'build-tools;35.0.0'],
+    /** AGP 8.7.3 requires Gradle 8.9 or newer. */
+    gradle: { version: '8.9', label: 'Gradle 8.9' },
+    /**
+     * XcodeGen, which turns a spec into an `.xcodeproj`.
+     *
+     * A `.xcodeproj` is a generated artefact full of absolute paths and a merge conflict in every
+     * pull request. Generating it means the repository holds a readable spec instead — and unlike
+     * Xcode itself, this is a single binary that can be downloaded.
+     */
+    xcodegen: { version: '2.42.0', label: 'XcodeGen 2.42.0' },
+    /**
+     * `rcodesign`, which is what signs a Mac target built anywhere but a Mac.
+     *
+     * Apple's `codesign` is macOS only and electron-builder silently skips signing without it, so
+     * without this a cross-built `.app` is unsigned and the loader on Apple Silicon refuses it.
+     * This is the one implementation of Apple's code signature format that runs on Linux.
+     *
+     * The Linux asset is linked against musl and is a single static binary, so it does not care
+     * which distribution it lands on and installs nothing system-wide.
+     */
+    rcodesign: { version: '0.29.0', label: 'rcodesign 0.29.0 (apple-codesign)' },
+};
+/**
+ * Where downloaded tools live.
+ *
+ * Outside the project on purpose: two games on one machine share one Android SDK, and a `git
+ * clean` must not cost half a gigabyte of downloads.
+ */
+export function toolchainHome() {
+    const override = process.env.DRIFT_TOOLCHAIN_HOME;
+    if (typeof override === 'string' && override.length > 0)
+        return override;
+    const cache = process.env.XDG_CACHE_HOME;
+    const base = typeof cache === 'string' && cache.length > 0 ? cache : join(homedir(), '.cache');
+    return join(base, 'driftengine', 'toolchain');
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The JDK this machine will use, preferring one it already has. */
+export async function findJavaHome() {
+    const fromEnv = process.env.JAVA_HOME;
+    if (typeof fromEnv === 'string' &&
+        fromEnv.length > 0 &&
+        (await exists(join(fromEnv, 'bin', javac())))) {
+        return fromEnv;
+    }
+    const cached = join(toolchainHome(), 'jdk');
+    return (await exists(join(cached, 'bin', javac()))) ? cached : null;
+}
+/** The Android SDK this machine will use, preferring one it already has. */
+export async function findAndroidSdk() {
+    for (const name of ['ANDROID_HOME', 'ANDROID_SDK_ROOT']) {
+        const root = process.env[name];
+        if (typeof root === 'string' &&
+            root.length > 0 &&
+            (await exists(join(root, 'platform-tools')))) {
+            return root;
+        }
+    }
+    const cached = join(toolchainHome(), 'android-sdk');
+    return (await exists(join(cached, 'platform-tools'))) ? cached : null;
+}
+/** The Gradle this machine will use. A system one is taken at whatever version it is. */
+export async function findGradle() {
+    const cached = join(toolchainHome(), `gradle-${PINS.gradle.version}`, 'bin', gradleBinary());
+    if (await exists(cached))
+        return cached;
+    return null;
+}
+/** XcodeGen, from the cache or from the machine. */
+export async function findXcodeGen() {
+    const cached = join(toolchainHome(), `xcodegen-${PINS.xcodegen.version}`, 'bin', 'xcodegen');
+    if (await exists(cached))
+        return cached;
+    /* Installed by Homebrew or Mint, which many Macs already have. */
+    for (const path of ['/opt/homebrew/bin/xcodegen', '/usr/local/bin/xcodegen']) {
+        if (await exists(path))
+            return path;
+    }
+    return null;
+}
+/**
+ * The `rcodesign` this machine will use, from the cache or from the machine.
+ *
+ * A system one is taken at whatever version it is, the way Gradle and XcodeGen are: this signs
+ * with a format Apple has not changed in years, and a person who installed it deliberately has a
+ * reason. `cargo install apple-codesign` puts one in `~/.cargo/bin`, which is why that is looked
+ * at — it is the route on an architecture the release page has no asset for.
+ */
+export async function findRcodesign() {
+    const cached = join(toolchainHome(), `rcodesign-${PINS.rcodesign.version}`, 'rcodesign');
+    if (await exists(cached))
+        return cached;
+    const home = process.env.HOME;
+    const candidates = [
+        '/usr/local/bin/rcodesign',
+        '/usr/bin/rcodesign',
+        '/opt/homebrew/bin/rcodesign',
+        ...(typeof home === 'string' && home.length > 0
+            ? [join(home, '.cargo', 'bin', 'rcodesign')]
+            : []),
+    ];
+    for (const path of candidates) {
+        if (await exists(path))
+            return path;
+    }
+    return null;
+}
+/**
+ * Whether a target signs with `rcodesign` rather than with the host's own signer.
+ *
+ * The one condition is a Mac target that is not being built on a Mac. Kept here beside the tool
+ * it decides about, so `doctor`, `bootstrap` and `build` cannot disagree about when it is needed.
+ */
+export function needsRcodesign(target, platform = process.platform) {
+    return (target === 'mac-arm64' || target === 'mac-x64') && platform !== 'darwin';
+}
+export async function androidToolchain() {
+    const javaHome = await findJavaHome();
+    const sdkRoot = await findAndroidSdk();
+    const gradle = await findGradle();
+    if (javaHome === null || sdkRoot === null || gradle === null)
+        return null;
+    return {
+        javaHome,
+        sdkRoot,
+        gradle,
+        system: javaHome === process.env.JAVA_HOME || sdkRoot === process.env.ANDROID_HOME,
+    };
+}
+/** Which of the pinned tools a target needs, in the words `doctor` prints. */
+export function requirementsFor(target) {
+    switch (target) {
+        case 'android':
+            return [PINS.jdk.label, PINS.androidTools.label, ...PINS.androidPackages, PINS.gradle.label];
+        case 'ios':
+            /* XcodeGen is downloadable; Xcode is not, and pretending otherwise would be the lie this
+               file exists to avoid — it is a sign-in and an App Store download, and only on a Mac. */
+            return ['macOS', 'Xcode with the iOS SDK', PINS.xcodegen.label];
+        default:
+            return [
+                'the Electron runtime for this platform',
+                /* Only off a Mac, where the platform's own `codesign` is missing. */
+                ...(needsRcodesign(target) ? [PINS.rcodesign.label] : []),
+            ];
+    }
+}
+export async function ensureDir(path) {
+    await mkdir(path, { recursive: true });
+}
+function javac() {
+    return process.platform === 'win32' ? 'javac.exe' : 'javac';
+}
+function gradleBinary() {
+    return process.platform === 'win32' ? 'gradle.bat' : 'gradle';
+}