feat(npm): publish APM to npm via platform-specific optional packages

.github/workflows/build-release.yml

@@ -821,3 +821,58 @@ jobs:
                 "windows_x86_64": "${{ steps.checksums.outputs.windows-x86_64-sha }}"
               }
             }
+
+  publish-npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: [build-and-test, build-and-validate-macos-intel, build-and-validate-macos-arm, integration-tests, release-validation, create-release]
+    if: github.ref_type == 'tag' && needs.create-release.outputs.is_private_repo != 'true' && needs.create-release.outputs.is_prerelease != 'true'
+    permissions:
+      contents: read
+      id-token: write  # Required for npm provenance (publishConfig.provenance: true)
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download all build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: ./artifacts
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install test dependencies
+        run: uv sync --extra build
+
+      - name: Build npm packages
+        run: uv run scripts/npm_publish.py
+
+      # Publish platform packages first, then the main wrapper that lists
+      # them as optionalDependencies.
+      - name: Publish npm packages
+        run: |
+          for package in \
+            dist/npm/apm-cli-linux-x64 \
+            dist/npm/apm-cli-linux-arm64 \
+            dist/npm/apm-cli-darwin-x64 \
+            dist/npm/apm-cli-darwin-arm64 \
+            dist/npm/apm-cli-win32-x64 \
+            dist/npm/apm-cli; do
+            npm publish "$package" --tag latest --access public
+          done
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -86,6 +86,22 @@ Agent context is executable in effect — a prompt is a program for an LLM. APM
 
 ## Get Started
 
+#### Node.js projects
+
+```bash
+# Install globally
+npm install -g @microsoft/apm-cli
+# or: pnpm add -g @microsoft/apm-cli
+# or: yarn global add @microsoft/apm-cli
+
+# Or install as a project devDependency (recommended)
+npm install -D @microsoft/apm-cli
+# or: pnpm add -D @microsoft/apm-cli
+# or: yarn add -D @microsoft/apm-cli
+
+npx apm init
+```
+
 #### Linux / macOS
 
 ```bash

docs/src/content/docs/getting-started/installation.md

@@ -54,6 +54,22 @@ GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh
 
 ## Package managers
 
+**Node.js projects:**
+
+```bash
+# Global installation
+npm install -g @microsoft/apm-cli
+# or: pnpm add -g @microsoft/apm-cli
+# or: yarn global add @microsoft/apm-cli
+
+# Or as a project devDependency (recommended)
+npm install -D @microsoft/apm-cli
+# or: pnpm add -D @microsoft/apm-cli
+# or: yarn add -D @microsoft/apm-cli
+
+npx apm --version
+```
+
 **Homebrew (macOS/Linux):**
 
 ```bash

docs/src/content/docs/getting-started/quick-start.md

@@ -9,6 +9,20 @@ Three commands. Three minutes. Your AI agent learns your project's standards aut
 
 ## Install APM
 
+**Node.js projects:**
+
+```bash
+# Global
+npm install -g @microsoft/apm-cli
+# or: pnpm add -g @microsoft/apm-cli
+# or: yarn global add @microsoft/apm-cli
+
+# Or as a project devDependency
+npm install -D @microsoft/apm-cli
+# or: pnpm add -D @microsoft/apm-cli
+# or: yarn add -D @microsoft/apm-cli
+```
+
 **macOS / Linux:**
 
 ```bash

packages/@microsoft/apm-cli/templates/apm-cli-bin.js.jinja2

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+const { platform, arch, env, version, release } = process;
+
+const PLATFORMS = {
+{%- for npm_platform, archs in grouped_platforms.items() %}
+        {{ npm_platform }}: {
+{%- for npm_arch in archs %}
+                {{ npm_arch }}: "@microsoft/apm-cli-{{ npm_platform }}-{{ npm_arch }}/apm{%- if npm_platform == 'win32' -%}.exe{%- endif -%}",
+{%- endfor %}
+        },
+{%- endfor %}
+};
+
+const binPath = env.APM_BINARY ||
+        PLATFORMS?.[platform]?.[arch];
+
+if (binPath) {
+        const packageManager = detectPackageManager();
+        const result = require("child_process").spawnSync(
+                require.resolve(binPath),
+                process.argv.slice(2),
+                {
+                        shell: false,
+                        stdio: "inherit",
+                        env: {
+                                ...env,
+                                JS_RUNTIME_VERSION: version,
+                                JS_RUNTIME_NAME: release.name,
+                                ...(packageManager != null
+                                        ? { NODE_PACKAGE_MANAGER: packageManager }
+                                        : {}),
+                        },
+                },
+        );
+
+        if (result.error) {
+                throw result.error;
+        }
+
+        process.exitCode = result.status;
+} else {
+        console.error(
+                "The APM CLI package doesn't ship with prebuilt binaries for your platform yet. " +
+                        "You can still use the CLI by cloning the microsoft/apm repo from GitHub, " +
+                        "and follow the instructions there to build the CLI for your platform.",
+        );
+        process.exitCode = 1;
+}
+
+/**
+ * NPM, Yarn, and other package manager set the `npm_config_user_agent`. It has the following format:
+ *
+ * ```
+ * "npm/8.3.0 node/v16.13.2 win32 x64 workspaces/false
+ * ```
+ *
+ * @returns The package manager string (`npm/8.3.0`) or null if the user agent string isn't set.
+ */
+function detectPackageManager() {
+        const userAgent = env.npm_config_user_agent;
+
+        if (userAgent == null) {
+                return null;
+        }
+
+        return userAgent.split(" ")[0];
+}

packages/@microsoft/apm-cli/templates/apm-cli-package.json.jinja2

@@ -0,0 +1,36 @@
+{
+  "name": "@microsoft/apm-cli",
+  "version": "{{ version }}",
+  "description": "APM (Agent Package Manager) -- ship and govern AI agent context",
+  "license": "MIT",
+  "author": "Microsoft",
+  "homepage": "https://microsoft.github.io/apm/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/apm.git"
+  },
+  "bugs": "https://github.com/microsoft/apm/issues",
+  "bin": {
+    "apm": "bin/apm"
+  },
+  "keywords": [
+    "agent",
+    "package-manager",
+    "mcp",
+    "ai",
+    "llm",
+    "copilot",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "provenance": true
+  },
+  "optionalDependencies": {
+{% for npm_platform, npm_arch in platforms %}
+    "@microsoft/apm-cli-{{ npm_platform }}-{{ npm_arch }}": "{{ version }}"{{ "," if not loop.last else "" }}
+{% endfor %}
+  }
+}

packages/@microsoft/apm-cli/templates/platform-package.json.jinja2

@@ -0,0 +1,20 @@
+{
+  "name": "@microsoft/apm-cli-{{npm_platform}}-{{npm_arch}}",
+  "version": "{{ version }}",
+  "description": "APM (Agent Package Manager) -- ship and govern AI agent context",
+  "license": "MIT",
+  "author": "Microsoft",
+  "homepage": "https://microsoft.github.io/apm/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/apm.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [{{ npm_platform | tojson }}],
+  "cpu": [{{ npm_arch | tojson }}],
+  "publishConfig": {
+    "provenance": true
+  }
+}

packages/apm-guide/.apm/skills/apm-usage/installation.md

@@ -13,6 +13,10 @@ irm https://aka.ms/apm-windows | iex
 ## Package managers
 
 ```bash
+# Node.js environments
+npm install -g @microsoft/apm-cli      # Global (or pnpm add -g / yarn global add)
+npm install -D @microsoft/apm-cli      # Project devDependency (or pnpm/yarn add -D)
+
 # Homebrew (macOS / Linux)
 brew install microsoft/apm/apm
 

pyproject.toml

@@ -48,6 +48,7 @@ dev = [
     "mypy>=1.0.0",
 ]
 build = [
+    "jinja2>=3.1.6",
     "pyinstaller>=6.0.0",
 ]