feat: add @metamask/platform-api-docs package

.github/CODEOWNERS

@@ -83,6 +83,7 @@
 /packages/error-reporting-service      @MetaMask/core-platform
 /packages/eth-json-rpc-middleware      @MetaMask/core-platform
 /packages/messenger                    @MetaMask/core-platform
+/packages/messenger-docs               @MetaMask/core-platform
 /packages/sample-controllers           @MetaMask/core-platform
 /packages/polling-controller           @MetaMask/core-platform
 /packages/preferences-controller       @MetaMask/core-platform

.github/workflows/messenger-docs.yml

@@ -0,0 +1,60 @@
+name: Messenger API Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    name: Build Messenger API docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup environment
+        uses: MetaMask/action-checkout-and-setup@v2
+        with:
+          is-high-risk-environment: false
+
+      - name: Generate and build Messenger docs
+        run: yarn docs:messenger:build
+        env:
+          DOCS_URL: https://${{ github.repository_owner }}.github.io
+          DOCS_BASE_URL: /${{ github.event.repository.name }}/
+
+      - name: Upload build artifact (PR)
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          name: messenger-api-docs
+          path: .messenger-docs/build/
+          retention-days: 7
+
+      - name: Upload Pages artifact (main)
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .messenger-docs/build/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -34,4 +34,12 @@ scripts/coverage
 !.yarn/versions
 
 # typescript
-packages/*/*.tsbuildinfo
+packages/*/*.tsbuildinfo
+
+# Messenger API docs (generated)
+.messenger-docs/
+
+# Emacs
+\#*\#
+.#*
+.~

README.md

@@ -65,6 +65,7 @@ Each package in this repository has its own README where you can find installati
 - [`@metamask/logging-controller`](packages/logging-controller)
 - [`@metamask/message-manager`](packages/message-manager)
 - [`@metamask/messenger`](packages/messenger)
+- [`@metamask/messenger-docs`](packages/messenger-docs)
 - [`@metamask/multichain-account-service`](packages/multichain-account-service)
 - [`@metamask/multichain-api-middleware`](packages/multichain-api-middleware)
 - [`@metamask/multichain-network-controller`](packages/multichain-network-controller)
@@ -148,6 +149,7 @@ linkStyle default opacity:0.5
   logging_controller(["@metamask/logging-controller"]);
   message_manager(["@metamask/message-manager"]);
   messenger(["@metamask/messenger"]);
+  messenger_docs(["@metamask/messenger-docs"]);
   multichain_account_service(["@metamask/multichain-account-service"]);
   multichain_api_middleware(["@metamask/multichain-api-middleware"]);
   multichain_network_controller(["@metamask/multichain-network-controller"]);

eslint.config.mjs

@@ -15,6 +15,8 @@ const config = createConfig([
       'merged-packages/**',
       '.yarn/**',
       'scripts/create-package/package-template/**',
+      '.messenger-docs/**',
+      'packages/messenger-docs/template/**',
     ],
   },
   {
@@ -43,9 +45,18 @@ const config = createConfig([
       '**/tests/**/*.{js,ts}',
       'scripts/*.ts',
       'scripts/create-package/**/*.ts',
+      'packages/messenger-docs/src/**/*.ts',
     ],
     extends: [nodejs],
   },
+  {
+    files: ['packages/messenger-docs/src/cli.ts'],
+    rules: {
+      // The bin field points to dist/cli.mjs but the source is src/cli.ts.
+      // Without convertPath, n/hashbang cannot correlate the two.
+      'n/hashbang': 'off',
+    },
+  },
   {
     files: ['**/*.{js,cjs}'],
     languageOptions: {
@@ -125,7 +136,7 @@ const config = createConfig([
     },
   },
   {
-    files: ['scripts/*.ts'],
+    files: ['scripts/**/*.ts'],
     rules: {
       // Scripts may be self-executable and thus have hashbangs.
       'n/hashbang': 'off',

package.json

@@ -21,6 +21,10 @@
     "changelog:update": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:update",
     "changelog:validate": "yarn workspaces foreach --all --no-private --parallel --interlaced --verbose run changelog:validate",
     "create-package": "tsx scripts/create-package",
+    "docs:messenger:build": "yarn workspace @metamask/messenger-docs docs:build",
+    "docs:messenger:dev": "yarn workspace @metamask/messenger-docs docs:dev",
+    "docs:messenger:generate": "yarn workspace @metamask/messenger-docs docs:generate",
+    "docs:messenger:serve": "yarn workspace @metamask/messenger-docs docs:serve",
     "generate-method-action-types": "yarn workspaces foreach --all --parallel --interlaced --verbose run generate-method-action-types",
     "lint": "yarn lint:eslint && echo && yarn lint:misc --check && yarn constraints && yarn lint:dependencies && yarn lint:teams && yarn generate-method-action-types --check",
     "lint:dependencies": "depcheck && yarn dedupe --check",
@@ -45,7 +49,11 @@
   },
   "resolutions": {
     "elliptic@6.5.4": "^6.5.7",
+    "eslint-import-resolver-typescript": "3.7.0",
+    "eslint-plugin-import-x": "4.6.1",
+    "eslint-plugin-n": "17.15.1",
     "fast-xml-parser@^4.3.4": "^4.4.1",
+    "prettier@npm:^3.3.3": "3.4.2",
     "ws@7.4.6": "^7.5.10"
   },
   "devDependencies": {
@@ -107,9 +115,10 @@
       "@lavamoat/preinstall-always-fail": false,
       "@keystonehq/bc-ur-registry-eth>hdkey>secp256k1": true,
       "babel-runtime>core-js": false,
+      "eslint-import-resolver-typescript>unrs-resolver": false,
+      "eslint-plugin-import-x>unrs-resolver": false,
       "simple-git-hooks": false,
-      "tsx>esbuild": false,
-      "eslint-plugin-import-x>unrs-resolver": false
+      "tsx>esbuild": false
     }
   }
 }

packages/messenger-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 messenger-docs package
+
+[Unreleased]: https://github.com/MetaMask/core/

packages/messenger-docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/messenger-docs/README.md

@@ -0,0 +1,82 @@
+# `@metamask/messenger-docs`
+
+Generate and serve Messenger API documentation for MetaMask controller packages.
+
+Scans TypeScript source files and declaration files for messenger action/event types, then generates a searchable Docusaurus site with per-namespace documentation.
+
+## Installation
+
+`yarn add @metamask/messenger-docs`
+
+or
+
+`npm install @metamask/messenger-docs`
+
+## Usage
+
+### Core monorepo
+
+The package includes workspace scripts for development:
+
+```bash
+# Generate docs from all packages
+yarn workspace @metamask/messenger-docs docs:generate
+
+# Generate + start dev server with hot reload
+yarn workspace @metamask/messenger-docs docs:dev
+
+# Generate + build static site
+yarn workspace @metamask/messenger-docs docs:build
+
+# Generate + build + serve
+yarn workspace @metamask/messenger-docs docs:serve
+```
+
+### Client projects (Extension, Mobile)
+
+Add `@metamask/messenger-docs` as a dev dependency, then add a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:messenger": "messenger-docs --serve"
+  }
+}
+```
+
+By default, the tool scans `src/` for `.ts` files and `node_modules/@metamask/` for `.d.cts` declaration files. If your project has source files in other directories, configure `scanDirs` in `package.json`:
+
+```json
+{
+  "messenger-docs": {
+    "scanDirs": ["app", "src"]
+  }
+}
+```
+
+Or pass `--scan-dir` flags:
+
+```bash
+messenger-docs --scan-dir app --scan-dir shared --serve
+```
+
+### CLI options
+
+```
+messenger-docs [project-path] [options]
+
+Arguments:
+  project-path      Path to the project to scan (default: current directory)
+
+Options:
+  --build           Generate docs and build static site
+  --serve           Generate docs, build, and serve static site
+  --dev             Generate docs and start dev server with hot reload
+  --scan-dir <dir>  Extra source directory to scan (repeatable)
+  --output <dir>    Output directory (default: <project-path>/.messenger-docs)
+  --help            Show this help message
+```
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

packages/messenger-docs/jest.config.js

@@ -0,0 +1,29 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+const merge = require('deepmerge');
+const path = require('path');
+
+const baseConfig = require('../../jest.config.packages');
+
+const displayName = path.basename(__dirname);
+
+module.exports = merge(baseConfig, {
+  // The display name when running multiple projects
+  displayName,
+
+  // Allow running without any test files
+  passWithNoTests: true,
+
+  // An object that configures minimum threshold enforcement for coverage results
+  coverageThreshold: {
+    global: {
+      branches: 0,
+      functions: 0,
+      lines: 0,
+      statements: 0,
+    },
+  },
+});