@devopsplaybook.io/common-utils 1.7.0-beta.16.a8b6bbc → 1.8.0-beta.17.1c8c436

package/.github/workflows/reusable-merge-build.yml

@@ -29,11 +29,14 @@ on:
         required: false
 
 # Immutable build strategy: the image validated on the pull request is promoted
-# as-is, so merging runs no build, lint or test. `pull-requests: read` is needed
-# to resolve which PR produced the commit pushed to the default branch.
+# as-is, so merging runs no build, lint or test.
+#
+# `contents: read` only. Callers run with the default read-only token, whose
+# ceiling is `contents: read, pull-requests: none`, so requesting anything more
+# here makes the caller fail to start with "Invalid workflow file". The PR is
+# therefore resolved without needing pull-request scopes.
 permissions:
   contents: read
-  pull-requests: read
 
 jobs:
   promote-image:
@@ -64,21 +67,33 @@ jobs:
           SERVICE_VERSION=$(jq -r '.version' package.json)
           IMAGE="${DOCKER_HUB_USERNAME}/${SERVICE_NAME}"
 
-          # Find the PR that produced this commit. Works for squash, rebase and
-          # merge commits.
+          PR_NUMBER=""
+          PR_SOURCE="none"
+
+          # Preferred: ask the API which PR introduced this commit. This needs
+          # `pull-requests: read`, which callers on the default token are not
+          # granted, so a failure here is expected rather than exceptional.
           PR_NUMBER=$(curl -sfL \
             -H "Authorization: Bearer ${GH_TOKEN}" \
             -H "Accept: application/vnd.github+json" \
             "${GITHUB_API_URL}/repos/${GITHUB_REPOSITORY}/commits/${GITHUB_SHA}/pulls" \
             | jq -r '.[0].number // empty' || true)
+          if [ -n "${PR_NUMBER}" ]; then
+            PR_SOURCE="api"
+          fi
 
-          # Fallback: read the PR number from the commit message, either
-          # "<title> (#123)" for squash/rebase or "Merge pull request #123".
+          # Fallback: parse the commit title, where GitHub writes the PR number
+          # for squash ("<title> (#123)") and merge ("Merge pull request #123")
+          # commits. Only the title is read, so a "fixes #99" reference in the
+          # commit body cannot select the wrong pull request.
           if [ -z "${PR_NUMBER}" ]; then
-            MESSAGE=$(git log -1 --pretty=%B)
-            PR_NUMBER=$(printf '%s' "${MESSAGE}" | grep -oE '\(#[0-9]+\)' | tail -1 | tr -d '(#)' || true)
+            TITLE=$(git log -1 --pretty=%s)
+            PR_NUMBER=$(printf '%s' "${TITLE}" | grep -oE '\(#[0-9]+\)' | tail -1 | tr -d '(#)' || true)
             if [ -z "${PR_NUMBER}" ]; then
-              PR_NUMBER=$(printf '%s' "${MESSAGE}" | grep -oE 'Merge pull request #[0-9]+' | grep -oE '[0-9]+' | tail -1 || true)
+              PR_NUMBER=$(printf '%s' "${TITLE}" | grep -oE 'Merge pull request #[0-9]+' | grep -oE '[0-9]+' | head -1 || true)
+            fi
+            if [ -n "${PR_NUMBER}" ]; then
+              PR_SOURCE="commit-title"
             fi
           fi
 
@@ -105,11 +120,14 @@ jobs:
             echo "service_name=${SERVICE_NAME}"
             echo "service_version=${SERVICE_VERSION}"
             echo "pr_number=${PR_NUMBER}"
+            echo "pr_source=${PR_SOURCE}"
             echo "source_image=${SOURCE_IMAGE}"
             echo "strategy=${STRATEGY}"
           } >> "${GITHUB_OUTPUT}"
 
-          echo "Service: ${SERVICE_NAME} ${SERVICE_VERSION}"
+          echo "Service:  ${SERVICE_NAME} ${SERVICE_VERSION}"
+          echo "PR:       ${PR_NUMBER:-none} (resolved via ${PR_SOURCE})"
+          echo "Source:   ${SOURCE_IMAGE:-none}"
           echo "Strategy: ${STRATEGY}"
 
       - name: Promote the PR image to the release tags

package/.github/workflows/reusable-npm-pr.yml

@@ -21,7 +21,37 @@ on:
         required: false
 
 jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Fetch main branch
+        run: git fetch origin main --depth=1
+
+      - name: Verify version is higher than main
+        run: |
+          PR_VERSION=$(jq -r '.version' package.json)
+          MAIN_VERSION=$(git show origin/main:package.json | jq -r '.version')
+
+          echo "PR version:   ${PR_VERSION}"
+          echo "Main version: ${MAIN_VERSION}"
+
+          if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
+            echo "::error::PR version (${PR_VERSION}) must be higher than main branch version (${MAIN_VERSION}). Please bump the version in package.json."
+            exit 1
+          fi
+
+          HIGHER=$(printf '%s\n%s' "$PR_VERSION" "$MAIN_VERSION" | sort -V | tail -n1)
+          if [ "$HIGHER" != "$PR_VERSION" ]; then
+            echo "::error::PR version (${PR_VERSION}) is lower than main branch version (${MAIN_VERSION}). Please bump the version in package.json."
+            exit 1
+          fi
+
+          echo "Version check passed: ${PR_VERSION} > ${MAIN_VERSION}"
+
   test-and-build:
+    needs: version-check
     runs-on: ubuntu-latest
 
     steps:

package/.github/workflows/reusable-pr-verify.yml

@@ -29,7 +29,37 @@ on:
         required: false
 
 jobs:
+  version-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Fetch main branch
+        run: git fetch origin main --depth=1
+
+      - name: Verify version is higher than main
+        run: |
+          PR_VERSION=$(jq -r '.version' package.json)
+          MAIN_VERSION=$(git show origin/main:package.json | jq -r '.version')
+
+          echo "PR version:   ${PR_VERSION}"
+          echo "Main version: ${MAIN_VERSION}"
+
+          if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
+            echo "::error::PR version (${PR_VERSION}) must be higher than main branch version (${MAIN_VERSION}). Please bump the version in package.json."
+            exit 1
+          fi
+
+          HIGHER=$(printf '%s\n%s' "$PR_VERSION" "$MAIN_VERSION" | sort -V | tail -n1)
+          if [ "$HIGHER" != "$PR_VERSION" ]; then
+            echo "::error::PR version (${PR_VERSION}) is lower than main branch version (${MAIN_VERSION}). Please bump the version in package.json."
+            exit 1
+          fi
+
+          echo "Version check passed: ${PR_VERSION} > ${MAIN_VERSION}"
+
   node-build:
+    needs: version-check
     if: inputs.node_app_directories != ''
     strategy:
       matrix:
@@ -106,6 +136,7 @@ jobs:
           fi
 
   docker-build:
+    needs: version-check
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7

package/AGENTS.md

@@ -54,6 +54,7 @@ src/
 - **SQLite-first SQL**: Write SQL with `?` placeholders. The `DbUtils` facade and `DbUtilsNoTelemetry` module auto-convert to `$1, $2, ...` for Postgres via `convertToPostgresPlaceholders()`.
 - **Migration convention**: SQL files named `init-NNNN.sql`. `init-0000.sql` must create the `metadata` table. Subsequent files are applied in lexicographic order; applied versions are tracked in `metadata` for idempotency.
 - **Immutable Docker builds**: images are built once on the pull request (`reusable-pr-verify.yml` pushes `beta-pr-<PR number>` and `beta`) and promoted unchanged on merge (`reusable-merge-build.yml` writes `<version>`, `<major>`, `<minor>` and `latest`). The merge workflow runs no build, lint or test: it resolves the merged PR, carbon-copies the manifest with `docker buildx imagetools create --prefer-index=false`, then reads back each published digest and fails on a mismatch. It falls back to a full build only when no `beta-pr-<PR number>` image can be promoted. Image name and version come from the root `package.json`, and PR branches must be up to date with the default branch before merging.
+- **Reusable workflow permissions ceiling**: `reusable-merge-build.yml` may request only `contents: read`. A called workflow cannot exceed its caller's permissions, and callers use the default read-only token whose ceiling is `contents: read, pull-requests: none`. Adding `pull-requests: read` does not fail here — it fails in every consuming repo at startup with `Invalid workflow file ... requesting 'pull-requests: read', but is only allowed 'pull-requests: none'`. `GET /repos/{owner}/{repo}/commits/{sha}/pulls` works with `contents: read`, so no extra scope is needed.
 
 ## Build and Verification
 

package/README.md

@@ -539,16 +539,31 @@ Docker images are built **once**, on the pull request, and **promoted** on merge
 
 On merge the workflow:
 
-1. Resolves the pull request behind the commit pushed to the default branch through `GET /repos/{owner}/{repo}/commits/{sha}/pulls`, falling back to the PR number in the commit message (`<title> (#123)` for squash and rebase, `Merge pull request #123` for merge commits).
+1. Resolves the pull request behind the commit pushed to the default branch through `GET /repos/{owner}/{repo}/commits/{sha}/pulls`, falling back to the PR number in the commit **title** (`<title> (#123)` for squash and rebase, `Merge pull request #123` for merge commits). Only the title is parsed, so a `fixes #99` reference in the commit body cannot select the wrong pull request.
 2. Carbon-copies the manifest with `docker buildx imagetools create --prefer-index=false`, which preserves the exact digest and the full multi-platform image index.
 3. Reads back the digest of every tag it published and fails if one differs from the source.
 
-No `npm ci`, build, lint or test runs on merge, and no Docker build happens unless promotion is impossible. The build fallback keeps releases working when a commit reaches the default branch with no matching `beta-pr-<PR number>` image, such as a direct push or a PR whose image was deleted from the registry.
+The resolve step logs how it reached its answer, which is the first thing to check when a merge falls back to a build:
+
+```text
+Service:  planner-llm-agent 0.2.0
+PR:       2 (resolved via api)
+Source:   <namespace>/planner-llm-agent:beta-pr-2
+Strategy: retag
+```
+
+`Strategy` is `retag` when the PR image was found and `build` when it was not.
+
+No `npm ci`, build, lint or test runs on merge, and no Docker build happens unless promotion is impossible. The build fallback keeps releases working when a commit reaches the default branch with no matching `beta-pr-<PR number>` image, such as a direct push, a rebase merge (which leaves no PR number in the commit title), or a PR whose image was deleted from the registry.
+
+> **Callers need no `permissions:` block.** `reusable-merge-build` requests only `contents: read`. A reusable workflow cannot ask for more than its caller is allowed, and the default read-only token ceiling is `contents: read, pull-requests: none` — requesting `pull-requests: read` makes the caller fail to start with `Invalid workflow file … The workflow is requesting 'pull-requests: read', but is only allowed 'pull-requests: none'`. The API lookup above works with `contents: read` alone.
 
 The image name and version come from the root `package.json`, so bump the minor version in the pull request that carries the change.
 
 > **Keep PR branches up to date with the default branch before merging.** The promoted image is the one built from the PR head, so if the default branch moved in the meantime the released artifact will not contain those commits.
 
+Validated end to end on `planner-llm-agent` 0.2.0: the pull request pushed `beta-pr-2` and `beta`, the merge promoted that image in **40 seconds** with no build, and `beta-pr-2`, `beta`, `0.2.0`, `0.2`, `0` and `latest` all resolve to the single digest `sha256:710fed19…` with identical per-architecture digests.
+
 ### Adopting in Your Project
 
 Create a caller workflow in `.github/workflows/main-build.yml`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.7.0-beta.16.a8b6bbc",
+  "version": "1.8.0-beta.17.1c8c436",
   "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, auth/users, notifications, LLM, system helpers)",
   "keywords": [
     "Open Telemetry",