@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schalkneethling/calavera-skill-npm-trusted-publishing-github-workflow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "npm trusted publishing GitHub workflow artifact for Calavera.",
   "license": "MIT",
   "repository": {

package/payload/npm-trusted-publishing-github-workflow/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Generate, repair, or debug the GitHub Actions workflow FILE that performs an OIDC
   trusted publish of a pnpm package — the concrete publish.yml, its test → build →
   publish job shape, the package tarball artifact handoff, Node-version inference from
-  package.json, pnpm and runtime setup via pnpm/setup, the npm-CLI-version upgrade step, and
+  package.json, version-aware pnpm and runtime setup, the npm-CLI-version upgrade step, and
   repository.url/Sigstore provenance matching. Use when the user wants the actual
   workflow written or fixed, or is debugging a specific CI failure: npm publish
   E404/E403/422, NODE_AUTH_TOKEN appearing unexpectedly, provenance or id-token errors,
@@ -24,23 +24,23 @@ Implement the same hardened npm trusted publishing pattern every time, without r
 
 This skill generates and debugs the publish workflow file. For the surrounding security posture — account and repository 2FA, branch protection, GitHub publish environments, release-strategy choice, and sole-maintainer risk — use the `npm-package-publishing` skill. The two are complementary: `npm-package-publishing` decides how publishing should be set up, this skill writes and fixes the YAML that does it.
 
-One number to keep consistent between the two: both skills use Node 24.8.0 or higher as the publish-step floor. Node 24.8.0 bundles npm 11.6.0, which already exceeds the npm CLI 11.5.1 minimum that trusted publishing requires, so on that floor no manual npm upgrade is needed. If a project must publish on an older Node, it has to upgrade npm to 11.5.1 or later first — the publish job retains a guard step for exactly that case.
+One number to keep consistent between the two: both skills use Node 24.8.0 or higher as the publish-step floor. Node 24.8.0 bundles npm 11.6.0, which already exceeds the npm CLI 11.5.1 minimum that trusted publishing requires, so on that floor no manual npm upgrade is needed. If a project must publish on an older supported Node, reject anything below Node 22.14.0 and upgrade npm only on Node 22.14.0 through 24.7.x.
 
 ## Workflow
 
 1. Inspect `package.json`, `.npmrc`, lockfiles, and existing `.github/workflows/*.yml`.
 2. Resolve every workflow dependency to its latest stable version at the moment the file is created, and pin each to the full-length commit SHA of that version. Never leave third-party or GitHub-owned actions pinned to tag-based refs such as `@v4`, `@v6`, or `@v7` in the final workflow; tag refs weaken supply-chain integrity and violate pinned-action policy. The SHAs in this skill's template are placeholders that will be out of date; never copy them verbatim. See "Pinning actions to current SHAs" below for the procedure.
 3. Preserve pinned action SHAs when they already exist; annotate each with a version comment so Dependabot can bump it.
-4. Drive the test and build jobs' Node version from the project's **existing** target, not from a number invented for this workflow. Read it from the repo's current `devEngines.runtime`, `.nvmrc`, `.node-version`, `volta.node`, or CI config; if none exists, ask the developer rather than guessing. For pnpm projects, prefer `pnpm/setup` and either let it read `devEngines.runtime` from `package.json` or set its `runtime` input to the resolved existing target, such as `node@22`. Do not point runtime selection at `engines.node`, which is the consumer compatibility range — an unbounded range like `>=20` can float CI away from the version developers actually run.
-5. Never raise the project's Node version, create a new `.nvmrc`, or overwrite an existing one to "match" the publish step. The publish step's Node 24.8.0 (step 11) is an isolated requirement of the publish action and must not propagate to `.nvmrc`, to `engines.node`, or to the test and build jobs. A project that targets Node 22 keeps testing and building on Node 22; only the final `npm publish` invocation runs on 24.8.0, and it does not rebuild the artifact. Conflating these two numbers is the most likely way this skill is misapplied — do not do it.
-6. Ensure every job that reads the repo (including any reading `.nvmrc`) runs `actions/checkout` first.
-7. For pnpm workflows, use `pnpm/setup` from the GitHub Marketplace instead of combining `pnpm/action-setup` with `actions/setup-node`. It installs pnpm from `@pnpm/exe` and installs the requested JavaScript runtime through `pnpm runtime set` in one step. Pin it to a full commit SHA like every other action.
-8. Set `install: false` on `pnpm/setup` in release/publish workflows, then run `pnpm install --frozen-lockfile --ignore-scripts` explicitly. The action can auto-install by default, but release workflows should keep install flags visible and hardened.
+4. Resolve the pnpm major from the exact `packageManager` value before selecting setup actions. For pnpm 11 or newer, use `pnpm/setup`. For pnpm 10 or older, use `pnpm/action-setup` together with `actions/setup-node`; `pnpm/setup` cannot install those versions. Do not guess or float the pnpm major.
+5. Drive the test and build jobs' Node version from the project's **existing** target, not from a number invented for this workflow. Read it from `devEngines.runtime`, `.nvmrc`, `.node-version`, `volta.node`, or existing CI; if none exists, ask rather than guessing. With pnpm 11 or newer, let `pnpm/setup` read `devEngines.runtime` or pass the resolved target as `runtime`. With pnpm 10 or older, pass the same target to `actions/setup-node`. Never use `engines.node`, which is the consumer compatibility range, as the CI runtime selector.
+6. Never raise the project's Node version, create a new `.nvmrc`, or overwrite an existing one to "match" the publish step. The publish step's Node 24.8.0 is isolated and must not propagate to development, test, or build targets.
+7. Ensure every job that reads the repo runs `actions/checkout` first.
+8. Disable automatic installation in the selected pnpm setup action, then run `pnpm install --frozen-lockfile --ignore-scripts` explicitly so release install flags stay visible and hardened.
 9. Do not use Corepack in release workflows: it is still marked experimental and downloads the package manager from the network on first use, which is an avoidable failure surface in a release pipeline.
 10. Set `persist-credentials: false` on every `actions/checkout` step. Never rely on checkout's default credential persistence. If a workflow genuinely must push to git, use an explicit, narrowly scoped credential only for that push step.
-11. Target Node 24.8.0 or higher in the publish step. That floor bundles npm 11.6.0, which already exceeds the npm CLI 11.5.1 minimum trusted publishing requires, so no manual npm upgrade is needed there. Keep a guard step that upgrades npm only when the resolved Node ships an npm below 11.5.1, so the workflow stays correct if a project pins an older Node. An npm that is too old silently falls back to token auth or fails to attempt OIDC at all.
-12. Pack into a dedicated artifact directory, usually `package/*.tgz`.
-13. In the publish job, download the artifact to `package`, find the `.tgz`, and publish its resolved path.
+11. Target Node 24.8.0 or higher in the publish step. If a lower version is unavoidable, reject Node below 22.14.0 before any npm upgrade, upgrade npm only on Node 22.14.0 through 24.7.x, and require npm 11.5.1 or newer.
+12. Pack into a unique directory under `RUNNER_TEMP`, keyed by the workflow run and attempt.
+13. In the publish job, download the artifact to the corresponding `RUNNER_TEMP` directory, find the `.tgz`, and publish its resolved path.
 14. Use GitHub OIDC trusted publishing, not npm tokens. Provenance is generated automatically under trusted publishing, so the `--provenance` flag is not required.
 15. Add a `concurrency` group keyed on the release so two tag pushes cannot race into overlapping publishes.
 
@@ -83,19 +83,57 @@ The publish-step version must never be copied into the other two. Do not raise `
 
 The `engines.node` value above is the _consumer_ floor and should reflect what the package actually supports; `>=20` is only an example, and a bounded upper limit is sensible if the package genuinely needs one. Do not raise it to 24.8.0 to satisfy CI — the publish step pins its own Node version, and the test and build jobs read theirs from `devEngines.runtime` or another existing project target, so the trusted-publishing requirement never leaks into the consumer contract.
 
-For pnpm projects, prefer declaring the development runtime in `devEngines.runtime` so `pnpm/setup`
-can read the runtime and version from `package.json`. If the repo already uses `.nvmrc`,
-`.node-version`, `volta.node`, or existing CI config instead, keep that source of truth and set
-`pnpm/setup`'s `runtime` input to the same resolved version. Do not default to the publish step's
-24.8.0.
+For pnpm 11-or-newer projects, prefer declaring the development runtime in `devEngines.runtime` so
+`pnpm/setup` can read it from `package.json`. If the repo already uses `.nvmrc`, `.node-version`,
+`volta.node`, or existing CI instead, keep that source of truth and set `pnpm/setup`'s `runtime`
+input to the same resolved version. For pnpm 10 or older, pass that target to `actions/setup-node`.
+Do not default test or build jobs to the publish step's 24.8.0.
 
 The `repository.url` field is not cosmetic. Provenance verification runs through Sigstore, which compares the repository in the OIDC token against `package.json`. A mismatch fails the publish with a 422 error that the user-facing npm docs do not explain. Make sure the owner/name in `repository.url` matches the repository actually running the workflow.
 
-Do not add npm auth tokens for trusted publishing.
+Trusted publishing itself must not receive `NODE_AUTH_TOKEN`. A project that installs private dependencies may expose a read-only token only on the dependency-install step. Keep registry mapping and the environment reference in the checked-in `.npmrc`, never a token value. Do not persist the token through setup, build, pack, or publish steps. Run `npm publish` from an isolated directory under `RUNNER_TEMP` so npm does not discover the repository's private-install `.npmrc`.
+
+```ini
+@OWNER:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+```yaml
+- name: Install dependencies
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.READ_ONLY_PACKAGES_TOKEN }}
+  run: pnpm install --frozen-lockfile --ignore-scripts
+```
 
 ## Workflow Template
 
-Use this shape for pnpm packages, adapting only names, test commands, and existing pinned action SHAs. The `@<sha>` values below are **placeholders**: before writing the file, resolve each action to its latest stable release and replace the placeholder with that release's full-length commit SHA, keeping the `# vX.Y.Z` comment accurate. Do not copy the example SHAs — see "Pinning actions to current SHAs".
+Use this shape for pnpm 11-or-newer packages, adapting names, test commands, and pinned action SHAs. Verify the exact pnpm major from `packageManager` first. For pnpm 10 or older, replace every test/build `pnpm/setup` step with pinned `pnpm/action-setup` (`run_install: false`) plus pinned `actions/setup-node` using the resolved project Node target. In the publish job, use pinned `actions/setup-node` with Node 24.8.0 or newer; pnpm is not needed after the tarball is downloaded.
+
+The `@<sha>` values below are **placeholders**: resolve each action to its latest stable release and replace the placeholder with that release's full-length commit SHA, keeping the version comment accurate. Do not copy the example SHAs.
+
+For pnpm 10 or older, use this concrete setup shape in both test and build jobs:
+
+```yaml
+- name: Setup pnpm
+  uses: pnpm/action-setup@2222222222222222222222222222222222222222 # PLACEHOLDER SHA, re-resolve before use
+  with:
+    version: 10 # Replace with the exact project major or version.
+    run_install: false
+
+- name: Setup Node.js
+  uses: actions/setup-node@3333333333333333333333333333333333333333 # PLACEHOLDER SHA, re-resolve before use
+  with:
+    node-version: "22" # Replace with the resolved existing project target.
+```
+
+In the pnpm-10 publish job, only Node is required:
+
+```yaml
+- name: Setup Node.js for publish
+  uses: actions/setup-node@3333333333333333333333333333333333333333 # PLACEHOLDER SHA, re-resolve before use
+  with:
+    node-version: "24.8.0"
+```
 
 ```yaml
 # NOTE: every action SHA below is a PLACEHOLDER and is almost certainly out of date.
@@ -123,7 +161,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2 — PLACEHOLDER SHA, re-resolve before use
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 — PLACEHOLDER SHA, re-resolve before use
         with:
           persist-credentials: false
 
@@ -153,7 +191,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2 — PLACEHOLDER SHA, re-resolve before use
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 — PLACEHOLDER SHA, re-resolve before use
         with:
           persist-credentials: false
 
@@ -169,16 +207,19 @@ jobs:
         run: pnpm install --frozen-lockfile --ignore-scripts
 
       - name: Create package directory
-        run: mkdir package
+        run: |
+          package_dir="${RUNNER_TEMP}/npm-package-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          mkdir -p "$package_dir"
+          echo "PACKAGE_DIR=$package_dir" >> "$GITHUB_ENV"
 
       - name: Create package tarball
-        run: pnpm pack --pack-destination package
+        run: pnpm pack --pack-destination "$PACKAGE_DIR"
 
       - name: Upload package tarball
         uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1 — PLACEHOLDER SHA, re-resolve before use
         with:
           name: npm-package
-          path: package/*.tgz
+          path: ${{ runner.temp }}/npm-package-${{ github.run_id }}-${{ github.run_attempt }}/*.tgz
           if-no-files-found: error
           retention-days: 7
 
@@ -193,7 +234,7 @@ jobs:
       id-token: write
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.2.2 — PLACEHOLDER SHA, re-resolve before use
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 — PLACEHOLDER SHA, re-resolve before use
         with:
           persist-credentials: false
 
@@ -206,61 +247,75 @@ jobs:
           install: false
 
       - name: Ensure npm is new enough for trusted publishing
-        # No-op on Node >= 24.8.0; the guard only matters if Node is pinned lower.
         run: |
-          required="11.5.1"
+          minimum_node="22.14.0"
+          no_upgrade_node="24.8.0"
+          required_npm="11.5.1"
           pinned_npm="11.6.0"
-          current="$(npm --version)"
-          if node - "$current" "$required" <<'NODE'
-          const [current, required] = process.argv.slice(2);
-          const parse = (version) => version.split(".").map((part) => Number.parseInt(part, 10));
-          const [currentMajor, currentMinor, currentPatch] = parse(current);
-          const [requiredMajor, requiredMinor, requiredPatch] = parse(required);
-          const currentParts = [currentMajor, currentMinor, currentPatch];
-          const requiredParts = [requiredMajor, requiredMinor, requiredPatch];
-          let isBelow = false;
-          for (const [index, part] of currentParts.entries()) {
-            if (part !== requiredParts[index]) {
-              isBelow = part < requiredParts[index];
-              break;
+          version_at_least() {
+            node - "$1" "$2" <<'NODE'
+          const [current, required] = process.argv.slice(2).map((version) =>
+            version.split(".").map((part) => Number.parseInt(part, 10)),
+          );
+          for (let index = 0; index < 3; index += 1) {
+            if (current[index] !== required[index]) {
+              process.exit(current[index] > required[index] ? 0 : 1);
             }
           }
-          process.exit(isBelow ? 1 : 0);
           NODE
-          then
-            echo "npm $current satisfies $required."
+          }
+
+          node_version="$(node --version | sed 's/^v//')"
+          current_npm="$(npm --version)"
+          if ! version_at_least "$node_version" "$minimum_node"; then
+            echo "Trusted publishing requires Node $minimum_node or newer; found $node_version." >&2
+            exit 1
+          fi
+
+          if version_at_least "$current_npm" "$required_npm"; then
+            echo "npm $current_npm satisfies $required_npm."
+          elif version_at_least "$node_version" "$no_upgrade_node"; then
+            echo "Node $node_version unexpectedly provides npm $current_npm; refusing a global npm mutation." >&2
+            exit 1
           else
-            echo "npm $current is below $required; upgrading to pinned npm $pinned_npm."
+            echo "npm $current_npm is below $required_npm; upgrading to pinned npm $pinned_npm."
             npm install -g "npm@$pinned_npm"
           fi
-          npm --version
+          version_at_least "$(npm --version)" "$required_npm"
 
       - name: Download package tarball
         uses: actions/download-artifact@cc203385981b70ca67e1cc392babf9cc229d5806 # v4.1.9 — PLACEHOLDER SHA, re-resolve before use
         with:
           name: npm-package
-          path: package
+          path: ${{ runner.temp }}/npm-package-${{ github.run_id }}-${{ github.run_attempt }}
 
       - name: Publish to npm
         run: |
-          tarball="$(find package -type f -name '*.tgz' -print -quit)"
+          package_dir="${RUNNER_TEMP}/npm-package-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          tarball="$(find "$package_dir" -type f -name '*.tgz' -print -quit)"
 
           if [ -z "$tarball" ]; then
             echo "No package tarball found in downloaded artifact."
-            find package -maxdepth 3 -type f -print
+            find "$package_dir" -maxdepth 3 -type f -print
             exit 1
           fi
 
-          npm publish "$(realpath "$tarball")" --ignore-scripts --access public --registry https://registry.npmjs.org
+          tarball="$(realpath "$tarball")"
+          publish_dir="${RUNNER_TEMP}/npm-publish-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          mkdir -p "$publish_dir"
+          cd "$publish_dir"
+          npm publish "$tarball" --ignore-scripts --registry https://registry.npmjs.org
 ```
 
+Do not add `--access public` unconditionally. Prefer explicit package metadata such as `publishConfig.access` when public access is required, and preserve private or restricted package intent.
+
 ## Pinning actions to current SHAs
 
 The template's SHAs are stale by design. Action versions and their commit SHAs change over time, so resolve them fresh whenever a `publish.yml` is created or reviewed. Pin to the full-length commit SHA, never a tag or branch, because a tag can be moved to point at malicious code after you have reviewed it. Tag-based refs such as `@v4`, `@v6`, and `@v7` are acceptable only as temporary input to a pinning tool; they must not survive in committed workflow YAML.
 
 There are two reliable ways to produce current pins.
 
-The preferred approach is to let tooling resolve and pin for you. Write the workflow first using human-readable tags only in the temporary draft consumed by the tool (for example `actions/checkout@v4`), then run `npx actions-up@1.16.0` in the repository to rewrite every `uses:` reference to the latest stable release pinned to its commit SHA, with a version comment appended. This is the same tool the `npm-package-publishing` skill recommends, and it removes the chance of a hand-typed SHA being wrong. After it runs, confirm each line carries a `@<40-hex-sha> # vX.Y.Z` form.
+The preferred approach is to let tooling resolve and pin for you. Write the workflow first using human-readable tags only in the temporary draft consumed by the tool, then run `npx actions-up@1.16.0 --yes` so the command is non-interactive. Confirm each line carries a `@<40-hex-sha> # vX.Y.Z` form.
 
 If resolving manually, for each action find the latest stable release tag, then read the exact commit that tag points to and pin that commit:
 
@@ -274,7 +329,7 @@ gh api repos/actions/checkout/git/refs/tags/v4.2.2 --jq .object.sha
 
 For an annotated tag the first lookup may return a tag object rather than a commit; dereference it with `gh api repos/<owner>/<repo>/git/tags/<sha> --jq .object.sha` to reach the underlying commit. Pin the commit SHA, not the tag SHA.
 
-Keep the pins current after creation by letting Dependabot manage action updates. This is why every `uses:` line carries a `# vX.Y.Z` comment: Dependabot reads the comment to know which version a SHA represents and to raise update PRs. The companion Dependabot configuration should include a `github-actions` ecosystem entry pointing at `/` so the publish workflow is covered. Periodically re-running `npx actions-up@1.16.0` is a reasonable backstop if Dependabot is not enabled.
+Keep the pins current after creation by letting Dependabot manage action updates. This is why every `uses:` line carries a `# vX.Y.Z` comment: Dependabot reads the comment to know which version a SHA represents and to raise update PRs. The companion Dependabot configuration should include a `github-actions` ecosystem entry pointing at `/` so the publish workflow is covered. Periodically re-running `npx actions-up@1.16.0 --yes` is a reasonable backstop if Dependabot is not enabled.
 
 ## Checks
 
@@ -300,25 +355,42 @@ if grep -n "PLACEHOLDER" .github/workflows/publish.yml; then
   exit 1
 fi
 
-# Every uses: line must reference a 40-hex SHA, not a tag
-if ! grep -qE "uses: [^@]+@" .github/workflows/publish.yml; then
-  echo "No uses lines found"
-  exit 1
-fi
-
-bad_refs="$(grep -nE "uses: [^@]+@[^ ]+" .github/workflows/publish.yml \
-  | grep -vE "@[0-9a-f]{40} " || true)"
-if [ -n "$bad_refs" ]; then
-  echo "$bad_refs"
-  echo "Unpinned action found" >&2
-  exit 1
-fi
-echo "All actions SHA-pinned"
+# Parse the actual YAML uses values so comments and unrelated text cannot satisfy the check.
+ruby <<'RUBY'
+require "yaml"
+
+uses = []
+walk = lambda do |value|
+  case value
+  when Hash
+    value.each do |key, child|
+      uses << child.to_s if key.to_s == "uses"
+      walk.call(child)
+    end
+  when Array
+    value.each { |child| walk.call(child) }
+  end
+end
+walk.call(YAML.load_file(".github/workflows/publish.yml"))
+
+abort "No uses entries found" if uses.empty?
+bad_refs = uses.reject do |ref|
+  next true if ref.start_with?("./", "docker://")
+
+  sha = ref[/@([0-9a-f]{40})\z/i, 1]
+  sha && !sha.match?(/\A(.)\1{39}\z/)
+end
+unless bad_refs.empty?
+  warn bad_refs.join("\n")
+  abort "Unpinned or placeholder action found"
+end
+puts "All actions SHA-pinned"
+RUBY
 ```
 
 ## Failure Clues
 
-- `NODE_AUTH_TOKEN: ***` appears in the publish log: token auth is being used or injected. Trusted publishing should not need it.
+- `NODE_AUTH_TOKEN: ***` appears in the publish log: token auth is being used or injected into the publish step. A read-only token is acceptable only on a private-dependency install step and must be absent afterward.
 - `E404 Not Found - PUT ... could not be found or you do not have permission`: often an auth/scope permission problem, especially if local manual publish works.
 - `422 Unprocessable Entity` during publish with provenance: the repository in the OIDC token does not match `package.json`. Check `repository.url` first.
 - npm silently publishing with a token despite trusted-publisher config: the runner's npm CLI is older than 11.5.1. This should not happen on the pinned Node 24.8.0 (which bundles npm 11.6.0); if the publish step was moved to an older Node, confirm the guard step actually upgraded npm and reported a version at or above 11.5.1.
@@ -334,7 +406,7 @@ Repo changes cannot create npm's trusted publisher entry. Remind the user to ver
 
 - provider: GitHub Actions
 - repository owner/name matches the repo
-- workflow filename matches `.github/workflows/publish.yml`
+- workflow filename matches `publish.yml` (filename only, including the extension)
 - publish environment matches the workflow if npm is configured with one
 - at least one allowed action is selected: configurations created after 20 May 2026 require explicitly selecting an allowed action (for example, allow `npm publish`), or the publish will be rejected