0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
Commit graph

6 commits

Author SHA1 Message Date
mastra-platform[bot]
0893940ca2
fix(docs): generate SOURCE_MAP.json from public export names (#29328)
Co-authored-by: Lennart <lekoarts@gmail.com>
2026-11-04 09:58:46 -08:00
Caleb Barnes
2456d7d9bc
fix(ci): don't fail prepack docs generation in E2E tests (#12906)
## Summary

- PR #12836 moved docs generation from build-time to `prepack` hooks.
This causes E2E tests to fail because they publish packages to a local
Verdaccio registry, which triggers `prepack`, and the script hard-fails
in CI when `docs/build/llms-manifest.json` is missing.
- Replace the broad `process.env.CI` check with
`process.env.REQUIRE_PACKAGE_DOCS`, which is only set in
`npm-publish.yml` publish steps
- E2E tests and local dev now gracefully skip docs generation when the
manifest is missing, while real npm publishes still enforce it

## Test plan

- [ ] E2E tests (create-mastra, commonjs, no-bundling, monorepo) should
pass in CI now that prepack doesn't hard-fail
- [ ] npm-publish workflow still enforces docs generation via
`REQUIRE_PACKAGE_DOCS` env var

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Chores**
* Updated npm publish workflow to enforce package documentation
generation as a required step.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: CalebBarnes <CalebBarnes@users.noreply.github.com>
2026-02-10 15:01:18 -08:00
Eric Pinzur
d62462e646
Decouple package docs generation from build task (#12836)
## 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 -->
2026-02-10 14:22:14 +01:00
Lennart
6efbaa9bd8
chore(repo): Improve embedded docs script (#12664)
## 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 -->
2026-02-04 16:24:43 -08:00
Ehindero Israel
4de95eabbf
fix: check if chunk path is a file before reading in findExportLine (#11509) 2025-12-31 12:45:45 +01:00
Ehindero Israel
bc72b529ee
feat: embedded documentation for AI coding agents (#11472)
## Summary

Enables Mastra packages to ship embedded documentation that AI coding
agents can read directly from `node_modules`. This allows agents to
understand the framework as if they were its creators.

## What's Included

### Infrastructure
- **`scripts/generate-package-docs.ts`** - Shared script to generate
docs from MDX sources
- **`SOURCE_MAP.json`** - Machine-readable index mapping exports → types
→ implementation (with line numbers)
- **`SKILL.md`** - Claude Skills entry point for automatic discovery
- **`EMBEDDED_DOCS.md`** - Guide for adding embedded docs to any package

### Package Coverage (47 packages)
- **Core:** memory, rag, evals, mcp, server, auth, deployer, cli,
client-js, loggers
- **Voice:** 13 providers (openai, deepgram, elevenlabs, etc.)
- **Stores:** 22 providers (pg, libsql, pinecone, etc.)

Each package gets:
- `docs.config.json` - Topic/source file mappings
- `postbuild` script - Auto-generates `dist/docs/` after build

## How It Works

1. MDX docs are transformed to clean Markdown (Docusaurus components
stripped, code blocks preserved)
2. Code references are auto-discovered from imports/usage and linked to
SOURCE_MAP
3. Docs are generated to `dist/docs/` on every build
4. Published to npm alongside the package

## Example Output
node_modules/@mastra/core/dist/docs/
├── SKILL.md # Agent entry point
├── README.md # Navigation
├── SOURCE_MAP.json # Export → file mappings
├── agents/
 │ ├── 01-overview.md
 │ └── ...
└── tools/
└── ...


## Related

- Follow-up PR for MCP tools: #11488

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Embedded package documentation is now automatically generated and
included in published npm packages, making documentation accessible
directly within package distributions and enabling integration with AI
tools and Claude Skills.

* **Documentation**
* Added comprehensive embedded documentation guide for generating and
integrating documentation from source files into package distributions.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2025-12-30 16:39:28 -08:00