@agentuity/cli 1.0.38 → 1.0.40

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

@@ -732,7 +732,8 @@ export async function generateRouteRegistry(
 				resolvedPath = `../api/${finalPath}`;
 			} else if (resolvedPath.startsWith('./') || resolvedPath.startsWith('../')) {
 				// Resolve relative import from route file's directory
-				const normalizedFilename = toForwardSlash(route.filename);
+				// Use schemaSourceFile when available (sub-router routes)
+				const normalizedFilename = toForwardSlash(route.schemaSourceFile ?? route.filename);
 				const routeDir = normalizedFilename.substring(0, normalizedFilename.lastIndexOf('/'));
 				// Join and normalize the path
 				const joined = `${routeDir}/${resolvedPath}`;
@@ -793,15 +794,19 @@ export async function generateRouteRegistry(
 
 			if (route.inputSchemaImportPath) {
 				// Schema is imported - rebase the import path from route file to generated file
-				importPath = rebaseImportPath(route.filename, route.inputSchemaImportPath, srcDir);
+				// Use schemaSourceFile if available (sub-router routes carry the original file)
+				const sourceFile = route.schemaSourceFile ?? route.filename;
+				importPath = rebaseImportPath(sourceFile, route.inputSchemaImportPath, srcDir);
 				// Use the actual exported name (handles aliased imports like `import { A as B }`)
 				schemaNameToImport =
 					route.inputSchemaImportedName === 'default'
 						? route.inputSchemaVariable
 						: (route.inputSchemaImportedName ?? route.inputSchemaVariable);
 			} else {
-				// Schema is locally defined - import from the route file
-				const filename = toForwardSlash(route.filename);
+				// Schema is locally defined - import from the file that defines/exports it
+				// When route is mounted via .route(), schemaSourceFile points to the sub-router file
+				const sourceFile = route.schemaSourceFile ?? route.filename;
+				const filename = toForwardSlash(sourceFile);
 				const withoutSrc = filename.startsWith('src/') ? filename.substring(4) : filename;
 				const withoutLeadingDot = withoutSrc.startsWith('./')
 					? withoutSrc.substring(2)
@@ -828,15 +833,17 @@ export async function generateRouteRegistry(
 
 			if (route.outputSchemaImportPath) {
 				// Schema is imported - rebase the import path from route file to generated file
-				importPath = rebaseImportPath(route.filename, route.outputSchemaImportPath, srcDir);
+				const sourceFile = route.schemaSourceFile ?? route.filename;
+				importPath = rebaseImportPath(sourceFile, route.outputSchemaImportPath, srcDir);
 				// Use the actual exported name (handles aliased imports like `import { A as B }`)
 				schemaNameToImport =
 					route.outputSchemaImportedName === 'default'
 						? route.outputSchemaVariable
 						: (route.outputSchemaImportedName ?? route.outputSchemaVariable);
 			} else {
-				// Schema is locally defined - import from the route file
-				const filename = toForwardSlash(route.filename);
+				// Schema is locally defined - import from the file that defines/exports it
+				const sourceFile = route.schemaSourceFile ?? route.filename;
+				const filename = toForwardSlash(sourceFile);
 				const withoutSrc = filename.startsWith('src/') ? filename.substring(4) : filename;
 				const withoutLeadingDot = withoutSrc.startsWith('./')
 					? withoutSrc.substring(2)
@@ -858,19 +865,37 @@ export async function generateRouteRegistry(
 		}
 	});
 
-	// Generate schema imports with unique aliases to avoid conflicts
+	// Generate schema imports, only aliasing when names collide across files
 	const schemaImportAliases = new Map<string, Map<string, string>>(); // importPath -> (schemaName -> alias)
-	let aliasCounter = 0;
+
+	// First pass: count how many times each schema name appears across all import paths
+	const globalNameCount = new Map<string, number>();
+	routeFileImports.forEach((schemas) => {
+		for (const schemaName of schemas) {
+			globalNameCount.set(schemaName, (globalNameCount.get(schemaName) ?? 0) + 1);
+		}
+	});
+
+	// Track aliases assigned to duplicated names for uniqueness
+	const duplicateCounters = new Map<string, number>();
 
 	routeFileImports.forEach((schemas, importPath) => {
 		const aliases = new Map<string, string>();
 		const importParts: string[] = [];
 
 		for (const schemaName of Array.from(schemas)) {
-			// Create a unique alias for this schema to avoid collisions
-			const alias = `${schemaName}_${aliasCounter++}`;
-			aliases.set(schemaName, alias);
-			importParts.push(`${schemaName} as ${alias}`);
+			if ((globalNameCount.get(schemaName) ?? 0) > 1) {
+				// Name appears in multiple import paths — alias to avoid collision
+				const counter = duplicateCounters.get(schemaName) ?? 0;
+				duplicateCounters.set(schemaName, counter + 1);
+				const alias = `${schemaName}_${counter}`;
+				aliases.set(schemaName, alias);
+				importParts.push(`${schemaName} as ${alias}`);
+			} else {
+				// Unique name — import directly, no alias needed
+				aliases.set(schemaName, schemaName);
+				importParts.push(schemaName);
+			}
 		}
 
 		schemaImportAliases.set(importPath, aliases);

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

@@ -1,8 +1,9 @@
 /**
  * Route Discovery - READ-ONLY AST analysis
  *
- * Discovers routes by scanning src/api/**\/*.ts files
- * Extracts route definitions WITHOUT mutating source files
+ * Discovers routes by scanning src/api/**\/*.ts files or by following
+ * explicit router mounts from createApp({ router }).
+ * Extracts route definitions WITHOUT mutating source files.
  */
 
 import { join, relative } from 'node:path';
@@ -10,6 +11,7 @@ import { existsSync } from 'node:fs';
 import type { Logger } from '../../../types';
 import { parseRoute } from '../ast';
 import { toForwardSlash } from '../../../utils/normalize-path';
+import { detectExplicitRouter, type AppRouterDetection } from '../app-router-detector';
 
 export interface RouteMetadata {
 	id: string;
@@ -46,6 +48,12 @@ export interface RouteInfo {
 	outputSchemaCode?: string;
 	stream?: boolean;
 	pathParams?: string[];
+	/**
+	 * When a route is mounted via .route(), its filename is set to the parent file
+	 * (for dedup filtering). schemaSourceFile preserves the actual file where the
+	 * route's schema variables are defined/exported, so registry imports resolve correctly.
+	 */
+	schemaSourceFile?: string;
 }
 
 /**
@@ -66,13 +74,152 @@ export function extractPathParams(path: string): string[] {
 }
 
 /**
- * Discover all routes in src/api directory (READ-ONLY)
+ * Discover all routes — tries explicit router detection first, falls back to file-based.
+ *
+ * When `createApp({ router })` is detected in app.ts, routes are discovered by
+ * following the router imports with code-derived mount paths. Otherwise, falls back
+ * to scanning src/api/**\/*.ts with filesystem-derived paths.
  */
 export async function discoverRoutes(
 	srcDir: string,
 	projectId: string,
 	deploymentId: string,
 	logger: Logger
+): Promise<{
+	routes: RouteMetadata[];
+	routeInfoList: RouteInfo[];
+	/** Whether explicit router was detected (vs file-based fallback) */
+	explicitRouter?: AppRouterDetection;
+}> {
+	const rootDir = join(srcDir, '..');
+
+	// Try explicit router detection first
+	const detection = await detectExplicitRouter(rootDir, logger);
+	if (detection.detected && detection.mounts.length > 0) {
+		logger.debug(
+			'Using explicit router detection (%d mount(s) from createApp)',
+			detection.mounts.length
+		);
+		const result = await discoverExplicitRoutes(
+			rootDir,
+			srcDir,
+			projectId,
+			deploymentId,
+			detection,
+			logger
+		);
+		return { ...result, explicitRouter: detection };
+	}
+
+	// Fall back to file-based discovery
+	return discoverFileBasedRoutes(srcDir, projectId, deploymentId, logger);
+}
+
+/**
+ * Discover routes from explicit router mounts detected in app.ts.
+ * Parses each router file with its code-derived mount prefix.
+ */
+async function discoverExplicitRoutes(
+	rootDir: string,
+	srcDir: string,
+	projectId: string,
+	deploymentId: string,
+	detection: AppRouterDetection,
+	logger: Logger
+): Promise<{ routes: RouteMetadata[]; routeInfoList: RouteInfo[] }> {
+	const routes: RouteMetadata[] = [];
+	const routeInfoList: RouteInfo[] = [];
+	const visited = new Set<string>();
+	const mountedSubrouters = new Set<string>();
+
+	for (const mount of detection.mounts) {
+		try {
+			const parsedRoutes = await parseRoute(rootDir, mount.routerFile, projectId, deploymentId, {
+				visitedFiles: visited,
+				mountedSubrouters,
+				mountPrefix: mount.path,
+			});
+
+			if (parsedRoutes.length > 0) {
+				const relFile = './' + toForwardSlash(relative(srcDir, mount.routerFile));
+				logger.trace(
+					'Discovered %d route(s) from explicit mount at %s (%s)',
+					parsedRoutes.length,
+					mount.path,
+					relFile
+				);
+				routes.push(...parsedRoutes);
+
+				for (const route of parsedRoutes) {
+					const pathParams = extractPathParams(route.path);
+					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,
+						inputSchemaImportPath: route.config?.inputSchemaImportPath as string | undefined,
+						inputSchemaImportedName: route.config?.inputSchemaImportedName as
+							| string
+							| undefined,
+						outputSchemaImportPath: route.config?.outputSchemaImportPath as
+							| string
+							| undefined,
+						outputSchemaImportedName: route.config?.outputSchemaImportedName as
+							| string
+							| undefined,
+						stream:
+							route.config?.stream !== undefined && route.config.stream !== null
+								? Boolean(route.config.stream)
+								: route.type === 'stream'
+									? true
+									: undefined,
+						pathParams: pathParams.length > 0 ? pathParams : undefined,
+						schemaSourceFile: route.config?.schemaSourceFile as string | undefined,
+					});
+				}
+			}
+		} catch (error) {
+			logger.warn(
+				'Failed to parse explicit router at %s: %s',
+				mount.routerFile,
+				error instanceof Error ? error.message : String(error)
+			);
+		}
+	}
+
+	logger.debug('Discovered %d route(s) via explicit router detection', 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 };
+}
+
+/**
+ * Discover routes by scanning src/api directory (original file-based approach).
+ */
+async function discoverFileBasedRoutes(
+	srcDir: string,
+	projectId: string,
+	deploymentId: string,
+	logger: Logger
 ): Promise<{ routes: RouteMetadata[]; routeInfoList: RouteInfo[] }> {
 	const apiDir = join(srcDir, 'api');
 	const routes: RouteMetadata[] = [];
@@ -154,6 +301,7 @@ export async function discoverRoutes(
 										? true
 										: undefined,
 							pathParams: pathParams.length > 0 ? pathParams : undefined,
+							schemaSourceFile: route.config?.schemaSourceFile as string | undefined,
 						});
 					}
 				}

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

@@ -325,6 +325,17 @@ export async function runAllBuilds(options: Omit<ViteBuildOptions, 'mode'>): Pro
 	// Load config to check if workbench is enabled (dev mode only)
 	const { loadAgentuityConfig, getWorkbenchConfig } = await import('./config-loader');
 	const config = await loadAgentuityConfig(rootDir, logger);
+
+	// Copy bundle files if configured (before build so build output takes priority)
+	if (config?.bundle?.length) {
+		const { copyBundleFiles } = await import('./bundle-files');
+		const outDir = join(rootDir, '.agentuity');
+		const count = await copyBundleFiles(rootDir, outDir, config.bundle, logger);
+		if (count > 0) {
+			logger.debug(`Copied ${count} bundle file(s) to .agentuity`);
+		}
+	}
+
 	const workbenchConfig = getWorkbenchConfig(config, dev);
 	// Generate workbench files BEFORE any builds if enabled (dev mode only)
 	if (workbenchConfig.enabled) {

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

@@ -10,6 +10,7 @@ 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';
@@ -89,6 +90,9 @@ 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/index.ts

@@ -20,6 +20,11 @@ import { isTTY, hasLoggedInBefore } from '../../auth';
 import { createFileWatcher } from './file-watcher';
 import { prepareDevLock, releaseLockSync } from './dev-lock';
 import { checkAndUpgradeDependencies } from '../../utils/dependency-checker';
+import {
+	promptRouteMigration,
+	performMigration,
+	checkMigrationEligibility,
+} from '../../utils/route-migration';
 import { ErrorCode } from '../../errors';
 
 const DEFAULT_PORT = 3500;
@@ -232,6 +237,12 @@ export const command = createCommand({
 				.boolean()
 				.optional()
 				.describe('Skip TypeScript type checking on startup and restarts'),
+			migrateRoutes: z
+				.boolean()
+				.optional()
+				.describe(
+					'Migrate file-based routes to explicit routing (src/api/index.ts root router)'
+				),
 			resume: z.string().optional().describe('Resume a paused Hub session by ID'),
 		}),
 	},
@@ -414,6 +425,29 @@ export const command = createCommand({
 			);
 		}
 
+		// Check if project can migrate to explicit routing
+		if (opts.migrateRoutes) {
+			const eligibility = checkMigrationEligibility(rootDir);
+			if (eligibility.available) {
+				const result = performMigration(rootDir, eligibility.routeFiles);
+				if (result.success) {
+					tui.success(result.message);
+					if (result.filesCreated.length > 0) {
+						tui.info(`Created: ${result.filesCreated.map((f) => tui.muted(f)).join(', ')}`);
+					}
+					tui.newline();
+				} else {
+					tui.warning(result.message);
+					tui.newline();
+				}
+			} else {
+				tui.info('No migration needed — already using explicit routing.');
+				tui.newline();
+			}
+		} else {
+			await promptRouteMigration(rootDir, logger, { interactive });
+		}
+
 		try {
 			// Setup devmode and gravity (if using public URL)
 			const useMockService = process.env.DEVMODE_SYNC_SERVICE_MOCK === 'true';

package/src/types.ts

@@ -249,6 +249,15 @@ export interface AgentuityConfig {
 	 * Note: Cannot override AGENTUITY_PUBLIC_* or process.env.NODE_ENV
 	 */
 	define?: Record<string, string>;
+	/**
+	 * Glob patterns for additional files to include in the deployment bundle.
+	 * Files matching these patterns will be copied into the .agentuity build
+	 * output directory before the build runs, preserving their relative paths
+	 * from the project root. Build output will overwrite any conflicting files.
+	 *
+	 * @example ['data/**', 'templates/*.json', 'models/weights.bin']
+	 */
+	bundle?: string[];
 }
 
 /**