@agentuity/cli 2.0.10 → 2.0.12

package/src/cmd/dev/index.ts

@@ -45,27 +45,38 @@ interface ServerLike {
 /**
  * Kill any lingering gravity processes from previous dev sessions.
  * This is a defensive measure to clean up orphaned processes.
+ *
+ * When a projectId is provided, only kills gravity processes for that specific
+ * project. Otherwise falls back to killing all gravity processes (used during
+ * startup before project info is available).
  */
-async function killLingeringGravityProcesses(logger: {
-	debug: (msg: string, ...args: unknown[]) => void;
-}): Promise<void> {
+async function killLingeringGravityProcesses(
+	logger: {
+		debug: (msg: string, ...args: unknown[]) => void;
+	},
+	projectId?: string
+): Promise<void> {
 	// Only attempt on Unix-like systems (macOS, Linux)
 	if (process.platform === 'win32') {
 		return;
 	}
 
 	try {
-		// Use pkill to kill gravity processes owned by current user
-		// The -f flag matches against full command line
-		// We specifically match the gravity binary name to avoid killing unrelated processes
-		const result = Bun.spawnSync(['pkill', '-f', 'gravity.*--endpoint-id'], {
+		// Scope the pkill pattern to the specific project when possible,
+		// avoiding killing gravity processes from other dev sessions.
+		const pattern = projectId ? `gravity.*--project-id.*${projectId}` : 'gravity.*--endpoint-id';
+
+		const result = Bun.spawnSync(['pkill', '-f', pattern], {
 			stdout: 'ignore',
 			stderr: 'ignore',
 		});
 
 		// Exit code 0 = processes killed, 1 = no matching processes, other = error
 		if (result.exitCode === 0) {
-			logger.debug('Killed lingering gravity processes from previous session');
+			logger.debug(
+				'Killed lingering gravity processes%s from previous session',
+				projectId ? ` (project ${projectId})` : ''
+			);
 			// Brief pause to let processes fully terminate
 			await new Promise((resolve) => setTimeout(resolve, 100));
 		} else if (result.exitCode === 1) {
@@ -78,19 +89,46 @@ async function killLingeringGravityProcesses(logger: {
 
 /**
  * Kill the Bun backend subprocess if one is running.
+ *
+ * @param forceKill - If true, sends SIGKILL instead of SIGTERM. Used in
+ *   process.on('exit') handlers where there's no time for graceful shutdown.
+ *   Also kills the entire process tree to prevent orphaned child processes.
  */
-function killBunSubprocess(logger: { debug: (msg: string, ...args: unknown[]) => void }): void {
+function killBunSubprocess(
+	logger: { debug: (msg: string, ...args: unknown[]) => void },
+	forceKill = false
+): void {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const globalAny = globalThis as any;
 	const bunSubprocess = globalAny.__AGENTUITY_BUN_SUBPROCESS__ as ProcessLike | undefined;
 	if (!bunSubprocess) return;
 
-	try {
-		bunSubprocess.kill('SIGTERM');
-		logger.debug('Bun subprocess killed');
-	} catch (err) {
-		logger.debug('Error killing Bun subprocess: %s', err);
+	const signal: NodeJS.Signals = forceKill ? 'SIGKILL' : 'SIGTERM';
+	const pid = bunSubprocess.pid;
+
+	// Kill the entire process tree if we have a PID (guard against dangerous PIDs)
+	if (pid && pid > 1) {
+		try {
+			process.kill(-pid, signal);
+			logger.debug('Sent %s to Bun subprocess process group -%d', signal, pid);
+		} catch {
+			// Process group kill failed, fall back to direct kill
+			try {
+				bunSubprocess.kill(signal);
+				logger.debug('Sent %s to Bun subprocess pid %d (direct)', signal, pid);
+			} catch (err) {
+				logger.debug('Error killing Bun subprocess: %s', err);
+			}
+		}
+	} else {
+		try {
+			bunSubprocess.kill(signal);
+			logger.debug('Bun subprocess killed with %s', signal);
+		} catch (err) {
+			logger.debug('Error killing Bun subprocess: %s', err);
+		}
 	}
+
 	globalAny.__AGENTUITY_BUN_SUBPROCESS__ = undefined;
 }
 
@@ -326,9 +364,9 @@ export const command = createCommand({
 		// and creates a new lockfile for this session
 		const devLock = await prepareDevLock(rootDir, opts.port, logger);
 
-		// Kill any lingering gravity processes from previous dev sessions
-		// This is a fallback for cases where the lockfile was corrupted
-		await killLingeringGravityProcesses(logger);
+		// Kill any lingering gravity processes from previous dev sessions.
+		// Scoped to this project to avoid killing gravity from other dev sessions.
+		await killLingeringGravityProcesses(logger, project?.projectId);
 
 		// Check and upgrade @agentuity/* dependencies if needed
 		const upgradeResult = await checkAndUpgradeDependencies(rootDir, logger);
@@ -534,102 +572,47 @@ export const command = createCommand({
 				};
 			}
 
-			// Start Vite dev server on an internal port.
-			// The user-facing port is handled by the front-door TCP proxy (ws-proxy)
-			// which routes WS upgrades to Bun and everything else to Vite.
+			// --- State for long-running processes ---
+			// Declared early so signal handlers can reference them before
+			// servers are started.
 			let viteServer: ServerLike | null = null;
-			let vitePort: number;
+			let frontDoorServer: import('../build/vite/ws-proxy').WsProxyServer | null = null;
+			let gravityProcess: ProcessLike | null = null;
+			let gravityHeartbeatInterval: ReturnType<typeof setInterval> | null = null;
+			let stdinListenerRegistered = false;
+			let stdinDataHandler: ((data: Buffer | string) => void) | null = null;
+			let shutdownRequested = false;
 
 			// Initialize process manager to track all servers/processes
 			const procManager = initProcessManager(logger);
 
-			try {
-				logger.debug('Starting Vite dev server (internal port %d)...', viteInternalPort);
-				const viteResult = await startViteAssetServer({
-					rootDir,
-					logger,
-					workbenchPath: workbench.config?.route,
-					port: viteInternalPort,
-					backendPort: bunBackendPort,
-					routePaths,
-					liveHostname: devmode?.hostname,
-				});
-				viteServer = viteResult.server;
-				vitePort = viteResult.port;
-
-				// Register Vite server with process manager
-				procManager.registerServer({
-					id: 'vite',
-					server: viteServer,
-					description: 'Vite dev server (frontend assets)',
-					port: vitePort,
-				});
-
-				// Update dev lock with actual Vite port
-				await devLock.updatePorts({ vite: vitePort });
-
-				logger.debug(
-					`Vite dev server running on port ${vitePort} (internal, proxying backend on port ${bunBackendPort})`
-				);
-			} catch (error) {
-				tui.error(`Failed to start Vite dev server: ${error}`);
-				await procManager.cleanup('vite startup failure');
-				await devLock.release();
-				originalExit(1);
-				return;
-			}
-
-			// Start the front-door TCP proxy on the user-facing port.
-			// Routes WebSocket upgrades (for /api/*, /_agentuity/*) directly to Bun
-			// and everything else (HTTP, HMR WebSocket) to Vite.
-			// This works around Bun's broken node:http upgrade socket implementation.
-			let frontDoorServer: import('node:net').Server | null = null;
-			try {
-				const { startWsProxy } = await import('../build/vite/ws-proxy');
-				frontDoorServer = await startWsProxy({
-					port: opts.port,
-					vitePort,
-					backendPort: bunBackendPort,
-					routePaths,
-					logger,
-				});
+			// Resolve the actual Vite port BEFORE starting Bun so that env vars
+			// like AGENTUITY_BASE_URL contain the correct port. The runtime's
+			// CORS trusted-origins are built once at startup, so a late update
+			// would leave the backend with stale origins.
+			const { findAvailablePort } = await import('../build/vite/vite-asset-server');
+			const vitePort = await findAvailablePort(viteInternalPort, '127.0.0.1');
 
-				// Register front-door proxy with process manager
-				procManager.registerServer({
-					id: 'front-door-proxy',
-					server: {
-						close: () => {
-							frontDoorServer?.close();
-						},
-					},
-					description: 'Front-door TCP proxy (WS routing)',
-					port: opts.port,
-				});
-
-				logger.debug(
-					`Front-door proxy on port ${opts.port} (Vite:${vitePort}, Bun:${bunBackendPort})`
+			if (vitePort !== viteInternalPort) {
+				logger.info(
+					`Port ${viteInternalPort} is in use, using port ${vitePort} for Vite dev server`
 				);
-			} catch (error) {
-				tui.error(`Failed to start front-door proxy: ${error}`);
-				await procManager.cleanup('front-door proxy startup failure');
-				await devLock.release();
-				originalExit(1);
-				return;
 			}
 
-			// --- State for long-running processes ---
-			let gravityProcess: ProcessLike | null = null;
-			let gravityHeartbeatInterval: ReturnType<typeof setInterval> | null = null;
-			let stdinListenerRegistered = false;
-			let stdinDataHandler: ((data: Buffer | string) => void) | null = null;
-			let shutdownRequested = false;
+			// Separate guard flags:
+			// - cleanupStarted: prevents double-entry into cleanup()
+			// - shutdownRequested: breaks the main wait loop (set inside cleanup
+			//   AFTER the cleanupStarted guard passes, so the loop resolves only
+			//   once cleanup has actually started running)
+			let cleanupStarted = false;
 
 			/**
 			 * Centralized cleanup function for all resources.
 			 * Uses the process manager for tracked servers/processes.
 			 */
 			const cleanup = async (exitAfter = false, exitCode = 0, silent = false) => {
-				if (shutdownRequested) return;
+				if (cleanupStarted) return;
+				cleanupStarted = true;
 				shutdownRequested = true;
 
 				if (!silent) {
@@ -647,7 +630,7 @@ export const command = createCommand({
 
 				// Additional cleanup for non-tracked resources
 				await devLock.release();
-				await killLingeringGravityProcesses(logger);
+				await killLingeringGravityProcesses(logger, project?.projectId);
 
 				if (exitAfter) {
 					if (stdinListenerRegistered && process.stdin.isTTY) {
@@ -673,7 +656,6 @@ export const command = createCommand({
 				if (exitingFromSignal) return;
 				exitingFromSignal = true;
 				if (reason) logger.debug('DevMode terminating (%d): %s', code, reason);
-				shutdownRequested = true;
 				cleanup(true, code).catch(() => originalExit(1));
 			};
 
@@ -693,21 +675,16 @@ export const command = createCommand({
 				);
 			});
 			process.on('exit', () => {
-				if (gravityProcess?.exitCode === null) {
-					try {
-						gravityProcess.kill('SIGKILL');
-					} catch {
-						// Ignore
-					}
-				}
-				if (viteServer) {
-					try {
-						viteServer.close();
-					} catch {
-						// Ignore
-					}
-				}
-				killBunSubprocess(logger);
+				// Last-resort synchronous cleanup. Only runs aggressive SIGKILL
+				// if the async cleanup() hasn't already handled everything.
+				// This prevents the race where both cleanup paths try to kill
+				// the same processes.
+				procManager.forceKillAllSync();
+
+				// SIGKILL the Bun subprocess tree as a final safety net.
+				// forceKill=true ensures we use SIGKILL (no time for graceful
+				// shutdown in an exit handler) and target the process group.
+				killBunSubprocess(logger, true);
 				releaseLockSync(rootDir);
 			});
 
@@ -861,6 +838,10 @@ export const command = createCommand({
 			// Note: AGENTUITY_SDK_KEY, NODE_ENV, AGENTUITY_ENV, and
 			// AGENTUITY_TRANSPORT_URL are already set in Step 0b (before
 			// agent discovery) to support gateway env patching.
+			//
+			// vitePort is pre-resolved (via findAvailablePort) before Bun
+			// starts, so env vars like AGENTUITY_BASE_URL are correct when
+			// the runtime builds its CORS trusted-origin set.
 
 			process.env.AGENTUITY_SDK_DEV_MODE = 'true';
 			process.env.AGENTUITY_RUNTIME = 'yes';
@@ -910,29 +891,141 @@ export const command = createCommand({
 					inspect: opts.inspect,
 					inspectWait: opts.inspectWait,
 					inspectBrk: opts.inspectBrk,
+					// Register the subprocess BEFORE the readiness wait so a SIGINT
+					// during startup can clean it up via procManager. Without this,
+					// the only safety net is the synchronous process.on('exit')
+					// handler, which is fragile and runs too late on some signals.
+					onSpawn: (proc) => {
+						procManager.registerProcess({
+							id: 'bun-backend',
+							process: proc,
+							description: 'Bun backend server (--hot)',
+							port: bunBackendPort,
+							critical: true,
+						});
+					},
 				});
+			} catch (error) {
+				tui.error(`Failed to start Bun backend server: ${error}`);
+				await cleanup(true, 1, true);
+				return;
+			}
 
-				// Register Bun subprocess with process manager
-				// The subprocess is stored in globalThis.__AGENTUITY_BUN_SUBPROCESS__
-				// eslint-disable-next-line @typescript-eslint/no-explicit-any
-				const bunSubprocess = (globalThis as any).__AGENTUITY_BUN_SUBPROCESS__ as ProcessLike;
-				if (bunSubprocess) {
-					procManager.registerProcess({
-						id: 'bun-backend',
-						process: bunSubprocess,
-						description: 'Bun backend server (--hot)',
-						port: bunBackendPort,
-						critical: true,
-					});
+			// ================================================================
+			// Step 4: Start Vite asset server (frontend + API proxy)
+			// ================================================================
+			// Vite starts AFTER the Bun backend so that its proxy is ready
+			// to forward API requests immediately — no ECONNREFUSED race.
+
+			try {
+				logger.debug('Starting Vite dev server (internal port %d)...', viteInternalPort);
+				const viteResult = await startViteAssetServer({
+					rootDir,
+					logger,
+					workbenchPath: workbench.config?.route,
+					port: vitePort,
+					backendPort: bunBackendPort,
+					routePaths,
+					liveHostname: devmode?.hostname,
+				});
+				viteServer = viteResult.server;
+
+				// Verify Vite used the port we pre-resolved (should always match
+				// since strictPort:true is set and we already confirmed availability).
+				if (viteResult.port !== vitePort) {
+					logger.warn(
+						`Vite started on port ${viteResult.port} instead of expected ${vitePort} — env vars may be incorrect`
+					);
 				}
+
+				// Register Vite server with process manager.
+				// We wrap close() to first force-drop keep-alive HTTP/HMR sockets via
+				// httpServer.closeAllConnections() (Node 18.2+). Without this, idle
+				// keep-alive connections keep the listener bound until they time out,
+				// which leaves the Vite port reserved for several seconds after the
+				// CLI exits. We also extend the close timeout (Vite's chokidar +
+				// HMR teardown can exceed 1s under load).
+				const viteForCleanup = viteServer;
+				procManager.registerServer({
+					id: 'vite',
+					server: {
+						close: async () => {
+							try {
+								const http = (
+									viteForCleanup as unknown as {
+										httpServer?: {
+											closeAllConnections?: () => void;
+											closeIdleConnections?: () => void;
+										};
+									}
+								).httpServer;
+								http?.closeIdleConnections?.();
+								http?.closeAllConnections?.();
+							} catch {
+								// Best effort — these methods are runtime-dependent.
+							}
+							await viteForCleanup.close();
+						},
+					},
+					description: 'Vite dev server (frontend assets)',
+					port: vitePort,
+					closeTimeoutMs: 3000,
+				});
+
+				// Update dev lock with actual Vite port
+				await devLock.updatePorts({ vite: vitePort });
+
+				logger.debug(
+					`Vite dev server running on port ${vitePort} (internal, proxying backend on port ${bunBackendPort})`
+				);
 			} catch (error) {
-				tui.error(`Failed to start Bun backend server: ${error}`);
+				tui.error(`Failed to start Vite dev server: ${error}`);
 				await cleanup(true, 1, true);
 				return;
 			}
 
 			// ================================================================
-			// Step 4: Start gravity tunnel (if public URL enabled)
+			// Step 5: Start front-door TCP proxy (user-facing port)
+			// ================================================================
+			// Routes WebSocket upgrades (for /api/*, /_agentuity/*) directly to Bun
+			// and everything else (HTTP, HMR WebSocket) to Vite.
+			// This works around Bun's broken node:http upgrade socket implementation.
+
+			try {
+				const { startWsProxy } = await import('../build/vite/ws-proxy');
+				frontDoorServer = await startWsProxy({
+					port: opts.port,
+					vitePort,
+					backendPort: bunBackendPort,
+					routePaths,
+					logger,
+				});
+
+				// Register front-door proxy with process manager. Use closeAll()
+				// (returns a Promise) so cleanup actually waits for the listener
+				// to release the user-facing port instead of fire-and-forgetting.
+				// closeAll() also destroys live piped sockets (HMR WS, backend WS)
+				// so the listener doesn't sit waiting for clients to disconnect.
+				procManager.registerServer({
+					id: 'front-door-proxy',
+					server: {
+						close: () => frontDoorServer?.closeAll() ?? Promise.resolve(),
+					},
+					description: 'Front-door TCP proxy (WS routing)',
+					port: opts.port,
+				});
+
+				logger.debug(
+					`Front-door proxy on port ${opts.port} (Vite:${vitePort}, Bun:${bunBackendPort})`
+				);
+			} catch (error) {
+				tui.error(`Failed to start front-door proxy: ${error}`);
+				await cleanup(true, 1, true);
+				return;
+			}
+
+			// ================================================================
+			// Step 6: Start gravity tunnel (if public URL enabled)
 			// ================================================================
 
 			if (gravityBin && gravityURL && devmode && project) {
@@ -945,6 +1038,15 @@ export const command = createCommand({
 					return;
 				}
 
+				// Gravity must target the user-facing front-door proxy port.
+				// The front-door proxy (ws-proxy) is the only server that correctly
+				// routes public WebSocket upgrades to /api/* through to the Bun backend.
+				// We read the actual bound port from the front-door server to avoid any
+				// mismatch with opts.port (e.g. if the port was overridden or shifted).
+				const frontDoorPort =
+					(frontDoorServer?.address() as import('node:net').AddressInfo | null)?.port ??
+					opts.port;
+
 				try {
 					gravityProcess = Bun.spawn(
 						[
@@ -952,7 +1054,7 @@ export const command = createCommand({
 							'--endpoint-id',
 							devmode.id,
 							'--port',
-							vitePort.toString(),
+							frontDoorPort.toString(),
 							'--url',
 							gravityURL,
 							'--log-level',
@@ -969,10 +1071,24 @@ export const command = createCommand({
 							cwd: rootDir,
 							stdout: 'pipe',
 							stderr: 'pipe',
-							detached: false,
+							// Make the child a process-group leader so process.kill(-pid, signal)
+							// from procManager.killProcessTree() actually reaches the whole tree
+							// (otherwise it fails with EPERM and falls back to a direct PID kill
+							// that leaves any grandchildren running). We intentionally do NOT call
+							// .unref() — we still want the parent to track the child's lifecycle
+							// and drive cleanup on Ctrl-C / shutdown.
+							detached: true,
+							// Pass a clean env without PORT to prevent the inherited
+							// PORT (set to bunBackendPort) from leaking into gravity.
+							env: {
+								...process.env,
+								PORT: undefined,
+							},
 						}
 					);
 
+					logger.debug('Gravity tunnel targeting front-door proxy on port %d', frontDoorPort);
+
 					const gravityPid = (gravityProcess as { pid?: number }).pid;
 					if (gravityPid) {
 						await devLock.registerChild({
@@ -1046,7 +1162,7 @@ export const command = createCommand({
 			}
 
 			// ================================================================
-			// Step 5: Keyboard shortcuts + wait for shutdown
+			// Step 7: Keyboard shortcuts + wait for shutdown
 			// ================================================================
 
 			if (interactive && process.stdin.isTTY && process.stdout.isTTY) {
@@ -1069,7 +1185,6 @@ export const command = createCommand({
 							process.stdin.removeListener('data', stdinDataHandler);
 							stdinDataHandler = null;
 						}
-						shutdownRequested = true;
 						cleanup(true, 0).catch(() => originalExit(1));
 						return;
 					}
@@ -1109,7 +1224,7 @@ export const command = createCommand({
 		} finally {
 			/* brute force clean up */
 			await devLock.release();
-			await killLingeringGravityProcesses(logger);
+			await killLingeringGravityProcesses(logger, project?.projectId);
 			releaseLockSync(rootDir);
 		}
 	},