@agentuity/cli 2.0.0-beta.0 → 2.0.0-beta.1

package/src/cmd/dev/index.ts

@@ -20,6 +20,8 @@ import { isTTY, hasLoggedInBefore } from '../../auth';
 
 import { prepareDevLock, releaseLockSync } from './dev-lock';
 import { checkAndUpgradeDependencies } from '../../utils/dependency-checker';
+import { initProcessManager } from './process-manager';
+import { detectVersionMismatch, formatVersionMismatchWarning } from '../../utils/version-mismatch';
 
 import { ErrorCode } from '../../errors';
 
@@ -31,12 +33,13 @@ const MAX_PORT = 65535;
 interface ProcessLike {
 	kill: (signal?: number | NodeJS.Signals) => void;
 	exitCode: number | null;
+	pid?: number;
 	stdout?: AsyncIterable<Uint8Array>;
 	stderr?: AsyncIterable<Uint8Array>;
 }
 
 interface ServerLike {
-	close: () => void;
+	close: () => void | Promise<void>;
 }
 
 /**
@@ -337,6 +340,14 @@ export const command = createCommand({
 			);
 		}
 
+		// Check for version mismatches (v1 vs v2 SDK packages)
+		const versionMismatch = detectVersionMismatch(rootDir, logger);
+		if (versionMismatch.hasV1Packages || versionMismatch.hasMajorMismatches) {
+			tui.newline();
+			tui.warning(formatVersionMismatchWarning(versionMismatch));
+			tui.newline();
+		}
+
 		try {
 			// Setup devmode and gravity (if using public URL)
 			const useMockService = process.env.DEVMODE_SYNC_SERVICE_MOCK === 'true';
@@ -428,12 +439,12 @@ export const command = createCommand({
 				}
 			}
 
-			// Get workbench info from config (new Vite approach)
-			const { loadAgentuityConfig, getWorkbenchConfig } = await import(
+			// Get workbench info from createApp() in app.ts (v2 approach)
+			const { getWorkbenchConfig, loadRuntimeConfig } = await import(
 				'../build/vite/config-loader'
 			);
-			const agentuityConfig = await loadAgentuityConfig(rootDir, ctx.logger);
-			const workbenchConfigData = getWorkbenchConfig(agentuityConfig, true); // dev mode
+			const runtimeConfig = await loadRuntimeConfig(rootDir, logger);
+			const workbenchConfigData = getWorkbenchConfig(true, runtimeConfig); // dev mode
 			const workbench = {
 				hasWorkbench: workbenchConfigData.enabled,
 				config: workbenchConfigData.enabled
@@ -529,6 +540,9 @@ export const command = createCommand({
 			let viteServer: ServerLike | null = null;
 			let vitePort: number;
 
+			// 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({
@@ -542,6 +556,14 @@ export const command = createCommand({
 				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 });
 
@@ -550,6 +572,7 @@ export const command = createCommand({
 				);
 			} catch (error) {
 				tui.error(`Failed to start Vite dev server: ${error}`);
+				await procManager.cleanup('vite startup failure');
 				await devLock.release();
 				originalExit(1);
 				return;
@@ -569,11 +592,25 @@ export const command = createCommand({
 					routePaths,
 					logger,
 				});
+
+				// 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})`
 				);
 			} 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;
@@ -585,63 +622,29 @@ export const command = createCommand({
 			let stdinListenerRegistered = false;
 			let stdinDataHandler: ((data: Buffer | string) => void) | null = null;
 			let shutdownRequested = false;
-			let cleaningUp = 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 (cleaningUp) return;
-				cleaningUp = true;
+				if (shutdownRequested) return;
+				shutdownRequested = true;
 
 				if (!silent) {
 					tui.info('Shutting down...');
 				}
 
-				// Stop front-door proxy
-				try {
-					frontDoorServer?.close();
-				} catch (err) {
-					logger.debug('Error stopping front-door proxy: %s', err);
-				}
-
-				// Kill Bun subprocess
-				killBunSubprocess(logger);
-
-				// Stop gravity heartbeat interval
+				// Stop gravity heartbeat interval first
 				if (gravityHeartbeatInterval) {
 					clearInterval(gravityHeartbeatInterval);
 					gravityHeartbeatInterval = null;
 				}
 
-				// Kill gravity client
-				if (gravityProcess) {
-					try {
-						gravityProcess.kill('SIGTERM');
-						await new Promise((resolve) => setTimeout(resolve, 150));
-						if (gravityProcess.exitCode === null) {
-							gravityProcess.kill('SIGKILL');
-						}
-					} catch (err) {
-						logger.debug('Error killing gravity: %s', err);
-					} finally {
-						gravityProcess = null;
-					}
-				}
-
-				// Close Vite
-				if (viteServer) {
-					try {
-						const closePromise = viteServer.close();
-						const timeoutPromise = new Promise<void>((resolve) => setTimeout(resolve, 2000));
-						await Promise.race([closePromise, timeoutPromise]);
-					} catch (err) {
-						logger.debug('Error closing Vite: %s', err);
-					} finally {
-						viteServer = null;
-					}
-				}
+				// Use process manager for tracked cleanup
+				await procManager.cleanup('shutdown');
 
+				// Additional cleanup for non-tracked resources
 				await devLock.release();
 				await killLingeringGravityProcesses(logger);
 
@@ -848,15 +851,35 @@ export const command = createCommand({
 			// Step 3: Start Bun backend with --hot (handles its own HMR)
 			// ================================================================
 
-			await startBunDevServer({
-				rootDir,
-				port: bunBackendPort,
-				logger,
-				vitePort,
-				inspect: opts.inspect,
-				inspectWait: opts.inspectWait,
-				inspectBrk: opts.inspectBrk,
-			});
+			try {
+				await startBunDevServer({
+					rootDir,
+					port: bunBackendPort,
+					logger,
+					vitePort,
+					inspect: opts.inspect,
+					inspectWait: opts.inspectWait,
+					inspectBrk: opts.inspectBrk,
+				});
+
+				// 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,
+					});
+				}
+			} catch (error) {
+				tui.error(`Failed to start Bun backend server: ${error}`);
+				await cleanup(true, 1, true);
+				return;
+			}
 
 			// ================================================================
 			// Step 4: Start gravity tunnel (if public URL enabled)
@@ -865,94 +888,111 @@ export const command = createCommand({
 			if (gravityBin && gravityURL && devmode && project) {
 				const privateKeyPEM = devmode.privateKey ?? savedPrivateKey;
 				if (!privateKeyPEM) {
-					throw new Error(
+					tui.error(
 						'No private key available for gravity connection. Please re-run to generate a new key.'
 					);
+					await cleanup(true, 1, true);
+					return;
 				}
-				gravityProcess = Bun.spawn(
-					[
-						gravityBin,
-						'--endpoint-id',
-						devmode.id,
-						'--port',
-						vitePort.toString(),
-						'--url',
-						gravityURL,
-						'--log-level',
-						process.env.AGENTUITY_GRAVITY_LOG_LEVEL ?? 'error',
-						'--org-id',
-						project.orgId,
-						'--project-id',
-						project.projectId,
-						'--private-key',
-						Buffer.from(privateKeyPEM).toString('base64'),
-						'--health-check',
-					],
-					{
-						cwd: rootDir,
-						stdout: 'pipe',
-						stderr: 'pipe',
-						detached: false,
-					}
-				);
 
-				const gravityPid = (gravityProcess as { pid?: number }).pid;
-				if (gravityPid) {
-					await devLock.registerChild({
-						pid: gravityPid,
-						type: 'gravity',
-						description: 'Gravity public URL tunnel',
-					});
-				}
+				try {
+					gravityProcess = Bun.spawn(
+						[
+							gravityBin,
+							'--endpoint-id',
+							devmode.id,
+							'--port',
+							vitePort.toString(),
+							'--url',
+							gravityURL,
+							'--log-level',
+							process.env.AGENTUITY_GRAVITY_LOG_LEVEL ?? 'error',
+							'--org-id',
+							project.orgId,
+							'--project-id',
+							project.projectId,
+							'--private-key',
+							Buffer.from(privateKeyPEM).toString('base64'),
+							'--health-check',
+						],
+						{
+							cwd: rootDir,
+							stdout: 'pipe',
+							stderr: 'pipe',
+							detached: false,
+						}
+					);
 
-				// Log gravity output and detect heartbeat port
-				(async () => {
-					try {
-						if (gravityProcess?.stdout) {
-							for await (const chunk of gravityProcess.stdout) {
-								const text = new TextDecoder().decode(chunk);
-								const trimmed = text.trim();
-
-								const match = trimmed.match(/^HEARTBEAT_PORT=(\d+)$/m);
-								if (match?.[1]) {
-									const heartbeatPort = parseInt(match[1], 10);
-									logger.debug('Gravity heartbeat port: %d', heartbeatPort);
-
-									if (!gravityHeartbeatInterval) {
-										const sendHeartbeat = async () => {
-											try {
-												await fetch(`http://127.0.0.1:${heartbeatPort}/heartbeat`, {
-													method: 'POST',
-													signal: AbortSignal.timeout(2000),
-												});
-											} catch {
-												// Ignore heartbeat failures
-											}
-										};
-										sendHeartbeat();
-										gravityHeartbeatInterval = setInterval(sendHeartbeat, 5000);
+					const gravityPid = (gravityProcess as { pid?: number }).pid;
+					if (gravityPid) {
+						await devLock.registerChild({
+							pid: gravityPid,
+							type: 'gravity',
+							description: 'Gravity public URL tunnel',
+						});
+
+						// Register with process manager
+						procManager.registerProcess({
+							id: 'gravity',
+							process: gravityProcess,
+							description: 'Gravity public URL tunnel',
+							critical: false,
+						});
+					}
+
+					// Log gravity output and detect heartbeat port
+					(async () => {
+						try {
+							if (gravityProcess?.stdout) {
+								for await (const chunk of gravityProcess.stdout) {
+									const text = new TextDecoder().decode(chunk);
+									const trimmed = text.trim();
+
+									const match = trimmed.match(/^HEARTBEAT_PORT=(\d+)$/m);
+									if (match?.[1]) {
+										const heartbeatPort = parseInt(match[1], 10);
+										logger.debug('Gravity heartbeat port: %d', heartbeatPort);
+
+										if (!gravityHeartbeatInterval) {
+											const sendHeartbeat = async () => {
+												try {
+													await fetch(`http://127.0.0.1:${heartbeatPort}/heartbeat`, {
+														method: 'POST',
+														signal: AbortSignal.timeout(2000),
+													});
+												} catch {
+													// Ignore heartbeat failures
+												}
+											};
+											sendHeartbeat();
+											gravityHeartbeatInterval = setInterval(sendHeartbeat, 5000);
+										}
+									} else if (trimmed) {
+										logger.debug('[gravity] %s', trimmed);
 									}
-								} else if (trimmed) {
-									logger.debug('[gravity] %s', trimmed);
 								}
 							}
+						} catch (err) {
+							logger.error('Error reading gravity stdout: %s', err);
 						}
-					} catch (err) {
-						logger.error('Error reading gravity stdout: %s', err);
-					}
-				})();
+					})();
 
-				(async () => {
-					try {
-						if (gravityProcess?.stderr) {
-							for await (const chunk of gravityProcess.stderr) {
-								logger.warn('[gravity] %s', new TextDecoder().decode(chunk).trim());
+					(async () => {
+						try {
+							if (gravityProcess?.stderr) {
+								for await (const chunk of gravityProcess.stderr) {
+									logger.warn('[gravity] %s', new TextDecoder().decode(chunk).trim());
+								}
 							}
+						} catch (err) {
+							logger.error('Error reading gravity stderr: %s', err);
 						}
-					} catch (err) {
-						logger.error('Error reading gravity stderr: %s', err);
-					}
-				})();
+					})();
+				} catch (error) {
+					tui.error(`Failed to start gravity tunnel: ${error}`);
+					await cleanup(true, 1, true);
+					return;
+				}
 			}
 
 			// ================================================================

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

@@ -0,0 +1,261 @@
+/**
+ * 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);
+	}
+}

package/src/cmd/git/account/remove.ts

@@ -22,6 +22,7 @@ const RemoveResponseSchema = z.object({
 
 export const removeSubcommand = createSubcommand({
 	name: 'remove',
+	aliases: ['rm', 'del', 'delete', 'terminate'],
 	description: 'Remove a GitHub App installation',
 	tags: ['mutating', 'destructive', 'slow'],
 	idempotent: false,

package/src/cmd/profile/delete.ts

@@ -11,7 +11,7 @@ export const deleteCommand = createSubcommand({
 	description: 'Delete a configuration profile',
 	tags: ['destructive', 'deletes-resource', 'fast'],
 	idempotent: false,
-	aliases: ['remove', 'rm', 'del'],
+	aliases: ['rm', 'del', 'remove', 'terminate'],
 	examples: [
 		{ command: getCommand('profile delete staging'), description: 'Delete item' },
 		{