@agentuity/migrate 2.0.10 → 3.0.0-alpha.0

package/README.md

@@ -4,7 +4,7 @@ CLI tool to migrate Agentuity SDK projects from v1 to v2.
 
 ## What's Changed in v2
 
-v2 introduces six fundamental architectural changes:
+v2 introduces seven fundamental architectural changes:
 
 ### 1. Agents are Declarative
 
@@ -14,10 +14,10 @@ v2 introduces six fundamental architectural changes:
 
 ```typescript
 import { createApp } from '@agentuity/runtime';
-import * as agents from './agent'; // Barrel export
+import agents from './agent'; // Barrel default export (AgentRunner[])
 
-export default createApp({
-  agents, // Explicit declaration
+export default await createApp({
+  agents,
 });
 ```
 
@@ -33,28 +33,29 @@ createApp({
 ```
 
 **v2**: Use standard patterns:
-- **Initialization**: Module-level code (runs when file loads)
-- **Cleanup**: Hono middleware or Bun's `process.on('beforeExit', ...)`
+- **Initialization**: Module-level code only for env-independent setup
+  (for env-dependent SDK clients, initialize inside agent `setup()`)
+- **Cleanup**: `registerShutdownHook()` from `@agentuity/runtime`, or Bun's `process.on('beforeExit', ...)`
 
-### 3. Router is Required
+### 3. Explicit Router Configuration
 
 **v1**: File-based auto-discovery — routes in `src/api/*.ts` were automatically mounted.
 
-**v2**: You must explicitly provide a router to `createApp()`:
+**v2**: Routes are explicitly provided to `createApp()` when needed:
 
 ```typescript
 import router from './api'; // Your Hono router
 
-export default createApp({
-  router, // Required — no more auto-discovery
+export default await createApp({
+  router,
 });
 ```
 
 The old file-based approach no longer works. Routes must be composed into a barrel (`src/api/index.ts`) and exported as a Hono instance.
 
-### 4. Use Hono Directly (No createRouter)
+### 4. Hono-Based Routing
 
-**v1**: `createRouter()` was a wrapper around Hono:
+**v1**: `createRouter()` was a wrapper around Hono using mutating methods:
 
 ```typescript
 import { createRouter } from '@agentuity/runtime';
@@ -63,9 +64,16 @@ const router = createRouter();
 router.get('/hello', async (c) => c.json({ msg: 'hi' }));
 ```
 
-**v2**: Use Hono directly with chained methods:
+**v2**: Use `createRouter()` or `new Hono<Env>()` with chained methods:
 
 ```typescript
+// Option A: createRouter() from @agentuity/runtime
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter()
+  .get('/hello', async (c) => c.json({ msg: 'hi' }));
+
+// Option B: plain Hono instance
 import { Hono } from 'hono';
 import type { Env } from '@agentuity/runtime';
 
@@ -75,7 +83,7 @@ const router = new Hono<Env>()
 
 ### 5. React Helpers Removed
 
-**v1**: `@agentuity/react` exported `createClient`, `useAPI`, `RPCRouteRegistry` for API calls.
+**v1**: `@agentuity/react` exported `createClient`, `useAPI`, `useAgentuity`, `RPCRouteRegistry` for API calls.
 
 **v2**: These are removed. Use your preferred data fetching library:
 - **Hono client directly**: `hc<AppRouter>()` from `hono/client`
@@ -123,13 +131,34 @@ export default defineConfig({
 // app.ts
 import { createApp } from '@agentuity/runtime';
 
-export default createApp({
+export default await createApp({
   analytics: true,
   workbench: true,
 });
 ```
 
 > **Note**: v2 doesn't include a default Vite plugin. You must add the plugin for your frontend framework (React, Vue, Svelte, Solid, etc.).
+>
+> **Note**: If your frontend entry is at `src/web/index.html` (not the project root), either add `build.rollupOptions.input` to your config, or omit `vite.config.ts` entirely and let the CLI generate a correct fallback.
+
+### 7. Build-Time Agent Imports
+
+v2's build system imports agent files at build time to extract metadata. Module-scope code that requires environment variables (like `new OpenAI()`) will fail during `agentuity build`.
+
+Move SDK client constructors into the agent's `setup()` function:
+
+```typescript
+// ❌ Fails at build time (module scope)
+const openai = new OpenAI();
+
+// ✅ Runs at startup (agent setup)
+export default createAgent('my-agent', {
+  setup: async () => ({ openai: new OpenAI() }),
+  handler: async (ctx, input) => {
+    const result = await ctx.config.openai.chat.completions.create({...});
+  },
+});
+```
 
 ---
 
@@ -166,7 +195,7 @@ Run in your project root (or pass a path). The tool checks that your **git workt
 | Finding | What happens |
 |---|---|
 | `setup` in `createApp()` | Migration comment added — move init to module level |
-| `shutdown` in `createApp()` | Guidance to use Hono's lifecycle hooks instead |
+| `shutdown` in `createApp()` | Guidance to use `registerShutdownHook()` from `@agentuity/runtime` instead |
 | No `router`/`agents` in `createApp()` | Guidance shown — wire up the generated barrels |
 | `agentuity.config.ts` has Vite keys | Guidance to create `vite.config.ts` with plugins/define/render/bundle |
 | `agentuity.config.ts` has analytics/workbench | Remove — keep only in `createApp()` |
@@ -200,4 +229,4 @@ Run in your project root (or pass a path). The tool checks that your **git workt
 
 **Setup/shutdown lifecycle**
 - v1: `createApp({ setup, shutdown })` with generic state via `ctx.app`
-- v2: Use Hono's standard patterns — module-level initialization and Hono lifecycle hooks
+- v2: Module-level init for env-independent setup; agent `setup()` for SDK clients; `registerShutdownHook()` for cleanup

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/migrate",
-	"version": "2.0.10",
+	"version": "3.0.0-alpha.0",
 	"description": "Migration tool from Agentuity SDK v1 to v2",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
@@ -30,16 +30,21 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "2.0.10",
+		"@agentuity/core": "3.0.0-alpha.0",
 		"typescript": "^5.9.0"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "2.0.10",
+		"@agentuity/test-utils": "3.0.0-alpha.0",
 		"@types/bun": "latest",
 		"bun-types": "latest"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"sideEffects": false
+	"sideEffects": false,
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/agentuity/sdk.git",
+		"directory": "packages/migrate"
+	}
 }