feat: add file-system routed studio config (studio.ts singleton)

[devin-ai-integration]

Description

Extends the file-system routing pipeline to discover a studio.ts singleton file under the mastra directory and register it on the Mastra instance. This is the fifth PR in a stack that removes the need for new Mastra() when users fully embrace the file-based paradigm.

Stacked on #18888 (file-based server).

Changes

Core (packages/core/src/mastra/index.ts):

• Added #studioExplicit flag — set when user passes studio to new Mastra({studio})
• Added __registerFsStudio(fsStudio) — calls setStudio() only if no explicit studio config was provided; otherwise logs a warning (code wins)

Codegen (codegen.ts):

// Generated entry now includes:
import __fsStudio from "/path/to/studio.ts";
if (__userEntry.mastra && typeof __userEntry.mastra.__registerFsStudio === 'function') {
  __userEntry.mastra.__registerFsStudio(__fsStudio);
}

Prepare (prepare.ts):

• Discovers studio alongside agents/workflows/storage/observability/server in parallel
• hasStudio: boolean added to PrepareFsAgentsEntryResult

Full file-based project structure now supported

With this PR, the complete set of infrastructure singletons is discoverable:

src/mastra/
  storage.ts          → PR #18885
  observability.ts    → PR #18887
  server.ts           → PR #18888
  studio.ts           → this PR
  agents/             → already works
  workflows/          → PR #18883

Related issue(s)

Part of the file-based primitives MVP stack (eliminates new Mastra() boilerplate).

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
• I have addressed all Coderabbit comments on this PR

Link to Devin session: https://app.devin.ai/sessions/b9e3b35378b54413b9931e8f2499ab8c

ELI5

This PR teaches Mastra to notice a new studio.ts file in the mastra folder and wire it up automatically. That means people can keep more of their app in files instead of hand-writing setup code, while still letting an explicitly configured studio win if both exist.

What changed

• Added studio.ts file-system routing support in @mastra/core.
• Mastra now tracks whether studio was set directly in the constructor.
• Added __registerFsStudio() to register a discovered studio config only when one wasn’t explicitly provided.
• Updated fs-routing codegen to import and register studio.ts in generated wrappers.
• Extended fs-routing preparation to discover studio.ts alongside agents, workflows, storage, and observability.
• Added tests for studio discovery, wrapper generation, and precedence behavior.
• Updated the changeset to mark @mastra/core and @mastra/deployer for minor release.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mastra-docs-1.x	Ready	Preview, Comment	Jul 6, 2026 2:04pm
mastra-playground-ui	Ready	Preview, Comment	Jul 6, 2026 2:04pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
mastra-studio-preview	Ignored	Preview	Jul 6, 2026 2:04pm

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 13 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: dcb06ae1-789e-426f-9a51-46d18634518f

📥 Commits

Reviewing files that changed from the base of the PR and between 22bec18 and f47c342.

📒 Files selected for processing (5)

• .changeset/tidy-nails-repeat.md
• packages/core/src/mastra/index.ts
• packages/deployer/src/build/fs-routing/codegen.ts
• packages/deployer/src/build/fs-routing/fs-routing.test.ts
• packages/deployer/src/build/fs-routing/prepare.ts

Walkthrough

This PR adds support for a file-system routed studio.ts singleton. A new __registerFsStudio method on the Mastra class registers fs-discovered studio config, deferring to an explicitly code-configured studio when present. Fs-routing discovery and codegen are extended to detect and wire up studio.ts.

Changes

Studio singleton auto-registration

Layer / File(s)	Summary
Mastra core studio registration API packages/core/src/mastra/index.ts	Adds #studioExplicit flag set in the constructor and new __registerFsStudio(fsStudio) method that warns and preserves explicit config or applies the fs-discovered studio via setStudio.
Fs-routing discovery and codegen for studio.ts packages/deployer/src/build/fs-routing/codegen.ts, packages/deployer/src/build/fs-routing/prepare.ts	generateFsAgentsModule gains a studio option to import and register __fsStudio; prepareFsAgentsEntry discovers studio.ts, updates the no-primitives check, passes studio to codegen, and returns hasStudio in its result with updated JSDoc.
Tests and changeset for studio feature packages/deployer/src/build/fs-routing/fs-routing.test.ts, .changeset/tidy-nails-repeat.md	New tests cover studio import/registration in codegen and prepare flows, an existing test is updated with hasStudio: false, and a changeset documents the minor version bump and feature.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• mastra-ai/mastra#18694: Modifies the same prepareFsAgentsEntry/wrapper generation pipeline in fs-routing.
• mastra-ai/mastra#18883: Extends generateFsAgentsModule with similar singleton registration pattern (__registerFsWorkflows).

Suggested labels: complexity: medium

Suggested reviewers: wardpeet, TheIsrael1, LekoArts, NikAiyer, abhiaiyer91

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding filesystem-routed studio config support via studio.ts.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devin/1783072614-fs-studio

---

_{Comment @coderabbitai help to get the list of available commands.}

[dane-ai-mastra]

PR triage

Linked issue check skipped for excluded profile @devin-ai-integration[bot].

---

PR complexity score

Factor	Value	Score impact
Files changed	5	+10
Lines changed	112	+6
Author merged PRs	209	-20
Test files changed	Yes	-10
Final score		-14

Applied label: complexity: low

---

Changed test gate

Changed tests failed against the base branch as expected.

Label: tests: green ✅

[changeset-bot]

🦋 Changeset detected

Latest commit: f47c342

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 22 packages

Name	Type
@mastra/deployer	Minor
@mastra/core	Minor
@mastra/temporal	Patch
mastracode	Patch
@mastra/mcp-docs-server	Patch
@internal/playground	Patch
@mastra/client-js	Patch
@mastra/opencode	Patch
@mastra/longmemeval	Patch
mastra	Patch
@mastra/deployer-cloud	Minor
@mastra/react	Patch
@mastra/playground-ui	Patch
@mastra/server	Minor
create-mastra	Patch
@mastra/express	Patch
@mastra/fastify	Patch
@mastra/hono	Patch
@mastra/koa	Patch
@mastra/nestjs	Patch
@mastra/next	Patch
@mastra/tanstack-start	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

.changeset/tidy-nails-repeat.md (1)

1-7: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Add a short code example for this new feature.

The entry describes a new public-facing convention (studio.ts auto-discovery) but doesn't show what the file looks like. As per path instructions, "If the change is a breaking change or is adding a new feature, ensure that a short code example is provided. This code example should show the public API usage."

📝 Suggested addition

 Added file-system routed studio config singleton. Place a studio.ts file in your mastra directory that default-exports a StudioConfig object, and it will be auto-discovered and registered when running mastra dev or mastra build. Code-registered studio config takes precedence if both are present.
+
+```ts
+// mastra/studio.ts
+import type { StudioConfig } from '`@mastra/core`';
+
+export default {
+  auth: new MastraAuthStudio(),
+} satisfies StudioConfig;
+```

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.changeset/tidy-nails-repeat.md around lines 1 - 7, The changeset entry for
the new studio.ts auto-discovery feature is missing a short public API example.
Update the markdown content to include a concise code snippet showing the
expected default export from a studio.ts file in the Mastra directory, using the
StudioConfig type and a realistic exported config object so users can see how to
adopt the feature.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In @.changeset/tidy-nails-repeat.md:
- Around line 1-7: The changeset entry for the new studio.ts auto-discovery
feature is missing a short public API example. Update the markdown content to
include a concise code snippet showing the expected default export from a
studio.ts file in the Mastra directory, using the StudioConfig type and a
realistic exported config object so users can see how to adopt the feature.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ba55ff57-8bba-462b-b411-b724eb43c610

📥 Commits

Reviewing files that changed from the base of the PR and between 9f169f0 and 22bec18.

📒 Files selected for processing (5)

• .changeset/tidy-nails-repeat.md
• packages/core/src/mastra/index.ts
• packages/deployer/src/build/fs-routing/codegen.ts
• packages/deployer/src/build/fs-routing/fs-routing.test.ts
• packages/deployer/src/build/fs-routing/prepare.ts