@driftengine/package 3.61.0

package/src/steam/main.ts

@@ -0,0 +1,69 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+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;
+}
+
+interface SteamClient {
+  achievement: { activate(name: string): boolean };
+  localplayer: { setRichPresence(key: string, value: string | undefined): void };
+  cloud: SteamCloud;
+}
+
+export function openSteam(appId: number | null, appRoot: string): SteamRuntime | null {
+  if (appId === null) return null;
+
+  let client: SteamClient;
+  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') as { init(appId: number): SteamClient };
+    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/src/templates/buildWindows.ts

@@ -0,0 +1,163 @@
+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 function buildWindowsScript(manifest: PackageManifest): string {
+  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/src/templates/packageWrapper.ts

@@ -0,0 +1,82 @@
+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 function packageWrapperScript(manifest: PackageManifest): string {
+  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/src/toolchain.ts

@@ -0,0 +1,210 @@
+import { access, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+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 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'] as const,
+  /** 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)' },
+} as const;
+
+/**
+ * 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(): string {
+  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');
+}
+
+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;
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The JDK this machine will use, preferring one it already has. */
+export async function findJavaHome(): Promise<string | null> {
+  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(): Promise<string | null> {
+  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(): Promise<string | null> {
+  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(): Promise<string | null> {
+  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(): Promise<string | null> {
+  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: Target,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  return (target === 'mac-arm64' || target === 'mac-x64') && platform !== 'darwin';
+}
+
+export async function androidToolchain(): Promise<AndroidToolchain | null> {
+  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: Target): readonly string[] {
+  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: string): Promise<void> {
+  await mkdir(path, { recursive: true });
+}
+
+function javac(): string {
+  return process.platform === 'win32' ? 'javac.exe' : 'javac';
+}
+
+function gradleBinary(): string {
+  return process.platform === 'win32' ? 'gradle.bat' : 'gradle';
+}