local-operator-ui 0.19.6 → 0.20.0

package/bin/ensure-electron.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+/**
+ * Make sure the Electron runtime the BUILD shells out to is on disk.
+ *
+ * WHY A BUILD NEEDS THE BINARY AT ALL: electron-vite's bytecode step runs the
+ * Electron binary from `node_modules/electron/dist` to produce `.jsc` for the
+ * exact V8 it will load under — so the build needs a real dist/, and it does
+ * not go through `require("electron")`, which is the call that would fetch the
+ * runtime on demand. Missing dist/ therefore fails the build with
+ * `[vite:bytecode] spawn … ENOENT` rather than downloading anything.
+ *
+ * WHY THIS EXISTS BESIDE bin/postinstall.js: since Electron 42 the `electron`
+ * package has no postinstall, so `node_modules/electron/dist` is absent on a
+ * fresh install until something fetches it. bin/postinstall.js fetches it on
+ * every platform, which covers `pnpm install`; this script covers the trees
+ * that hook cannot reach — `pnpm install --ignore-scripts`, and the common
+ * local case of a dist/ deleted or replaced by hand — by running from the
+ * `prebuild` hook, before anything reads it. Both call the same
+ * ensureElectronDist() so there is one implementation of "what counts as
+ * present" and one fetch.
+ *
+ * It is IDEMPOTENT and cache-backed: with dist/ present this exits in well
+ * under a second without touching the network.
+ *
+ * It FAILS the build when the runtime cannot be fetched, unlike the postinstall
+ * (which must never fail an install). There is no way for the build to succeed
+ * without it, and a named failure with the one command that fixes it beats the
+ * ENOENT this exists to prevent.
+ */
+
+const path = require("node:path");
+const { ensureElectronDist } = require("./linux-sandbox.js");
+
+const packageRoot = path.join(__dirname, "..");
+
+if (!ensureElectronDist(packageRoot, { quiet: false })) {
+	console.error(
+		"local-operator-ui: the Electron runtime is missing from node_modules and could not be fetched.",
+	);
+	console.error(
+		"The build needs it: electron-vite compiles the main bundle to V8 bytecode for that exact runtime (the preload ships as plain JS — bytecode cannot load in an Electron 44 renderer, see electron.vite.config.js).",
+	);
+	console.error("Fetch it explicitly, then build again:");
+	console.error("  npx install-electron --no && pnpm build");
+	process.exit(1);
+}

package/bin/linux-sandbox.js

@@ -411,16 +411,31 @@ const exitCodeFor = (code, signal) => {
  * That is the failure mode this file's whole design is meant to avoid, so it is
  * recorded here rather than quietly corrected.
  *
+ * That ordering argument is history since Electron 42, and the function is
+ * MORE load-bearing for it, not less: the `electron` package no longer runs a
+ * postinstall at all, so nothing downloads dist/ during an install any more,
+ * while `electron-vite`'s bytecode step spawns the binary straight from
+ * `dist/` (never through `require("electron")`, which is the call that would
+ * fetch it on demand). See bin/postinstall.js and bin/ensure-electron.js --
+ * between them they are the only things that put the runtime on disk.
+ *
  * The fix is to drive Electron's own installer first. It is idempotent and
  * cache-backed: with a valid dist/ already present it returns in ~0.08s without
  * touching the network, and npm's later invocation of the same script is then
  * the no-op instead. It also preserves a setuid bit we have already set
  * (verified), so the ordering between the two runs does not matter.
  *
- * Returns true when a helper is present afterwards. Every failure degrades to
- * false: the install must still succeed (see bin/postinstall.js).
+ * Returns true when the Electron runtime itself is present afterwards (keyed on
+ * `dist/version`, the marker Electron's own installer uses). Every failure
+ * degrades to false: the install must still succeed (see bin/postinstall.js).
+ *
+ * `quiet` silences the installer, which is what the install path wants -- the
+ * download prints a progress bar that would otherwise appear twice in one
+ * `npm install`, once from us and once from npm's own run of the same script.
+ * The build path passes `quiet: false`, because there the download IS the
+ * visible work and a silent multi-minute wait reads as a hang.
  */
-const ensureElectronDist = (packageRoot) => {
+const ensureElectronDist = (packageRoot, { quiet = true } = {}) => {
 	const installer = path.join(
 		packageRoot,
 		"node_modules",
@@ -431,29 +446,23 @@ const ensureElectronDist = (packageRoot) => {
 		return false;
 	}
 	const distDir = path.join(packageRoot, "node_modules", "electron", "dist");
-	// Key the fast path on the SAME marker electron's own isInstalled() uses
-	// (dist/version) as well as the helper. Keying on chrome-sandbox alone let a
-	// partially-extracted dist/ that happens to contain the helper report a
-	// healthy install, so we would skip the installer that would have repaired it.
-	if (
-		fs.existsSync(path.join(distDir, "version")) &&
-		fs.existsSync(path.join(distDir, "chrome-sandbox"))
-	) {
+	// The fast path keys on `dist/version` ALONE. It used to also require
+	// `dist/chrome-sandbox`, which exists only on Linux, so on macOS and Windows
+	// every install re-ran the installer (idempotent, but a 10-minute-bounded
+	// spawn per install) and -- now that this function is also what fetches the
+	// runtime off Linux -- every build too. `dist/version` is the complete-extraction
+	// marker because electron's own isInstalled() reads the same file.
+	if (fs.existsSync(path.join(distDir, "version"))) {
 		return true;
 	}
-	// Inherit nothing on stdout: the download prints a progress bar that would
-	// otherwise appear twice in the install log, once here and once from npm's
-	// own run of the same script.
 	const result = spawnSync(process.execPath, [installer], {
 		cwd: path.dirname(installer),
-		stdio: "ignore",
+		stdio: quiet ? "ignore" : "inherit",
 		// A hung download must not hang the install. Ten minutes is generous for a
 		// ~100MB fetch on a slow link and still bounded.
 		timeout: 10 * 60 * 1000,
 	});
-	return (
-		result.status === 0 && fs.existsSync(path.join(distDir, "chrome-sandbox"))
-	);
+	return result.status === 0 && fs.existsSync(path.join(distDir, "version"));
 };
 
 module.exports = {

package/bin/postinstall.js

@@ -1,22 +1,36 @@
 #!/usr/bin/env node
 
 /**
- * Restore the setuid bit on Electron's chrome-sandbox helper after install.
+ * Two install-time duties, one script, because both are "the install did not
+ * leave this tree runnable" problems and npm's lifecycle gives us one hook:
  *
- * npm strips setuid bits from package contents by design, so the helper lands
- * root:root 0755 and Chromium aborts for a non-root user (issue #91). We fix it
- * here because `sudo npm install -g` — the ordinary way to install a global CLI
- * — runs this script as root, which is the one moment in the lifecycle where we
- * hold the privilege the fix needs.
+ * 1. Fetch the Electron runtime. Since Electron 42 the `electron` package has
+ *    no postinstall that downloads the binary, and `electron-vite`'s bytecode
+ *    step spawns the binary straight from `dist/` rather than through
+ *    `require("electron")` (the one call that would fetch it on demand). So
+ *    without this, a fresh clone or a cold CI runner fails its first
+ *    `pnpm build` with `[vite:bytecode] spawn ... ENOENT` -- on macOS and
+ *    Windows too, not only on Linux. bin/ensure-electron.js calls the same
+ *    helper from the build path, for trees installed with --ignore-scripts or
+ *    with dist/ removed afterwards.
+ *
+ * 2. Restore the setuid bit on Electron's chrome-sandbox helper. npm strips
+ *    setuid bits from package contents by design, so the helper lands
+ *    root:root 0755 and Chromium aborts for a non-root user (issue #91). We fix
+ *    it here because `sudo npm install -g` -- the ordinary way to install a
+ *    global CLI -- runs this script as root, which is the one moment in the
+ *    lifecycle where we hold the privilege the fix needs. Linux only: the
+ *    helper does not exist anywhere else.
  *
  * THIS SCRIPT MUST NEVER FAIL THE INSTALL. An unprivileged `npm install -g`
  * (prefix in $HOME), a container without CAP_CHOWN, macOS and Windows where the
- * helper does not exist, and an install where the optional Electron download was
- * skipped are all normal situations in which the repair cannot happen. Leaving
- * the user with no package at all would be a worse defect than the one being
- * fixed, so every failure path exits 0. Where the repair does not happen, the
- * launcher's post-mortem guidance (bin/local-operator-ui.js) covers it with the
- * exact commands.
+ * helper does not exist, and an install where the Electron download failed or
+ * was skipped are all normal situations. Leaving the user with no package at
+ * all would be a worse defect than the one being fixed, so every failure path
+ * exits 0. Where the runtime could not be fetched, `bin/ensure-electron.js`
+ * fails the build with the exact command instead, and where the repair does not
+ * happen the launcher's post-mortem guidance (bin/local-operator-ui.js) covers
+ * it.
  *
  * It is quiet on success for the same reason npm scripts generally are: the
  * common case is a working install and noise there trains people to ignore it.
@@ -24,22 +38,6 @@
 
 const process = require("node:process");
 
-// Silence is the contract on non-Linux: the helper is a Linux-only artifact, so
-// there is nothing to repair and nothing worth printing on a Mac.
-//
-// LOCAL_OPERATOR_UI_FORCE_POSTINSTALL exists so the test suite can reach the
-// repair path on a macOS developer machine and on CI's ubuntu runner alike.
-// Without it the only assertion this script's test could make on darwin was
-// "exit 0", which it satisfies by returning here before doing anything -- a
-// vacuous test that passed while the whole body was mutated away. It is read
-// only, never written by us, and namespaced so it cannot be set by accident.
-if (
-	process.platform !== "linux" &&
-	process.env.LOCAL_OPERATOR_UI_FORCE_POSTINSTALL !== "1"
-) {
-	process.exit(0);
-}
-
 const main = () => {
 	const path = require("node:path");
 	const {
@@ -47,12 +45,36 @@ const main = () => {
 		repairSandboxHelper,
 	} = require("./linux-sandbox.js");
 
-	// Do NOT resolve the helper through require("electron"). npm runs this script
-	// BEFORE electron's own postinstall downloads dist/, so at this point that
-	// call throws and the helper does not exist yet. ensureElectronDist() drives
-	// electron's installer first; see the long note on it for the measurements.
+	// Fetch BEFORE the platform guard, because the build needs the runtime on
+	// every platform and this is the only hook that runs on a plain
+	// `pnpm install`. The installer is silent here on purpose: the download
+	// prints a progress bar that would otherwise appear twice in one install,
+	// once from us and once from npm's own run of the same script.
 	const packageRoot = path.join(__dirname, "..");
-	if (!ensureElectronDist(packageRoot)) {
+	const distReady = ensureElectronDist(packageRoot);
+
+	// Silence is the contract on non-Linux: the helper is a Linux-only artifact,
+	// so with the runtime in place there is nothing left to repair and nothing
+	// worth printing on a Mac.
+	//
+	// LOCAL_OPERATOR_UI_FORCE_POSTINSTALL exists so the test suite can reach the
+	// repair path on a macOS developer machine and on CI's ubuntu runner alike.
+	// Without it the only assertion this script's test could make on darwin was
+	// "exit 0", which it satisfies by returning here before doing anything -- a
+	// vacuous test that passed while the whole body was mutated away. It is read
+	// only, never written by us, and namespaced so it cannot be set by accident.
+	if (
+		process.platform !== "linux" &&
+		process.env.LOCAL_OPERATOR_UI_FORCE_POSTINSTALL !== "1"
+	) {
+		return;
+	}
+
+	// Do NOT resolve the helper through require("electron"): that call fetches
+	// the runtime on demand when it is missing, which inside an install is a
+	// synchronous download in the wrong place. ensureElectronDist() above is the
+	// one that drives electron's installer, on purpose.
+	if (!distReady) {
 		// No Electron to repair: optional install skipped, or the download failed.
 		// The launcher reports that case with its own guidance.
 		return;