@nikelyh/metamorph 2.1.0 → 2.1.2

package/README.md

@@ -16,16 +16,19 @@
 
 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.
+- **Project Intelligence Engine (PIE)** -- Autonomously detects project architecture, frameworks, and monorepo workspace topologies (Turborepo, pnpm workspaces, npm/yarn workspaces, Lerna).
+- **Polymorphic Package Manager (PPME)** -- Automatically detects and adapts to your chosen package manager (`npm`, `pnpm`, `yarn`, `bun`) without host process leakage.
+- **Multi-Agent Concurrency** -- Utilizes Mapper, Worker, Reviewer, Integration, and Coordinator agents to migrate code in parallel.
+- **Zero Risk (Shadow Workspace)** -- All migrations happen in an isolated `.metamorph/shadow` workspace. Your original code is completely untouched until you explicitly approve and apply the changes.
+- **Shadow Build Verification** -- Every migration is validated with your package manager (`npm`, `pnpm`, `yarn`, `bun`) and verification build inside the shadow workspace before completion.
+- **Visual Dashboard** -- Watch your agents work in real-time through the built-in local dashboard UI.
+- **Extensive Framework Support** -- Easily migrate between popular frontend and backend frameworks.
 
-## 📦 Installation
+## Installation
 
 Install Metamorph globally via NPM:
 
@@ -33,66 +36,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/ProjectDetector-WU3OD6WT.js

@@ -0,0 +1,16 @@
+import {
+  detectMonorepo,
+  detectTechnologies,
+  inspectManifest,
+  inspectProject,
+  inspectStructure,
+  resolveProjectRoot
+} from "./chunk-XLD7NXYU.js";
+export {
+  detectMonorepo,
+  detectTechnologies,
+  inspectManifest,
+  inspectProject,
+  inspectStructure,
+  resolveProjectRoot
+};

package/dist/{chunk-OXXEISZT.js → chunk-APRESSUR.js}

@@ -1,6 +1,6 @@
 import {
-  findMigrationCatalogEntry
-} from "./chunk-VEAYUIOZ.js";
+  resolveMigrationCatalog
+} from "./chunk-WLHSZWET.js";
 
 // ../infrastructure/src/db/SQLiteStateStore.ts
 import { DatabaseSync } from "node:sqlite";
@@ -50,6 +50,10 @@ var SQLiteStateStore = class {
       this.db.exec("ALTER TABLE plans ADD COLUMN phase TEXT");
     } catch (e) {
     }
+    try {
+      this.db.exec("ALTER TABLE plans ADD COLUMN outcome TEXT");
+    } catch (e) {
+    }
     try {
       this.db.exec("ALTER TABLE plans ADD COLUMN applied_at TEXT");
     } catch (e) {
@@ -58,6 +62,10 @@ var SQLiteStateStore = class {
       this.db.exec("ALTER TABLE plans ADD COLUMN applied_branch TEXT");
     } catch (e) {
     }
+    try {
+      this.db.exec("ALTER TABLE plans ADD COLUMN package_manager TEXT DEFAULT 'npm'");
+    } catch (e) {
+    }
     this.db.exec(`
       CREATE TABLE IF NOT EXISTS tasks (
         plan_id TEXT,
@@ -80,8 +88,8 @@ var SQLiteStateStore = class {
   }
   async savePlan(plan) {
     const stmtPlan = this.db.prepare(`
-      INSERT OR REPLACE INTO plans (id, run_id, target_path, source_framework, target_framework, rules_json, created_at, integration_rounds, phase, applied_at, applied_branch)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      INSERT OR REPLACE INTO plans (id, run_id, target_path, source_framework, target_framework, rules_json, created_at, integration_rounds, phase, outcome, applied_at, applied_branch, package_manager)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
     stmtPlan.run(
       plan.id,
@@ -93,8 +101,10 @@ var SQLiteStateStore = class {
       plan.createdAt.toISOString(),
       plan.integrationRounds ?? 0,
       plan.phase || "files",
+      plan.outcome || null,
       plan.appliedAt ? plan.appliedAt.toISOString() : null,
-      plan.appliedBranch || null
+      plan.appliedBranch || null,
+      plan.packageManager || "npm"
     );
     const stmtTask = this.db.prepare(`
       INSERT OR REPLACE INTO tasks (plan_id, file_path, status, dependencies_json, error)
@@ -115,6 +125,7 @@ var SQLiteStateStore = class {
       id: planRow.id,
       runId: planRow.run_id,
       targetPath: planRow.target_path,
+      packageManager: planRow.package_manager || "npm",
       profile: {
         source: planRow.source_framework,
         target: planRow.target_framework,
@@ -123,6 +134,7 @@ var SQLiteStateStore = class {
       createdAt: new Date(planRow.created_at),
       integrationRounds: planRow.integration_rounds ?? 0,
       phase: planRow.phase || "files",
+      outcome: planRow.outcome || void 0,
       appliedAt: planRow.applied_at ? new Date(planRow.applied_at) : void 0,
       appliedBranch: planRow.applied_branch || void 0,
       tasks: taskRows.map((row) => ({
@@ -195,7 +207,8 @@ function assertSandbox(filePath, sandboxDir) {
   const resolved = path.resolve(filePath);
   if (sandboxDir) {
     const resolvedSandbox = path.resolve(sandboxDir);
-    if (!resolved.startsWith(resolvedSandbox)) {
+    const isInside = resolved === resolvedSandbox || resolved.startsWith(resolvedSandbox + path.sep);
+    if (!isInside) {
       throw new Error(
         `BLOCKED: Path "${resolved}" is outside the sandbox "${resolvedSandbox}". All file operations must stay within the shadow workspace.`
       );
@@ -396,6 +409,16 @@ function createListDirectoryTool(sandboxDir) {
     }
   };
 }
+function createShadowTools(shadowDir) {
+  return [
+    createReadFileTool(shadowDir),
+    createWriteFileTool(shadowDir),
+    createRenameFileTool(shadowDir),
+    createCreateFileTool(shadowDir),
+    createDeleteFileTool(shadowDir),
+    createListDirectoryTool(shadowDir)
+  ];
+}
 
 // ../infrastructure/src/workspace/ShadowWorkspace.ts
 import fs from "fs-extra";
@@ -454,15 +477,16 @@ var ShadowWorkspace = class {
    * Cleans up old shadow runs to save disk space, keeping only the specified number of most recent runs.
    * @param keepCount Number of recent runs to keep (default: 3)
    */
-  cleanupOldRuns(keepCount = 3) {
+  cleanupOldRuns(keepCount = 3, protectedRunIds = []) {
     if (!fs.existsSync(this.baseDir)) return;
+    const protectedSet = new Set(protectedRunIds);
     const runs = fs.readdirSync(this.baseDir).filter((f) => f.startsWith("run_") && fs.statSync(join3(this.baseDir, f)).isDirectory());
     runs.sort();
-    if (runs.length > keepCount) {
-      const toDelete = runs.slice(0, runs.length - keepCount);
-      for (const run of toDelete) {
-        this.rollback(run);
-      }
+    const unprotected = runs.filter((run) => !protectedSet.has(run));
+    if (unprotected.length <= keepCount) return;
+    const toDelete = unprotected.slice(0, unprotected.length - keepCount);
+    for (const run of toDelete) {
+      this.rollback(run);
     }
   }
 };
@@ -472,7 +496,11 @@ import fs2 from "fs-extra";
 import * as path2 from "path";
 import { execFileSync } from "child_process";
 var COPY_IGNORED = ["node_modules", ".git", ".metamorph", "dist", "build", "out", "coverage", ".next"];
-var GITIGNORE_ENTRIES = [".metamorph/", ".next/", "node_modules/", "dist/", "build/", "coverage/", ".env"];
+function isCopyIgnored(itemName) {
+  if (COPY_IGNORED.includes(itemName)) return true;
+  if (itemName === ".env" || itemName.startsWith(".env.")) return true;
+  return false;
+}
 var MigrationIntegrator = class {
   shadowWorkspace;
   constructor(shadowWorkspace) {
@@ -494,6 +522,20 @@ var MigrationIntegrator = class {
         "Metamorph apply requires a Git repository. Run this from a project that already has git (including monorepo packages whose .git lives in a parent folder). Nested git init is not supported."
       );
     }
+    const rootPkgJson = path2.join(gitRoot, "package.json");
+    if (fs2.existsSync(rootPkgJson)) {
+      try {
+        const pkg = JSON.parse(fs2.readFileSync(rootPkgJson, "utf-8"));
+        const normalizedTarget = resolvedTarget.replace(/\\/g, "/");
+        if (pkg.name === "metamorph-monorepo" && normalizedTarget.includes("/scratch/")) {
+          throw new Error(
+            `BLOCKED: Cannot apply to "${resolvedTarget}" because it is inside the development scratch/ directory of the Metamorph repository. Use a standalone git repository for user project migrations.`
+          );
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.startsWith("BLOCKED:")) throw e;
+      }
+    }
     if (this.isIgnoredByGit(gitRoot, resolvedTarget)) {
       throw new Error(
         `Cannot apply via Git: "${resolvedTarget}" is ignored by the repository at "${gitRoot}" (.gitignore). Metamorph will not create branches on a parent repo for ignored sandboxes. Use a standalone git project, or a tracked package inside a monorepo.`
@@ -536,22 +578,17 @@ var MigrationIntegrator = class {
       throw new Error(`git ${args.join(" ")} failed: ${detail || "unknown git error"}`);
     }
   }
-  ensureApplyGitignore(gitRoot) {
-    const gitignorePath = path2.join(gitRoot, ".gitignore");
-    const existing = fs2.existsSync(gitignorePath) ? fs2.readFileSync(gitignorePath, "utf-8") : "";
-    const missing = GITIGNORE_ENTRIES.filter((entry) => {
-      const name = entry.replace(/\/$/, "").replace(".", "\\.");
-      const pattern = new RegExp(`(^|\\n)${name}(/)?(\\n|$)`);
-      return !pattern.test(existing.replace(/\r/g, "\n"));
-    });
-    if (missing.length === 0) return;
-    const block = `
-# Metamorph apply
-${missing.join("\n")}
-`;
-    fs2.appendFileSync(gitignorePath, block, "utf-8");
-  }
   async applyWithGit(runId, shadowDir, targetPath, gitRoot, branchName) {
+    const relativeTarget = path2.relative(gitRoot, targetPath).replace(/\\/g, "/");
+    const addPath = relativeTarget === "" ? "." : relativeTarget;
+    const dirtyStatus = this.git(["status", "--porcelain", "--", addPath], gitRoot).trim();
+    if (dirtyStatus) {
+      throw new Error(
+        `Cannot apply migration: the target directory has uncommitted changes:
+${dirtyStatus}
+Please commit or stash your changes before applying.`
+      );
+    }
     try {
       this.git(["checkout", "-B", branchName], gitRoot);
     } catch (e) {
@@ -561,9 +598,6 @@ ${missing.join("\n")}
       throw new Error(`Failed to create/reset git branch ${branchName}: ${String(e)}`);
     }
     this.copyShadowToTarget(shadowDir, targetPath);
-    this.ensureApplyGitignore(gitRoot);
-    const relativeTarget = path2.relative(gitRoot, targetPath).replace(/\\/g, "/");
-    const addPath = relativeTarget === "" ? "." : relativeTarget;
     try {
       try {
         this.git(["-c", "advice.addIgnoredFile=false", "add", "-A", "--", addPath], gitRoot);
@@ -597,13 +631,13 @@ ${missing.join("\n")}
     if (fs2.existsSync(targetPath)) {
       const targetItems = fs2.readdirSync(targetPath);
       for (const item of targetItems) {
-        if (COPY_IGNORED.includes(item)) continue;
+        if (isCopyIgnored(item)) continue;
         fs2.removeSync(path2.join(targetPath, item));
       }
     }
     const shadowItems = fs2.readdirSync(shadowDir);
     for (const item of shadowItems) {
-      if (COPY_IGNORED.includes(item)) continue;
+      if (isCopyIgnored(item)) continue;
       const itemSrc = path2.join(shadowDir, item);
       const itemDest = path2.join(targetPath, item);
       fs2.copySync(itemSrc, itemDest, { overwrite: true });
@@ -677,12 +711,16 @@ async function createApiServer(store, migrationRunner) {
   });
   app.get("/api/detect", async (req, res) => {
     try {
-      const { detectTechnologies } = await import("./TechDetector-5YP44RVR.js");
+      const { detectTechnologies: detectTechnologies2, inspectProject: inspectProject2, detectMonorepo } = await import("./ProjectDetector-WU3OD6WT.js");
       const targetPath = req.query.path ? String(req.query.path) : ".";
-      const detected = detectTechnologies(targetPath);
+      const monorepo = detectMonorepo(targetPath);
+      const profiles = inspectProject2(targetPath);
+      const detected = detectTechnologies2(targetPath);
       res.json({
         detected,
-        primary: detected.length > 0 ? detected[0].framework : null
+        profiles,
+        monorepo: monorepo.isMonorepo ? monorepo : null,
+        primary: profiles.length > 0 ? profiles[0].framework : null
       });
     } catch (error) {
       if (error instanceof Error) {
@@ -702,7 +740,7 @@ async function createApiServer(store, migrationRunner) {
           });
           return;
         }
-        const catalogEntry = findMigrationCatalogEntry(from, to);
+        const catalogEntry = resolveMigrationCatalog(from, to);
         if (!catalogEntry) {
           res.status(400).json({
             error: `Unsupported migration profile: ${from} -> ${to}. Please check the supported catalog.`
@@ -732,15 +770,29 @@ async function createApiServer(store, migrationRunner) {
           });
           return;
         }
-        const integrator = new MigrationIntegrator(migrationRunner.workspace);
-        const result = await integrator.applyMigration(runId, targetPath);
         const plans = await store.getAllPlans();
         const plan = plans.find((item) => item.runId === runId);
-        if (plan) {
-          plan.appliedAt = /* @__PURE__ */ new Date();
-          plan.appliedBranch = result.branch;
-          await store.savePlan(plan);
+        if (!plan) {
+          res.status(404).json({ error: `Plan for run "${runId}" not found in database.` });
+          return;
+        }
+        if (plan.phase !== "completed" || plan.outcome !== "success") {
+          res.status(400).json({
+            error: `Cannot apply migration: plan is not completed successfully (phase: "${plan.phase}", outcome: "${plan.outcome || "none"}"). Only successful migrations can be applied.`
+          });
+          return;
         }
+        if (plan.appliedAt) {
+          res.status(400).json({
+            error: `Migration for run "${runId}" has already been applied at ${new Date(plan.appliedAt).toISOString()} to branch ${plan.appliedBranch || "unknown"}.`
+          });
+          return;
+        }
+        const integrator = new MigrationIntegrator(migrationRunner.workspace);
+        const result = await integrator.applyMigration(runId, targetPath);
+        plan.appliedAt = /* @__PURE__ */ new Date();
+        plan.appliedBranch = result.branch;
+        await store.savePlan(plan);
         await store.logEvent("migration.applied", { runId, branch: result.branch, targetPath });
         res.json({ ok: true, ...result });
       } catch (error) {
@@ -918,7 +970,11 @@ function parseImplicatedFiles(output, shadowPath) {
     const resolved = path4.resolve(abs);
     const inside = resolved === root || resolved.startsWith(root + path4.sep);
     if (!inside) return;
-    if (fs3.existsSync(resolved) && fs3.statSync(resolved).isFile()) found.add(resolved);
+    if (fs3.existsSync(resolved)) {
+      if (fs3.statSync(resolved).isFile()) found.add(resolved);
+    } else {
+      found.add(resolved);
+    }
   };
   for (const re of patterns) {
     let match;
@@ -953,13 +1009,16 @@ ${result.output}`;
 
 export {
   SQLiteStateStore,
+  assertSandbox,
   createReadFileTool,
   createWriteFileTool,
   createRenameFileTool,
   createCreateFileTool,
   createDeleteFileTool,
   createListDirectoryTool,
+  createShadowTools,
   ShadowWorkspace,
+  isCopyIgnored,
   MigrationIntegrator,
   createApiServer,
   createCheckProjectDiagnosticsTool,