fix: prevent infinite app spawn loop in production builds (#28)

jcanizalez · web-flow · commit 552868053407 · 2026-03-14T13:19:07.000-06:00
* fix: prevent infinite app spawn loop in production builds

The server launcher used `spawn(process.execPath, ...)` to start the
standalone server process in production. Since process.execPath is the
Electron binary, this launched another full Electron app instance instead
of a Node.js process, which in turn tried to launch another server,
creating an infinite spawn loop.

Fix: use Electron's `utilityProcess.fork()` for production builds, which
runs the server script as a proper Node.js child process without creating
another Electron window. Dev mode continues using `npx tsx` via
child_process.spawn.

Also adds `app.requestSingleInstanceLock()` as a safety net to prevent
multiple app instances from ever running simultaneously.

* fix: resolve native module loading in utilityProcess

The utilityProcess can't access modules inside the asar archive and
doesn't have Electron's ASAR require() patching. This caused three
failures in the production build:

1. Server entry detected as index.js but tsup outputs index.cjs
   (package.json has "type": "module") — add .cjs to isDirectRun check

2. JS dependencies (fastify, pino, etc.) externalized by default —
   add tsup config with noExternal regex to bundle all JS deps while
   keeping only native modules (node-pty, better-sqlite3) external

3. Native module resolution broken because Electron's utility_init wraps
   Module._resolveFilename — patch Module._load instead via tsup banner
   to intercept require() calls and redirect native modules to their
   absolute paths in app.asar.unpacked/node_modules/

4. better-sqlite3 uses require('bindings') which is trapped in the asar —
   shim the bindings package in the Module._load patch to resolve
   .node addons directly from known unpacked paths

* fix: address PR review feedback

- Update comment to say index.cjs instead of index.js
- Simplify exit listener — both ChildProcess and UtilityProcess
  support .on('exit'), no branching needed
- Handle bindings object form { bindings: 'name.node' }
- Log errors in native module patch instead of silently swallowing
diff --git a/packages/server/package.json b/packages/server/package.json
@@ -13,7 +13,7 @@
     "./git-utils": "./src/git-utils.ts"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs --target node20 --external node-pty --external better-sqlite3 --clean",
+    "build": "tsup --config tsup.config.ts",
     "dev": "tsx src/index.ts"
   },
   "dependencies": {
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
@@ -104,7 +104,10 @@ export async function startServer(
 }
 
 // Run directly
-const isDirectRun = process.argv[1]?.endsWith('index.ts') || process.argv[1]?.endsWith('index.js')
+const isDirectRun =
+  process.argv[1]?.endsWith('index.ts') ||
+  process.argv[1]?.endsWith('index.js') ||
+  process.argv[1]?.endsWith('index.cjs')
 if (isDirectRun) {
   const portArg = process.argv.find((a) => a.startsWith('--port='))
   const port = portArg ? parseInt(portArg.split('=')[1], 10) : 0
diff --git a/packages/server/tsup.config.ts b/packages/server/tsup.config.ts
@@ -0,0 +1,77 @@
+import { defineConfig } from 'tsup'
+
+const NATIVE_MODULE_PATCH = `
+// Patch module resolution for Electron's utilityProcess.
+//
+// utilityProcess doesn't have the main process's ASAR require() patching,
+// so bare require('node-pty') fails. Electron wraps Module._resolveFilename
+// with its own n._resolveFilename, making Module-level patches unreliable.
+//
+// Solution: intercept Module._load (the function that actually calls require)
+// before Electron can interfere, and redirect native module names to their
+// absolute paths in app.asar.unpacked/node_modules/.
+//
+// The parent process passes VIBEGRID_NATIVE_MODULES_PATH as an env var
+// pointing to the unpacked node_modules directory.
+//
+// Additionally, better-sqlite3 uses require('bindings') to locate its
+// .node addon. Since 'bindings' is a JS package trapped inside the asar
+// archive (inaccessible to utilityProcess), we intercept it and return a
+// shim that resolves directly to the known .node file path.
+//
+// @see https://electron-vite.org/guide/assets
+// @see https://github.com/electron/electron/issues/8727
+;(function() {
+  var nativePath = process.env.VIBEGRID_NATIVE_MODULES_PATH;
+  if (!nativePath) return;
+  try {
+    var Module = require('module');
+    var path = require('path');
+    var nativeModules = { 'node-pty': true, 'better-sqlite3': true };
+
+    // Map of known native addon .node files for the bindings shim
+    var knownAddons = {
+      'better_sqlite3.node': path.join(nativePath, 'better-sqlite3', 'build', 'Release', 'better_sqlite3.node')
+    };
+
+    var origLoad = Module._load;
+    Module._load = function(request, parent, isMain) {
+      // Redirect native module requires to unpacked path
+      if (nativeModules[request]) {
+        return origLoad.call(this, path.join(nativePath, request), parent, isMain);
+      }
+      // Shim the 'bindings' package — return a function that resolves
+      // addon names from our known unpacked paths
+      if (request === 'bindings') {
+        return function(opts) {
+          // bindings accepts a string or { bindings: 'name.node', ... }
+          var name = typeof opts === 'object' ? opts.bindings : opts;
+          if (knownAddons[name]) {
+            return origLoad.call(Module, knownAddons[name], parent, false);
+          }
+          // Fallback: try original bindings module
+          return origLoad.call(Module, 'bindings', parent, isMain)(opts);
+        };
+      }
+      return origLoad.call(this, request, parent, isMain);
+    };
+  } catch(e) { console.error('[native-module-patch] failed:', e); }
+})();
+`
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs'],
+  target: 'node20',
+  clean: true,
+  banner: {
+    js: NATIVE_MODULE_PATCH
+  },
+  // Bundle ALL JS dependencies so the server runs standalone in Electron's
+  // utilityProcess (which cannot access modules inside the asar archive).
+  //
+  // Native modules (node-pty, better-sqlite3) remain external because they
+  // contain compiled .node binaries loaded at runtime from disk.
+  noExternal: [/^(?!node-pty$|better-sqlite3$)/],
+  external: ['node-pty', 'better-sqlite3']
+})
diff --git a/src/main/index.ts b/src/main/index.ts
@@ -10,6 +10,14 @@ import log from './logger'
 
 let isQuitting = false
 
+// Ensure only one instance of the app runs at a time.
+// Without this, spawning bugs (e.g. using process.execPath to launch the server)
+// could cause an infinite cascade of Electron app instances.
+const gotTheLock = app.requestSingleInstanceLock()
+if (!gotTheLock) {
+  app.quit()
+}
+
 // Prevent EPIPE and other uncaught errors from crashing the main process
 process.on('uncaughtException', (err) => {
   if ((err as NodeJS.ErrnoException).code === 'EPIPE') return
@@ -244,6 +252,15 @@ function updatePermissionShortcuts(): void {
   })
 }
 
+// When a second instance is launched, focus the existing window instead
+app.on('second-instance', () => {
+  if (mainWindow) {
+    if (mainWindow.isMinimized()) mainWindow.restore()
+    mainWindow.show()
+    mainWindow.focus()
+  }
+})
+
 app.whenReady().then(async () => {
   let bridge: ServerBridge
   try {
diff --git a/src/main/server/server-launcher.ts b/src/main/server/server-launcher.ts
@@ -1,61 +1,102 @@
 import { spawn, type ChildProcess } from 'node:child_process'
 import path from 'node:path'
 import { createInterface } from 'node:readline'
-import { app } from 'electron'
+import { app, utilityProcess, type UtilityProcess } from 'electron'
 import log from '../logger'
 import { ServerBridge } from './server-bridge'
 
-let serverProcess: ChildProcess | null = null
+let serverProcess: ChildProcess | UtilityProcess | null = null
 let bridge: ServerBridge | null = null
 
 /**
  * Spawns the @vibegrid/server process and returns a connected ServerBridge.
  *
  * The server writes `{"port": N}` to stdout on startup.
  * We read the port, then connect a WebSocket bridge.
+ *
+ * In dev mode: uses `npx tsx` via child_process.spawn (TypeScript execution).
+ * In production: uses Electron's utilityProcess.fork() to run the bundled
+ * server script as a Node.js process WITHOUT launching another Electron window.
+ *
+ * NOTE: Previously this used `spawn(process.execPath, ...)` in production,
+ * which caused an infinite app spawn loop because process.execPath is the
+ * Electron binary — spawning it launches another full Electron app instance.
  */
 export async function launchServer(): Promise<ServerBridge> {
   const serverEntryPoint = resolveServerEntry()
   log.info(`[launcher] starting server: ${serverEntryPoint}`)
 
   const dataDir = app.getPath('userData')
-
   const isDev = !!process.env.ELECTRON_RENDERER_URL
-  const command = isDev ? 'npx' : process.execPath
-  const args = isDev
-    ? ['tsx', serverEntryPoint, `--data-dir=${dataDir}`]
-    : [serverEntryPoint, `--data-dir=${dataDir}`]
-
-  serverProcess = spawn(command, args, {
-    stdio: ['pipe', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      NODE_ENV: process.env.NODE_ENV ?? (isDev ? 'development' : 'production'),
-      // In production, native modules live in the asar-unpacked node_modules
-      ...(isDev
-        ? {}
-        : {
-            NODE_PATH: [
-              path.join(app.getAppPath(), 'node_modules'),
-              path.join(app.getAppPath() + '.unpacked', 'node_modules')
-            ].join(path.delimiter)
-          })
-    },
-    cwd: isDev ? path.join(__dirname, '../..') : undefined
-  })
 
-  serverProcess.stdin?.end()
+  let port: number
+
+  if (isDev) {
+    // Dev mode: use npx tsx to run TypeScript directly
+    const child = spawn('npx', ['tsx', serverEntryPoint, `--data-dir=${dataDir}`], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        NODE_ENV: process.env.NODE_ENV ?? 'development'
+      },
+      cwd: path.join(__dirname, '../..')
+    })
+
+    child.stdin?.end()
+
+    // Forward server stderr to our log
+    if (child.stderr) {
+      const errLines = createInterface({ input: child.stderr })
+      errLines.on('line', (line) => {
+        log.info(`[server] ${line}`)
+      })
+    }
+
+    port = await readServerPort(child)
+
+    child.on('exit', (code, signal) => {
+      log.warn(`[launcher] server exited (code=${code}, signal=${signal})`)
+      serverProcess = null
+    })
+
+    serverProcess = child
+  } else {
+    // Production: use Electron's utilityProcess.fork() to run the bundled
+    // server as a proper Node.js child process (NOT another Electron instance)
+    //
+    // The main process has Electron's ASAR patching so it can resolve native
+    // modules. The utilityProcess does NOT, so we resolve the absolute paths
+    // here and pass them via environment variables for the server banner to use.
+    const asarUnpacked = path.join(app.getAppPath() + '.unpacked', 'node_modules')
+
+    const child = utilityProcess.fork(serverEntryPoint, [`--data-dir=${dataDir}`], {
+      stdio: 'pipe',
+      env: {
+        ...process.env,
+        NODE_ENV: 'production',
+        VIBEGRID_NATIVE_MODULES_PATH: asarUnpacked,
+        NODE_PATH: [path.join(app.getAppPath(), 'node_modules'), asarUnpacked].join(path.delimiter)
+      }
+    })
+
+    // Forward server stderr to our log
+    if (child.stderr) {
+      const errLines = createInterface({ input: child.stderr })
+      errLines.on('line', (line) => {
+        log.info(`[server] ${line}`)
+      })
+    }
+
+    port = await readServerPort(child)
 
-  // Forward server stderr to our log
-  if (serverProcess.stderr) {
-    const errLines = createInterface({ input: serverProcess.stderr })
-    errLines.on('line', (line) => {
-      log.info(`[server] ${line}`)
+    child.on('exit', (code) => {
+      log.warn(`[launcher] server exited (code=${code})`)
+      serverProcess = null
     })
+
+    serverProcess = child
   }
 
-  // Read port from server stdout
-  const port = await readServerPort(serverProcess)
   log.info(`[launcher] server started on port ${port}`)
 
   // Connect bridge
@@ -71,12 +112,6 @@ export async function launchServer(): Promise<ServerBridge> {
     })
   })
 
-  // Handle server crash
-  serverProcess.on('exit', (code, signal) => {
-    log.warn(`[launcher] server exited (code=${code}, signal=${signal})`)
-    serverProcess = null
-  })
-
   return bridge
 }
 
@@ -95,29 +130,37 @@ export async function stopServer(): Promise<void> {
     bridge = null
   }
 
-  if (serverProcess && !serverProcess.killed) {
-    serverProcess.kill('SIGTERM')
-    // Force kill after 3 seconds
-    setTimeout(() => {
-      if (serverProcess && !serverProcess.killed) {
-        serverProcess.kill('SIGKILL')
+  if (serverProcess) {
+    if ('killed' in serverProcess) {
+      // ChildProcess (dev mode)
+      const child = serverProcess as ChildProcess
+      if (!child.killed) {
+        child.kill('SIGTERM')
+        setTimeout(() => {
+          if (child && !child.killed) {
+            child.kill('SIGKILL')
+          }
+        }, 3000)
       }
-    }, 3000)
+    } else {
+      // UtilityProcess (production) — only has kill()
+      serverProcess.kill()
+    }
     serverProcess = null
   }
 }
 
 function resolveServerEntry(): string {
   // In dev: packages/server/src/index.ts (run via tsx)
-  // In production: resources/server/index.js (bundled)
+  // In production: resources/server/index.cjs (bundled)
   if (process.env.ELECTRON_RENDERER_URL) {
     // Dev mode — use tsx to run TypeScript directly
     return path.join(__dirname, '../../packages/server/src/index.ts')
   }
-  return path.join(process.resourcesPath, 'server', 'index.js')
+  return path.join(process.resourcesPath, 'server', 'index.cjs')
 }
 
-function readServerPort(child: ChildProcess): Promise<number> {
+function readServerPort(child: ChildProcess | UtilityProcess): Promise<number> {
   return new Promise((resolve, reject) => {
     if (!child.stdout) {
       reject(new Error('No stdout on server process'))
@@ -142,9 +185,11 @@ function readServerPort(child: ChildProcess): Promise<number> {
       }
     })
 
-    child.on('exit', (code) => {
+    // Both ChildProcess and UtilityProcess support .on('exit', cb)
+    const onExit = (code: number | null) => {
       clearTimeout(timeout)
       reject(new Error(`Server exited before reporting port (code=${code})`))
-    })
+    }
+    ;(child as UtilityProcess).on('exit', onExit)
   })
 }
