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

package/src/cmd/build/vite/bun-dev-server.ts

@@ -7,10 +7,15 @@
  *
  * The user's app.ts exports the result of createApp() which includes `fetch`
  * and `port` properties that Bun uses to manage the server lifecycle.
+ *
+ * Key requirements for bun --hot:
+ * - app.ts MUST have `export default` with { fetch, port } properties
+ * - Without export default, Bun runs the code but never starts an HTTP server
  */
 
 import type { Logger } from '../../../types';
 import { getAgentEnv } from '../../../agent-detection';
+import { createServer as createNetServer } from 'node:net';
 
 export interface BunDevServerOptions {
 	rootDir: string;
@@ -26,6 +31,264 @@ export interface BunDevServerResult {
 	bunServerPort: number;
 }
 
+/**
+ * Check if a port is available for binding.
+ * Returns true if the port is free, false if in use.
+ */
+function isPortAvailable(port: number, host: string = '127.0.0.1'): Promise<boolean> {
+	return new Promise((resolve) => {
+		const server = createNetServer();
+		server.once('error', () => {
+			resolve(false);
+		});
+		server.listen(port, host, () => {
+			server.close(() => {
+				resolve(true);
+			});
+		});
+	});
+}
+
+/**
+ * Kill any process listening on the specified port.
+ * Uses lsof on Unix systems to find and kill the process.
+ */
+async function killProcessOnPort(
+	port: number,
+	logger: { debug: (msg: string, ...args: unknown[]) => void }
+): Promise<boolean> {
+	if (process.platform === 'win32') {
+		// Windows: use netstat to find PID, then taskkill
+		// This is more complex and less reliable, skip for now
+		return false;
+	}
+
+	try {
+		// Find PIDs listening on the port
+		const result = Bun.spawnSync(['lsof', '-t', '-i', `:${port}`], {
+			stdout: 'pipe',
+			stderr: 'ignore',
+		});
+
+		if (result.exitCode !== 0 || !result.stdout) {
+			return false;
+		}
+
+		const pids = new TextDecoder()
+			.decode(result.stdout)
+			.trim()
+			.split('\n')
+			.filter((line) => line && /^\d+$/.test(line));
+
+		if (pids.length === 0) {
+			return false;
+		}
+
+		// Kill each process
+		for (const pid of pids) {
+			try {
+				// Use SIGKILL to ensure cleanup
+				const killResult = Bun.spawnSync(['kill', '-9', pid], {
+					stdout: 'ignore',
+					stderr: 'ignore',
+				});
+				if (killResult.exitCode === 0) {
+					logger.debug('Killed orphan process %s on port %d', pid, port);
+				}
+			} catch {
+				// Ignore kill errors
+			}
+		}
+
+		// Brief pause to let the port be released
+		await new Promise((resolve) => setTimeout(resolve, 100));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Ensure the port is available, cleaning up any orphan processes if needed.
+ */
+async function ensurePortAvailable(
+	port: number,
+	logger: { debug: (msg: string, ...args: unknown[]) => void }
+): Promise<void> {
+	const available = await isPortAvailable(port);
+	if (available) {
+		return;
+	}
+
+	logger.debug('Port %d is in use, attempting to clean up orphan process...', port);
+
+	const killed = await killProcessOnPort(port, logger);
+	if (killed) {
+		// Verify the port is now free
+		const nowAvailable = await isPortAvailable(port);
+		if (!nowAvailable) {
+			throw new Error(
+				`Port ${port} is still in use after cleanup. Another process may be holding it.\n` +
+					`Run 'lsof -i :${port}' to identify the process.`
+			);
+		}
+		logger.debug('Port %d is now available', port);
+	} else {
+		throw new Error(
+			`Port ${port} is already in use.\n` +
+				`Run 'lsof -i :${port}' to identify the process, or kill it manually.`
+		);
+	}
+}
+
+/**
+ * Validation result for app.ts entry point.
+ */
+interface AppValidationResult {
+	/** Whether app.ts has a default export */
+	hasDefaultExport: boolean;
+	/** Whether app.ts calls createApp() */
+	hasCreateApp: boolean;
+	/** Whether it's the v1 pattern (destructuring without export) */
+	isV1Pattern: boolean;
+	/** Any validation hints to show */
+	hints: string[];
+}
+
+/**
+ * Validate app.ts for common issues that prevent Bun --hot from starting.
+ *
+ * Bun --hot requires `export default { fetch, port }` to start a server.
+ * Common mistakes:
+ * - No `export default` (v1 pattern: destructuring result without exporting)
+ * - Calling createApp() but not exporting it
+ *
+ * @internal Exported for testing only
+ */
+export async function validateAppTs(appPath: string): Promise<AppValidationResult> {
+	const result: AppValidationResult = {
+		hasDefaultExport: false,
+		hasCreateApp: false,
+		isV1Pattern: false,
+		hints: [],
+	};
+
+	const file = Bun.file(appPath);
+	if (!(await file.exists())) {
+		return result;
+	}
+
+	const content = await file.text();
+
+	// Strip comments to avoid false positives from commented-out code
+	// Simple approach: remove single-line and multi-line comments
+	const codeWithoutComments = content
+		.replace(/\/\/.*$/gm, '') // Single-line comments
+		.replace(/\/\*[\s\S]*?\*\//g, ''); // Multi-line comments
+
+	// Check for default export patterns (only in actual code, not comments)
+	// Matches: export default createApp(...), export default await createApp(...),
+	// export default { fetch, port }, const { ... } = await createApp(...) then export default result
+	result.hasDefaultExport = /\bexport\s+default\b/.test(codeWithoutComments);
+
+	// Check for createApp call
+	result.hasCreateApp = /\bcreateApp\s*\(/.test(content);
+
+	// Detect v1 pattern: destructuring createApp result without export default
+	// e.g., const { server, logger } = await createApp({...});
+	const hasDestructuring = /const\s*\{[^}]*\}\s*=\s*(?:await\s+)?createApp/.test(content);
+	if (hasDestructuring && !result.hasDefaultExport) {
+		result.isV1Pattern = true;
+		result.hints.push(
+			'app.ts calls createApp() but does not export it. Bun --hot requires `export default` to start a server.',
+			'',
+			'Fix: Change your app.ts to export the createApp() result:',
+			'',
+			'  import { createApp } from "@agentuity/runtime";',
+			'  import agents from "@agent/index";',
+			'',
+			'  export default createApp({',
+			'    agents,',
+			'    router: { path: "/api", router: api },',
+			'  });',
+			'',
+			'Or if you need the logger:',
+			'',
+			'  const app = await createApp({ agents });',
+			'  app.logger.debug("Running %s", app.server.url);',
+			'  export default app;'
+		);
+	}
+
+	// Check for missing createApp entirely
+	if (!result.hasCreateApp && !content.includes('Bun.serve')) {
+		result.hints.push(
+			'app.ts does not call createApp(). This is required for Agentuity apps.',
+			'',
+			'Example:',
+			'',
+			'  import { createApp } from "@agentuity/runtime";',
+			'  export default createApp({ agents });'
+		);
+	}
+
+	return result;
+}
+
+/**
+ * Build a detailed error message with validation hints and captured output.
+ *
+ * @internal Exported for testing only
+ */
+export function buildStartupErrorMessage(
+	port: number,
+	timeoutMs: number,
+	stderr: string,
+	validation: AppValidationResult
+): string {
+	const lines: string[] = [];
+
+	lines.push(`Bun server failed to start on port ${port} after ${timeoutMs}ms`);
+	lines.push('');
+
+	// Show captured stderr if any
+	if (stderr.trim()) {
+		lines.push('Bun output:');
+		lines.push('');
+		// Indent stderr lines for readability
+		for (const line of stderr.trim().split('\n').slice(0, 20)) {
+			lines.push(`  ${line}`);
+		}
+		if (stderr.split('\n').length > 20) {
+			lines.push('  ... (truncated)');
+		}
+		lines.push('');
+	}
+
+	// Show validation hints
+	if (validation.hints.length > 0) {
+		lines.push('Possible issue:');
+		lines.push('');
+		for (const hint of validation.hints) {
+			lines.push(`  ${hint}`);
+		}
+		lines.push('');
+	}
+
+	// Generic troubleshooting if no specific hints
+	if (validation.hints.length === 0) {
+		lines.push('Troubleshooting:');
+		lines.push('');
+		lines.push('  1. Check app.ts exports `export default createApp({...})`');
+		lines.push('  2. Check for TypeScript/syntax errors in your code');
+		lines.push(`  3. Check if port ${port} is already in use: lsof -i :${port}`);
+		lines.push('  4. Try running manually: bun run --hot app.ts');
+		lines.push('');
+	}
+
+	return lines.join('\n');
+}
+
 /**
  * Start Bun dev server with --hot (Vite asset server must already be running).
  *
@@ -45,6 +308,20 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 		throw new Error(`App entry not found at ${appPath}.`);
 	}
 
+	// Pre-validate app.ts for common issues
+	const validation = await validateAppTs(appPath);
+	if (validation.isV1Pattern) {
+		logger.warn('');
+		logger.warn('⚠️  app.ts may have a v1-style pattern that prevents Bun --hot from starting.');
+		for (const hint of validation.hints) {
+			logger.warn('   %s', hint);
+		}
+		logger.warn('');
+	}
+
+	// Ensure the port is available, cleaning up any orphan processes
+	await ensurePortAvailable(port, logger);
+
 	process.env.PORT = String(port);
 
 	const args: string[] = ['bun'];
@@ -66,10 +343,34 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 
 	logger.debug('Spawning bun subprocess: %s', args.join(' '));
 
+	// Capture stderr for error reporting while still showing it in real-time
+	const stderrChunks: string[] = [];
+	const stdoutChunks: string[] = [];
+
+	// Helper to read a stream, capture output, and forward to parent
+	const captureStream = async (
+		stream: ReadableStream<Uint8Array>,
+		chunks: string[],
+		output: typeof process.stdout | typeof process.stderr
+	) => {
+		const reader = stream.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				const str = new TextDecoder().decode(value);
+				chunks.push(str);
+				output.write(value); // Forward to parent for real-time visibility
+			}
+		} catch {
+			// Stream may be closed unexpectedly when process exits
+		}
+	};
+
 	const bunProcess = Bun.spawn(args, {
 		cwd: rootDir,
-		stdout: 'inherit',
-		stderr: 'inherit',
+		stdout: 'pipe',
+		stderr: 'pipe',
 		env: {
 			...process.env,
 			...getAgentEnv(),
@@ -77,17 +378,29 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 		},
 	});
 
+	// Start capturing streams in the background (don't await, we need to check server readiness)
+	if (bunProcess.stdout) {
+		captureStream(bunProcess.stdout, stdoutChunks, process.stdout).catch(() => {});
+	}
+	if (bunProcess.stderr) {
+		captureStream(bunProcess.stderr, stderrChunks, process.stderr).catch(() => {});
+	}
+
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	(globalThis as any).__AGENTUITY_BUN_SUBPROCESS__ = bunProcess;
 
 	// Wait for server to start listening
 	const maxRetries = 50;
 	const retryDelay = 100;
+	const timeoutMs = maxRetries * retryDelay;
 	let serverReady = false;
 
 	for (let i = 0; i < maxRetries; i++) {
 		if (bunProcess.exitCode !== null) {
-			throw new Error(`Bun subprocess exited with code ${bunProcess.exitCode} during startup`);
+			const stderr = stderrChunks.join('');
+			throw new Error(
+				`Bun subprocess exited with code ${bunProcess.exitCode} during startup\n\n${stderr}`
+			);
 		}
 
 		try {
@@ -111,9 +424,9 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 		}
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		(globalThis as any).__AGENTUITY_BUN_SUBPROCESS__ = undefined;
-		throw new Error(
-			`Bun server failed to start on port ${port} after ${maxRetries * retryDelay}ms`
-		);
+
+		const stderr = stderrChunks.join('');
+		throw new Error(buildStartupErrorMessage(port, timeoutMs, stderr, validation));
 	}
 
 	logger.debug(`Bun dev server started on http://127.0.0.1:${port} (--hot mode)`);

package/src/cmd/build/vite/config-loader.ts

@@ -1,108 +1,76 @@
 /**
- * Config loader for agentuity.config.ts
+ * Config loader for v2
+ *
+ * In v2, all runtime config (analytics, workbench) goes in createApp().
+ * Vite-specific config (plugins, define, render, bundle) goes in vite.config.ts.
+ *
+ * Runtime config values are extracted from app.ts via app-config-extractor.
  */
 
-import { join } from 'node:path';
 import type { Logger } from '../../../types';
-import type { AgentuityConfig } from '../../../types';
+import { extractAppConfig, type ExtractedAppConfig } from '../app-config-extractor';
 
 /**
- * Load agentuity.config.ts from the project root
- * Returns null if the file doesn't exist or fails to load
+ * Load runtime config from createApp() in app.ts (v2 approach).
+ *
+ * This is the only way to get analytics/workbench config in v2.
+ * The CLI reads these values directly from the user's createApp() call.
  */
-export async function loadAgentuityConfig(
+export async function loadRuntimeConfig(
 	rootDir: string,
 	logger: Logger
-): Promise<AgentuityConfig | null> {
-	const configPath = join(rootDir, 'agentuity.config.ts');
-
-	if (!(await Bun.file(configPath).exists())) {
-		logger.trace('No agentuity.config.ts found');
-		return null;
-	}
-
-	try {
-		const config = await import(configPath);
-		const userConfig = config.default as AgentuityConfig | undefined;
-
-		if (!userConfig) {
-			logger.warn('agentuity.config.ts does not export a default configuration');
-			return null;
-		}
-
-		logger.trace('Loaded agentuity.config.ts');
-		return userConfig;
-	} catch (error) {
-		logger.warn('Failed to load agentuity.config.ts:', error);
-		return null;
-	}
+): Promise<ExtractedAppConfig> {
+	return extractAppConfig(rootDir, logger);
 }
 
 /**
- * Get workbench configuration with defaults
- * NOTE: Workbench is only enabled at runtime in dev mode, but we need to know
- * if it's configured at build time so we can generate the correct code.
+ * Get workbench configuration with defaults.
  *
- * Presence of workbench config implicitly enables it (no explicit 'enabled' flag needed)
- * Missing workbench config implicitly disables it
+ * In v2, workbench config is extracted from createApp() in app.ts.
  */
 export function getWorkbenchConfig(
-	config: AgentuityConfig | null,
-	dev: boolean
+	dev: boolean,
+	runtimeConfig?: ExtractedAppConfig
 ): {
 	configured: boolean;
 	enabled: boolean;
 	route: string;
 	headers: Record<string, string>;
 } {
-	const configured = config?.workbench !== undefined;
+	const workbenchFromRuntime = runtimeConfig?.workbench;
 
 	// Workbench is enabled if:
 	// 1. In dev mode (never in production)
-	// 2. Config has a workbench object (presence implies enablement)
-	const enabled = dev && configured;
+	// 2. Workbench is configured in createApp()
+	const hasWorkbench = workbenchFromRuntime !== undefined;
+	const configured = hasWorkbench;
+	const enabled = dev && hasWorkbench;
 
-	const workbench = config?.workbench || {};
+	// Extract values from createApp()
+	let route = '/workbench';
+	let headers: Record<string, string> = {};
+
+	if (workbenchFromRuntime !== undefined) {
+		if (typeof workbenchFromRuntime === 'string') {
+			route = workbenchFromRuntime;
+		} else if (typeof workbenchFromRuntime === 'object' && workbenchFromRuntime !== null) {
+			if ('route' in workbenchFromRuntime && typeof workbenchFromRuntime.route === 'string') {
+				route = workbenchFromRuntime.route;
+			}
+			if (
+				'headers' in workbenchFromRuntime &&
+				typeof workbenchFromRuntime.headers === 'object'
+			) {
+				headers = workbenchFromRuntime.headers as Record<string, string>;
+			}
+		}
+		// boolean true uses defaults
+	}
 
 	return {
 		configured,
 		enabled,
-		route: workbench.route ?? '/workbench',
-		headers: workbench.headers ?? {},
+		route,
+		headers,
 	};
 }
-
-/**
- * Known Vite framework plugin name prefixes.
- * Each framework's Vite plugin registers one or more plugins whose names
- * start with these prefixes. We match against these to detect whether the
- * user has already configured a framework plugin in their agentuity.config.ts.
- */
-const FRAMEWORK_PLUGIN_PREFIXES = [
-	'vite:react', // @vitejs/plugin-react  (vite:react-babel, vite:react-refresh, …)
-	'vite:preact', // @preact/preset-vite
-	'vite-plugin-svelte', // @sveltejs/vite-plugin-svelte
-	'vite:vue', // @vitejs/plugin-vue      (vite:vue, vite:vue-jsx)
-	'vite-plugin-solid', // vite-plugin-solid
-	'solid', // vite-plugin-solid also uses plain "solid"
-];
-
-/**
- * Check if the user's plugins include any known UI-framework Vite plugin
- * (React, Svelte, Vue, Solid, Preact, …).
- *
- * Detection is name-based: Vite plugins expose a `name` property and every
- * major framework plugin uses a predictable prefix. This avoids dynamically
- * importing every possible framework just to compare names.
- */
-export function hasFrameworkPlugin(userPlugins: import('vite').PluginOption[]): boolean {
-	const flat = (userPlugins as unknown[]).flat(Infinity).filter(Boolean);
-	return flat.some(
-		(p: unknown) =>
-			p &&
-			typeof p === 'object' &&
-			'name' in p &&
-			typeof (p as { name: unknown }).name === 'string' &&
-			FRAMEWORK_PLUGIN_PREFIXES.some((prefix) => (p as { name: string }).name.startsWith(prefix))
-	);
-}

package/src/cmd/build/vite/static-renderer.ts

@@ -17,7 +17,6 @@ import { join } from 'node:path';
 import { createRequire } from 'node:module';
 import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
 import type { Logger } from '../../../types';
-import { hasFrameworkPlugin } from './config-loader';
 
 /** Minimal shape of a TanStack Router route tree node. */
 interface RouteTreeNode {
@@ -75,8 +74,6 @@ function extractRoutePaths(node: RouteTreeNode): string[] {
 export interface StaticRenderOptions {
 	rootDir: string;
 	logger: Logger;
-	/** User plugins from agentuity.config.ts */
-	userPlugins: import('vite').PluginOption[];
 }
 
 export interface StaticRenderResult {
@@ -85,7 +82,7 @@ export interface StaticRenderResult {
 }
 
 export async function runStaticRender(options: StaticRenderOptions): Promise<StaticRenderResult> {
-	const { rootDir, logger, userPlugins } = options;
+	const { rootDir, logger } = options;
 	const started = Date.now();
 
 	const clientDir = join(rootDir, '.agentuity/client');
@@ -109,33 +106,52 @@ export async function runStaticRender(options: StaticRenderOptions): Promise<Sta
 		);
 	}
 
+	const isViteDebug =
+		process.env.AGENTUITY_VITE_DEBUG === '1' || process.env.AGENTUITY_VITE_DEBUG === 'true';
+	if (isViteDebug) {
+		logger.debug('Vite debug logging enabled via AGENTUITY_VITE_DEBUG');
+		const existing = process.env.DEBUG || '';
+		if (!existing.includes('vite:')) {
+			process.env.DEBUG = existing ? `${existing},vite:*` : 'vite:*';
+		}
+	}
+
 	// Step 1: Vite SSR build
 	// This resolves import.meta.glob, MDX imports, and other Vite-specific APIs
 	logger.debug('Running Vite SSR build for static rendering...');
 
 	const projectRequire = createRequire(join(rootDir, 'package.json'));
 	let vitePath = 'vite';
-	let reactPluginPath = '@vitejs/plugin-react';
 	try {
 		vitePath = projectRequire.resolve('vite');
-		reactPluginPath = projectRequire.resolve('@vitejs/plugin-react');
 	} catch {
 		// Use CLI's bundled version
 	}
 
-	const { build: viteBuild } = await import(vitePath);
-	const reactModule = await import(reactPluginPath);
-	const react = reactModule.default;
+	const { build: viteBuild, loadConfigFromFile, mergeConfig } = await import(vitePath);
+
+	// Load vite.config.ts if it exists (v2 approach)
+	let userConfig: import('vite').InlineConfig = {};
+	const viteConfigPath = join(rootDir, 'vite.config.ts');
 
-	// Build plugin list: auto-add React if no framework plugin present
-	const plugins = [...(userPlugins || [])];
-	if (plugins.length === 0 || !hasFrameworkPlugin(plugins)) {
-		plugins.unshift(react());
+	if (await Bun.file(viteConfigPath).exists()) {
+		try {
+			const loaded = await loadConfigFromFile(
+				{ command: 'build', mode: 'production' },
+				viteConfigPath
+			);
+			if (loaded?.config) {
+				userConfig = loaded.config as import('vite').InlineConfig;
+				logger.debug('Loaded vite.config.ts for SSR build');
+			}
+		} catch (error) {
+			logger.warn('Failed to load vite.config.ts: %s', error);
+		}
 	}
 
-	await viteBuild({
+	// Merge user config with SSR build settings
+	const ssrConfig = mergeConfig(userConfig, {
 		root: rootDir,
-		plugins,
 		build: {
 			ssr: entryServerPath,
 			outDir: ssrOutDir,
@@ -150,9 +166,11 @@ export async function runStaticRender(options: StaticRenderOptions): Promise<Sta
 			// resolved at build time. Node built-ins are still externalized.
 			noExternal: true,
 		},
-		logLevel: 'warn',
+		logLevel: isViteDebug ? 'info' : 'warn',
 	});
 
+	await viteBuild(ssrConfig);
+
 	// Steps 2–4: wrapped in try-finally so SSR artifacts are always cleaned up,
 	// even if an exception is thrown during module import, validation, or rendering.
 	let routeCount = 0;