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

.github/CODEOWNERS

@@ -94,6 +94,7 @@
 /packages/eth-json-rpc-middleware      @MetaMask/core-platform
 /packages/messenger                    @MetaMask/core-platform
 /packages/messenger-cli                @MetaMask/core-platform
+/packages/platform-api-docs               @MetaMask/core-platform
 /packages/sample-controllers           @MetaMask/core-platform
 /packages/polling-controller           @MetaMask/core-platform
 /packages/preferences-controller       @MetaMask/core-platform

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

@@ -0,0 +1,75 @@
+name: Deploy Platform 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 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.
+        run: |
+          yarn docs:platform-api:build \
+            --site-url "https://${{ github.repository_owner }}.github.io" \
+            --site-base-url "/${{ github.event.repository.name }}/platform-api/"
+
+      - name: Upload build artifact (PR)
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v7
+        with:
+          name: platform-api-docs
+          path: .platform-api-docs/build/
+          retention-days: 7
+
+      - name: Upload build artifact for deploy job
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-artifact@v7
+        with:
+          name: platform-api-docs-build
+          path: .platform-api-docs/build/
+          retention-days: 1
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - 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@v4.1.0
+        with:
+          github_token: ${{ secrets.GITHUB_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

.gitignore

@@ -37,4 +37,7 @@ scripts/coverage
 packages/*/*.tsbuildinfo
 
 # AI
-.sisyphus/
+.sisyphus/
+
+# Platform API docs (generated)
+.platform-api-docs/

README.md

@@ -83,6 +83,7 @@ Each package in this repository has its own README where you can find installati
 - [`@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)
@@ -176,6 +177,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

@@ -76,9 +76,11 @@ const config = createConfig([
       '**/dist/**',
       '**/docs/**',
       '**/coverage/**',
+      '.platform-api-docs/**',
       'merged-packages/**',
       '.yarn/**',
       'scripts/create-package/package-template/**',
+      'packages/platform-api-docs/site/**',
     ],
   },
   {
@@ -114,6 +116,7 @@ const config = createConfig([
       '**/tests/**/*.{js,ts}',
       'scripts/*.ts',
       'scripts/create-package/**/*.ts',
+      'packages/platform-api-docs/**/*.ts',
     ],
     extends: [nodejs],
   },
@@ -207,7 +210,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',
@@ -306,6 +309,14 @@ const config = createConfig([
       'import-x/no-nodejs-modules': 'off',
     },
   },
+  {
+    files: ['packages/platform-api-docs/**/*.{js,ts}'],
+    rules: {
+      'import-x/no-nodejs-modules': 'off',
+      'n/no-process-env': 'off',
+      'n/no-sync': 'off',
+    },
+  },
   {
     files: [
       'packages/notification-services-controller/src/NotificationServicesPushController/services/push/*-web.ts',

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": "depcheck && yarn dedupe --check",
     "lint:dependencies:fix": "depcheck && yarn dedupe",
@@ -96,7 +99,12 @@
   },
   "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",
+    "webpackbar@^6.0.1": "^7.0.0",
     "ws@7.4.6": "^7.5.10"
   },
   "simple-git-hooks": {
@@ -111,9 +119,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/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.