chore: add prepublishOnly guard and document publish workflow

christso · christso · commit 59aa7bfd9171 · 2026-03-21T07:59:48.000Z
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -152,6 +152,15 @@ Shared formatting lives in `src/cli/format-sync.ts`. When adding new sync output
 
 Internally, `vscode` and `copilot` remain distinct client types with separate path mappings (see `resolveClientMappings()` in `client-mapping.ts`).
 
+## Publishing
+
+**Never run `npm publish` directly.** Always use the two-step workflow:
+
+1. `bun run publish:next` — publishes to the `next` tag
+2. `bun run promote:latest` — promotes `next` to `latest` after testing
+
+A `prepublishOnly` guard in `package.json` blocks direct `npm publish`. This prevents untested releases from going to `latest`.
+
 ## Troubleshooting
 
 ### agent-browser
diff --git a/package.json b/package.json
@@ -27,7 +27,8 @@
     "prepare": "bun run build && (test -d .git && bunx prek install -t pre-push || true)",
     "release": "bun run scripts/release.ts",
     "release:next": "bun run scripts/release.ts next",
-    "publish:next": "bun run build && bun publish --tag next",
+    "prepublishOnly": "test \"$ALLOW_PUBLISH\" = '1' || (echo 'ERROR: Use bun run publish:next, then bun run promote:latest' && exit 1)",
+    "publish:next": "bun run build && ALLOW_PUBLISH=1 npm publish --tag next",
     "promote:latest": "bun scripts/tag-channel.ts latest"
   },
   "keywords": [
