@agentuity/migrate 3.0.0-alpha.0 → 3.0.0-alpha.1

package/src/transforms/v3/package-json.ts

@@ -0,0 +1,183 @@
+/**
+ * Transform: package.json for v2 → v3 migration.
+ *
+ * - Removes @agentuity/runtime
+ * - Adds hono and @agentuity/hono
+ * - Adds individual service packages based on detected usage
+ * - Bumps all @agentuity/* packages to ^3.0.0
+ * - Updates start script if it references old entry point
+ */
+
+import { SERVICE_PACKAGE_MAP, type V3OutdatedPackage } from '../../detect-v3';
+
+export interface V3PackageJsonResult {
+	/** Transformed package.json content, or null if no changes */
+	content: string | null;
+	/** Description of each change */
+	changes: string[];
+}
+
+/**
+ * Transform package.json for v3 migration.
+ */
+export function transformPackageJsonV3(
+	source: string,
+	outdatedPackages: V3OutdatedPackage[],
+	servicesUsed: string[],
+	options?: {
+		/** Whether the project had @agentuity/runtime */
+		removeRuntime?: boolean;
+		/** Whether to remove @agentuity/react */
+		removeReact?: boolean;
+		/** Dev scripts to add (from dev-setup transform) */
+		devScripts?: Record<string, string>;
+	}
+): V3PackageJsonResult {
+	const changes: string[] = [];
+	let pkg: Record<string, unknown>;
+
+	try {
+		pkg = JSON.parse(source);
+	} catch {
+		return { content: null, changes: ['Failed to parse package.json'] };
+	}
+
+	const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+	const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+	// ── 1. Remove @agentuity/runtime ──────────────────────────────────────
+	if (options?.removeRuntime && deps['@agentuity/runtime']) {
+		delete deps['@agentuity/runtime'];
+		changes.push('Removed @agentuity/runtime from dependencies');
+	}
+	if (options?.removeRuntime && devDeps['@agentuity/runtime']) {
+		delete devDeps['@agentuity/runtime'];
+		changes.push('Removed @agentuity/runtime from devDependencies');
+	}
+
+	// ── 2. Add hono ───────────────────────────────────────────────────────
+	if (!deps['hono']) {
+		deps['hono'] = '^4.0.0';
+		changes.push('Added hono@^4.0.0 to dependencies');
+	}
+
+	// ── 3. Add @agentuity/hono ────────────────────────────────────────────
+	if (!deps['@agentuity/hono']) {
+		deps['@agentuity/hono'] = '^3.0.0';
+		changes.push('Added @agentuity/hono@^3.0.0 to dependencies');
+	}
+
+	// ── 4. Add individual service packages based on usage ─────────────────
+	for (const service of servicesUsed) {
+		if (service === 'logger') {
+			// Logger comes from telemetry
+			if (!deps['@agentuity/telemetry']) {
+				deps['@agentuity/telemetry'] = '^3.0.0';
+				changes.push('Added @agentuity/telemetry@^3.0.0 (for logger)');
+			}
+			continue;
+		}
+
+		const mapping = SERVICE_PACKAGE_MAP[service];
+		if (!mapping) continue;
+
+		if (!deps[mapping.pkg]) {
+			deps[mapping.pkg] = '^3.0.0';
+			changes.push(`Added ${mapping.pkg}@^3.0.0 (${service} service detected in use)`);
+		}
+	}
+
+	// ── 5. Bump existing @agentuity/* packages to ^3.0.0 ──────────────────
+	for (const outdated of outdatedPackages) {
+		const section = outdated.section === 'dependencies' ? deps : devDeps;
+		if (section[outdated.name]) {
+			section[outdated.name] = '^3.0.0';
+			changes.push(`Updated ${outdated.name} ${outdated.currentVersion} → ^3.0.0`);
+		}
+	}
+
+	// ── 6. Remove @agentuity/react if requested ───────────────────────────
+	if (options?.removeReact) {
+		if (deps['@agentuity/react']) {
+			delete deps['@agentuity/react'];
+			changes.push('Removed @agentuity/react from dependencies (deprecated in v3)');
+		}
+		if (devDeps['@agentuity/react']) {
+			delete devDeps['@agentuity/react'];
+			changes.push('Removed @agentuity/react from devDependencies (deprecated in v3)');
+		}
+	}
+
+	// ── 7. Update scripts for new entry point ─────────────────────────
+	const scripts = (pkg.scripts ?? {}) as Record<string, string>;
+
+	// Replace app.ts references in existing scripts
+	if (scripts.start && scripts.start.includes('app.ts')) {
+		const oldStart = scripts.start;
+		scripts.start = scripts.start.replace('app.ts', 'src/index.ts');
+		changes.push(`Updated start script: "${oldStart}" → "${scripts.start}"`);
+	}
+	if (scripts.dev && scripts.dev.includes('app.ts')) {
+		const oldDev = scripts.dev;
+		scripts.dev = scripts.dev.replace('app.ts', 'src/index.ts');
+		changes.push(`Updated dev script: "${oldDev}" → "${scripts.dev}"`);
+	}
+
+	// Ensure a start script exists that points to the new entry point.
+	// The buildpack's generic detector uses this to determine how to run the app.
+	if (
+		!scripts.start ||
+		scripts.start.includes('.agentuity') ||
+		scripts.start.includes('agentuity')
+	) {
+		const oldStart = scripts.start;
+		scripts.start = 'bun src/index.ts';
+		if (oldStart) {
+			changes.push(`Replaced start script: "${oldStart}" → "${scripts.start}"`);
+		} else {
+			changes.push(`Added start script: "${scripts.start}"`);
+		}
+	}
+
+	// Apply dev scripts from dev-setup transform
+	if (options?.devScripts) {
+		for (const [name, value] of Object.entries(options.devScripts)) {
+			const old = scripts[name];
+			scripts[name] = value;
+			if (old) {
+				changes.push(`Updated ${name} script: "${old}" → "${value}"`);
+			} else {
+				changes.push(`Added ${name} script: "${value}"`);
+			}
+		}
+	}
+
+	// Write back
+	if (Object.keys(deps).length > 0) pkg.dependencies = deps;
+	if (Object.keys(devDeps).length > 0) pkg.devDependencies = devDeps;
+	if (Object.keys(scripts).length > 0) pkg.scripts = scripts;
+
+	if (changes.length === 0) {
+		return { content: null, changes: [] };
+	}
+
+	// Preserve the original indentation style
+	const indent = detectIndent(source);
+	return {
+		content: JSON.stringify(pkg, null, indent) + '\n',
+		changes,
+	};
+}
+
+/**
+ * Detect indentation (tab vs spaces) from package.json source.
+ */
+function detectIndent(source: string): string | number {
+	const match = source.match(/^(\s+)"/m);
+	if (match) {
+		const whitespace = match[1] ?? '\t';
+		if (whitespace.includes('\t')) return '\t';
+		return whitespace.length;
+	}
+	return '\t'; // default to tabs (project convention)
+}

package/src/transforms/v3/routes.ts

@@ -0,0 +1,185 @@
+/**
+ * Transform: rewrite service access in route files.
+ *
+ * Replaces c.var.kv, c.var.vector, etc. with direct imports from the
+ * shared services module.
+ *
+ * Uses string-level surgery rather than AST round-trip to preserve
+ * formatting and comments.
+ */
+
+import ts from 'typescript';
+import type { ServiceUsage } from '../../detect-v3';
+import { relative, dirname } from 'node:path';
+
+export interface RouteServiceTransformResult {
+	/** The transformed source, or null if no changes */
+	source: string | null;
+	/** What was changed */
+	changes: string[];
+}
+
+/**
+ * Rewrite c.var.* service access patterns to direct imports.
+ *
+ * @param source     - File source text
+ * @param usage      - Detected service usage info
+ * @param servicesRelativePath - Relative import path to services module (e.g., '../services')
+ */
+/**
+ * Remove all imports from @agentuity/runtime.
+ * In v3, this package is a deprecation stub — nothing should be imported from it.
+ */
+export function removeRuntimeImports(source: string): { source: string; removed: boolean } {
+	const pattern =
+		/import\s+(?:type\s+)?\{[^}]*\}\s*from\s*['"]@agentuity\/runtime['"]\s*;?\s*\n?/g;
+	const replaced = source.replace(pattern, '');
+	return { source: replaced, removed: replaced !== source };
+}
+
+export function transformRouteServices(
+	source: string,
+	usage: ServiceUsage,
+	servicesRelativePath: string
+): RouteServiceTransformResult {
+	let output = source;
+	const changes: string[] = [];
+	const servicesAdded = new Set<string>();
+
+	// Remove @agentuity/runtime imports (Env type, sse, stream, websocket, etc.)
+	const runtimeCleanup = removeRuntimeImports(output);
+	if (runtimeCleanup.removed) {
+		output = runtimeCleanup.source;
+		changes.push('Removed @agentuity/runtime imports');
+	}
+
+	if (usage.accessPattern === 'c.var') {
+		// Replace c.var.serviceName patterns
+		// We need to handle various Hono context variable names: c, ctx, context
+		const contextNames = ['c', 'ctx', 'context'];
+
+		for (const service of usage.services) {
+			for (const ctxName of contextNames) {
+				// Match: c.var.kv  c.var.vector  etc.
+				const pattern = new RegExp(`\\b${ctxName}\\.var\\.${service}\\b`, 'g');
+				if (pattern.test(output)) {
+					output = output.replace(pattern, service);
+					servicesAdded.add(service);
+					changes.push(`Replaced ${ctxName}.var.${service} → ${service}`);
+				}
+			}
+		}
+	} else if (usage.accessPattern === 'ctx') {
+		// Replace ctx.serviceName patterns (agent context)
+		const contextNames = ['ctx', 'context', 'c'];
+
+		for (const service of usage.services) {
+			for (const ctxName of contextNames) {
+				const pattern = new RegExp(`\\b${ctxName}\\.${service}\\b`, 'g');
+				if (pattern.test(output)) {
+					output = output.replace(pattern, service);
+					servicesAdded.add(service);
+					changes.push(`Replaced ${ctxName}.${service} → ${service}`);
+				}
+			}
+		}
+	}
+
+	// Clean up self-referencing declarations: `const kv = kv;` or `const stream = await stream.create(...)`
+	// These happen when the original code had `const kv = c.var.kv;`
+	if (servicesAdded.size > 0) {
+		for (const service of servicesAdded) {
+			// Pattern: const/let/var service = service; (entire line)
+			const selfRefPattern = new RegExp(
+				`^\\s*(?:const|let|var)\\s+${service}\\s*=\\s*${service}\\s*;?\\s*$`,
+				'gm'
+			);
+			if (selfRefPattern.test(output)) {
+				output = output.replace(selfRefPattern, '');
+				changes.push(`Removed self-referencing declaration: const ${service} = ${service}`);
+			}
+		}
+	}
+
+	// Add import for services if any were rewritten
+	if (servicesAdded.size > 0) {
+		const importList = [...servicesAdded].sort().join(', ');
+		const importLine = `import { ${importList} } from '${servicesRelativePath}';`;
+
+		// Check if there's already an import from the services module
+		const existingServicesImport = new RegExp(
+			`import\\s*\\{[^}]*\\}\\s*from\\s*['"]${escapeRegex(servicesRelativePath)}['"]`
+		);
+
+		if (existingServicesImport.test(output)) {
+			// Merge with existing import
+			output = output.replace(existingServicesImport, (match) => {
+				// Extract existing imports
+				const existingMatch = match.match(/\{([^}]*)\}/);
+				if (!existingMatch) return match;
+				const existing = existingMatch[1]!
+					.split(',')
+					.map((s) => s.trim())
+					.filter(Boolean);
+				const merged = [...new Set([...existing, ...servicesAdded])].sort();
+				return `import { ${merged.join(', ')} } from '${servicesRelativePath}'`;
+			});
+		} else {
+			// Insert new import after existing imports
+			output = insertAfterImports(output, importLine);
+		}
+
+		changes.push(`Added import for: ${importList}`);
+	}
+
+	if (changes.length === 0) {
+		return { source: null, changes: [] };
+	}
+
+	return { source: output, changes };
+}
+
+/**
+ * Compute the relative import path from a source file to src/services.ts.
+ */
+export function computeServicesRelativePath(projectDir: string, sourceFilePath: string): string {
+	const servicesPath = 'src/services';
+	const sourceDir = dirname(relative(projectDir, sourceFilePath));
+
+	let rel = relative(sourceDir, servicesPath);
+	// Ensure it starts with ./ or ../
+	if (!rel.startsWith('.')) {
+		rel = './' + rel;
+	}
+	// Remove .ts extension if present
+	rel = rel.replace(/\.ts$/, '');
+
+	return rel;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function insertAfterImports(source: string, importLine: string): string {
+	const sf = ts.createSourceFile('temp.ts', source, ts.ScriptTarget.ESNext, true);
+
+	let lastImportEnd = -1;
+	for (const stmt of sf.statements) {
+		if (ts.isImportDeclaration(stmt)) {
+			lastImportEnd = stmt.getEnd();
+		}
+	}
+
+	if (lastImportEnd >= 0) {
+		return (
+			source.substring(0, lastImportEnd) + '\n' + importLine + source.substring(lastImportEnd)
+		);
+	}
+
+	return importLine + '\n' + source;
+}
+
+function escapeRegex(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/transforms/v3/services.ts

@@ -0,0 +1,76 @@
+/**
+ * Transform: generate src/services.ts
+ *
+ * Creates a shared services module that exports singleton client instances
+ * for all Agentuity services detected in use across the project.
+ *
+ * Only includes services that are actually used — no unnecessary dependencies.
+ */
+
+import { SERVICE_PACKAGE_MAP } from '../../detect-v3';
+
+export interface ServicesFileResult {
+	/** Generated source for src/services.ts, or null if no services used */
+	source: string | null;
+	/** What was included */
+	changes: string[];
+}
+
+/**
+ * Generate src/services.ts based on detected service usage.
+ */
+export function generateServicesFile(servicesUsed: string[]): ServicesFileResult {
+	if (servicesUsed.length === 0) {
+		return { source: null, changes: [] };
+	}
+
+	const changes: string[] = [];
+	const imports: string[] = [];
+	const exports: string[] = [];
+
+	// Header comment
+	const header = [
+		'/**',
+		' * Shared Agentuity service clients.',
+		' *',
+		' * Auto-generated by @agentuity/migrate (v2 → v3 migration).',
+		' * Each client auto-configures from AGENTUITY_* environment variables.',
+		' *',
+		' * Usage:',
+		" *   import { kv, vector } from './services';",
+		" *   const data = await kv.get('namespace', 'key');",
+		' */',
+		'',
+	];
+
+	// Logger is special — comes from @agentuity/telemetry
+	const hasLogger = servicesUsed.includes('logger');
+	const serviceClients = servicesUsed.filter((s) => s !== 'logger');
+
+	// Generate import + export for each service client
+	for (const service of serviceClients.sort()) {
+		const mapping = SERVICE_PACKAGE_MAP[service];
+		if (!mapping) continue;
+
+		imports.push(`import { ${mapping.client} } from '${mapping.pkg}';`);
+		exports.push(`export const ${service} = new ${mapping.client}();`);
+		changes.push(`Added ${service} client from ${mapping.pkg}`);
+	}
+
+	// Logger from telemetry
+	if (hasLogger) {
+		imports.push("import { register } from '@agentuity/telemetry';");
+		exports.push('');
+		exports.push('/** Shared logger instance from telemetry */');
+		exports.push('const telemetry = register();');
+		exports.push('export const logger = telemetry.logger;');
+		changes.push('Added logger from @agentuity/telemetry');
+	}
+
+	const lines = [...header, ...imports, '', ...exports, ''];
+
+	return {
+		source: lines.join('\n'),
+		changes,
+	};
+}