feat: distribute binaries via npm platform packages

.claude/agent-memory/archgate-developer/MEMORY.md

@@ -48,6 +48,14 @@ Skipping steps 2 or 3 is a workflow violation. The user should NEVER have to inv
 
 - **`archgate` command = `bun run cli`** — This is the CLI repo itself, so the `archgate` binary is not installed in PATH. Use `bun run cli <command>` (e.g., `bun run cli check`, `bun run cli adr list`) instead of `archgate <command>`. The `bun run cli` script maps to `bun run src/cli.ts`.
 
+## Distribution / Packaging
+
+- **npm binary distribution (Sentry pattern)** — Binaries are distributed as platform npm packages (`archgate-darwin-arm64`, `archgate-linux-x64`) listed as `optionalDependencies` of the main `archgate` package. Main package has a `bin` field pointing to `bin/archgate.cjs`.
+- **`.cjs` extension is mandatory** — Root `package.json` has `"type": "module"`. Any Node.js CJS wrapper script placed at the package root MUST use `.cjs`, not `.js`, or Node.js will attempt to parse it as ESM and fail.
+- **Platform package version placeholder** — Platform `package.json` files start at version `0.0.0`. CI runs `npm version "$VERSION" --no-git-tag-version` inside the package directory before publishing.
+- **Gitignore and prettierignore rules** — `packages/*/bin/archgate` is gitignored (binary injected by CI); `packages/*/bin/` is prettier-ignored (binary files must not be formatted).
+- **npm OIDC publishing** — Uses `id-token: write` permission + `actions/setup-node@v4` with `registry-url: 'https://registry.npmjs.org'`. No `NODE_AUTH_TOKEN` secret needed for OIDC trusted publishing — matches the pattern in `release.yml`.
+
 ## MCP Tools Structure
 
 - MCP tools live in `src/mcp/tools/` — one file per tool (check, list-adrs, review-context, session-context)

.github/workflows/release-binaries.yml

@@ -10,11 +10,12 @@ on:
         required: true
 
 permissions:
-  contents: write
+  contents: read
+  id-token: write
 
 jobs:
-  build:
-    name: Build ${{ matrix.artifact }}
+  build-and-publish:
+    name: Build and publish ${{ matrix.artifact }}
     timeout-minutes: 15
     strategy:
       fail-fast: false
@@ -29,21 +30,17 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
         with:
           ref: ${{ github.event.release.tag_name || inputs.tag }}
 
-      - name: Setup toolchain (proto)
-        uses: moonrepo/setup-toolchain@v0
+      - uses: moonrepo/setup-toolchain@v0
         with:
           auto-install: true
 
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
+      - run: bun install --frozen-lockfile
 
-      - name: Validate
-        run: bun run validate
+      - run: bun run validate
 
       - name: Build binary
         run: |
@@ -54,69 +51,18 @@ jobs:
             --target ${{ matrix.target }} \
             --outfile dist/${{ matrix.artifact }}
 
-      - name: Generate checksum
-        run: |
-          cd dist
-          sha256sum ${{ matrix.artifact }} > ${{ matrix.artifact }}.sha256
-          cat ${{ matrix.artifact }}.sha256
-
-      - name: Upload to release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: ${{ github.event.release.tag_name || inputs.tag }}
-          files: |
-            dist/${{ matrix.artifact }}
-            dist/${{ matrix.artifact }}.sha256
-
-  update-homebrew:
-    name: Update Homebrew tap
-    needs: build
-    timeout-minutes: 5
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout CLI repo
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.release.tag_name || inputs.tag }}
-
-      - name: Resolve tag
-        id: tag
+      - name: Copy binary into npm package
         run: |
           TAG="${{ github.event.release.tag_name || inputs.tag }}"
-          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
-          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
-
-      - name: Download checksums
-        run: |
-          BASE="https://github.com/archgate/cli/releases/download/${{ steps.tag.outputs.tag }}"
-          curl -fsSL "${BASE}/archgate-darwin-arm64.sha256" -o darwin-arm64.sha256
-          curl -fsSL "${BASE}/archgate-linux-x64.sha256" -o linux-x64.sha256
-          SHA_DARWIN=$(awk '{print $1}' darwin-arm64.sha256)
-          SHA_LINUX=$(awk '{print $1}' linux-x64.sha256)
-          echo "sha_darwin=${SHA_DARWIN}" >> "$GITHUB_ENV"
-          echo "sha_linux=${SHA_LINUX}" >> "$GITHUB_ENV"
+          VERSION="${TAG#v}"
+          cp dist/${{ matrix.artifact }} packages/${{ matrix.artifact }}/bin/archgate
+          chmod +x packages/${{ matrix.artifact }}/bin/archgate
+          cd packages/${{ matrix.artifact }}
+          npm version "$VERSION" --no-git-tag-version
 
-      - name: Checkout homebrew-tap
-        uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          repository: archgate/homebrew-tap
-          path: homebrew-tap
-          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          registry-url: "https://registry.npmjs.org"
 
-      - name: Update formula
-        run: |
-          VERSION="${{ steps.tag.outputs.version }}"
-          sed -i "s/PLACEHOLDER_VERSION/${VERSION}/g" scripts/archgate.rb
-          sed -i "s/PLACEHOLDER_SHA256_DARWIN_ARM64/${{ env.sha_darwin }}/g" scripts/archgate.rb
-          sed -i "s/PLACEHOLDER_SHA256_LINUX_X64/${{ env.sha_linux }}/g" scripts/archgate.rb
-          cp scripts/archgate.rb homebrew-tap/Formula/archgate.rb
-
-      - name: Commit and push formula
-        run: |
-          cd homebrew-tap
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add Formula/archgate.rb
-          git commit -m "chore: update archgate to ${{ steps.tag.outputs.tag }}"
-          git push
+      - name: Publish platform package
+        run: npm publish packages/${{ matrix.artifact }} --access public

.github/workflows/release.yml

@@ -127,7 +127,7 @@ jobs:
       - name: Setup Node.js for npm publish
         uses: actions/setup-node@v4
         with:
-          registry-url: 'https://registry.npmjs.org'
+          registry-url: "https://registry.npmjs.org"
       - name: Release
         uses: TrigenSoftware/simple-release-action@v1
         with:

.gitignore

@@ -27,3 +27,6 @@ coverage
 # Package manager
 *.tgz
 .npm
+
+# Platform package binaries (injected by CI)
+packages/*/bin/archgate

.prettierignore

@@ -3,3 +3,4 @@ dist
 coverage
 bun.lock
 CHANGELOG.md
+packages/*/bin/

bin/archgate.cjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+function getPlatformPackageName() {
+  const { platform, arch } = process;
+  if (platform === "darwin" && arch === "arm64") return "archgate-darwin-arm64";
+  if (platform === "linux" && arch === "x64") return "archgate-linux-x64";
+  throw new Error(
+    `Unsupported platform: ${platform}/${arch}\narchgate supports darwin/arm64 and linux/x64 only.`
+  );
+}
+
+function getBinaryPath() {
+  const pkgName = getPlatformPackageName();
+  try {
+    const pkgDir = path.dirname(require.resolve(`${pkgName}/package.json`));
+    const binaryPath = path.join(pkgDir, "bin", "archgate");
+    if (fs.existsSync(binaryPath)) return binaryPath;
+  } catch {
+    /* platform package not installed */
+  }
+  throw new Error(
+    `archgate binary not found. "${getPlatformPackageName()}" may not be installed.\nTry reinstalling: npm install -g archgate`
+  );
+}
+
+try {
+  const binary = getBinaryPath();
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  if (typeof e.status === "number") process.exit(e.status);
+  console.error(e.message);
+  process.exit(2);
+}

package.json

@@ -5,11 +5,15 @@
   "readme": "README.md",
   "license": "FSL-1.1-ALv2",
   "homepage": "https://archgate.dev",
+  "bin": {
+    "archgate": "bin/archgate.cjs"
+  },
   "exports": {
     "./rules": "./src/formats/rules.ts"
   },
   "files": [
-    "src/formats/rules.ts"
+    "src/formats/rules.ts",
+    "bin/archgate.cjs"
   ],
   "author": {
     "name": "Archgate",
@@ -43,9 +47,6 @@
     "build:check": "bun build src/cli.ts --compile --bytecode --outfile dist/.build-check && rm -f dist/.build-check",
     "validate": "bun run lint && bun run typecheck && bun run format:check && bun test && bun run check && bun run build:check",
     "commit": "cz",
-    "build": "bun run scripts/build.ts",
-    "build:darwin": "bun run scripts/build.ts --target darwin-arm64",
-    "build:linux": "bun run scripts/build.ts --target linux-x64",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
   },
   "type": "module",
@@ -69,5 +70,9 @@
   },
   "peerDependencies": {
     "typescript": "^5"
+  },
+  "optionalDependencies": {
+    "archgate-darwin-arm64": ">=0.1.1",
+    "archgate-linux-x64": ">=0.1.1"
   }
 }

packages/archgate-darwin-arm64/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "archgate-darwin-arm64",
+  "version": "0.0.0",
+  "description": "darwin arm64 binary for archgate",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "files": [
+    "bin/archgate"
+  ],
+  "license": "FSL-1.1-ALv2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/archgate/cli.git"
+  }
+}

packages/archgate-linux-x64/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "archgate-linux-x64",
+  "version": "0.0.0",
+  "description": "linux x64 binary for archgate",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "bin/archgate"
+  ],
+  "license": "FSL-1.1-ALv2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/archgate/cli.git"
+  }
+}