@vantaloom/cli 0.6.0 → 0.13.6

package/src/lib/legacy-cleanup.mjs

@@ -0,0 +1,148 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import { binaryName, psQuote } from "./platform.mjs"
+
+// This module holds process-cleanup helpers that used to live in mesh.mjs
+// (removed in 0.13 along with the EasyTier mesh sidecar and the CLI's
+// install-time mesh-service registration). Neither function below is
+// mesh-specific to its live callers:
+//   - killTrayProcess predates the mesh sidecar entirely (kills a leftover
+//     vantaloom-tray.exe — a separate, already-removed feature).
+//   - removeMeshService is now a ONE-TIME migration primitive: the elevated
+//     uninstall of the legacy privileged `VantaloomMesh` service, invoked
+//     exactly once per install by uninstallLegacyMeshOnce below.
+
+export function killTrayProcess(prefix) {
+  if (process.platform === "win32") {
+    // Try PID file first (new tray versions write runtime/tray.pid).
+    const pidFile = path.join(prefix, "runtime", "tray.pid")
+    if (existsSync(pidFile)) {
+      const pid = readFileSync(pidFile, "utf8").trim()
+      if (pid) {
+        spawnSync("taskkill", ["/PID", pid, "/F"], { stdio: "ignore", windowsHide: true })
+        try { rmSync(pidFile, { force: true }) } catch {}
+      }
+    }
+    // Fallback: kill by image name if the binary is inside our prefix.
+    const result = spawnSync("tasklist", ["/FI", "IMAGENAME eq vantaloom-tray.exe", "/FO", "CSV", "/NH"], {
+      encoding: "utf8",
+      windowsHide: true,
+    })
+    if (result.stdout) {
+      for (const line of result.stdout.split("\n")) {
+        const match = line.match(/"vantaloom-tray\.exe","(\d+)"/)
+        if (match) {
+          spawnSync("taskkill", ["/PID", match[1], "/F"], { stdio: "ignore", windowsHide: true })
+        }
+      }
+    }
+    // Brief pause to let file handles release.
+    spawnSync("timeout", ["/t", "1", "/nobreak"], { stdio: "ignore", windowsHide: true })
+  } else {
+    // Unix: pkill by name (best-effort).
+    spawnSync("pkill", ["-f", "vantaloom-tray"], { stdio: "ignore", windowsHide: true })
+  }
+}
+
+// meshServiceRunningOrInstalled reports whether the Windows service exists at
+// all (running or stopped), so removeMeshService only prompts for elevation
+// when there is actually something to remove.
+function meshServiceRunningOrInstalled(binDir) {
+  const exe = path.join(binDir, "vantaloom-mesh.exe")
+  if (!existsSync(exe)) return false
+  const r = spawnSync(exe, ["status"], { encoding: "utf8", windowsHide: true })
+  if (r.error || typeof r.stdout !== "string") return false
+  return !r.stdout.toLowerCase().includes("not installed")
+}
+
+// removeMeshService elevates once to invoke the still-on-disk legacy
+// vantaloom-mesh binary's own `uninstall` verb, which self-removes its SCM
+// service (Windows) or LaunchDaemon (macOS). Linux never registered a service
+// (it only used setcap) so there's nothing to remove there.
+//
+// Returns true when there was nothing to do, or removal succeeded; false when
+// an elevated uninstall was attempted but declined/failed (never throws) — a
+// caller that wants "retry next time" semantics acts on the return value (see
+// uninstallLegacyMeshOnce).
+export function removeMeshService(prefix, options) {
+  const platform = process.platform
+  if (platform !== "win32" && platform !== "darwin") return true // Linux: nothing registered
+  const exe = path.join(prefix, "bin", binaryName("vantaloom-mesh"))
+  if (!existsSync(exe)) return true
+  if (options.skipMesh) return true
+
+  if (platform === "win32") {
+    if (!meshServiceRunningOrInstalled(path.join(prefix, "bin"))) return true
+    console.log("  mesh: removing legacy privileged P2P service (UAC prompt) ...")
+    const ps = `$ErrorActionPreference='Stop'; $p = Start-Process -FilePath ${psQuote(exe)} -ArgumentList 'uninstall' -Verb RunAs -Wait -PassThru; exit $p.ExitCode`
+    const r = spawnSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", ps], { stdio: "inherit", windowsHide: true })
+    if (r.error || r.status !== 0) {
+      console.warn(`  mesh: could not remove legacy service; run manually (as Administrator):  "${exe}" uninstall`)
+      return false
+    }
+    return true
+  }
+
+  console.log("  mesh: removing legacy privileged P2P service (sudo) ...")
+  const r = spawnSync("sudo", [exe, "uninstall"], { stdio: "inherit", windowsHide: true })
+  if (r.error || r.status !== 0) {
+    console.warn(`  mesh: could not remove legacy service; run manually:  sudo "${exe}" uninstall`)
+    return false
+  }
+  return true
+}
+
+// The bin/ files a pre-0.13 install's EasyTier mesh sidecar left behind
+// (Windows and Unix names both listed — deleting a name absent on this
+// platform is a harmless no-op via rmSync's force:true).
+const LEGACY_MESH_FILE_NAMES = [
+  "vantaloom-mesh.exe", "vantaloom-mesh",
+  "easytier-core.exe", "easytier-core",
+  "easytier-cli.exe", "easytier-cli",
+  "wintun.dll", "Packet.dll", "WinDivert64.sys",
+]
+
+// uninstallLegacyMeshOnce is the one-time migration that removes a pre-0.13
+// install's privileged `VantaloomMesh` service (Windows SCM service / macOS
+// LaunchDaemon; Linux never had one) plus its stale bin/ binaries. It exists
+// because applyPackage's bin/ copy only OVERLAYS files — it never deletes —
+// so a 0.13+ package (which no longer bundles vantaloom-mesh/easytier-core/
+// the support DLLs) would otherwise leave the old service + binaries in place
+// forever, and the orphaned service could even restart-loop easytier-core.
+//
+// Idempotent via a done-marker file (<prefix>/.mesh-removed): once cleanup has
+// run, every future install/update returns immediately. Never blocks
+// install/update — a failed or user-declined elevation prompt just logs a
+// hint and leaves the marker UNwritten, so the very next install/update
+// retries (design doc §10: "拒绝则留置、下次再试").
+export async function uninstallLegacyMeshOnce(prefix, options) {
+  const markerPath = path.join(prefix, ".mesh-removed")
+  if (existsSync(markerPath)) return
+
+  try {
+    const removed = removeMeshService(prefix, options)
+    if (!removed) {
+      console.warn("  mesh: legacy service removal was declined or failed; will retry on the next install/update")
+      return // leave the marker unwritten so this retries
+    }
+
+    // Best-effort: delete the stale mesh binaries so nothing can linger or
+    // restart-loop even after the service registration itself is gone.
+    const binDir = path.join(prefix, "bin")
+    for (const name of LEGACY_MESH_FILE_NAMES) {
+      try { rmSync(path.join(binDir, name), { force: true }) } catch {}
+    }
+
+    mkdirSync(prefix, { recursive: true })
+    writeFileSync(markerPath, `${new Date().toISOString()}\n`)
+  } catch (error) {
+    console.warn(`  mesh: legacy cleanup failed (${error.message}); will retry on the next install/update`)
+  }
+}

package/src/lib/lifecycle.mjs

@@ -0,0 +1,189 @@
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { spawnSync } from "node:child_process"
+import os from "node:os"
+import path from "node:path"
+import {
+  AUTOSTART_LABEL,
+  WINDOWS_RUN_KEY,
+  WINDOWS_RUN_VALUE,
+} from "./constants.mjs"
+import {
+  binaryName,
+  safeDirectory,
+  defaultPrefix,
+  run,
+  removeKnownPath,
+} from "./platform.mjs"
+import {
+  removeMeshService,
+  killTrayProcess,
+} from "./legacy-cleanup.mjs"
+
+// ── Runtime login-autostart (no elevation) ──
+// Start the local runtime (api/agent/web/tray) at login/boot using only
+// per-user mechanisms — no UAC/sudo. This is separate from the privileged mesh
+// service: the mesh sidecar autostarts via the OS service manager; this brings
+// up the unprivileged runtime that joins the mesh and serves the local API.
+
+export function enableRuntimeAutostart(prefix) {
+  try {
+    if (process.platform === "win32") {
+      // A .vbs launches the runtime with a hidden window (no console flash); the
+      // HKCU Run key runs it at login without elevation.
+      const launcher = path.join(prefix, "vantaloom.cmd")
+      const vbsPath = path.join(prefix, "autostart.vbs")
+      const vbs = `' Vantaloom runtime autostart (hidden)\r\nCreateObject("WScript.Shell").Run """${launcher}"" start", 0, False\r\n`
+      writeFileSync(vbsPath, vbs)
+      const result = spawnSync(
+        "powershell",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `Set-ItemProperty -Path '${WINDOWS_RUN_KEY}' -Name '${WINDOWS_RUN_VALUE}' -Value 'wscript.exe "${vbsPath}"'`,
+        ],
+        { stdio: "ignore", windowsHide: true }
+      )
+      if (result.error || result.status !== 0) {
+        console.warn("  autostart: could not register login entry (HKCU Run)")
+      } else {
+        console.log("  autostart: enabled (login Run key)")
+      }
+      return
+    }
+    if (process.platform === "darwin") {
+      const launcher = path.join(prefix, "vantaloom")
+      const dir = path.join(os.homedir(), "Library", "LaunchAgents")
+      mkdirSync(dir, { recursive: true })
+      const plistPath = path.join(dir, `${AUTOSTART_LABEL}.plist`)
+      // RunAtLoad only (no KeepAlive): `vantaloom start` spawns detached and exits.
+      const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${AUTOSTART_LABEL}</string>
+  <key>ProgramArguments</key><array><string>${launcher}</string><string>start</string></array>
+  <key>RunAtLoad</key><true/>
+</dict></plist>
+`
+      writeFileSync(plistPath, plist)
+      spawnSync("launchctl", ["unload", plistPath], { stdio: "ignore", windowsHide: true })
+      spawnSync("launchctl", ["load", "-w", plistPath], { stdio: "ignore", windowsHide: true })
+      console.log("  autostart: enabled (LaunchAgent)")
+      return
+    }
+    // Linux: user systemd unit + linger (no root).
+    const launcher = path.join(prefix, "vantaloom")
+    const dir = path.join(os.homedir(), ".config", "systemd", "user")
+    mkdirSync(dir, { recursive: true })
+    const unit = `[Unit]
+Description=Vantaloom local runtime
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=${launcher} start
+ExecStop=${launcher} stop
+
+[Install]
+WantedBy=default.target
+`
+    writeFileSync(path.join(dir, "vantaloom-runtime.service"), unit)
+    spawnSync("loginctl", ["enable-linger"], { stdio: "ignore", windowsHide: true })
+    spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore", windowsHide: true })
+    spawnSync("systemctl", ["--user", "enable", "vantaloom-runtime.service"], { stdio: "ignore", windowsHide: true })
+    console.log("  autostart: enabled (systemd user unit)")
+  } catch (error) {
+    console.warn(`  autostart: could not enable (${error.message})`)
+  }
+}
+
+export function disableRuntimeAutostart() {
+  try {
+    if (process.platform === "win32") {
+      // Remove the Run-key entry; the autostart.vbs lives in the install dir and
+      // is deleted with it.
+      spawnSync(
+        "powershell",
+        ["-NoProfile", "-NonInteractive", "-Command", `Remove-ItemProperty -Path '${WINDOWS_RUN_KEY}' -Name '${WINDOWS_RUN_VALUE}' -ErrorAction SilentlyContinue`],
+        { stdio: "ignore", windowsHide: true }
+      )
+      return
+    }
+    if (process.platform === "darwin") {
+      const plistPath = path.join(os.homedir(), "Library", "LaunchAgents", `${AUTOSTART_LABEL}.plist`)
+      if (existsSync(plistPath)) {
+        spawnSync("launchctl", ["unload", "-w", plistPath], { stdio: "ignore", windowsHide: true })
+        rmSync(plistPath, { force: true })
+      }
+      return
+    }
+    const unit = path.join(os.homedir(), ".config", "systemd", "user", "vantaloom-runtime.service")
+    if (existsSync(unit)) {
+      spawnSync("systemctl", ["--user", "disable", "vantaloom-runtime.service"], { stdio: "ignore", windowsHide: true })
+      rmSync(unit, { force: true })
+      spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore", windowsHide: true })
+    }
+  } catch (error) {
+    console.warn(`  autostart: could not disable (${error.message})`)
+  }
+}
+
+// uninstallRuntime tears down a local install: stop the runtime, remove any
+// legacy privileged mesh service (elevated), then delete the install directory.
+export async function uninstallRuntime(options) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  if (!existsSync(prefix)) {
+    console.log(`Vantaloom is not installed at ${prefix}`)
+    return
+  }
+  console.log(`Uninstalling Vantaloom from ${prefix} ...`)
+
+  // 1. Stop the runtime (api/agent/web/tray). Best-effort.
+  const ctlBin = path.join(prefix, "bin", binaryName("vantaloomctl"))
+  if (existsSync(ctlBin)) {
+    spawnSync(ctlBin, ["stop", "--prefix", prefix], { stdio: "inherit", windowsHide: true })
+  }
+  killTrayProcess(prefix)
+
+  // 2. Remove a legacy privileged mesh service if this install predates 0.13
+  // (releases the TUN adapter + file locks). A no-op on any install that
+  // never had one (see legacy-cleanup.mjs's removeMeshService).
+  removeMeshService(prefix, options)
+
+  // 2b. Remove the login-autostart entry (lives outside the install dir).
+  disableRuntimeAutostart()
+
+  // 3. Delete the install directory.
+  try {
+    const parent = path.dirname(prefix)
+    removeKnownPath(prefix, parent)
+    console.log(`removed ${prefix}`)
+  } catch (error) {
+    console.warn(`  could not remove ${prefix}: ${error.message}`)
+    console.warn("  some files may still be locked; re-run after closing Vantaloom processes.")
+  }
+
+  console.log("Vantaloom uninstalled.")
+  console.log("note: the install dir was left out of PATH edits; remove the bin/ entry from your shell profile if you added it.")
+}
+
+export function runCtl(command, options) {
+  const prefix = safeDirectory(options.prefix ?? defaultPrefix())
+  const ctl = path.join(prefix, "bin", binaryName("vantaloomctl"))
+  if (!existsSync(ctl)) {
+    throw new Error(`missing installed runtime at ${prefix}; run "vantaloom install" first`)
+  }
+
+  const args = [command, "--prefix", prefix]
+  if (options.component) {
+    args.push("--component", options.component)
+  }
+  run(ctl, args)
+}

package/src/lib/package.mjs

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync } from "node:fs"
+import { cp } from "node:fs/promises"
+import path from "node:path"
+import { platformId, removeKnownPath, runPnpm } from "./platform.mjs"
+import {
+  buildGo,
+  copyStaticWeb,
+  copyCliDirectory,
+  writeBuildManifest,
+  writeRuntimePackageMetadata,
+  runtimeConfigFromSource,
+  gitVersion,
+  npmPackageVersion,
+} from "./install.mjs"
+
+export async function buildRuntimePackage(sourceRoot, packageRoot, options) {
+  // Every build — npm release AND local/dev — stamps VERSION/manifest with the
+  // npm package version. There is exactly ONE product version (the npm semver);
+  // the git hash is recorded separately as manifest `commit` for diagnostics.
+  // History: pre-0.13.5 local builds stamped the git hash into VERSION, which
+  // split the version universe in two (the desktop shell read VERSION, the
+  // settings page read cli/package.json) and broke update prompts both ways.
+  const version = npmPackageVersion(sourceRoot)
+  const commit = gitVersion(sourceRoot)
+  const platform = options.target ?? platformId()
+  const buildBin = path.join(packageRoot, "bin")
+  const buildWeb = path.join(packageRoot, "web")
+
+  removeKnownPath(packageRoot, path.dirname(packageRoot))
+  mkdirSync(buildBin, { recursive: true })
+
+  buildGo(sourceRoot, buildBin, "vantaloom-api", platform)
+  buildGo(sourceRoot, buildBin, "vantaloom-agent", platform)
+  buildGo(sourceRoot, buildBin, "vantaloomctl", platform)
+  // Official "Vantaloom 浏览器" extension sidecar. Pure-Go (chromedp/CDP, no
+  // CGO), cross-compiles for every target. Ships dormant: it's only started by
+  // the api when the user installs+enables the browser extension (the heavy
+  // Chromium binary is downloaded on demand, NOT bundled here).
+  buildGo(sourceRoot, buildBin, "vantaloom-browser", platform)
+  // The Windows system-tray app (vantaloom-tray) was removed — it crash-looped
+  // on some Windows 11 builds and got respawned until OOM. No longer built.
+
+  // Bundle the Obscura headless browser (the official "Vantaloom 浏览器" engine,
+  // driven by the vantaloom-browser sidecar over CDP) for the target platform.
+  await copyObscura(sourceRoot, buildBin, platform)
+
+  if (options.buildWeb) {
+    runPnpm(["--filter", "vantaloom-app", "build"], { cwd: sourceRoot })
+  }
+
+  await copyStaticWeb(sourceRoot, buildWeb)
+  await copyCliDirectory(path.join(packageRoot, "cli"), sourceRoot, runtimeConfigFromSource(sourceRoot))
+  writeBuildManifest(packageRoot, version, platform, commit)
+
+  return { platform, version }
+}
+
+// copyObscura bundles the vendored Obscura headless-browser binaries
+// (obscura + obscura-worker, .exe on Windows) for the target platform into the
+// package bin/ dir. Obscura is the official "Vantaloom 浏览器" engine: a
+// CDP-compatible, V8-backed headless browser the vantaloom-browser sidecar
+// launches via `obscura serve` and drives over CDP. Warns + skips if the
+// vendor dir is absent (a cleaned vendor/ silently ships a runtime with no
+// browser engine).
+export async function copyObscura(sourceRoot, buildBin, platform) {
+  const vendorMap = {
+    "win32-x64": "windows-x86_64",
+    "darwin-arm64": "macos-aarch64",
+    "linux-x64": "linux-x86_64",
+  }
+  const vendorName = vendorMap[platform]
+  if (!vendorName) {
+    console.warn(`  warning: no Obscura mapping for ${platform}; browser engine disabled for this platform`)
+    return
+  }
+  const srcDir = path.join(sourceRoot, "vendor", "obscura", vendorName)
+  if (!existsSync(srcDir)) {
+    console.warn(`  warning: Obscura binaries not found at ${srcDir}; run vendor download first`)
+    return
+  }
+  const isWin = platform.startsWith("win32")
+  const exe = isWin ? ".exe" : ""
+  // Both binaries MUST ship together: obscura is the CLI/CDP server, obscura-worker
+  // is the V8 render worker it spawns. Without the worker, `obscura serve` cannot
+  // open pages.
+  const files = [`obscura${exe}`, `obscura-worker${exe}`]
+  let copied = 0
+  for (const f of files) {
+    const src = path.join(srcDir, f)
+    if (!existsSync(src)) {
+      console.warn(`  warning: Obscura file missing: ${f}`)
+      continue
+    }
+    await cp(src, path.join(buildBin, f), { force: true })
+    copied++
+  }
+  console.log(`  bundled Obscura ${vendorName} (${copied} files)`)
+}

package/src/lib/platform.mjs

@@ -0,0 +1,158 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs"
+import { writeFile } from "node:fs/promises"
+import { execFileSync } from "node:child_process"
+import os from "node:os"
+import path from "node:path"
+
+// binaryName returns the OS-appropriate binary file name.
+// NOTE: mirrored in Go at apps/desktop/internal/runtime/
+export function binaryName(name, targetPlatform) {
+  const isWindows = targetPlatform
+    ? targetPlatform.startsWith("win32")
+    : process.platform === "win32"
+  return isWindows ? `${name}.exe` : name
+}
+
+// platformId returns the current platform identifier string.
+// NOTE: mirrored in Go at apps/desktop/internal/runtime/
+export function platformId() {
+  return `${process.platform}-${process.arch}`
+}
+
+// runtimePackageName returns the npm package name for a given platform.
+// NOTE: mirrored in Go at apps/desktop/internal/runtime/
+export function runtimePackageName(platform) {
+  return `@vantaloom/runtime-${platform}`
+}
+
+export function parsePlatformId(platform) {
+  const parts = platform.split("-")
+  const cpu = parts.pop()
+  const runtimeOS = parts.join("-")
+  if (!runtimeOS || !cpu) {
+    throw new Error(`invalid platform id: ${platform}`)
+  }
+  return { os: runtimeOS, cpu }
+}
+
+// psQuote wraps a value as a PowerShell single-quoted string literal.
+// NOTE: mirrored in Go at apps/desktop/internal/runtime/
+export function psQuote(value) {
+  return "'" + String(value).replace(/'/g, "''") + "'"
+}
+
+// defaultPrefix returns the default install prefix for the current platform.
+// NOTE: mirrored in Go at apps/desktop/internal/runtime/
+export function defaultPrefix() {
+  if (process.env.VANTALOOM_HOME) {
+    return process.env.VANTALOOM_HOME
+  }
+  if (process.platform === "win32") {
+    // Prefer D: (the historical default) but fall back to C: when this machine
+    // has no D: drive. Keep in sync with the desktop shell's DefaultPrefix().
+    return existsSync("D:\\") ? "D:\\Vantaloom" : "C:\\Vantaloom"
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Applications", "Vantaloom")
+  }
+  return path.join(os.homedir(), ".local", "vantaloom")
+}
+
+export function displayCommand(prefix) {
+  if (process.platform === "win32") {
+    return path.join(prefix, "vantaloom.cmd")
+  }
+  return path.join(prefix, "vantaloom")
+}
+
+export function readJSONIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return {}
+  }
+  return JSON.parse(readFileSync(filePath, "utf8"))
+}
+
+export function packageBasename(name) {
+  return name.split("/").pop() ?? name
+}
+
+export function normalizeRegistry(value) {
+  return value.replace(/\/+$/, "")
+}
+
+export function toCamel(value) {
+  return value.replace(/-([a-z])/g, (_, char) => char.toUpperCase())
+}
+
+export function safeDirectory(value) {
+  const full = path.resolve(value)
+  const parsed = path.parse(full)
+  if (full === parsed.root) {
+    throw new Error(`refusing to operate on unsafe directory: ${value}`)
+  }
+  return full
+}
+
+export function removeKnownPath(target, expectedParent) {
+  if (!existsSync(target)) {
+    return
+  }
+  const full = path.resolve(target)
+  const parent = path.resolve(expectedParent)
+  const prefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`
+  if (!full.startsWith(prefix)) {
+    throw new Error(`refusing to remove path outside expected parent: ${full}`)
+  }
+  rmSync(full, { recursive: true, force: true })
+}
+
+export async function writeText(filePath, content) {
+  mkdirSync(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, content)
+}
+
+export function run(command, args, options = {}) {
+  try {
+    execFileSync(command, args, { stdio: "inherit", windowsHide: true, ...options })
+  } catch (error) {
+    if (error && typeof error.status === "number") {
+      throw new Error(`${command} exited with ${error.status}`)
+    }
+    throw error
+  }
+}
+
+export function runPnpm(args, options = {}) {
+  if (process.platform === "win32") {
+    run("cmd.exe", ["/d", "/s", "/c", "pnpm", ...args], options)
+    return
+  }
+  run("pnpm", args, options)
+}
+
+// runNpm invokes npm cross-platform. On Windows npm is `npm.cmd`, which
+// execFileSync (used by run) can't resolve directly (ENOENT) — so wrap via
+// cmd.exe, mirroring runPnpm.
+export function runNpm(args, options = {}) {
+  if (process.platform === "win32") {
+    run("cmd.exe", ["/d", "/s", "/c", "npm", ...args], options)
+    return
+  }
+  run("npm", args, options)
+}
+
+export function platformToGoEnv(platform) {
+  const { os: runtimeOS, cpu } = parsePlatformId(platform)
+  const goosMap = { win32: "windows", linux: "linux", darwin: "darwin" }
+  const goarchMap = { x64: "amd64", arm64: "arm64" }
+  return {
+    GOOS: goosMap[runtimeOS] ?? runtimeOS,
+    GOARCH: goarchMap[cpu] ?? cpu,
+    CGO_ENABLED: "0",
+  }
+}