Skip to content

The agent that grows with you

31.8 KB
Raw Blame
#!/usr/bin/env node
// stage-native-deps.mjs — stages node-pty's native runtime dependencies
//
// Usage:
//   node scripts/stage-native-deps.mjs                # host platform/arch
//   node scripts/stage-native-deps.mjs --platform win32 --arch arm64
//   node scripts/stage-native-deps.mjs --source REPO --out NATIVE_NODE_MODULES
//
// Preparation owns acquisition and helper compilation. beforePack only copies
// the admitted per-target tree.

import { createRequire } from 'node:module'
import { fileURLToPath } from 'node:url'
import { dirname, resolve, join } from 'node:path'
import {
  chmodSync,
  copyFileSync,
  existsSync,
  lstatSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  rmdirSync,
  rmSync,
  unlinkSync,
  writeFileSync
} from 'node:fs'
import { spawnSync } from 'node:child_process'
import { isMain } from './utils.mjs'
import { recordNativeInputs } from './prepared-native-deps.mjs'
import { buildCommandScreenshotMonitor } from './build-command-screenshot-monitor.mjs'
import { buildHudModifierMonitor, hudModifierBinaryRelativePath } from './build-hud-modifier-monitor.mjs'
import { parseArgs } from 'node:util'
import { productOutput, withProduct, workspaceTool } from '../../../scripts/build/frontend-common.mjs'

const here = dirname(fileURLToPath(import.meta.url))
const projectRoot = resolve(here, '..')
const require = createRequire(import.meta.url)

function makeExecutable(filePath) {
  chmodSync(filePath, 0o755)
}

// ─── libuv-safe fs primitives ────────────────────────────────────────
//
// Node's native (non-libuv) rewrite of fs.cpSync/fs.rmSync mishandles
// non-ASCII Windows paths (observed on v24.11.1 with an accented Windows
// user name, i.e. a default %LOCALAPPDATA%\hermes home): a recursive
// cpSync fails with EIO "Access is denied" or hard-crashes the process,
// an overwriting cpSync fails with a bogus errno-0 unlink error, and
// rmSync silently deletes nothing — leaving a half-staged tree that
// breaks every retry. Fixed upstream (nodejs/node#61878 → v24.15.0;
// nodejs/node#56049 → v24.13.1), but the installer builds on whatever
// Node the user already has, so staging sticks to libuv-backed
// primitives (copyFileSync/unlinkSync/rmdirSync/readdirSync), which
// handle those paths correctly on every affected version.

/** Recursively copy a directory without fs.cpSync. */
function copyDirSync(srcDir, destDir) {
  mkdirSync(destDir, { recursive: true })
  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
    const src = join(srcDir, entry.name)
    const dest = join(destDir, entry.name)
    if (entry.isDirectory()) {
      copyDirSync(src, dest)
    } else {
      copyFileSync(src, dest)
    }
  }
}

/**
 * Recursively delete a path without fs.rmSync — missing paths are fine,
 * a plain file or symlink at the path is unlinked (rm -rf semantics).
 * Verifies the tree is actually gone afterwards: a silent no-op here
 * surfaces later as an inexplicable staging failure, so fail loudly.
 *
 * Also used by before-pack.mjs as the fallback when the native rmSync
 * silently leaves the stale unpacked dir behind.
 */
export function removeDirSync(dir) {
  let stats
  try {
    stats = lstatSync(dir)
  } catch {
    return
  }
  if (!stats.isDirectory()) {
    unlinkSync(dir)
    return
  }
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name)
    if (entry.isDirectory()) {
      removeDirSync(full)
    } else {
      unlinkSync(full)
    }
  }
  rmdirSync(dir)
  if (existsSync(dir)) {
    throw new Error(`[stage-native-deps] failed to remove ${dir}`)
  }
}

function patchUnixTerminalAsarPaths(destRoot) {
  const filePath = join(destRoot, 'lib', 'unixTerminal.js')
  if (!existsSync(filePath)) return

  const source = readFileSync(filePath, 'utf8')
  const patched = source
    .replace(
      "helperPath = helperPath.replace('app.asar', 'app.asar.unpacked');",
      "helperPath = helperPath.replace(/app\\.asar(?!\\.unpacked)/, 'app.asar.unpacked');"
    )
    .replace(
      "helperPath = helperPath.replace('node_modules.asar', 'node_modules.asar.unpacked');",
      "helperPath = helperPath.replace(/node_modules\\.asar(?!\\.unpacked)/, 'node_modules.asar.unpacked');"
    )

  if (patched !== source) {
    writeFileSync(filePath, patched)
  }
}

/**
 * Locate node-pty's package root via real module resolution, so this
 * works whether it's hoisted to a workspace root or local to this app.
 */
function resolveNodePtyRoot(appRoot = projectRoot) {
  const pkgJsonPath = require.resolve('node-pty/package.json', {
    paths: [appRoot]
  })
  return dirname(pkgJsonPath)
}

function copyGlobByExt(srcDir, destDir, extensions) {
  if (!existsSync(srcDir)) return
  mkdirSync(destDir, { recursive: true })
  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
    if (entry.isDirectory()) {
      copyGlobByExt(join(srcDir, entry.name), join(destDir, entry.name), extensions)
      continue
    }
    if (extensions.some((ext) => entry.name.endsWith(ext))) {
      mkdirSync(destDir, { recursive: true })
      copyFileSync(join(srcDir, entry.name), join(destDir, entry.name))
    }
  }
}

/**
 * Copies the locally-compiled build/Release output (used when no prebuild
 * was available and node-pty was built from source for the host machine).
 *
 * Filters by name/pattern rather than extension only: macOS builds a
 * separate `spawn-helper` executable (no file extension) that
 * lib/unixTerminal.js requires at a fixed relative path. Filtering this
 * directory by ['.node'] silently drops it — the package then looks
 * fine, ships fine, and crashes the first time a terminal is spawned.
 * Directories are copied wholesale to also cover any nested native
 * payload (e.g. a conpty/ subfolder some build layouts produce).
 */
function copyBuildRelease(srcDir, destDir) {
  if (!existsSync(srcDir)) return
  mkdirSync(destDir, { recursive: true })
  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
    if (entry.isDirectory()) {
      copyDirSync(join(srcDir, entry.name), join(destDir, entry.name))
      continue
    }
    if (entry.name === 'spawn-helper' || /\.(node|dll|exe)$/.test(entry.name)) {
      const destFile = join(destDir, entry.name)
      copyFileSync(join(srcDir, entry.name), destFile)
      if (entry.name === 'spawn-helper') {
        makeExecutable(destFile)
      }
    }
  }
}

// ─── binary classification ───────────────────────────────────────────
//
// .node files are shared libraries in the target platform's native binary
// format. By reading the first few bytes (magic) we can determine which
// platform a given .node was compiled for, without shelling out to `file`.
//
//   ELF  (\x7fELF)                         → linux
//   Mach-O 32-bit BE  (feedface)            → darwin
//   Mach-O 64-bit BE  (feedfacf)            → darwin
//   Mach-O 32-bit LE  (cefaedfe — CIGAM)    → darwin
//   Mach-O 64-bit LE  (cffaedfe — CIGAM_64) → darwin
//   Fat/Universal BE (cafebabe)             → darwin
//   Fat/Universal LE (bebafeca — FAT_CIGAM) → darwin
//   PE (MZ DOS header)                      → win32
//
// Mach-O and Fat binaries are stored on disk in the host's native byte
// order. On x64/arm64 Darwin (every Apple Silicon + every Intel Mac that
// ships node-pty prebuilds) that is little-endian, so the on-disk magic is
// the CIGAM byte-swapped form, NOT the big-endian MH_MAGIC form. Checking
// only the BE constants misclassifies every real Darwin prebuild as unknown.
//
// Exported for unit testing.

/**
 * Classify a native binary's target platform from its magic bytes.
 * Returns `'linux'`, `'darwin'`, `'win32'`, or `null` if unrecognized
 * or the file cannot be read.
 */
export function classifyNativeBinary(filePath) {
  let buf
  try {
    buf = readFileSync(filePath, { start: 0, end: 63 }) // first 64 bytes
  } catch {
    return null
  }
  if (buf.length < 4) return null

  // ELF: \x7f E L F
  if (buf[0] === 0x7f && buf[1] === 0x45 && buf[2] === 0x4c && buf[3] === 0x46) {
    return 'linux'
  }
  // Mach-O 32-bit (big-endian / MH_MAGIC): feedface
  if (buf[0] === 0xfe && buf[1] === 0xed && buf[2] === 0xfa && buf[3] === 0xce) {
    return 'darwin'
  }
  // Mach-O 64-bit (big-endian / MH_MAGIC_64): feedfacf
  if (buf[0] === 0xfe && buf[1] === 0xed && buf[2] === 0xfa && buf[3] === 0xcf) {
    return 'darwin'
  }
  // Mach-O 32-bit (little-endian / MH_CIGAM): cefaedfe
  if (buf[0] === 0xce && buf[1] === 0xfa && buf[2] === 0xed && buf[3] === 0xfe) {
    return 'darwin'
  }
  // Mach-O 64-bit (little-endian / MH_CIGAM_64): cffaedfe
  if (buf[0] === 0xcf && buf[1] === 0xfa && buf[2] === 0xed && buf[3] === 0xfe) {
    return 'darwin'
  }
  // Fat/Universal binary (big-endian / FAT_MAGIC): cafebabe
  if (buf[0] === 0xca && buf[1] === 0xfe && buf[2] === 0xba && buf[3] === 0xbe) {
    return 'darwin'
  }
  // Fat/Universal binary (little-endian / FAT_CIGAM): bebafeca
  if (buf[0] === 0xbe && buf[1] === 0xba && buf[2] === 0xfe && buf[3] === 0xca) {
    return 'darwin'
  }
  // PE: MZ DOS header
  if (buf[0] === 0x4d && buf[1] === 0x5a) {
    return 'win32'
  }
  return null
}

/**
 * Scan the staged destination tree for .node files and verify each one's
 * binary platform matches the requested target. Throws on any mismatch.
 *
 * This is the fail-closed safety net: even if a prebuild or build/Release
 * somehow slipped through with the wrong platform, this catches it before
 * the package ships a broken native binary to users.
 */
function validateStagedBinaries(destRoot, targetPlatform) {
  const mismatches = []
  function scan(dir, relPrefix) {
    if (!existsSync(dir)) return
    for (const entry of readdirSync(dir, { withFileTypes: true })) {
      if (entry.isDirectory()) {
        scan(join(dir, entry.name), `${relPrefix}${entry.name}/`)
        continue
      }
      if (!entry.name.endsWith('.node')) continue
      const fullPath = join(dir, entry.name)
      const classified = classifyNativeBinary(fullPath)
      if (classified !== targetPlatform) {
        mismatches.push({ file: `${relPrefix}${entry.name}`, classified, expected: targetPlatform })
      }
    }
  }
  scan(join(destRoot, 'prebuilds'), 'prebuilds/')
  scan(join(destRoot, 'build', 'Release'), 'build/Release/')
  if (mismatches.length > 0) {
    throw new Error(
      `[stage-native-deps] native binary platform mismatch (target=${targetPlatform}):\n` +
        mismatches
          .map((m) => `  ${m.file}: expected ${m.expected}, got ${m.classified ?? 'unknown'}`)
          .join('\n') +
        `\nRefusing to stage a binary compiled for the wrong platform.`
    )
  }
}

/**
 * Stage node-pty's native runtime dependencies into `destRoot`.
 *
 * Exported separately from `stageNodePty` so tests can supply a fake
 * node-pty source tree without going through real module resolution.
 *
 * Strategy (fail-closed):
 *
 * 1. Copy the matching prebuild (`prebuilds/<platform>-<arch>/`) if present.
 * 2. Copy `build/Release/` **only when the target matches the host** —
 *    build/Release contains a binary compiled for the host's platform/arch,
 *    so staging it for a different target ships a broken app.
 * 3. If no native binary was staged:
 *    - Same platform as host, different arch → run `electron-rebuild --arch`.
 *    - Different platform from host → throw (cannot cross-compile native
 *      modules; build on the target platform or provide a prebuild).
 * 4. Validate every staged `.node` file's binary platform matches the target.
 */
export function stageNodePtyInto(srcRoot, destRoot, { platform = process.platform, arch = process.arch, appRoot = projectRoot } = {}) {
  const hostMatch = platform === process.platform && arch === process.arch

  removeDirSync(destRoot)
  mkdirSync(destRoot, { recursive: true })

  // package.json — needed so `require('node-pty')` resolves the package
  // (reads "main") rather than treating it as a directory with no entry.
  copyFileSync(join(srcRoot, 'package.json'), join(destRoot, 'package.json'))

  // lib/**/*.js — the JS surface node-pty's `main` points into.
  copyGlobByExt(join(srcRoot, 'lib'), join(destRoot, 'lib'), ['.js'])
  patchUnixTerminalAsarPaths(destRoot)

  // prebuilds/<platform>-<arch>/* — the prebuild-install payload for the
  // *target* we're packaging, not necessarily the host running this script.
  // Explicit extensions only, to skip the ~25MB of Windows .pdb symbols
  // prebuild-install bundles alongside the .node/.dll.
  const prebuildDir = join(srcRoot, 'prebuilds', `${platform}-${arch}`)
  if (existsSync(prebuildDir)) {
    const destPrebuild = join(destRoot, 'prebuilds', `${platform}-${arch}`)
    mkdirSync(destPrebuild, { recursive: true })
    for (const entry of readdirSync(prebuildDir, { withFileTypes: true })) {
      if (entry.name === 'conpty' && entry.isDirectory()) {
        copyDirSync(join(prebuildDir, 'conpty'), join(destPrebuild, 'conpty'))
        continue
      }
      if (entry.isFile() && /\.(node|dll|exe)$/.test(entry.name)) {
        copyFileSync(join(prebuildDir, entry.name), join(destPrebuild, entry.name))
        continue
      }
      if (entry.name === 'spawn-helper') {
        const destFile = join(destPrebuild, entry.name)
        copyFileSync(join(prebuildDir, entry.name), destFile)
        makeExecutable(destFile)
      }
    }
  }

  // build/Release/* — present when node-pty was compiled locally
  // (e.g. no prebuild available for this Electron ABI/platform combo).
  // Only stage this when the target matches the host, because
  // build/Release contains a binary compiled for the *host's* platform
  // and architecture. Staging a host binary for a different target (e.g.
  // a macOS Mach-O .node staged for a linux-arm64 target) ships a broken
  // app that crashes the first time a terminal is spawned.
  if (hostMatch) {
    const buildReleaseDir = join(srcRoot, 'build/Release')
    copyBuildRelease(buildReleaseDir, join(destRoot, 'build/Release'))
  }

  // Check whether a native binary for this target was staged.
  const stagedDirs = [
    join(destRoot, 'prebuilds', `${platform}-${arch}`),
    join(destRoot, 'build/Release')
  ]
  const hasNativeBinary = stagedDirs.some((dir) => {
    if (!existsSync(dir)) return false
    return readdirSync(dir, { recursive: true }).some((name) => String(name).endsWith('.node'))
  })

  if (!hasNativeBinary) {
    if (platform !== process.platform) {
      throw new Error(
        `[stage-native-deps] no prebuilt binary for ${platform}-${arch} and ` +
          `cannot cross-compile native modules from ${process.platform}-${process.arch}. ` +
          `Build on the target platform or provide a prebuild.`
      )
    }
    // Same platform, possibly different arch — rebuild from source with
    // the target architecture so electron-rebuild produces the correct
    // binary rather than defaulting to the host's arch.
    console.log(
      `[stage-native-deps] no native binary for ${platform}-${arch}; ` +
        `running electron-rebuild (target arch: ${arch})...`
    )
    const rebuildArgs = [
      join(dirname(workspaceTool(resolve(appRoot, '../..'), 'apps/desktop', '@electron/rebuild')), 'cli.js'),
      '-f',
      '-w',
      'node-pty',
      '--arch',
      arch
    ]
    const result = spawnSync(process.execPath, rebuildArgs, {
      cwd: appRoot,
      stdio: 'inherit'
    })
    if (result.status !== 0) {
      throw new Error(
        `electron-rebuild failed for ${platform}-${arch} (exit ${result.status}). ` +
          `Cannot stage node-pty without a native binary.`
      )
    }
    // Re-copy build/Release after electron-rebuild populated it.
    const buildReleaseDir = join(srcRoot, 'build/Release')
    copyBuildRelease(buildReleaseDir, join(destRoot, 'build/Release'))
  }

  // Validate every staged .node binary matches the target platform.
  validateStagedBinaries(destRoot, platform)

  console.log(`[stage-native-deps] staged node-pty (${platform}-${arch}) -> ${destRoot}`)
  return destRoot
}

export function stageNodePty({ platform = process.platform, arch = process.arch, source = resolve(projectRoot, '../..'), out = join(source, 'apps/desktop/dist/node_modules') } = {}) {
  const appRoot = join(source, 'apps/desktop')
  const srcRoot = resolveNodePtyRoot(appRoot)
  const destRoot = join(out, 'node-pty')
  return stageNodePtyInto(srcRoot, destRoot, { platform, arch, appRoot })
}

// ─── get-windows (read_window_below tool) ────────────────────────────
//
// Staged like node-pty: external to the esbuild bundle, resolved at runtime
// from dist/node_modules (which asarUnpack ships unpacked via `dist/**`).
//
// The published package's lib/windows.js statically imports
// @mapbox/node-pre-gyp — and index.js statically imports lib/windows.js on
// EVERY platform — so shipping it verbatim would drag node-pre-gyp's whole
// dependency tree into the package. pre-gyp is only used to *locate* the
// prebuilt .node we stage ourselves, so the staged copy replaces
// lib/windows.js with a resolver that requires the staged binding directly
// (and fails soft to no-op stubs, matching upstream's missing-binding
// behavior).

const STAGED_WINDOWS_JS = `// Rewritten by stage-native-deps.mjs: resolves the staged prebuilt binding
// directly instead of through the pre-gyp locator (see stageGetWindowsInto).
import path from 'node:path';
import fs from 'node:fs';
import {fileURLToPath} from 'node:url';
import {createRequire} from 'node:module';

const getAddon = () => {
\tconst require = createRequire(import.meta.url);
\tconst bindingRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), 'binding');

\ttry {
\t\tfor (const dir of fs.readdirSync(bindingRoot)) {
\t\t\tconst bindingPath = path.join(bindingRoot, dir, 'node-get-windows.node');
\t\t\tif (fs.existsSync(bindingPath)) {
\t\t\t\treturn require(bindingPath);
\t\t\t}
\t\t}
\t} catch {}

\treturn {
\t\tgetActiveWindow() {},
\t\tgetOpenWindows() {},
\t};
};

export async function activeWindow() {
\treturn getAddon().getActiveWindow();
}

export function activeWindowSync() {
\treturn getAddon().getActiveWindow();
}

export function openWindows() {
\treturn getAddon().getOpenWindows();
}

export function openWindowsSync() {
\treturn getAddon().getOpenWindows();
}
`

function resolveGetWindowsRoot(appRoot = projectRoot) {
  // get-windows is an optionalDependency (its node-pre-gyp install script has
  // no Linux or Windows ARM64 prebuilt and its node-gyp fallback may fail, so
  // `npm ci` can skip it entirely on those targets). Return null when it is
  // absent; the caller decides whether that is fatal per platform and arch.
  try {
    // get-windows' exports map doesn't expose ./package.json; resolve the entry
    // (index.js sits at the package root) and take its directory.
    const entryPath = require.resolve('get-windows', {
      paths: [appRoot]
    })
    return dirname(entryPath)
  } catch {
    return null
  }
}

/**
 * Stage get-windows into `destRoot` for `platform`.
 *
 * Per-platform native payload: macOS ships the `main` Swift helper binary
 * (universal, present in every published tarball), Windows the node-pre-gyp
 * prebuilt under lib/binding (downloaded by the package's install script on
 * a Windows host — cross-platform packs already can't happen, see
 * stageNodePtyInto), Linux nothing (it shells out to xprop at runtime).
 */
const GET_WINDOWS_VERSION = '9.3.0'

export function stageGetWindowsInto(
  srcRoot,
  destRoot,
  { platform = process.platform, arch = process.arch, install } = {}
) {
  // The STAGED_WINDOWS_JS rewrite mirrors this exact version's export surface.
  // A version bump must fail the build here until the rewrite is re-verified —
  // otherwise it ships stale and fails soft as a generic "unavailable".
  const srcVersion = JSON.parse(readFileSync(join(srcRoot, 'package.json'), 'utf8')).version
  if (srcVersion !== GET_WINDOWS_VERSION) {
    throw new Error(
      `[stage-native-deps] get-windows is ${srcVersion} but the staged lib/windows.js ` +
        `rewrite was verified against ${GET_WINDOWS_VERSION}. Re-verify the rewrite ` +
        `(STAGED_WINDOWS_JS) against the new version, then update GET_WINDOWS_VERSION.`
    )
  }

  removeDirSync(destRoot)
  mkdirSync(destRoot, { recursive: true })

  copyFileSync(join(srcRoot, 'package.json'), join(destRoot, 'package.json'))
  copyFileSync(join(srcRoot, 'index.js'), join(destRoot, 'index.js'))

  // lib/*.js only — NOT copyGlobByExt, which recurses into lib/binding and
  // stages empty dirs for every prebuilt slot (including the darwin one the
  // tarball bundles on all platforms). Bindings are staged explicitly below.
  mkdirSync(join(destRoot, 'lib'), { recursive: true })
  for (const entry of readdirSync(join(srcRoot, 'lib'), { withFileTypes: true })) {
    if (entry.isFile() && entry.name.endsWith('.js')) {
      copyFileSync(join(srcRoot, 'lib', entry.name), join(destRoot, 'lib', entry.name))
    }
  }

  writeFileSync(join(destRoot, 'lib', 'windows.js'), STAGED_WINDOWS_JS)

  if (platform === 'darwin') {
    const helper = join(srcRoot, 'main')
    if (!existsSync(helper)) {
      // A half-extracted install (#90829) can keep the package but lose the
      // helper; the runtime already fails soft on an unstaged module, so lose
      // only window enumeration rather than the whole Desktop build.
      removeDirSync(destRoot)
      console.warn(
        '[stage-native-deps] get-windows is missing its macOS helper binary (main); ' +
          'not staged — read_window_below will be unavailable in this build'
      )
      return undefined
    }
    copyFileSync(helper, join(destRoot, 'main'))
    makeExecutable(join(destRoot, 'main'))
  }

  if (platform === 'win32') {
    // The published tarball bundles a darwin binding dir on EVERY platform
    // (its `files` includes lib/), so a Windows host's lib/binding holds both
    // that and the win32 dir node-pre-gyp downloaded. Stage only dirs naming
    // the target platform; the classify gate below still catches a dir that
    // claims win32 but holds a foreign binary.
    const bindingRoot = join(srcRoot, 'lib', 'binding')
    const scanBindingDirs = () =>
      existsSync(bindingRoot)
        ? readdirSync(bindingRoot).filter(
            (dir) =>
              dir.includes(`-${platform}-`) &&
              dir.endsWith(`-${arch}`) &&
              existsSync(join(bindingRoot, dir, 'node-get-windows.node'))
          )
        : []
    let bindingDirs = scanBindingDirs()
    let installAttempted = false
    if (bindingDirs.length === 0 && arch !== 'arm64' && typeof install === 'function') {
      // A plain `npm install` won't re-run an install script for a package
      // that is already on disk, so every checkout that installed while
      // get-windows was missing from allowScripts stays bricked even after
      // the allowlist is fixed. Invoke node-pre-gyp directly: npm treats this
      // optional dependency's failed lifecycle as non-fatal and can report a
      // successful rebuild without producing the Windows binding.
      console.log(
        '[stage-native-deps] get-windows has no win32 binding; running its native installer...'
      )
      installAttempted = true
      try {
        install()
      } catch (error) {
        console.warn(
          `[stage-native-deps] get-windows native installer failed: ${error instanceof Error ? error.message : String(error)}`
        )
      }
      bindingDirs = scanBindingDirs()
    }
    if (bindingDirs.length === 0) {
      // get-windows 9.3.0 publishes win32 prebuilds for ia32/x64 only, and a
      // half-extracted install (#90829) can leave even those without one. The
      // staged windows.js deliberately fails soft when binding/ is absent, so
      // preserve the desktop build and disable only window enumeration.
      const reason = installAttempted
        ? `native installer produced no win32-${arch} binding`
        : `has no win32-${arch} prebuilt binding`
      console.warn(
        `[stage-native-deps] get-windows ${reason}; ` +
          'staging the fail-soft JS surface without native window enumeration.'
      )
    }
    for (const dir of bindingDirs) {
      const dest = join(destRoot, 'lib', 'binding', dir)
      mkdirSync(dest, { recursive: true })
      const destFile = join(dest, 'node-get-windows.node')
      copyFileSync(join(bindingRoot, dir, 'node-get-windows.node'), destFile)
      const classified = classifyNativeBinary(destFile)
      if (classified !== platform) {
        throw new Error(
          `[stage-native-deps] get-windows binding ${dir}/node-get-windows.node: ` +
            `expected ${platform}, got ${classified ?? 'unknown'}. ` +
            'Refusing to stage a binary compiled for the wrong platform.'
        )
      }
    }
  }

  console.log(`[stage-native-deps] staged get-windows (${platform}) -> ${destRoot}`)
  return destRoot
}

export function installGetWindowsNativeBinding(
  srcRoot,
  { resolveInstaller, spawn = spawnSync } = {}
) {
  let installerPath
  try {
    const resolveNodePreGyp =
      resolveInstaller ??
      (() =>
        require.resolve('@mapbox/node-pre-gyp/bin/node-pre-gyp', {
          paths: [srcRoot]
        }))
    installerPath = resolveNodePreGyp()
  } catch (error) {
    const detail = error instanceof Error ? error.message : String(error)
    throw new Error(`[stage-native-deps] cannot resolve get-windows native installer: ${detail}`)
  }

  const result = spawn(process.execPath, [installerPath, 'install', '--fallback-to-build'], {
    cwd: srcRoot,
    stdio: 'inherit'
  })
  if (result.error) {
    throw new Error(
      `[stage-native-deps] get-windows native installer could not start: ${result.error.message}`
    )
  }
  if (result.status !== 0) {
    throw new Error(`[stage-native-deps] get-windows native installer exited with ${result.status}`)
  }
}

/**
 * A get-windows directory that exists but does not resolve as a package: an
 * `npm install` interrupted by a running Desktop/gateway holding files open
 * (TAR_ENTRY_ERROR on Windows) leaves the binding on disk without
 * package.json, and npm never revisits a directory that already exists, so the
 * tree stays broken across every later update. Walks the same
 * `node_modules` ancestors `require.resolve` does (the workspace root hoist or
 * the app-local copy).
 */
export function findHalfInstalledGetWindowsDir(startDir = projectRoot) {
  for (let dir = startDir; ; dir = dirname(dir)) {
    const candidate = join(dir, 'node_modules', 'get-windows')
    if (existsSync(candidate)) return candidate
    if (dirname(dir) === dir) return null
  }
}

/** The warning printed when get-windows cannot be staged. */
export function missingGetWindowsWarning({ platform, arch, halfInstalledDir }) {
  const lines = [
    `[stage-native-deps] get-windows not installed (optional dep skipped for ${platform}-${arch}); ` +
      'read_window_below will be unavailable in this build'
  ]
  if (halfInstalledDir) {
    lines.push(
      `[stage-native-deps] ${halfInstalledDir} exists but is not a loadable package — an ` +
        'interrupted npm install left it half-extracted (look for TAR_ENTRY_ERROR in the install log). ' +
        'To restore read_window_below: close every Hermes window and gateway so the extract is not ' +
        'interrupted again, then run `hermes desktop --force-build` — it removes the stale dir before npm.'
    )
  }
  return lines.join('\n')
}

export function stageGetWindows(
  {
    platform = process.platform,
    arch = process.arch,
    source = resolve(projectRoot, '../..'),
    out = join(source, 'apps/desktop/dist/node_modules'),
    resolveRoot = () => resolveGetWindowsRoot(join(source, 'apps/desktop')),
    findHalfInstalledDir = findHalfInstalledGetWindowsDir
  } = {}
) {
  const srcRoot = resolveRoot()
  const destRoot = join(out, 'get-windows')

  if (!srcRoot) {
    // npm may omit an optional dependency whose install script fails, or an in-place
    // update may fail to extract it due to file locks (#90829). The runtime import
    // already fails soft, so we disable only window enumeration instead of failing
    // the entire Desktop build (which would strand users on an old version).
    console.warn(
      missingGetWindowsWarning({ platform, arch, halfInstalledDir: findHalfInstalledDir() })
    )
    return undefined
  }

  // Only a win32 host can produce the win32 binding, so a cross-platform pack
  // has nothing to gain from the native installer.
  const install =
    platform === 'win32' && process.platform === 'win32'
      ? () => installGetWindowsNativeBinding(srcRoot)
      : undefined
  return stageGetWindowsInto(srcRoot, destRoot, { platform, arch, install })
}

/**
 * Whether ``out`` holds every native piece a build on THIS host can stage for the target.
 * Cross-target packs never build helpers and win32-arm64 has no get-windows prebuild, so neither
 * counts as missing: nothing a host fix could add.
 * @param {string} out @param {string} platform @param {string} arch @returns {boolean}
 */
export function nativeTreeComplete(out, platform, arch) {
  const native = platform === process.platform && (platform !== 'linux' || arch === process.arch)
  const required = ['get-windows/lib/windows.js']
  if (platform === 'darwin') required.push('get-windows/main')
  if (platform === 'win32' && arch !== 'arm64') required.push('get-windows/lib/binding')
  if (native && ['darwin', 'linux', 'win32'].includes(platform)) {
    required.push(hudModifierBinaryRelativePath(platform, arch))
  }
  return required.every(relative => existsSync(join(out, relative))) && nodePtyComplete(join(out, 'node-pty'), platform)
}

// node-pty loads pty.node from the first of these that has one (lib/utils.js loadNativeModule), and
// on macOS spawns through the spawn-helper beside it (lib/unixTerminal.js): a layout with the
// binding but not the helper loads fine and fails on the first terminal.
function nodePtyComplete(pty, platform) {
  const layout = ['build/Release', 'build/Debug', ...readdirSafe(join(pty, 'prebuilds')).map(name => `prebuilds/${name}`)]
    .find(dir => existsSync(join(pty, dir, 'pty.node')))
  return !!layout && (platform !== 'darwin' || existsSync(join(pty, layout, 'spawn-helper')))
}

function readdirSafe(dir) {
  try { return readdirSync(dir).sort() } catch { return [] }
}

/**
 * Preparation may rebuild/download native bindings; compilation only consumes them.
 * @param {{ source: string, out: string, platform?: string, arch?: string, nativeToolchain?: string }} inputs
 * @returns {Promise<{out: string}>}
 */
export async function prepareDesktopNativeDependencies({ source, out, platform = process.platform, arch = process.arch, nativeToolchain }) {
  ;({ source, out } = productOutput(source, out, ['node_modules', 'apps/desktop/node_modules', 'apps/desktop/src', 'apps/desktop/electron']))
  rmSync(`${out}.prepared.json`, { force: true })
  await withProduct(out, async product => {
    stageNodePty({ source, out: product, platform, arch })
    stageGetWindows({ source, out: product, platform, arch })
    buildCommandScreenshotMonitor({ source, distDir: product, platform })
    buildHudModifierMonitor({ source, distDir: product, platform, arch })
  }, { source })
  // Each component fails soft (no get-windows or its win32 binding, no X11 toolchain). Judge the
  // staged tree, not each builder's return shape: a tree missing a piece this host could produce
  // is degraded, and build.mjs restages it on every build, so fixing the host repairs the next update.
  recordNativeInputs({ source, out, platform, arch, nativeToolchain, degraded: !nativeTreeComplete(out, platform, arch) })
  return { out }
}

if (isMain(import.meta.url)) {
  const { values } = parseArgs({ options: {
    source: { type: 'string', default: resolve(projectRoot, '../..') },
    out: { type: 'string' }, platform: { type: 'string', default: process.platform }, arch: { type: 'string', default: process.arch },
    'native-toolchain': { type: 'string' },
  } })
  await prepareDesktopNativeDependencies({ ...values, nativeToolchain: values['native-toolchain'], out: values.out || join(values.source, 'apps/desktop/build/native-deps') })
}