@agentuity/migrate 2.0.0-beta.1

package/src/transforms/app-ts.ts

@@ -0,0 +1,144 @@
+/**
+ * Transform: app.ts
+ *
+ * Handles the following mechanical changes:
+ *   1. Remove bootstrapRuntimeEnv() import + call
+ *   2. Add migration comment for setup/shutdown (removed in v2)
+ *
+ * Note: analytics/workbench STAY in createApp() — they are not moved anywhere.
+ * In v2, createApp() is the single source of truth for all runtime config.
+ *
+ * We use simple string-level surgery rather than a full AST round-trip so that
+ * formatting and comments are preserved.  The TypeScript API is used only for
+ * detection (already done in detect.ts); we apply regex-based patches here.
+ *
+ * COMPLEXITY GUARD: if the file contains anything we don't recognise (e.g. the
+ * giant generated/app.ts blob that v1 CLI wrote), we refuse to touch it and
+ * return a `complexityError`.
+ */
+
+import type { DetectionResult } from '../detect';
+
+export interface AppTsTransformResult {
+	/** The transformed source, or null if transformation was skipped */
+	source: string | null;
+	/** Set when the file is too complex for automated transformation */
+	complexityError?: string;
+	/** Informational messages about what was changed */
+	changes: string[];
+}
+
+/**
+ * Heuristics that identify the v1 *generated* app.ts (the 500-line blob the
+ * CLI wrote, not the user-facing app.ts).  If we detect these, we bail out
+ * because the user probably has a non-standard setup.
+ */
+const COMPLEXITY_MARKERS = [
+	'bootstrapRuntimeEnv',
+	'createBaseMiddleware',
+	'createOtelMiddleware',
+	'createAgentMiddleware',
+	'setGlobalLogger',
+	'setGlobalTracer',
+	'setGlobalRouter',
+	'getAppState',
+	'getAppConfig',
+	'getUserRouter',
+	'loadBuildMetadata',
+	'patchBunS3ForStorageDev',
+	'createWorkbenchRouter',
+	'injectAnalytics',
+	'registerAnalyticsRoutes',
+];
+
+/** How many complexity markers before we bail */
+const COMPLEXITY_THRESHOLD = 3;
+
+export function transformAppTs(source: string, detection: DetectionResult): AppTsTransformResult {
+	const changes: string[] = [];
+
+	// ── Complexity guard ───────────────────────────────────────────────────
+	const markerCount = COMPLEXITY_MARKERS.filter((m) => source.includes(m)).length;
+	if (markerCount >= COMPLEXITY_THRESHOLD) {
+		return {
+			source: null,
+			complexityError:
+				`app.ts appears to be the v1 CLI-generated entry file (detected ${markerCount} internal ` +
+				`framework markers). This file cannot be automatically migrated.\n` +
+				`\n` +
+				`Action required:\n` +
+				`  Replace app.ts with a clean v2 entry:\n` +
+				`\n` +
+				`     import { createApp } from '@agentuity/runtime';\n` +
+				`     import router from './src/api';\n` +
+				`     import agents from './src/agent';\n` +
+				`\n` +
+				`     const { server, logger } = await createApp({\n` +
+				`       router: { path: '/api', router },\n` +
+				`       agents,\n` +
+				`     });\n` +
+				`\n` +
+				`     logger.debug('Running %s', server.url);\n`,
+			changes: [],
+		};
+	}
+
+	let out = source;
+
+	// ── 1. Remove bootstrapRuntimeEnv import binding ──────────────────────
+	if (detection.bootstrapCallInAppTs) {
+		// Remove the named import specifier (handles both standalone and combined imports)
+		// e.g. import { bootstrapRuntimeEnv } from '@agentuity/runtime';
+		// e.g. import { createApp, bootstrapRuntimeEnv } from '@agentuity/runtime';
+		out = out.replace(
+			/import\s*\{([^}]*)\}\s*from\s*['"]@agentuity\/runtime['"]\s*;?/g,
+			(match, bindings: string) => {
+				const cleaned = bindings
+					.split(',')
+					.map((s) => s.trim())
+					.filter((s) => s && s !== 'bootstrapRuntimeEnv')
+					.join(', ');
+				if (!cleaned) return ''; // entire import removed
+				return match.replace(bindings, ` ${cleaned} `);
+			}
+		);
+
+		// Remove the standalone call — handles `await bootstrapRuntimeEnv();` with optional options
+		out = out.replace(/^\s*await\s+bootstrapRuntimeEnv\([^)]*\)\s*;?\s*\n?/gm, '');
+		out = out.replace(/^\s*bootstrapRuntimeEnv\([^)]*\)\s*;?\s*\n?/gm, '');
+
+		// Clean up any blank lines that result from the removal (max one blank line)
+		out = out.replace(/\n{3,}/g, '\n\n');
+
+		changes.push('Removed bootstrapRuntimeEnv() import and call');
+	}
+
+	// Note: analytics/workbench stay in createApp() in v2 - no migration needed
+
+	// ── 2. setup / shutdown scaffolding comment ───────────────────────────
+	if (detection.setupInCreateApp || detection.shutdownInCreateApp) {
+		// We do NOT remove setup/shutdown — they require human judgment.
+		// Instead, prepend a prominent comment block.
+		const comment =
+			`// ⚠️  MIGRATION REQUIRED — setup/shutdown removed in v2\n` +
+			`//\n` +
+			`// Move initialisation logic to module-level code (top of this file).\n` +
+			`// For cleanup, use Hono's standard patterns or Bun's process hooks:\n` +
+			`//\n` +
+			`//   process.on('beforeExit', async () => {\n` +
+			`//     // your cleanup here\n` +
+			`//   });\n` +
+			`//\n` +
+			`// Then remove the setup and shutdown props from createApp().\n`;
+
+		// Insert just before the createApp call
+		// Match: const { a, b } = await createApp  OR  const foo = await createApp  OR  export default await createApp
+		out = out.replace(
+			/(const|let|var)\s+(\{[^}]+\}|\w+)\s*=\s*await\s+createApp|export default await createApp/,
+			`${comment}\n$&`
+		);
+		changes.push('Added migration comment for setup/shutdown — manual action required');
+	}
+
+	return { source: out, changes };
+}

package/src/transforms/barrels.ts

@@ -0,0 +1,138 @@
+/**
+ * Transform: generate/update barrel files
+ *
+ *  • src/agent/index.ts  — exports default array of all agent runners
+ *  • src/api/index.ts    — exports composed Hono router + AppRouter type
+ *
+ * These are generated fresh; if a file already exists and is not the empty
+ * v1 stub we leave it alone (detection layer already decided).
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Agent barrel
+// ---------------------------------------------------------------------------
+
+interface AgentEntry {
+	importName: string; // camelCase identifier
+	relativePath: string; // './hello/agent'
+}
+
+function toImportName(agentDirName: string): string {
+	// kebab-case or snake_case → camelCase
+	return agentDirName
+		.split(/[-_]/)
+		.map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+		.join('');
+}
+
+function findAgentDirs(agentDir: string): AgentEntry[] {
+	if (!existsSync(agentDir)) return [];
+	const entries: AgentEntry[] = [];
+
+	for (const entry of readdirSync(agentDir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const agentFile = join(agentDir, entry.name, 'agent.ts');
+		if (existsSync(agentFile)) {
+			entries.push({
+				importName: toImportName(entry.name),
+				relativePath: `./${entry.name}/agent`,
+			});
+		}
+	}
+
+	return entries.sort((a, b) => a.importName.localeCompare(b.importName));
+}
+
+export function generateAgentBarrel(projectDir: string): string | null {
+	const agentDir = join(projectDir, 'src', 'agent');
+	const agents = findAgentDirs(agentDir);
+
+	if (agents.length === 0) return null;
+
+	const imports = agents
+		.map(({ importName, relativePath }) => `import ${importName} from '${relativePath}';`)
+		.join('\n');
+
+	const exportList = agents.map(({ importName }) => `\t${importName},`).join('\n');
+
+	return `${imports}\n\n` + `const agents = [\n${exportList}\n];\n\n` + `export default agents;\n`;
+}
+
+// ---------------------------------------------------------------------------
+// API barrel
+// ---------------------------------------------------------------------------
+
+interface RouteEntry {
+	importName: string; // camelCase identifier, e.g. `helloRouter`
+	mountPath: string; // '/hello'
+	relativePath: string; // './hello/route'
+}
+
+function toRouterImportName(routeDirName: string): string {
+	const camel = toImportName(routeDirName);
+	return `${camel}Router`;
+}
+
+function findRouteFiles(apiDir: string): RouteEntry[] {
+	if (!existsSync(apiDir)) return [];
+	const entries: RouteEntry[] = [];
+
+	for (const entry of readdirSync(apiDir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const routeFile = join(apiDir, entry.name, 'route.ts');
+		if (existsSync(routeFile)) {
+			entries.push({
+				importName: toRouterImportName(entry.name),
+				mountPath: `/${entry.name}`,
+				relativePath: `./${entry.name}/route`,
+			});
+		}
+	}
+
+	return entries.sort((a, b) => a.mountPath.localeCompare(b.mountPath));
+}
+
+export function generateApiBarrel(projectDir: string): string | null {
+	const apiDir = join(projectDir, 'src', 'api');
+	const routes = findRouteFiles(apiDir);
+
+	if (routes.length === 0) return null;
+
+	const imports = [
+		`import { Hono } from 'hono';`,
+		`import type { Env } from '@agentuity/runtime';`,
+		...routes.map(
+			({ importName, relativePath }) => `import ${importName} from '${relativePath}';`
+		),
+	].join('\n');
+
+	const chain = routes
+		.map(({ mountPath, importName }) => `\t.route('${mountPath}', ${importName})`)
+		.join('\n');
+
+	// The router MUST be built as a single chained expression so that TypeScript
+	// accumulates every route's schema into `typeof router` (AppRouter).
+	// Breaking the chain (e.g. separate `router.route(...)` statements) would
+	// produce an empty/incomplete AppRouter and break hc<AppRouter>() on the
+	// frontend.
+	//
+	// Frontend usage:
+	//   import { hc } from 'hono/client';
+	//   import type { AppRouter } from '../api';
+	//   const client = hc<AppRouter>(window.location.origin + '/api');
+	//   const res = await client.hello.$post({ json: { name: 'World' } });
+	return (
+		`${imports}\n\n` +
+		`// Routes are chained in a single expression so TypeScript can accumulate\n` +
+		`// every sub-router's schema into AppRouter — required for Hono RPC typing.\n` +
+		`const router = new Hono<Env>()\n${chain};\n\n` +
+		`// AppRouter is the fully-typed entry point for the Hono client.\n` +
+		`// Import it in your frontend:  import type { AppRouter } from '../api';\n` +
+		`// Then use:  hc<AppRouter>(window.location.origin + '/api')\n` +
+		`export type AppRouter = typeof router;\n\n` +
+		`export default router;\n`
+	);
+}

package/src/transforms/generated.ts

@@ -0,0 +1,11 @@
+/**
+ * Transform: delete src/generated/
+ *
+ * The generated directory is 100% CLI-managed in v1.  In v2 it is gone.
+ */
+
+import { rmSync } from 'node:fs';
+
+export function deleteGeneratedDir(generatedDir: string): void {
+	rmSync(generatedDir, { recursive: true, force: true });
+}

package/src/transforms/routes.ts

@@ -0,0 +1,273 @@
+/**
+ * Transform: v1 route files → v2 Hono chained style
+ *
+ * v1 pattern:
+ *   import { createRouter } from '@agentuity/runtime';
+ *   const router = createRouter();
+ *   router.get('/foo', handler);
+ *   router.post('/bar', handler);
+ *   export default router;
+ *
+ * v2 pattern:
+ *   import { Hono } from 'hono';
+ *   import type { Env } from '@agentuity/runtime';
+ *
+ *   const router = new Hono<Env>()
+ *     .get('/foo', handler)
+ *     .post('/bar', handler);
+ *
+ *   export default router;
+ *
+ * WHY CHAINING MATTERS — Hono RPC type inference:
+ *   Hono accumulates route types via TypeScript's return-type inference on
+ *   each chained call.  If you break the chain (e.g. `router.get(...)` on a
+ *   separate statement after the variable declaration), the Schema type
+ *   parameter never accumulates new routes and `typeof router` carries no
+ *   route information.  The chained style is the ONLY way to get the full
+ *   AppRouter type used by `hc<AppRouter>()` on the frontend.
+ *
+ *   Individual route files export a typed router; the barrel (src/api/index.ts)
+ *   composes them with `.route()` and re-exports `AppRouter = typeof router`.
+ *   Frontend code imports that type:
+ *
+ *     import { hc } from 'hono/client';
+ *     import type { AppRouter } from '../api';          // or wherever
+ *     const client = hc<AppRouter>(window.location.origin + '/api');
+ *     const res = await client.hello.$post({ json: { name: 'World' } });
+ *
+ * COMPLEXITY GUARD: if the file:
+ *   • Has more than one createRouter() call
+ *   • Uses variable re-assignment of the router variable
+ * …we refuse and return a complexityError.
+ */
+
+import ts from 'typescript';
+
+function capitalize(s: string): string {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export interface RouteTransformResult {
+	source: string | null;
+	complexityError?: string;
+	changes: string[];
+}
+
+// HTTP methods supported by Hono (chained)
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'all', 'route', 'use']);
+
+interface RouterCall {
+	method: string;
+	/** Full text of `router.<method>(args)` statement */
+	statementText: string;
+	/** Just the argument list text, e.g. `'/foo', handler` */
+	argsText: string;
+}
+
+export function transformRouteFile(source: string): RouteTransformResult {
+	const changes: string[] = [];
+
+	// ── Parse ──────────────────────────────────────────────────────────────
+	const sf = ts.createSourceFile('route.ts', source, ts.ScriptTarget.ESNext, true);
+
+	// ── Find createRouter() variable declaration ───────────────────────────
+	let routerVarName: string | null = null;
+
+	ts.forEachChild(sf, (node) => {
+		if (
+			ts.isVariableStatement(node) ||
+			(ts.isVariableDeclarationList(node) && node.declarations)
+		) {
+			const declList = ts.isVariableStatement(node)
+				? node.declarationList.declarations
+				: (node as ts.VariableDeclarationList).declarations;
+
+			for (const decl of declList) {
+				if (
+					decl.initializer &&
+					ts.isCallExpression(decl.initializer) &&
+					ts.isIdentifier(decl.initializer.expression) &&
+					decl.initializer.expression.text === 'createRouter' &&
+					ts.isIdentifier(decl.name)
+				) {
+					if (routerVarName !== null) {
+						return; // multiple createRouter calls
+					}
+					routerVarName = decl.name.text;
+				}
+			}
+		}
+	});
+
+	if (!routerVarName) {
+		// Not a v1 route file — nothing to do
+		return { source, changes: [] };
+	}
+
+	// ── Complexity checks ─────────────────────────────────────────────────
+
+	// Count how many times createRouter() is called
+	let createRouterCount = 0;
+	(source.match(/createRouter\s*\(/g) ?? []).forEach(() => createRouterCount++);
+	if (createRouterCount > 1) {
+		return {
+			source: null,
+			complexityError:
+				`Route file calls createRouter() ${createRouterCount} times. ` +
+				`Only a single top-level router variable is supported by the auto-migration.`,
+			changes: [],
+		};
+	}
+
+	// Check for re-assignment (after declaration)
+	// The initial `const router = createRouter()` is one match; any additional = re-assignment
+	const reassignPattern = new RegExp(`\\b${routerVarName}\\s*=(?!=)`, 'g');
+	const reassignMatches = source.match(reassignPattern) ?? [];
+	if (reassignMatches.length > 1) {
+		return {
+			source: null,
+			complexityError:
+				`Router variable '${routerVarName}' appears to be re-assigned. ` +
+				`This pattern cannot be automatically migrated.`,
+			changes: [],
+		};
+	}
+
+	// ── Collect router.<method>(...) calls ────────────────────────────────
+	const routerCalls: RouterCall[] = [];
+
+	ts.forEachChild(sf, (node) => {
+		if (!ts.isExpressionStatement(node)) return;
+		const expr = node.expression;
+		if (!ts.isCallExpression(expr)) return;
+		if (!ts.isPropertyAccessExpression(expr.expression)) return;
+		const obj = expr.expression.expression;
+		const method = expr.expression.name.text;
+
+		if (!ts.isIdentifier(obj) || obj.text !== routerVarName) return;
+		if (!HTTP_METHODS.has(method)) return;
+
+		const argsText = expr.arguments.map((a) => a.getText(sf)).join(', ');
+		const statementText = node.getText(sf);
+
+		routerCalls.push({ method, statementText, argsText });
+	});
+
+	if (routerCalls.length === 0) {
+		// createRouter() declared but no method calls — still rewrite the declaration
+	}
+
+	// ── Build replacement source ──────────────────────────────────────────
+
+	// 1. Replace `import { createRouter ... } from '@agentuity/runtime'` with
+	//    `import { Hono } from 'hono';` + `import type { Env } from '@agentuity/runtime';`
+	let out = source;
+
+	// Remove createRouter from the @agentuity/runtime import
+	out = out.replace(
+		/import\s*\{([^}]*)\}\s*from\s*['"]@agentuity\/runtime['"]\s*;?/g,
+		(_match, bindings: string) => {
+			const parts = bindings
+				.split(',')
+				.map((s) => s.trim())
+				.filter(Boolean);
+
+			const withoutCreateRouter = parts.filter((p) => p !== 'createRouter');
+
+			const runtimeParts = withoutCreateRouter.filter((p) => !p.startsWith('type '));
+			const typeParts = withoutCreateRouter
+				.filter((p) => p.startsWith('type '))
+				.map((p) => p.slice('type '.length).trim());
+
+			// Always add `Env` to the type imports from @agentuity/runtime
+			if (!typeParts.includes('Env')) typeParts.push('Env');
+
+			const lines: string[] = [];
+
+			if (runtimeParts.length > 0) {
+				lines.push(`import { ${runtimeParts.join(', ')} } from '@agentuity/runtime';`);
+			}
+			if (typeParts.length > 0) {
+				lines.push(`import type { ${typeParts.join(', ')} } from '@agentuity/runtime';`);
+			}
+
+			return lines.join('\n');
+		}
+	);
+
+	// Add `import { Hono } from 'hono';` if not already present
+	if (!out.includes("from 'hono'") && !out.includes('from "hono"')) {
+		// Insert after the last import statement
+		out = out.replace(
+			/^(import\s[^;]+;?\s*\n)(?!import\s)/m,
+			(match) => `import { Hono } from 'hono';\n${match}`
+		);
+	} else {
+		// Ensure Hono is in the existing hono import
+		out = out.replace(
+			/import\s*\{([^}]*)\}\s*from\s*['"]hono['"]\s*;?/,
+			(_match, bindings: string) => {
+				const parts = bindings
+					.split(',')
+					.map((s) => s.trim())
+					.filter(Boolean);
+				if (!parts.includes('Hono')) {
+					parts.unshift('Hono');
+				}
+				return `import { ${parts.join(', ')} } from 'hono';`;
+			}
+		);
+	}
+
+	// 2. Replace `const router = createRouter();` with `const router = new Hono<Env>()`
+	//    and fold the method calls into a chain.
+	const chainedCalls = routerCalls
+		.map(({ method, argsText }) => `\t.${method}(${argsText})`)
+		.join('\n');
+
+	const varDecl = `const ${routerVarName} = createRouter();`;
+
+	if (routerCalls.length > 0) {
+		const replacement = `const ${routerVarName} = new Hono<Env>()\n${chainedCalls};`;
+
+		// Remove individual router.<method>(...) statements
+		let modified = out;
+		for (const { statementText } of routerCalls) {
+			// Use a literal string replacement (not regex) to avoid special char issues
+			modified = modified.split(statementText).join('');
+		}
+
+		// Replace the createRouter() declaration
+		modified = modified.split(varDecl).join(replacement);
+
+		// Collapse extra blank lines
+		modified = modified.replace(/\n{3,}/g, '\n\n');
+
+		out = modified;
+		changes.push(
+			`Rewrote createRouter() declaration + ${routerCalls.length} method call(s) to chained Hono<Env>`
+		);
+	} else {
+		// No method calls — just swap the declaration
+		out = out.split(varDecl).join(`const ${routerVarName} = new Hono<Env>();`);
+		changes.push('Rewrote createRouter() declaration to new Hono<Env>()');
+	}
+
+	// Add `export type` for the router if not already exported.
+	// This lets the barrel (src/api/index.ts) compose routers in a
+	// fully-typed way, and downstream consumers can reference sub-router types.
+	const exportDefaultPattern = new RegExp(`export\\s+default\\s+${routerVarName}\\s*;?`);
+	if (exportDefaultPattern.test(out) && !out.includes(`export type`)) {
+		out = out.replace(
+			exportDefaultPattern,
+			`export type ${capitalize(routerVarName)}Type = typeof ${routerVarName};\n\nexport default ${routerVarName};`
+		);
+		changes.push(
+			`Added 'export type ${capitalize(routerVarName)}Type' for Hono RPC sub-router typing`
+		);
+	}
+
+	changes.push("Updated imports: added 'hono' import, replaced createRouter with Env type");
+
+	return { source: out, changes };
+}