@agentuity/cli 2.0.11 → 2.0.13

package/src/cmd/ai/prompt/web.md

@@ -260,27 +260,52 @@ export function App() {
 
 ## Static Assets
 
-Place static files in the **public/** folder:
+Agentuity uses the standard Vite asset conventions. There are two ways to
+reference static files:
+
+### Import the asset (recommended for JS/TSX)
+
+For anything referenced from a component, `import` the file. Vite emits a
+content-hashed copy at build time and replaces the import with the final URL
+(including the production CDN when deployed):
+
+```typescript
+import logoUrl from './assets/logo.svg';
+
+export function Header() {
+	return <img src={logoUrl} alt="Logo" />;
+}
+```
+
+This works for images, fonts, videos, JSON, and any other static file type
+Vite understands. Because the filename is hashed, the browser can cache it
+forever and the CDN serves it from the edge.
+
+### Use `publicDir` (for HTML-referenced files and root-served assets)
+
+Files under `src/web/public/` are copied to the build root as-is and served
+at the URL root — **without** a `/public/` prefix. Use this for files that
+must live at a specific URL (e.g. `robots.txt`, `favicon.ico`, a PWA
+`manifest.json`) or that are referenced from `index.html`:
 
 ```
 src/web/public/
-├── logo.svg
-├── styles.css
-└── script.js
+├── favicon.ico      → served at /favicon.ico
+├── robots.txt       → served at /robots.txt
+└── styles.css       → served at /styles.css
 ```
 
-Reference them in your HTML or components:
-
 ```html
-<!-- In index.html -->
-<link rel="stylesheet" href="/public/styles.css" />
-<script src="/public/script.js"></script>
+<!-- In index.html — Vite rewrites root paths to the CDN in production -->
+<link rel="stylesheet" href="/styles.css" />
+<script src="/script.js"></script>
+<link rel="icon" href="/favicon.ico" />
 ```
 
-```typescript
-// In React components
-<img src="/public/logo.svg" alt="Logo" />
-```
+> **Do not** use a `/public/` prefix (e.g. `/public/logo.svg`). That path
+> is not served and will 404 in production. This is enforced by a build-time
+> lint — the build fails if `/public/...` or `src/web/public/...` appears in
+> any string literal under `src/web/`.
 
 ## Styling
 
@@ -294,7 +319,7 @@ Reference them in your HTML or components:
 
 ### CSS Files
 
-Create `public/styles.css`:
+Create `src/web/public/styles.css`:
 
 ```css
 body {
@@ -307,7 +332,7 @@ body {
 Import in `index.html`:
 
 ```html
-<link rel="stylesheet" href="/public/styles.css" />
+<link rel="stylesheet" href="/styles.css" />
 ```
 
 ### Style Tag in Component
@@ -334,7 +359,7 @@ Import in `index.html`:
 - Use **useAuth** for authentication state management
 - Handle loading and error states in UI
 - Place reusable components in separate files
-- Keep static assets in the **public/** folder
+- Put assets in `src/web/public/` (for root-served files) or alongside your components (for imported files)
 
 ## Rules
 
@@ -343,5 +368,6 @@ Import in `index.html`:
 - **index.html** must have a `<div id="root"></div>`
 - Route types are derived from your Hono router via `hc<typeof router>()`
 - The web app is served at `/` by default
-- Static files in `public/` are served at `/public/*`
+- Files in `src/web/public/` are served at the URL root (`/filename`, **not** `/public/filename`)
+- For assets referenced from JS/TSX, use `import url from './path.svg'` — never a string literal like `/public/foo.svg`
 - Module script tag: `<script type="module" src="/web/frontend.tsx"></script>`

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

@@ -17,14 +17,35 @@ import type { Logger } from '../../../types';
 import { getAgentEnv } from '../../../agent-detection';
 import { createServer as createNetServer } from 'node:net';
 
+/**
+ * Minimal handle for the spawned Bun subprocess. Mirrors the shape used
+ * elsewhere (procManager, killBunSubprocess) so callers can register
+ * the process with their tracking layer without depending on Bun-specific
+ * Subprocess types.
+ */
+export interface BunSubprocessHandle {
+	kill: (signal?: number | NodeJS.Signals) => void;
+	exitCode: number | null;
+	pid?: number;
+}
+
 export interface BunDevServerOptions {
 	rootDir: string;
 	port?: number;
 	logger: Logger;
-	vitePort: number;
+	vitePort: number; // Kept for backward compatibility — no longer used internally
 	inspect?: boolean;
 	inspectWait?: boolean;
 	inspectBrk?: boolean;
+	/**
+	 * Optional callback fired the moment `Bun.spawn` returns, BEFORE the
+	 * readiness wait. Lets callers register the subprocess with a process
+	 * manager / shutdown handler immediately, eliminating the multi-second
+	 * window during which a SIGINT could orphan the child.
+	 *
+	 * If this throws, the subprocess is killed and the error is rethrown.
+	 */
+	onSpawn?: (proc: BunSubprocessHandle) => void;
 }
 
 export interface BunDevServerResult {
@@ -311,9 +332,17 @@ export function buildStartupErrorMessage(
  * are re-evaluated.
  */
 export async function startBunDevServer(options: BunDevServerOptions): Promise<BunDevServerResult> {
-	const { rootDir, port = 3500, logger, vitePort, inspect, inspectWait, inspectBrk } = options;
-
-	logger.debug('Starting Bun dev server (Vite already running on port %d)...', vitePort);
+	const {
+		rootDir,
+		port = 3500,
+		logger,
+		vitePort: _vitePort,
+		inspect,
+		inspectWait,
+		inspectBrk,
+	} = options;
+
+	logger.debug('Starting Bun dev server (port %d)...', port);
 
 	const appPath = `${rootDir}/app.ts`;
 
@@ -391,6 +420,15 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 			PORT: String(port),
 			FORCE_COLOR: '1', // Enable colors even though stdout is piped
 		},
+		// Make the child a process-group leader so the CLI's procManager /
+		// killBunSubprocess() can signal the whole tree via process.kill(-pid, ...).
+		// Without detached:true, bun --hot and any workers it spawns share our
+		// process group, process.kill(-pid) fails with EPERM (not a group leader),
+		// and we fall back to a direct PID kill that leaves children orphaned.
+		//
+		// We intentionally do NOT call .unref() here — the parent still tracks
+		// and drives the child's lifecycle, and piped stdio is unaffected.
+		detached: true,
 	});
 
 	// Start capturing streams in the background (don't await, we need to check server readiness)
@@ -404,6 +442,35 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	(globalThis as any).__AGENTUITY_BUN_SUBPROCESS__ = bunProcess;
 
+	// Notify caller IMMEDIATELY so the subprocess can be registered with the
+	// process manager before the readiness wait below. Without this, a SIGINT
+	// during the up-to-5s readiness wait would leave the subprocess unmanaged
+	// (only the synchronous exit-handler safety net would catch it).
+	if (options.onSpawn) {
+		try {
+			options.onSpawn(bunProcess as BunSubprocessHandle);
+		} catch (err) {
+			logger.debug('onSpawn callback threw, killing subprocess: %s', err);
+			const pid = bunProcess.pid;
+			try {
+				if (typeof pid === 'number' && pid > 1 && process.platform !== 'win32') {
+					try {
+						process.kill(-pid, 'SIGKILL');
+					} catch {
+						bunProcess.kill('SIGKILL');
+					}
+				} else {
+					bunProcess.kill('SIGKILL');
+				}
+			} catch {
+				// Best effort
+			}
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			(globalThis as any).__AGENTUITY_BUN_SUBPROCESS__ = undefined;
+			throw err;
+		}
+	}
+
 	// Wait for server to start listening
 	const maxRetries = 50;
 	const retryDelay = 100;
@@ -436,8 +503,28 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 	}
 
 	if (!serverReady) {
+		// The subprocess is spawned with detached:true and is therefore the
+		// leader of its own process group. bunProcess.kill() only targets the
+		// direct PID, which would leave any workers/grandchildren orphaned.
+		// Signal the whole process group with SIGKILL and fall back to the
+		// handle's kill() if the group-kill fails (EPERM, not-group-leader,
+		// or Windows where negative PIDs aren't supported).
+		const pid = bunProcess.pid;
 		try {
-			bunProcess.kill();
+			if (typeof pid === 'number' && pid > 1 && process.platform !== 'win32') {
+				try {
+					process.kill(-pid, 'SIGKILL');
+				} catch (groupErr) {
+					logger.debug(
+						'Process-group SIGKILL failed for pid %d (%s), falling back to direct kill',
+						pid,
+						(groupErr as NodeJS.ErrnoException).code ?? groupErr
+					);
+					bunProcess.kill('SIGKILL');
+				}
+			} else {
+				bunProcess.kill('SIGKILL');
+			}
 		} catch (err) {
 			logger.debug('Error killing subprocess during startup failure: %s', err);
 		}
@@ -452,7 +539,6 @@ export async function startBunDevServer(options: BunDevServerOptions): Promise<B
 	}
 
 	logger.debug(`Bun dev server started on http://127.0.0.1:${port} (--hot mode)`);
-	logger.debug(`Proxied to Vite:${vitePort}`);
 
 	return { bunServerPort: port };
 }

package/src/cmd/build/vite/index.ts

@@ -1,3 +1,2 @@
 // Re-export plugins for direct use in vite.config.ts
 export { browserEnvPlugin } from './browser-env-plugin';
-export { publicAssetPathPlugin } from './public-asset-path-plugin';

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

@@ -18,7 +18,7 @@ import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node
 import type { Logger } from '../../../types';
 
 /** Minimal shape of a TanStack Router route tree node. */
-interface RouteTreeNode {
+export interface RouteTreeNode {
 	path?: string;
 	options?: { path?: string };
 	children?: Record<string, RouteTreeNode>;
@@ -32,7 +32,7 @@ interface RouteTreeNode {
  * under layout routes have relative paths (e.g., '/key-value' under a
  * '/reference/api' layout should resolve to '/reference/api/key-value').
  */
-function extractRoutePaths(node: RouteTreeNode): string[] {
+export function extractRoutePaths(node: RouteTreeNode): string[] {
 	const paths = new Set<string>();
 
 	function walk(route: RouteTreeNode, parentPath: string) {
@@ -40,18 +40,29 @@ function extractRoutePaths(node: RouteTreeNode): string[] {
 
 		// Build the full path by accumulating segments from parent routes.
 		// - Layout routes have no path (undefined) and don't contribute to the URL.
-		// - Index routes have path '/' and resolve to the parent path itself.
+		// - Index routes have path '/' and resolve to the parent path itself
+		//   (e.g., the '/' child of the root is the landing page; the '/' child
+		//   of a '/docs' layout is '/docs'). They do not append anything.
 		// - Leaf/layout routes have paths like '/reference/api' or '/key-value'.
 		let currentPath = parentPath;
-		if (segment && segment !== '/') {
+		let isIndexRoute = false;
+		if (segment === '/') {
+			isIndexRoute = true;
+		} else if (segment) {
 			// Non-root segment: append to parent path.
 			// Segments always start with '/' (TanStack Router convention).
 			currentPath = parentPath === '/' ? segment : parentPath + segment;
 		}
 
-		// Add non-parameterized, non-empty paths
-		if (currentPath && !currentPath.includes('$')) {
-			const normalized = currentPath === '/' ? '/' : currentPath.replace(/\/+$/, '');
+		// Decide which URL, if any, to emit for this node.
+		// - Index routes emit the parent URL, defaulting to '/' when the parent
+		//   itself is pathless (i.e., the site root). Without this, a
+		//   `createFileRoute('/')` route is never pre-rendered and the
+		//   landing page ships with the unreplaced <!--app-html--> placeholder.
+		// - Non-index routes emit their own accumulated path.
+		const emit = isIndexRoute ? parentPath || '/' : currentPath;
+		if (emit && !emit.includes('$')) {
+			const normalized = emit === '/' ? '/' : emit.replace(/\/+$/, '');
 			if (normalized) {
 				paths.add(normalized);
 			}

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

@@ -22,6 +22,37 @@ export interface GenerateAssetServerConfigOptions {
 	liveHostname?: string;
 }
 
+/**
+ * Shared proxy configuration for backend routes.
+ *
+ * Includes `configure` callback that gracefully handles ECONNREFUSED errors
+ * when the Bun backend isn't ready yet (startup race condition or brief
+ * disconnect during --hot reload). Instead of logging noisy errors, the
+ * proxy returns 503 Service Unavailable with a retry hint.
+ */
+function backendProxyOptions(backendPort: number) {
+	return {
+		target: `http://127.0.0.1:${backendPort}`,
+		changeOrigin: true,
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		configure: (proxy: any, _options: any) => {
+			proxy.on('error', (err: Error & { code?: string }, _req: any, res: any) => {
+				if (err.code === 'ECONNREFUSED' && res && !res.writableEnded) {
+					res.statusCode = 503;
+					res.setHeader('Content-Type', 'application/json');
+					res.end(
+						JSON.stringify({
+							error: 'Backend unavailable',
+							message: 'The Bun backend is not ready yet. Retrying shortly...',
+							retry: true,
+						})
+					);
+				}
+			});
+		},
+	};
+}
+
 /**
  * Vite plugin that injects analytics scripts in dev mode.
  *
@@ -95,7 +126,7 @@ function spaFallbackPlugin(rootDir: string, routePaths: string[], workbenchPath?
 				const isDocumentRequest = secFetchDest === 'document' || accept.includes('text/html');
 
 				// Skip file requests (have an extension)
-				if (pathname !== '/' && /\.[a-zA-Z0-9]+$/.test(pathname)) return next();
+				if (pathname !== '/' && /\.[\w-]+$/.test(pathname)) return next();
 
 				// For non-document requests, only allow root path fallback.
 				// (e.g. don't turn module/script fetches into HTML accidentally)
@@ -241,37 +272,19 @@ export async function generateAssetServerConfig(
 			proxy: {
 				// User-defined route mounts (from createApp({ router }))
 				...Object.fromEntries(
-					routePaths.map((routePath) => [
-						routePath,
-						{
-							target: `http://127.0.0.1:${backendPort}`,
-							changeOrigin: true,
-						},
-					])
+					routePaths.map((routePath) => [routePath, backendProxyOptions(backendPort)])
 				),
 				// Agentuity system routes (workbench API, health, analytics, etc.)
-				'/_agentuity': {
-					target: `http://127.0.0.1:${backendPort}`,
-					changeOrigin: true,
-				},
+				'/_agentuity': backendProxyOptions(backendPort),
 				// Workbench UI route (served by Bun, references /@fs/* paths handled by Vite)
 				...(workbenchPath
 					? {
-							[workbenchPath]: {
-								target: `http://127.0.0.1:${backendPort}`,
-								changeOrigin: true,
-							},
+							[workbenchPath]: backendProxyOptions(backendPort),
 						}
 					: {}),
 				// Legacy health check routes
-				'/_health': {
-					target: `http://127.0.0.1:${backendPort}`,
-					changeOrigin: true,
-				},
-				'/_idle': {
-					target: `http://127.0.0.1:${backendPort}`,
-					changeOrigin: true,
-				},
+				'/_health': backendProxyOptions(backendPort),
+				'/_idle': backendProxyOptions(backendPort),
 			},
 
 			// HMR works natively — Vite is the primary server, no proxy needed
@@ -296,13 +309,10 @@ export async function generateAssetServerConfig(
 		// Agentuity-specific plugins (Vite loads user plugins from vite.config.ts automatically)
 		plugins: await (async () => {
 			const { browserEnvPlugin } = await import('./browser-env-plugin');
-			const { publicAssetPathPlugin } = await import('./public-asset-path-plugin');
 
 			return [
 				// Browser env plugin to map process.env to import.meta.env
 				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

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

@@ -50,8 +50,12 @@ function isPortAvailable(port: number, host: string): Promise<boolean> {
 /**
  * Find an available port starting from the preferred port.
  * Tries incrementing ports up to maxAttempts times.
+ *
+ * Exported so the dev command can pre-resolve the Vite port before
+ * starting the Bun backend (env vars like AGENTUITY_BASE_URL need
+ * the real port before Bun initializes CORS).
  */
-async function findAvailablePort(
+export async function findAvailablePort(
 	preferredPort: number,
 	host: string = '127.0.0.1',
 	maxAttempts: number = 20

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

@@ -227,6 +227,7 @@ import { join } from 'node:path';
 export default defineConfig({
 	plugins: [react()],
 	root: '.',
+	publicDir: 'src/web/public',
 	build: {
 		rollupOptions: {
 			input: join(__dirname, 'src/web/index.html'),
@@ -244,17 +245,27 @@ export default defineConfig({
 				? `https://${options.region === 'local' ? 'localstack-static-assets.t3.storageapi.dev' : 'cdn.agentuity.com'}/${options.deploymentId}/client/`
 				: undefined;
 
+		// Pass the user's vite.config.ts directly to the subprocess. We used to
+		// wrap it in an auto-generated `.agentuity/vite.client.config.ts` to
+		// merge a lint plugin in, but that wrapper added complexity (plugin-path
+		// resolution, a junk file in the deploy bundle) for a warning-only
+		// linter. If we need to inject plugins again, expose them as a published
+		// CLI export and have users add them in their own vite.config.ts.
 		const args = [
 			'bun',
 			'x',
 			'vite',
 			'build',
+			'--config',
+			viteConfigPath,
 			'--mode',
 			buildMode,
 			'--outDir',
 			clientOutDir,
+			// `warn` surfaces Vite warnings (e.g. large-chunk notices) without
+			// adding its own info-level chatter.
 			'--logLevel',
-			'error',
+			'warn',
 			'--clearScreen',
 			'false',
 		];

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

@@ -33,7 +33,7 @@
  * ```
  */
 
-import { createServer, connect, type Server } from 'node:net';
+import { createServer, connect, type Server, type Socket } from 'node:net';
 import type { Logger } from '../../../types';
 
 export interface WsProxyOptions {
@@ -48,18 +48,44 @@ export interface WsProxyOptions {
 	logger: Logger;
 }
 
+/**
+ * Front-door TCP proxy server.
+ *
+ * Extends `net.Server` with a `closeAll()` method that destroys all live
+ * client + upstream sockets and waits for the listening socket to close.
+ * The native `Server.close()` only stops accepting new connections — long-
+ * lived piped sockets (Vite HMR WebSocket, backend WS) keep the listener
+ * bound until they close on their own. During dev-mode shutdown we want
+ * the user-facing port released immediately, so cleanup paths should
+ * prefer `closeAll()` over `close()`.
+ */
+export interface WsProxyServer extends Server {
+	closeAll(): Promise<void>;
+}
+
 /**
  * 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> {
+export function startWsProxy(options: WsProxyOptions): Promise<WsProxyServer> {
 	const { port, vitePort, backendPort, routePaths, logger } = options;
 
 	// Prefixes whose WebSocket upgrades go to Bun instead of Vite
 	const wsPathPrefixes = ['/_agentuity', ...routePaths];
 
+	// Track every live socket pair so shutdown can drop them. Without this,
+	// `server.close()` waits for active connections to terminate by themselves
+	// (e.g. browser HMR WebSockets), which can keep the user-facing port bound
+	// for many seconds after dev mode exits.
+	const liveSockets = new Set<Socket>();
+	const trackSocket = (sock: Socket) => {
+		liveSockets.add(sock);
+		sock.once('close', () => liveSockets.delete(sock));
+	};
+
 	return new Promise((resolve, reject) => {
 		const server = createServer((socket) => {
+			trackSocket(socket);
 			let handled = false;
 
 			// Peek at the first chunk to decide where to route
@@ -87,6 +113,7 @@ export function startWsProxy(options: WsProxyOptions): Promise<Server> {
 				}
 
 				const target = connect(targetPort, '127.0.0.1');
+				trackSocket(target);
 
 				target.on('connect', () => {
 					target.write(firstChunk);
@@ -109,7 +136,29 @@ export function startWsProxy(options: WsProxyOptions): Promise<Server> {
 			socket.on('error', () => {
 				if (!handled) socket.destroy();
 			});
-		});
+		}) as WsProxyServer;
+
+		// Async close that destroys live sockets first, then waits for the
+		// listener to close. Idempotent: safe to call after the server has
+		// already been closed by other means.
+		server.closeAll = () => {
+			return new Promise<void>((resolveClose) => {
+				for (const sock of liveSockets) {
+					try {
+						if (!sock.destroyed) sock.destroy();
+					} catch {
+						// Best effort
+					}
+				}
+				liveSockets.clear();
+
+				if (!server.listening) {
+					resolveClose();
+					return;
+				}
+				server.close(() => resolveClose());
+			});
+		};
 
 		server.on('error', reject);