@agentuity/migrate 2.0.0-beta.1

package/README.md

@@ -0,0 +1,203 @@
+# @agentuity/migrate
+
+CLI tool to migrate Agentuity SDK projects from v1 to v2.
+
+## What's Changed in v2
+
+v2 introduces six fundamental architectural changes:
+
+### 1. Agents are Declarative
+
+**v1**: Agents were auto-discovered from `src/agent/*/agent.ts` files at runtime.
+
+**v2**: Agents must be explicitly imported and passed to `createApp()`:
+
+```typescript
+import { createApp } from '@agentuity/runtime';
+import * as agents from './agent'; // Barrel export
+
+export default createApp({
+  agents, // Explicit declaration
+});
+```
+
+### 2. No More setup/shutdown Hooks
+
+**v1**: Lifecycle hooks in `createApp()`:
+
+```typescript
+createApp({
+  setup: async (ctx) => { /* initialize */ },
+  shutdown: async (ctx) => { /* cleanup */ }
+});
+```
+
+**v2**: Use standard patterns:
+- **Initialization**: Module-level code (runs when file loads)
+- **Cleanup**: Hono middleware or Bun's `process.on('beforeExit', ...)`
+
+### 3. Router is Required
+
+**v1**: File-based auto-discovery — routes in `src/api/*.ts` were automatically mounted.
+
+**v2**: You must explicitly provide a router to `createApp()`:
+
+```typescript
+import router from './api'; // Your Hono router
+
+export default createApp({
+  router, // Required — no more auto-discovery
+});
+```
+
+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)
+
+**v1**: `createRouter()` was a wrapper around Hono:
+
+```typescript
+import { createRouter } from '@agentuity/runtime';
+
+const router = createRouter();
+router.get('/hello', async (c) => c.json({ msg: 'hi' }));
+```
+
+**v2**: Use Hono directly with chained methods:
+
+```typescript
+import { Hono } from 'hono';
+import type { Env } from '@agentuity/runtime';
+
+const router = new Hono<Env>()
+  .get('/hello', async (c) => c.json({ msg: 'hi' }));
+```
+
+### 5. React Helpers Removed
+
+**v1**: `@agentuity/react` exported `createClient`, `useAPI`, `RPCRouteRegistry` for API calls.
+
+**v2**: These are removed. Use your preferred data fetching library:
+- **Hono client directly**: `hc<AppRouter>()` from `hono/client`
+- **TanStack Query**: Combine with Hono client for caching, background updates
+- **SWR**: Stale-while-revalidate pattern
+- **RTK Query**: If already using Redux Toolkit
+
+Example with TanStack Query:
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { hc } from 'hono/client';
+import type { AppRouter } from '../api';
+
+const client = hc<AppRouter>('/api');
+
+function useHello() {
+  return useQuery({
+    queryKey: ['hello'],
+    queryFn: async () => {
+      const res = await client.hello.$get();
+      return res.json();
+    },
+  });
+}
+```
+
+### 6. Standard vite.config.ts
+
+**v1**: Vite config lived inside `agentuity.config.ts` along with workbench settings.
+
+**v2**: Use standard `vite.config.ts` for build config; runtime settings go in `createApp()`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()], // Add your frontend framework's plugin
+});
+```
+
+```typescript
+// app.ts
+import { createApp } from '@agentuity/runtime';
+
+export default 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.).
+
+---
+
+## Usage
+
+```bash
+npx @agentuity/migrate [project-dir] [options]
+```
+
+Run in your project root (or pass a path). The tool checks that your **git worktree is clean** before touching anything, so you can always `git diff` to review changes or `git checkout .` to roll back.
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--yes`, `-y` | Skip interactive confirmation |
+| `--dry-run` | Print the migration report without modifying files |
+| `--help`, `-h` | Show help |
+
+## What it migrates
+
+### Auto-fixable (fully automated)
+
+| Finding | Action |
+|---|---|
+| `src/generated/` directory | Deleted |
+| `bootstrapRuntimeEnv()` call in `app.ts` | Removed (createApp handles it) |
+| v1 `createRouter()` + mutating `.get()/.post()` route files | Rewritten to `new Hono<Env>()` chained style |
+| Missing `src/api/index.ts` barrel | Generated from discovered route files |
+| Missing `src/agent/index.ts` barrel | Generated from discovered agent files |
+
+### Guided (applied with your review)
+
+| 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 |
+| 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()` |
+| `agentuity.config.ts` empty | Can be deleted |
+
+### Manual (instructions only, no auto-transform)
+
+| Finding | Guidance |
+|---|---|
+| Frontend files using `createClient`, `useAPI`, `useAgentuity`, `RPCRouteRegistry` etc. | Replace with `hc<AppRouter>()` from `hono/client` or your preferred data fetching library |
+
+## V1 → V2 changes summary
+
+**Configuration (consolidated)**
+- v1: Config split between `app.ts` and `agentuity.config.ts`
+- v2: **All runtime config in `createApp()`** — analytics, workbench, cors, compression, etc.
+- v2: **Vite config in `vite.config.ts`** — plugins, define, render, bundle
+- v2: `agentuity.config.ts` is **deprecated** — delete it
+
+**`app.ts` entrypoint**
+- v1: thin shell; CLI generated a 500-line `src/generated/app.ts`
+- v2: `app.ts` is the real entrypoint; `createApp()` handles all lifecycle
+
+**Routing**
+- v1: file-based auto-discovery + `createRouter()` mutating style
+- v2: explicit `src/api/index.ts` barrel + `new Hono<Env>()` chained style
+
+**Type-safe API client**
+- v1: `createClient<RPCRouteRegistry>()` from `@agentuity/react`
+- v2: `hc<AppRouter>()` from `hono/client` — Hono's native RPC inference
+
+**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

package/bin/migrate.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+
+/**
+ * @agentuity/migrate CLI entry point
+ *
+ * Usage:
+ *   npx @agentuity/migrate [project-dir] [options]
+ *
+ * Options:
+ *   --yes, -y        Skip interactive confirmation prompts
+ *   --dry-run        Print migration report without modifying any files
+ *   --help, -h       Show this help message
+ */
+
+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[2m'}Usage:${'\x1b[0m'}
+    npx @agentuity/migrate [project-dir] [options]
+
+  ${'\x1b[2m'}Arguments:${'\x1b[0m'}
+    project-dir        Path to the project to migrate (default: current directory)
+
+  ${'\x1b[2m'}Options:${'\x1b[0m'}
+    --yes, -y          Skip interactive confirmation prompts
+    --dry-run          Print the migration report without modifying any files
+    --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
+    • 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
+
+  ${'\x1b[2m'}Safety:${'\x1b[0m'}
+    The tool checks that your git worktree is clean before making any changes,
+    so you can always review the diff or roll back with  git checkout .
+`);
+	process.exit(0);
+}
+
+// Parse flags
+const yes = args.includes('--yes') || args.includes('-y');
+const dryRun = args.includes('--dry-run');
+
+// First non-flag argument is the project dir
+const projectDir = args.find((a) => !a.startsWith('-')) ?? process.cwd();
+
+const { migrate } = await import('../src/migrate');
+
+const result = await migrate({ projectDir, yes, dryRun });
+
+process.exit(result.ok ? 0 : 1);

package/dist/detect.d.ts

@@ -0,0 +1,56 @@
+/**
+ * V1 pattern detection.
+ *
+ * Analyses a project directory and returns a structured report of every v1
+ * artefact that needs to be migrated to v2.  No files are modified here.
+ */
+/** Severity of a finding — drives the interactive prompt */
+export type Severity = 'auto' | 'guided' | 'manual';
+export interface Finding {
+    /** Short identifier used to reference this finding in transforms */
+    id: string;
+    severity: Severity;
+    /** Human-readable summary */
+    message: string;
+    /** File relative to project root, or undefined for project-level findings */
+    file?: string;
+    /** Extra detail or migration hint shown in the report */
+    hint?: string;
+}
+export interface DetectionResult {
+    projectDir: string;
+    /** All findings, ordered by severity (auto → guided → manual) */
+    findings: Finding[];
+    /** Absolute path to app.ts, if found */
+    appTsPath?: string;
+    /** Absolute path to src/generated dir, if it exists */
+    generatedDir?: string;
+    /** Absolute paths of route files detected as v1-style (mutating createRouter) */
+    v1RouteFiles: string[];
+    /** Absolute paths of route files already in v2-style (chained Hono) */
+    v2RouteFiles: string[];
+    /** Whether src/agent/index.ts barrel exists */
+    hasAgentBarrel: boolean;
+    /** Whether src/api/index.ts barrel exists */
+    hasApiBarrel: boolean;
+    /** Whether agentuity.config.ts exists */
+    hasAgentuityConfig: boolean;
+    /** Whether app.ts passes analytics/workbench inside createApp() */
+    analyticsInCreateApp: boolean;
+    workbenchInCreateApp: boolean;
+    /** Whether app.ts passes setup/shutdown inside createApp() */
+    setupInCreateApp: boolean;
+    shutdownInCreateApp: boolean;
+    /** Whether app.ts calls bootstrapRuntimeEnv() */
+    bootstrapCallInAppTs: boolean;
+    /** Whether frontend code uses removed APIs */
+    frontendRemovedApis: FrontendFinding[];
+}
+export interface FrontendFinding {
+    file: string;
+    apis: string[];
+    /** APIs that are deprecated (still work but should migrate away) */
+    deprecatedApis?: string[];
+}
+export declare function detect(projectDir: string): Promise<DetectionResult>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,4DAA4D;AAC5D,MAAM,MAAM,QAAQ,GACjB,MAAM,GACN,QAAQ,GACR,QAAQ,CAAC;AAEZ,MAAM,WAAW,OAAO;IACvB,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+CAA+C;IAC/C,cAAc,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,YAAY,EAAE,OAAO,CAAC;IACtB,yCAAyC;IACzC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mEAAmE;IACnE,oBAAoB,EAAE,OAAO,CAAC;IAC9B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,8DAA8D;IAC9D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iDAAiD;IACjD,oBAAoB,EAAE,OAAO,CAAC;IAC9B,8CAA8C;IAC9C,mBAAmB,EAAE,eAAe,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AA4PD,wBAAsB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAqXzE"}