@mastra/agent-builder 0.0.0-experimental-agent-builder-20250815195917 → 0.0.1-alpha.1

package/dist/index.js

@@ -1,13 +1,13 @@
 import { Agent } from '@mastra/core/agent';
 import { Memory } from '@mastra/memory';
 import { TokenLimiter } from '@mastra/memory/processors';
-import { exec as exec$1, spawn as spawn$1 } from 'child_process';
-import { mkdtemp, rm, readFile, mkdir, copyFile, writeFile, stat, readdir } from 'fs/promises';
+import { exec as exec$1, execFile as execFile$1, spawn as spawn$1 } from 'child_process';
+import { mkdtemp, rm, readFile, writeFile, mkdir, copyFile, stat, readdir } from 'fs/promises';
 import { join, resolve, dirname, extname, basename, isAbsolute, relative } from 'path';
 import { createTool } from '@mastra/core/tools';
-import { MCPClient } from '@mastra/mcp';
+import ignore from 'ignore';
 import { z } from 'zod';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { createRequire } from 'module';
 import { promisify } from 'util';
 import { MemoryProcessor, Agent as Agent$1 } from '@mastra/core';
@@ -15,7 +15,7 @@ import { tmpdir } from 'os';
 import { openai } from '@ai-sdk/openai';
 import { createStep, createWorkflow } from '@mastra/core/workflows';
 
-// src/index.ts
+// src/agent/index.ts
 var UNIT_KINDS = ["mcp-server", "tool", "workflow", "agent", "integration", "network", "other"];
 var TemplateUnitSchema = z.object({
   kind: z.enum(UNIT_KINDS),
@@ -28,7 +28,7 @@ z.object({
   description: z.string().optional(),
   units: z.array(TemplateUnitSchema)
 });
-var MergeInputSchema = z.object({
+var AgentBuilderInputSchema = z.object({
   repo: z.string().describe("Git URL or local path of the template repo"),
   ref: z.string().optional().describe("Tag/branch/commit to checkout (defaults to main/master)"),
   slug: z.string().optional().describe("Slug for branch/scripts; defaults to inferred from repo"),
@@ -40,51 +40,342 @@ z.object({
   templateDir: z.string(),
   units: z.array(TemplateUnitSchema)
 });
+var CopiedFileSchema = z.object({
+  source: z.string(),
+  destination: z.string(),
+  unit: z.object({
+    kind: z.enum(UNIT_KINDS),
+    id: z.string()
+  })
+});
+var ConflictSchema = z.object({
+  unit: z.object({
+    kind: z.enum(UNIT_KINDS),
+    id: z.string()
+  }),
+  issue: z.string(),
+  sourceFile: z.string(),
+  targetFile: z.string()
+});
+var FileCopyInputSchema = z.object({
+  orderedUnits: z.array(TemplateUnitSchema),
+  templateDir: z.string(),
+  commitSha: z.string(),
+  slug: z.string(),
+  targetPath: z.string().optional()
+});
+var FileCopyResultSchema = z.object({
+  success: z.boolean(),
+  copiedFiles: z.array(CopiedFileSchema),
+  conflicts: z.array(ConflictSchema),
+  message: z.string(),
+  error: z.string().optional()
+});
+var ConflictResolutionSchema = z.object({
+  unit: z.object({
+    kind: z.enum(UNIT_KINDS),
+    id: z.string()
+  }),
+  issue: z.string(),
+  resolution: z.string()
+});
+var IntelligentMergeInputSchema = z.object({
+  conflicts: z.array(ConflictSchema),
+  copiedFiles: z.array(CopiedFileSchema),
+  templateDir: z.string(),
+  commitSha: z.string(),
+  slug: z.string(),
+  targetPath: z.string().optional(),
+  branchName: z.string().optional()
+});
+var IntelligentMergeResultSchema = z.object({
+  success: z.boolean(),
+  applied: z.boolean(),
+  message: z.string(),
+  conflictsResolved: z.array(ConflictResolutionSchema),
+  error: z.string().optional()
+});
+var ValidationResultsSchema = z.object({
+  valid: z.boolean(),
+  errorsFixed: z.number(),
+  remainingErrors: z.number()
+});
+var ValidationFixInputSchema = z.object({
+  commitSha: z.string(),
+  slug: z.string(),
+  targetPath: z.string().optional(),
+  templateDir: z.string(),
+  orderedUnits: z.array(TemplateUnitSchema),
+  copiedFiles: z.array(CopiedFileSchema),
+  conflictsResolved: z.array(ConflictResolutionSchema).optional(),
+  maxIterations: z.number().optional().default(5)
+});
+var ValidationFixResultSchema = z.object({
+  success: z.boolean(),
+  applied: z.boolean(),
+  message: z.string(),
+  validationResults: ValidationResultsSchema,
+  error: z.string().optional()
+});
 var ApplyResultSchema = z.object({
   success: z.boolean(),
   applied: z.boolean(),
   branchName: z.string().optional(),
+  message: z.string(),
+  validationResults: ValidationResultsSchema.optional(),
+  error: z.string().optional(),
+  errors: z.array(z.string()).optional(),
+  stepResults: z.object({
+    cloneSuccess: z.boolean().optional(),
+    analyzeSuccess: z.boolean().optional(),
+    discoverSuccess: z.boolean().optional(),
+    orderSuccess: z.boolean().optional(),
+    prepareBranchSuccess: z.boolean().optional(),
+    packageMergeSuccess: z.boolean().optional(),
+    installSuccess: z.boolean().optional(),
+    copySuccess: z.boolean().optional(),
+    mergeSuccess: z.boolean().optional(),
+    validationSuccess: z.boolean().optional(),
+    filesCopied: z.number(),
+    conflictsSkipped: z.number(),
+    conflictsResolved: z.number()
+  }).optional()
+});
+var CloneTemplateResultSchema = z.object({
+  templateDir: z.string(),
+  commitSha: z.string(),
+  slug: z.string(),
+  success: z.boolean().optional(),
+  error: z.string().optional()
+});
+var PackageAnalysisSchema = z.object({
+  name: z.string().optional(),
+  version: z.string().optional(),
+  description: z.string().optional(),
+  dependencies: z.record(z.string()).optional(),
+  devDependencies: z.record(z.string()).optional(),
+  peerDependencies: z.record(z.string()).optional(),
+  scripts: z.record(z.string()).optional(),
+  success: z.boolean().optional(),
+  error: z.string().optional()
+});
+var DiscoveryResultSchema = z.object({
+  units: z.array(TemplateUnitSchema),
+  success: z.boolean().optional(),
+  error: z.string().optional()
+});
+var OrderedUnitsSchema = z.object({
+  orderedUnits: z.array(TemplateUnitSchema),
+  success: z.boolean().optional(),
+  error: z.string().optional()
+});
+var PackageMergeInputSchema = z.object({
+  commitSha: z.string(),
+  slug: z.string(),
+  targetPath: z.string().optional(),
+  packageInfo: PackageAnalysisSchema
+});
+var PackageMergeResultSchema = z.object({
+  success: z.boolean(),
+  applied: z.boolean(),
+  message: z.string(),
+  error: z.string().optional()
+});
+var InstallInputSchema = z.object({
+  targetPath: z.string().describe("Path to the project to install packages in")
+});
+var InstallResultSchema = z.object({
+  success: z.boolean(),
+  error: z.string().optional()
+});
+var PrepareBranchInputSchema = z.object({
+  slug: z.string(),
+  commitSha: z.string().optional(),
+  // from clone-template if relevant
+  targetPath: z.string().optional()
+});
+var PrepareBranchResultSchema = z.object({
+  branchName: z.string(),
+  success: z.boolean().optional(),
   error: z.string().optional()
 });
 
 // src/utils.ts
 var exec = promisify(exec$1);
+var execFile = promisify(execFile$1);
+function isInWorkspaceSubfolder(cwd) {
+  try {
+    const currentPackageJson = resolve(cwd, "package.json");
+    if (!existsSync(currentPackageJson)) {
+      return false;
+    }
+    let currentDir = cwd;
+    let previousDir = "";
+    while (currentDir !== previousDir && currentDir !== "/") {
+      previousDir = currentDir;
+      currentDir = dirname(currentDir);
+      if (currentDir === cwd) {
+        continue;
+      }
+      console.log(`Checking for workspace indicators in: ${currentDir}`);
+      if (existsSync(resolve(currentDir, "pnpm-workspace.yaml"))) {
+        return true;
+      }
+      const parentPackageJson = resolve(currentDir, "package.json");
+      if (existsSync(parentPackageJson)) {
+        try {
+          const parentPkg = JSON.parse(readFileSync(parentPackageJson, "utf-8"));
+          if (parentPkg.workspaces) {
+            return true;
+          }
+        } catch {
+        }
+      }
+      if (existsSync(resolve(currentDir, "lerna.json"))) {
+        return true;
+      }
+    }
+    return false;
+  } catch (error) {
+    console.log(`Error in workspace detection: ${error}`);
+    return false;
+  }
+}
 function spawn(command, args, options) {
   return new Promise((resolve4, reject) => {
     const childProcess = spawn$1(command, args, {
-      // stdio: 'inherit',
+      stdio: "inherit",
+      // Enable proper stdio handling
       ...options
     });
     childProcess.on("error", (error) => {
       reject(error);
     });
+    childProcess.on("close", (code) => {
+      if (code === 0) {
+        resolve4(void 0);
+      } else {
+        reject(new Error(`Command failed with exit code ${code}`));
+      }
+    });
+  });
+}
+async function isGitInstalled() {
+  try {
+    await spawnWithOutput("git", ["--version"], {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isInsideGitRepo(cwd) {
+  try {
+    if (!await isGitInstalled()) return false;
+    const { stdout } = await spawnWithOutput("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+    return stdout.trim() === "true";
+  } catch {
+    return false;
+  }
+}
+function spawnWithOutput(command, args, options) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const childProcess = spawn$1(command, args, {
+      ...options
+    });
+    let stdout = "";
     let stderr = "";
-    childProcess.stderr?.on("data", (message) => {
-      stderr += message;
+    childProcess.on("error", (error) => {
+      rejectPromise(error);
+    });
+    childProcess.stdout?.on("data", (chunk) => {
+      process.stdout.write(chunk);
+      stdout += chunk?.toString?.() ?? String(chunk);
+    });
+    childProcess.stderr?.on("data", (chunk) => {
+      stderr += chunk?.toString?.() ?? String(chunk);
+      process.stderr.write(chunk);
     });
     childProcess.on("close", (code) => {
       if (code === 0) {
-        resolve4(void 0);
+        resolvePromise({ stdout, stderr, code: code ?? 0 });
       } else {
-        reject(new Error(stderr));
+        const err = new Error(stderr || `Command failed: ${command} ${args.join(" ")}`);
+        err.code = code;
+        rejectPromise(err);
       }
     });
   });
 }
 async function spawnSWPM(cwd, command, packageNames) {
-  await spawn(createRequire(import.meta.filename).resolve("swpm"), [command, ...packageNames], {
-    cwd
-  });
+  try {
+    console.log("Running install command with swpm");
+    const swpmPath = createRequire(import.meta.filename).resolve("swpm");
+    await spawn(swpmPath, [command, ...packageNames], { cwd });
+    return;
+  } catch (e) {
+    console.log("Failed to run install command with swpm", e);
+  }
+  try {
+    let packageManager;
+    if (existsSync(resolve(cwd, "pnpm-lock.yaml"))) {
+      packageManager = "pnpm";
+    } else if (existsSync(resolve(cwd, "yarn.lock"))) {
+      packageManager = "yarn";
+    } else {
+      packageManager = "npm";
+    }
+    let nativeCommand = command === "add" ? "add" : command === "install" ? "install" : command;
+    const args = [nativeCommand];
+    if (nativeCommand === "install") {
+      const inWorkspace = isInWorkspaceSubfolder(cwd);
+      if (packageManager === "pnpm") {
+        args.push("--force");
+        if (inWorkspace) {
+          args.push("--ignore-workspace");
+        }
+      } else if (packageManager === "npm") {
+        args.push("--yes");
+        if (inWorkspace) {
+          args.push("--ignore-workspaces");
+        }
+      }
+    }
+    args.push(...packageNames);
+    console.log(`Falling back to ${packageManager} ${args.join(" ")}`);
+    await spawn(packageManager, args, { cwd });
+    return;
+  } catch (e) {
+    console.log(`Failed to run install command with native package manager: ${e}`);
+  }
+  throw new Error(`Failed to run install command with swpm and native package managers`);
 }
 function kindWeight(kind) {
   const idx = UNIT_KINDS.indexOf(kind);
   return idx === -1 ? UNIT_KINDS.length : idx;
 }
+async function fetchMastraTemplates() {
+  try {
+    const response = await fetch("https://mastra.ai/api/templates.json");
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    throw new Error(`Failed to fetch Mastra templates: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function getMastraTemplate(slug) {
+  const templates = await fetchMastraTemplates();
+  const template = templates.find((t) => t.slug === slug);
+  if (!template) {
+    throw new Error(`Template "${slug}" not found. Available templates: ${templates.map((t) => t.slug).join(", ")}`);
+  }
+  return template;
+}
 async function logGitState(targetPath, label) {
   try {
-    const gitStatusResult = await exec("git status --porcelain", { cwd: targetPath });
-    const gitLogResult = await exec("git log --oneline -3", { cwd: targetPath });
-    const gitCountResult = await exec("git rev-list --count HEAD", { cwd: targetPath });
+    if (!await isInsideGitRepo(targetPath)) return;
+    const gitStatusResult = await git(targetPath, "status", "--porcelain");
+    const gitLogResult = await git(targetPath, "log", "--oneline", "-3");
+    const gitCountResult = await git(targetPath, "rev-list", "--count", "HEAD");
     console.log(`\u{1F4CA} Git state ${label}:`);
     console.log("Status:", gitStatusResult.stdout.trim() || "Clean working directory");
     console.log("Recent commits:", gitLogResult.stdout.trim());
@@ -93,6 +384,91 @@ async function logGitState(targetPath, label) {
     console.warn(`Could not get git state ${label}:`, gitError);
   }
 }
+async function git(cwd, ...args) {
+  const { stdout, stderr } = await spawnWithOutput("git", args, { cwd });
+  return { stdout: stdout ?? "", stderr: stderr ?? "" };
+}
+async function gitClone(repo, destDir, cwd) {
+  await git(process.cwd(), "clone", repo, destDir);
+}
+async function gitCheckoutRef(cwd, ref) {
+  if (!await isInsideGitRepo(cwd)) return;
+  await git(cwd, "checkout", ref);
+}
+async function gitRevParse(cwd, rev) {
+  if (!await isInsideGitRepo(cwd)) return "";
+  const { stdout } = await git(cwd, "rev-parse", rev);
+  return stdout.trim();
+}
+async function gitAddFiles(cwd, files) {
+  if (!files || files.length === 0) return;
+  if (!await isInsideGitRepo(cwd)) return;
+  await git(cwd, "add", ...files);
+}
+async function gitAddAll(cwd) {
+  if (!await isInsideGitRepo(cwd)) return;
+  await git(cwd, "add", ".");
+}
+async function gitHasStagedChanges(cwd) {
+  if (!await isInsideGitRepo(cwd)) return false;
+  const { stdout } = await git(cwd, "diff", "--cached", "--name-only");
+  return stdout.trim().length > 0;
+}
+async function gitCommit(cwd, message, opts) {
+  try {
+    if (!await isInsideGitRepo(cwd)) return false;
+    if (opts?.skipIfNoStaged) {
+      const has = await gitHasStagedChanges(cwd);
+      if (!has) return false;
+    }
+    const args = ["commit", "-m", message];
+    if (opts?.allowEmpty) args.push("--allow-empty");
+    await git(cwd, ...args);
+    return true;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (/nothing to commit/i.test(msg) || /no changes added to commit/i.test(msg)) {
+      return false;
+    }
+    throw e;
+  }
+}
+async function gitAddAndCommit(cwd, message, files, opts) {
+  try {
+    if (!await isInsideGitRepo(cwd)) return false;
+    if (files && files.length > 0) {
+      await gitAddFiles(cwd, files);
+    } else {
+      await gitAddAll(cwd);
+    }
+    return gitCommit(cwd, message, opts);
+  } catch (e) {
+    console.error(`Failed to add and commit files: ${e instanceof Error ? e.message : String(e)}`);
+    return false;
+  }
+}
+async function gitCheckoutBranch(branchName, targetPath) {
+  try {
+    if (!await isInsideGitRepo(targetPath)) return;
+    await git(targetPath, "checkout", "-b", branchName);
+    console.log(`Created new branch: ${branchName}`);
+  } catch (error) {
+    const errorStr = error instanceof Error ? error.message : String(error);
+    if (errorStr.includes("already exists")) {
+      try {
+        await git(targetPath, "checkout", branchName);
+        console.log(`Switched to existing branch: ${branchName}`);
+      } catch {
+        const timestamp = Date.now().toString().slice(-6);
+        const uniqueBranchName = `${branchName}-${timestamp}`;
+        await git(targetPath, "checkout", "-b", uniqueBranchName);
+        console.log(`Created unique branch: ${uniqueBranchName}`);
+      }
+    } else {
+      throw error;
+    }
+  }
+}
 async function backupAndReplaceFile(sourceFile, targetFile) {
   const backupFile = `${targetFile}.backup-${Date.now()}`;
   await copyFile(targetFile, backupFile);
@@ -503,26 +879,6 @@ export const mastra = new Mastra({
 });
 \`\`\`
 
-### MCPClient
-\`\`\`
-// ./src/mcp/client.ts
-
-import { MCPClient } from '@mastra/mcp-client';
-
-// leverage existing MCP servers, or create your own
-export const mcpClient = new MCPClient({
-  id: 'example-mcp-client',
-  servers: {
-    some-mcp-server: {
-      command: 'npx',
-      args: ["some-mcp-server"],
-    },
-  },
-});
-
-export const tools = await mcpClient.getTools();
-\`\`\`
-
 </examples>`;
   static DEFAULT_MEMORY_CONFIG = {
     lastMessages: 20
@@ -535,28 +891,7 @@ export const tools = await mcpClient.getTools();
     network: "src/mastra/networks"
   };
   static DEFAULT_TOOLS = async (projectPath, mode = "code-editor") => {
-    const mcpClient = new MCPClient({
-      id: "agent-builder-mcp-client",
-      servers: {
-        // web: {
-        // 	command: 'node',
-        // 	args: ['/Users/daniellew/Documents/Mastra/web-search/build/index.js'],
-        // },
-        docs: {
-          command: "npx",
-          args: ["-y", "@mastra/mcp-docs-server"]
-        }
-      }
-    });
-    const tools = await mcpClient.getTools();
-    const filteredTools = {};
-    Object.keys(tools).forEach((key) => {
-      if (!key.includes("MastraCourse")) {
-        filteredTools[key] = tools[key];
-      }
-    });
     const agentBuilderTools = {
-      ...filteredTools,
       readFile: createTool({
         id: "read-file",
         description: "Read contents of a file with optional line range selection.",
@@ -735,6 +1070,27 @@ export const tools = await mcpClient.getTools();
           return await _AgentBuilderDefaults.performMultiEdit({ ...context, projectPath });
         }
       }),
+      replaceLines: createTool({
+        id: "replace-lines",
+        description: "Replace specific line ranges in files with new content. Perfect for fixing multiline imports, function signatures, or other structured code.",
+        inputSchema: z.object({
+          filePath: z.string().describe("Path to the file to edit"),
+          startLine: z.number().describe("Starting line number to replace (1-indexed)"),
+          endLine: z.number().describe("Ending line number to replace (1-indexed, inclusive)"),
+          newContent: z.string().describe("New content to replace the lines with"),
+          createBackup: z.boolean().default(false).describe("Create backup file before editing")
+        }),
+        outputSchema: z.object({
+          success: z.boolean(),
+          message: z.string(),
+          linesReplaced: z.number().optional(),
+          backup: z.string().optional(),
+          error: z.string().optional()
+        }),
+        execute: async ({ context }) => {
+          return await _AgentBuilderDefaults.replaceLines({ ...context, projectPath });
+        }
+      }),
       // Interactive Communication
       askClarification: createTool({
         id: "ask-clarification",
@@ -807,7 +1163,7 @@ export const tools = await mcpClient.getTools();
           })
         }),
         execute: async ({ context }) => {
-          return await _AgentBuilderDefaults.performSmartSearch(context);
+          return await _AgentBuilderDefaults.performSmartSearch(context, projectPath);
         }
       }),
       validateCode: createTool({
@@ -1178,12 +1534,12 @@ export const tools = await mcpClient.getTools();
    */
   static async createMastraProject({ features, projectName }) {
     try {
-      const args = ["pnpx", "create", "mastra@latest", projectName ?? "", "-l", "openai", "-k", "skip"];
+      const args = ["pnpx", "create-mastra@latest", projectName?.replace(/[;&|`$(){}\[\]]/g, "") ?? "", "-l", "openai"];
       if (features && features.length > 0) {
         args.push("--components", features.join(","));
       }
       args.push("--example");
-      const { stdout, stderr } = await exec(args.join(" "));
+      const { stdout, stderr } = await spawnWithOutput(args[0], args.slice(1), {});
       return {
         success: true,
         projectPath: `./${projectName}`,
@@ -1192,6 +1548,7 @@ export const tools = await mcpClient.getTools();
         error: stderr
       };
     } catch (error) {
+      console.log(error);
       return {
         success: false,
         message: `Failed to create project: ${error instanceof Error ? error.message : String(error)}`
@@ -1367,9 +1724,17 @@ export const tools = await mcpClient.getTools();
    * Stop the Mastra server
    */
   static async stopMastraServer({ port = 4200, projectPath: _projectPath }) {
+    if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
+      return {
+        success: false,
+        status: "error",
+        error: `Invalid port value: ${String(port)}`
+      };
+    }
     try {
-      const { stdout } = await exec(`lsof -ti:${port} || echo "No process found"`);
-      if (!stdout.trim() || stdout.trim() === "No process found") {
+      const { stdout } = await execFile("lsof", ["-ti", String(port)]);
+      const effectiveStdout = stdout.trim() ? stdout : "No process found";
+      if (!effectiveStdout || effectiveStdout === "No process found") {
         return {
           success: true,
           status: "stopped",
@@ -1385,8 +1750,9 @@ export const tools = await mcpClient.getTools();
         try {
           process.kill(pid, "SIGTERM");
           killedPids.push(pid);
-        } catch {
+        } catch (e) {
           failedPids.push(pid);
+          console.warn(`Failed to kill process ${pid}:`, e);
         }
       }
       if (killedPids.length === 0) {
@@ -1397,10 +1763,16 @@ export const tools = await mcpClient.getTools();
           error: `Could not kill PIDs: ${failedPids.join(", ")}`
         };
       }
+      if (failedPids.length > 0) {
+        console.warn(
+          `Killed ${killedPids.length} processes but failed to kill ${failedPids.length} processes: ${failedPids.join(", ")}`
+        );
+      }
       await new Promise((resolve4) => setTimeout(resolve4, 2e3));
       try {
-        const { stdout: checkStdout } = await exec(`lsof -ti:${port} || echo "No process found"`);
-        if (checkStdout.trim() && checkStdout.trim() !== "No process found") {
+        const { stdout: checkStdoutRaw } = await execFile("lsof", ["-ti", String(port)]);
+        const checkStdout = checkStdoutRaw.trim() ? checkStdoutRaw : "No process found";
+        if (checkStdout && checkStdout !== "No process found") {
           const remainingPids = checkStdout.trim().split("\n").filter((pid) => pid.trim());
           for (const pidStr of remainingPids) {
             const pid = parseInt(pidStr.trim());
@@ -1412,8 +1784,9 @@ export const tools = await mcpClient.getTools();
             }
           }
           await new Promise((resolve4) => setTimeout(resolve4, 1e3));
-          const { stdout: finalCheck } = await exec(`lsof -ti:${port} || echo "No process found"`);
-          if (finalCheck.trim() && finalCheck.trim() !== "No process found") {
+          const { stdout: finalCheckRaw } = await execFile("lsof", ["-ti", String(port)]);
+          const finalCheck = finalCheckRaw.trim() ? finalCheckRaw : "No process found";
+          if (finalCheck && finalCheck !== "No process found") {
             return {
               success: false,
               status: "unknown",
@@ -1471,8 +1844,9 @@ export const tools = await mcpClient.getTools();
       }
     } catch {
       try {
-        const { stdout } = await exec(`lsof -ti:${port} || echo "No process found"`);
-        const hasProcess = stdout.trim() && stdout.trim() !== "No process found";
+        const { stdout } = await execFile("lsof", ["-ti", String(port)]);
+        const effectiveStdout = stdout.trim() ? stdout : "No process found";
+        const hasProcess = effectiveStdout && effectiveStdout !== "No process found";
         return {
           success: Boolean(hasProcess),
           status: hasProcess ? "starting" : "stopped",
@@ -1503,9 +1877,9 @@ export const tools = await mcpClient.getTools();
     const execOptions = { cwd: projectPath };
     if (validationType.includes("types")) {
       try {
-        const filePattern = files?.length ? files.join(" ") : "";
-        const tscCommand = files?.length ? `npx tsc --noEmit ${filePattern}` : "npx tsc --noEmit";
-        await exec(tscCommand, execOptions);
+        const fileArgs = files?.length ? files : [];
+        const args = ["tsc", "--noEmit", ...fileArgs];
+        await execFile("npx", args, execOptions);
         validationsPassed.push("types");
       } catch (error) {
         let tsOutput = "";
@@ -1526,9 +1900,9 @@ export const tools = await mcpClient.getTools();
     }
     if (validationType.includes("lint")) {
       try {
-        const filePattern = files?.length ? files.join(" ") : ".";
-        const eslintCommand = `npx eslint ${filePattern} --format json`;
-        const { stdout } = await exec(eslintCommand, execOptions);
+        const fileArgs = files?.length ? files : ["."];
+        const eslintArgs = ["eslint", ...fileArgs, "--format", "json"];
+        const { stdout } = await execFile("npx", eslintArgs, execOptions);
         if (stdout) {
           const eslintResults = JSON.parse(stdout);
           const eslintErrors = _AgentBuilderDefaults.parseESLintErrors(eslintResults);
@@ -1662,6 +2036,11 @@ export const tools = await mcpClient.getTools();
     if (!_AgentBuilderDefaults.taskStorage) {
       _AgentBuilderDefaults.taskStorage = /* @__PURE__ */ new Map();
     }
+    const sessions = Array.from(_AgentBuilderDefaults.taskStorage.keys());
+    if (sessions.length > 10) {
+      const sessionsToRemove = sessions.slice(0, sessions.length - 10);
+      sessionsToRemove.forEach((session) => _AgentBuilderDefaults.taskStorage.delete(session));
+    }
     const sessionId = "current";
     const existingTasks = _AgentBuilderDefaults.taskStorage.get(sessionId) || [];
     try {
@@ -1758,7 +2137,35 @@ export const tools = await mcpClient.getTools();
   static async analyzeCode(context) {
     try {
       const { action, path, language, depth = 3 } = context;
-      const languagePattern = language ? `*.${language}` : "*";
+      const ALLOWED_LANGUAGES = [
+        "js",
+        "ts",
+        "jsx",
+        "tsx",
+        "py",
+        "java",
+        "go",
+        "cpp",
+        "c",
+        "cs",
+        "rb",
+        "php",
+        "rs",
+        "kt",
+        "swift",
+        "m",
+        "scala",
+        "sh",
+        "json",
+        "yaml",
+        "yml",
+        "toml",
+        "ini"
+      ];
+      let languagePattern = "*";
+      if (language && ALLOWED_LANGUAGES.includes(language)) {
+        languagePattern = `*.${language}`;
+      }
       switch (action) {
         case "definitions":
           const definitionPatterns = [
@@ -1771,9 +2178,15 @@ export const tools = await mcpClient.getTools();
           const definitions = [];
           for (const pattern of definitionPatterns) {
             try {
-              const { stdout } = await exec(
-                `rg -n "${pattern}" "${path}" --type ${languagePattern} --max-depth ${depth}`
-              );
+              const { stdout } = await execFile("rg", [
+                "-n",
+                pattern,
+                path,
+                "--type",
+                languagePattern,
+                "--max-depth",
+                String(depth)
+              ]);
               const matches = stdout.split("\n").filter((line) => line.trim());
               matches.forEach((match) => {
                 const parts = match.split(":");
@@ -1811,7 +2224,7 @@ export const tools = await mcpClient.getTools();
           const dependencies = [];
           for (const pattern of depPatterns) {
             try {
-              const { stdout } = await exec(`rg -n "${pattern}" "${path}" --type ${languagePattern}`);
+              const { stdout } = await execFile("rg", ["-n", pattern, path, "--type", languagePattern]);
               const matches = stdout.split("\n").filter((line) => line.trim());
               matches.forEach((match) => {
                 const parts = match.split(":");
@@ -1838,10 +2251,11 @@ export const tools = await mcpClient.getTools();
             message: `Found ${dependencies.length} dependencies`
           };
         case "structure":
-          const { stdout: lsOutput } = await exec(`find "${path}" -type f -name "${languagePattern}" | head -1000`);
-          const files = lsOutput.split("\n").filter((line) => line.trim());
-          const { stdout: dirOutput } = await exec(`find "${path}" -type d | wc -l`);
-          const directories = parseInt(dirOutput.trim());
+          const { stdout: lsOutput } = await execFile("find", [path, "-type", "f", "-name", languagePattern]);
+          const allFiles = lsOutput.split("\n").filter((line) => line.trim());
+          const files = allFiles.slice(0, 1e3);
+          const { stdout: dirOutput } = await execFile("find", [path, "-type", "d"]);
+          const directories = dirOutput.split("\n").filter((line) => line.trim()).length;
           const languages = {};
           files.forEach((file) => {
             const ext = file.split(".").pop();
@@ -1881,56 +2295,57 @@ export const tools = await mcpClient.getTools();
    * Perform multiple edits across files atomically
    */
   static async performMultiEdit(context) {
+    const { operations, createBackup = false, projectPath = process.cwd() } = context;
     const results = [];
     try {
-      const { projectPath } = context;
-      for (const operation of context.operations) {
-        const resolvedPath = isAbsolute(operation.filePath) ? operation.filePath : resolve(projectPath || process.cwd(), operation.filePath);
-        const result = {
-          filePath: resolvedPath,
-          editsApplied: 0,
-          errors: [],
-          backup: void 0
-        };
+      for (const operation of operations) {
+        const filePath = isAbsolute(operation.filePath) ? operation.filePath : join(projectPath, operation.filePath);
+        let editsApplied = 0;
+        const errors = [];
+        let backup;
         try {
-          const originalContent = await readFile(resolvedPath, "utf-8");
-          if (context.createBackup) {
-            const backupPath = `${resolvedPath}.backup.${Date.now()}`;
-            await writeFile(backupPath, originalContent);
-            result.backup = backupPath;
+          if (createBackup) {
+            const backupPath = `${filePath}.backup.${Date.now()}`;
+            const originalContent = await readFile(filePath, "utf-8");
+            await writeFile(backupPath, originalContent, "utf-8");
+            backup = backupPath;
           }
-          let modifiedContent = originalContent;
+          let content = await readFile(filePath, "utf-8");
           for (const edit of operation.edits) {
-            if (edit.replaceAll) {
-              const regex = new RegExp(edit.oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
-              const matches = modifiedContent.match(regex);
+            const { oldString, newString, replaceAll = false } = edit;
+            if (replaceAll) {
+              const regex = new RegExp(oldString.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+              const matches = content.match(regex);
               if (matches) {
-                modifiedContent = modifiedContent.replace(regex, edit.newString);
-                result.editsApplied += matches.length;
+                content = content.replace(regex, newString);
+                editsApplied += matches.length;
               }
             } else {
-              if (modifiedContent.includes(edit.oldString)) {
-                modifiedContent = modifiedContent.replace(edit.oldString, edit.newString);
-                result.editsApplied++;
+              if (content.includes(oldString)) {
+                content = content.replace(oldString, newString);
+                editsApplied++;
               } else {
-                result.errors.push(`String not found: "${edit.oldString.substring(0, 50)}..."`);
+                errors.push(`String not found: "${oldString.substring(0, 50)}${oldString.length > 50 ? "..." : ""}"`);
               }
             }
           }
-          if (result.editsApplied > 0) {
-            await writeFile(resolvedPath, modifiedContent);
-          }
+          await writeFile(filePath, content, "utf-8");
         } catch (error) {
-          result.errors.push(error instanceof Error ? error.message : String(error));
+          errors.push(`File operation error: ${error instanceof Error ? error.message : String(error)}`);
         }
-        results.push(result);
+        results.push({
+          filePath: operation.filePath,
+          editsApplied,
+          errors,
+          backup
+        });
       }
       const totalEdits = results.reduce((sum, r) => sum + r.editsApplied, 0);
       const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
       return {
         success: totalErrors === 0,
         results,
-        message: `Applied ${totalEdits} edits across ${results.length} files${totalErrors > 0 ? ` with ${totalErrors} errors` : ""}`
+        message: `Applied ${totalEdits} edits across ${operations.length} files${totalErrors > 0 ? ` with ${totalErrors} errors` : ""}`
       };
     } catch (error) {
       return {
@@ -1940,6 +2355,56 @@ export const tools = await mcpClient.getTools();
       };
     }
   }
+  /**
+   * Replace specific line ranges in a file with new content
+   */
+  static async replaceLines(context) {
+    const { filePath, startLine, endLine, newContent, createBackup = false, projectPath = process.cwd() } = context;
+    try {
+      const fullPath = isAbsolute(filePath) ? filePath : join(projectPath, filePath);
+      const content = await readFile(fullPath, "utf-8");
+      const lines = content.split("\n");
+      if (startLine < 1 || endLine < 1 || startLine > lines.length || endLine > lines.length) {
+        return {
+          success: false,
+          message: `Invalid line range: ${startLine}-${endLine}. File has ${lines.length} lines.`,
+          error: "Invalid line range"
+        };
+      }
+      if (startLine > endLine) {
+        return {
+          success: false,
+          message: `Start line (${startLine}) cannot be greater than end line (${endLine}).`,
+          error: "Invalid line range"
+        };
+      }
+      let backup;
+      if (createBackup) {
+        const backupPath = `${fullPath}.backup.${Date.now()}`;
+        await writeFile(backupPath, content, "utf-8");
+        backup = backupPath;
+      }
+      const beforeLines = lines.slice(0, startLine - 1);
+      const afterLines = lines.slice(endLine);
+      const newLines = newContent ? newContent.split("\n") : [];
+      const updatedLines = [...beforeLines, ...newLines, ...afterLines];
+      const updatedContent = updatedLines.join("\n");
+      await writeFile(fullPath, updatedContent, "utf-8");
+      const linesReplaced = endLine - startLine + 1;
+      return {
+        success: true,
+        message: `Successfully replaced ${linesReplaced} lines (${startLine}-${endLine}) in ${filePath}`,
+        linesReplaced,
+        backup
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Failed to replace lines: ${error instanceof Error ? error.message : String(error)}`,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
   /**
    * Ask user for clarification
    */
@@ -1986,32 +2451,38 @@ export const tools = await mcpClient.getTools();
   /**
    * Perform intelligent search with context
    */
-  static async performSmartSearch(context) {
+  static async performSmartSearch(context, projectPath) {
     try {
       const { query, type = "text", scope = {}, context: searchContext = {} } = context;
       const { paths = ["."], fileTypes = [], excludePaths = [], maxResults = 50 } = scope;
       const { beforeLines = 2, afterLines = 2 } = searchContext;
-      let rgCommand = "rg";
-      if (beforeLines > 0 || afterLines > 0) {
-        rgCommand += ` -A ${afterLines} -B ${beforeLines}`;
+      const rgArgs = [];
+      if (beforeLines > 0) {
+        rgArgs.push("-B", beforeLines.toString());
+      }
+      if (afterLines > 0) {
+        rgArgs.push("-A", afterLines.toString());
       }
-      rgCommand += " -n";
+      rgArgs.push("-n");
       if (type === "regex") {
-        rgCommand += " -e";
+        rgArgs.push("-e");
       } else if (type === "fuzzy") {
-        rgCommand += " --fixed-strings";
+        rgArgs.push("--fixed-strings");
       }
       if (fileTypes.length > 0) {
         fileTypes.forEach((ft) => {
-          rgCommand += ` --type-add 'custom:*.${ft}' -t custom`;
+          rgArgs.push("--type-add", `custom:*.${ft}`, "-t", "custom");
         });
       }
       excludePaths.forEach((path) => {
-        rgCommand += ` --glob '!${path}'`;
+        rgArgs.push("--glob", `!${path}`);
+      });
+      rgArgs.push("-m", maxResults.toString());
+      rgArgs.push(query);
+      rgArgs.push(...paths);
+      const { stdout } = await execFile("rg", rgArgs, {
+        cwd: projectPath
       });
-      rgCommand += ` -m ${maxResults}`;
-      rgCommand += ` "${query}" ${paths.join(" ")}`;
-      const { stdout } = await exec(rgCommand);
       const lines = stdout.split("\n").filter((line) => line.trim());
       const matches = [];
       let currentMatch = null;
@@ -2144,14 +2615,29 @@ export const tools = await mcpClient.getTools();
         includeMetadata = true,
         projectPath
       } = context;
+      const gitignorePath = join(projectPath || process.cwd(), ".gitignore");
+      let gitignoreFilter;
+      try {
+        const gitignoreContent = await readFile(gitignorePath, "utf-8");
+        gitignoreFilter = ignore().add(gitignoreContent);
+      } catch (err) {
+        if (err.code !== "ENOENT") {
+          console.error(`Error reading .gitignore file:`, err);
+        }
+      }
       const resolvedPath = isAbsolute(path) ? path : resolve(projectPath || process.cwd(), path);
       const items = [];
       async function processDirectory(dirPath, currentDepth = 0) {
+        const relativeToProject = relative(projectPath || process.cwd(), dirPath);
+        if (gitignoreFilter?.ignores(relativeToProject)) return;
         if (currentDepth > maxDepth) return;
         const entries = await readdir(dirPath);
         for (const entry of entries) {
+          const entryPath = join(dirPath, entry);
+          const relativeEntryPath = relative(projectPath || process.cwd(), entryPath);
+          if (gitignoreFilter?.ignores(relativeEntryPath)) continue;
           if (!includeHidden && entry.startsWith(".")) continue;
-          const fullPath = join(dirPath, entry);
+          const fullPath = entryPath;
           const relativePath = relative(resolvedPath, fullPath);
           if (pattern) {
             const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
@@ -2385,12 +2871,19 @@ var ToolSummaryProcessor = class extends MemoryProcessor {
       }
     }
     if (summaryTasks.length > 0) {
-      const summaryResults = await Promise.all(summaryTasks.map((task) => task.promise));
+      const summaryResults = await Promise.allSettled(summaryTasks.map((task) => task.promise));
       summaryTasks.forEach((task, index) => {
-        const summaryResult = summaryResults[index];
-        const summaryText = summaryResult.text;
-        this.summaryCache.set(task.cacheKey, summaryText);
-        task.content.result = `Tool call summary: ${summaryText}`;
+        const result = summaryResults[index];
+        if (!result) return;
+        if (result.status === "fulfilled") {
+          const summaryResult = result.value;
+          const summaryText = summaryResult.text;
+          this.summaryCache.set(task.cacheKey, summaryText);
+          task.content.result = `Tool call summary: ${summaryText}`;
+        } else if (result.status === "rejected") {
+          console.warn(`Failed to generate summary for tool call:`, result.reason);
+          task.content.result = `Tool call summary: [Summary generation failed]`;
+        }
       });
     }
     return messages;
@@ -2403,19 +2896,30 @@ var WriteToDiskProcessor = class extends MemoryProcessor {
     this.prefix = prefix;
   }
   async process(messages) {
-    await writeFile(`${this.prefix}-${Date.now()}.json`, JSON.stringify(messages, null, 2));
+    await writeFile(`${this.prefix}-${Date.now()}-${process.pid}.json`, JSON.stringify(messages, null, 2));
     return messages;
   }
 };
+var resolveModel = (runtimeContext) => {
+  const modelFromContext = runtimeContext.get("model");
+  if (modelFromContext) {
+    if (isValidMastraLanguageModel(modelFromContext)) {
+      return modelFromContext;
+    }
+    throw new Error(
+      'Invalid model provided. Model must be a MastraLanguageModel instance (e.g., openai("gpt-4"), anthropic("claude-3-5-sonnet"), etc.)'
+    );
+  }
+  return openai("gpt-4.1");
+};
+var isValidMastraLanguageModel = (model) => {
+  return model && typeof model === "object" && typeof model.modelId === "string" && typeof model.generate === "function";
+};
 var cloneTemplateStep = createStep({
   id: "clone-template",
   description: "Clone the template repository to a temporary directory at the specified ref",
-  inputSchema: MergeInputSchema,
-  outputSchema: z.object({
-    templateDir: z.string(),
-    commitSha: z.string(),
-    slug: z.string()
-  }),
+  inputSchema: AgentBuilderInputSchema,
+  outputSchema: CloneTemplateResultSchema,
   execute: async ({ inputData }) => {
     const { repo, ref = "main", slug } = inputData;
     if (!repo) {
@@ -2424,45 +2928,37 @@ var cloneTemplateStep = createStep({
     const inferredSlug = slug || repo.split("/").pop()?.replace(/\.git$/, "") || "template";
     const tempDir = await mkdtemp(join(tmpdir(), "mastra-template-"));
     try {
-      const cloneCmd = `git clone "${repo}" "${tempDir}"`;
-      await exec(cloneCmd);
+      await gitClone(repo, tempDir);
       if (ref !== "main" && ref !== "master") {
-        await exec(`git checkout "${ref}"`, { cwd: tempDir });
+        await gitCheckoutRef(tempDir, ref);
       }
-      const { stdout: commitSha } = await exec("git rev-parse HEAD", { cwd: tempDir });
+      const commitSha = await gitRevParse(tempDir, "HEAD");
       return {
         templateDir: tempDir,
         commitSha: commitSha.trim(),
-        slug: inferredSlug
+        slug: inferredSlug,
+        success: true
       };
     } catch (error) {
       try {
         await rm(tempDir, { recursive: true, force: true });
       } catch {
       }
-      throw new Error(`Failed to clone template: ${error instanceof Error ? error.message : String(error)}`);
+      return {
+        templateDir: "",
+        commitSha: "",
+        slug: slug || "unknown",
+        success: false,
+        error: `Failed to clone template: ${error instanceof Error ? error.message : String(error)}`
+      };
     }
   }
 });
 var analyzePackageStep = createStep({
   id: "analyze-package",
   description: "Analyze the template package.json to extract dependency information",
-  inputSchema: z.object({
-    templateDir: z.string(),
-    commitSha: z.string(),
-    slug: z.string()
-  }),
-  outputSchema: z.object({
-    dependencies: z.record(z.string()).optional(),
-    devDependencies: z.record(z.string()).optional(),
-    peerDependencies: z.record(z.string()).optional(),
-    scripts: z.record(z.string()).optional(),
-    packageInfo: z.object({
-      name: z.string().optional(),
-      version: z.string().optional(),
-      description: z.string().optional()
-    })
-  }),
+  inputSchema: CloneTemplateResultSchema,
+  outputSchema: PackageAnalysisSchema,
   execute: async ({ inputData }) => {
     console.log("Analyzing template package.json...");
     const { templateDir } = inputData;
@@ -2476,11 +2972,10 @@ var analyzePackageStep = createStep({
         devDependencies: packageJson.devDependencies || {},
         peerDependencies: packageJson.peerDependencies || {},
         scripts: packageJson.scripts || {},
-        packageInfo: {
-          name: packageJson.name,
-          version: packageJson.version,
-          description: packageJson.description
-        }
+        name: packageJson.name || "",
+        version: packageJson.version || "",
+        description: packageJson.description || "",
+        success: true
       };
     } catch (error) {
       console.warn(`Failed to read template package.json: ${error instanceof Error ? error.message : String(error)}`);
@@ -2489,7 +2984,11 @@ var analyzePackageStep = createStep({
         devDependencies: {},
         peerDependencies: {},
         scripts: {},
-        packageInfo: {}
+        name: "",
+        version: "",
+        description: "",
+        success: true
+        // This is a graceful fallback, not a failure
       };
     }
   }
@@ -2497,20 +2996,15 @@ var analyzePackageStep = createStep({
 var discoverUnitsStep = createStep({
   id: "discover-units",
   description: "Discover template units by analyzing the templates directory structure",
-  inputSchema: z.object({
-    templateDir: z.string(),
-    commitSha: z.string(),
-    slug: z.string()
-  }),
-  outputSchema: z.object({
-    units: z.array(TemplateUnitSchema)
-  }),
-  execute: async ({ inputData }) => {
+  inputSchema: CloneTemplateResultSchema,
+  outputSchema: DiscoveryResultSchema,
+  execute: async ({ inputData, runtimeContext }) => {
     const { templateDir } = inputData;
     const tools = await AgentBuilderDefaults.DEFAULT_TOOLS(templateDir);
-    const agent = new Agent({
-      model: openai("gpt-4o-mini"),
-      instructions: `You are an expert at analyzing Mastra projects.
+    try {
+      const agent = new Agent({
+        model: resolveModel(runtimeContext),
+        instructions: `You are an expert at analyzing Mastra projects.
 
 Your task is to scan the provided directory and identify all available units (agents, workflows, tools, MCP servers, networks).
 
@@ -2541,14 +3035,14 @@ IMPORTANT - Naming Consistency Rules:
 - use the relative path from the template root for the file (e.g., 'src/mastra/lib/util.ts' \u2192 file: 'src/mastra/lib/util.ts')
 
 Return the actual exported names of the units, as well as the file names.`,
-      name: "Mastra Project Discoverer",
-      tools: {
-        readFile: tools.readFile,
-        listDirectory: tools.listDirectory
-      }
-    });
-    const result = await agent.generate(
-      `Analyze the Mastra project directory structure at "${templateDir}".
+        name: "Mastra Project Discoverer",
+        tools: {
+          readFile: tools.readFile,
+          listDirectory: tools.listDirectory
+        }
+      });
+      const result = await agent.generate(
+        `Analyze the Mastra project directory structure at "${templateDir}".
 
             List directory contents using listDirectory tool, and then analyze each file with readFile tool.
       IMPORTANT:
@@ -2558,51 +3052,70 @@ Return the actual exported names of the units, as well as the file names.`,
       - If a directory doesn't exist or has no files, return an empty array
 
       Return the analysis in the exact format specified in the output schema.`,
-      {
-        experimental_output: z.object({
-          agents: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
-          workflows: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
-          tools: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
-          mcp: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
-          networks: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
-          other: z.array(z.object({ name: z.string(), file: z.string() })).optional()
-        }),
-        maxSteps: 100
+        {
+          experimental_output: z.object({
+            agents: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
+            workflows: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
+            tools: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
+            mcp: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
+            networks: z.array(z.object({ name: z.string(), file: z.string() })).optional(),
+            other: z.array(z.object({ name: z.string(), file: z.string() })).optional()
+          }),
+          maxSteps: 100
+        }
+      );
+      const template = result.object ?? {};
+      const units = [];
+      template.agents?.forEach((agentId) => {
+        units.push({ kind: "agent", id: agentId.name, file: agentId.file });
+      });
+      template.workflows?.forEach((workflowId) => {
+        units.push({ kind: "workflow", id: workflowId.name, file: workflowId.file });
+      });
+      template.tools?.forEach((toolId) => {
+        units.push({ kind: "tool", id: toolId.name, file: toolId.file });
+      });
+      template.mcp?.forEach((mcpId) => {
+        units.push({ kind: "mcp-server", id: mcpId.name, file: mcpId.file });
+      });
+      template.networks?.forEach((networkId) => {
+        units.push({ kind: "network", id: networkId.name, file: networkId.file });
+      });
+      template.other?.forEach((otherId) => {
+        units.push({ kind: "other", id: otherId.name, file: otherId.file });
+      });
+      console.log("Discovered units:", JSON.stringify(units, null, 2));
+      if (units.length === 0) {
+        throw new Error(`No Mastra units (agents, workflows, tools) found in template.
+          Possible causes:
+          - Template may not follow standard Mastra structure
+          - AI agent couldn't analyze template files (model/token limits)
+          - Template is empty or in wrong branch
+
+          Debug steps:
+          - Check template has files in src/mastra/ directories
+          - Try a different branch
+          - Check template repository structure manually`);
       }
-    );
-    const template = result.object ?? {};
-    const units = [];
-    template.agents?.forEach((agentId) => {
-      units.push({ kind: "agent", id: agentId.name, file: agentId.file });
-    });
-    template.workflows?.forEach((workflowId) => {
-      units.push({ kind: "workflow", id: workflowId.name, file: workflowId.file });
-    });
-    template.tools?.forEach((toolId) => {
-      units.push({ kind: "tool", id: toolId.name, file: toolId.file });
-    });
-    template.mcp?.forEach((mcpId) => {
-      units.push({ kind: "mcp-server", id: mcpId.name, file: mcpId.file });
-    });
-    template.networks?.forEach((networkId) => {
-      units.push({ kind: "network", id: networkId.name, file: networkId.file });
-    });
-    template.other?.forEach((otherId) => {
-      units.push({ kind: "other", id: otherId.name, file: otherId.file });
-    });
-    console.log("Discovered units:", JSON.stringify(units, null, 2));
-    return { units };
+      return {
+        units,
+        success: true
+      };
+    } catch (error) {
+      console.error("Failed to discover units:", error);
+      return {
+        units: [],
+        success: false,
+        error: `Failed to discover units: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
   }
 });
 var orderUnitsStep = createStep({
   id: "order-units",
   description: "Sort units in topological order based on kind weights",
-  inputSchema: z.object({
-    units: z.array(TemplateUnitSchema)
-  }),
-  outputSchema: z.object({
-    orderedUnits: z.array(TemplateUnitSchema)
-  }),
+  inputSchema: DiscoveryResultSchema,
+  outputSchema: OrderedUnitsSchema,
   execute: async ({ inputData }) => {
     const { units } = inputData;
     const orderedUnits = [...units].sort((a, b) => {
@@ -2610,103 +3123,102 @@ var orderUnitsStep = createStep({
       const bWeight = kindWeight(b.kind);
       return aWeight - bWeight;
     });
-    return { orderedUnits };
+    return {
+      orderedUnits,
+      success: true
+    };
+  }
+});
+var prepareBranchStep = createStep({
+  id: "prepare-branch",
+  description: "Create or switch to integration branch before modifications",
+  inputSchema: PrepareBranchInputSchema,
+  outputSchema: PrepareBranchResultSchema,
+  execute: async ({ inputData, runtimeContext }) => {
+    const targetPath = inputData.targetPath || runtimeContext.get("targetPath") || process.cwd();
+    try {
+      const branchName = `feat/install-template-${inputData.slug}`;
+      await gitCheckoutBranch(branchName, targetPath);
+      return {
+        branchName,
+        success: true
+      };
+    } catch (error) {
+      console.error("Failed to prepare branch:", error);
+      return {
+        branchName: `feat/install-template-${inputData.slug}`,
+        // Return the intended name anyway
+        success: false,
+        error: `Failed to prepare branch: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
   }
 });
 var packageMergeStep = createStep({
   id: "package-merge",
-  description: "Merge template package.json dependencies into target project and install",
-  inputSchema: z.object({
-    commitSha: z.string(),
-    slug: z.string(),
-    targetPath: z.string().optional(),
-    packageInfo: z.object({
-      dependencies: z.record(z.string()).optional(),
-      devDependencies: z.record(z.string()).optional(),
-      peerDependencies: z.record(z.string()).optional(),
-      scripts: z.record(z.string()).optional(),
-      packageInfo: z.object({
-        name: z.string().optional(),
-        version: z.string().optional(),
-        description: z.string().optional()
-      })
-    })
-  }),
-  outputSchema: z.object({
-    success: z.boolean(),
-    applied: z.boolean(),
-    message: z.string(),
-    error: z.string().optional()
-  }),
+  description: "Merge template package.json dependencies into target project",
+  inputSchema: PackageMergeInputSchema,
+  outputSchema: PackageMergeResultSchema,
   execute: async ({ inputData, runtimeContext }) => {
     console.log("Package merge step starting...");
     const { slug, packageInfo } = inputData;
     const targetPath = inputData.targetPath || runtimeContext.get("targetPath") || process.cwd();
     try {
-      const allTools = await AgentBuilderDefaults.DEFAULT_TOOLS(targetPath);
-      const packageMergeAgent = new Agent({
-        name: "package-merger",
-        description: "Specialized agent for merging package.json dependencies",
-        instructions: `You are a package.json merge specialist. Your job is to:
-
-1. **Read the target project's package.json** using readFile tool
-2. **Merge template dependencies** into the target package.json following these rules:
-   - For dependencies: Add ALL NEW ones with template versions, KEEP EXISTING versions for conflicts
-   - For devDependencies: Add ALL NEW ones with template versions, KEEP EXISTING versions for conflicts  
-   - For peerDependencies: Add ALL NEW ones with template versions, KEEP EXISTING versions for conflicts
-   - For scripts: Add new scripts with "template:${slug}:" prefix, don't overwrite existing ones
-   - Maintain existing package.json structure and formatting
-3. **Write the updated package.json** using writeFile tool
-
-Template Dependencies to Merge:
-- Dependencies: ${JSON.stringify(packageInfo.dependencies || {}, null, 2)}
-- Dev Dependencies: ${JSON.stringify(packageInfo.devDependencies || {}, null, 2)}
-- Peer Dependencies: ${JSON.stringify(packageInfo.peerDependencies || {}, null, 2)}
-- Scripts: ${JSON.stringify(packageInfo.scripts || {}, null, 2)}
-
-CRITICAL MERGE RULES:
-1. For each dependency in template dependencies, if it does NOT exist in target, ADD it with template version
-2. For each dependency in template dependencies, if it ALREADY exists in target, KEEP target version
-3. You MUST add ALL template dependencies that don't conflict - do not skip any
-4. Be explicit about what you're adding vs keeping
-
-EXAMPLE:
-Template has: {"@mastra/libsql": "latest", "@mastra/core": "latest", "zod": "^3.25.67"}
-Target has: {"@mastra/core": "latest", "zod": "^3.25.0"}
-Result should have: {"@mastra/core": "latest", "zod": "^3.25.0", "@mastra/libsql": "latest"}
-
-Be systematic and thorough. Always read the existing package.json first, then merge, then write.`,
-        model: openai("gpt-4o-mini"),
-        tools: {
-          readFile: allTools.readFile,
-          writeFile: allTools.writeFile,
-          listDirectory: allTools.listDirectory
+      const targetPkgPath = join(targetPath, "package.json");
+      let targetPkgRaw = "{}";
+      try {
+        targetPkgRaw = await readFile(targetPkgPath, "utf-8");
+      } catch {
+        console.warn(`No existing package.json at ${targetPkgPath}, creating a new one`);
+      }
+      let targetPkg;
+      try {
+        targetPkg = JSON.parse(targetPkgRaw || "{}");
+      } catch (e) {
+        throw new Error(
+          `Failed to parse existing package.json at ${targetPkgPath}: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+      const ensureObj = (o) => o && typeof o === "object" ? o : {};
+      targetPkg.dependencies = ensureObj(targetPkg.dependencies);
+      targetPkg.devDependencies = ensureObj(targetPkg.devDependencies);
+      targetPkg.peerDependencies = ensureObj(targetPkg.peerDependencies);
+      targetPkg.scripts = ensureObj(targetPkg.scripts);
+      const tplDeps = ensureObj(packageInfo.dependencies);
+      const tplDevDeps = ensureObj(packageInfo.devDependencies);
+      const tplPeerDeps = ensureObj(packageInfo.peerDependencies);
+      const tplScripts = ensureObj(packageInfo.scripts);
+      const existsAnywhere = (name) => name in targetPkg.dependencies || name in targetPkg.devDependencies || name in targetPkg.peerDependencies;
+      for (const [name, ver] of Object.entries(tplDeps)) {
+        if (!existsAnywhere(name)) {
+          targetPkg.dependencies[name] = String(ver);
         }
-      });
-      console.log("Starting package merge agent...");
-      console.log("Template dependencies to merge:", JSON.stringify(packageInfo.dependencies, null, 2));
-      console.log("Template devDependencies to merge:", JSON.stringify(packageInfo.devDependencies, null, 2));
-      const result = await packageMergeAgent.stream(
-        `Please merge the template dependencies into the target project's package.json at ${targetPath}/package.json.`,
-        { experimental_output: z.object({ success: z.boolean() }) }
-      );
-      let buffer = [];
-      for await (const chunk of result.fullStream) {
-        if (chunk.type === "text-delta") {
-          buffer.push(chunk.textDelta);
-          if (buffer.length > 20) {
-            console.log(buffer.join(""));
-            buffer = [];
-          }
+      }
+      for (const [name, ver] of Object.entries(tplDevDeps)) {
+        if (!existsAnywhere(name)) {
+          targetPkg.devDependencies[name] = String(ver);
         }
       }
-      if (buffer.length > 0) {
-        console.log(buffer.join(""));
+      for (const [name, ver] of Object.entries(tplPeerDeps)) {
+        if (!(name in targetPkg.peerDependencies)) {
+          targetPkg.peerDependencies[name] = String(ver);
+        }
+      }
+      const prefix = `template:${slug}:`;
+      for (const [name, cmd] of Object.entries(tplScripts)) {
+        const newKey = `${prefix}${name}`;
+        if (!(newKey in targetPkg.scripts)) {
+          targetPkg.scripts[newKey] = String(cmd);
+        }
       }
+      await writeFile(targetPkgPath, JSON.stringify(targetPkg, null, 2), "utf-8");
+      await gitAddAndCommit(targetPath, `feat(template): merge deps for ${slug}`, [targetPkgPath], {
+        skipIfNoStaged: true
+      });
       return {
         success: true,
         applied: true,
-        message: `Successfully merged template dependencies and installed packages for ${slug}`
+        message: `Successfully merged template dependencies for ${slug}`
       };
     } catch (error) {
       console.error("Package merge failed:", error);
@@ -2719,32 +3231,30 @@ Be systematic and thorough. Always read the existing package.json first, then me
     }
   }
 });
-var flatInstallStep = createStep({
-  id: "flat-install",
-  description: "Run a flat install command without specifying packages",
-  inputSchema: z.object({
-    targetPath: z.string().describe("Path to the project to install packages in")
-  }),
-  outputSchema: z.object({
-    success: z.boolean(),
-    message: z.string(),
-    details: z.string().optional()
-  }),
+var installStep = createStep({
+  id: "install",
+  description: "Install packages based on merged package.json",
+  inputSchema: InstallInputSchema,
+  outputSchema: InstallResultSchema,
   execute: async ({ inputData, runtimeContext }) => {
-    console.log("Running flat install...");
+    console.log("Running install step...");
     const targetPath = inputData.targetPath || runtimeContext.get("targetPath") || process.cwd();
     try {
       await spawnSWPM(targetPath, "install", []);
+      const lock = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock"].map((f) => join(targetPath, f)).find((f) => existsSync(f));
+      if (lock) {
+        await gitAddAndCommit(targetPath, `chore(template): commit lockfile after install`, [lock], {
+          skipIfNoStaged: true
+        });
+      }
       return {
-        success: true,
-        message: "Successfully ran flat install command",
-        details: "Installed all dependencies from package.json"
+        success: true
       };
     } catch (error) {
-      console.error("Flat install failed:", error);
+      console.error("Install failed:", error);
       return {
         success: false,
-        message: `Flat install failed: ${error instanceof Error ? error.message : String(error)}`
+        error: error instanceof Error ? error.message : String(error)
       };
     }
   }
@@ -2752,45 +3262,8 @@ var flatInstallStep = createStep({
 var programmaticFileCopyStep = createStep({
   id: "programmatic-file-copy",
   description: "Programmatically copy template files to target project based on ordered units",
-  inputSchema: z.object({
-    orderedUnits: z.array(
-      z.object({
-        kind: z.string(),
-        id: z.string(),
-        file: z.string()
-      })
-    ),
-    templateDir: z.string(),
-    commitSha: z.string(),
-    slug: z.string(),
-    targetPath: z.string().optional()
-  }),
-  outputSchema: z.object({
-    success: z.boolean(),
-    copiedFiles: z.array(
-      z.object({
-        source: z.string(),
-        destination: z.string(),
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        })
-      })
-    ),
-    conflicts: z.array(
-      z.object({
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        }),
-        issue: z.string(),
-        sourceFile: z.string(),
-        targetFile: z.string()
-      })
-    ),
-    message: z.string(),
-    error: z.string().optional()
-  }),
+  inputSchema: FileCopyInputSchema,
+  outputSchema: FileCopyResultSchema,
   execute: async ({ inputData, runtimeContext }) => {
     console.log("Programmatic file copy step starting...");
     const { orderedUnits, templateDir, commitSha, slug } = inputData;
@@ -2953,14 +3426,83 @@ var programmaticFileCopyStep = createStep({
           });
         }
       }
+      try {
+        const targetTsconfig = resolve(targetPath, "tsconfig.json");
+        if (!existsSync(targetTsconfig)) {
+          const templateTsconfig = resolve(templateDir, "tsconfig.json");
+          if (existsSync(templateTsconfig)) {
+            await copyFile(templateTsconfig, targetTsconfig);
+            copiedFiles.push({
+              source: templateTsconfig,
+              destination: targetTsconfig,
+              unit: { kind: "other", id: "tsconfig.json" }
+            });
+            console.log("\u2713 Copied tsconfig.json from template to target");
+          } else {
+            const minimalTsconfig = {
+              compilerOptions: {
+                target: "ES2020",
+                module: "NodeNext",
+                moduleResolution: "NodeNext",
+                strict: false,
+                esModuleInterop: true,
+                skipLibCheck: true,
+                resolveJsonModule: true,
+                outDir: "dist"
+              },
+              include: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+              exclude: ["node_modules", "dist", "build", ".next", ".output", ".turbo"]
+            };
+            await writeFile(targetTsconfig, JSON.stringify(minimalTsconfig, null, 2), "utf-8");
+            copiedFiles.push({
+              source: "[generated tsconfig.json]",
+              destination: targetTsconfig,
+              unit: { kind: "other", id: "tsconfig.json" }
+            });
+            console.log("\u2713 Generated minimal tsconfig.json in target");
+          }
+        }
+      } catch (e) {
+        conflicts.push({
+          unit: { kind: "other", id: "tsconfig.json" },
+          issue: `Failed to ensure tsconfig.json: ${e instanceof Error ? e.message : String(e)}`,
+          sourceFile: "tsconfig.json",
+          targetFile: "tsconfig.json"
+        });
+      }
+      try {
+        const targetMastraIndex = resolve(targetPath, "src/mastra/index.ts");
+        if (!existsSync(targetMastraIndex)) {
+          const templateMastraIndex = resolve(templateDir, "src/mastra/index.ts");
+          if (existsSync(templateMastraIndex)) {
+            if (!existsSync(dirname(targetMastraIndex))) {
+              await mkdir(dirname(targetMastraIndex), { recursive: true });
+            }
+            await copyFile(templateMastraIndex, targetMastraIndex);
+            copiedFiles.push({
+              source: templateMastraIndex,
+              destination: targetMastraIndex,
+              unit: { kind: "other", id: "mastra-index" }
+            });
+            console.log("\u2713 Copied src/mastra/index.ts from template to target");
+          }
+        }
+      } catch (e) {
+        conflicts.push({
+          unit: { kind: "other", id: "mastra-index" },
+          issue: `Failed to ensure Mastra index file: ${e instanceof Error ? e.message : String(e)}`,
+          sourceFile: "src/mastra/index.ts",
+          targetFile: "src/mastra/index.ts"
+        });
+      }
       if (copiedFiles.length > 0) {
         try {
           const fileList = copiedFiles.map((f) => f.destination);
-          const gitCommand = ["git", "add", ...fileList];
-          await exec(gitCommand.join(" "), { cwd: targetPath });
-          await exec(
-            `git commit -m "feat(template): copy ${copiedFiles.length} files from ${slug}@${commitSha.substring(0, 7)}"`,
-            { cwd: targetPath }
+          await gitAddAndCommit(
+            targetPath,
+            `feat(template): copy ${copiedFiles.length} files from ${slug}@${commitSha.substring(0, 7)}`,
+            fileList,
+            { skipIfNoStaged: true }
           );
           console.log(`\u2713 Committed ${copiedFiles.length} copied files`);
         } catch (commitError) {
@@ -2977,83 +3519,26 @@ var programmaticFileCopyStep = createStep({
       };
     } catch (error) {
       console.error("Programmatic file copy failed:", error);
-      throw new Error(`Programmatic file copy failed: ${error instanceof Error ? error.message : String(error)}`);
+      return {
+        success: false,
+        copiedFiles: [],
+        conflicts: [],
+        message: `Programmatic file copy failed: ${error instanceof Error ? error.message : String(error)}`,
+        error: error instanceof Error ? error.message : String(error)
+      };
     }
   }
 });
 var intelligentMergeStep = createStep({
   id: "intelligent-merge",
   description: "Use AgentBuilder to intelligently merge template files",
-  inputSchema: z.object({
-    conflicts: z.array(
-      z.object({
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        }),
-        issue: z.string(),
-        sourceFile: z.string(),
-        targetFile: z.string()
-      })
-    ),
-    copiedFiles: z.array(
-      z.object({
-        source: z.string(),
-        destination: z.string(),
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        })
-      })
-    ),
-    templateDir: z.string(),
-    commitSha: z.string(),
-    slug: z.string(),
-    targetPath: z.string().optional()
-  }),
-  outputSchema: z.object({
-    success: z.boolean(),
-    applied: z.boolean(),
-    message: z.string(),
-    conflictsResolved: z.array(
-      z.object({
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        }),
-        issue: z.string(),
-        resolution: z.string()
-      })
-    ),
-    error: z.string().optional(),
-    branchName: z.string().optional()
-  }),
+  inputSchema: IntelligentMergeInputSchema,
+  outputSchema: IntelligentMergeResultSchema,
   execute: async ({ inputData, runtimeContext }) => {
     console.log("Intelligent merge step starting...");
-    const { conflicts, copiedFiles, commitSha, slug, templateDir } = inputData;
+    const { conflicts, copiedFiles, commitSha, slug, templateDir, branchName } = inputData;
     const targetPath = inputData.targetPath || runtimeContext.get("targetPath") || process.cwd();
-    const baseBranchName = `feat/install-template-${slug}`;
     try {
-      let branchName = baseBranchName;
-      try {
-        await exec(`git checkout -b "${branchName}"`, { cwd: targetPath });
-        console.log(`Created new branch: ${branchName}`);
-      } catch (error) {
-        const errorStr = error instanceof Error ? error.message : String(error);
-        if (errorStr.includes("already exists")) {
-          try {
-            await exec(`git checkout "${branchName}"`, { cwd: targetPath });
-            console.log(`Switched to existing branch: ${branchName}`);
-          } catch {
-            const timestamp = Date.now().toString().slice(-6);
-            branchName = `${baseBranchName}-${timestamp}`;
-            await exec(`git checkout -b "${branchName}"`, { cwd: targetPath });
-            console.log(`Created unique branch: ${branchName}`);
-          }
-        } else {
-          throw error;
-        }
-      }
       const copyFileTool = createTool({
         id: "copy-file",
         description: "Copy a file from template to target project (use only for edge cases - most files are already copied programmatically).",
@@ -3091,7 +3576,7 @@ var intelligentMergeStep = createStep({
       const agentBuilder = new AgentBuilder({
         projectPath: targetPath,
         mode: "template",
-        model: openai("gpt-4o-mini"),
+        model: resolveModel(runtimeContext),
         instructions: `
 You are an expert at integrating Mastra template components into existing projects.
 
@@ -3106,49 +3591,52 @@ CONFLICTS TO RESOLVE:
 ${JSON.stringify(conflicts, null, 2)}
 
 CRITICAL INSTRUCTIONS:
-1. **When committing changes**: NEVER add dependency/build directories. Use specific file paths with 'git add'
-2. **Package management**: NO need to install packages (already handled by package merge step)
-3. **Validation**: When validation fails due to import issues, check existing files and imports for correct naming conventions
-4. **Variable vs file names**: A variable name might differ from file name (e.g., filename: ./downloaderTool.ts, export const fetcherTool(...))
-5. **File copying**: Most files are already copied programmatically. Only use copyFile tool for edge cases where additional files are needed
+1. **Package management**: NO need to install packages (already handled by package merge step)
+2. **File copying**: Most files are already copied programmatically. Only use copyFile tool for edge cases where additional files are needed for conflict resolution
 
 KEY RESPONSIBILITIES:
 1. Resolve any conflicts from the programmatic copy step
 2. Register components in existing Mastra index file (agents, workflows, networks, mcp-servers)
 3. DO NOT register tools in existing Mastra index file - tools should remain standalone
-4. Fix import path issues in copied files
-5. Ensure TypeScript imports and exports are correct
-6. Validate integration works properly
-7. Copy additional files ONLY if needed for conflict resolution or missing dependencies
+4. Copy additional files ONLY if needed for conflict resolution
 
-MASTRA-SPECIFIC INTEGRATION:
+MASTRA INDEX FILE HANDLING (src/mastra/index.ts):
+1. **Verify the file exists**
+   - Call readFile
+   - If it fails with ENOENT (or listDirectory shows it missing) -> copyFile the template version to src/mastra/index.ts, then confirm it now exists
+   - Always verify after copying that the file exists and is accessible
+
+2. **Edit the file**
+   - Always work with the full file content
+   - Generate the complete, correct source (imports, anchors, registrations, formatting)
+   - Keep existing registrations intact and maintain file structure
+   - Ensure proper spacing and organization of new additions
+
+3. **Handle anchors and structure**
+   - When generating new content, ensure you do not duplicate existing imports or object entries
+   - If required anchors (e.g., agents: {}) are missing, add them while generating the new content
+   - Add missing anchors just before the closing brace of the Mastra config
+   - Do not restructure or reorder existing anchors and registrations
+
+CRITICAL: ALWAYS use writeFile to update the mastra/index.ts file when needed to register new components.
+
+MASTRA-SPECIFIC REGISTRATION:
 - Agents: Register in existing Mastra index file
 - Workflows: Register in existing Mastra index file
 - Networks: Register in existing Mastra index file
 - MCP servers: Register in existing Mastra index file
 - Tools: Copy to ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.tool} but DO NOT register in existing Mastra index file
-
-EDGE CASE FILE COPYING:
-- IF a file for a resource does not exist in the target project AND was not programmatically copied, you can use copyFile tool
-- When taking files from template, ensure you get the right file name and path
-- Only copy files that are actually needed for the integration to work
-
-NAMING CONVENTION GUIDANCE:
-When fixing imports or understanding naming patterns, use these examples:
-
-**Import Path Patterns:**
-- camelCase files: import { myAgent } from './myAgent'
-- snake_case files: import { myAgent } from './my_agent'
-- kebab-case files: import { myAgent } from './my-agent'
-- PascalCase files: import { MyAgent } from './MyAgent'
-
-**Naming Detection Examples:**
-- Files like "weatherAgent.ts", "chatAgent.ts" \u2192 use camelCase
-- Files like "weather_agent.ts", "chat_agent.ts" \u2192 use snake_case  
-- Files like "weather-agent.ts", "chat-agent.ts" \u2192 use kebab-case
-- Files like "WeatherAgent.ts", "ChatAgent.ts" \u2192 use PascalCase
-
-**Key Rule:** Keep variable/export names unchanged - only adapt file names and import paths
+- If an anchor (e.g., "agents: {") is not found, avoid complex restructuring; instead, insert the missing anchor on a new line (e.g., add "agents: {" just before the closing brace of the Mastra config) and then proceed with the other registrations.
+
+CONFLICT RESOLUTION AND FILE COPYING:
+- Only copy files if needed to resolve specific conflicts
+- When copying files from template:
+  - Ensure you get the right file name and path
+  - Verify the destination directory exists
+  - Maintain the same relative path structure
+  - Only copy files that are actually needed
+- Preserve existing functionality when resolving conflicts
+- Focus on registration and conflict resolution, validation will happen in a later step
 
 Template information:
 - Slug: ${slug}
@@ -3169,15 +3657,23 @@ Template information:
           notes: `Unit: ${conflict.unit.kind}:${conflict.unit.id}, Issue: ${conflict.issue}, Source: ${conflict.sourceFile}, Target: ${conflict.targetFile}`
         });
       });
-      const nonToolFiles = copiedFiles.filter((f) => f.unit.kind !== "tool");
-      if (nonToolFiles.length > 0) {
+      const registrableKinds = /* @__PURE__ */ new Set(["agent", "workflow", "network", "mcp-server"]);
+      const registrableFiles = copiedFiles.filter((f) => registrableKinds.has(f.unit.kind));
+      const targetMastraIndex = resolve(targetPath, "src/mastra/index.ts");
+      const mastraIndexExists = existsSync(targetMastraIndex);
+      console.log(`Mastra index exists: ${mastraIndexExists} at ${targetMastraIndex}`);
+      console.log(
+        "Registrable components:",
+        registrableFiles.map((f) => `${f.unit.kind}:${f.unit.id}`)
+      );
+      if (registrableFiles.length > 0) {
         tasks.push({
           id: "register-components",
-          content: `Register ${nonToolFiles.length} components in existing Mastra index file (src/mastra/index.ts)`,
+          content: `Register ${registrableFiles.length} components in existing Mastra index file (src/mastra/index.ts)`,
           status: "pending",
           priority: "medium",
           dependencies: conflicts.length > 0 ? conflicts.map((c) => `conflict-${c.unit.kind}-${c.unit.id}`) : void 0,
-          notes: `Components to register: ${nonToolFiles.map((f) => `${f.unit.kind}:${f.unit.id}`).join(", ")}`
+          notes: `Components to register: ${registrableFiles.map((f) => `${f.unit.kind}:${f.unit.id}`).join(", ")}`
         });
       }
       console.log(`Creating task list with ${tasks.length} tasks...`);
@@ -3274,10 +3770,12 @@ Start by listing your tasks and work through them systematically!
           };
         }
       });
+      await gitAddAndCommit(targetPath, `feat(template): apply intelligent merge for ${slug}`, void 0, {
+        skipIfNoStaged: true
+      });
       return {
         success: true,
         applied: true,
-        branchName,
         message: `Successfully resolved ${conflicts.length} conflicts from template ${slug}`,
         conflictsResolved: conflictResolutions
       };
@@ -3285,7 +3783,6 @@ Start by listing your tasks and work through them systematically!
       return {
         success: false,
         applied: false,
-        branchName: baseBranchName,
         message: `Failed to resolve conflicts: ${error instanceof Error ? error.message : String(error)}`,
         conflictsResolved: [],
         error: error instanceof Error ? error.message : String(error)
@@ -3295,52 +3792,9 @@ Start by listing your tasks and work through them systematically!
 });
 var validationAndFixStep = createStep({
   id: "validation-and-fix",
-  description: "Validate the merged template code and fix any validation errors using a specialized agent",
-  inputSchema: z.object({
-    commitSha: z.string(),
-    slug: z.string(),
-    targetPath: z.string().optional(),
-    templateDir: z.string(),
-    orderedUnits: z.array(
-      z.object({
-        kind: z.string(),
-        id: z.string(),
-        file: z.string()
-      })
-    ),
-    copiedFiles: z.array(
-      z.object({
-        source: z.string(),
-        destination: z.string(),
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        })
-      })
-    ),
-    conflictsResolved: z.array(
-      z.object({
-        unit: z.object({
-          kind: z.string(),
-          id: z.string()
-        }),
-        issue: z.string(),
-        resolution: z.string()
-      })
-    ).optional(),
-    maxIterations: z.number().optional().default(5)
-  }),
-  outputSchema: z.object({
-    success: z.boolean(),
-    applied: z.boolean(),
-    message: z.string(),
-    validationResults: z.object({
-      valid: z.boolean(),
-      errorsFixed: z.number(),
-      remainingErrors: z.number()
-    }),
-    error: z.string().optional()
-  }),
+  description: "Validate the merged template code and fix any issues using a specialized agent",
+  inputSchema: ValidationFixInputSchema,
+  outputSchema: ValidationFixResultSchema,
   execute: async ({ inputData, runtimeContext }) => {
     console.log("Validation and fix step starting...");
     const { commitSha, slug, orderedUnits, templateDir, copiedFiles, conflictsResolved, maxIterations = 5 } = inputData;
@@ -3375,26 +3829,84 @@ var validationAndFixStep = createStep({
    - ESLint issues
    - Import/export problems
    - Missing dependencies
+   - Index file structure and exports
+   - Component registration correctness
+   - Naming convention compliance
 
 2. **Fix validation errors systematically**:
    - Use readFile to examine files with errors
-   - Use multiEdit to fix issues like missing imports, incorrect paths, syntax errors
+   - Use multiEdit for simple search-replace fixes (single line changes)
+   - Use replaceLines for complex multiline fixes (imports, function signatures, etc.)
    - Use listDirectory to understand project structure when fixing import paths
    - Update file contents to resolve TypeScript and linting issues
 
-3. **Re-validate after fixes** to ensure all issues are resolved
-
-4. **Focus on template integration issues**:
-   - Files were copied with new names based on unit IDs
-   - Original template imports may reference old filenames
-   - Missing imports in index files
-   - Incorrect file paths in imports
-   - Type mismatches after integration
-   - Missing exports in barrel files
+3. **Choose the right tool for the job**:
+   - multiEdit: Simple replacements, single line changes, small fixes
+   - replaceLines: Multiline imports, function signatures, complex code blocks
+   - writeFile: ONLY for creating new files (never overwrite existing)
+
+4. **Create missing files ONLY when necessary**:
+   - Use writeFile ONLY for creating NEW files that don't exist
+   - NEVER overwrite existing files - use multiEdit or replaceLines instead
+   - Common cases: missing barrel files (index.ts), missing config files, missing type definitions
+   - Always check with readFile first to ensure file doesn't exist
+
+5. **Fix ALL template integration issues**:
+   - Fix import path issues in copied files
+   - Ensure TypeScript imports and exports are correct
+   - Validate integration works properly
+   - Fix files copied with new names based on unit IDs
+   - Update original template imports that reference old filenames
+   - Fix missing imports in index files
+   - Fix incorrect file paths in imports
+   - Fix type mismatches after integration
+   - Fix missing exports in barrel files
    - Use the COPIED FILES mapping below to fix import paths
+   - Fix any missing dependencies or module resolution issues
+
+6. **Validate index file structure**:
+   - Correct imports for all components
+   - Proper anchor structure (agents: {}, etc.)
+   - No duplicate registrations
+   - Correct export names and paths
+   - Proper formatting and organization
+
+7. **Follow naming conventions**:
+   Import paths:
+   - camelCase: import { myAgent } from './myAgent'
+   - snake_case: import { myAgent } from './my_agent'
+   - kebab-case: import { myAgent } from './my-agent'
+   - PascalCase: import { MyAgent } from './MyAgent'
+
+   File names:
+   - camelCase: weatherAgent.ts, chatAgent.ts
+   - snake_case: weather_agent.ts, chat_agent.ts
+   - kebab-case: weather-agent.ts, chat-agent.ts
+   - PascalCase: WeatherAgent.ts, ChatAgent.ts
+
+   Key Rule: Keep variable/export names unchanged, only adapt file names and import paths
+
+8. **Re-validate after fixes** to ensure all issues are resolved
 
 CRITICAL: Always validate the entire project first to get a complete picture of issues, then fix them systematically, and re-validate to confirm fixes worked.
 
+CRITICAL TOOL SELECTION GUIDE:
+- **multiEdit**: Use for simple string replacements, single-line changes
+  Example: changing './oldPath' to './newPath'
+  
+- **replaceLines**: Use for multiline fixes, complex code structures
+  Example: fixing multiline imports, function signatures, or code blocks
+  Usage: replaceLines({ filePath: 'file.ts', startLine: 5, endLine: 8, newContent: 'new multiline content' })
+  
+- **writeFile**: ONLY for creating new files that don't exist
+  Example: creating missing index.ts barrel files
+
+CRITICAL WRITEFIL\u0415 SAFETY RULES:
+- ONLY use writeFile for creating NEW files that don't exist
+- ALWAYS check with readFile first to verify file doesn't exist
+- NEVER use writeFile to overwrite existing files - use multiEdit or replaceLines instead
+- Common valid uses: missing index.ts barrel files, missing type definitions, missing config files
+
 CRITICAL IMPORT PATH RESOLUTION:
 The following files were copied from template with new names:
 ${JSON.stringify(copiedFiles, null, 2)}
@@ -3415,11 +3927,13 @@ INTEGRATED UNITS:
 ${JSON.stringify(orderedUnits, null, 2)}
 
 Be thorough and methodical. Always use listDirectory to verify actual file existence before fixing imports.`,
-        model: openai("gpt-4o-mini"),
+        model: resolveModel(runtimeContext),
         tools: {
           validateCode: allTools.validateCode,
           readFile: allTools.readFile,
+          writeFile: allTools.writeFile,
           multiEdit: allTools.multiEdit,
+          replaceLines: allTools.replaceLines,
           listDirectory: allTools.listDirectory,
           executeCommand: allTools.executeCommand
         }
@@ -3480,10 +3994,12 @@ Previous iterations may have fixed some issues, so start by re-running validateC
         currentIteration++;
       }
       try {
-        await exec(
-          `git add . && git commit -m "fix(template): resolve validation errors for ${slug}@${commitSha.substring(0, 7)}" || true`,
+        await gitAddAndCommit(
+          targetPath,
+          `fix(template): resolve validation errors for ${slug}@${commitSha.substring(0, 7)}`,
+          void 0,
           {
-            cwd: targetPath
+            skipIfNoStaged: true
           }
         );
       } catch (commitError) {
@@ -3522,10 +4038,10 @@ Previous iterations may have fixed some issues, so start by re-running validateC
     }
   }
 });
-var mergeTemplateWorkflow = createWorkflow({
-  id: "merge-template",
+var agentBuilderTemplateWorkflow = createWorkflow({
+  id: "agent-builder-template",
   description: "Merges a Mastra template repository into the current project using intelligent AgentBuilder-powered merging",
-  inputSchema: MergeInputSchema,
+  inputSchema: AgentBuilderInputSchema,
   outputSchema: ApplyResultSchema,
   steps: [
     cloneTemplateStep,
@@ -3533,15 +4049,36 @@ var mergeTemplateWorkflow = createWorkflow({
     discoverUnitsStep,
     orderUnitsStep,
     packageMergeStep,
-    flatInstallStep,
+    installStep,
     programmaticFileCopyStep,
     intelligentMergeStep,
     validationAndFixStep
   ]
-}).then(cloneTemplateStep).parallel([analyzePackageStep, discoverUnitsStep]).map(async ({ getStepResult }) => {
+}).then(cloneTemplateStep).map(async ({ getStepResult }) => {
+  const cloneResult = getStepResult(cloneTemplateStep);
+  if (shouldAbortWorkflow(cloneResult)) {
+    throw new Error(`Critical failure in clone step: ${cloneResult.error}`);
+  }
+  return cloneResult;
+}).parallel([analyzePackageStep, discoverUnitsStep]).map(async ({ getStepResult }) => {
+  const analyzeResult = getStepResult(analyzePackageStep);
   const discoverResult = getStepResult(discoverUnitsStep);
+  if (shouldAbortWorkflow(analyzeResult)) {
+    throw new Error(`Failure in analyze package step: ${analyzeResult.error || "Package analysis failed"}`);
+  }
+  if (shouldAbortWorkflow(discoverResult)) {
+    throw new Error(`Failure in discover units step: ${discoverResult.error || "Unit discovery failed"}`);
+  }
   return discoverResult;
 }).then(orderUnitsStep).map(async ({ getStepResult, getInitData }) => {
+  const cloneResult = getStepResult(cloneTemplateStep);
+  const initData = getInitData();
+  return {
+    commitSha: cloneResult.commitSha,
+    slug: cloneResult.slug,
+    targetPath: initData.targetPath
+  };
+}).then(prepareBranchStep).map(async ({ getStepResult, getInitData }) => {
   const cloneResult = getStepResult(cloneTemplateStep);
   const packageResult = getStepResult(analyzePackageStep);
   const initData = getInitData();
@@ -3556,10 +4093,14 @@ var mergeTemplateWorkflow = createWorkflow({
   return {
     targetPath: initData.targetPath
   };
-}).then(flatInstallStep).map(async ({ getStepResult, getInitData }) => {
+}).then(installStep).map(async ({ getStepResult, getInitData }) => {
   const cloneResult = getStepResult(cloneTemplateStep);
   const orderResult = getStepResult(orderUnitsStep);
+  const installResult = getStepResult(installStep);
   const initData = getInitData();
+  if (shouldAbortWorkflow(installResult)) {
+    throw new Error(`Failure in install step: ${installResult.error || "Install failed"}`);
+  }
   return {
     orderedUnits: orderResult.orderedUnits,
     templateDir: cloneResult.templateDir,
@@ -3594,15 +4135,31 @@ var mergeTemplateWorkflow = createWorkflow({
     copiedFiles: copyResult.copiedFiles,
     conflictsResolved: mergeResult.conflictsResolved
   };
-}).then(validationAndFixStep).map(async ({ getStepResult, getInitData }) => {
-  const validationResult = getStepResult(validationAndFixStep);
-  const intelligentMergeResult = getStepResult(intelligentMergeStep);
-  const copyResult = getStepResult(programmaticFileCopyStep);
+}).then(validationAndFixStep).map(async ({ getStepResult }) => {
   const cloneResult = getStepResult(cloneTemplateStep);
-  const initData = getInitData();
-  const branchName = intelligentMergeResult.branchName || `feat/install-template-${cloneResult.slug || initData.slug}`;
-  const allErrors = [copyResult.error, intelligentMergeResult.error, validationResult.error].filter(Boolean);
-  const overallSuccess = copyResult.success !== false && intelligentMergeResult.success !== false && validationResult.success;
+  const analyzeResult = getStepResult(analyzePackageStep);
+  const discoverResult = getStepResult(discoverUnitsStep);
+  const orderResult = getStepResult(orderUnitsStep);
+  const prepareBranchResult = getStepResult(prepareBranchStep);
+  const packageMergeResult = getStepResult(packageMergeStep);
+  const installResult = getStepResult(installStep);
+  const copyResult = getStepResult(programmaticFileCopyStep);
+  const intelligentMergeResult = getStepResult(intelligentMergeStep);
+  const validationResult = getStepResult(validationAndFixStep);
+  const branchName = prepareBranchResult.branchName;
+  const allErrors = [
+    cloneResult.error,
+    analyzeResult.error,
+    discoverResult.error,
+    orderResult.error,
+    prepareBranchResult.error,
+    packageMergeResult.error,
+    installResult.error,
+    copyResult.error,
+    intelligentMergeResult.error,
+    validationResult.error
+  ].filter(Boolean);
+  const overallSuccess = cloneResult.success !== false && analyzeResult.success !== false && discoverResult.success !== false && orderResult.success !== false && prepareBranchResult.success !== false && packageMergeResult.success !== false && installResult.success !== false && copyResult.success !== false && intelligentMergeResult.success !== false && validationResult.success !== false;
   const messages = [];
   if (copyResult.copiedFiles?.length > 0) {
     messages.push(`${copyResult.copiedFiles.length} files copied`);
@@ -3627,6 +4184,13 @@ var mergeTemplateWorkflow = createWorkflow({
     branchName,
     // Additional debugging info
     stepResults: {
+      cloneSuccess: cloneResult.success,
+      analyzeSuccess: analyzeResult.success,
+      discoverSuccess: discoverResult.success,
+      orderSuccess: orderResult.success,
+      prepareBranchSuccess: prepareBranchResult.success,
+      packageMergeSuccess: packageMergeResult.success,
+      installSuccess: installResult.success,
       copySuccess: copyResult.success,
       mergeSuccess: intelligentMergeResult.success,
       validationSuccess: validationResult.success,
@@ -3636,15 +4200,29 @@ var mergeTemplateWorkflow = createWorkflow({
     }
   };
 }).commit();
+async function mergeTemplateBySlug(slug, targetPath) {
+  const template = await getMastraTemplate(slug);
+  const run = await agentBuilderTemplateWorkflow.createRunAsync();
+  return await run.start({
+    inputData: {
+      repo: template.githubUrl,
+      slug: template.slug,
+      targetPath
+    }
+  });
+}
 var determineConflictStrategy = (_unit, _targetFile) => {
   return "skip";
 };
+var shouldAbortWorkflow = (stepResult) => {
+  return stepResult?.success === false || stepResult?.error;
+};
 
-// src/index.ts
+// src/agent/index.ts
 var AgentBuilder = class extends Agent {
   builderConfig;
   /**
-   * Private constructor - use AgentBuilder.create() instead
+   * Constructor for AgentBuilder
    */
   constructor(config) {
     const additionalInstructions = config.instructions ? `## Priority Instructions 
@@ -3663,7 +4241,7 @@ ${config.instructions}` : "";
         };
       },
       workflows: {
-        "merge-template": mergeTemplateWorkflow
+        "merge-template": agentBuilderTemplateWorkflow
       },
       memory: new Memory({
         options: AgentBuilderDefaults.DEFAULT_MEMORY_CONFIG,
@@ -3767,4 +4345,4 @@ ${!options?.outputFormat || options.outputFormat === "both" ? "Provide both expl
   }
 };
 
-export { AgentBuilder };
+export { AgentBuilder, AgentBuilderDefaults, agentBuilderTemplateWorkflow, mergeTemplateBySlug };