@agentuity/migrate 2.0.11 → 3.0.0-alpha.1

package/bin/migrate.ts

@@ -9,14 +9,18 @@
  * Options:
  *   --yes, -y        Skip interactive confirmation prompts
  *   --dry-run        Print migration report without modifying any files
+ *   --v1-to-v2       Force v1 → v2 migration mode
+ *   --v2-to-v3       Force v2 → v3 migration mode
  *   --help, -h       Show this help message
  */
 
+export {};
+
 const args = process.argv.slice(2);
 
 if (args.includes('--help') || args.includes('-h')) {
 	console.log(`
-  ${'\x1b[1m'}@agentuity/migrate${'\x1b[0m'} — Migrate an Agentuity SDK v1 project to v2
+  ${'\x1b[1m'}@agentuity/migrate${'\x1b[0m'} — Migrate Agentuity SDK projects
 
   ${'\x1b[2m'}Usage:${'\x1b[0m'}
     npx @agentuity/migrate [project-dir] [options]
@@ -27,17 +31,29 @@ if (args.includes('--help') || args.includes('-h')) {
   ${'\x1b[2m'}Options:${'\x1b[0m'}
     --yes, -y          Skip interactive confirmation prompts
     --dry-run          Print the migration report without modifying any files
+    --v1-to-v2         Force v1 → v2 migration mode
+    --v2-to-v3         Force v2 → v3 migration mode
     --help, -h         Show this help message
 
-  ${'\x1b[2m'}What it does:${'\x1b[0m'}
-    • Detects v1 patterns (generated dir, old createApp config, mutable routes…)
-    • Prints a categorised report: auto-fixable, guided, and manual changes
-    • Asks for confirmation, then applies mechanical codemods
+  ${'\x1b[2m'}Auto-detection:${'\x1b[0m'}
+    The tool reads package.json and picks the right migration automatically:
+    • @agentuity/runtime ^1.x → runs v1 → v2 migration
+    • @agentuity/runtime ^2.x → runs v2 → v3 migration
+    • Use --v1-to-v2 or --v2-to-v3 to override detection
+
+  ${'\x1b[2m'}v1 → v2 migration:${'\x1b[0m'}
     • Rewrites route files to chained  new Hono<Env>()  style
     • Generates  src/api/index.ts  and  src/agent/index.ts  barrel files
     • Removes  src/generated/  directory
-    • Guides you to delete  agentuity.config.ts  (config now in createApp/vite.config)
-    • Runs  tsc --noEmit  to verify no type errors were introduced
+    • Updates @agentuity/* packages to ^2.0.0
+
+  ${'\x1b[2m'}v2 → v3 migration:${'\x1b[0m'}
+    • Replaces createApp() with plain Hono app + @agentuity/hono middleware
+    • Converts simple agents to plain exported functions
+    • Generates src/services.ts with singleton service clients
+    • Rewrites c.var.*/ctx.* service access to direct imports
+    • Moves entry point from app.ts → src/index.ts
+    • Removes @agentuity/runtime, adds hono + service packages
 
   ${'\x1b[2m'}Safety:${'\x1b[0m'}
     The tool checks that your git worktree is clean before making any changes,
@@ -49,12 +65,79 @@ if (args.includes('--help') || args.includes('-h')) {
 // Parse flags
 const yes = args.includes('--yes') || args.includes('-y');
 const dryRun = args.includes('--dry-run');
+const forceV1toV2 = args.includes('--v1-to-v2');
+const forceV2toV3 = args.includes('--v2-to-v3');
 
 // First non-flag argument is the project dir
 const projectDir = args.find((a) => !a.startsWith('-')) ?? process.cwd();
 
-const { migrate } = await import('../src/migrate');
+// ---------------------------------------------------------------------------
+// Auto-detect migration mode from package.json
+// ---------------------------------------------------------------------------
+
+async function detectMigrationMode(dir: string): Promise<'v1-to-v2' | 'v2-to-v3' | null> {
+	try {
+		const pkgPath = `${dir}/package.json`;
+		const file = Bun.file(pkgPath);
+		if (!(await file.exists())) return null;
+
+		const pkg = JSON.parse(await file.text());
+		const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+		const runtimeVersion = deps['@agentuity/runtime'];
+
+		if (!runtimeVersion) return null;
+
+		// ^1.x or 1.x → v1 to v2
+		if (/^[~^]?1\./.test(runtimeVersion) || runtimeVersion === '1') {
+			return 'v1-to-v2';
+		}
 
-const result = await migrate({ projectDir, yes, dryRun });
+		// ^2.x or 2.x or latest or * or workspace:* → v2 to v3
+		if (
+			/^[~^]?2\./.test(runtimeVersion) ||
+			runtimeVersion === 'latest' ||
+			runtimeVersion === '*' ||
+			runtimeVersion.startsWith('workspace:')
+		) {
+			return 'v2-to-v3';
+		}
 
-process.exit(result.ok ? 0 : 1);
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+// Determine which migration to run
+let mode: 'v1-to-v2' | 'v2-to-v3';
+
+if (forceV1toV2) {
+	mode = 'v1-to-v2';
+} else if (forceV2toV3) {
+	mode = 'v2-to-v3';
+} else {
+	const detected = await detectMigrationMode(projectDir);
+	if (!detected) {
+		console.error(
+			'\n  \x1b[31m✗\x1b[0m  Could not detect migration mode.\n\n' +
+				'     No @agentuity/runtime found in package.json, or version is not\n' +
+				'     recognized as v1.x or v2.x.\n\n' +
+				'     Use --v1-to-v2 or --v2-to-v3 to specify the migration explicitly.\n'
+		);
+		process.exit(1);
+	}
+	mode = detected;
+}
+
+// Run the appropriate migration
+if (mode === 'v1-to-v2') {
+	console.log('\n  \x1b[36mℹ\x1b[0m  Detected v1 project — running v1 → v2 migration\n');
+	const { migrate } = await import('../src/migrate');
+	const result = await migrate({ projectDir, yes, dryRun });
+	process.exit(result.ok ? 0 : 1);
+} else {
+	console.log('\n  \x1b[36mℹ\x1b[0m  Detected v2 project — running v2 → v3 migration\n');
+	const { migrateV3 } = await import('../src/migrate-v3');
+	const result = await migrateV3({ projectDir, yes, dryRun });
+	process.exit(result.ok ? 0 : 1);
+}

package/dist/detect-v3.d.ts

@@ -0,0 +1,92 @@
+/**
+ * V2 → V3 pattern detection.
+ *
+ * Analyses a project directory and returns a structured report of every v2
+ * artefact that needs to be migrated to v3 (framework-agnostic Hono).
+ * No files are modified here.
+ */
+export type Severity = 'auto' | 'guided' | 'manual';
+export interface V3Finding {
+    id: string;
+    severity: Severity;
+    message: string;
+    file?: string;
+    hint?: string;
+}
+/** Classification of agent complexity */
+export type AgentComplexity = 'simple' | 'complex';
+/** Detected agent file */
+export interface AgentFile {
+    /** Absolute path */
+    path: string;
+    /** Relative path from project root */
+    relativePath: string;
+    /** Agent name passed to createAgent() */
+    name: string;
+    /** Whether the agent is simple (handler+schema only) or complex */
+    complexity: AgentComplexity;
+    /** Reason for complexity classification (if complex) */
+    complexityReason?: string;
+    /** Whether the agent uses schema validation */
+    hasSchema: boolean;
+    /** Services accessed via ctx.* */
+    ctxServices: string[];
+}
+/** Detected service usage in a file */
+export interface ServiceUsage {
+    /** Absolute path */
+    path: string;
+    /** Relative path from project root */
+    relativePath: string;
+    /** Services used: 'kv' | 'vector' | 'stream' | 'queue' | 'email' | 'task' | 'schedule' | 'sandbox' | 'logger' */
+    services: string[];
+    /** Access pattern: 'ctx' (agent context) | 'c.var' (Hono context) */
+    accessPattern: 'ctx' | 'c.var';
+}
+/** Outdated package that needs version update */
+export interface V3OutdatedPackage {
+    name: string;
+    currentVersion: string;
+    section: 'dependencies' | 'devDependencies';
+}
+export interface V3DetectionResult {
+    projectDir: string;
+    findings: V3Finding[];
+    /** Whether the project has @agentuity/runtime in package.json */
+    hasRuntimeDep: boolean;
+    /** Version of @agentuity/runtime if found */
+    runtimeVersion?: string;
+    /** Absolute path to app.ts, if found */
+    appTsPath?: string;
+    /** Whether app.ts uses createApp from @agentuity/runtime */
+    hasCreateApp: boolean;
+    /** Properties passed to createApp() */
+    createAppProps: string[];
+    /** Detected agent files */
+    agentFiles: AgentFile[];
+    /** Whether src/agent/index.ts barrel exists */
+    hasAgentBarrel: boolean;
+    /** Service usage across all scanned files */
+    serviceUsages: ServiceUsage[];
+    /** Deduplicated set of all services used anywhere */
+    allServicesUsed: string[];
+    /** Whether src/web/ exists (SPA) */
+    hasFrontend: boolean;
+    /** Whether agentuity.config.ts exists */
+    hasAgentuityConfig: boolean;
+    /** Whether vite.config.ts exists */
+    hasViteConfig: boolean;
+    /** @agentuity/* packages that need version upgrade */
+    outdatedPackages: V3OutdatedPackage[];
+    /** Whether @agentuity/react is used */
+    hasReactPackage: boolean;
+    /** Whether @agentuity/frontend is used */
+    hasFrontendPackage: boolean;
+}
+/** Map from service name to package */
+export declare const SERVICE_PACKAGE_MAP: Record<string, {
+    pkg: string;
+    client: string;
+}>;
+export declare function detectV3(projectDir: string): Promise<V3DetectionResult>;
+//# sourceMappingURL=detect-v3.d.ts.map

package/dist/detect-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-v3.d.ts","sourceRoot":"","sources":["../src/detect-v3.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,yCAAyC;AACzC,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnD,0BAA0B;AAC1B,MAAM,WAAW,SAAS;IACzB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,EAAE,eAAe,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;IACnB,kCAAkC;IAClC,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC5B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,iHAAiH;IACjH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qEAAqE;IACrE,aAAa,EAAE,KAAK,GAAG,OAAO,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,EAAE,CAAC;IAEtB,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,uCAAuC;IACvC,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,2BAA2B;IAC3B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,+CAA+C;IAC/C,cAAc,EAAE,OAAO,CAAC;IAExB,6CAA6C;IAC7C,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,qDAAqD;IACrD,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,oCAAoC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,oCAAoC;IACpC,aAAa,EAAE,OAAO,CAAC;IAEvB,sDAAsD;IACtD,gBAAgB,EAAE,iBAAiB,EAAE,CAAC;IAEtC,uCAAuC;IACvC,eAAe,EAAE,OAAO,CAAC;IACzB,0CAA0C;IAC1C,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAoBD,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAS/E,CAAC;AA0UF,wBAAsB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgZ7E"}