@rmartz/bot-automerge 0.2.1 → 1.0.2

package/README.md

@@ -11,69 +11,46 @@ merge?", bot-automerge answers "is this a bot PR we trust enough to enable
 auto-merge on?". Unlike merge-safety, it posts **no check-run**.
 
 It is distributed the same way [`@rmartz/repo-hygiene`](https://github.com/rmartz/repo-hygiene)
-and `@rmartz/merge-safety` are:
-
-1. **Updates propagate automatically.** Consuming repos pin one reusable workflow
-   by SHA; Dependabot's `github-actions` ecosystem opens PRs to bump that pin.
+and `@rmartz/merge-safety` are — the package lives here, and consumers reach it
+through a separate action repo:
+
+1. **Updates propagate automatically.** Consuming repos pin
+   [`rmartz/bot-automerge-action`](https://github.com/rmartz/bot-automerge-action)
+   by SHA; Dependabot's `github-actions` ecosystem opens PRs to bump that pin. The
+   action pins this package's version in its own `package.json`, bumped by
+   Dependabot's `npm` ecosystem, so a new CLI release reaches consumers as an
+   action release.
 2. **No check-run contract.** bot-automerge is purely an eligibility enabler — it
    requires no fleet-wide status-check name. See
    [docs/bot-automerge-contract.md](docs/bot-automerge-contract.md).
 
 > **Status: implemented.** The `enable` classification — Dependabot `patch`/`minor`
-> bumps and release-please release PRs — and the reusable workflow are complete and
-> ship in `v0.1.0`, the first release to GitHub Packages. It was built per
+> bumps and release-please release PRs — shipped in `v0.1.0`, the first release to
+> GitHub Packages. It was built per
 > [ai-tools#264](https://github.com/rmartz/ai-tools/issues/264); see
 > [docs/bot-automerge-contract.md](docs/bot-automerge-contract.md) for the
 > eligibility contract.
 
 ## Using it in a consuming repo
 
-Add one caller workflow (this is what Dependabot keeps current). Unlike a
-read-only hygiene check, this caller carries the triggers, grants write scopes,
-and passes secrets through — because a reusable workflow can't declare its own
-triggers and runs with the intersection of granted and declared permissions:
-
-```yaml
-# .github/workflows/bot-automerge.yml
-name: bot-automerge
-on:
-  pull_request_target:
-    types: [opened, reopened, synchronize, labeled]
-permissions:
-  contents: write
-  pull-requests: write
-  packages: read # install the CLI from GitHub Packages
-jobs:
-  bot-automerge:
-    uses: rmartz/bot-automerge/.github/workflows/bot-automerge.yml@<sha> # vX.Y.Z
-    with:
-      pr: ${{ github.event.pull_request.number }}
-    secrets: inherit
-```
-
-It uses `pull_request_target` (not `pull_request`) because Dependabot PRs run with
-a read-only token, and enabling auto-merge needs base-context write.
+Use [`rmartz/bot-automerge-action`](https://github.com/rmartz/bot-automerge-action)
+— its [consumer guide](https://github.com/rmartz/bot-automerge-action/blob/main/docs/consuming.md)
+has the caller workflow, its permissions, and the `merge-safety` prerequisite.
+This repo no longer ships a reusable workflow; see
+[docs/consuming.md](docs/consuming.md) for what that means for existing callers.
 
 > **Require `merge-safety` + your CI checks on the default branch _before_ adopting
-> this.** `gh pr merge --auto` merges a PR immediately if the repo has no required
+> it.** `gh pr merge --auto` merges a PR immediately if the repo has no required
 > status checks — bot-automerge only makes a bot PR _eligible_ to auto-merge; the
-> repo's required checks are what it waits on. See the
-> [consumer setup guide](docs/consuming.md) for the full prerequisite.
-
-The public `@rmartz/bot-automerge` package on GitHub Packages is readable with the
-built-in `GITHUB_TOKEN`, so no consumer PAT is required.
-
-> For the full walkthrough — the caller's permissions, why it isn't trigger-free,
-> and how the pin stays current — see the
-> [consumer setup guide](docs/consuming.md).
+> repo's required checks are what it waits on.
 
 ## Requirements
 
 - Node.js >= 20.11
 - pnpm 9 (pinned via `packageManager`)
 
-Consuming repos need neither — the reusable workflow runs the published CLI on a
-GitHub-hosted runner.
+Consuming repos need neither — `rmartz/bot-automerge-action` runs the published
+CLI on a GitHub-hosted runner.
 
 ## Local development
 
@@ -90,10 +67,16 @@ pnpm run test         # vitest
 
 Versioned by [semantic-release](.releaserc.json). A push to `main` analyzes the
 Conventional-Commit history since the last `bot-automerge-v*` tag and, when a
-release is warranted, publishes the package to GitHub Packages (public) and
-creates the git tag + GitHub Release — no release PR and no commit-back, so the
+release is warranted, publishes the package to npmjs (public, via OIDC trusted
+publishing with provenance — no npm token) and creates the git tag + GitHub
+Release. Versions up to 0.2.1 were published to GitHub Packages and stay there for
+existing pins; new versions go to npmjs only. There is no release PR and no
+commit-back, so the
 built-in `GITHUB_TOKEN` suffices. `tagFormat` stays `bot-automerge-v${version}`
-for continuity with the prior release-please tags.
+for continuity with the prior release-please tags. A `Release dry-run` CI job
+validates the semantic-release config (that the changelog toolchain renders) on
+every PR, so a broken release setup is caught before merge rather than on the
+post-merge release run.
 
 ---
 

package/dist/bin/bot-automerge.js

@@ -2,7 +2,6 @@
 import {
   AUTOMERGE_HANDLED_LABEL,
   RELEASE_PLEASE_BRANCH_PREFIX,
-  RELEASE_PLEASE_PENDING_LABEL,
   isBotAutomergeCommand,
   isDependabotAuthor,
   isDependabotUpdateType,
@@ -60,29 +59,38 @@ function isRateLimited(text) {
 }
 async function runTransport({ argv, stdin }, cwd) {
   const [command, ...args] = argv;
-  if (command === void 0) return { stdout: null, stderr: "empty argv" };
+  if (command === void 0) return { stdout: null, failure: { code: null, stderr: "empty argv" } };
   try {
     const r = await boundedRun(command, args, { timeoutMs: GH_API_TIMEOUT_MS, cwd, input: stdin });
-    if (r.code === 0) return { stdout: r.stdout, stderr: "" };
-    return { stdout: null, stderr: r.stderr || "" };
+    if (r.code === 0) return { stdout: r.stdout, failure: { code: 0, stderr: "" } };
+    const stderr = r.timedOut ? `timed out after ${GH_API_TIMEOUT_MS}ms` : r.stderr || "";
+    return { stdout: null, failure: { code: r.timedOut ? null : r.code, stderr } };
   } catch (err) {
-    return { stdout: null, stderr: err instanceof Error ? err.message : String(err) };
+    return {
+      stdout: null,
+      failure: { code: null, stderr: err instanceof Error ? err.message : String(err) }
+    };
   }
 }
-async function ghCall(primary, fallback, opts = {}) {
+async function ghCallDetailed(primary, fallback, opts = {}) {
   const sleep = opts.sleep ?? realSleep;
+  let lastFailure = { code: null, stderr: "no transport attempted" };
   for (const transport of [primary, fallback]) {
     if (!transport) continue;
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-      const { stdout, stderr } = await runTransport(transport, opts.cwd);
-      if (stdout !== null) return stdout;
-      if (isRateLimited(stderr)) break;
+      const { stdout, failure } = await runTransport(transport, opts.cwd);
+      if (stdout !== null) return { stdout, failure: null };
+      lastFailure = failure;
+      if (isRateLimited(failure.stderr)) break;
       if (attempt < MAX_RETRIES) {
         await sleep(Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_CAP_MS));
       }
     }
   }
-  return null;
+  return { stdout: null, failure: lastFailure };
+}
+async function ghCall(primary, fallback, opts = {}) {
+  return (await ghCallDetailed(primary, fallback, opts)).stdout;
 }
 function parseSlugFromRemoteUrl(url) {
   const trimmed = url.trim();
@@ -131,6 +139,43 @@ async function addLabels(repo, issue, labels, call = {}) {
   return out !== null ? out.trim() : null;
 }
 
+// src/lib/gh-failure.ts
+var MAX_DETAIL_CHARS = 200;
+function classifyGhFailure(stderr) {
+  if (/rate limit|HTTP 429|abuse detection/i.test(stderr)) return "rate-limited";
+  if (/HTTP 401|Bad credentials|SAML|\bSSO\b|gh auth login/i.test(stderr)) {
+    return "token-rejected";
+  }
+  if (/Resource not accessible|HTTP 403|scope/i.test(stderr)) return "permission-denied";
+  if (/Could not resolve to a PullRequest/i.test(stderr)) return "pr-not-found";
+  if (/Could not resolve to a Repository/i.test(stderr)) return "repo-not-found";
+  if (/HTTP 404|Not Found/i.test(stderr)) return "pr-not-found";
+  return "unknown";
+}
+function tokenSource(env = process.env) {
+  if (env.GH_TOKEN) return "GH_TOKEN";
+  if (env.GITHUB_TOKEN) return "GITHUB_TOKEN";
+  return "gh's stored login";
+}
+var SUMMARIES = {
+  "rate-limited": () => "rate limited by GitHub \u2014 wait for the limit to reset, then re-run",
+  "token-rejected": (source) => `token rejected (from ${source}) \u2014 it is expired, revoked, or SSO-deauthorized; rotate it, or unset it to fall back to the workflow token`,
+  "permission-denied": (source) => `token lacks permission (from ${source}) \u2014 it needs contents:write and pull-requests:write on this repo`,
+  "pr-not-found": () => "PR not found \u2014 check the PR number the caller passed",
+  "repo-not-found": (source) => `repository not found or not visible to the token (from ${source}) \u2014 check --repo and the token's repo access`,
+  unknown: () => "gh failed"
+};
+function firstLine(stderr) {
+  const line = stderr.split("\n").map((l) => l.trim()).find((l) => l !== "");
+  if (!line) return "(no stderr)";
+  return line.length > MAX_DETAIL_CHARS ? `${line.slice(0, MAX_DETAIL_CHARS)}\u2026` : line;
+}
+function describeGhFailure(failure, env = process.env) {
+  const summary = SUMMARIES[classifyGhFailure(failure.stderr)](tokenSource(env));
+  const exit = failure.code === null ? "gh did not exit cleanly" : `gh exited ${failure.code}`;
+  return `${summary} (${exit}: ${firstLine(failure.stderr)})`;
+}
+
 // src/lib/automerge-label.ts
 async function markPrHandled(repo, pr, opts = {}) {
   const out = await addLabels(repo, pr, [AUTOMERGE_HANDLED_LABEL], opts);
@@ -143,9 +188,7 @@ function isEvaluablePrState(state) {
 }
 function detectBotPrType(view) {
   if (isDependabotAuthor(view.author)) return "dependabot";
-  if (view.headRefName.startsWith(RELEASE_PLEASE_BRANCH_PREFIX) || view.labels.includes(RELEASE_PLEASE_PENDING_LABEL)) {
-    return "release-please";
-  }
+  if (view.headRefName.startsWith(RELEASE_PLEASE_BRANCH_PREFIX)) return "release-please";
   return null;
 }
 function semverWord(updateType) {
@@ -220,12 +263,14 @@ function parse(argv) {
   return args;
 }
 async function ghJson(argv, cwd) {
-  const out = await ghCall({ argv }, null, { cwd });
-  if (out === null) return null;
+  const { stdout, failure } = await ghCallDetailed({ argv }, null, { cwd });
+  if (stdout === null) {
+    return { ok: false, why: failure ? describeGhFailure(failure) : "gh failed" };
+  }
   try {
-    return JSON.parse(out);
+    return { ok: true, value: JSON.parse(stdout) };
   } catch {
-    return null;
+    return { ok: false, why: "gh returned output that is not valid JSON" };
   }
 }
 async function fetchPrView(repo, pr, cwd) {
@@ -248,22 +293,23 @@ function emitVerdictJson(verdict2, isError) {
   if (isError) process.exitCode = 1;
 }
 async function enableAutoMerge(repo, pr, cwd) {
-  const out = await ghCall(
+  const { failure } = await ghCallDetailed(
     { argv: ["gh", "pr", "merge", "--auto", "--squash", String(pr), "--repo", repo] },
     null,
     { cwd }
   );
-  return out !== null;
+  return failure ? describeGhFailure(failure) : null;
 }
 async function runEnable(repo, pr, args) {
-  const view = await fetchPrView(repo, pr, args.cwd);
-  if (!view) {
-    const msg = `could not read PR #${pr}`;
+  const fetched = await fetchPrView(repo, pr, args.cwd);
+  if (!fetched.ok) {
+    const msg = `could not read PR #${pr} \u2014 ${fetched.why}`;
     if (args.json) return emitVerdictJson(errorBotAutomergeVerdict(msg), true);
     console.error(`#${pr}: ${msg} \u2014 not enabling auto-merge`);
     process.exitCode = 1;
     return;
   }
+  const view = fetched.value;
   const prView = {
     author: view.author?.login ?? "",
     headRefName: view.headRefName,
@@ -282,9 +328,11 @@ async function runEnable(repo, pr, args) {
     console.log(`#${pr}: not eligible \u2014 ${verdict2.reason}`);
     return;
   }
-  const enabled = await enableAutoMerge(repo, pr, args.cwd);
-  if (!enabled) {
-    console.error(`#${pr}: eligible (${verdict2.reason}) but failed to enable auto-merge`);
+  const mergeFailure = await enableAutoMerge(repo, pr, args.cwd);
+  if (mergeFailure !== null) {
+    console.error(
+      `#${pr}: eligible (${verdict2.reason}) but failed to enable auto-merge \u2014 ${mergeFailure}`
+    );
     process.exitCode = 1;
     return;
   }

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  *
  * The classification + enablement implementation (and the `ai-bot-automerge` bin)
  * lives alongside it; this module is intentionally the narrow, frozen surface the
- * reusable workflow and consumers depend on. Extracted per rmartz/ai-tools#264.
+ * bot-automerge-action and consumers depend on. Extracted per rmartz/ai-tools#264.
  */
 /**
  * The operations the `ai-bot-automerge` CLI dispatches:
@@ -45,11 +45,15 @@ declare const DEPENDABOT_AUTHORS: readonly ["dependabot[bot]", "app/dependabot"]
 declare function isDependabotAuthor(login: string): boolean;
 /**
  * The head-branch prefix release-please gives its release PR (e.g.
- * `release-please--branches--main`). Either this prefix OR the pending label
- * below marks a PR as a release-please release PR.
+ * `release-please--branches--main`). This prefix alone marks a PR as a
+ * release-please release PR.
  */
 declare const RELEASE_PLEASE_BRANCH_PREFIX = "release-please--";
-/** The label release-please applies to its open release PR. */
+/**
+ * The label release-please applies to its open release PR. Informational only:
+ * it is NOT an eligibility signal, because anyone with triage permission can
+ * apply it to any PR (GHSA-4f7f-7fcp-gcm6).
+ */
 declare const RELEASE_PLEASE_PENDING_LABEL = "autorelease: pending";
 /**
  * The Dependabot semver update-type, as emitted verbatim by

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@rmartz/bot-automerge",
-  "version": "0.2.1",
-  "description": "Enables GitHub-native auto-merge for trustworthy bot pull requests (Dependabot patch/minor bumps and release-please release PRs), distributed via a reusable workflow kept current by Dependabot.",
+  "version": "1.0.2",
+  "description": "Enables GitHub-native auto-merge for trustworthy bot pull requests (Dependabot patch/minor bumps and release-please release PRs), distributed via rmartz/bot-automerge-action.",
   "keywords": [
     "ci",
     "bot-automerge",
     "auto-merge",
     "github-actions",
-    "reusable-workflow",
     "dependabot"
   ],
   "homepage": "https://github.com/rmartz/bot-automerge#readme",
@@ -50,12 +49,12 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "@typescript-eslint/eslint-plugin": "^8.70.0",
     "@typescript-eslint/parser": "^8.70.0",
     "@vitest/coverage-v8": "^5.0.1",
     "conventional-changelog-conventionalcommits": "^9.1.0",
-    "eslint": "^10.10.0",
+    "eslint": "^10.11.0",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
     "prettier": "^3.9.6",