@mandujs/mcp 0.20.6 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.20.6",
+  "version": "0.21.0",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,9 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.29.0",
+    "@mandujs/core": "^0.31.0",
     "@mandujs/ate": "^0.19.1",
-    "@mandujs/skills": "^8.0.1",
+    "@mandujs/skills": "^10.0.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "engines": {

package/src/tools/extract-contract.ts

@@ -0,0 +1,406 @@
+/**
+ * MCP tool — `mandu.refactor.extract_contract`
+ *
+ * Scans `app/api/**\/route.ts` for inline ad-hoc Zod schemas and extracts
+ * each into a sibling contract module following the `defineContract()`
+ * convention from `@mandujs/core`.
+ *
+ * Detection is conservative: we look for `z.object({ … })` literals bound
+ * to a local identifier (`const FooSchema = z.object({ … })`). We do NOT
+ * attempt to re-parse the route handler — extraction emits a new file and
+ * leaves a `TODO` comment next to each source site instructing the author
+ * to swap to the contract import. The intent is "halfway refactor"
+ * assistance, not a full AST-level transform.
+ *
+ * Output format:
+ *   For `app/api/users/route.ts` containing
+ *     `const CreateUser = z.object({ name: z.string() });`
+ *   we emit `contract/users.contract.ts`:
+ *     ```ts
+ *     import { z } from "zod";
+ *     import { defineContract } from "@mandujs/core";
+ *     export const usersContract = defineContract({
+ *       create: {
+ *         method: "POST",
+ *         path: "/api/users",
+ *         input: z.object({ name: z.string() }),
+ *         output: z.unknown(),
+ *       },
+ *     });
+ *     ```
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { readdir } from "fs/promises";
+import path from "path";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ExtractContractInput {
+  dryRun?: boolean;
+  route?: string;
+}
+
+export interface ExtractedContractEntry {
+  route: string;
+  contractFile: string;
+  schemaName: string;
+  sourceFile: string;
+}
+
+export interface ExtractContractResult {
+  extracted: ExtractedContractEntry[];
+  skipped: Array<{ route: string; reason: string }>;
+  dryRun: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────
+
+function validateInput(
+  raw: Record<string, unknown>,
+):
+  | { ok: true; value: { dryRun: boolean; route?: string } }
+  | { ok: false; error: string; field: string; hint: string } {
+  const dryRun = raw.dryRun;
+  if (dryRun !== undefined && typeof dryRun !== "boolean") {
+    return {
+      ok: false,
+      error: "'dryRun' must be a boolean",
+      field: "dryRun",
+      hint: "Omit to default to true",
+    };
+  }
+  const route = raw.route;
+  if (route !== undefined && typeof route !== "string") {
+    return {
+      ok: false,
+      error: "'route' must be a string",
+      field: "route",
+      hint: "E.g. 'app/api/users'",
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      dryRun: dryRun === undefined ? true : dryRun,
+      ...(typeof route === "string" ? { route } : {}),
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Route discovery — find `app/api/**\/route.ts(x)` files
+// ─────────────────────────────────────────────────────────────────────────
+
+async function findApiRoutes(projectRoot: string): Promise<string[]> {
+  const apiDir = path.join(projectRoot, "app", "api");
+  const out: string[] = [];
+  await walkApi(apiDir, out);
+  return out.sort();
+}
+
+async function walkApi(dir: string, out: string[]): Promise<void> {
+  let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === "node_modules" || e.name.startsWith("_")) continue;
+      await walkApi(full, out);
+    } else if (e.isFile() && /^route\.(?:tsx|ts|jsx|js)$/.test(e.name)) {
+      out.push(full);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Inline-schema detection
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface DetectedSchema {
+  name: string;
+  /** The balanced `z.object({ … })` literal. */
+  body: string;
+  /** The HTTP method associated (heuristic from exported fn names). */
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+}
+
+/**
+ * Walk forward from `z.object(` and return the index just past the
+ * matching `)` using brace-depth tracking. Returns -1 if unbalanced.
+ */
+export function findZodObjectEnd(source: string, start: number): number {
+  // Expect `z.object(` at `start`.
+  const open = source.indexOf("(", start);
+  if (open < 0) return -1;
+  let depth = 0;
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") {
+      depth--;
+      if (depth === 0 && ch === ")") return i + 1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Detect inline Zod schemas bound to a const identifier.
+ *
+ * Exported for regression tests.
+ */
+export function detectInlineSchemas(source: string): DetectedSchema[] {
+  const out: DetectedSchema[] = [];
+  const constRegex = /\bconst\s+(\w+)\s*=\s*z\.object\s*\(/g;
+  let m: RegExpExecArray | null;
+  while ((m = constRegex.exec(source)) !== null) {
+    const name = m[1];
+    const openZ = source.indexOf("z.object", m.index);
+    if (openZ < 0) continue;
+    const end = findZodObjectEnd(source, openZ);
+    if (end < 0) continue;
+    const body = source.slice(openZ, end);
+    out.push({
+      name,
+      body,
+      method: inferMethod(source, name),
+    });
+  }
+  return out;
+}
+
+function inferMethod(
+  source: string,
+  schemaName: string,
+): "GET" | "POST" | "PUT" | "PATCH" | "DELETE" {
+  // Heuristic: look at which exported HTTP handler mentions the schema.
+  const methods = ["POST", "PUT", "PATCH", "DELETE", "GET"] as const;
+  for (const method of methods) {
+    const re = new RegExp(
+      `export\\s+(?:async\\s+)?function\\s+${method}\\b[\\s\\S]*?\\b${schemaName}\\b`,
+    );
+    if (re.test(source)) return method;
+  }
+  // Fallback: if the schema name hints at mutation, guess POST.
+  if (/create|update|delete|patch/i.test(schemaName)) return "POST";
+  return "GET";
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Emit contract file
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface ContractModuleOutput {
+  fileName: string;
+  contractName: string;
+  source: string;
+}
+
+/**
+ * Build a `contract/<name>.contract.ts` source for the given route +
+ * detected schemas. Exported for tests.
+ */
+export function renderContractModule(
+  routeRel: string,
+  schemas: DetectedSchema[],
+): ContractModuleOutput {
+  // routeRel like `app/api/users/route.ts` → group name `users`
+  const parts = routeRel.split(/[\\/]/);
+  const apiIdx = parts.indexOf("api");
+  const segs = apiIdx >= 0 ? parts.slice(apiIdx + 1) : parts.slice(-2);
+  const group =
+    segs
+      .filter((s) => s !== "route.ts" && s !== "route.tsx")
+      .filter(Boolean)
+      .join("-")
+      .replace(/[\[\]]/g, "")
+      .replace(/[^A-Za-z0-9_-]/g, "") || "api";
+
+  const contractName = `${camelize(group)}Contract`;
+  const urlPath = "/api/" + segs.filter((s) => !/^route\./.test(s)).join("/");
+
+  const endpoints = schemas
+    .map((s) => {
+      const opKey = deriveOpKey(s.name, s.method);
+      return (
+        `  ${opKey}: {\n` +
+        `    method: ${JSON.stringify(s.method)},\n` +
+        `    path: ${JSON.stringify(urlPath)},\n` +
+        `    input: ${s.body},\n` +
+        `    output: z.unknown(),\n` +
+        `  },`
+      );
+    })
+    .join("\n");
+
+  const src =
+    `/**\n` +
+    ` * Auto-generated by mandu.refactor.extract_contract.\n` +
+    ` * Replace output: z.unknown() with your response schema.\n` +
+    ` */\n` +
+    `import { z } from "zod";\n` +
+    `import { defineContract } from "@mandujs/core";\n\n` +
+    `export const ${contractName} = defineContract({\n` +
+    `${endpoints}\n` +
+    `});\n`;
+
+  return {
+    fileName: `${group}.contract.ts`,
+    contractName,
+    source: src,
+  };
+}
+
+function camelize(s: string): string {
+  return s
+    .split(/[-_]/)
+    .map((part, i) =>
+      i === 0 ? part.toLowerCase() : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase(),
+    )
+    .join("");
+}
+
+function deriveOpKey(
+  schemaName: string,
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+): string {
+  const lower = schemaName.toLowerCase();
+  if (lower.includes("create")) return "create";
+  if (lower.includes("update") || lower.includes("patch")) return "update";
+  if (lower.includes("delete")) return "remove";
+  if (lower.includes("list") || lower.includes("query")) return "list";
+  return method === "GET" ? "read" : "mutate";
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Public handler
+// ─────────────────────────────────────────────────────────────────────────
+
+async function runExtract(
+  projectRoot: string,
+  input: ExtractContractInput,
+): Promise<
+  | ExtractContractResult
+  | { error: string; field?: string; hint?: string }
+> {
+  const validated = validateInput(input as Record<string, unknown>);
+  if (!validated.ok) {
+    return { error: validated.error, field: validated.field, hint: validated.hint };
+  }
+  const { dryRun, route: filter } = validated.value;
+
+  const routes = await findApiRoutes(projectRoot);
+  const extracted: ExtractedContractEntry[] = [];
+  const skipped: Array<{ route: string; reason: string }> = [];
+
+  const contractDir = path.join(projectRoot, "contract");
+
+  for (const routeFile of routes) {
+    const routeRel = path.relative(projectRoot, routeFile).replace(/\\/g, "/");
+    const routeDirRel = routeRel.replace(/\/route\.(?:tsx?|jsx?)$/, "");
+    if (filter && !routeDirRel.startsWith(filter.replace(/\\/g, "/"))) continue;
+
+    let source: string;
+    try {
+      source = await Bun.file(routeFile).text();
+    } catch (err) {
+      skipped.push({
+        route: routeDirRel,
+        reason: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+
+    let schemas: DetectedSchema[];
+    try {
+      schemas = detectInlineSchemas(source);
+    } catch (err) {
+      skipped.push({
+        route: routeDirRel,
+        reason: `parse error: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+    if (schemas.length === 0) {
+      skipped.push({ route: routeDirRel, reason: "no inline z.object schemas" });
+      continue;
+    }
+
+    const out = renderContractModule(routeRel, schemas);
+    const target = path.join(contractDir, out.fileName);
+    const targetRel = path.relative(projectRoot, target).replace(/\\/g, "/");
+
+    if (!dryRun) {
+      try {
+        await Bun.write(target, out.source);
+      } catch (err) {
+        skipped.push({
+          route: routeDirRel,
+          reason: `write failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+        continue;
+      }
+    }
+
+    for (const s of schemas) {
+      extracted.push({
+        route: routeDirRel,
+        contractFile: targetRel,
+        schemaName: s.name,
+        sourceFile: routeRel,
+      });
+    }
+  }
+
+  return { extracted, skipped, dryRun };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// MCP tool definition + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const extractContractToolDefinitions: Tool[] = [
+  {
+    name: "mandu.refactor.extract_contract",
+    description:
+      "Scan `app/api/**/route.ts` for inline Zod schemas and extract them to `contract/<group>.contract.ts` using the `defineContract()` convention. The source handler is left untouched — follow-up manual step is to import the contract and swap ad-hoc validation. Dry-run by default.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        dryRun: {
+          type: "boolean",
+          description:
+            "When true (default), return the plan without writing files. When false, write the contract files to `contract/`.",
+        },
+        route: {
+          type: "string",
+          description:
+            "Optional prefix to restrict scan (e.g. 'app/api/users').",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function extractContractTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> =
+    {
+      "mandu.refactor.extract_contract": async (args) =>
+        runExtract(projectRoot, args as ExtractContractInput),
+    };
+  return handlers;
+}

package/src/tools/index.ts

@@ -37,6 +37,19 @@ export { runTestsTools, runTestsToolDefinitions } from "./run-tests.js";
 export { deployPreviewTools, deployPreviewToolDefinitions } from "./deploy-preview.js";
 export { aiBriefTools, aiBriefToolDefinitions } from "./ai-brief.js";
 export { loopCloseTools, loopCloseToolDefinitions } from "./loop-close.js";
+// Phase 18.ι — AI refactor MCP tools
+export {
+  rewriteGeneratedBarrelTools,
+  rewriteGeneratedBarrelToolDefinitions,
+} from "./rewrite-generated-barrel.js";
+export {
+  migrateRouteConventionsTools,
+  migrateRouteConventionsToolDefinitions,
+} from "./migrate-route-conventions.js";
+export {
+  extractContractTools,
+  extractContractToolDefinitions,
+} from "./extract-contract.js";
 
 // 도구 모듈 import (등록용)
 import { specTools, specToolDefinitions } from "./spec.js";
@@ -63,6 +76,19 @@ import { runTestsTools, runTestsToolDefinitions } from "./run-tests.js";
 import { deployPreviewTools, deployPreviewToolDefinitions } from "./deploy-preview.js";
 import { aiBriefTools, aiBriefToolDefinitions } from "./ai-brief.js";
 import { loopCloseTools, loopCloseToolDefinitions } from "./loop-close.js";
+// Phase 18.ι — AI refactor MCP tools
+import {
+  rewriteGeneratedBarrelTools,
+  rewriteGeneratedBarrelToolDefinitions,
+} from "./rewrite-generated-barrel.js";
+import {
+  migrateRouteConventionsTools,
+  migrateRouteConventionsToolDefinitions,
+} from "./migrate-route-conventions.js";
+import {
+  extractContractTools,
+  extractContractToolDefinitions,
+} from "./extract-contract.js";
 
 /**
  * 도구 모듈 정보
@@ -108,6 +134,22 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "deploy-preview", definitions: deployPreviewToolDefinitions, handlers: deployPreviewTools },
   { category: "ai-brief", definitions: aiBriefToolDefinitions, handlers: aiBriefTools },
   { category: "loop-close", definitions: loopCloseToolDefinitions, handlers: loopCloseTools },
+  // Phase 18.ι — AI refactor tools (destructive writes; dry-run by default)
+  {
+    category: "refactor-barrel",
+    definitions: rewriteGeneratedBarrelToolDefinitions,
+    handlers: rewriteGeneratedBarrelTools,
+  },
+  {
+    category: "refactor-routes",
+    definitions: migrateRouteConventionsToolDefinitions,
+    handlers: migrateRouteConventionsTools,
+  },
+  {
+    category: "refactor-contract",
+    definitions: extractContractToolDefinitions,
+    handlers: extractContractTools,
+  },
 ];
 
 /**

package/src/tools/migrate-route-conventions.ts

@@ -0,0 +1,345 @@
+/**
+ * MCP tool — `mandu.refactor.migrate_route_conventions`
+ *
+ * Detects Next.js-style inline patterns in user code and migrates them to
+ * Mandu's file-system route conventions:
+ *
+ *   • Inline `<Suspense fallback={…}>…</Suspense>` → extract to `loading.tsx`
+ *   • Inline `<ErrorBoundary fallback={…}>…</ErrorBoundary>` → `error.tsx`
+ *   • Inline `if (!x) return <NotFound />` / `notFound()` call → `not-found.tsx`
+ *
+ * Scope:
+ *   • We only act on files under the `app/` tree (Mandu's routes dir).
+ *   • We never overwrite an existing convention file — if `loading.tsx`
+ *     already exists, we report the route as already-migrated.
+ *   • We do not parse TSX with a real parser — detection uses conservative
+ *     regex markers. False positives are acceptable; false file writes are
+ *     not, so we bail out of extraction on any ambiguity.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { readdir } from "fs/promises";
+import path from "path";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export type RouteConvention = "loading" | "error" | "not-found";
+
+export interface MigrateRouteConventionsInput {
+  dryRun?: boolean;
+  routes?: string[];
+}
+
+export interface MigrateExtractionEntry {
+  route: string;
+  convention: RouteConvention;
+  extractedPath: string;
+  sourceFile: string;
+  note?: string;
+}
+
+export interface MigrateRouteConventionsResult {
+  routes: string[];
+  extracted: MigrateExtractionEntry[];
+  skipped: Array<{ route: string; reason: string }>;
+  dryRun: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────
+
+function validateInput(
+  raw: Record<string, unknown>,
+):
+  | { ok: true; value: { dryRun: boolean; routes?: string[] } }
+  | { ok: false; error: string; field: string; hint: string } {
+  const dryRun = raw.dryRun;
+  if (dryRun !== undefined && typeof dryRun !== "boolean") {
+    return {
+      ok: false,
+      error: "'dryRun' must be a boolean",
+      field: "dryRun",
+      hint: "Omit to default to true, pass false to actually write files",
+    };
+  }
+  const routes = raw.routes;
+  if (routes !== undefined) {
+    if (!Array.isArray(routes) || !routes.every((r) => typeof r === "string")) {
+      return {
+        ok: false,
+        error: "'routes' must be an array of strings",
+        field: "routes",
+        hint: "E.g. ['app/dashboard', 'app/users/[id]']",
+      };
+    }
+  }
+  return {
+    ok: true,
+    value: {
+      dryRun: dryRun === undefined ? true : dryRun,
+      ...(Array.isArray(routes) ? { routes: routes as string[] } : {}),
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Route discovery — a lightweight replacement for fs-scanner that keeps
+// this tool self-contained. We look for `page.ts(x)` files under `app/`.
+// ─────────────────────────────────────────────────────────────────────────
+
+async function collectRoutes(
+  projectRoot: string,
+  filter?: string[],
+): Promise<string[]> {
+  const appDir = path.join(projectRoot, "app");
+  const found: string[] = [];
+  await walkPages(appDir, found);
+  const rels = found.map((p) => path.relative(projectRoot, path.dirname(p)));
+  if (!filter || filter.length === 0) return rels.sort();
+  const set = new Set(filter.map((f) => f.replace(/\\/g, "/")));
+  return rels.filter((r) => set.has(r.replace(/\\/g, "/"))).sort();
+}
+
+async function walkPages(dir: string, out: string[]): Promise<void> {
+  let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name.startsWith("_") || e.name === "node_modules") continue;
+      await walkPages(full, out);
+    } else if (
+      e.isFile() &&
+      /^page\.(?:tsx|ts|jsx|js)$/.test(e.name)
+    ) {
+      out.push(full);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Detection
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface DetectionHit {
+  convention: RouteConvention;
+  fallbackSnippet: string;
+}
+
+/**
+ * Scan a single page source for inline Suspense / ErrorBoundary / NotFound
+ * patterns. Exported for regression tests.
+ */
+export function detectConventions(source: string): DetectionHit[] {
+  const hits: DetectionHit[] = [];
+
+  // `<Suspense fallback={<Loading />}>`
+  const suspense = /<Suspense\s+fallback\s*=\s*\{([^}]*)\}\s*>/.exec(source);
+  if (suspense) {
+    hits.push({
+      convention: "loading",
+      fallbackSnippet: suspense[1].trim(),
+    });
+  }
+
+  // `<ErrorBoundary fallback={…}>`
+  const errBoundary = /<ErrorBoundary\s+fallback\s*=\s*\{([^}]*)\}\s*>/.exec(source);
+  if (errBoundary) {
+    hits.push({
+      convention: "error",
+      fallbackSnippet: errBoundary[1].trim(),
+    });
+  }
+
+  // `if (…) return <NotFound />` — lenient single-line match
+  const inlineNotFound =
+    /return\s*<NotFound\s*\/?\s*>|notFound\s*\(\s*\)/.exec(source);
+  if (inlineNotFound) {
+    hits.push({
+      convention: "not-found",
+      fallbackSnippet: "<div>Not found</div>",
+    });
+  }
+
+  return hits;
+}
+
+function conventionFilename(c: RouteConvention): string {
+  return `${c}.tsx`;
+}
+
+function renderConventionFile(
+  convention: RouteConvention,
+  fallback: string,
+): string {
+  const header =
+    `/**\n` +
+    ` * Auto-generated by mandu.refactor.migrate_route_conventions.\n` +
+    ` * Review and hand-tune as needed.\n` +
+    ` */\n`;
+
+  switch (convention) {
+    case "loading":
+      return `${header}\nexport default function Loading() {\n  return ${fallback};\n}\n`;
+    case "error":
+      return (
+        `${header}\n` +
+        `export default function Error({ error, reset }: { error: Error; reset: () => void }) {\n` +
+        `  return ${fallback};\n` +
+        `}\n`
+      );
+    case "not-found":
+      return `${header}\nexport default function NotFound() {\n  return ${fallback};\n}\n`;
+  }
+}
+
+async function fileExists(absPath: string): Promise<boolean> {
+  try {
+    const f = Bun.file(absPath);
+    return await f.exists();
+  } catch {
+    return false;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Public handler
+// ─────────────────────────────────────────────────────────────────────────
+
+async function runMigrate(
+  projectRoot: string,
+  input: MigrateRouteConventionsInput,
+): Promise<
+  | MigrateRouteConventionsResult
+  | { error: string; field?: string; hint?: string }
+> {
+  const validated = validateInput(input as Record<string, unknown>);
+  if (!validated.ok) {
+    return { error: validated.error, field: validated.field, hint: validated.hint };
+  }
+  const { dryRun, routes: filter } = validated.value;
+
+  const routes = await collectRoutes(projectRoot, filter);
+  const extracted: MigrateExtractionEntry[] = [];
+  const skipped: Array<{ route: string; reason: string }> = [];
+
+  for (const route of routes) {
+    const routeDir = path.join(projectRoot, route);
+
+    // Find the page file (tsx > ts > jsx > js)
+    let pageFile: string | null = null;
+    for (const ext of ["tsx", "ts", "jsx", "js"]) {
+      const cand = path.join(routeDir, `page.${ext}`);
+      if (await fileExists(cand)) {
+        pageFile = cand;
+        break;
+      }
+    }
+    if (!pageFile) {
+      skipped.push({ route, reason: "no page file" });
+      continue;
+    }
+
+    let source: string;
+    try {
+      source = await Bun.file(pageFile).text();
+    } catch (err) {
+      skipped.push({
+        route,
+        reason: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+
+    const hits = detectConventions(source);
+    if (hits.length === 0) continue;
+
+    for (const hit of hits) {
+      const target = path.join(routeDir, conventionFilename(hit.convention));
+      const relTarget = path.relative(projectRoot, target);
+
+      if (await fileExists(target)) {
+        extracted.push({
+          route,
+          convention: hit.convention,
+          extractedPath: relTarget,
+          sourceFile: path.relative(projectRoot, pageFile),
+          note: "already exists — skipped write",
+        });
+        continue;
+      }
+
+      const content = renderConventionFile(hit.convention, hit.fallbackSnippet);
+
+      if (!dryRun) {
+        try {
+          await Bun.write(target, content);
+        } catch (err) {
+          skipped.push({
+            route,
+            reason: `write ${hit.convention}: ${err instanceof Error ? err.message : String(err)}`,
+          });
+          continue;
+        }
+      }
+
+      extracted.push({
+        route,
+        convention: hit.convention,
+        extractedPath: relTarget,
+        sourceFile: path.relative(projectRoot, pageFile),
+      });
+    }
+  }
+
+  return { routes, extracted, skipped, dryRun };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// MCP tool definition + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const migrateRouteConventionsToolDefinitions: Tool[] = [
+  {
+    name: "mandu.refactor.migrate_route_conventions",
+    description:
+      "Detect Next.js-style inline patterns in `app/**/page.*` files (Suspense fallback, ErrorBoundary, inline NotFound) and extract them to Mandu's file-system route conventions (`loading.tsx`, `error.tsx`, `not-found.tsx`). Never overwrites an existing convention file. Dry-run by default.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        dryRun: {
+          type: "boolean",
+          description:
+            "When true (default), return the plan without writing files. When false, create the convention files.",
+        },
+        routes: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional list of route directories to restrict the scan to. Paths are relative to the project root (e.g. 'app/dashboard').",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function migrateRouteConventionsTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> =
+    {
+      "mandu.refactor.migrate_route_conventions": async (args) =>
+        runMigrate(projectRoot, args as MigrateRouteConventionsInput),
+    };
+  return handlers;
+}

package/src/tools/rewrite-generated-barrel.ts

@@ -0,0 +1,403 @@
+/**
+ * MCP tool — `mandu.refactor.rewrite_generated_barrel`
+ *
+ * Automates migration of barrel files that reach directly into
+ * `__generated__/*` paths (the #1 cause of `INVALID_GENERATED_IMPORT` guard
+ * failures) to the sanctioned `getGenerated()` accessor from
+ * `@mandujs/core/runtime`.
+ *
+ * Transform example:
+ *
+ *   // BEFORE
+ *   export { items } from "../__generated__/items.data";
+ *
+ *   // AFTER
+ *   import { getGenerated } from "@mandujs/core/runtime";
+ *   declare module "@mandujs/core/runtime" {
+ *     interface GeneratedRegistry { "items": typeof items; }
+ *   }
+ *   export const items = getGenerated("items");
+ *
+ * Behaviour:
+ *   • Input: `{ dryRun?: boolean, patterns?: string[] }`. `patterns` are
+ *     relative glob-like roots to scan (default: `packages/*`, `src/**`).
+ *     The implementation uses a deterministic recursive walk — we do not
+ *     pull in a glob dep.
+ *   • Each file is parsed with a minimal, conservative regex set that only
+ *     matches re-exports of the form `export { … } from "…/__generated__/…"`.
+ *     Anything more exotic is reported under `skipped` with a reason.
+ *   • On `dryRun: true` (default) we only return the plan. On
+ *     `dryRun: false` we write files via `Bun.write`, which is atomic.
+ *   • Parse / I/O errors for a single file are captured and do not abort
+ *     the scan.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { readdir } from "fs/promises";
+import path from "path";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface RewriteBarrelInput {
+  dryRun?: boolean;
+  patterns?: string[];
+}
+
+export interface RewriteBarrelPlanEntry {
+  file: string;
+  before: string;
+  after: string;
+  rewrites: Array<{ name: string; key: string; source: string }>;
+  appliedIf: "not-dry-run";
+}
+
+export interface RewriteBarrelSkip {
+  file: string;
+  reason: string;
+}
+
+export interface RewriteBarrelResult {
+  scanned: number;
+  matched: number;
+  rewritten: number;
+  skipped: RewriteBarrelSkip[];
+  plan: RewriteBarrelPlanEntry[];
+  dryRun: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────
+
+function validateInput(
+  raw: Record<string, unknown>,
+):
+  | { ok: true; value: { dryRun: boolean; patterns: string[] } }
+  | { ok: false; error: string; field: string; hint: string } {
+  const dryRun = raw.dryRun;
+  if (dryRun !== undefined && typeof dryRun !== "boolean") {
+    return {
+      ok: false,
+      error: "'dryRun' must be a boolean",
+      field: "dryRun",
+      hint: "Omit to default to true, pass false to actually write files",
+    };
+  }
+
+  const patterns = raw.patterns;
+  if (patterns !== undefined) {
+    if (!Array.isArray(patterns) || !patterns.every((p) => typeof p === "string")) {
+      return {
+        ok: false,
+        error: "'patterns' must be an array of strings",
+        field: "patterns",
+        hint: "E.g. ['packages', 'src']",
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    value: {
+      dryRun: dryRun === undefined ? true : dryRun,
+      patterns:
+        patterns && Array.isArray(patterns) && patterns.length > 0
+          ? (patterns as string[])
+          : ["packages", "src"],
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// FS walk
+// ─────────────────────────────────────────────────────────────────────────
+
+const EXT_REGEX = /\.(?:ts|tsx|mts|cts)$/;
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".mandu",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  "coverage",
+  "__generated__",
+]);
+
+async function walk(root: string, dir: string, out: string[]): Promise<void> {
+  let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (IGNORE_DIRS.has(e.name)) continue;
+      await walk(root, full, out);
+    } else if (e.isFile() && EXT_REGEX.test(e.name)) {
+      out.push(full);
+    }
+  }
+}
+
+async function collectFiles(projectRoot: string, patterns: string[]): Promise<string[]> {
+  const collected = new Set<string>();
+  for (const rel of patterns) {
+    const abs = path.resolve(projectRoot, rel);
+    const files: string[] = [];
+    await walk(projectRoot, abs, files);
+    for (const f of files) collected.add(f);
+  }
+  return [...collected].sort();
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Rewrite engine
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Regex matching a re-export of the form:
+ *   export { a, b as c } from "…/__generated__/name.data";
+ *
+ * Captures:
+ *   [1] = names block (e.g. `a, b as c`)
+ *   [2] = source path
+ */
+const GENERATED_REEXPORT_REGEX =
+  /export\s*\{\s*([^}]+)\s*\}\s*from\s*["']([^"']*__generated__[^"']*)["']\s*;?/g;
+
+/** Parse a names-block `a, b as c, default as d` → [{name, alias?}]. */
+function parseNames(namesBlock: string): Array<{ name: string; alias?: string }> {
+  return namesBlock
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((tok) => {
+      const asMatch = /^(\S+)\s+as\s+(\S+)$/.exec(tok);
+      if (asMatch) return { name: asMatch[1], alias: asMatch[2] };
+      return { name: tok };
+    });
+}
+
+/** Derive a registry key from a __generated__ source path. */
+export function deriveGeneratedKey(source: string): string {
+  // `../__generated__/items.data` → `items`
+  // `./__generated__/foo/bar.data` → `foo/bar`
+  const idx = source.indexOf("__generated__/");
+  const tail = idx >= 0 ? source.slice(idx + "__generated__/".length) : source;
+  return tail.replace(/\.(?:data|index|gen|g)$/, "").replace(/\/index$/, "");
+}
+
+export interface RewriteOutcome {
+  after: string;
+  rewrites: Array<{ name: string; key: string; source: string }>;
+}
+
+/**
+ * Rewrite the source of a single barrel file. Returns `null` when no
+ * `__generated__` re-export is present (nothing to do).
+ *
+ * Exported for regression testing.
+ */
+export function rewriteBarrelSource(before: string): RewriteOutcome | null {
+  // Fast bail: no hits at all.
+  if (!/__generated__/.test(before)) return null;
+
+  const rewrites: Array<{ name: string; key: string; source: string }> = [];
+  let matched = false;
+
+  // Build an accumulator of replacement blocks; each match becomes a
+  // declare-module + const block.
+  const replaced = before.replace(
+    GENERATED_REEXPORT_REGEX,
+    (_full, namesBlock: string, source: string) => {
+      matched = true;
+      const key = deriveGeneratedKey(source);
+      const names = parseNames(namesBlock);
+      const constDecls: string[] = [];
+      const typeLines: string[] = [];
+      for (const n of names) {
+        const exported = n.alias ?? n.name;
+        // Per re-export we emit a single registry key but re-expose each
+        // symbol as its own const. The registry key is derived from the
+        // file path — all symbols in the same re-export share it and are
+        // expected to live on the same generated artifact. When multiple
+        // symbols come from one source we destructure.
+        if (names.length === 1) {
+          constDecls.push(
+            `export const ${exported} = getGenerated(${JSON.stringify(key)});`,
+          );
+          typeLines.push(`    ${JSON.stringify(key)}: typeof ${exported};`);
+        } else {
+          // First rewrite emits the shared const; subsequent destructures
+          // pull the field off of it.
+          if (constDecls.length === 0) {
+            constDecls.push(
+              `const __${sanitize(key)} = getGenerated(${JSON.stringify(key)});`,
+            );
+          }
+          constDecls.push(
+            `export const ${exported} = __${sanitize(key)}.${n.name};`,
+          );
+          typeLines.push(
+            `    ${JSON.stringify(key)}: { ${names
+              .map((m) => `${m.name}: typeof ${m.alias ?? m.name};`)
+              .join(" ")} };`,
+          );
+        }
+        rewrites.push({ name: exported, key, source });
+      }
+
+      const dedupedTypeLines = [...new Set(typeLines)];
+      return [
+        `declare module "@mandujs/core/runtime" {`,
+        `  interface GeneratedRegistry {`,
+        ...dedupedTypeLines,
+        `  }`,
+        `}`,
+        ...constDecls,
+      ].join("\n");
+    },
+  );
+
+  if (!matched) return null;
+
+  // Ensure a single `import { getGenerated } from "@mandujs/core/runtime"`
+  // is present. If the file already imports it, we leave it alone.
+  const hasImport =
+    /import\s*\{[^}]*\bgetGenerated\b[^}]*\}\s*from\s*["']@mandujs\/core\/runtime["']/.test(
+      replaced,
+    );
+  const after = hasImport
+    ? replaced
+    : `import { getGenerated } from "@mandujs/core/runtime";\n${replaced}`;
+
+  return { after, rewrites };
+}
+
+function sanitize(s: string): string {
+  return s.replace(/[^A-Za-z0-9_]/g, "_");
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Public handler
+// ─────────────────────────────────────────────────────────────────────────
+
+async function runRewrite(
+  projectRoot: string,
+  input: RewriteBarrelInput,
+): Promise<RewriteBarrelResult | { error: string; field?: string; hint?: string }> {
+  const validated = validateInput(input as Record<string, unknown>);
+  if (!validated.ok) {
+    return { error: validated.error, field: validated.field, hint: validated.hint };
+  }
+  const { dryRun, patterns } = validated.value;
+
+  const files = await collectFiles(projectRoot, patterns);
+
+  const plan: RewriteBarrelPlanEntry[] = [];
+  const skipped: RewriteBarrelSkip[] = [];
+  let rewritten = 0;
+
+  for (const file of files) {
+    let before: string;
+    try {
+      before = await Bun.file(file).text();
+    } catch (err) {
+      skipped.push({
+        file: path.relative(projectRoot, file),
+        reason: `read failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+
+    let outcome: RewriteOutcome | null = null;
+    try {
+      outcome = rewriteBarrelSource(before);
+    } catch (err) {
+      skipped.push({
+        file: path.relative(projectRoot, file),
+        reason: `parse error: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+
+    if (!outcome) continue; // no __generated__ re-export, irrelevant
+
+    const rel = path.relative(projectRoot, file);
+    plan.push({
+      file: rel,
+      before,
+      after: outcome.after,
+      rewrites: outcome.rewrites,
+      appliedIf: "not-dry-run",
+    });
+
+    if (!dryRun) {
+      try {
+        await Bun.write(file, outcome.after);
+        rewritten += 1;
+      } catch (err) {
+        skipped.push({
+          file: rel,
+          reason: `write failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+    }
+  }
+
+  return {
+    scanned: files.length,
+    matched: plan.length,
+    rewritten,
+    skipped,
+    plan,
+    dryRun,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// MCP tool definition + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const rewriteGeneratedBarrelToolDefinitions: Tool[] = [
+  {
+    name: "mandu.refactor.rewrite_generated_barrel",
+    description:
+      "Scan the project for barrel files that re-export from `__generated__/*` paths (a `INVALID_GENERATED_IMPORT` guard violation) and rewrite each to use `getGenerated()` from `@mandujs/core/runtime` with the proper `GeneratedRegistry` module augmentation. Returns a per-file before/after plan. Dry-run by default.",
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        dryRun: {
+          type: "boolean",
+          description:
+            "When true (default), return the plan without writing files. When false, rewrite files atomically via Bun.write.",
+        },
+        patterns: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Relative directory roots to scan (default: ['packages', 'src']).",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function rewriteGeneratedBarrelTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> =
+    {
+      "mandu.refactor.rewrite_generated_barrel": async (args) =>
+        runRewrite(projectRoot, args as RewriteBarrelInput),
+    };
+  return handlers;
+}