@agentuity/cli 2.0.10 → 3.0.0-alpha.0

package/src/cmd/dev/file-watcher.ts

@@ -1,423 +0,0 @@
-/**
- * File Watcher for Dev Server Hot Reload
- *
- * Watches source files and triggers server restart on changes.
- * Handles both backend (API, agents, lib) and generates restart signals.
- */
-
-import { watch, type FSWatcher, statSync, readdirSync, lstatSync } from 'node:fs';
-import { resolve, relative } from 'node:path';
-import type { Logger } from '../../types';
-import { createAgentTemplates } from './templates';
-
-export interface FileWatcherOptions {
-	rootDir: string;
-	logger: Logger;
-	onRestart: () => void;
-	additionalPaths?: string[];
-}
-
-export interface FileWatcherManager {
-	start: () => void;
-	stop: () => void;
-	pause: () => void;
-	resume: () => void;
-}
-
-/**
- * Create a file watcher manager for hot reload
- */
-export function createFileWatcher(options: FileWatcherOptions): FileWatcherManager {
-	const { rootDir, logger, onRestart, additionalPaths = [] } = options;
-
-	const watchers: FSWatcher[] = [];
-	let paused = false;
-	let buildCooldownTimer: NodeJS.Timeout | null = null;
-
-	// Directories to ignore - these are NEVER traversed into
-	// This prevents EMFILE errors from symlink cycles in node_modules
-	const ignoreDirs = new Set([
-		'.agentuity',
-		'.agents',
-		'.claude',
-		'.code',
-		'.opencode',
-		'node_modules',
-		'.git',
-		'.github',
-		'dist',
-		'build',
-		'.next',
-		'.turbo',
-		'.npm',
-		'.dist',
-		'.vscode',
-		'.idea',
-		'.DS_Store',
-		'.playwright',
-		'.bun',
-		'src/generated',
-	]);
-
-	// Paths to ignore for file change events (but may still be traversed)
-	const ignorePaths = [
-		'.agentuity',
-		'.agents',
-		'.claude',
-		'.code',
-		'.opencode',
-		'node_modules',
-		'.git',
-		'.github',
-		'dist',
-		'build',
-		'.next',
-		'.turbo',
-		'.npm',
-		'.dist',
-		'.vscode',
-		'.idea',
-		'.bun',
-		'.DS_Store',
-		'.playwright',
-		'src/web', // Vite handles frontend with HMR - no backend restart needed
-		'src/generated', // Generated files shouldn't trigger rebuilds
-	];
-
-	// File extensions to ignore - non-code files that shouldn't trigger reload
-	const ignoreExtensions = new Set([
-		'.md',
-		'.mdx',
-		'.txt',
-		'.log',
-		'.lock',
-		'.yaml',
-		'.yml',
-		'.toml',
-		'.csv',
-		'.svg',
-		'.png',
-		'.jpg',
-		'.jpeg',
-		'.gif',
-		'.webp',
-		'.ico',
-		'.woff',
-		'.woff2',
-		'.ttf',
-		'.eot',
-		'.mp4',
-		'.mp3',
-		'.wav',
-		'.ogg',
-		'.webm',
-		'.pdf',
-		'.zip',
-		'.tar',
-		'.gz',
-		'.map',
-	]);
-
-	/**
-	 * Check if a path should be ignored
-	 */
-	function shouldIgnorePath(changedFile: string | null, watchDir: string): boolean {
-		if (!changedFile) return false;
-
-		const absPath = resolve(watchDir, changedFile);
-
-		// Check against ignore list - match both relative path and absolute path
-		for (const ignorePath of ignorePaths) {
-			// Check relative path from watchDir
-			if (
-				changedFile === ignorePath ||
-				changedFile.startsWith(`${ignorePath}/`) ||
-				changedFile.startsWith(`${ignorePath}\\`)
-			) {
-				logger.trace('File change ignored (%s): %s', ignorePath, changedFile);
-				return true;
-			}
-
-			// Check if absolute path contains the ignore pattern
-			const ignoreAbsPath = resolve(rootDir, ignorePath);
-			if (
-				absPath === ignoreAbsPath ||
-				absPath.startsWith(`${ignoreAbsPath}/`) ||
-				absPath.startsWith(`${ignoreAbsPath}\\`)
-			) {
-				logger.trace('File change ignored (%s): %s', ignorePath, changedFile);
-				return true;
-			}
-
-			// Also check if changedFile path includes the ignore pattern anywhere
-			// This handles cases like "some/path/.agentuity/file.js"
-			const normalizedChanged = changedFile.replace(/\\/g, '/');
-			const normalizedIgnore = ignorePath.replace(/\\/g, '/');
-			if (
-				normalizedChanged.includes(`/${normalizedIgnore}/`) ||
-				normalizedChanged.includes(`/${normalizedIgnore}`)
-			) {
-				logger.trace('File change ignored (%s in path): %s', ignorePath, changedFile);
-				return true;
-			}
-		}
-
-		// Ignore temp files from editors
-		if (changedFile.match(/\.(tmp|swp|swo|swx)$|~$/)) {
-			logger.trace('File change ignored (temp file): %s', changedFile);
-			return true;
-		}
-
-		// Ignore files with non-code extensions
-		const extIndex = changedFile.lastIndexOf('.');
-		if (extIndex !== -1) {
-			const ext = changedFile.slice(extIndex).toLowerCase();
-			if (ignoreExtensions.has(ext)) {
-				logger.trace('File change ignored (%s): %s', ext, changedFile);
-				return true;
-			}
-		}
-
-		// Ignore hidden files (except .env)
-		if (changedFile.startsWith('.') && !changedFile.startsWith('.env')) {
-			logger.trace('File change ignored (hidden file): %s', changedFile);
-			return true;
-		}
-
-		return false;
-	}
-
-	/**
-	 * Handle file change event
-	 */
-	function handleFileChange(eventType: string, changedFile: string | null, watchDir: string) {
-		if (paused) {
-			logger.trace('File change ignored (watcher paused): %s', changedFile);
-			return;
-		}
-
-		if (shouldIgnorePath(changedFile, watchDir)) {
-			return;
-		}
-
-		// During build cooldown, ignore changes (they're likely build outputs)
-		if (buildCooldownTimer) {
-			logger.trace('File change ignored (build cooldown): %s', changedFile);
-			return;
-		}
-
-		// Get absolute path for checking
-		const absPath = changedFile ? resolve(watchDir, changedFile) : watchDir;
-
-		// Check if this is a directory
-		let isDirectory = false;
-		try {
-			const stats = statSync(absPath);
-			isDirectory = stats.isDirectory();
-		} catch {
-			// File doesn't exist (was deleted) - not a directory
-			isDirectory = false;
-		}
-
-		// Check if an empty directory was created in src/agent/
-		// This helps with developer experience by auto-scaffolding template files
-		if (changedFile && eventType === 'rename' && isDirectory) {
-			try {
-				// Normalize the path for comparison (use forward slashes)
-				const normalizedPath = changedFile.replace(/\\/g, '/');
-
-				// Check if it's empty
-				const contents = readdirSync(absPath);
-				if (contents.length === 0) {
-					if (
-						normalizedPath.startsWith('src/agent/') ||
-						normalizedPath.includes('/src/agent/')
-					) {
-						logger.debug('Agent directory created: %s', changedFile);
-						createAgentTemplates(absPath);
-					}
-				}
-			} catch (error) {
-				// File might have been deleted or doesn't exist yet - this is normal
-				logger.trace(
-					'Unable to check directory for template creation (%s): %s',
-					changedFile,
-					error
-				);
-			}
-		}
-
-		// Ignore directory-only change events (mtime updates when files inside change)
-		// We only care about actual file changes - the watcher will report those directly
-		if (isDirectory && eventType === 'change') {
-			logger.trace('File change ignored (directory mtime update): %s', changedFile);
-			return;
-		}
-
-		logger.debug('File changed (%s): %s', eventType, changedFile || watchDir);
-		onRestart();
-	}
-
-	/**
-	 * Recursively collect all directories to watch, skipping ignored directories.
-	 * This prevents EMFILE errors from symlink cycles in node_modules.
-	 */
-	function collectWatchDirs(dir: string, visited: Set<string> = new Set()): string[] {
-		const dirs: string[] = [dir];
-
-		try {
-			// Use lstat to check for symlinks - get the real path to detect cycles
-			const stat = lstatSync(dir);
-
-			// Skip symlinks to prevent following circular symlinks
-			if (stat.isSymbolicLink()) {
-				logger.trace('Skipping symlink: %s', dir);
-				return [];
-			}
-
-			// Track visited inodes to detect cycles
-			const key = `${stat.dev}:${stat.ino}`;
-			if (visited.has(key)) {
-				logger.trace('Skipping already visited directory (cycle detected): %s', dir);
-				return [];
-			}
-			visited.add(key);
-
-			const entries = readdirSync(dir, { withFileTypes: true });
-
-			for (const entry of entries) {
-				if (!entry.isDirectory()) continue;
-
-				const name = entry.name;
-
-				// Skip ignored directories entirely - this is the key fix
-				if (ignoreDirs.has(name)) {
-					logger.trace('Skipping ignored directory: %s', resolve(dir, name));
-					continue;
-				}
-
-				// Skip hidden directories (except specific ones like .env folders)
-				if (name.startsWith('.')) {
-					logger.trace('Skipping hidden directory: %s', resolve(dir, name));
-					continue;
-				}
-
-				const fullPath = resolve(dir, name);
-				dirs.push(...collectWatchDirs(fullPath, visited));
-			}
-		} catch (error) {
-			logger.trace('Error reading directory %s: %s', dir, error);
-		}
-
-		return dirs;
-	}
-
-	/**
-	 * Start watching files
-	 */
-	function start() {
-		logger.debug('Starting file watchers for hot reload...');
-
-		// Collect all directories to watch, excluding node_modules and other ignored dirs
-		const allDirs = collectWatchDirs(rootDir);
-
-		// Add additional paths
-		if (additionalPaths && additionalPaths.length > 0) {
-			for (const additionalPath of additionalPaths) {
-				const fullPath = resolve(rootDir, additionalPath);
-				allDirs.push(...collectWatchDirs(fullPath));
-			}
-		}
-
-		// De-duplicate directories
-		const uniqueDirs = [...new Set(allDirs)];
-
-		logger.debug('Collected %d directories to watch', uniqueDirs.length);
-
-		// Watch each directory non-recursively
-		for (const watchPath of uniqueDirs) {
-			try {
-				// Use non-recursive watch to avoid traversing into node_modules
-				const watcher = watch(watchPath, { recursive: false }, (eventType, changedFile) => {
-					// Construct relative path from rootDir for consistent handling
-					const relPath = changedFile
-						? relative(rootDir, resolve(watchPath, changedFile))
-						: relative(rootDir, watchPath);
-					handleFileChange(eventType, relPath || changedFile, rootDir);
-				});
-
-				watchers.push(watcher);
-			} catch (error) {
-				logger.trace('Failed to start watcher for %s: %s', watchPath, error);
-			}
-		}
-
-		logger.debug('File watchers started (%d directories)', watchers.length);
-	}
-
-	/**
-	 * Stop all watchers
-	 */
-	function stop() {
-		logger.debug('Stopping file watchers...');
-
-		for (const watcher of watchers) {
-			try {
-				watcher.close();
-			} catch (error) {
-				logger.trace('Error closing watcher: %s', error);
-			}
-		}
-
-		watchers.length = 0;
-
-		if (buildCooldownTimer) {
-			clearTimeout(buildCooldownTimer);
-			buildCooldownTimer = null;
-		}
-
-		logger.debug('File watchers stopped');
-	}
-
-	/**
-	 * Temporarily pause watching (e.g., during build)
-	 */
-	function pause() {
-		paused = true;
-		logger.trace('File watchers paused');
-
-		// Set cooldown timer to ignore changes for a bit after build
-		if (buildCooldownTimer) {
-			clearTimeout(buildCooldownTimer);
-		}
-
-		buildCooldownTimer = setTimeout(() => {
-			buildCooldownTimer = null;
-			logger.trace('Build cooldown expired');
-		}, 500); // 500ms cooldown
-	}
-
-	/**
-	 * Resume watching
-	 */
-	function resume() {
-		paused = false;
-
-		// Clear any pending build cooldown timer so file changes are detected immediately.
-		// Without this, events arriving during the remaining cooldown window after a fast
-		// typecheck failure would be silently dropped.
-		if (buildCooldownTimer) {
-			clearTimeout(buildCooldownTimer);
-			buildCooldownTimer = null;
-		}
-
-		logger.trace('File watchers resumed');
-	}
-
-	return {
-		start,
-		stop,
-		pause,
-		resume,
-	};
-}

package/src/cmd/dev/process-manager.ts

@@ -1,261 +0,0 @@
-/**
- * Process Manager for Dev Mode
- *
- * Tracks all spawned processes and ensures they're cleaned up on:
- * - Startup failure (any server fails to start)
- * - Runtime crash (uncaught exception)
- * - Graceful shutdown (SIGINT/SIGTERM)
- *
- * This prevents orphan processes and port conflicts between dev sessions.
- */
-
-import type { Logger } from '../../types';
-
-export interface ManagedProcess {
-	/** Process identifier for logging */
-	id: string;
-	/** The process handle */
-	process: {
-		kill: (signal?: number | NodeJS.Signals) => void;
-		exitCode: number | null;
-		pid?: number;
-	};
-	/** Human-readable description */
-	description: string;
-	/** The port this process uses (if any) */
-	port?: number;
-	/** Whether this process is critical (startup fails if it dies) */
-	critical?: boolean;
-}
-
-export interface ManagedServer {
-	/** Server identifier */
-	id: string;
-	/** The server handle */
-	server: {
-		close: () => void | Promise<void>;
-	};
-	/** Human-readable description */
-	description: string;
-	/** The port this server uses */
-	port?: number;
-}
-
-/**
- * Process Manager
- *
- * Tracks all processes and servers started during dev mode and provides
- * centralized cleanup on failure or shutdown.
- */
-export class ProcessManager {
-	private processes: ManagedProcess[] = [];
-	private servers: ManagedServer[] = [];
-	private logger: Logger;
-	private cleaningUp = false;
-
-	constructor(logger: Logger) {
-		this.logger = logger;
-	}
-
-	/**
-	 * Register a spawned process for tracking.
-	 */
-	registerProcess(proc: ManagedProcess): void {
-		this.processes.push(proc);
-		this.logger.debug(
-			'Registered process: %s (pid=%s, port=%s)',
-			proc.id,
-			proc.process.pid ?? 'unknown',
-			proc.port ?? 'n/a'
-		);
-	}
-
-	/**
-	 * Register a server for tracking.
-	 */
-	registerServer(server: ManagedServer): void {
-		this.servers.push(server);
-		this.logger.debug('Registered server: %s (port=%s)', server.id, server.port ?? 'n/a');
-	}
-
-	/**
-	 * Unregister a process (e.g., after it exits normally).
-	 */
-	unregisterProcess(id: string): void {
-		const idx = this.processes.findIndex((p) => p.id === id);
-		if (idx !== -1) {
-			this.processes.splice(idx, 1);
-			this.logger.debug('Unregistered process: %s', id);
-		}
-	}
-
-	/**
-	 * Unregister a server.
-	 */
-	unregisterServer(id: string): void {
-		const idx = this.servers.findIndex((s) => s.id === id);
-		if (idx !== -1) {
-			this.servers.splice(idx, 1);
-			this.logger.debug('Unregistered server: %s', id);
-		}
-	}
-
-	/**
-	 * Get all registered ports (for cleanup verification).
-	 */
-	getPorts(): number[] {
-		const ports: number[] = [];
-		for (const proc of this.processes) {
-			if (proc.port) ports.push(proc.port);
-		}
-		for (const server of this.servers) {
-			if (server.port) ports.push(server.port);
-		}
-		return ports;
-	}
-
-	/**
-	 * Clean up all tracked processes and servers.
-	 *
-	 * @param reason - Why cleanup is happening (for logging)
-	 * @param timeout - Max time to wait for graceful shutdown (ms)
-	 */
-	async cleanup(reason: string, timeout = 3000): Promise<void> {
-		if (this.cleaningUp) {
-			this.logger.debug('Cleanup already in progress, skipping');
-			return;
-		}
-		this.cleaningUp = true;
-
-		this.logger.debug('Starting cleanup (reason: %s)', reason);
-
-		// Kill processes in reverse order (LIFO)
-		for (let i = this.processes.length - 1; i >= 0; i--) {
-			const proc = this.processes[i];
-			if (!proc) continue;
-
-			try {
-				if (proc.process.exitCode === null) {
-					this.logger.debug(
-						'Killing process %s (pid=%s)',
-						proc.id,
-						proc.process.pid ?? 'unknown'
-					);
-					proc.process.kill('SIGTERM');
-				}
-			} catch (err) {
-				this.logger.debug('Error killing process %s: %s', proc.id, err);
-			}
-		}
-
-		// Close servers
-		for (let i = this.servers.length - 1; i >= 0; i--) {
-			const server = this.servers[i];
-			if (!server) continue;
-
-			try {
-				this.logger.debug('Closing server %s', server.id);
-				const closePromise = server.server.close();
-				if (closePromise instanceof Promise) {
-					await Promise.race([
-						closePromise,
-						new Promise<void>((resolve) => setTimeout(resolve, 1000)),
-					]);
-				}
-			} catch (err) {
-				this.logger.debug('Error closing server %s: %s', server.id, err);
-			}
-		}
-
-		// Wait for processes to exit, then force-kill if needed
-		const startTime = Date.now();
-		while (Date.now() - startTime < timeout) {
-			const allExited = this.processes.every((p) => p.process.exitCode !== null);
-			if (allExited) break;
-			await new Promise((resolve) => setTimeout(resolve, 100));
-		}
-
-		// Force kill any remaining
-		for (const proc of this.processes) {
-			if (proc.process.exitCode === null) {
-				try {
-					this.logger.debug('Force killing process %s', proc.id);
-					proc.process.kill('SIGKILL');
-				} catch (err) {
-					this.logger.debug('Error force killing process %s: %s', proc.id, err);
-				}
-			}
-		}
-
-		this.logger.debug('Cleanup complete');
-		this.processes = [];
-		this.servers = [];
-	}
-
-	/**
-	 * Verify that all ports used by tracked processes are released.
-	 * Used after cleanup to ensure no orphan processes remain.
-	 */
-	async verifyPortsReleased(): Promise<{ port: number; released: boolean }[]> {
-		const results: { port: number; released: boolean }[] = [];
-		const ports = this.getPorts();
-
-		for (const port of ports) {
-			const released = await this.isPortAvailable(port);
-			results.push({ port, released });
-
-			if (!released) {
-				this.logger.warn('Port %d is still in use after cleanup', port);
-			}
-		}
-
-		return results;
-	}
-
-	/**
-	 * Check if a port is available.
-	 */
-	private isPortAvailable(port: number, host = '127.0.0.1'): Promise<boolean> {
-		return new Promise((resolve) => {
-			const net = require('node:net');
-			const server = net.createServer();
-			server.once('error', () => resolve(false));
-			server.listen(port, host, () => {
-				server.close(() => resolve(true));
-			});
-		});
-	}
-}
-
-/**
- * Global process manager instance for dev mode.
- * Set in dev/index.ts during startup.
- */
-let globalProcessManager: ProcessManager | null = null;
-
-/**
- * Get the global process manager (throws if not initialized).
- */
-export function getProcessManager(): ProcessManager {
-	if (!globalProcessManager) {
-		throw new Error('ProcessManager not initialized. Call initProcessManager first.');
-	}
-	return globalProcessManager;
-}
-
-/**
- * Initialize the global process manager.
- */
-export function initProcessManager(logger: Logger): ProcessManager {
-	globalProcessManager = new ProcessManager(logger);
-	return globalProcessManager;
-}
-
-/**
- * Cleanup helper that can be called from signal handlers or error handlers.
- */
-export async function cleanupAll(reason: string): Promise<void> {
-	if (globalProcessManager) {
-		await globalProcessManager.cleanup(reason);
-	}
-}