@agentuity/cli 0.0.95 → 0.0.96

package/src/cmd/build/vite/registry-generator.ts

@@ -0,0 +1,288 @@
+/**
+ * Registry Generator
+ *
+ * Generates .agentuity/registry.generated.ts from discovered agents
+ */
+
+import { join } from 'node:path';
+import { writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
+import { StructuredError } from '@agentuity/core';
+import { toCamelCase, toPascalCase } from '../../../utils/string';
+import type { AgentMetadata } from './agent-discovery';
+import type { RouteInfo } from './route-discovery';
+
+const AgentIdentifierCollisionError = StructuredError('AgentIdentifierCollisionError');
+
+/**
+ * Generate .agentuity/registry.generated.ts with agent registry and types
+ */
+export function generateAgentRegistry(srcDir: string, agents: AgentMetadata[]): void {
+	const projectRoot = join(srcDir, '..');
+	const agentuityDir = join(projectRoot, '.agentuity');
+	const registryPath = join(agentuityDir, 'registry.generated.ts');
+
+	// Detect naming collisions in generated identifiers
+	const generatedNames = new Set<string>();
+	const collisions: string[] = [];
+
+	for (const agent of agents) {
+		const camelName = toCamelCase(agent.name);
+
+		if (generatedNames.has(camelName)) {
+			collisions.push(`Identifier collision detected: "${camelName}" (from "${agent.name}")`);
+		}
+		generatedNames.add(camelName);
+	}
+
+	if (collisions.length > 0) {
+		throw new AgentIdentifierCollisionError({
+			message:
+				`Agent identifier naming collisions detected:\n${collisions.join('\n')}\n\n` +
+				`This occurs when different agent names produce the same camelCase identifier.\n` +
+				`Please rename your agents to avoid this collision.`,
+		});
+	}
+
+	// Generate imports for all agents
+	const imports = agents
+		.map(({ name, filename }) => {
+			const camelName = toCamelCase(name);
+			// Handle both './agent/...' and 'src/agent/...' formats
+			let relativePath = filename;
+			if (relativePath.startsWith('./agent/')) {
+				relativePath = relativePath.replace(/^\.\/agent\//, '../src/agent/');
+			} else if (relativePath.startsWith('src/agent/')) {
+				relativePath = '../' + relativePath;
+			}
+			return `import ${camelName} from '${relativePath}';`;
+		})
+		.join('\n');
+
+	// Generate flat registry structure
+	const registry = agents
+		.map(({ name }) => {
+			const camelName = toCamelCase(name);
+			return `  ${camelName}: ${camelName},`;
+		})
+		.join('\n');
+
+	// Generate type exports for all agents
+	const typeExports = agents
+		.map(({ name }) => {
+			const camelName = toCamelCase(name);
+			const pascalName = toPascalCase(name);
+			return `export type ${pascalName}Runner = AgentRunner<typeof ${camelName}['inputSchema'], typeof ${camelName}['outputSchema'], typeof ${camelName}['stream'] extends true ? true : false>;`;
+		})
+		.join('\n');
+
+	// Generate flat agent type definitions for AgentRegistry interface augmentation
+	const runtimeAgentTypes = agents
+		.map(({ name }) => {
+			const camelName = toCamelCase(name);
+			return `		${camelName}: AgentRunner<typeof ${camelName}['inputSchema'], typeof ${camelName}['outputSchema'], typeof ${camelName}['stream'] extends true ? true : false>;`;
+		})
+		.join('\n');
+
+	const generatedContent = `/// <reference types="hono" />
+// Auto-generated by Agentuity - do not edit manually
+${imports}
+import type { AgentRunner, Logger } from '@agentuity/runtime';
+import type { KeyValueStorage, StreamStorage, VectorStorage } from '@agentuity/core';
+
+/**
+ * Registry of all agents in this application.
+ * Provides strongly-typed access to agent metadata and runner functions.
+ * Auto-generated from your agent files during build.
+ */
+export const agentRegistry = {
+${registry}
+} as const;
+
+// Local type aliases for Hono augmentation
+type LocalAgentName = keyof typeof agentRegistry;
+type LocalAgentRegistry = typeof agentRegistry;
+
+// Typed runners for each agent
+${typeExports}
+
+// Augment @agentuity/runtime types with strongly-typed agents from this project
+declare module "@agentuity/runtime" {
+	// Augment the AgentRegistry interface with project-specific strongly-typed agents
+	export interface AgentRegistry {
+${runtimeAgentTypes}
+	}
+}
+
+// NOTE: Hono Context properties are accessed via c.var (e.g., c.var.logger, c.var.kv)
+// The Variables interface in @agentuity/runtime defines all available context properties
+`;
+
+	const agentsDir = join(srcDir, 'agent');
+	const legacyTypesPath = join(agentsDir, 'types.generated.d.ts');
+
+	// Ensure .agentuity directory exists
+	if (!existsSync(agentuityDir)) {
+		mkdirSync(agentuityDir, { recursive: true });
+	}
+
+	writeFileSync(registryPath, generatedContent, 'utf-8');
+
+	// Remove legacy types.generated.d.ts if it exists (now consolidated into registry.generated.ts)
+	if (existsSync(legacyTypesPath)) {
+		unlinkSync(legacyTypesPath);
+	}
+}
+
+/**
+ * Generate RouteRegistry type definitions from discovered routes.
+ *
+ * Creates a module augmentation for @agentuity/react that provides
+ * strongly-typed route keys with input/output schema information.
+ */
+export function generateRouteRegistry(srcDir: string, routes: RouteInfo[]): void {
+	// Filter routes by type
+	const apiRoutes = routes.filter((r) => r.routeType === 'api' || r.routeType === 'stream');
+	const websocketRoutes = routes.filter((r) => r.routeType === 'websocket');
+	const sseRoutes = routes.filter((r) => r.routeType === 'sse');
+
+	if (apiRoutes.length === 0 && websocketRoutes.length === 0 && sseRoutes.length === 0) {
+		return;
+	}
+
+	// Generate imports for agents and schemas
+	const imports: string[] = [];
+	const agentImports = new Map<string, string>();
+	const routeFileImports = new Map<string, Set<string>>();
+
+	const allRoutes = [...apiRoutes, ...websocketRoutes, ...sseRoutes];
+
+	// Collect agent imports
+	allRoutes.forEach((route) => {
+		if (!route.hasValidator) return;
+
+		if (route.agentVariable && route.agentImportPath && !agentImports.has(route.agentVariable)) {
+			let resolvedPath = route.agentImportPath;
+
+			if (resolvedPath.startsWith('@agent/')) {
+				resolvedPath = `../src/agent/${resolvedPath.substring('@agent/'.length)}`;
+			} else if (resolvedPath.startsWith('@api/')) {
+				resolvedPath = `../src/web/${resolvedPath.substring('@api/'.length)}`;
+			} else if (resolvedPath.startsWith('./') || resolvedPath.startsWith('../')) {
+				const routeDir = route.filename.substring(0, route.filename.lastIndexOf('/'));
+				resolvedPath = `../${routeDir}/${resolvedPath}`;
+			}
+
+			const uniqueImportName = `agent_${route.agentVariable}`;
+			imports.push(`import type ${uniqueImportName} from '${resolvedPath}';`);
+			agentImports.set(route.agentVariable, uniqueImportName);
+		}
+
+		// Collect schema variable imports
+		if (route.inputSchemaVariable || route.outputSchemaVariable) {
+			const filename = route.filename.replace(/\\/g, '/');
+			const importPath = `../${filename.replace(/\.ts$/, '')}`;
+
+			if (!routeFileImports.has(importPath)) {
+				routeFileImports.set(importPath, new Set());
+			}
+
+			if (route.inputSchemaVariable) {
+				routeFileImports.get(importPath)!.add(route.inputSchemaVariable);
+			}
+			if (route.outputSchemaVariable) {
+				routeFileImports.get(importPath)!.add(route.outputSchemaVariable);
+			}
+		}
+	});
+
+	// Generate schema imports
+	routeFileImports.forEach((schemas, importPath) => {
+		const schemaList = Array.from(schemas).join(', ');
+		imports.push(`import type { ${schemaList} } from '${importPath}';`);
+	});
+
+	const importsStr = imports.join('\n');
+
+	// Helper to generate route entry
+	const generateRouteEntry = (route: RouteInfo): string => {
+		const routeKey = route.path;
+
+		if (!route.hasValidator) {
+			const streamValue = route.stream === true ? 'true' : 'false';
+			return `  '${routeKey}': {
+    inputSchema: never;
+    outputSchema: never;
+    stream: ${streamValue};
+  };`;
+		}
+
+		if (route.agentVariable) {
+			const importName = agentImports.get(route.agentVariable)!;
+			return `  '${routeKey}': {
+    inputSchema: typeof ${importName} extends { inputSchema?: infer I } ? I : never;
+    outputSchema: typeof ${importName} extends { outputSchema?: infer O } ? O : never;
+    stream: typeof ${importName} extends { stream?: infer S } ? S : false;
+  };`;
+		}
+
+		if (route.inputSchemaVariable || route.outputSchemaVariable) {
+			const inputType = route.inputSchemaVariable
+				? `typeof ${route.inputSchemaVariable}`
+				: 'never';
+			const outputType = route.outputSchemaVariable
+				? `typeof ${route.outputSchemaVariable}`
+				: 'never';
+			const streamValue = route.stream === true ? 'true' : 'false';
+			return `  '${routeKey}': {
+    inputSchema: ${inputType};
+    outputSchema: ${outputType};
+    stream: ${streamValue};
+  };`;
+		}
+
+		return `  '${routeKey}': {
+    inputSchema: any;
+    outputSchema: any;
+  };`;
+	};
+
+	// Generate route entries with METHOD prefix for API routes
+	const apiRouteEntries = apiRoutes
+		.map((route) => {
+			const routeKey = `${route.method.toUpperCase()} ${route.path}`;
+			return generateRouteEntry({ ...route, path: routeKey });
+		})
+		.join('\n');
+
+	const websocketRouteEntries = websocketRoutes.map(generateRouteEntry).join('\n');
+	const sseRouteEntries = sseRoutes.map(generateRouteEntry).join('\n');
+
+	const generatedContent = `// Auto-generated by Agentuity - do not edit manually
+${importsStr}
+
+// Augment @agentuity/react types with project-specific routes
+declare module '@agentuity/react' {
+  export interface RouteRegistry {
+${apiRouteEntries}
+  }
+  
+  export interface WebSocketRouteRegistry {
+${websocketRouteEntries}
+  }
+  
+  export interface SSERouteRegistry {
+${sseRouteEntries}
+  }
+}
+`;
+
+	const projectRoot = join(srcDir, '..');
+	const agentuityDir = join(projectRoot, '.agentuity');
+	const registryPath = join(agentuityDir, 'routes.generated.ts');
+
+	if (!existsSync(agentuityDir)) {
+		mkdirSync(agentuityDir, { recursive: true });
+	}
+
+	writeFileSync(registryPath, generatedContent, 'utf-8');
+}

package/src/cmd/build/vite/route-discovery.ts

@@ -0,0 +1,186 @@
+/**
+ * Route Discovery - READ-ONLY AST analysis
+ *
+ * Discovers routes by scanning src/api/**\/*.ts files
+ * Extracts route definitions WITHOUT mutating source files
+ */
+
+import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { Logger } from '../../../types';
+import { parseRoute } from '../ast';
+
+export interface RouteMetadata {
+	id: string;
+	filename: string;
+	path: string;
+	method: string;
+	version: string;
+	type: 'api' | 'sms' | 'email' | 'cron' | 'websocket' | 'sse' | 'stream';
+	agentIds?: string[];
+	config?: Record<string, unknown>;
+	schema?: {
+		input?: string;
+		output?: string;
+	};
+}
+
+export interface RouteInfo {
+	method: string;
+	path: string;
+	filename: string;
+	hasValidator: boolean;
+	routeType: 'api' | 'sms' | 'email' | 'cron' | 'websocket' | 'sse' | 'stream';
+	agentVariable?: string;
+	agentImportPath?: string;
+	inputSchemaVariable?: string;
+	outputSchemaVariable?: string;
+	stream?: boolean;
+}
+
+/**
+ * Discover all routes in src/api directory (READ-ONLY)
+ */
+export async function discoverRoutes(
+	srcDir: string,
+	projectId: string,
+	deploymentId: string,
+	logger: Logger
+): Promise<{ routes: RouteMetadata[]; routeInfoList: RouteInfo[] }> {
+	const apiDir = join(srcDir, 'api');
+	const routes: RouteMetadata[] = [];
+	const routeInfoList: RouteInfo[] = [];
+
+	// Check if API directory exists
+	if (!existsSync(apiDir)) {
+		logger.trace('No api directory found at %s', apiDir);
+		return { routes, routeInfoList };
+	}
+
+	const transpiler = new Bun.Transpiler({ loader: 'ts', target: 'bun' });
+
+	// Scan all .ts files in api directory
+	const glob = new Bun.Glob('**/*.ts');
+	for await (const file of glob.scan(apiDir)) {
+		const filePath = join(apiDir, file);
+
+		try {
+			const source = await Bun.file(filePath).text();
+			const contents = transpiler.transformSync(source);
+
+			// Check if file has createRouter or Hono
+			if (!contents.includes('createRouter') && !contents.includes('new Hono')) {
+				logger.trace('Skipping %s (no router)', file);
+				continue;
+			}
+
+			const rootDir = join(srcDir, '..');
+			const relativeFilename = './' + relative(srcDir, filePath);
+
+			try {
+				const parsedRoutes = await parseRoute(rootDir, filePath, projectId, deploymentId);
+
+				if (parsedRoutes.length > 0) {
+					logger.trace('Discovered %d route(s) in %s', parsedRoutes.length, relativeFilename);
+					routes.push(...parsedRoutes);
+
+					// Convert to RouteInfo for registry
+					for (const route of parsedRoutes) {
+						routeInfoList.push({
+							method: route.method.toUpperCase(),
+							path: route.path,
+							filename: route.filename,
+							hasValidator: route.config?.hasValidator === true,
+							routeType: route.type || 'api',
+							agentVariable: route.config?.agentVariable as string | undefined,
+							agentImportPath: route.config?.agentImportPath as string | undefined,
+							inputSchemaVariable: route.config?.inputSchemaVariable as string | undefined,
+							outputSchemaVariable: route.config?.outputSchemaVariable as string | undefined,
+							stream:
+								route.config?.stream !== undefined && route.config.stream !== null
+									? Boolean(route.config.stream)
+									: route.type === 'stream'
+										? true
+										: undefined,
+						});
+					}
+				}
+			} catch (error) {
+				// Skip files that don't have proper router setup
+				if (error instanceof Error) {
+					if (
+						error.message.includes('could not find default export') ||
+						error.message.includes('could not find an proper createRouter')
+					) {
+						logger.trace('Skipping %s: %s', file, error.message);
+					} else {
+						throw error;
+					}
+				} else {
+					throw error;
+				}
+			}
+		} catch (error) {
+			logger.warn(`Failed to parse route file ${filePath}: ${error}`);
+		}
+	}
+
+	logger.debug('Discovered %d route(s)', routes.length);
+
+	// Check for route conflicts
+	const conflicts = detectRouteConflicts(routeInfoList);
+	if (conflicts.length > 0) {
+		logger.error('Route conflicts detected:');
+		for (const conflict of conflicts) {
+			logger.error('  %s', conflict.message);
+			for (const route of conflict.routes) {
+				logger.error('    - %s %s in %s', route.method, route.path, route.filename);
+			}
+		}
+		throw new Error(
+			`Found ${conflicts.length} route conflict(s). Fix the conflicts and try again.`
+		);
+	}
+
+	return { routes, routeInfoList };
+}
+
+export interface RouteConflict {
+	type: 'duplicate';
+	routes: Array<{ method: string; path: string; filename: string }>;
+	message: string;
+}
+
+/**
+ * Detect conflicts between routes
+ */
+export function detectRouteConflicts(
+	routes: Array<{ method: string; path: string; filename: string }>
+): RouteConflict[] {
+	const conflicts: RouteConflict[] = [];
+
+	// Group routes by method+path
+	const methodPathMap = new Map<string, Array<{ path: string; filename: string }>>();
+
+	for (const route of routes) {
+		const key = `${route.method.toUpperCase()} ${route.path}`;
+		if (!methodPathMap.has(key)) {
+			methodPathMap.set(key, []);
+		}
+		methodPathMap.get(key)!.push({ path: route.path, filename: route.filename });
+	}
+
+	// Check for exact duplicates
+	for (const [methodPath, routeList] of methodPathMap.entries()) {
+		if (routeList.length > 1) {
+			const [method] = methodPath.split(' ', 2);
+			conflicts.push({
+				type: 'duplicate',
+				routes: routeList.map((r) => ({ method, path: r.path, filename: r.filename })),
+				message: `Duplicate route: ${methodPath} defined in ${routeList.length} files`,
+			});
+		}
+	}
+
+	return conflicts;
+}