@nikelyh/metamorph 2.1.0 → 2.1.1

package/README.md

@@ -16,16 +16,17 @@
 
 Metamorph is a CLI tool powered by [Mozaik](https://github.com/jigjoy-ai/mozaik) that automates complex architectural shifts and framework migrations in your codebase. Instead of doing it manually, Metamorph spawns a swarm of specialized AI agents that safely refactor your code in an isolated "Shadow Workspace".
 
-📚 **[Read the Full Documentation](https://metamorph.nikelyh.tech/docs)**
+**[Read the Full Documentation](https://metamorph.nikelyh.tech/docs)** | **[System Architecture](https://github.com/yohanvillarp/metamorph/blob/main/docs/architecture.md)**
 
-## 🚀 Features
+## Features
 
-- **Multi-Agent Concurrency**: Utilizes Mapper, Worker, Reviewer, and PackageManager agents to migrate code.
-- **Zero Risk**: All migrations happen in a `.metamorph/shadow` workspace. Your original code is completely untouched until you explicitly approve and integrate the changes.
-- **Visual Dashboard**: Watch your agents work in real-time through the built-in local dashboard UI.
-- **Extensive Framework Support**: Easily migrate between popular frameworks automatically.
+- **Multi-Agent Concurrency** -- Utilizes Mapper, Worker, Reviewer, Integration, and Coordinator agents to migrate code in parallel.
+- **Zero Risk** -- All migrations happen in a `.metamorph/shadow` workspace. Your original code is completely untouched until you explicitly approve and apply the changes.
+- **Visual Dashboard** -- Watch your agents work in real-time through the built-in local dashboard UI.
+- **Shadow Build Verification** -- Every migration is validated with `npm install` and `npm run build` inside the shadow workspace before completion.
+- **Extensive Framework Support** -- Easily migrate between popular frontend and backend frameworks.
 
-## 📦 Installation
+## Installation
 
 Install Metamorph globally via NPM:
 
@@ -33,66 +34,90 @@ Install Metamorph globally via NPM:
 npm install -g @nikelyh/metamorph
 ```
 
-## 🛠️ Typical Workflow
+### Prerequisites
 
-You can run the entire migration lifecycle using just your terminal. 
+- Node.js >= 20
+- An LLM provider API key (OpenAI, Anthropic, or compatible). Set it as an environment variable:
+  ```bash
+  export OPENAI_API_KEY=sk-...
+  ```
 
-### 1. Help & Options
-To see all available commands and options at any time, run:
-```bash
-metamorph --help
-```
+## Typical Workflow
+
+### 1. Start a Migration
 
-### 2. Start a Migration
 Navigate to the root of the project you want to migrate and run:
+
 ```bash
 metamorph run
 ```
-Metamorph will automatically detect your current stack (e.g. Express, React) and prompt you to select the target framework. Alternatively, you can bypass the interactive prompt by passing the source explicitly:
+
+Metamorph automatically detects your current stack (e.g., Express, React) and prompts you to select the target framework. You can bypass the interactive prompt by passing the source explicitly:
+
 ```bash
 metamorph run --from express
 ```
 
-### 3. Monitor the Agents (Dashboard UI)
-Once a migration is running, the AI swarm begins working in the background. To see their real-time progress, open a **new terminal tab** in the same folder and run:
+### 2. Monitor the Agents (Dashboard UI)
+
+Once a migration is running, the AI swarm begins working in the background. To see their real-time progress, open a new terminal in the same directory and run:
+
 ```bash
 metamorph ui
 ```
-This will start the internal dashboard server and open a Neo-Brutalist interface in your default browser. You can specify a port with `--port 8080`.
 
-### 4. Review and Apply
-After the AI finishes the migration in the isolated Shadow Workspace, you will receive a `runId`. You can apply the completed migration to your actual repository (which automatically creates a new git branch for safety):
+This starts the internal dashboard server and opens a monitoring interface in your default browser. You can specify a port with `--port 8080`.
+
+### 3. Review and Apply
+
+After the AI finishes the migration in the isolated Shadow Workspace, you will receive a `runId`. Apply the completed migration to your actual repository (which automatically creates a new Git branch for safety):
+
 ```bash
 metamorph apply <runId> .
 ```
 
-### 5. Managing Migrations
-If you want to discard a run without applying it:
+### 4. Managing Migrations
+
+Discard a run without applying it:
+
 ```bash
 metamorph rollback <runId>
 ```
-To see a history of all migrations:
+
+View migration history:
+
 ```bash
 metamorph list
 ```
-To clear the local database and reset all events:
+
+Clear the local database and reset all events:
+
 ```bash
 metamorph reset
 ```
 
 ### Utility Commands
-To test the technology detection on your repository without starting a migration:
+
+Test the technology detection on your repository without starting a migration:
+
 ```bash
 metamorph detect .
 ```
 
-## 🔄 Supported Migrations
+View all available commands and options:
 
-As Metamorph's AI capabilities are constantly expanding, the list of supported architectural shifts is updated frequently.
+```bash
+metamorph --help
+```
 
-To see the complete, up-to-date list of all supported frontend and backend framework migrations, please visit our official documentation:
+## Supported Migrations
 
-👉 **[View Supported Migrations](https://metamorph.nikelyh.tech/docs/migrations)**
+The list of supported architectural shifts is updated frequently as new migration catalogs are added.
+
+See the complete, up-to-date list of all supported frontend and backend framework migrations in the official documentation:
+
+**[View Supported Migrations](https://metamorph.nikelyh.tech/docs/migrations)**
 
 ---
-*Built with ❤️ using Mozaik.*
+
+*Built with [Mozaik](https://github.com/jigjoy-ai/mozaik).*

package/dist/NextMigrationHints-BGO2W3K4.js

@@ -0,0 +1,32 @@
+import {
+  analyzeCallbackPropMismatches,
+  analyzeReactToNextComposition,
+  analyzeReactToNextStructure,
+  analyzeUnresolvedLocalImports,
+  findShadowRoot,
+  hasNextAppRoutes,
+  isFsdPageComponent,
+  isHollowView,
+  isSpaPagesTreeFile,
+  isSpaRootComponent,
+  isStubAppRouterPage,
+  listAppRouterFiles,
+  nextMigrationFileHint,
+  unresolvedLocalImports
+} from "./chunk-H2LZEPNI.js";
+export {
+  analyzeCallbackPropMismatches,
+  analyzeReactToNextComposition,
+  analyzeReactToNextStructure,
+  analyzeUnresolvedLocalImports,
+  findShadowRoot,
+  hasNextAppRoutes,
+  isFsdPageComponent,
+  isHollowView,
+  isSpaPagesTreeFile,
+  isSpaRootComponent,
+  isStubAppRouterPage,
+  listAppRouterFiles,
+  nextMigrationFileHint,
+  unresolvedLocalImports
+};

package/dist/chunk-H2LZEPNI.js

@@ -0,0 +1,352 @@
+// ../application/src/utils/NextMigrationHints.ts
+import * as fs from "fs";
+import * as path from "path";
+function findShadowRoot(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const marker = "/.metamorph/shadow/";
+  const index = normalized.indexOf(marker);
+  if (index === -1) return null;
+  const after = normalized.slice(index + marker.length);
+  const runId = after.split("/")[0];
+  if (!runId) return null;
+  return filePath.slice(0, index + marker.length + runId.length);
+}
+function isFsdPageComponent(filePath) {
+  return /[/\\]src[/\\]pages[/\\][^/\\]+[/\\]ui[/\\]/i.test(filePath);
+}
+function isSpaRootComponent(filePath) {
+  return /[/\\](App|main|index)\.(t|j)sx?$/i.test(filePath) && !/[/\\]src[/\\]app[/\\]/i.test(filePath) && !isFsdPageComponent(filePath);
+}
+function hasNextAppRoutes(shadowRoot) {
+  const appDir = path.join(shadowRoot, "src", "app");
+  if (!fs.existsSync(appDir)) return false;
+  const stack = [appDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        stack.push(path.join(dir, entry.name));
+      } else if (entry.name === "page.tsx" || entry.name === "page.jsx" || entry.name === "page.js") {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function nextMigrationFileHint(filePath, target) {
+  if (target !== "next") return "";
+  if (isFsdPageComponent(filePath) || isSpaPagesTreeFile(filePath)) {
+    return `
+This file sits under src/pages. In Next.js that directory is the Pages Router.
+Move this file out of src/pages (keep the component and its business logic) into a folder Next does not treat as routes.
+Then add or update src/app/<route>/page.tsx so the App Router imports that screen for the former URL.
+The home route ("/") is src/app/page.tsx and must render the former "/" screen \u2014 not an empty shell, null, a TODO, or a deleted App.tsx.
+Delete the old src/pages copy after the screen exists elsewhere.
+`;
+  }
+  if (isSpaRootComponent(filePath)) {
+    return `
+This is a SPA root/entry file (App.tsx / main.tsx / index.tsx).
+Read it and map each route to src/app/<path>/page.tsx that imports the actual screen component (after moving anything that lived under src/pages).
+src/app/page.tsx must render the home screen. Never import App from the new page (App is being removed).
+Never write a stub that the root component "could not be resolved". After App Router files exist with real UI, delete this legacy root file.
+`;
+  }
+  if (/[/\\]src[/\\]app[/\\].*page\.(t|j)sx$/i.test(filePath)) {
+    return `
+This is a Next App Router page. Import the existing screen component and return it.
+Do not paste that screen's JSX here. Do not rename its public props at the wrapper.
+Do not hollow out the module you imported from.
+`;
+  }
+  return "";
+}
+var NEXT_PAGES_RESERVED = /(?:^|[/\\])(_app|_document|_error|404|500)\.(t|j)sx?$/i;
+function isSpaPagesTreeFile(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  if (!/\/src\/pages\//i.test(normalized)) return false;
+  if (/\/src\/pages\/api\//i.test(normalized)) return false;
+  if (NEXT_PAGES_RESERVED.test(normalized)) return false;
+  return true;
+}
+function listFilesRecursive(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (/\.(t|j)sx?$/.test(entry.name)) out.push(full);
+    }
+  }
+  return out;
+}
+function findAppRouterHome(shadowRoot) {
+  const candidates = [
+    path.join(shadowRoot, "src", "app", "page.tsx"),
+    path.join(shadowRoot, "src", "app", "page.jsx"),
+    path.join(shadowRoot, "app", "page.tsx"),
+    path.join(shadowRoot, "app", "page.jsx")
+  ];
+  return candidates.find((file) => fs.existsSync(file)) || null;
+}
+function listAppRouterFiles(shadowRoot) {
+  const roots = [path.join(shadowRoot, "src", "app"), path.join(shadowRoot, "app")];
+  const names = /^(page|layout)\.(t|j)sx$/i;
+  return roots.flatMap((dir) => listFilesRecursive(dir).filter((file) => names.test(path.basename(file))));
+}
+function isHollowView(content) {
+  const withoutComments = content.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+  const hasFeatureImports = /from\s+['"][^'"]*\/(features|entities|widgets)\//.test(withoutComments);
+  const tinyTree = /<h1[^>]*>[^<]{0,40}<\/h1>/.test(withoutComments) && !hasFeatureImports;
+  const emptyMain = /<main>\s*<h1>/.test(withoutComments) && !hasFeatureImports;
+  return tinyTree || emptyMain;
+}
+function findViewPages(shadowRoot) {
+  const viewsDir = path.join(shadowRoot, "src", "views");
+  return listFilesRecursive(viewsDir).filter((file) => /(?:^|[/\\])(?:.+Page|page)\.(t|j)sx$/i.test(file));
+}
+function resolveLocalImport(fromFile, specifier) {
+  const dir = path.dirname(fromFile);
+  const resolved = specifier.startsWith("@/") ? path.join(findSrcRoot(fromFile), specifier.slice(2)) : path.resolve(dir, specifier);
+  const candidates = [
+    resolved,
+    `${resolved}.tsx`,
+    `${resolved}.jsx`,
+    `${resolved}.ts`,
+    `${resolved}.js`,
+    path.join(resolved, "index.tsx"),
+    path.join(resolved, "index.ts")
+  ];
+  return candidates.find((file) => {
+    try {
+      return fs.existsSync(file) && fs.statSync(file).isFile();
+    } catch {
+      return false;
+    }
+  }) || null;
+}
+function localTsxImports(fromFile, content) {
+  const out = [];
+  const re = /import\s+(?:\{([^}]+)\}|(\w+))\s+from\s+['"](\.\.?\/[^'"]+|@\/[^'"]+)['"]/g;
+  let match;
+  while ((match = re.exec(content)) !== null) {
+    const absPath = resolveLocalImport(fromFile, match[3]);
+    if (!absPath) continue;
+    if (match[2]) out.push({ tag: match[2], absPath });
+    if (match[1]) {
+      for (const part of match[1].split(",")) {
+        const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+        if (name) out.push({ tag: name, absPath });
+      }
+    }
+  }
+  return out;
+}
+function unresolvedLocalImports(fromFile, content) {
+  const out = [];
+  const re = /from\s+['"](\.\.?\/[^'"]+|@\/[^'"]+)['"]/g;
+  let match;
+  while ((match = re.exec(content)) !== null) {
+    if (!resolveLocalImport(fromFile, match[1])) {
+      out.push(match[1]);
+    }
+  }
+  return out;
+}
+function analyzeUnresolvedLocalImports(shadowRoot) {
+  const issues = [];
+  const files = [
+    ...listFilesRecursive(path.join(shadowRoot, "src", "app")),
+    ...listFilesRecursive(path.join(shadowRoot, "app"))
+  ].filter((file) => /\.(t|j)sx$/.test(file));
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf-8");
+    const missing = unresolvedLocalImports(file, content);
+    if (missing.length === 0) continue;
+    issues.push({
+      filePath: file,
+      errors: [
+        `${path.relative(shadowRoot, file)} imports modules that are not on disk: ${missing.join(", ")}. Do not import a deleted App/main from App Router pages \u2014 import the surviving screen component instead.`
+      ]
+    });
+  }
+  return issues;
+}
+function findSrcRoot(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const idx = normalized.lastIndexOf("/src/");
+  if (idx === -1) return path.dirname(filePath);
+  return filePath.slice(0, idx + 4);
+}
+function declaredCallbackProps(componentSource) {
+  const names = /* @__PURE__ */ new Set();
+  const iface = /interface\s+\w+\s*\{([^}]+)\}/g;
+  let block;
+  while ((block = iface.exec(componentSource)) !== null) {
+    const field = /(\b(?:on[A-Z]\w+|action[A-Z]\w+)\??)\s*:/g;
+    let f;
+    while ((f = field.exec(block[1])) !== null) names.add(f[1].replace("?", ""));
+  }
+  const dest = /export\s+(?:default\s+)?function\s+\w+\s*\(\s*\{\s*([^}]+)\}/;
+  const d = dest.exec(componentSource);
+  if (d) {
+    for (const part of d[1].split(",")) {
+      const name = part.trim().split(":")[0].trim();
+      if (/^(on[A-Z]|action[A-Z])/.test(name)) names.add(name);
+    }
+  }
+  return [...names];
+}
+function jsxCallbackProps(callerSource, tag) {
+  const names = [];
+  const tagRe = new RegExp(`<${tag}\\b([^>]*)\\/?>`, "g");
+  let match;
+  while ((match = tagRe.exec(callerSource)) !== null) {
+    const propRe = /\b((?:on|action)[A-Z]\w+)\s*=/g;
+    let p;
+    while ((p = propRe.exec(match[1])) !== null) names.push(p[1]);
+  }
+  return names;
+}
+function analyzeCallbackPropMismatches(shadowRoot) {
+  const issues = [];
+  const files = [
+    ...listFilesRecursive(path.join(shadowRoot, "src", "app")),
+    ...listFilesRecursive(path.join(shadowRoot, "app")),
+    ...listFilesRecursive(path.join(shadowRoot, "src", "views"))
+  ].filter((file) => /\.(t|j)sx$/.test(file));
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf-8");
+    for (const imp of localTsxImports(file, content)) {
+      let callee;
+      try {
+        callee = fs.readFileSync(imp.absPath, "utf-8");
+      } catch {
+        continue;
+      }
+      const expected = declaredCallbackProps(callee);
+      if (expected.length === 0) continue;
+      const passed = jsxCallbackProps(content, imp.tag);
+      const missing = expected.filter((name) => !passed.includes(name));
+      const extra = passed.filter((name) => !expected.includes(name));
+      if (missing.length === 0 && extra.length === 0) continue;
+      issues.push({
+        filePath: file,
+        errors: [
+          `<${imp.tag}> public callback props do not match ${path.relative(shadowRoot, imp.absPath)}. Expected: ${expected.join(", ") || "(none)"}. Passed: ${passed.join(", ") || "(none)"}. Do not rename props when wrapping a screen in a router file.`
+        ]
+      });
+    }
+  }
+  return issues;
+}
+function analyzeReactToNextComposition(shadowRoot) {
+  const issues = [];
+  const home = findAppRouterHome(shadowRoot);
+  if (!home) return issues;
+  const homeContent = fs.readFileSync(home, "utf-8");
+  const views = findViewPages(shadowRoot);
+  const hollowViews = views.filter((file) => isHollowView(fs.readFileSync(file, "utf-8")));
+  const homeImportsView = views.some((file) => {
+    const stem = path.basename(file).replace(/\.(t|j)sx$/, "");
+    return homeContent.includes(stem);
+  });
+  const homeAssemblesFeatures = /from\s+['"][^'"]*\/(features|entities|widgets)\//.test(homeContent);
+  if (views.length > 0 && !homeImportsView && homeAssemblesFeatures) {
+    issues.push({
+      filePath: home,
+      errors: [
+        "The App Router home reassembles the UI from lower-level modules instead of importing the existing route-level screen. Import that screen and return it. Renaming props at the wrapper causes runtime TypeError while next build still succeeds."
+      ]
+    });
+  }
+  for (const file of hollowViews) {
+    issues.push({
+      filePath: file,
+      errors: [
+        "This screen was hollowed out. Restore the original UI here. The App Router page should import this file, not replace it with a stub heading."
+      ]
+    });
+  }
+  return issues;
+}
+function isStubAppRouterPage(content) {
+  const hasLocalImport = /from\s+['"](\.\.?\/|@\/)/.test(content);
+  const emptyish = /return\s*\(\s*<main\s*\/>\s*\)|return\s+null\s*;?|return\s*\(\s*<>\s*<\/>\s*\)|TODO:|could not be resolved/i.test(content);
+  const onlyLayoutShell = /<main\s*\/>/.test(content) && !hasLocalImport;
+  return !hasLocalImport || emptyish || onlyLayoutShell;
+}
+function analyzeReactToNextStructure(shadowRoot) {
+  const issues = [];
+  const pagesDir = path.join(shadowRoot, "src", "pages");
+  if (fs.existsSync(pagesDir)) {
+    for (const file of listFilesRecursive(pagesDir)) {
+      if (!isSpaPagesTreeFile(file)) continue;
+      issues.push({
+        filePath: file,
+        errors: [
+          "This UI still lives under src/pages. Next.js will treat it as a Pages Router route. Move it to a folder Next does not reserve, then import it from src/app/**/page.tsx for the old URL. Remove the src/pages copy."
+        ]
+      });
+    }
+  }
+  const home = findAppRouterHome(shadowRoot);
+  if (!home) {
+    issues.push({
+      filePath: path.join(shadowRoot, "src", "app", "page.tsx"),
+      errors: [
+        'Missing App Router home (src/app/page.tsx). Create it so it imports and renders the screen the SPA showed at "/".'
+      ]
+    });
+    return issues;
+  }
+  const homeContent = fs.readFileSync(home, "utf-8");
+  if (isStubAppRouterPage(homeContent)) {
+    issues.push({
+      filePath: home,
+      errors: [
+        "src/app/page.tsx does not render the application UI. Import the former home screen component (after moving any SPA UI out of src/pages if needed). Do not return an empty shell, null, a TODO, or a deleted App.tsx."
+      ]
+    });
+  }
+  issues.push(...analyzeUnresolvedLocalImports(shadowRoot));
+  issues.push(...analyzeReactToNextComposition(shadowRoot));
+  issues.push(...analyzeCallbackPropMismatches(shadowRoot));
+  const pkgPath = path.join(shadowRoot, "package.json");
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+      const viteScripts = Object.entries(pkg.scripts || {}).filter(([, cmd]) => /\bvite\b/.test(cmd));
+      if (viteScripts.length > 0) {
+        issues.push({
+          filePath: pkgPath,
+          errors: [
+            `package.json still runs Vite in scripts (${viteScripts.map(([name]) => name).join(", ")}). After moving to Next, drop leftover preview/vite scripts.`
+          ]
+        });
+      }
+    } catch {
+    }
+  }
+  return issues;
+}
+
+export {
+  findShadowRoot,
+  isFsdPageComponent,
+  isSpaRootComponent,
+  hasNextAppRoutes,
+  nextMigrationFileHint,
+  isSpaPagesTreeFile,
+  listAppRouterFiles,
+  isHollowView,
+  unresolvedLocalImports,
+  analyzeUnresolvedLocalImports,
+  analyzeCallbackPropMismatches,
+  analyzeReactToNextComposition,
+  isStubAppRouterPage,
+  analyzeReactToNextStructure
+};