@agentuity/cli 1.0.47 → 2.0.0-beta.0

package/src/cmd/build/vite/vite-asset-server-config.ts

@@ -1,20 +1,163 @@
 /**
- * Vite Asset Server Configuration
+ * Vite Dev Server Configuration
  *
- * Minimal Vite config for serving frontend assets with HMR only.
- * Does NOT handle API routes, workbench, or WebSocket - that's the Bun server's job.
+ * Vite is the primary dev server — serves frontend assets natively and proxies
+ * API/WebSocket requests to the Bun backend server.
  */
 
 import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import type { InlineConfig } from 'vite';
+import type { InlineConfig, Plugin } from 'vite';
 import type { Logger } from '../../../types';
 
 export interface GenerateAssetServerConfigOptions {
 	rootDir: string;
 	logger: Logger;
 	workbenchPath?: string;
-	port: number; // The port Vite will run on (for HMR client configuration)
+	port: number; // The port Vite will listen on (user-facing)
+	backendPort: number; // The port Bun backend is running on (internal)
+	/** User-defined route mount paths from createApp({ router }) (e.g., ['/api', '/v1']) */
+	routePaths?: string[];
+}
+
+/**
+ * Vite plugin that injects analytics scripts in dev mode.
+ *
+ * In production the beacon plugin handles this at build time. In dev mode
+ * the analytics config + session + beacon scripts are served by the Bun
+ * backend at /_agentuity/webanalytics/* routes, but we need to inject the
+ * `<script>` tags into the HTML so the browser loads them.
+ */
+function devAnalyticsPlugin(): Plugin {
+	return {
+		name: 'agentuity:dev-analytics',
+		transformIndexHtml: {
+			order: 'pre',
+			handler(html) {
+				// Default analytics config — matches resolveAnalyticsConfig(undefined) in runtime
+				const config = {
+					enabled: true,
+					trackClicks: true,
+					trackScroll: true,
+					trackOutboundLinks: true,
+					trackForms: false,
+					trackWebVitals: true,
+					trackErrors: true,
+					trackSPANavigation: true,
+					isDevmode: true,
+				};
+
+				const injection =
+					`<script>window.__AGENTUITY_ANALYTICS__=${JSON.stringify(config)};</script>` +
+					'<script src="/_agentuity/webanalytics/session.js" async></script>' +
+					'<script src="/_agentuity/webanalytics/analytics.js"></script>';
+
+				if (html.includes('</head>')) {
+					return html.replace('</head>', `${injection}</head>`);
+				}
+				return html;
+			},
+		},
+	};
+}
+
+/**
+ * Vite plugin that serves src/web/index.html as the SPA fallback.
+ *
+ * Vite's built-in SPA fallback only serves index.html from the project root.
+ * Since Agentuity apps keep their HTML entry at src/web/index.html, we need
+ * this plugin to rewrite the URL so Vite's built-in transform pipeline
+ * (including React Fast Refresh injection) processes it correctly.
+ */
+function spaFallbackPlugin(rootDir: string, routePaths: string[], workbenchPath?: string): Plugin {
+	const htmlPath = join(rootDir, 'src', 'web', 'index.html');
+	const hasHtml = existsSync(htmlPath);
+
+	return {
+		name: 'agentuity:spa-fallback',
+		configureServer(server) {
+			if (!hasHtml) return;
+
+			server.middlewares.use(async (req, res, next) => {
+				// Only handle GET/HEAD navigation requests
+				if (req.method !== 'GET' && req.method !== 'HEAD') return next();
+
+				const url = req.url || '/';
+				const pathname = url.split('?')[0] || '/';
+				const accept = req.headers.accept || '';
+				const secFetchDest = req.headers['sec-fetch-dest'] || '';
+
+				// For robustness, treat unknown GET/HEAD routes as potential SPA navigations.
+				// We still avoid intercepting assets/backend paths via the filters below.
+				// (This also makes non-browser readiness probes like fetch('/streams') work.)
+				const isDocumentRequest = secFetchDest === 'document' || accept.includes('text/html');
+
+				// Skip file requests (have an extension)
+				if (pathname !== '/' && /\.[a-zA-Z0-9]+$/.test(pathname)) return next();
+
+				// For non-document requests, only allow root path fallback.
+				// (e.g. don't turn module/script fetches into HTML accidentally)
+				if (!isDocumentRequest && pathname === '/') {
+					// allow root fallback for simple probes
+				}
+
+				// Skip Vite/module/internal asset paths
+				if (
+					pathname.startsWith('/@vite') ||
+					pathname.startsWith('/@react-refresh') ||
+					pathname.startsWith('/@id/') ||
+					pathname.startsWith('/@fs/') ||
+					pathname.startsWith('/node_modules/') ||
+					pathname.startsWith('/src/') ||
+					(pathname.startsWith('/@') && !pathname.startsWith('/_agentuity'))
+				) {
+					return next();
+				}
+
+				// Skip paths that are proxied to the Bun backend
+				if (
+					pathname.startsWith('/_agentuity') ||
+					pathname.startsWith('/_health') ||
+					pathname.startsWith('/_idle')
+				) {
+					return next();
+				}
+				// Skip workbench path (served by Bun)
+				if (
+					workbenchPath &&
+					(pathname === workbenchPath || pathname.startsWith(workbenchPath + '/'))
+				) {
+					return next();
+				}
+				for (const rp of routePaths) {
+					if (pathname === rp || pathname.startsWith(rp + '/')) return next();
+				}
+
+				// If this isn't clearly a document navigation, still allow SPA fallback
+				// for extensionless client-side routes like /streams, /rpc, /webrtc.
+				// We already excluded backend paths and asset/module paths above.
+
+				try {
+					let html = await Bun.file(htmlPath).text();
+					// Match old devHtmlHandler behavior from the generated Bun entry:
+					// rewrite relative paths so the app works from / and client-side routes.
+					html = html
+						.replace(/src="\.\//g, 'src="/src/web/')
+						.replace(/href="\.\//g, 'href="/src/web/');
+
+					// Let Vite inject HMR client, React refresh preamble, etc.
+					html = await server.transformIndexHtml(url, html, req.originalUrl);
+
+					res.statusCode = 200;
+					res.setHeader('Content-Type', 'text/html; charset=utf-8');
+					res.end(html);
+				} catch (error) {
+					next(error as Error);
+				}
+			});
+		},
+	};
 }
 
 /**
@@ -23,7 +166,7 @@ export interface GenerateAssetServerConfigOptions {
 export async function generateAssetServerConfig(
 	options: GenerateAssetServerConfigOptions
 ): Promise<InlineConfig> {
-	const { rootDir, logger, workbenchPath, port } = options;
+	const { rootDir, logger, workbenchPath, port, backendPort, routePaths = ['/api'] } = options;
 
 	// Load custom user config for define values and plugins
 	const { loadAgentuityConfig } = await import('./config-loader');
@@ -90,27 +233,56 @@ export async function generateAssetServerConfig(
 		envPrefix: ['VITE_', 'AGENTUITY_PUBLIC_', 'PUBLIC_'],
 
 		server: {
-			// Use the port we selected
+			// Vite is the primary dev server — listens on the user-facing port
 			port,
 			strictPort: true, // Port is pre-verified as available by findAvailablePort()
 			host: '127.0.0.1',
 
-			// CORS headers to allow Bun server on port 3500 to proxy requests
-			cors: {
-				origin: 'http://127.0.0.1:3500',
-				credentials: true,
+			// Proxy backend routes to Bun server (HTTP only).
+			// WebSocket upgrades are handled by the front-door TCP proxy (ws-proxy.ts)
+			// which routes them directly to the Bun backend, bypassing Vite entirely.
+			// This avoids Bun's broken node:http upgrade socket implementation.
+			proxy: {
+				// User-defined route mounts (from createApp({ router }))
+				...Object.fromEntries(
+					routePaths.map((routePath) => [
+						routePath,
+						{
+							target: `http://127.0.0.1:${backendPort}`,
+							changeOrigin: true,
+						},
+					])
+				),
+				// Agentuity system routes (workbench API, health, analytics, etc.)
+				'/_agentuity': {
+					target: `http://127.0.0.1:${backendPort}`,
+					changeOrigin: true,
+				},
+				// Workbench UI route (served by Bun, references /@fs/* paths handled by Vite)
+				...(workbenchPath
+					? {
+							[workbenchPath]: {
+								target: `http://127.0.0.1:${backendPort}`,
+								changeOrigin: true,
+							},
+						}
+					: {}),
+				// Legacy health check routes
+				'/_health': {
+					target: `http://127.0.0.1:${backendPort}`,
+					changeOrigin: true,
+				},
+				'/_idle': {
+					target: `http://127.0.0.1:${backendPort}`,
+					changeOrigin: true,
+				},
 			},
 
-			// HMR configuration for development with tunnel support (*.agentuity.live)
-			// Do NOT set host/protocol - let Vite auto-detect from page origin
-			// This allows HMR to work both locally and through the Gravity tunnel
-			// The Bun server proxies /__vite_hmr WebSocket connections to Vite
-			hmr: {
-				// Use a dedicated path for HMR WebSocket to enable proxying
-				path: '/__vite_hmr',
-			},
+			// HMR works natively — Vite is the primary server, no proxy needed
+			// Auto-detect host/protocol from page origin for tunnel support
+			hmr: true,
 
-			// Don't open browser - Bun server will be the entry point
+			// Don't open browser automatically
 			open: false,
 		},
 
@@ -159,6 +331,10 @@ export async function generateAssetServerConfig(
 				browserEnvPlugin(),
 				// Warn about incorrect public asset paths in dev mode
 				publicAssetPathPlugin({ warnInDev: true }),
+				// Inject analytics scripts in dev HTML
+				devAnalyticsPlugin(),
+				// SPA fallback: serve src/web/index.html for navigation requests
+				spaFallbackPlugin(rootDir, routePaths, workbenchPath),
 			];
 		})(),
 

package/src/cmd/build/vite/vite-asset-server.ts

@@ -1,8 +1,9 @@
 /**
- * Vite Asset Server
+ * Vite Dev Server (Primary)
  *
- * Starts a minimal Vite dev server for frontend asset transformation and HMR only.
- * Does NOT handle API routes or WebSocket - the Bun server proxies to this.
+ * Starts Vite as the primary dev server on the user-facing port.
+ * Serves frontend assets natively and proxies API/WebSocket requests
+ * to the Bun backend server.
  */
 
 import { join } from 'node:path';
@@ -21,6 +22,10 @@ export interface StartViteAssetServerOptions {
 	rootDir: string;
 	logger: Logger;
 	workbenchPath?: string;
+	port?: number; // Preferred user-facing port (default: 3500)
+	backendPort: number; // Port of the Bun backend server
+	/** User-defined route mount paths from createApp({ router }) */
+	routePaths?: string[];
 }
 
 /**
@@ -68,27 +73,34 @@ async function findAvailablePort(
 export async function startViteAssetServer(
 	options: StartViteAssetServerOptions
 ): Promise<ViteAssetServerResult> {
-	const { rootDir, logger, workbenchPath } = options;
+	const {
+		rootDir,
+		logger,
+		workbenchPath,
+		port: preferredPort = 3500,
+		backendPort,
+		routePaths,
+	} = options;
 
-	logger.debug('Starting Vite asset server (HMR only)...');
+	logger.debug('Starting Vite dev server (primary, proxying backend on port %d)...', backendPort);
 
-	// Find an available port before starting Vite
-	// This avoids relying on Vite's strictPort:false fallback which can fail
-	const preferredPort = 5173;
+	// Find an available port for the user-facing Vite server
 	const availablePort = await findAvailablePort(preferredPort, '127.0.0.1');
 
 	if (availablePort !== preferredPort) {
 		logger.info(
-			`Port ${preferredPort} is in use, using port ${availablePort} for Vite asset server`
+			`Port ${preferredPort} is in use, using port ${availablePort} for Vite dev server`
 		);
 	}
 
-	// Generate minimal config with the available port
+	// Generate config with proxy to Bun backend
 	const config = await generateAssetServerConfig({
 		rootDir,
 		logger,
 		workbenchPath,
 		port: availablePort,
+		backendPort,
+		routePaths,
 	});
 
 	// Dynamically import vite from the project's node_modules
@@ -130,11 +142,9 @@ export async function startViteAssetServer(
 	// Port was pre-verified and strictPort:true ensures Vite uses exactly this port
 	const actualPort = availablePort;
 
-	logger.info(`Vite asset server running on port ${actualPort}`);
-	logger.debug(`Asset server will handle: HMR, React transformation, source maps`);
-	logger.debug(
-		`HMR WebSocket configured at /__vite_hmr (proxied through Bun server for tunnel support)`
-	);
+	logger.debug(`Vite dev server running on port ${actualPort} (primary)`);
+	logger.debug(`Frontend: HMR, React transformation, source maps (native)`);
+	logger.debug(`Backend: proxying to Bun on port ${backendPort}`);
 
 	return { server, port: actualPort };
 }

package/src/cmd/build/vite/vite-builder.ts

@@ -74,25 +74,7 @@ export interface ViteBuildOptions {
  * Uses inline Vite config (customizable via agentuity.config.ts)
  */
 export async function runViteBuild(options: ViteBuildOptions): Promise<void> {
-	const {
-		rootDir,
-		mode,
-		dev = false,
-		projectId = '',
-		deploymentId = '',
-		logger,
-		profile,
-	} = options;
-
-	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:*';
-		}
-	}
+	const { rootDir, mode, dev = false, deploymentId = '', logger, profile } = options;
 
 	logger.debug(`Running Vite build for mode: ${mode}`);
 
@@ -125,24 +107,7 @@ export async function runViteBuild(options: ViteBuildOptions): Promise<void> {
 			profile,
 		});
 
-		// Load workbench config for entry file generation
-		const { loadAgentuityConfig, getWorkbenchConfig } = await import('./config-loader');
-		const config = await loadAgentuityConfig(rootDir, logger);
-		const workbenchConfig = getWorkbenchConfig(config, dev);
-
-		// Then, generate the entry file
-		const { generateEntryFile } = await import('../entry-generator');
-		await generateEntryFile({
-			rootDir,
-			projectId,
-			deploymentId: deploymentId || '',
-			logger,
-			mode: dev ? 'dev' : 'prod',
-			workbench: workbenchConfig.configured ? workbenchConfig : undefined,
-			analytics: config?.analytics,
-		});
-
-		// Finally, build with Bun.build
+		// Build with Bun.build (app.ts is the entrypoint)
 		const { installExternalsAndBuild } = await import('./server-bundler');
 		await installExternalsAndBuild({
 			rootDir,
@@ -255,7 +220,7 @@ export async function runViteBuild(options: ViteBuildOptions): Promise<void> {
 				// In dev mode, Vite serves them directly from src/web/public/
 				copyPublicDir: !dev,
 			},
-			logLevel: isViteDebug ? 'info' : 'warn',
+			logLevel: 'warn',
 		};
 	} else if (mode === 'workbench') {
 		const { workbenchRoute = '/workbench' } = options;
@@ -290,7 +255,7 @@ export async function runViteBuild(options: ViteBuildOptions): Promise<void> {
 				manifest: true,
 				emptyOutDir: true,
 			},
-			logLevel: isViteDebug ? 'info' : 'warn',
+			logLevel: 'warn',
 		};
 	} else {
 		throw new Error(`Unknown build mode: ${mode}`);
@@ -356,7 +321,6 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 
 	// 1. Discover agents and routes BEFORE builds
 	logger.debug('Discovering agents and routes...');
-	const { generateAgentRegistry, generateRouteRegistry } = await import('./registry-generator');
 	const { discoverAgents } = await import('./agent-discovery');
 	const { discoverRoutes } = await import('./route-discovery');
 
@@ -367,18 +331,9 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 		options.deploymentId || '',
 		logger
 	);
-	const { routes, routeInfoList } = await discoverRoutes(
-		srcDir,
-		projectId,
-		options.deploymentId || '',
-		logger
-	);
+	const { routes } = await discoverRoutes(srcDir, projectId, options.deploymentId || '', logger);
 
-	// Generate agent and route registries for type augmentation BEFORE builds
-	// (TypeScript needs these files to exist during type checking)
-	generateAgentRegistry(srcDir, agentMetadata);
-	await generateRouteRegistry(srcDir, routeInfoList);
-	logger.debug('Agent and route registries generated');
+	// Agent metadata is used for metadata.json generation (no registry codegen needed)
 
 	// Check if web frontend exists
 	const hasWebFrontend = await Bun.file(join(rootDir, 'src', 'web', 'index.html')).exists();

package/src/cmd/build/vite/ws-proxy.ts

@@ -0,0 +1,126 @@
+/**
+ * WebSocket-aware front-door TCP proxy for dev mode.
+ *
+ * Bun's node:http has several bugs that prevent Vite's built-in http-proxy
+ * from proxying WebSocket upgrades (see linked PRs). Rather than polyfilling
+ * those bugs, this module places a lightweight `net.createServer` on the
+ * user-facing port. It inspects the first bytes of each TCP connection and
+ * routes accordingly:
+ *
+ * - **WebSocket upgrades to backend paths** → piped directly to Bun backend
+ *   (Bun's native `server.upgrade()` works perfectly over raw TCP)
+ * - **Everything else** (HTTP requests, Vite HMR WebSocket) → piped to Vite
+ *
+ * From the browser's perspective there is only one port. Vite and Bun both
+ * listen on internal ports that are never exposed.
+ *
+ * Bun bugs this works around:
+ * - https://github.com/oven-sh/bun/pull/27237 (socket.write drops data)
+ * - https://github.com/oven-sh/bun/pull/26264 (missing destroySoon)
+ * - https://github.com/oven-sh/bun/pull/27859 (http.request upgrade event)
+ * - Server-side upgrade socket read broken (HTTP parser doesn't hand off)
+ *
+ * This entire module can be removed once those Bun PRs are merged and the
+ * Vite `ws: true` proxy works natively under Bun.
+ *
+ * ```
+ * Browser ──TCP──▶ net.Server (:3500, user-facing)
+ *                     │
+ *         ┌───────────┴───────────┐
+ *         ▼ (WS upgrade to       ▼ (everything else)
+ *          backend paths)
+ *   Bun backend (:3501)    Vite server (:3502)
+ * ```
+ */
+
+import { createServer, connect, type Server } from 'node:net';
+import type { Logger } from '../../../types';
+
+export interface WsProxyOptions {
+	/** Port the front-door proxy listens on (user-facing) */
+	port: number;
+	/** Port of the Vite dev server (internal) */
+	vitePort: number;
+	/** Port of the Bun backend server (internal) */
+	backendPort: number;
+	/** Route path prefixes that should be proxied to the backend */
+	routePaths: string[];
+	logger: Logger;
+}
+
+/**
+ * Start a front-door TCP proxy that routes WebSocket upgrades to the Bun
+ * backend and everything else to Vite. Returns the `net.Server` instance.
+ */
+export function startWsProxy(options: WsProxyOptions): Promise<Server> {
+	const { port, vitePort, backendPort, routePaths, logger } = options;
+
+	// Prefixes whose WebSocket upgrades go to Bun instead of Vite
+	const wsPathPrefixes = ['/_agentuity', ...routePaths];
+
+	return new Promise((resolve, reject) => {
+		const server = createServer((socket) => {
+			let handled = false;
+
+			// Peek at the first chunk to decide where to route
+			socket.once('data', (firstChunk) => {
+				handled = true;
+
+				const header = firstChunk.toString('utf8', 0, Math.min(firstChunk.length, 4096));
+
+				// Detect: is this a WebSocket upgrade for a backend path?
+				const isUpgrade = /upgrade:\s*websocket/i.test(header);
+				let targetPort = vitePort;
+
+				if (isUpgrade) {
+					const pathMatch = header.match(/^(?:GET|POST)\s+(\S+)/);
+					const pathname = (pathMatch?.[1] ?? '/').split('?')[0] ?? '/';
+
+					const isBackendPath = wsPathPrefixes.some(
+						(prefix) => pathname === prefix || pathname.startsWith(prefix + '/')
+					);
+
+					if (isBackendPath) {
+						targetPort = backendPort;
+						logger.debug('WS upgrade %s → Bun :%d', pathname, backendPort);
+					}
+				}
+
+				const target = connect(targetPort, '127.0.0.1');
+
+				target.on('connect', () => {
+					target.write(firstChunk);
+					socket.pipe(target);
+					target.pipe(socket);
+				});
+
+				target.on('error', () => {
+					if (!socket.destroyed) socket.destroy();
+				});
+				socket.on('error', () => {
+					if (!target.destroyed) target.destroy();
+				});
+			});
+
+			// Client disconnected before sending anything
+			socket.on('close', () => {
+				if (!handled) socket.destroy();
+			});
+			socket.on('error', () => {
+				if (!handled) socket.destroy();
+			});
+		});
+
+		server.on('error', reject);
+
+		server.listen(port, '127.0.0.1', () => {
+			logger.debug(
+				'WS front-door proxy on :%d (Vite :%d, Bun :%d)',
+				port,
+				vitePort,
+				backendPort
+			);
+			resolve(server);
+		});
+	});
+}

package/src/cmd/build/vite-bundler.ts

@@ -10,7 +10,6 @@ import { StructuredError } from '@agentuity/core';
 import type { Logger, DeployOptions } from '../../types';
 import { runAllBuilds } from './vite/vite-builder';
 import { checkAndUpgradeDependencies } from '../../utils/dependency-checker';
-import { promptRouteMigration } from '../../utils/route-migration';
 import { checkBunVersion } from '../../utils/bun-version-checker';
 import * as tui from '../../tui';
 import type { BuildReportCollector } from '../../build-report';
@@ -90,9 +89,6 @@ export async function viteBundle(options: ViteBundleOptions): Promise<{ output:
 		});
 	}
 
-	// Check if project can migrate from file-based to explicit routing
-	await promptRouteMigration(rootDir, logger);
-
 	try {
 		// Run all builds (client -> workbench -> server)
 		logger.debug('Starting builds...');

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

@@ -8,7 +8,7 @@
 import { watch, type FSWatcher, statSync, readdirSync, lstatSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import type { Logger } from '../../types';
-import { createAgentTemplates, createAPITemplates } from './templates';
+import { createAgentTemplates } from './templates';
 
 export interface FileWatcherOptions {
 	rootDir: string;
@@ -219,7 +219,7 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 			isDirectory = false;
 		}
 
-		// Check if an empty directory was created in src/agent/ or src/api/
+		// 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 {
@@ -229,19 +229,12 @@ export function createFileWatcher(options: FileWatcherOptions): FileWatcherManag
 				// Check if it's empty
 				const contents = readdirSync(absPath);
 				if (contents.length === 0) {
-					// Check if this is an agent or API directory
 					if (
 						normalizedPath.startsWith('src/agent/') ||
 						normalizedPath.includes('/src/agent/')
 					) {
 						logger.debug('Agent directory created: %s', changedFile);
 						createAgentTemplates(absPath);
-					} else if (
-						normalizedPath.startsWith('src/api/') ||
-						normalizedPath.includes('/src/api/')
-					) {
-						logger.debug('API directory created: %s', changedFile);
-						createAPITemplates(absPath);
 					}
 				}
 			} catch (error) {