feat: add @metamask/platform-api-docs package (MetaMask#8012)

## Explanation

Adds `@metamask/platform-api-docs`, a publishable package that generates
and serves a searchable site documenting the Platform API — the catalog
of actions and events available to clients through the message bus.

The package scans TypeScript source and `.d.cts` declaration files,
finds every `*Messenger` type declaration, walks its `Actions` and
`Events` type arguments to discover the capability types they reference,
extracts JSDoc/handler/payload information for each, and renders the
result as a Docusaurus site with per-namespace pages and local search.

### Features

- **Anchored on Messenger declarations.** Extraction discovers
`*Messenger` type aliases and walks `Messenger<Namespace, Actions,
Events>` to find the capability types — eliminating false positives from
unrelated types that happen to share an action/event-like shape.
- **Two capability-type patterns supported.** Inline (`type FooAction =
{ type: '...'; handler: ... }`) and capability-type constructors (`type
FooGetStateAction = ControllerGetStateAction<typeof name, State>`),
including their `interface` variants.
- **Union expansion.** When a Messenger references an umbrella union
like `FooActions = FooGetAction | FooSetAction`, the walker descends
through it without documenting the intermediate alias.
- **Scans three layouts.** Configured `--scan-dir`s, `packages/*/src/`
(`.ts`), and `node_modules/@metamask/*/dist/` (`.d.cts`).
- **Source links resolve automatically.** Reads `git remote get-url
origin` and `git symbolic-ref refs/remotes/origin/HEAD` to build
`https://github.com/<owner>/<repo>/blob/<branch>/<path>#L<line>` URLs;
falls back to `main` for shallow clones.
- **Project label and commit SHA stamped on the site.** `--project-label
Core` / `--project-label Extension` produces titles like `Platform API
(Core)`, and the short Git commit is shown in the intro and navbar so
engineers can tell how current the docs are.
- **Dedup across packages.** When a capability is declared in two places
(e.g. once as the home definition and once as a re-export), the version
with JSDoc and from the matching namespace's package wins.
- **Docusaurus site** with dark/light mode, offline search (no Algolia),
and MDX-safe rendering of JSDoc.

### Usage

From the core monorepo:
```bash
yarn docs:platform-api:build   # Generate docs and build static site
yarn docs:platform-api:dev     # Dev server with hot reload
yarn docs:platform-api:serve   # Build and serve
```

From client projects (Extension, Mobile), install
`@metamask/platform-api-docs` as a devDependency and add a script:
```json
{
  "scripts": {
    "docs:platform-api:build": "platform-api-docs --build --project-label MyProject"
  }
}
```

### Implementation

- **`packages/platform-api-docs/`** — separate workspace from
`@metamask/messenger-cli` (different deps and release cadence).
- **CLI** built with yargs; runs Docusaurus through `execa`. Flags:
`--build`, `--serve`, `--dev`, `--scan-dir` (additive, repeatable),
`--output`, `--project-label`. Configuration is CLI-only — no
`package.json` config block.
- **AST parsing via ts-morph** instead of the raw TypeScript compiler
API. Standard JSDoc extraction (`jsDoc.getDescription()` + `getTags()`)
replaces the previous hand-rolled comment parser.
- **Single-pass extraction.** The Messenger walk returns
`TypeAliasDeclaration`/`InterfaceDeclaration` nodes directly tagged with
`'action'`/`'event'` kind, so the main loop doesn't re-walk the source
file looking up names.
- **File discovery via the `glob` package**, with results sorted for
deterministic output across filesystems.
- **Test coverage**: 100% lines / ~93% branches. Defensive guards
against AST shapes that don't appear in real messenger types are
explicitly marked with `// istanbul ignore` comments.
- **GitHub Actions workflow** (`deploy-platform-api-docs.yml`) builds
docs on PRs (uploads the build as an artifact) and deploys to GitHub
Pages on `main`.

## References

- [WPC-82](https://consensyssoftware.atlassian.net/browse/WPC-82)

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by updating changelogs
for packages I've changed
- [ ] I've introduced breaking changes in this PR and have prepared
draft pull requests for clients and consumer packages to resolve them

[WPC-82]:
https://consensyssoftware.atlassian.net/browse/WPC-82?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Changes are additive (new package, docs tooling, and CI deploy) with
no runtime impact on existing controllers or clients.
> 
> **Overview**
> Introduces **`@metamask/platform-api-docs`**, a new workspace package
that scans TypeScript and `.d.cts` for `*Messenger` types, walks their
`Actions`/`Events` unions, extracts JSDoc and handler/payload shapes
(via **ts-morph**), and emits a **Docusaurus** site with per-namespace
pages, deduplication, and optional GitHub source links.
> 
> The **monorepo** gains root scripts
(`docs:platform-api:build|dev|serve`), README/CODEOWNERS entries,
`.gitignore` for `.platform-api-docs/`, and **eslint/knip** rules for
the new package. **CI** adds `deploy-platform-api-docs.yml` (build on
every run; publish to GitHub Pages under `/platform-api/` on `main` with
`keep_files` and a token-exchange PAT) and wires that job into
**`main.yml`**’s required `all-jobs-complete` gate.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d5fdb00. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Elliot Winkler <elliot.winkler@gmail.com>

Author: cryptodev-2s

.github/CODEOWNERS

@@ -100,6 +100,7 @@
 /packages/multichain-api-middleware        @MetaMask/core-platform
 /packages/permission-controller            @MetaMask/core-platform
 /packages/permission-log-controller        @MetaMask/core-platform
+/packages/platform-api-docs                @MetaMask/core-platform
 /packages/polling-controller               @MetaMask/core-platform
 /packages/preferences-controller           @MetaMask/core-platform
 /packages/rate-limit-controller            @MetaMask/core-platform

.github/workflows/deploy-platform-api-docs.yml

@@ -0,0 +1,92 @@
+name: Deploy Platform API Docs
+
+on:
+  workflow_call:
+
+jobs:
+  build-docs:
+    name: Build Platform API docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout and setup environment
+        uses: MetaMask/action-checkout-and-setup@v3
+        with:
+          is-high-risk-environment: true
+
+      - name: Generate and build Platform API docs
+        # The site is published under the `/platform-api/` subdirectory of
+        # the repo's GitHub Pages site so that other doc sites (e.g.
+        # package API docs) can be hosted alongside under sibling paths.
+        env:
+          REPO_OWNER: ${{ github.repository_owner }}
+          REPO_NAME: ${{ github.event.repository.name }}
+        run: |
+          yarn docs:platform-api:build \
+            --site-url "https://${REPO_OWNER}.github.io" \
+            --site-base-url "/${REPO_NAME}/platform-api/"
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' && 'platform-api-docs-build' || 'platform-api-docs' }}
+          path: .platform-api-docs/build/
+          retention-days: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' && 1 || 7 }}
+
+  get-token:
+    name: Get access token
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment: github-pages
+    permissions:
+      id-token: write
+    outputs:
+      token: ${{ steps.get-token.outputs.token }}
+    steps:
+      - name: Get access token
+        id: get-token
+        uses: MetaMask/github-tools/.github/actions/get-token@v1
+        with:
+          token-exchange-url: ${{ vars.TOKEN_EXCHANGE_URL }}
+          permissions: |
+            contents: write
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs:
+      - build-docs
+      - get-token
+    runs-on: ubuntu-latest
+    environment: github-pages
+    permissions:
+      # Just for the initial `actions/checkout` — the actual push to
+      # `gh-pages` uses the PAT from the `get-token` job, not GITHUB_TOKEN.
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Download build artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: platform-api-docs-build
+          path: build/
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          # Use a PAT obtained via Token Exchange Service rather than the
+          # default `GITHUB_TOKEN`. `GITHUB_TOKEN` can't be granted branch
+          # protections that disallow direct human pushes while still letting
+          # this workflow publish, which is what we want for `gh-pages`.
+          personal_token: ${{ needs.get-token.outputs.token }}
+          publish_dir: ./build
+          destination_dir: platform-api
+          # Preserve sibling subdirectories (e.g. /package-api/) so this
+          # deploy only overwrites /platform-api/.
+          keep_files: true

.github/workflows/main.yml

@@ -77,6 +77,14 @@ jobs:
     needs: check-workflows
     uses: ./.github/workflows/lint-build-test.yml
 
+  deploy-platform-api-docs:
+    name: Deploy Platform API Docs
+    needs: lint-build-test
+    permissions:
+      contents: read
+      id-token: write
+    uses: ./.github/workflows/deploy-platform-api-docs.yml
+
   check-release:
     name: Check release
     needs: check-workflows
@@ -135,6 +143,7 @@ jobs:
     needs:
       - analyse-code
       - check-release
+      - deploy-platform-api-docs
       - lint-build-test
     outputs:
       passed: ${{ steps.set-output.outputs.passed }}

.gitignore

@@ -39,6 +39,9 @@ packages/*/*.tsbuildinfo
 # AI
 .sisyphus/
 
+# Platform API docs (generated)
+.platform-api-docs/
+
 # Agent skills
 # Copy `.skills.local.example` to `.skills.local` and edit `SKILLS_DOMAINS=`.
 .skills.local

README.md

@@ -106,6 +106,7 @@ yarn skills --reset                 # clear saved local selection
 - [`@metamask/permission-log-controller`](packages/permission-log-controller)
 - [`@metamask/perps-controller`](packages/perps-controller)
 - [`@metamask/phishing-controller`](packages/phishing-controller)
+- [`@metamask/platform-api-docs`](packages/platform-api-docs)
 - [`@metamask/polling-controller`](packages/polling-controller)
 - [`@metamask/preferences-controller`](packages/preferences-controller)
 - [`@metamask/profile-metrics-controller`](packages/profile-metrics-controller)
@@ -206,6 +207,7 @@ linkStyle default opacity:0.5
   permission_log_controller(["@metamask/permission-log-controller"]);
   perps_controller(["@metamask/perps-controller"]);
   phishing_controller(["@metamask/phishing-controller"]);
+  platform_api_docs(["@metamask/platform-api-docs"]);
   polling_controller(["@metamask/polling-controller"]);
   preferences_controller(["@metamask/preferences-controller"]);
   profile_metrics_controller(["@metamask/profile-metrics-controller"]);

eslint.config.mjs

@@ -81,6 +81,7 @@ const config = createConfig([
       '.yarn/**',
       'merged-packages/**',
       'scripts/create-package/package-template/**',
+      '.platform-api-docs/**',
     ],
   },
   {
@@ -117,6 +118,7 @@ const config = createConfig([
       '**/tests/**/*.{js,ts}',
       'scripts/*.ts',
       'scripts/create-package/**/*.ts',
+      'packages/platform-api-docs/**/*.ts',
     ],
     extends: [nodejs],
   },
@@ -210,7 +212,7 @@ const config = createConfig([
     },
   },
   {
-    files: ['scripts/*.ts'],
+    files: ['scripts/*.ts', 'packages/platform-api-docs/src/cli.ts'],
     rules: {
       // Scripts may be self-executable and thus have hashbangs.
       'n/hashbang': 'off',
@@ -317,7 +319,10 @@ const config = createConfig([
     },
   },
   {
-    files: ['packages/wallet-cli/src/**/*.test.{js,ts}'],
+    files: [
+      'packages/wallet-cli/src/**/*.test.{js,ts}',
+      'packages/platform-api-docs/**/*.{js,ts}',
+    ],
     rules: {
       'jest/unbound-method': 'off',
       'n/no-process-env': 'off',

knip.config.ts

@@ -136,6 +136,30 @@ const config: KnipConfig = {
     'packages/phishing-controller': {
       ignoreDependencies: ['immer', 'punycode'],
     },
+    'packages/platform-api-docs': {
+      // This package has both a CLI (`src/`) and a Docusaurus site (`site/`).
+      // Scan both so the CLI's deps (e.g. `glob`, `ts-morph`) and the site's
+      // `@docusaurus/*` / `prism-react-renderer` imports in
+      // `docusaurus.config.ts` are seen and neither gets flagged as unused.
+      entry: ['site/docusaurus.config.ts'],
+      project: ['src/**/*.{ts,tsx}', 'site/**/*.{ts,tsx}'],
+      ignoreDependencies: [
+        // Docusaurus runtime and React peers loaded by the framework at build
+        // time; the `docusaurus` binary is invoked via execa, never imported
+        // by source.
+        '@docusaurus/core',
+        '@docusaurus/plugin-content-docs',
+        '@mdx-js/react',
+        'react',
+        'react-dom',
+        // Loaded by docusaurus as a plugin name string (themes[0]); knip
+        // doesn't trace string-referenced plugins.
+        '@easyops-cn/docusaurus-search-local',
+        // Pulled in transitively by `@docusaurus/preset-classic`; pinned here
+        // so the framework's webpack/theme resolution finds a single version.
+        '@docusaurus/theme-common',
+      ],
+    },
     'packages/profile-metrics-controller': {
       ignoreDependencies: ['cockatiel'],
     },

package.json

@@ -22,6 +22,9 @@
     "changelog:validate": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:validate",
     "create-release-branch": "create-release-branch --formatter oxfmt",
     "create-package": "tsx scripts/create-package",
+    "docs:platform-api:build": "yarn workspace @metamask/platform-api-docs cli ../.. --build --project-label Core",
+    "docs:platform-api:dev": "yarn workspace @metamask/platform-api-docs cli ../.. --dev --project-label Core",
+    "docs:platform-api:serve": "yarn workspace @metamask/platform-api-docs cli ../.. --serve --project-label Core",
     "lint": "yarn lint:eslint && echo && yarn lint:misc --check && yarn constraints && yarn lint:dependencies && yarn lint:teams && yarn messenger-action-types:check && yarn readme-content:check",
     "lint:dependencies": "knip --dependencies && yarn dedupe --check",
     "lint:dependencies:fix": "knip --dependencies && yarn dedupe",

packages/platform-api-docs/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release of the platform-api-docs package ([#8012](https://github.com/MetaMask/core/pull/8012))
+
+[Unreleased]: https://github.com/MetaMask/core/

packages/platform-api-docs/LICENSE

@@ -0,0 +1,6 @@
+This project is licensed under either of
+
+ * MIT license ([LICENSE.MIT](LICENSE.MIT))
+ * Apache License, Version 2.0 ([LICENSE.APACHE2](LICENSE.APACHE2))
+
+at your option.