0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/packages/codemod
Ward Peeters 809dab6bd1
chore: remove an unused core source file and fix the codemod typecheck (#29893)
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
History 2026-11-10 13:08:16 +01:00
..
.claude/skills/codemod-patterns chore(deps): update formatting & linting (#19388) 2026-07-20 16:13:28 +02:00
scripts feat(config): enforce node: prefix for Node.js built-in imports (#10625) 2025-11-28 14:05:35 +01:00
src chore: remove an unused core source file and fix the codemod typecheck (#29893) 2026-11-10 13:08:16 +01:00
AGENTS.md chore: enforce AGENTS.md token limits (#15464) 2026-04-18 19:12:37 -07:00
CHANGELOG.md chore: version - exit prerelease mode 2026-10-28 13:15:52 +00:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
oxlint.config.ts chore: migrate linting to oxlint (#20173) 2026-07-25 01:04:02 +02:00
package.json chore: version - exit prerelease mode 2026-10-28 13:15:52 +00:00
README.md chore(*): Update/unify/add READMEs (#22858) 2026-09-02 14:36:59 +02:00
tsconfig.json refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
tsdown.config.ts chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
turbo.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
vitest.config.ts test(core): move real-API tests to e2e files and fix failing unit tests (#13193) 2026-02-19 15:19:22 +01:00

@mastra/codemod

Mastra codemods are automated source transformations for upgrading applications when APIs are deprecated, removed, or changed between releases. They apply repeatable migrations across individual files, directories, or an entire project.

Installation

You do not need to install the package globally. Run codemods directly with npx from the project you want to update.

Usage

Run every codemod for the v0-to-v1 migration:

npx @mastra/codemod v1

Run one codemod against a file, directory, or project:

npx @mastra/codemod <codemod-name> <path>

npx @mastra/codemod v1/mastra-core-imports src/mastra.ts
npx @mastra/codemod v1/mastra-core-imports src/
npx @mastra/codemod v1/mastra-core-imports .

Documentation

Available commands

Run npx @mastra/codemod v1 to apply the complete v0-to-v1 migration, or use one of these names to run an individual transformation:

Codemod Description
v1/agent-abort-signal Moves abortSignal from modelSettings to the top-level agent method options.
v1/agent-generate-stream-v-next Renames generateVNext() and streamVNext() to generate() and stream().
v1/agent-processor-methods Renames agent processor getters to the corresponding list methods.
v1/agent-property-access Converts direct agent property access, such as agent.llm, to getter methods.
v1/agent-voice Moves agent voice methods, such as speak(), under the voice namespace.
v1/client-get-memory-thread Converts positional getMemoryThread() arguments to an options object.
v1/client-msg-function-args Updates client agent methods to accept messages as their first argument.
v1/client-offset-limit Replaces offset and limit pagination with page and perPage.
v1/client-sdk-types Renames Client SDK Get* types to the List* naming pattern.
v1/client-to-ai-sdk-format Renames toAISdkFormat() to toAISdkStream().
v1/evals-prebuilt-imports Moves prebuilt scorer imports to scorers/prebuilt.
v1/evals-run-experiment Renames runExperiment() to runEvals().
v1/evals-scorer-by-name Renames getScorerByName() to getScorerById().
v1/experimental-auth Renames the experimental_auth Mastra option to auth.
v1/mastra-core-imports Rewrites @mastra/core imports to use package subpaths.
v1/mastra-plural-apis Renames plural Mastra get* APIs to list*.
v1/mcp-get-tools Renames mcp.getTools() to mcp.listTools().
v1/mcp-get-toolsets Renames mcp.getToolsets() to mcp.listToolsets().
v1/memory-message-v2-type Renames MastraMessageV2 to MastraDBMessage.
v1/memory-query-to-recall Renames memory.query() to memory.recall().
v1/memory-readonly-to-options Moves memory.readOnly to memory.options.readOnly.
v1/memory-vector-search-param Renames vectorMessageSearch to vectorSearchString.
v1/runtime-context Renames RuntimeContext and runtimeContext to RequestContext and requestContext.
v1/storage-get-messages-paginated Replaces getMessagesPaginated() with listMessages() and updates pagination.
v1/storage-get-threads-by-resource Renames getThreadsByResourceId() to listThreadsByResourceId().
v1/storage-list-messages-by-id Renames getMessagesById() to listMessagesById().
v1/storage-list-threads-by-resource-to-list-threads Replaces listThreadsByResourceId() with listThreads({ filter: { resourceId } }).
v1/storage-list-workflow-runs Renames getWorkflowRuns() to listWorkflowRuns().
v1/storage-postgres-schema-name Renames the PostgreSQL store's schema option to schemaName.
v1/vector-pg-constructor Converts the PgVector connection string argument to an options object.
v1/voice-property-names Updates legacy agent voice configuration property names.
v1/workflow-create-run-async Renames workflow.createRunAsync() to workflow.createRun().
v1/workflow-get-init-data Adds an explicit type argument to untyped getInitData() calls.
v1/workflow-list-runs Renames workflow.getWorkflowRuns() to workflow.listWorkflowRuns().
v1/workflow-run-count Renames workflow step runCount to retryCount.
v1/workflow-stream-vnext Renames the vNext workflow stream, resume, and observe methods.

For example:

npx @mastra/codemod v1/agent-generate-stream-v-next src/
npx @mastra/codemod v1/runtime-context src/
npx @mastra/codemod v1/workflow-create-run-async src/

CLI options

npx @mastra/codemod <command> [options]
  • --dry previews a transformation without writing files.
  • --print writes transformed source to stdout.
  • --verbose displays detailed transformation output.
npx @mastra/codemod --dry v1/mastra-core-imports src/
npx @mastra/codemod --print v1/mastra-core-imports src/mastra.ts
npx @mastra/codemod --verbose v1/runtime-context src/

Contributing

Create new codemods in src/codemods/<version>, add input and output fixtures under src/test/__fixtures__/, and add the corresponding tests in src/test/. The package includes a scaffold command for generating the boilerplate:

cd packages/codemod
pnpm scaffold

Testing

Run tests from packages/codemod:

pnpm test
pnpm test mastra-core-imports
pnpm test:watch

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.