Guard release workflow helper docs

Author: CharGrnmn

.github/workflows/ray-core-release.yml

@@ -2,10 +2,9 @@ name: "@razroo/ray-core Release to npm"
 
 # Publish when a GitHub Release whose tag starts with `core-v` is published.
 #
-# Cutting a release (after bumping packages/core/package.json version):
-#   TAG="core-v$(bun -e 'console.log(require("./packages/core/package.json").version)')"
-#   git tag -a "$TAG" -m "Release $TAG (@razroo/ray-core)" && git push origin "$TAG"
-#   gh release create "$TAG" --generate-notes --title "$TAG"
+# Cut releases with the guarded helper from main:
+#   bun run release:github -- --dry-run
+#   bun run release:github -- --yes
 
 on:
   release:

.github/workflows/ray-sdk-release.yml

@@ -3,10 +3,9 @@ name: "@razroo/ray-sdk Release to npm"
 # Publish when a GitHub Release whose tag starts with `sdk-v` is published.
 # Publish @razroo/ray-core first if its version changed; SDK releases often follow core.
 #
-# Cutting a release (after bumping packages/sdk/package.json version):
-#   TAG="sdk-v$(bun -e 'console.log(require("./packages/sdk/package.json").version)')"
-#   git tag -a "$TAG" -m "Release $TAG (@razroo/ray-sdk)" && git push origin "$TAG"
-#   gh release create "$TAG" --generate-notes --title "$TAG"
+# Cut releases with the guarded helper from main:
+#   bun run release:github -- --dry-run
+#   bun run release:github -- --yes
 
 on:
   release:

docs/npm-publishing.md

@@ -66,43 +66,24 @@ Infrastructure-only PRs can add an empty changeset: `bunx changeset add --empty`
 
 ## Cut a release (GH + npm)
 
-1. Ensure **`bun run version`** has been run and the version bump is committed on **`main`**.
+1. Ensure **`bun run version`** has been run and the version bump is committed and pushed on **`main`**.
 
-2. Create **annotated tags** pointing at that commit:
+2. Create both annotated tags and GitHub Releases with the guarded helper:
 
    ```bash
-   TAG_CORE="core-v$(bun -e 'console.log(require("./packages/core/package.json").version)')"
-   TAG_SDK="sdk-v$(bun -e 'console.log(require("./packages/sdk/package.json").version)')"
-   git tag -a "$TAG_CORE" -m "Release $TAG_CORE (@razroo/ray-core)"
-   git tag -a "$TAG_SDK" -m "Release $TAG_SDK (@razroo/ray-sdk)"
-   git push --atomic origin "$TAG_CORE" "$TAG_SDK"
+   bun run release:github -- --dry-run
+   bun run release:github -- --yes
    ```
 
-   Push linked package tags atomically so a failed push cannot publish only one side of the release pair.
+   The helper checks that the working tree is clean, `main` is synced with `origin/main`, package versions match, and GitHub CLI auth is available. It creates annotated `core-v…` and `sdk-v…` tags, pushes them atomically, creates both GitHub Releases, and safely reuses already-created annotated tags or releases on retry.
 
-3. Create GitHub Releases (fires the npm workflows):
-
-   ```bash
-   gh release create "$TAG_CORE" --generate-notes --title "$TAG_CORE"
-   gh release create "$TAG_SDK" --generate-notes --title "$TAG_SDK"
-   ```
-
-4. Workflow behavior:
+3. Workflow behavior:
    - Confirms the release tag commit is reachable from `origin/main`.
    - Uses **`gh api`** to confirm the **`quality`** check run on the tagged commit succeeded (geometra-style gate before npm).
    - Runs **`packages/*/scripts/release/check-source.mjs`** so the tag matches `package.json`.
    - **`bun run build`**, **`bun pm pack`**, then **`npm publish <tarball> --provenance`** with OIDC provenance (`id-token: write`).
 
-5. Omit or delete a faulty GitHub Release and tag before re-cutting; avoid amending published tags.
-
-### One-command tags + GitHub Releases (`gh`)
-
-After **`bun run version`** is committed on **`main`** and pushed (`git push origin main`), you can create both tags and GitHub Releases with:
-
-```bash
-bun run release:github -- --dry-run   # plan only
-bun run release:github -- --yes     # tag, git push --atomic tags, gh release create ×2
-```
+4. Omit or delete a faulty GitHub Release and tag before re-cutting; avoid amending published tags.
 
 Requires [**GitHub CLI**](https://cli.github.com/) (`gh`) authenticated (`gh auth login`). If a transient failure leaves local or remote annotated tags at the release commit, or creates one GitHub Release before the other, the helper reuses the safe pieces on retry and creates only what is still missing; local or remote lightweight tags, tags pointing elsewhere, and ambiguous release probes fail closed. NPM publish still runs in Actions when each release is **published**.
 

scripts/package-runtime-coverage.test.ts

@@ -1116,6 +1116,7 @@ test("validatePackageRuntimeCoverage rejects lightweight release tag workflow co
       'name: "@razroo/ray-core Release to npm"',
       '#   TAG="core-v$(bun -e \'console.log(require("./packages/core/package.json").version)\')"',
       '#   git tag "$TAG" && git push origin "$TAG"',
+      "#   bun run release:github -- --yes",
       "jobs:",
       "  publish:",
       "    if: github.repository == 'razroo/ray'",
@@ -1146,6 +1147,62 @@ test("validatePackageRuntimeCoverage rejects lightweight release tag workflow co
         diagnostic.code === "workflow_npm_release_lightweight_tag_doc" && diagnostic.line === 3,
     ),
   );
+  assert.ok(
+    diagnostics.some(
+      (diagnostic) =>
+        diagnostic.code === "workflow_npm_release_manual_command_doc" && diagnostic.line === 3,
+    ),
+  );
+});
+
+test("validatePackageRuntimeCoverage requires guarded release helper workflow comments", async (t) => {
+  const tempDir = await mkdtemp(path.join(tmpdir(), "ray-package-runtime-release-helper-docs-"));
+  t.after(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+  const workflowDir = path.join(tempDir, ".github", "workflows");
+  await mkdir(workflowDir, { recursive: true });
+  await writeFile(
+    path.join(workflowDir, "ray-sdk-release.yml"),
+    [
+      'name: "@razroo/ray-sdk Release to npm"',
+      "# Cutting a release:",
+      '#   git tag -a "$TAG" -m "Release $TAG"',
+      '#   git push origin "$TAG"',
+      '#   gh release create "$TAG" --generate-notes --title "$TAG"',
+      "jobs:",
+      "  publish:",
+      "    if: github.repository == 'razroo/ray'",
+      "    runs-on: ubuntu-latest",
+      "    timeout-minutes: 60",
+      "    permissions:",
+      "      id-token: write",
+      "    steps:",
+      "      - run: timeout 120s git fetch --no-tags --prune origin main:refs/remotes/origin/main",
+      '      - run: git merge-base --is-ancestor "$SHA" refs/remotes/origin/main',
+      "      - run: timeout 300s npm publish ./pkg.tgz --access public --provenance",
+      "        env:",
+      "          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}",
+      "",
+    ].join("\n"),
+  );
+
+  const summary = await validatePackageRuntimeCoverage({
+    cwd: tempDir,
+    packageJsonPaths: [],
+  });
+  const diagnostics = summary.results.flatMap((result) => result.diagnostics);
+
+  assert.equal(summary.ok, false);
+  assert.ok(
+    diagnostics.some((diagnostic) => diagnostic.code === "workflow_npm_release_helper_doc_missing"),
+  );
+  assert.equal(
+    diagnostics.filter(
+      (diagnostic) => diagnostic.code === "workflow_npm_release_manual_command_doc",
+    ).length,
+    3,
+  );
 });
 
 test("validatePackageRuntimeCoverage rejects unsafe release tag doc commands", async (t) => {

scripts/package-runtime-coverage.ts

@@ -70,6 +70,9 @@ const workflowReleaseMainAncestryPattern =
 const workflowIdTokenWritePattern = /^\s*id-token:\s*write\s*$/m;
 const workflowNpmTokenPattern = /NODE_AUTH_TOKEN:\s*\$\{\{\s*secrets\.NPM_TOKEN\s*\}\}/;
 const workflowLightweightReleaseTagCommentPattern = /^\s*#\s*git\s+tag\s+"\$TAG"(?:\s|$)/;
+const workflowManualReleaseCommandCommentPattern =
+  /^\s*#\s*(?:git\s+(?:tag|push)\b|gh\s+release\s+create\b)/;
+const workflowReleaseGithubHelperCommentPattern = /^\s*#.*\bbun\s+run\s+release:github\b/;
 const releaseTagVariablePattern = /\$(?:\{TAG(?:_(?:CORE|SDK))?\}|TAG(?:_(?:CORE|SDK))?)/;
 const releaseDocGitTagCommandPattern = /^git\s+tag\s+/;
 const releaseDocAnnotatedGitTagCommandPattern = /^git\s+tag\s+(?:-a|--annotate)\b/;
@@ -1863,6 +1866,20 @@ function validateNpmReleaseWorkflowTagDocs(
   }
 
   const diagnostics: PackageRuntimeCoverageDiagnostic[] = [];
+  const documentsGuardedHelper = lines.some((line) =>
+    workflowReleaseGithubHelperCommentPattern.test(line),
+  );
+
+  if (!documentsGuardedHelper) {
+    diagnostics.push({
+      level: "error",
+      code: "workflow_npm_release_helper_doc_missing",
+      workflowPath,
+      message:
+        "npm release workflow cutting comments must point maintainers at `bun run release:github` so release tags and GitHub Releases use the guarded helper.",
+    });
+  }
+
   for (const [index, rawLine] of lines.entries()) {
     if (workflowLightweightReleaseTagCommentPattern.test(rawLine)) {
       diagnostics.push({
@@ -1874,6 +1891,17 @@ function validateNpmReleaseWorkflowTagDocs(
           "npm release workflow cutting comments must use annotated git tags so operator docs do not recommend lightweight release tags.",
       });
     }
+
+    if (workflowManualReleaseCommandCommentPattern.test(rawLine)) {
+      diagnostics.push({
+        level: "error",
+        code: "workflow_npm_release_manual_command_doc",
+        workflowPath,
+        line: index + 1,
+        message:
+          "npm release workflow cutting comments must not document direct git tag, git push, or gh release create commands; use `bun run release:github` instead.",
+      });
+    }
   }
 
   return diagnostics;