@agentuity/cli 0.0.102 → 0.0.104

package/src/cmd/dev/dev-lock.ts

@@ -0,0 +1,332 @@
+/**
+ * Dev Lock Manager
+ *
+ * Manages a lockfile to track the dev server process and its children.
+ * On startup, detects and cleans up stale processes from previous sessions.
+ * Ensures proper cleanup on all exit paths.
+ */
+
+import { join, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { existsSync, unlinkSync } from 'node:fs';
+import { promises as fs } from 'node:fs';
+
+interface LoggerLike {
+	debug: (msg: string, ...args: unknown[]) => void;
+	warn: (msg: string, ...args: unknown[]) => void;
+	error: (msg: string, ...args: unknown[]) => void;
+}
+
+/**
+ * Lockfile format for tracking dev server processes
+ */
+export interface DevLockFileV1 {
+	version: 1;
+	projectRoot: string;
+	mainPid: number;
+	instanceId: string;
+	createdAt: string;
+	updatedAt: string;
+	ports: {
+		bun?: number;
+		vite?: number;
+		gravity?: number;
+	};
+	children: Array<{
+		pid: number;
+		type: 'gravity' | 'vite' | 'other';
+		description?: string;
+	}>;
+}
+
+export interface DevLockManager {
+	state: DevLockFileV1;
+	registerChild: (info: {
+		pid: number;
+		type: 'gravity' | 'vite' | 'other';
+		description?: string;
+	}) => Promise<void>;
+	updatePorts: (ports: Partial<DevLockFileV1['ports']>) => Promise<void>;
+	release: () => Promise<void>;
+}
+
+function getLockPath(rootDir: string): string {
+	return join(rootDir, '.agentuity', 'devserver.lock');
+}
+
+/**
+ * Check if a process with the given PID exists
+ */
+function pidExists(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err: unknown) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code === 'ESRCH' || error.code === 'EINVAL') return false;
+		// EPERM means it exists but we can't signal it
+		return error.code === 'EPERM';
+	}
+}
+
+/**
+ * Kill a process by PID with SIGTERM, then SIGKILL if still alive
+ */
+async function killPid(pid: number, logger: LoggerLike): Promise<void> {
+	if (!pidExists(pid)) return;
+
+	try {
+		process.kill(pid, 'SIGTERM');
+		logger.debug('Sent SIGTERM to pid %d', pid);
+	} catch (err: unknown) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code === 'ESRCH') return;
+		logger.debug('Error sending SIGTERM to pid %d: %s', pid, error.message);
+	}
+
+	// Give it a moment to exit gracefully
+	await new Promise((r) => setTimeout(r, 500));
+
+	if (!pidExists(pid)) return;
+
+	// Force kill
+	try {
+		process.kill(pid, 'SIGKILL');
+		logger.debug('Sent SIGKILL to pid %d', pid);
+	} catch (err: unknown) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code !== 'ESRCH') {
+			logger.debug('Error sending SIGKILL to pid %d: %s', pid, error.message);
+		}
+	}
+
+	// Wait for process to fully terminate
+	await new Promise((r) => setTimeout(r, 100));
+}
+
+/**
+ * Read an existing lockfile (if any)
+ */
+async function readLock(lockPath: string, logger: LoggerLike): Promise<DevLockFileV1 | null> {
+	if (!existsSync(lockPath)) return null;
+	try {
+		const raw = await fs.readFile(lockPath, 'utf8');
+		const parsed = JSON.parse(raw);
+		if (parsed && parsed.version === 1) return parsed as DevLockFileV1;
+	} catch (err) {
+		logger.warn('Failed to read/parse devserver.lock: %s', err);
+	}
+	return null;
+}
+
+/**
+ * Remove lockfile if it exists
+ */
+async function removeLock(lockPath: string, logger: LoggerLike): Promise<void> {
+	try {
+		await fs.unlink(lockPath);
+		logger.debug('Removed devserver.lock');
+	} catch (err: unknown) {
+		const error = err as NodeJS.ErrnoException;
+		if (error.code !== 'ENOENT') {
+			logger.debug('Failed to remove devserver.lock: %s', error.message);
+		}
+	}
+}
+
+/**
+ * Check if a port is in use by attempting to connect to it.
+ * Uses GET instead of HEAD since some servers return 405 for HEAD requests.
+ * Any response (including errors like 404, 500) means the port is in use.
+ */
+async function isPortResponding(port: number): Promise<boolean> {
+	try {
+		const response = await fetch(`http://127.0.0.1:${port}/`, {
+			method: 'GET',
+			signal: AbortSignal.timeout(500),
+		});
+		// Consume body to avoid memory leaks
+		await response.text().catch(() => {});
+		return true;
+	} catch (err: unknown) {
+		// Connection refused (ECONNREFUSED) means nothing is listening
+		// Other errors (timeout, reset) might indicate a busy port
+		const error = err as Error & { cause?: { code?: string } };
+		const code = error.cause?.code;
+		if (code === 'ECONNREFUSED' || code === 'ECONNRESET') {
+			return false;
+		}
+		// For other errors (like timeout), assume port might be in use but unresponsive
+		return false;
+	}
+}
+
+/**
+ * Kill processes referenced by a stale lock, then remove the lock
+ */
+async function cleanupStaleLock(
+	rootDir: string,
+	lock: DevLockFileV1,
+	logger: LoggerLike
+): Promise<void> {
+	const lockPath = getLockPath(rootDir);
+	logger.debug(
+		'Cleaning up stale devserver.lock (pid=%d, instance=%s)',
+		lock.mainPid,
+		lock.instanceId
+	);
+
+	// Collect all PIDs to kill (children first, then main)
+	const childPids: number[] = [];
+	for (const child of lock.children ?? []) {
+		if (child.pid && child.pid !== lock.mainPid && child.pid !== process.pid) {
+			childPids.push(child.pid);
+		}
+	}
+
+	// Kill children first
+	for (const pid of childPids) {
+		await killPid(pid, logger);
+	}
+
+	// Kill main process if it's not us
+	if (lock.mainPid !== process.pid) {
+		await killPid(lock.mainPid, logger);
+	}
+
+	// Remove the stale lockfile
+	await removeLock(lockPath, logger);
+}
+
+/**
+ * Ensure there is no conflicting dev server for this project
+ * Always cleans up any existing lock and kills associated processes
+ */
+async function ensureNoActiveDevForProject(
+	rootDir: string,
+	port: number,
+	logger: LoggerLike
+): Promise<void> {
+	const lockPath = getLockPath(rootDir);
+	const existing = await readLock(lockPath, logger);
+	if (!existing) return;
+
+	const now = Date.now();
+	const createdAt = Date.parse(existing.createdAt || '');
+	const ageMs = isFinite(createdAt) ? now - createdAt : Infinity;
+
+	const mainAlive = pidExists(existing.mainPid);
+
+	// Check if the recorded Bun port is still responding
+	let bunPortInUse = false;
+	if (existing.ports?.bun) {
+		bunPortInUse = await isPortResponding(existing.ports.bun);
+	}
+
+	logger.debug(
+		'Found existing lock (pid=%d, mainAlive=%s, bunPortInUse=%s, age=%dms) - cleaning up',
+		existing.mainPid,
+		mainAlive,
+		bunPortInUse,
+		ageMs
+	);
+
+	await cleanupStaleLock(rootDir, existing, logger);
+}
+
+/**
+ * Initialize a new lock for the current dev run
+ * This should be called after ensureNoActiveDevForProject has possibly cleaned stale state
+ */
+async function initDevLock(
+	rootDir: string,
+	port: number,
+	logger: LoggerLike
+): Promise<DevLockManager> {
+	const lockPath = getLockPath(rootDir);
+	await fs.mkdir(dirname(lockPath), { recursive: true });
+
+	const state: DevLockFileV1 = {
+		version: 1,
+		projectRoot: rootDir,
+		mainPid: process.pid,
+		instanceId: randomUUID(),
+		createdAt: new Date().toISOString(),
+		updatedAt: new Date().toISOString(),
+		ports: { bun: port },
+		children: [],
+	};
+
+	const writeLock = async () => {
+		state.updatedAt = new Date().toISOString();
+		await fs.writeFile(lockPath, JSON.stringify(state, null, 2), { encoding: 'utf8' });
+	};
+
+	await writeLock();
+	logger.debug('Created devserver.lock (pid=%d, instance=%s)', state.mainPid, state.instanceId);
+
+	const manager: DevLockManager = {
+		state,
+
+		async registerChild(child) {
+			if (!child.pid) return;
+			// Avoid duplicates
+			if (state.children.some((c) => c.pid === child.pid)) return;
+			state.children.push(child);
+			await writeLock();
+			logger.debug('Registered child process (pid=%d, type=%s)', child.pid, child.type);
+		},
+
+		async updatePorts(ports) {
+			state.ports = { ...state.ports, ...ports };
+			await writeLock();
+		},
+
+		async release() {
+			await removeLock(lockPath, logger);
+		},
+	};
+
+	return manager;
+}
+
+/**
+ * Main entry point for dev lock management
+ * Call this early in the dev command to:
+ * 1. Clean up any stale processes from previous sessions
+ * 2. Create a new lockfile for this session
+ */
+export async function prepareDevLock(
+	rootDir: string,
+	port: number,
+	logger: LoggerLike
+): Promise<DevLockManager> {
+	await ensureNoActiveDevForProject(rootDir, port, logger);
+	return initDevLock(rootDir, port, logger);
+}
+
+/**
+ * Utility to kill all processes in a lockfile by path
+ * Useful for emergency cleanup without creating a new lock
+ */
+export async function cleanupLockfile(rootDir: string, logger: LoggerLike): Promise<void> {
+	const lockPath = getLockPath(rootDir);
+	const existing = await readLock(lockPath, logger);
+	if (existing) {
+		await cleanupStaleLock(rootDir, existing, logger);
+	}
+}
+
+/**
+ * Synchronous lockfile removal for use in process.on('exit') handlers
+ * Does not kill processes - just removes the file
+ */
+export function releaseLockSync(rootDir: string): void {
+	const lockPath = getLockPath(rootDir);
+	try {
+		unlinkSync(lockPath);
+	} catch {
+		// Ignore errors - file may already be gone
+	}
+}

package/src/cmd/dev/index.ts

@@ -16,6 +16,7 @@ import { getDefaultConfigDir, saveConfig } from '../../config';
 import type { Config } from '../../types';
 import { createFileWatcher } from './file-watcher';
 import { regenerateSkillsAsync } from './skills';
+import { prepareDevLock, releaseLockSync } from './dev-lock';
 
 const DEFAULT_PORT = 3500;
 const MIN_PORT = 1024;
@@ -42,9 +43,9 @@ interface BunServer {
  * Kill any lingering gravity processes from previous dev sessions.
  * This is a defensive measure to clean up orphaned processes.
  */
-async function killLingeringGravityProcesses(
-	logger: { debug: (msg: string, ...args: unknown[]) => void }
-): Promise<void> {
+async function killLingeringGravityProcesses(logger: {
+	debug: (msg: string, ...args: unknown[]) => void;
+}): Promise<void> {
 	// Only attempt on Unix-like systems (macOS, Linux)
 	if (process.platform === 'win32') {
 		return;
@@ -72,7 +73,7 @@ async function killLingeringGravityProcesses(
 
 /**
  * Stop the existing Bun server if one is running.
- * Waits for the port to become available before returning.
+ * Waits for the port to become available before returning (with timeout).
  */
 async function stopBunServer(
 	port: number,
@@ -81,26 +82,32 @@ async function stopBunServer(
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	const globalAny = globalThis as any;
 	const server = globalAny.__AGENTUITY_SERVER__ as BunServer | undefined;
-	if (!server) return;
+	if (!server) {
+		logger.debug('No Bun server to stop');
+		return;
+	}
 
 	try {
-		logger.debug('Stopping previous Bun server...');
+		logger.debug('Stopping Bun server...');
 		server.stop(true); // Close active connections immediately
+		logger.debug('Bun server stop() called');
 	} catch (err) {
-		logger.debug('Error stopping previous Bun server: %s', err);
+		logger.debug('Error stopping Bun server: %s', err);
 	}
 
-	// Wait for socket to close to avoid EADDRINUSE races
-	for (let i = 0; i < 20; i++) {
+	// Wait for socket to close (max 2 seconds to avoid hanging on shutdown)
+	const MAX_WAIT_ITERATIONS = 10;
+	for (let i = 0; i < MAX_WAIT_ITERATIONS; i++) {
 		try {
 			await fetch(`http://127.0.0.1:${port}/`, {
 				method: 'HEAD',
-				signal: AbortSignal.timeout(200),
+				signal: AbortSignal.timeout(150),
 			});
 			// Still responding, wait a bit more
 			await new Promise((r) => setTimeout(r, 50));
 		} catch {
 			// Connection refused or timeout => server is down
+			logger.debug('Bun server stopped');
 			break;
 		}
 	}
@@ -196,8 +203,12 @@ export const command = createCommand({
 			originalExit(1);
 		}
 
+		// Prepare dev lock: cleans up stale processes from previous sessions
+		// 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 prevents "zombie" gravity clients from blocking the public URL
+		// This is a fallback for cases where the lockfile was corrupted
 		await killLingeringGravityProcesses(logger);
 
 		// Setup devmode and gravity (if using public URL)
@@ -336,11 +347,16 @@ export const command = createCommand({
 			});
 			viteServer = viteResult.server;
 			vitePort = viteResult.port;
+
+			// Update dev lock with actual Vite port
+			await devLock.updatePorts({ vite: vitePort });
+
 			logger.debug(
 				`Vite asset server running on port ${vitePort} (stays running across backend restarts)`
 			);
 		} catch (error) {
 			tui.error(`Failed to start Vite asset server: ${error}`);
+			await devLock.release();
 			originalExit(1);
 			return;
 		}
@@ -371,6 +387,8 @@ export const command = createCommand({
 
 		// Track if cleanup is in progress to avoid duplicate cleanup
 		let cleaningUp = false;
+		// Track if shutdown was requested (SIGINT/SIGTERM) to break the main loop
+		let shutdownRequested = false;
 
 		/**
 		 * Centralized cleanup function for all resources.
@@ -403,6 +421,7 @@ export const command = createCommand({
 
 			// Kill gravity client with SIGTERM first, then SIGKILL as fallback
 			if (gravityProcess) {
+				logger.debug('Killing gravity process...');
 				try {
 					gravityProcess.kill('SIGTERM');
 					// Give it a moment to gracefully shutdown
@@ -410,6 +429,7 @@ export const command = createCommand({
 					if (gravityProcess.exitCode === null) {
 						gravityProcess.kill('SIGKILL');
 					}
+					logger.debug('Gravity process killed');
 				} catch (err) {
 					logger.debug('Error killing gravity process: %s', err);
 				} finally {
@@ -417,10 +437,20 @@ export const command = createCommand({
 				}
 			}
 
-			// Close Vite asset server last (it handles frontend, should stay up longest)
+			// Close Vite asset server with timeout to prevent hanging
 			if (viteServer) {
+				logger.debug('Closing Vite server...');
 				try {
-					await viteServer.close();
+					// Use Promise.race with timeout to prevent hanging
+					const closePromise = viteServer.close();
+					const timeoutPromise = new Promise<void>((resolve) => {
+						setTimeout(() => {
+							logger.debug('Vite server close timed out, continuing...');
+							resolve();
+						}, 2000);
+					});
+					await Promise.race([closePromise, timeoutPromise]);
+					logger.debug('Vite server closed');
 				} catch (err) {
 					logger.debug('Error closing Vite server: %s', err);
 				} finally {
@@ -428,10 +458,20 @@ export const command = createCommand({
 				}
 			}
 
+			// Release the dev lockfile
+			logger.debug('Releasing dev lock...');
+			try {
+				await devLock.release();
+				logger.debug('Dev lock released');
+			} catch (err) {
+				logger.debug('Error releasing dev lock: %s', err);
+			}
+
 			// Reset cleanup flag if not exiting (allows restart)
 			if (!exitAfter) {
 				cleaningUp = false;
 			} else {
+				logger.debug('Exiting with code %d', exitCode);
 				originalExit(exitCode);
 			}
 		};
@@ -474,6 +514,7 @@ export const command = createCommand({
 				if (reason) {
 					logger.debug('DevMode terminating (%d) due to: %s', code, reason);
 				}
+				shutdownRequested = true;
 				await cleanup(true, code);
 			};
 
@@ -488,7 +529,7 @@ export const command = createCommand({
 			// Handle uncaught exceptions - clean up and exit rather than limping on
 			process.on('uncaughtException', (err) => {
 				tui.error(
-					`Uncaught exception: ${err instanceof Error ? err.stack ?? err.message : String(err)}`
+					`Uncaught exception: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`
 				);
 				void safeExit(1, 'uncaughtException');
 			});
@@ -497,7 +538,7 @@ export const command = createCommand({
 			process.on('unhandledRejection', (reason) => {
 				logger.warn(
 					'Unhandled promise rejection: %s',
-					reason instanceof Error ? reason.stack ?? reason.message : String(reason)
+					reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)
 				);
 			});
 		}
@@ -532,9 +573,12 @@ export const command = createCommand({
 					// Ignore errors during exit cleanup
 				}
 			}
+
+			// Release the dev lockfile synchronously
+			releaseLockSync(rootDir);
 		});
 
-		while (true) {
+		while (!shutdownRequested) {
 			shouldRestart = false;
 
 			// Pause file watcher during build to avoid loops
@@ -589,10 +633,16 @@ export const command = createCommand({
 
 						const srcDir = join(rootDir, 'src');
 
+						const promises: Promise<void>[] = [];
+
 						// Generate/update prompt files (non-blocking)
-						import('../build/vite/prompt-generator')
-							.then(({ generatePromptFiles }) => generatePromptFiles(srcDir, logger))
-							.catch((err) => logger.warn('Failed to generate prompt files: %s', err.message));
+						promises.push(
+							import('../build/vite/prompt-generator')
+								.then(({ generatePromptFiles }) => generatePromptFiles(srcDir, logger))
+								.catch((err) =>
+									logger.warn('Failed to generate prompt files: %s', err.message)
+								)
+						);
 						const agents = await discoverAgents(
 							srcDir,
 							project?.projectId ?? '',
@@ -621,14 +671,17 @@ export const command = createCommand({
 
 						// Sync metadata with backend (creates agents and evals in the database)
 						if (syncService && project?.projectId) {
-							await syncService.sync(
-								metadata,
-								previousMetadata,
-								project.projectId,
-								deploymentId
+							promises.push(
+								syncService.sync(
+									metadata,
+									previousMetadata,
+									project.projectId,
+									deploymentId
+								)
 							);
 							previousMetadata = metadata;
 						}
+						await Promise.all(promises);
 					},
 					clearOnSuccess: true,
 				});
@@ -694,22 +747,35 @@ export const command = createCommand({
 				// Wait for app.ts to finish loading (Vite is ready but app may still be initializing)
 				// Give it 2 seconds to ensure app initialization completes
 				await new Promise((resolve) => setTimeout(resolve, 2000));
+
+				// Check if shutdown was requested during startup
+				if (shutdownRequested) {
+					break;
+				}
 			} catch (error) {
 				tui.error(`Failed to start dev server: ${error}`);
 				tui.warn('Waiting for file changes to retry...');
 
-				// Wait for next restart trigger
+				// Wait for next restart trigger or shutdown
 				await new Promise<void>((resolve) => {
 					const checkRestart = setInterval(() => {
-						if (shouldRestart) {
+						if (shouldRestart || shutdownRequested) {
 							clearInterval(checkRestart);
 							resolve();
 						}
 					}, 100);
 				});
+				if (shutdownRequested) {
+					break;
+				}
 				continue;
 			}
 
+			// Exit early if shutdown was requested
+			if (shutdownRequested) {
+				break;
+			}
+
 			try {
 				// Start gravity client if we have devmode
 				if (gravityBin && gravityURL && devmode) {
@@ -734,6 +800,16 @@ export const command = createCommand({
 						}
 					);
 
+					// Register gravity process in dev lock for cleanup tracking
+					const gravityPid = (gravityProcess as { pid?: number }).pid;
+					if (gravityPid) {
+						await devLock.registerChild({
+							pid: gravityPid,
+							type: 'gravity',
+							description: 'Gravity public URL tunnel',
+						});
+					}
+
 					// Log gravity output
 					(async () => {
 						try {
@@ -824,16 +900,21 @@ export const command = createCommand({
 				// Start/resume file watcher now that server is ready
 				fileWatcher.resume();
 
-				// Wait for restart signal
+				// Wait for restart signal or shutdown
 				await new Promise<void>((resolve) => {
 					const checkRestart = setInterval(() => {
-						if (shouldRestart) {
+						if (shouldRestart || shutdownRequested) {
 							clearInterval(checkRestart);
 							resolve();
 						}
 					}, 100);
 				});
 
+				// Exit loop if shutdown was requested
+				if (shutdownRequested) {
+					break;
+				}
+
 				// Restart triggered - cleanup and loop (Vite stays running)
 				logger.debug('Restarting backend server...');
 
@@ -849,13 +930,18 @@ export const command = createCommand({
 				// Cleanup on error (Vite stays running)
 				await cleanupForRestart();
 
+				// Exit if shutdown was requested during error handling
+				if (shutdownRequested) {
+					break;
+				}
+
 				// Resume file watcher to detect changes for retry
 				fileWatcher.resume();
 
-				// Wait for next restart trigger
+				// Wait for next restart trigger or shutdown
 				await new Promise<void>((resolve) => {
 					const checkRestart = setInterval(() => {
-						if (shouldRestart) {
+						if (shouldRestart || shutdownRequested) {
 							clearInterval(checkRestart);
 							resolve();
 						}