Enables `no-else-return: error` in the root Oxlint config and removes
186 redundant `else` branches across 111 source/test files. Existing
rule defaults are retained.
Reviewed every code diff for behavior preservation. An independent
TypeScript AST comparison confirms that changes are limited to removing
`else` after returning branches, with the same expressions, statement
order, return values, and `try`/`catch`/`finally` boundaries. All
181,158 identifier occurrences retain their bindings. The recorder
replay path keeps an explicit block: flattening it would shadow the
earlier request `body` with the response `body` and introduce a
temporal-dead-zone error.
Extends the existing monorepo optimized-dependency test to assert that a
raw TypeScript workspace package, including its enum and transitive
dependency, still executes in the production bundle.
Validation: the root rule-only scan passes on 15,273 files with zero
diagnostics; formatting and `git diff --check` pass. Schema
compatibility tests: 1,060 passed, 9 skipped. Recorder runtime tests: 21
passed. The core selection initially passed 3,513 tests; rerunning the
suites requiring local server/cache access passed 185 tests, with one
remaining cache-file assertion also reproduced on unchanged `main`.
Remaining validation limits: four asset-download cases cannot reach
`placehold.co`; the changed-file lint run reports six import-order
errors reproduced on unchanged files from `main`. Deployer unit tests
and the monorepo test could not run because this checkout lacks required
package dependencies (`fs-extra`/workspace links and `get-port`,
respectively). These limits are left visible for CI. No changeset is
included because this is a behavior-preserving lint cleanup.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR makes the code easier to read by removing `else` branches that
are not needed after a return. It also enables a rule that catches those
branches and adds a test for loading a raw TypeScript workspace package
in a production bundle.
## Summary
- Enables Oxlint’s `no-else-return` rule at error severity and removes
186 redundant `else` branches across 111 files.
- Extends the monorepo optimized-dependencies test to check a raw
TypeScript workspace package, its enum, and a transitive dependency.
- Updates the deployer’s transpile-package path pattern.
- In workflow event processing, a truthy branch index with no matching
child now falls through to publish a skipped-step end event. Previously,
this case published no event.
- Keeps the recorder replay block explicit to avoid request/response
`body` shadowing and a temporal-dead-zone error.
## Validation
Reported checks passed: the rule-only scan across 15,273 files,
formatting, `git diff --check`, schema compatibility tests (1,060
passed, 9 skipped), recorder runtime tests (21 passed), and an initial
core test selection (3,513 passed).
Some test limits remain. Four asset-download cases could not reach
`placehold.co`. Changed-file lint reported six import-order errors that
also occur on unchanged files from `main`. Deployer unit tests and the
monorepo test could not run because dependencies were unavailable. On
rerun, suites requiring local server/cache access had 185 passes; one
cache-file assertion also reproduced on unchanged `main`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- Make `generateTypes` always validate generated declaration imports
against runtime dependencies, removing the opt-in
`validateRuntimeImports` option from all package tsup configs.
- Fix bundled declaration handling so API Extractor sees `.d.ts`
references instead of copied `.js` export targets.
- Align `@internal/external-types` bundled packages and metadata so its
generated rollup passes API Extractor.
## Test plan
- `node --check packages/_types-builder/src/index.js && node --check
packages/_types-builder/src/replace-types.js`
- `pnpm --filter @internal/external-types build:lib`
- `pnpm --filter @internal/external-types build`
- `pnpm --filter @internal/external-types lint`
- `pnpm --filter @mastra/fastembed build`
- `git diff --check`
## Notes
- `pnpm --filter @internal/external-types test` was not run because the
package has no matching test files.
- CodeRabbit CLI was available, but `coderabbit review --type
uncommitted --plain --no-color` timed out after 180s before returning
findings.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR makes TypeScript type validation **always happen** when building
packages, instead of being something teams could skip. It's like having
a mandatory safety check that ensures all the type information a package
exports only references dependencies it actually has—preventing broken
imports and confusing errors for users of the package.
## Summary
The PR enforces mandatory validation of generated TypeScript
declarations (`.d.ts` files) against runtime dependencies by removing
the optional `validateRuntimeImports` flag. All packages now always
validate their generated types.
## Key Changes
### Declaration Validation System
- **`packages/_types-builder/src/index.js`** (+116 lines) – Implements
`validateDeclarationRuntimeImports()` that scans generated `.d.ts` files
and rejects any import/export statements referencing packages not in the
package's `dependencies`, `peerDependencies`, `optionalDependencies`, or
bundled packages. Adds regex-based import specifier parsing, Node
built-in module detection, and error consolidation. Validates that all
type declarations only reference declared dependencies.
- **`packages/_types-builder/src/replace-types.js`** (+207 lines) –
Replaced streaming substring search with ts-morph-based declaration
rewriting. Now parses declarations to collect module specifiers from
import/export statements and `import("...")` type expressions, resolves
bundled package declarations using `resolve.exports` with `@types/*`
fallback, and copies resolved declarations into `dist/_types/<pkg>` with
rewritten module specifiers instead of appending `.js` extensions.
### Build Configuration Updates
- **122 `tsup.config.ts` files** across all package types (auth,
deployers, integrations, observability, stores, voice, workflows,
workspaces, client-sdks) – Updated `onSuccess` hooks to call
`generateTypes(process.cwd(), new Set())` or
`generateTypes(process.cwd(), new Set([packages]))` with explicit
dependency/bundled package sets instead of relying on defaults. This
removes the implicit `validateRuntimeImports` opt-in pattern.
### Bundled Package Declaration Handling
- **`packages/_external-types/api-extractor.json`** – Expanded
`bundledPackages` array to include `@ai-sdk/provider-utils`,
`@ai-sdk/ui-utils`, `@standard-schema/spec`, `eventsource-parser`,
`json-schema`, and `@opentelemetry/api` alongside `ai`.
- **`packages/_external-types/tsup.config.ts`** – Explicitly lists
bundled packages in `generateTypes()` call for proper type generation
and validation.
- **`packages/_external-types/src/index.ts`** – Added `@public` JSDoc
tag to `ProviderDefinedTool`.
### Dependency Adjustments
- **Auth packages** – Added `@mastra/core` peer dependency (`>=1.0.0-0
<2.0.0-0` or `>=1.32.0-0 <2.0.0-0`); some added `hono` peer dependency
(`^4.0.0`).
- **`packages/deployer/package.json`** – Moved `@hono/node-server` and
`@mastra/hono` from `devDependencies` to `dependencies`.
- **`packages/fastembed/tsup.config.ts`** – Updated to include
`@internal/ai-sdk-v4`, `@internal/ai-sdk-v5`, `@internal/ai-v6` in type
generation.
- **`packages/core/tsup.config.ts`** – Expanded dependency allowlist to
include `@ai-sdk/*`, `eventsource-parser`, and internal packages.
- **`packages/mcp/tsup.config.ts`** – Updated to generate types for
`hono` and `hono-mcp-server-sse-transport`.
- **`packages/schema-compat/package.json`** – Moved
`@standard-schema/spec`, `ajv`, `@types/json-schema` from
`devDependencies` to `dependencies`.
- **`packages/server/package.json`** – Moved `@mastra/schema-compat`
from `devDependencies` to `dependencies`.
- **`packages/_external-types/package.json`** – Added dev dependencies
for `@ai-sdk/ui-utils`, `@opentelemetry/api`, `@standard-schema/spec`,
`eventsource-parser`, `json-schema`.
- **Store packages** – Several added `zod` peer dependency (`^3.25.0 ||
^4.0.0`).
- **Server adapter packages** – `nestjs` added `zod` peer dependency;
`hono` added `hono` peer dependency; `server-adapters/hono/package.json`
added explicit `hono: ^4.12.8` peer dependency.
- **`deployers/netlify/package.json`** – Added `rollup` dependency
(`^4.0.0`).
- **`voice/cloudflare/package.json`** – Moved
`@cloudflare/workers-types` from `devDependencies` to `dependencies`.
- **`client-sdks/react/package.json`** – Added `@ai-sdk/react` and
`@assistant-ui/react` peer dependencies.
- **`stores/cloudflare-d1/package.json`** – Added
`@cloudflare/workers-types` peer dependency.
- **`observability/mastra/package.json`** – Added `zod` peer dependency.
### Path Resolution Updates
- **`client-sdks/react/src/agent/hooks.ts`** – Changed from `@/lib/...`
aliases to relative `../lib/...` imports.
- **`client-sdks/react/src/mastra-react-provider.tsx`** – Changed from
`@/` alias to relative path for `mastra-client-context` imports.
### Type Validation in MCP
- **`packages/mcp/src/server/server.ts`** – Made
`tool.parameters.validate()` and `tool.outputSchema.validate()` calls
awaited to handle async validators.
### JSON Schema Adapter
-
**`packages/schema-compat/src/standard-schema/adapters/json-schema.ts`**
– Updated Ajv import from `ajv/dist/2020` to `ajv/dist/2020.js`.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16752?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
## Summary
- Moved docs generation from build-time to pack-time using npm's
`prepack` lifecycle hook across all 46 packages that embed documentation
into their dist
- Removed the `build:docs` turbo task and `build:package-docs` root
script entirely
- Made `generate-package-docs.ts` exit gracefully when the docs manifest
is missing
No changeset required
## Motivation
The `build:docs` task in each package depends on `mastra-docs#build` (a
full Docusaurus site build), which in turn runs `git log` for the
sitemap plugin. This meant:
1. Every `pnpm build` required a git repository — builds failed outside
of git repos (in sandboxes)
2. Every package depending on `@mastra/core` transitively triggered a
full docs site build — e.g., `build:observability` pulled in the entire
Docusaurus build via `@mastra/core#build` → `build:docs` →
`mastra-docs#build`
3. Dev builds were slower than necessary — compiling docs that are only
needed at publish time
### What changed
* **`package.json` (46 files across packages/, stores/, voice/,
client-sdks/)**
Replaced `build:docs` (or `postbuild` in voice packages) with `prepack`,
so docs generation only runs during `npm pack`/`npm publish` — never
during regular builds.
Before (packages/stores):
```
"build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
Before (voice packages):
```
"postbuild": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
Before (CLI — embedded in build:lib):
```
"build:lib": "tsup --silent --config tsup.config.ts && pnpx tsx
../../scripts/generate-package-docs.ts"
```
After (all packages):
```
"prepack": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
* **`turbo.json` (34 files — root + 33 packages)**
Removed the `build:docs` task definition entirely. It's no longer a
turbo task — docs generation is handled by the npm `prepack` lifecycle
instead.
* **`package.json` (root)**
Removed:
```
"build:package-docs": "pnpm turbo run build:docs"
```
* **`.github/workflows/npm-publish.yml`**
Removed all `pnpm build:package-docs` steps from prerelease, stable, and
exit-prerelease-mode flows. No longer needed — `prepack` fires
automatically during `pnpm publish -r`.
* **`scripts/generate-package-docs.ts`**
Changed error handling to exit gracefully (warn instead of crash) when
`docs/build/llms-manifest.json` is missing. This ensures `prepack`
doesn't block packaging when the docs site hasn't been built (e.g.,
local development, snapshots).
## Test plan
- Verify `pnpm build` succeeds without triggering docs generation
- Verify `pnpm pack` in a package with the docs site built generates
embedded docs via `prepack`
- Verify `pnpm pack` without the docs site built warns but doesn't fail
- Verify CI publish workflows still produce packages with embedded docs
(prepack fires during `pnpm publish -r`)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Docs generation now runs automatically during package preparation
(prepack) instead of as part of the main build.
* Removed separate docs build tasks to simplify and streamline build
dependency graphs across packages.
* **Bug Fixes**
* Improved docs generator error handling: failures fail CI but surface
as warnings locally to avoid blocking development.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
This PR reorganizes the test infrastructure across the monorepo by
introducing namespaced Vitest projects, proper test classification, and
a dedicated e2e CI job.
### Vitest project namespacing
- Rename all vitest project names from generic `'unit'` to
`'unit:<package-path>'` (e.g. `'unit:packages/core'`,
`'unit:auth/auth0'`) across ~100 packages
- Enables targeted test filtering with `--project 'unit:*'` glob
patterns in CI and locally
- Update CI workflow to use `'unit:*'` and `'typecheck:*'` patterns
### Test classification
- **Store tests** → `e2e:stores/*` (require external services like
Postgres, Redis, etc.)
- **RAG tests** → `e2e:packages/rag` (require embeddings API)
- **Evals LLM scorer tests** → `e2e:packages/evals` (require LLM API
keys)
- **pubsub tests** → `e2e:pubsub/*` (require Google Cloud)
- Add `isolate: false` to unit test configs for faster execution
### Core test reorganization
Split `agent.test.ts` (~7.5k lines) into focused unit test modules:
- `callbacks.test.ts` — callback/hook behavior
- `input-processors.test.ts` — input processing logic
- `instructions.test.ts` — instruction/system prompt handling
- `memory-metadata.test.ts` — memory metadata tests
- `save-and-errors.test.ts` — save behavior and error handling
- `title-generation.test.ts` — title generation logic
Renamed integration tests to `*.e2e.test.ts` for clarity (e.g.
`azure.integration.test.ts` → `azure.e2e.test.ts`).
### CI changes
- Add dedicated `e2e-test` job in `vitest-changed.yml` with shard-based
matrix
- Normalize shard names (`/` → `-`) for GitHub artifact compatibility
- Wire e2e job into `merge-reports` dependency chain
### Test fixes
- `tsx` → `tsx@latest` in MCP spawn calls to fix version resolution
- Rewrite `deployers/cloud` mock patterns for test reliability
- Skip network-dependent `mcp-registry-registry` tests (apitracker,
mcprun)
- Fix codemod `typeParameters` compatibility check
- Add `cwd` to CLI execa call
### Test plan
- Verified `pnpm vitest run --project 'unit:*'` runs only unit tests
- Verified `pnpm vitest run --project 'e2e:*'` runs only e2e tests
- Verified all extracted agent test files pass independently
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Tests**
* Added comprehensive test suites for agent features including
callbacks, input processors, instructions, memory handling, and title
generation across v1 and v2 implementations
* Reorganized test infrastructure with dedicated end-to-end test
workflows separate from unit tests
* Enhanced test isolation and parallel execution with named test
projects
* **Chores**
* Restructured test configuration across all packages for improved
organization and execution
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Mastra Code <noreply@mastra.ai>
## Description
Improve the `generate-package-docs.ts` script by using the new
`llms-manifest.json` from docs to copy over llms.txt files to the
embedded docs (previously the raw MDX was parsed and assembled).
This PR also updates the script to be run without any cli args, it just
runs in the current `process.cwd()` context. This simplifies usage when
running via `npm` scripts. This PR also improves the performance of the
`SOURCE_MAP.json` generation by 2x.
Lastly, the `dist/docs` structure itself is updated to follow the agent
skills spec.
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes#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
- [X] 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
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Docs generation moved to a centralized, manifest-driven workflow;
package-level doc scripts simplified to rely on contextual discovery and
a central docs build.
* Build tasks updated across packages to depend on the centralized docs
build step.
* **Documentation**
* Replaced a lengthy proposal with a concise Turbo-focused guide and
added optional description metadata for doc entries.
* **Bug Fix**
* Removed noisy console warnings during docs site initialization.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->