Relevant source files

The following files were used as context for generating this wiki page: - [CONTRIBUTING.md](https://github.com/mastra-ai/mastra/blob/main/CONTRIBUTING.md) - [DEVELOPMENT.md](https://github.com/mastra-ai/mastra/blob/main/DEVELOPMENT.md) - [CODE_OF_CONDUCT.md](https://github.com/mastra-ai/mastra/blob/main/CODE_OF_CONDUCT.md) - [README.md](https://github.com/mastra-ai/mastra/blob/main/README.md) - [CLAUDE.md](https://github.com/mastra-ai/mastra/blob/main/CLAUDE.md) - [templates/README.md](https://github.com/mastra-ai/mastra/blob/main/templates/README.md)

# Contributing to Mastra Mastra welcomes contributions of all sizes and from developers of any skill level. This guide provides the necessary information to set up your development environment, understand the contribution workflow, and submit your changes to the project. All contributions are expected to adhere to the project's [Code of Conduct](#code-of-conduct). Sources: [CONTRIBUTING.md:3](), [CODE_OF_CONDUCT.md]() ## Development Environment Setup Before contributing, you must set up your local development environment. This involves installing prerequisites and cloning the repository. Sources: [DEVELOPMENT.md:3-10]() ### Prerequisites Ensure you have the following tools installed on your system: | Tool | Required Version | Notes | | :-------- | :----------------- | :---------------------------------- | | Node.js | v22.13.0 or later | Core runtime for the project. | | pnpm | v10.18.0 or later | Used for package management. | | Docker | Optional | Only needed for a subset of tests. | Sources: [DEVELOPMENT.md:5-9]() ### Initial Setup The following diagram illustrates the steps to get your environment ready for development. ```mermaid flowchart TD A[Clone Repository] --> B[Enable Corepack] B --> C[Install Dependencies & Build] C --> D{Ready to Develop} subgraph "Commands" A_cmd(git clone https://github.com/mastra-ai/mastra.git) B_cmd(corepack enable) C_cmd(pnpm run setup) end A -- "1. " --- A_cmd B -- "2. " --- B_cmd C -- "3. " --- C_cmd ``` This diagram shows the initial setup process for the Mastra development environment. Sources: [DEVELOPMENT.md:38-51]() 1. **Clone the repository**: ```bash git clone https://github.com/mastra-ai/mastra.git cd mastra ``` 2. **Enable corepack**: This ensures you are using the correct version of `pnpm`. ```bash corepack enable ``` 3. **Install dependencies and build**: The `setup` script installs all dependencies and builds the necessary CLI package. ```bash pnpm run setup ``` Sources: [DEVELOPMENT.md:40-51](), [CLAUDE.md:7-8]() ## Contribution Workflow Mastra has a structured workflow for different types of contributions, such as bug reports, bug fixes, and new features. Sources: [CONTRIBUTING.md:12-28]() ### Contribution Process Flow The general process for contributing to Mastra is outlined below. ```mermaid graph TD subgraph "Start" A{Found a Bug?} B{Want a New Feature?} end A -- Yes --> C[Search GitHub Issues]; C -- Not Found --> D[Open New Bug Report]; D -- Include --> E[Minimal Reproduction]; C -- Found --> F[Comment on Existing Issue]; A -- No --> G{Wrote a Patch?}; G -- Yes --> H[Open a Pull Request]; H -- Describe --> I[Problem & Solution]; B -- Yes --> J[Open Feature Request]; J -- Wait for --> K[Maintainer Feedback]; K -- Positive --> H; ``` This diagram shows the decision flow for reporting bugs, proposing features, and submitting patches. Sources: [CONTRIBUTING.md:14-28]() ### Reporting Bugs If you find a bug, first search the [GitHub issues](https://github.com/mastra-ai/mastra/issues) to see if it has already been reported. If not, open a new bug report and provide a **minimal reproduction** of the issue. A minimal reproduction is a simplified project that demonstrates the bug with the least amount of code necessary. Sources: [CONTRIBUTING.md:14-19, 32-34]() #### Creating a Minimal Reproduction 1. **Start Fresh**: Create a new Mastra project using `npx create-mastra@latest bug-reproduction`. 2. **Isolate the Bug**: Add only the minimal code, configuration, and packages required to demonstrate the bug. Do not include your entire production codebase. 3. **Verify**: Ensure the minimal project reliably reproduces the error. 4. **Publish**: Push the code to a public GitHub repository and link it in your issue. Include a `README.md` with clear steps to reproduce the error. Sources: [CONTRIBUTING.md:36-65]() ### Submitting Changes For bug fixes or new features that have received positive feedback, follow these steps to submit your code. This sequence diagram details the process of submitting a code change. ```mermaid sequenceDiagram participant Dev as Developer participant LocalRepo as Local Repository participant RemoteRepo as Remote Repository (GitHub) Dev->>LocalRepo: git checkout -b feature/your-feature Note over Dev,LocalRepo: 1. Create a new branch Dev->>LocalRepo: Make code changes Dev->>LocalRepo: pnpm test Note over Dev,LocalRepo: 2. Implement changes and run tests Dev->>LocalRepo: pnpm changeset Note over Dev,LocalRepo: 3. Create a changeset for versioning Dev->>LocalRepo: git commit -am "feat: your change" Dev->>LocalRepo: git push origin feature/your-feature Note over Dev,LocalRepo: 4. Commit and push changes Dev->>RemoteRepo: Open Pull Request Note over Dev,RemoteRepo: 5. Describe problem and solution ``` Sources: [DEVELOPMENT.md:104-117]() 1. **Create a Branch**: ```bash git checkout -b feature/your-feature-name ``` 2. **Make Changes & Test**: Implement your changes and ensure all tests pass. ```bash pnpm test ``` 3. **Create a Changeset**: This is required for version management. ```bash pnpm changeset ``` Follow the prompts to describe your changes. 4. **Open a Pull Request**: Push your branch to GitHub and open a pull request, clearly describing the problem and solution. Sources: [DEVELOPMENT.md:104-117]() ## Building and Testing Mastra is a monorepo managed with `pnpm`. The project is divided into several packages that can be built and tested individually or all at once. Sources: [DEVELOPMENT.md:11, 53-54]() ### Building Packages You can build all packages or target specific ones. If you encounter memory errors during a build, you can increase Node's heap size. ```bash # Increase heap size for large builds NODE_OPTIONS="--max-old-space-size=4096" pnpm build ``` Sources: [DEVELOPMENT.md:58-62]() | Command | Description | | -------------------------- | --------------------------------- | | `pnpm build` | Build all packages. | | `pnpm build:packages` | Build all core packages. | | `pnpm build:core` | Build the core framework package. | | `pnpm build:cli` | Build the CLI and playground. | | `pnpm build:rag` | Build the RAG package. | | `pnpm build:memory` | Build the memory package. | | `pnpm build:deployers` | Build all deployment adapters. | | `pnpm build:combined-stores` | Build all storage adapters. | Sources: [DEVELOPMENT.md:64-87](), [CLAUDE.md:7-15]() ### Running Tests Mastra uses Vitest for testing. Some integration tests require environment variables and Docker services to be running. 1. **Set up environment variables**: Create a `.env` file in the root directory with the necessary API keys. ```text OPENAI_API_KEY= COHERE_API_KEY= PINECONE_API_KEY= ... ``` 2. **Start development services**: ```bash pnpm run dev:services:up ``` Sources: [DEVELOPMENT.md:93-102]() | Command | Description | | ----------------------- | ---------------------------------------------- | | `pnpm test` | Run all tests across all packages. | | `pnpm test:watch` | Run tests in interactive watch mode. | | `pnpm test:core` | Run tests for the `core` package. | | `pnpm test:cli` | Run tests for the `cli` package. | | `pnpm test:rag` | Run tests for the `rag` package. | | `pnpm test:memory` | Run tests for the `memory` package. | Sources: [DEVELOPMENT.md:89-102](), [CLAUDE.md:19-26]() For faster testing during development, it's recommended to build from the root and then run tests within a specific package's directory. Sources: [CLAUDE.md:20-24]() ## Contributing New Templates You can also contribute by adding new templates to the `templates/` directory. Sources: [templates/README.md:1-3]() ### Template Requirements A new template must be in its own folder and include the following files: | File | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `package.json` | Must have a `description`. All `@mastra/*` dependencies and `mastra` devDependency must be set to `"beta"`. Use `openai` as the LLM provider. | | `.env.example` | List all required environment variables, using `***` for secret values. | | `README.md` | Explain the template's purpose, overview, and setup steps. List all environment variables. | Sources: [templates/README.md:7-46]() ## Code of Conduct All contributors are expected to follow the [Mastra Code of Conduct](https://github.com/mastra-ai/mastra/blob/main/CODE_OF_CONDUCT.md). The community is committed to providing a welcoming and harassment-free experience for everyone. Sources: [CODE_OF_CONDUCT.md]() ## Security Disclosures If you discover a security vulnerability, please report it responsibly by emailing [security@mastra.ai](mailto:security@mastra.ai). Sources: [README.md:86-89]() ## Getting Help If you need help or have questions, join the [Mastra Discord community](https://discord.gg/BTYqqHKUrf). Sources: [DEVELOPMENT.md:121-122](), [README.md:80-82]()## FULL FILE CONTEXT SUMMARY Query: You are an expert code analyst examining the github repository: https://github.com/mastra-ai/mastra (mastra). You provide direct, concise, and accurate information about code repositories. You NEVER start responses with markdown headers or code fences. IMPORTANT:You MUST respond in English language. Total Files Included: 23 Total Files Skipped: 0 Total Context Tokens: 63,054 / 800,000 (7.9%) Remaining Token Budget: 736,946 ### Included Files: 1. DEVELOPMENT.md (1,328 tokens) 2. CLAUDE.md (1,330 tokens) 3. CONTRIBUTING.md (1,304 tokens) 4. packages/agent-builder/src/workflows/template-builder/template-builder.ts (15,408 tokens) 5. README.md (1,340 tokens) 6. packages/agent-builder/src/defaults.ts (21,235 tokens) 7. templates/template-docs-chatbot/README.md (1,339 tokens) 8. e2e-tests/kitchen-sink/README.md (1,659 tokens) 9. templates/template-ad-copy-from-content/README.md (1,738 tokens) 10. packages/agent-builder/src/workflows/workflow-builder/prompts.ts (4,062 tokens) 11. templates/README.md (653 tokens) 12. examples/dane/src/mastra/workflows/first-contributor.ts (955 tokens) 13. templates/template-google-sheets/README.md (1,429 tokens) 14. examples/dane/README.md (715 tokens) 15. examples/basics/evals/summarization/README.md (510 tokens) 16. examples/openapi-spec-writer/README.md (525 tokens) 17. templates/template-csv-to-questions/README.md (3,011 tokens) 18. packages/agent-builder/integration-tests/README.md (996 tokens) 19. packages/mcp-docs-server/README.md (951 tokens) 20. templates/template-deep-research/README.md (498 tokens) ... and 3 more files ================================================================================ FILE: DEVELOPMENT.md Relevance Score: 0.990 | Chunks Retrieved: 1 | Tokens: 1,328 ================================================================================ # Mastra Development Guide This guide provides instructions for developers who want to contribute to or work with the Mastra codebase. ## Prerequisites - **Node.js** (v22.13.0 or later) - **pnpm** (v10.18.0 or later) - Mastra uses pnpm for package management - **Docker** (for local development services) - Only needed for a subset of tests, not required for general development ## Repository Structure Mastra is organized as a monorepo with the following key directories: - **packages/** - Core packages that make up the Mastra framework - **core/** - The foundation of the Mastra framework that provides essential components including agent system, LLM abstractions, workflow orchestration, vector storage, memory management, and tools infrastructure - **cli/** - Command-line interface for creating, running, and managing Mastra projects, including the interactive playground UI for testing agents and workflows - **deployer/** - Server infrastructure and build tools for deploying Mastra applications to various environments, with API endpoints for agents, workflows, and memory management - **rag/** - Retrieval-augmented generation tools for document processing, chunking, embedding, and semantic search with support for various reranking strategies - **memory/** - Memory systems for storing and retrieving conversation history, vector data, and application state across sessions - **evals/** - Evaluation frameworks for measuring LLM performance with metrics for accuracy, relevance, toxicity, and other quality dimensions - **mcp/** - Model Context Protocol implementation for standardized communication with AI models, enabling tool usage and structured responses across different providers - **deployers/** - Platform-specific deployment adapters for services like Vercel, Netlify, and Cloudflare, handling environment configuration and serverless function deployment - **stores/** - Storage adapters for various vector and key-value databases, providing consistent APIs for data persistence across different storage backends - **voice/** - Speech-to-text and voice processing capabilities for real-time transcription and voice-based interactions - **client-sdks/** - Client libraries for different platforms and frameworks that provide type-safe interfaces to interact with Mastra services - **examples/** - Example applications demonstrating various Mastra features including agents, workflows, memory systems, and integrations with different frameworks ## Getting Started ### Setting Up Your Development Environment 1. **Clone the repository**: ```bash git clone https://github.com/mastra-ai/mastra.git cd mastra ``` 2. **Enable corepack** (ensures correct pnpm version): ```bash corepack enable ``` 3. **Install dependencies and build initial packages**: ```bash pnpm run setup ``` This command installs all dependencies and builds the CLI package, which is required for other packages. ### Building Packages If you run into the following error during a build: ```text Error [ERR_WORKER_OUT_OF_MEMORY]: Worker terminated due to reaching memory limit: JS heap out of memory ``` you can increase Node’s heap size by prepending your build command with: ```bash NODE_OPTIONS="--max-old-space-size=4096" pnpm build ``` - **Build all packages**: ```bash pnpm build ``` - **Build specific package groups**: ```bash pnpm build:packages # All core packages pnpm build:deployers # All deployment adapters pnpm build:combined-stores # All vector and data stores pnpm build:speech # All speech processing packages pnpm build:clients # All client SDKs ``` - **Build individual packages**: ```bash pnpm build:core # Core framework package pnpm build:cli # CLI and playground package pnpm build:deployer # Deployer package pnpm build:rag # RAG package pnpm build:memory # Memory package pnpm build:evals # Evaluation framework package pnpm build:docs-mcp # MCP documentation server ``` ## Testing Mastra uses Vitest for testing. You can run all tests or only specific packages. - All tests: ```bash pnpm test ``` - Specific package tests: ```bash pnpm test:core # Core package tests pnpm test:cli # CLI tests pnpm test:rag # RAG tests pnpm test:memory # Memory tests pnpm test:evals # Evals tests pnpm test:clients # Client SDK tests pnpm test:combined-stores # Combined stores tests ``` - Watch mode (for development): ```bash pnpm test:watch ``` Some tests require environment variables to be set. If you're unsure about the required variables, ask for help in the pull request or wait for CI to run the tests. Create a `.env` file in the root directory with the following content: ```text OPENAI_API_KEY= COHERE_API_KEY= PINECONE_API_KEY= CLOUDFLARE_ACCOUNT_ID= CLOUDFLARE_API_TOKEN= DB_URL=postgresql://postgres:postgres@localhost:5432/mastra ``` Afterwards, start the development services: ```bash pnpm run dev:services:up ``` ## Contributing 1. **Create a branch for your changes**: ```bash git checkout -b feature/your-feature-name ``` 2. **Make your changes and ensure tests pass**: ```bash pnpm test ``` 3. **Create a changeset** (for version management): ```bash pnpm changeset ``` Follow the prompts to describe your changes. 4. **Open a pull request** with your changes. ## Documentation The documentation site is built from the `/docs` directory. Follow its [documentation guide](./docs/CONTRIBUTING.md) for instructions on contributing to the docs. ## Need Help? Join the [Mastra Discord community](https://discord.gg/BTYqqHKUrf) for support and discussions. ================================================================================ ================================================================================ FILE: CLAUDE.md Relevance Score: 0.980 | Chunks Retrieved: 1 | Tokens: 1,330 ================================================================================ # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Development Commands ### Setup and Build - `pnpm run setup` - Install dependencies and build CLI (required first step) - `pnpm build` - Build all packages (excludes examples and docs) - `pnpm build:packages` - Build core packages only - `pnpm build:core` - Build core framework package - `pnpm build:cli` - Build CLI and playground package - `pnpm build:memory` - Build memory package - `pnpm build:rag` - Build RAG package - `pnpm build:combined-stores` - Build all storage adapters - `pnpm build:deployers` - Build deployment adapters - `pnpm build:evals` - Build evaluation framework - `NODE_OPTIONS="--max-old-space-size=4096" pnpm build` - Build with increased memory if needed ### Testing - `pnpm dev:services:up` - Start local Docker services (required for integration tests) - For faster testing: Build from root, then cd to specific package and run tests there ```bash pnpm build # Build from monorepo root first cd packages/memory pnpm test # Much faster than running all tests ``` - `pnpm test` - Run all tests (slow, use sparingly) - `pnpm test:watch` - Run tests in watch mode - Package-specific tests: `pnpm test:core`, `pnpm test:cli`, `pnpm test:memory`, `pnpm test:rag`, etc. ### Development - `pnpm dev:services:down` - Stop local Docker services - `pnpm typecheck` - Run TypeScript checks across all packages - `pnpm prettier:format` - Format code with Prettier - `pnpm format` - Run linting across all packages with auto-fix (excludes examples, docs, integrations, playground) ## Documentation ### Documentation Locations - **Main docs**: `docs/` directory - Contains the full documentation site built with Next.js - **Course content**: `docs/src/course/` - Tutorial and learning materials - **API reference**: Generated from code comments and exported types - **Package READMEs**: Each package/integration has its own README.md - **Development guide**: `DEVELOPMENT.md` - Setup and contribution instructions ### Documentation Guidelines - Follow `.cursor/rules/writing-documentation.mdc` for writing style - Avoid marketing language, focus on technical implementation details - Examples should be practical and runnable ## Architecture Overview Mastra is a modular AI framework built around central orchestration with pluggable components. Key architectural patterns: ### Core Components - **Mastra Class** (`packages/core/src/mastra/`) - Central configuration hub with dependency injection - **Agents** (`packages/core/src/agent/`) - Primary AI interaction abstraction with tools, memory, and voice - **Tools System** (`packages/core/src/tools/`) - Dynamic tool composition supporting multiple sources - **Memory System** (`packages/core/src/memory/`) - Thread-based conversation persistence with semantic recall - **Workflows** (`packages/core/src/workflows/`) - Step-based execution with suspend/resume capabilities - **Storage Layer** (`packages/core/src/storage/`) - Pluggable backends with standardized interfaces ### Package Structure - **packages/** - Core framework packages (core, cli, deployer, rag, memory, evals, mcp, server) - **stores/** - Storage adapters (pg, chroma, pinecone, etc.) - **deployers/** - Platform deployment adapters (vercel, netlify, cloudflare) - **speech/** - Speech processing packages (voice synthesis and recognition) - **client-sdks/** - Client libraries for different platforms - **integrations/** - Third-party API integrations (github, firecrawl, etc.) - **examples/** - Demo applications - **auth/** - Authentication provider integrations ### Key Patterns 1. **Dependency Injection** - Components register with central Mastra instance 2. **Plugin Architecture** - Pluggable storage, vectors, memory, deployers 3. **Runtime Context** - Request-scoped context propagation for dynamic configuration 4. **Message List Abstraction** - Unified message handling across formats ### Tools and Integrations - Tools are dynamically composed from multiple sources (assigned, memory, toolsets, MCP) - Integrations are OpenAPI-based with OAuth/API key authentication - MCP (Model Context Protocol) enables external tool integration ### Storage and Memory - Pluggable storage backends with standardized interfaces - Memory system supports thread-based conversations, semantic recall, and working memory - Vector stores provide semantic search capabilities ## Development Guidelines ### Documentation Writing Follow `.cursor/rules/writing-documentation.mdc`: - Avoid marketing language ("powerful", "complete", "out-of-the-box") - Don't use "your needs", "production-ready", "makes it easy" - Focus on technical details rather than benefits - Write for engineers, not marketing ### Monorepo Management - Use pnpm (v9.7.0+) for package management - Build dependencies are managed through turbo.json - All packages use TypeScript with strict type checking - For testing: build from root first, then cd to specific package for faster iteration ### Component Development - Components should integrate with central Mastra orchestration - Follow plugin patterns for extensibility - Implement standardized interfaces for storage/vector operations - Use telemetry decorators for observability - Support both sync and async operations where applicable ### Testing Strategy - Integration tests require Docker services (`pnpm dev:services:up`) - Use Vitest for testing framework - Test files should be co-located with source code - For faster development: build from root, then test individual packages - Mock external services in unit tests ### Common Issues - Memory errors during build: Use `NODE_OPTIONS="--max-old-space-size=4096"` - Missing dependencies: Run `pnpm setup` first - Test failures: Ensure Docker services are running and build from root first - Type errors: Run `pnpm typecheck` to check all packages ================================================================================ ================================================================================ FILE: CONTRIBUTING.md Relevance Score: 0.970 | Chunks Retrieved: 1 | Tokens: 1,304 ================================================================================ # Contributing to Mastra Welcome to Mastra! We welcome contributions of any size and skill level. Thanks for taking the time to contribute! > [!Tip] > > **For new contributors:** Take a look at [https://github.com/firstcontributions/first-contributions%5D%28https%3A//github.com/firstcontributions/first-contributions) for helpful information on contributing to open source projects. ## Contributor Guidelines Please read the guidance below about what to do if you: - [Found a bug](#did-you-find-a-bug) - [Fixed a bug](#did-you-write-a-patch-that-fixes-a-bug) - [Want to add a new feature or change an existing one](#do-you-intend-to-add-a-new-feature-or-change-an-existing-one) - [Want to improve documentation](#want-to-improve-documentation) Read the [Development Guide](./DEVELOPMENT.md) for information on setting up a development environment. ### Did you find a bug? - Ensure that the bug was not already reported by searching in the [GitHub issues](https://github.com/mastra-ai/mastra/issues) - If you're unable to find an open issue addressing the problem, [open a new bug report](https://github.com/mastra-ai/mastra/issues/new?template=bug_report.yml) providing a [minimal reproduction](#minimal-reproduction) of the issue. Be sure to include a title and clear description, as much relevant information as possible, and a **code sample** or an **executable test case** demonstrating the expected behavior that is not occurring. ### Did you write a patch that fixes a bug? - Open a new GitHub pull request with the patch - Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable ### Do you intend to add a new feature or change an existing one? - Open a [feature request](https://github.com/mastra-ai/mastra/issues/new?template=feature_request.yml) and wait for feedback from the Mastra maintainers - Assuming you get positive feedback, raise a pull request against your fork/branch to track the development of the feature and discuss the implementation. ### Want to improve documentation? Read the [documentation contribution guidelines](./docs/CONTRIBUTING.md) for more details. ## Minimal Reproduction A minimal reproduction is a simplified Mastra project that demonstrates a bug with the least amount of code necessary. This helps isolate the issue and makes it easier for maintainers to verify and fix the problem. A minimal reproduction also proves that the bug is not caused by other parts of your codebase or environment. Lastly, creating a minimal reproduction often helps you identify the root cause of the issue yourself. ### 1. Start with a fresh project Create a new Mastra project: ```bash npx create-mastra@latest bug-reproduction cd bug-reproduction ``` Alternatively, you can start from one of the examples in the `/examples` directory that's closest to your use case, then strip it down to the minimum. ### 2. Add only what's needed to demonstrate the bug **Do add:** - The specific Mastra packages related to the issue (e.g., `@mastra/core`, `@mastra/rag`, `@mastra/pg`) - Minimal configuration to reproduce the bug - Only the code that triggers the error **Don't add:** - Your entire production codebase - Multiple unrelated features - Custom UI components or styling - Business logic unrelated to the bug - Environment-specific configurations **For specific issues:** - **Agents**: Include only the minimal agent configuration and tools needed - **Integrations**: Add only the specific integration that's problematic - **Storage/Memory**: Include only the relevant store adapter - **Workflows**: Include only the minimal workflow steps that reproduce the issue - **Tools**: Add only the tool causing the problem ### 3. Verify the reproduction Test that your minimal reproduction actually demonstrates the problem: - Run the reproduction in a clean environment - Confirm you see the expected error or unexpected behavior - Try removing code to see if you can make it even more minimal - If you fixed the issue while creating the reproduction, document what you changed ### 4. Publish and share Create a public GitHub repository with your reproduction: 1. Push your code to GitHub 2. Add a clear README.md that includes: - Description of the expected vs actual behavior - Exact steps to reproduce (install, build, run commands) - Which command or action triggers the error - Your environment (Node version, package manager, OS) 3. Link to the repository in your GitHub issue ### Troubleshooting common scenarios **LLM/API keys**: - Use mock responses when possible to avoid requiring real API keys - If real keys are needed, clearly document which services require authentication - If possible, use OpenAI as it is widely accessible - Consider using environment variable examples: `OPENAI_API_KEY=your-key-here` **Docker services**: - Note if the reproduction requires `pnpm dev:services:up` for PostgreSQL, Redis, etc. - Specify which services are needed **Build vs runtime issues**: - Clarify if the bug occurs during `pnpm build`, `pnpm dev`, or at runtime - Include build output if it's a build-time error **Monorepo context**: - If the issue is in a specific package, mention which one - Note if the issue only occurs when built from the monorepo root ### Optional steps For complex reproductions, you may also need to: - **Observability**: Include logs from observability providers if relevant to the issue - **Production-only bugs**: If the issue only occurs in deployed environments, provide details about your deployment platform (Vercel, Netlify, Cloudflare, etc.) - **Specific LLM models**: Document if the bug only occurs with certain models or providers - **Screenshots/videos**: For UI-related issues, include visual documentation of the problem - **Network traces**: For integration issues, include relevant network request/response data A well-crafted minimal reproduction is the best way to get your issue resolved quickly. ================================================================================ ================================================================================ FILE: packages/agent-builder/src/workflows/template-builder/template-builder.ts Relevance Score: 0.960 | Chunks Retrieved: 1 | Tokens: 15,408 ================================================================================ import { existsSync } from 'node:fs'; import { mkdtemp, copyFile, readFile, mkdir, readdir, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join, dirname, resolve, extname, basename } from 'node:path'; import { openai } from '@ai-sdk/openai'; import { Agent, tryGenerateWithJsonFallback, tryStreamWithJsonFallback } from '@mastra/core/agent'; import { createTool } from '@mastra/core/tools'; import { createWorkflow, createStep } from '@mastra/core/workflows'; import { z } from 'zod'; import { AgentBuilder } from '../..'; import { AgentBuilderDefaults } from '../../defaults'; import type { TemplateUnit, UnitKind } from '../../types'; import { ApplyResultSchema, AgentBuilderInputSchema, CloneTemplateResultSchema, PackageAnalysisSchema, DiscoveryResultSchema, OrderedUnitsSchema, PackageMergeInputSchema, PackageMergeResultSchema, InstallInputSchema, InstallResultSchema, FileCopyInputSchema, FileCopyResultSchema, IntelligentMergeInputSchema, IntelligentMergeResultSchema, ValidationFixInputSchema, ValidationFixResultSchema, PrepareBranchInputSchema, PrepareBranchResultSchema, } from '../../types'; import { getMastraTemplate, kindWeight, spawnSWPM, logGitState, backupAndReplaceFile, renameAndCopyFile, gitCheckoutBranch, gitClone, gitCheckoutRef, gitRevParse, gitAddAndCommit, resolveTargetPath, mergeGitignoreFiles, mergeEnvFiles, resolveModel, } from '../../utils'; // Step 1: Clone template to temp directory const cloneTemplateStep = createStep({ id: 'clone-template', description: 'Clone the template repository to a temporary directory at the specified ref', inputSchema: AgentBuilderInputSchema, outputSchema: CloneTemplateResultSchema, execute: async ({ inputData }) => { const { repo, ref = 'main', slug, targetPath } = inputData; if (!repo) { throw new Error('Repository URL or path is required'); } // Extract slug from repo URL if not provided const inferredSlug = slug || repo .split('/') .pop() ?.replace(/\.git$/, '') || 'template'; // Create temporary directory const tempDir = await mkdtemp(join(tmpdir(), 'mastra-template-')); try { // Clone repository await gitClone(repo, tempDir); // Checkout specific ref if provided if (ref !== 'main' && ref !== 'master') { await gitCheckoutRef(tempDir, ref); } // Get commit SHA const commitSha = await gitRevParse(tempDir, 'HEAD'); return { templateDir: tempDir, commitSha: commitSha.trim(), slug: inferredSlug, success: true, targetPath, }; } catch (error) { // Cleanup on error try { await rm(tempDir, { recursive: true, force: true }); } catch {} return { templateDir: '', commitSha: '', slug: slug || 'unknown', success: false, error: `Failed to clone template: ${error instanceof Error ? error.message : String(error)}`, targetPath, }; } }, }); // Step 2: Analyze template package.json for dependencies const analyzePackageStep = createStep({ id: 'analyze-package', description: 'Analyze the template package.json to extract dependency information', inputSchema: CloneTemplateResultSchema, outputSchema: PackageAnalysisSchema, execute: async ({ inputData }) => { console.info('Analyzing template package.json...'); const { templateDir } = inputData; const packageJsonPath = join(templateDir, 'package.json'); try { const packageJsonContent = await readFile(packageJsonPath, 'utf-8'); const packageJson = JSON.parse(packageJsonContent); console.info('Template package.json:', JSON.stringify(packageJson, null, 2)); return { dependencies: packageJson.dependencies || {}, devDependencies: packageJson.devDependencies || {}, peerDependencies: packageJson.peerDependencies || {}, scripts: packageJson.scripts || {}, 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)}`); return { dependencies: {}, devDependencies: {}, peerDependencies: {}, scripts: {}, name: '', version: '', description: '', success: true, // This is a graceful fallback, not a failure }; } }, }); // Step 3: Discover template units by scanning the templates directory const discoverUnitsStep = createStep({ id: 'discover-units', description: 'Discover template units by analyzing the templates directory structure', inputSchema: CloneTemplateResultSchema, outputSchema: DiscoveryResultSchema, execute: async ({ inputData, requestContext }) => { const { templateDir } = inputData; const targetPath = resolveTargetPath(inputData, requestContext); const tools = await AgentBuilderDefaults.DEFAULT_TOOLS(templateDir); console.info('targetPath', targetPath); const model = await resolveModel({ requestContext, projectPath: targetPath, defaultModel: openai('gpt-4.1') }); try { const agent = new Agent({ id: 'mastra-project-discoverer', model, 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). Mastra Project Structure Analysis: - Each Mastra project has a structure like: ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.agent}, ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.workflow}, ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.tool}, ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE['mcp-server']}, ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.network} - Analyze TypeScript files in each category directory to identify exported units CRITICAL: YOU MUST USE YOUR TOOLS (readFile, listDirectory) TO DISCOVER THE UNITS IN THE TEMPLATE DIRECTORY. IMPORTANT - Agent Discovery Rules: 1. **Multiple Agent Files**: Some templates have separate files for each agent (e.g., evaluationAgent.ts, researchAgent.ts) 2. **Single File Multiple Agents**: Some files may export multiple agents (look for multiple 'export const' or 'export default' statements) 3. **Agent Identification**: Look for exported variables that are instances of 'new Agent()' or similar patterns 4. **Naming Convention**: Agent names should be extracted from the export name (e.g., 'weatherAgent', 'evaluationAgent') For each Mastra project directory you analyze: 1. Scan all TypeScript files in ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.agent} and identify ALL exported agents 2. Scan all TypeScript files in ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.workflow} and identify ALL exported workflows 3. Scan all TypeScript files in ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.tool} and identify ALL exported tools 4. Scan all TypeScript files in ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE['mcp-server']} and identify ALL exported MCP servers 5. Scan all TypeScript files in ${AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE.network} and identify ALL exported networks 6. Scan for any OTHER files in src/mastra that are NOT in the above default folders (e.g., lib/, utils/, types/, etc.) and identify them as 'other' files IMPORTANT - Naming Consistency Rules: - For ALL unit types (including 'other'), the 'name' field should be the filename WITHOUT extension - For structured units (agents, workflows, tools, etc.), prefer the actual export name if clearly identifiable - use the base filename without extension for the id (e.g., 'util.ts' → name: 'util') - use the relative path from the template root for the file (e.g., 'src/mastra/lib/util.ts' → 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 isV2 = model.specificationVersion === 'v2'; const prompt = `Analyze the Mastra project directory structure at "${templateDir}". List directory contents using listDirectory tool, and then analyze each file with readFile tool. IMPORTANT: - Look inside the actual file content to find export statements like 'export const agentName = new Agent(...)' - A single file may contain multiple exports - Return the actual exported variable names, 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.`; const 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(), }); const result = isV2 ? await tryGenerateWithJsonFallback(agent, prompt, { structuredOutput: { schema: output, }, maxSteps: 100, }) : await agent.generateLegacy(prompt, { experimental_output: output, maxSteps: 100, }); const template = result.object ?? {}; const units: TemplateUnit[] = []; // Add agents template.agents?.forEach((agentId: { name: string; file: string }) => { units.push({ kind: 'agent', id: agentId.name, file: agentId.file }); }); // Add workflows template.workflows?.forEach((workflowId: { name: string; file: string }) => { units.push({ kind: 'workflow', id: workflowId.name, file: workflowId.file }); }); // Add tools template.tools?.forEach((toolId: { name: string; file: string }) => { units.push({ kind: 'tool', id: toolId.name, file: toolId.file }); }); // Add MCP servers template.mcp?.forEach((mcpId: { name: string; file: string }) => { units.push({ kind: 'mcp-server', id: mcpId.name, file: mcpId.file }); }); // Add networks template.networks?.forEach((networkId: { name: string; file: string }) => { units.push({ kind: 'network', id: networkId.name, file: networkId.file }); }); // Add other files template.other?.forEach((otherId: { name: string; file: string }) => { units.push({ kind: 'other', id: otherId.name, file: otherId.file }); }); console.info('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`); } 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)}`, }; } }, }); // Step 4: Topological ordering (simplified) const orderUnitsStep = createStep({ id: 'order-units', description: 'Sort units in topological order based on kind weights', inputSchema: DiscoveryResultSchema, outputSchema: OrderedUnitsSchema, execute: async ({ inputData }) => { const { units } = inputData; // Simple sort by kind weight (mcp-servers first, then tools, agents, workflows, integration last) const orderedUnits = [...units].sort((a, b) => { const aWeight = kindWeight(a.kind); const bWeight = kindWeight(b.kind); return aWeight - bWeight; }); return { orderedUnits, success: true, }; }, }); // Step 5: Prepare branch const prepareBranchStep = createStep({ id: 'prepare-branch', description: 'Create or switch to integration branch before modifications', inputSchema: PrepareBranchInputSchema, outputSchema: PrepareBranchResultSchema, execute: async ({ inputData, requestContext }) => { const targetPath = resolveTargetPath(inputData, requestContext); 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)}`, }; } }, }); // Step 6: Package merge const packageMergeStep = createStep({ id: 'package-merge', description: 'Merge template package.json dependencies into target project', inputSchema: PackageMergeInputSchema, outputSchema: PackageMergeResultSchema, execute: async ({ inputData, requestContext }) => { console.info('Package merge step starting...'); const { slug, packageInfo } = inputData; const targetPath = resolveTargetPath(inputData, requestContext); try { 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: any; 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: any) => (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: string) => name in targetPkg.dependencies || name in targetPkg.devDependencies || name in targetPkg.peerDependencies; // Merge dependencies: add only if missing everywhere for (const [name, ver] of Object.entries(tplDeps)) { if (!existsAnywhere(name)) { (targetPkg.dependencies as Record)[name] = String(ver); } } // Merge devDependencies for (const [name, ver] of Object.entries(tplDevDeps)) { if (!existsAnywhere(name)) { (targetPkg.devDependencies as Record)[name] = String(ver); } } // Merge peerDependencies for (const [name, ver] of Object.entries(tplPeerDeps)) { if (!(name in targetPkg.peerDependencies)) { (targetPkg.peerDependencies as Record)[name] = String(ver); } } // Merge scripts with prefixed keys to avoid collisions const prefix = `template:${slug}:`; for (const [name, cmd] of Object.entries(tplScripts)) { const newKey = `${prefix}${name}`; if (!(newKey in targetPkg.scripts)) { (targetPkg.scripts as Record)[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 for ${slug}`, }; } catch (error) { console.error('Package merge failed:', error); return { success: false, applied: false, message: `Package merge failed: ${error instanceof Error ? error.message : String(error)}`, error: error instanceof Error ? error.message : String(error), }; } }, }); // Step 7: Install const installStep = createStep({ id: 'install', description: 'Install packages based on merged package.json', inputSchema: InstallInputSchema, outputSchema: InstallResultSchema, execute: async ({ inputData, requestContext }) => { console.info('Running install step...'); const targetPath = resolveTargetPath(inputData, requestContext); try { // Run install using swpm (no specific packages) 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, }; } catch (error) { console.error('Install failed:', error); return { success: false, error: error instanceof Error ? error.message : String(error), }; } }, }); // Step 7: Programmatic File Copy Step - copies template files to target project const programmaticFileCopyStep = createStep({ id: 'programmatic-file-copy', description: 'Programmatically copy template files to target project based on ordered units', inputSchema: FileCopyInputSchema, outputSchema: FileCopyResultSchema, execute: async ({ inputData, requestContext }) => { console.info('Programmatic file copy step starting...'); const { orderedUnits, templateDir, commitSha, slug } = inputData; const targetPath = resolveTargetPath(inputData, requestContext); try { const copiedFiles: Array<{ source: string; destination: string; unit: { kind: UnitKind; id: string }; }> = []; const conflicts: Array<{ unit: { kind: UnitKind; id: string }; issue: string; sourceFile: string; targetFile: string; }> = []; // Analyze target project naming convention first const analyzeNamingConvention = async ( directory: string, ): Promise<'camelCase' | 'snake_case' | 'kebab-case' | 'PascalCase' | 'unknown'> => { try { const files = await readdir(resolve(targetPath, directory), { withFileTypes: true }); const tsFiles = files.filter(f => f.isFile() && f.name.endsWith('.ts')).map(f => f.name); if (tsFiles.length === 0) return 'unknown'; // Check for patterns const camelCaseCount = tsFiles.filter(f => /^[a-z][a-zA-Z0-9]*\.ts$/.test(f)).length; const snakeCaseCount = tsFiles.filter(f => /^[a-z][a-z0-9_]*\.ts$/.test(f) && f.includes('_')).length; const kebabCaseCount = tsFiles.filter(f => /^[a-z][a-z0-9-]*\.ts$/.test(f) && f.includes('-')).length; const pascalCaseCount = tsFiles.filter(f => /^[A-Z][a-zA-Z0-9]*\.ts$/.test(f)).length; const max = Math.max(camelCaseCount, snakeCaseCount, kebabCaseCount, pascalCaseCount); if (max === 0) return 'unknown'; if (camelCaseCount === max) return 'camelCase'; if (snakeCaseCount === max) return 'snake_case'; if (kebabCaseCount === max) return 'kebab-case'; if (pascalCaseCount === max) return 'PascalCase'; return 'unknown'; } catch { return 'unknown'; } }; // Convert naming based on convention const convertNaming = (name: string, convention: string): string => { const baseName = basename(name, extname(name)); const ext = extname(name); switch (convention) { case 'camelCase': return ( baseName .replace(/[-_]/g, '') .replace(/([A-Z])/g, (match, p1, offset) => (offset === 0 ? p1.toLowerCase() : p1)) + ext ); case 'snake_case': return ( baseName .replace(/[-]/g, '_') .replace(/([A-Z])/g, (match, p1, offset) => (offset === 0 ? '' : '_') + p1.toLowerCase()) + ext ); case 'kebab-case': return ( baseName .replace(/[_]/g, '-') .replace(/([A-Z])/g, (match, p1, offset) => (offset === 0 ? '' : '-') + p1.toLowerCase()) + ext ); case 'PascalCase': return baseName.replace(/[-_]/g, '').replace(/^[a-z]/, match => match.toUpperCase()) + ext; default: return name; } }; // Process each unit for (const unit of orderedUnits) { console.info(`Processing ${unit.kind} unit "${unit.id}" from file "${unit.file}"`); // Resolve source file path with fallback logic let sourceFile: string; let resolvedUnitFile: string; // Check if unit.file already contains directory structure if (unit.file.includes('/')) { // unit.file has path structure (e.g., "src/mastra/agents/weatherAgent.ts") sourceFile = resolve(templateDir, unit.file); resolvedUnitFile = unit.file; } else { // unit.file is just filename (e.g., "weatherAgent.ts") - use fallback const folderPath = AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE[ unit.kind as keyof typeof AgentBuilderDefaults.DEFAULT_FOLDER_STRUCTURE ]; if (!folderPath) { conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `Unknown unit kind: ${unit.kind}`, sourceFile: unit.file, targetFile: 'N/A', }); continue; } resolvedUnitFile = `${folderPath}/${unit.file}`; sourceFile = resolve(templateDir, resolvedUnitFile); } // Check if source file exists if (!existsSync(sourceFile)) { conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `Source file not found: ${sourceFile}`, sourceFile: resolvedUnitFile, targetFile: 'N/A', }); continue; } // Extract target directory from resolved unit file path const targetDir = dirname(resolvedUnitFile); // Analyze target naming convention const namingConvention = await analyzeNamingConvention(targetDir); console.info(`Detected naming convention in ${targetDir}: ${namingConvention}`); // Convert unit.id to target filename with proper extension // Note: Check if unit.id already includes extension to avoid double extensions const hasExtension = extname(unit.id) !== ''; const baseId = hasExtension ? basename(unit.id, extname(unit.id)) : unit.id; const fileExtension = extname(unit.file); const convertedFileName = namingConvention !== 'unknown' ? convertNaming(baseId + fileExtension, namingConvention) : baseId + fileExtension; const targetFile = resolve(targetPath, targetDir, convertedFileName); // Handle file conflicts with strategy-based resolution if (existsSync(targetFile)) { const strategy = determineConflictStrategy(unit, targetFile); console.info(`File exists: ${convertedFileName}, using strategy: ${strategy}`); switch (strategy) { case 'skip': conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `File exists - skipped: ${convertedFileName}`, sourceFile: unit.file, targetFile: `${targetDir}/${convertedFileName}`, }); console.info(`⏭️ Skipped ${unit.kind} "${unit.id}": file already exists`); continue; case 'backup-and-replace': try { await backupAndReplaceFile(sourceFile, targetFile); copiedFiles.push({ source: sourceFile, destination: targetFile, unit: { kind: unit.kind, id: unit.id }, }); console.info( `🔄 Replaced ${unit.kind} "${unit.id}": ${unit.file} → ${convertedFileName} (backup created)`, ); continue; } catch (backupError) { conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `Failed to backup and replace: ${backupError instanceof Error ? backupError.message : String(backupError)}`, sourceFile: unit.file, targetFile: `${targetDir}/${convertedFileName}`, }); continue; } case 'rename': try { const uniqueTargetFile = await renameAndCopyFile(sourceFile, targetFile); copiedFiles.push({ source: sourceFile, destination: uniqueTargetFile, unit: { kind: unit.kind, id: unit.id }, }); console.info(`📝 Renamed ${unit.kind} "${unit.id}": ${unit.file} → ${basename(uniqueTargetFile)}`); continue; } catch (renameError) { conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `Failed to rename and copy: ${renameError instanceof Error ? renameError.message : String(renameError)}`, sourceFile: unit.file, targetFile: `${targetDir}/${convertedFileName}`, }); continue; } default: conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `Unknown conflict strategy: ${strategy}`, sourceFile: unit.file, targetFile: `${targetDir}/${convertedFileName}`, }); continue; } } // Ensure target directory exists await mkdir(dirname(targetFile), { recursive: true }); // Copy the file try { await copyFile(sourceFile, targetFile); copiedFiles.push({ source: sourceFile, destination: targetFile, unit: { kind: unit.kind, id: unit.id }, }); console.info(`✓ Copied ${unit.kind} "${unit.id}": ${unit.file} → ${convertedFileName}`); } catch (copyError) { conflicts.push({ unit: { kind: unit.kind, id: unit.id }, issue: `Failed to copy file: ${copyError instanceof Error ? copyError.message : String(copyError)}`, sourceFile: unit.file, targetFile: `${targetDir}/${convertedFileName}`, }); } } // Ensure tsconfig.json exists in target by copying from template if available, else generate a minimal one 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.info('✓ Copied tsconfig.json from template to target'); } else { // Generate a minimal tsconfig.json as a fallback 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'], } as const; 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.info('✓ 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', }); } // If the target project has no Mastra index file, copy from template 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))) {