@agentuity/cli 0.0.103 → 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;
@@ -72,7 +73,7 @@ async function killLingeringGravityProcesses(logger: {
 
 /**
  * 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;
 		}
@@ -405,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
@@ -412,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 {
@@ -419,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 {
@@ -430,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);
 			}
 		};
@@ -535,6 +573,9 @@ export const command = createCommand({
 					// Ignore errors during exit cleanup
 				}
 			}
+
+			// Release the dev lockfile synchronously
+			releaseLockSync(rootDir);
 		});
 
 		while (!shutdownRequested) {
@@ -640,7 +681,7 @@ export const command = createCommand({
 							);
 							previousMetadata = metadata;
 						}
-						await promises;
+						await Promise.all(promises);
 					},
 					clearOnSuccess: true,
 				});
@@ -759,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 {

package/src/cmd/dev/sync.ts

@@ -273,7 +273,7 @@ class DevmodeSyncService implements IDevmodeSyncService {
 		evalsToDelete: string[],
 		deploymentId: string
 	): Promise<void> {
-		this.logger.info(
+		this.logger.debug(
 			'[CLI EVAL SYNC] syncEvals called: %d to create, %d to delete',
 			evals.length,
 			evalsToDelete.length
@@ -360,24 +360,24 @@ class MockDevmodeSyncService implements IDevmodeSyncService {
 
 		// Log the requests that would be made
 		if (agentsToCreate.length > 0 || agentsToDelete.length > 0) {
-			this.logger.info(
+			this.logger.debug(
 				'[MOCK] Would make request: POST /cli/devmode/agent with %d agent(s) to create, %d agent(s) to delete',
 				agentsToCreate.length,
 				agentsToDelete.length
 			);
-			this.logger.info(
+			this.logger.debug(
 				'[MOCK] Request payload: %s',
 				JSON.stringify({ create: agentsToCreate, delete: agentsToDelete }, null, 2)
 			);
 		}
 
 		if (evalsToCreate.length > 0 || evalsToDelete.length > 0) {
-			this.logger.info(
+			this.logger.debug(
 				'[MOCK] Would make request: POST /cli/devmode/eval with %d eval(s) to create, %d eval(s) to delete',
 				evalsToCreate.length,
 				evalsToDelete.length
 			);
-			this.logger.info(
+			this.logger.debug(
 				'[MOCK] Request payload: %s',
 				JSON.stringify({ create: evalsToCreate, delete: evalsToDelete }, null, 2)
 			);
@@ -389,7 +389,7 @@ class MockDevmodeSyncService implements IDevmodeSyncService {
 			evalsToCreate.length === 0 &&
 			evalsToDelete.length === 0
 		) {
-			this.logger.info('[MOCK] No requests would be made (no changes detected)');
+			this.logger.debug('[MOCK] No requests would be made (no changes detected)');
 		}
 	}
 }

package/src/cmd/project/download.ts

@@ -375,9 +375,9 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 	// Build project
 	if (!noBuild) {
 		const exitCode = await tui.runCommand({
-			command: 'bun run build',
+			command: 'bun run build --dev',
 			cwd: dest,
-			cmd: ['bun', 'run', 'build'],
+			cmd: ['bun', 'run', 'build', '--dev'],
 			clearOnSuccess: true,
 		});
 		if (exitCode !== 0) {
@@ -385,6 +385,12 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 		}
 	}
 
+	// Generate and write AGENTS.md files for the CLI and source folders
+	// Always overwrite during project setup to ensure fresh content
+	await writeAgentsDocs(dest);
+}
+
+export async function initGitRepo(dest: string): Promise<void> {
 	// Initialize git repository if git is available
 	// Check for real git (not macOS stub that triggers Xcode CLT popup)
 	const { isGitAvailable, getDefaultBranch } = await import('../../git-helper');
@@ -435,10 +441,6 @@ export async function setupProject(options: SetupOptions): Promise<void> {
 			clearOnSuccess: true,
 		});
 	}
-
-	// Generate and write AGENTS.md files for the CLI and source folders
-	// Always overwrite during project setup to ensure fresh content
-	await writeAgentsDocs(dest);
 }
 
 async function replaceInFiles(dir: string, projectName: string, dirName: string): Promise<void> {

package/src/cmd/project/template-flow.ts

@@ -18,7 +18,7 @@ import * as tui from '../../tui';
 import { createPrompt, note } from '../../tui';
 import { playSound } from '../../sound';
 import { fetchTemplates, type TemplateInfo } from './templates';
-import { downloadTemplate, setupProject } from './download';
+import { downloadTemplate, setupProject, initGitRepo } from './download';
 import { type AuthData, type Config } from '../../types';
 import { ErrorCode } from '../../errors';
 import type { APIClient } from '../../api';
@@ -423,6 +423,9 @@ export async function runCreateFlow(options: CreateFlowOptions): Promise<void> {
 		}
 	}
 
+	// Initialize git repository after all files are generated
+	await initGitRepo(dest);
+
 	// Show completion message
 	if (!skipPrompts) {
 		tui.success('✨ Project created successfully!\n');