## Summary
This PR adds CI coverage for the peer-dependency compatibility issue
where a package can compile against the workspace `@mastra/core`, but
publish a peer range that allows older `@mastra/core` versions missing
the runtime exports it imports.
It adds two guardrails:
1. **`@mastra/server` core import check**
- Adds `packages/server/scripts/check-core-imports.ts`.
- Scans runtime named imports from `@mastra/core/*` in
`packages/server/src`.
- Resolves the `@mastra/core` peer dependency floor from
`packages/server/package.json`.
- Downloads that floor version via `npm pack` and checks the imported
runtime symbols against its `.d.ts` surface using `ts.createProgram()`.
- Fails with TypeScript diagnostics when server imports symbols that are
unavailable at the declared peer floor.
2. **Transitive peer dependency validation**
- Extends `scripts/validate-peerdeps.mjs` so packages that depend on
other Mastra packages cannot advertise a broader `@mastra/core` peer
range than their runtime Mastra dependencies require.
- This catches install graphs like `mastra` → `@mastra/deployer` →
`@mastra/server` where the top-level package would otherwise allow an
incompatible older `@mastra/core`.
The PR also aligns affected package peer ranges to `>=1.13.2-0 <2.0.0-0`
and adds a changeset for the published packages whose peer ranges
changed.
## Changed files of note
- `.github/workflows/lint.yml` — runs the server core import check in
`peerdeps-check`.
- `packages/server/scripts/check-core-imports.ts` — new import
compatibility check.
- `scripts/validate-peerdeps.mjs` — adds transitive `@mastra/core` peer
range validation.
- `packages/server/package.json` — adds `check:core-imports` script.
- `.changeset/giant-owls-rule.md` — patch changeset for peer range
updates.
## Validation
Ran locally:
- `pnpm --filter ./packages/server lint`
- `node ./scripts/validate-peerdeps.mjs`
- `pnpm --filter ./packages/server check:core-imports`
Note: `check:core-imports` currently reports the server/runtime import
incompatibilities against the declared `@mastra/core` peer floor. That
is the issue this guardrail is intended to surface in CI instead of
letting it reach users as an install/runtime mismatch.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds automatic safety checks to prevent publishing Mastra
packages with peer dependencies that claim to support older versions of
`@mastra/core` than they actually need. It's like saying "this toy works
with blocks from age 3 onwards" when it really only works with the
improved blocks from age 5. The PR catches this mismatch before
publishing and updates all affected packages to declare the correct
minimum version they require.
## Overview
This PR implements peer dependency compatibility guardrails across the
Mastra monorepo. It introduces runtime import validation for the server
package and transitive peer dependency checking, preventing packages
from advertising overly broad `@mastra/core` peer ranges that would
allow incompatible older versions to be installed.
## Key Changes
### New Runtime Import Validation Script
- **`packages/server/scripts/check-core-imports.ts`** (287 lines): A
TypeScript compatibility checker that scans `packages/server/src` for
non-type-only named imports from `@mastra/core`, extracts the declared
peer dependency floor, downloads that specific floor version, and
validates all imports are available at that version using TypeScript's
type checker. Failures report which imports are unavailable and suggest
updating the peer floor.
### Peer Dependency Validation Extension
- **`scripts/validate-peerdeps.mjs`**: Extended to add transitive peer
dependency validation. Ensures packages depending on other Mastra
packages cannot declare a broader `@mastra/core` peer range than their
runtime Mastra dependencies require, preventing installation graphs that
would allow incompatible older core versions.
### CI Integration
- **`.github/workflows/lint.yml`**: Updated `peerdeps-check` job to
enable dependency installation and run the new `check:core-imports`
check during linting.
### Documentation Update
- **`packages/server/AGENTS.md`**: Added instruction to keep
`check:core-imports` in sync when introducing new `@mastra/core`
imports.
### Configuration
- **`packages/server/package.json`**: Added `check:core-imports` script
invoking the new validation.
## Peer Dependency Updates
A changeset (`.changeset/giant-owls-rule.md`) documents updates to peer
dependency floors across 15+ packages:
- **Deployer packages** (`deployers/cloud`, `deployers/cloudflare`,
`deployers/netlify`, `deployers/vercel`) + `packages/deployer`: Updated
to `>=1.32.0-0 <2.0.0-0`
- **Server adapters** (`server-adapters/express`, `fastify`, `hono`,
`koa`, `nestjs`): Updated to `>=1.32.0-0 <2.0.0-0`
- **Workflow integrations** (`workflows/temporal`): Updated to
`>=1.32.0-0 <2.0.0-0`
- **Editor** (`packages/editor`), **Inngest** (`workflows/inngest`),
**Google Cloud Pub/Sub** (`pubsub/google-cloud-pubsub`): Updated to
`>=1.13.2-0 <2.0.0-0`
- **Observability packages** (Arize, Arthur, Braintrust, Datadog,
Laminar, Langfuse, Langsmith, OTEL Bridge, OTEL Exporter, PostHog,
Sentry): Updated to `>=1.16.0-0 <2.0.0-0`
- **Agent Builder** (`packages/agent-builder`): Updated to `>=1.4.1-0
<2.0.0-0`
- **CLI** (`packages/cli`): Updated to `>=1.32.0-0 <2.0.0-0`
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
## Description
<!-- Provide a brief description of the changes in this PR -->
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
#123 -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works