@codfish/actions 0.0.0-PR-58--24ced07

package/npm-publish-pr/action.yml

@@ -0,0 +1,362 @@
+name: npm-pr-version
+
+description:
+  Publishes package with PR-specific version (0.0.0-PR-123--abc1234) using detected package manager (npm/yarn/pnpm) or
+  OIDC trusted publishing, and automatically comments on PR
+
+inputs:
+  npm-token:
+    required: false
+    description:
+      Registry authentication token with publish permissions. If not provided, OIDC trusted publishing will be used.
+  tarball:
+    required: false
+    description:
+      Path to pre-built tarball to publish (e.g., '*.tgz'). When provided, publishes the tarball with --ignore-scripts
+      for security. Recommended for pull_request_target workflows to prevent execution of malicious lifecycle scripts.
+  comment:
+    required: false
+    default: 'true'
+    description: Whether to comment on the PR with the published version (true/false)
+  comment-tag:
+    required: false
+    default: npm-publish-pr
+    description: Tag to use for PR comments (for comment identification and updates)
+  dev:
+    required: false
+    default: 'false'
+    description: If true, use dev dependency install syntax in the PR comment (e.g. npm install -D, pnpm add -D).
+
+outputs:
+  version:
+    description: Generated PR-specific version number (0.0.0-PR-{number}--{short-sha})
+    value: '${{ steps.publish.outputs.version }}'
+  package-name:
+    description: Package name from package.json
+    value: '${{ steps.publish.outputs.package-name }}'
+  error-message:
+    description: Error message if publish fails
+    value: '${{ steps.publish.outputs.error-message }}'
+
+runs:
+  using: composite
+
+  steps:
+    - uses: codfish/actions/comment@v3
+      if: inputs.comment == 'true'
+      with:
+        message: ⏳ Publishing PR version...
+        upsert: true
+        tag: ${{ inputs.comment-tag }}
+
+    - name: Validate and publish to registry
+      id: publish
+      shell: bash
+      run: |
+        set +e # Don't exit on error so we can handle failures
+
+        # Initialize outputs for error handling
+        error_message=""
+        package_name=""
+        version=""
+        package_manager="npm"
+        tarball_mode=false
+        NPMRC_AUTH_FILE=""
+        REPACK_DIR=""
+
+        # Clean up on exit: remove temp auth file (never touch project .npmrc), temp files, repack dir
+        cleanup() {
+          local exit_code=$?
+          [ -n "$NPMRC_AUTH_FILE" ] && rm -f "$NPMRC_AUTH_FILE" 2>/dev/null || true
+          [ -n "$temp_pkg_json" ] && rm -f "$temp_pkg_json" 2>/dev/null || true
+          [ -n "$REPACK_DIR" ] && rm -rf "$REPACK_DIR" 2>/dev/null || true
+          return $exit_code
+        }
+        trap cleanup EXIT
+
+        # Detect if tarball mode is being used
+        if [ -n "$INPUT_TARBALL" ]; then
+          tarball_mode=true
+          echo "🔒 SECURE MODE: Using pre-built tarball (lifecycle scripts will NOT execute)"
+
+          # Expand glob patterns (e.g., *.tgz) to actual filename
+          shopt -s nullglob
+          tarball_files=($INPUT_TARBALL)
+          shopt -u nullglob
+
+          if [ ${#tarball_files[@]} -eq 0 ]; then
+            error_message="❌ ERROR: No tarball files found matching pattern: $INPUT_TARBALL"
+            echo "$error_message"
+            echo "error-message=$error_message" >> $GITHUB_OUTPUT
+            exit 1
+          elif [ ${#tarball_files[@]} -gt 1 ]; then
+            error_message="❌ ERROR: Multiple tarball files found matching pattern: $INPUT_TARBALL (found: ${tarball_files[*]}). Please specify a single tarball file."
+            echo "$error_message"
+            echo "error-message=$error_message" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Use the resolved tarball path
+          INPUT_TARBALL="${tarball_files[0]}"
+          echo "📦 Resolved tarball: $INPUT_TARBALL"
+        fi
+
+        # Function to extract relevant error message from npm output
+        extract_error() {
+          local output="$1"
+
+          # Extract npm error lines (lines starting with "npm error")
+          local error_lines=$(echo "$output" | grep "^npm error" | head -5)
+
+          # If we found error lines, use those
+          if [ -n "$error_lines" ]; then
+            echo "$error_lines" | tr '\n' ' ' | tr -s ' '
+          else
+            # Otherwise, take the last few lines (likely contains the error)
+            echo "$output" | tail -10 | tr '\n' ' ' | tr -s ' ' | cut -c1-500
+          fi
+        }
+
+        # Standardized publish error handler
+        handle_publish_error() {
+          local manager_name="$1"
+          local publish_output="$2"
+          local extracted_error=""
+
+          extracted_error=$(extract_error "$publish_output")
+          error_message="❌ Failed to publish with ${manager_name}: ${extracted_error}"
+          echo "Full output: $publish_output"
+          echo "Error message: $error_message"
+          echo "error-message=$error_message" >> $GITHUB_OUTPUT
+          exit 1
+        }
+
+        # In tarball mode: unpack, inject PR version, repack (so we publish a unique version)
+        # In normal mode, validate package.json
+        if [ "$tarball_mode" = true ]; then
+          # Validate tarball exists
+          if [ ! -f "$INPUT_TARBALL" ]; then
+            error_message="❌ ERROR: Tarball not found at path: $INPUT_TARBALL"
+            echo "$error_message"
+            echo "error-message=$error_message" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          echo "📦 Unpacking tarball and injecting PR version: $INPUT_TARBALL"
+
+          # Unpack to temp dir (npm pack format: top-level "package/" with package.json inside)
+          repack_dir=$(mktemp -d)
+          REPACK_DIR="$repack_dir"
+          tar -xzf "$INPUT_TARBALL" -C "$repack_dir"
+
+          if [ ! -f "$repack_dir/package/package.json" ]; then
+            error_message="❌ ERROR: Could not extract package.json from tarball (expected package/package.json)"
+            echo "$error_message"
+            echo "error-message=$error_message" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          package_name=$(jq -r '.name // empty' "$repack_dir/package/package.json")
+          if [ -z "$package_name" ] || [ "$package_name" = "null" ]; then
+            error_message="❌ ERROR: Tarball's package.json must have a 'name' field"
+            echo "$error_message"
+            echo "error-message=$error_message" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Generate PR-specific version (same format as normal mode) so we don't overwrite published versions
+          version="0.0.0-PR-${PR}--$(echo ${SHA} | cut -c -7)"
+          jq --arg v "$version" '.version = $v' "$repack_dir/package/package.json" > "$repack_dir/package/package.json.tmp" && mv "$repack_dir/package/package.json.tmp" "$repack_dir/package/package.json"
+
+          # Repack for publish (still secure: --ignore-scripts used when publishing)
+          (cd "$repack_dir" && tar -czf repack.tgz package)
+          TARBALL_TO_PUBLISH="$repack_dir/repack.tgz"
+
+          echo "📦 Tarball package: $package_name@$version (PR version)"
+          echo "package-name=$package_name" >> $GITHUB_OUTPUT
+          echo "version=$version" >> $GITHUB_OUTPUT
+        else
+          # Normal mode: validate package.json exists in current directory
+          if [ ! -f "package.json" ]; then
+            error_message="❌ ERROR: package.json not found in current directory. Make sure you're running this action in a directory with a package.json file"
+            echo "$error_message"
+            echo "error-message=$(extract_error "$error_message")" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Validate package.json is valid JSON
+          if ! jq empty package.json 2>/dev/null; then
+            error_message="❌ ERROR: package.json is not valid JSON"
+            echo "$error_message"
+            echo "error-message=$(extract_error "$error_message")" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Check if package has a name
+          package_name=$(jq -r '.name // empty' package.json)
+          if [ -z "$package_name" ] || [ "$package_name" = "null" ]; then
+            error_message="❌ ERROR: package.json must have a 'name' field"
+            echo "$error_message"
+            echo "error-message=$(extract_error "$error_message")" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+          # Output package name for use in error handling
+          echo "package-name=$package_name" >> $GITHUB_OUTPUT
+        fi
+
+        # Detect authentication mode and package manager
+        if [ -z "$INPUT_NPM_TOKEN" ]; then
+          echo "🔐 Using OIDC trusted publishing (no npm-token provided)"
+          echo "📦 Using npm for OIDC (--provenance requires npm)"
+
+          if [ -z "$ACTIONS_ID_TOKEN_REQUEST_URL" ]; then
+            error_message="❌ ERROR: OIDC token not available. Add 'permissions: { id-token: write }' to your workflow"
+            echo "$error_message"
+            echo "error-message=$error_message" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+        fi
+
+        if [ "$INPUT_NPM_TOKEN" ]; then
+          echo "🔐 Using token-based authentication"
+
+          # Token mode: use a temp userconfig file so we never overwrite or delete the project's .npmrc.
+          # npm merges NPM_CONFIG_USERCONFIG with project .npmrc, so custom registry/scoped config is preserved.
+          export NODE_AUTH_TOKEN="$INPUT_NPM_TOKEN"
+          NPMRC_AUTH_FILE=$(mktemp)
+          echo "//registry.npmjs.org/:_authToken=\${NODE_AUTH_TOKEN}" > "$NPMRC_AUTH_FILE"
+          export NPM_CONFIG_USERCONFIG="$NPMRC_AUTH_FILE"
+
+          # Detect package manager for token-based publishing
+          if [ -f "./yarn.lock" ]; then
+            package_manager="yarn"
+            echo "📦 Detected package manager: yarn"
+          elif [ -f "./pnpm-lock.yaml" ]; then
+            package_manager="pnpm"
+            echo "📦 Detected package manager: pnpm"
+          else
+            package_manager="npm"
+            echo "📦 Detected package manager: npm"
+          fi
+        fi
+
+        # Generate version (skip in tarball mode - already extracted)
+        if [ "$tarball_mode" = false ]; then
+          version="0.0.0-PR-${PR}--$(echo ${SHA} | cut -c -7)"
+          echo "📦 Publishing $package_name@$version with $package_manager"
+          echo "version=$version" >> $GITHUB_OUTPUT
+
+          # Update package.json version (all package managers support npm version)
+          version_output=$(npm version $version --no-git-tag-version 2>&1)
+          version_exit_code=$?
+          if [ $version_exit_code -ne 0 ]; then
+            error_message="❌ ERROR: Failed to update package version. Check if the version format is valid. Error: $version_output"
+            echo "$error_message"
+            echo "error-message=$(extract_error "$error_message")" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+        else
+          echo "📦 Publishing $package_name@$version from tarball"
+        fi
+
+        # Publish package
+        if [ "$tarball_mode" = true ]; then
+          # SECURE TARBALL MODE: Publish repacked tarball (PR version injected) with --ignore-scripts
+          echo "🔒 Publishing tarball with --ignore-scripts (secure mode)"
+
+          if [ -z "$INPUT_NPM_TOKEN" ]; then
+            # OIDC mode with tarball
+            publish_output=$(npm publish "$TARBALL_TO_PUBLISH" --access public --tag pr --provenance --ignore-scripts 2>&1)
+            publish_exit_code=$?
+
+            if [ $publish_exit_code -ne 0 ]; then
+              handle_publish_error "OIDC (tarball)" "$publish_output"
+            fi
+            echo "✅ Successfully published $package_name@$version using OIDC (secure tarball mode)"
+          else
+            # Token mode with tarball - always use npm for tarball publishing
+            publish_output=$(npm publish "$TARBALL_TO_PUBLISH" --access public --tag pr --ignore-scripts 2>&1)
+            publish_exit_code=$?
+
+            if [ $publish_exit_code -ne 0 ]; then
+              handle_publish_error "npm (tarball)" "$publish_output"
+            fi
+            echo "✅ Successfully published $package_name@$version using npm (secure tarball mode)"
+          fi
+        else
+          # NORMAL MODE: Traditional publishing (INSECURE for pull_request_target)
+          if [ -z "$INPUT_NPM_TOKEN" ]; then
+            echo "📦 Publishing with OIDC trusted publishing..."
+
+            publish_output=$(npm publish --access public --tag pr --provenance 2>&1)
+            publish_exit_code=$?
+
+            if [ $publish_exit_code -ne 0 ]; then
+              handle_publish_error "OIDC" "$publish_output"
+            fi
+            echo "✅ Successfully published $package_name@$version using OIDC"
+          else
+            # Token mode: use detected package manager
+            case "$package_manager" in
+              "yarn")
+                publish_output=$(yarn publish --access public --tag pr --new-version $version --no-git-tag-version --skip-check-working-tree 2>&1)
+                publish_exit_code=$?
+                if [ $publish_exit_code -ne 0 ]; then
+                  handle_publish_error "yarn" "$publish_output"
+                fi
+                ;;
+              "pnpm")
+                publish_output=$(pnpm publish --no-git-checks --access public --tag pr 2>&1)
+                publish_exit_code=$?
+                if [ $publish_exit_code -ne 0 ]; then
+                  handle_publish_error "pnpm" "$publish_output"
+                fi
+                ;;
+              *)
+                publish_output=$(npm publish --access public --tag pr 2>&1)
+                publish_exit_code=$?
+                if [ $publish_exit_code -ne 0 ]; then
+                  handle_publish_error "npm" "$publish_output"
+                fi
+                ;;
+            esac
+            echo "✅ Successfully published $package_name@$version using $package_manager"
+          fi
+        fi
+      env:
+        # CRITICAL: Use INPUT_NPM_TOKEN instead of NPM_TOKEN here to avoid
+        # setting NPM_TOKEN in the environment when empty (which could break OIDC)
+        INPUT_NPM_TOKEN: ${{ inputs.npm-token }}
+        INPUT_TARBALL: ${{ inputs.tarball }}
+        PR: ${{ github.event.number }}
+        SHA: ${{ github.event.pull_request.head.sha }}
+
+    - uses: codfish/actions/comment@v3
+      if: failure() && inputs.comment == 'true'
+      with:
+        message: |
+          ❌ **PR package publish failed!**
+
+          Error: ${{ steps.publish.outputs.error-message }}
+
+          📋 [View workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for more details.
+        upsert: true
+        tag: ${{ inputs.comment-tag }}
+
+    - uses: codfish/actions/comment@v3
+      if: success() && inputs.comment == 'true'
+      with:
+        message: |
+          ✅ **PR package published successfully!**
+
+          Install:
+
+              ${{ inputs.dev == 'true' && 'pnpm add -D ' || 'pnpm add ' }}${{ steps.publish.outputs.package-name }}@${{ steps.publish.outputs.version }}
+              ${{ inputs.dev == 'true' && 'npm install -D ' || 'npm install ' }}${{ steps.publish.outputs.package-name }}@${{ steps.publish.outputs.version }}
+              ${{ inputs.dev == 'true' && 'yarn add -D ' || 'yarn add ' }}${{ steps.publish.outputs.package-name }}@${{ steps.publish.outputs.version }}
+              ${{ inputs.dev == 'true' && 'bun add -d ' || 'bun add ' }}${{ steps.publish.outputs.package-name }}@${{ steps.publish.outputs.version }}
+
+          View on npm: https://www.npmjs.com/package/${{ steps.publish.outputs.package-name }}/v/${{ steps.publish.outputs.version }}
+        upsert: true
+        tag: ${{ inputs.comment-tag }}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@codfish/actions",
+  "type": "module",
+  "description": "Composite GitHub Actions for my projects.",
+  "author": "Chris O'Donnell <chris@codfish.dev>",
+  "license": "MIT",
+  "version": "0.0.0-PR-58--24ced07",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codfish/actions.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "comment",
+    "npm-publish-pr",
+    "setup-node-and-install",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.{json,css,md,yml}\" --config ./node_modules/@codfish/eslint-config/prettier.js",
+    "test": "bash tests/scripts/test-runner.sh",
+    "test:integration": "bash tests/scripts/test-runner.sh integration",
+    "test:unit": "bash tests/scripts/test-runner.sh unit",
+    "docs:generate": "node bin/generate-docs.js",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@codfish/eslint-config": "12.3.0",
+    "bats": "^1.13.0",
+    "doctoc": "^2.2.1",
+    "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "js-yaml": "^4.1.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "commitlint": {
+    "extends": [
+      "./node_modules/@codfish/eslint-config/commitlint.js"
+    ]
+  },
+  "lint-staged": {
+    "*.{json,css}": [
+      "prettier --write --config ./node_modules/@codfish/eslint-config/prettier.js"
+    ],
+    "*.md": [
+      "prettier --write --config ./node_modules/@codfish/eslint-config/prettier.js",
+      "doctoc --title '## Table of Contents'"
+    ]
+  }
+}

package/setup-node-and-install/README.md

@@ -0,0 +1,184 @@
+# setup-node-and-install
+
+Sets up Node.js environment and installs dependencies with automatic package manager detection, intelligent caching, and
+dynamic Node version detection via the `node-version` input, `.node-version`, `.nvmrc`, or `package.json` `volta.node`.
+
+This action provides the following functionality:
+
+- Automatically detects package manager (npm, yarn, or pnpm) from lockfiles
+- Uses GitHub's official `setup-node` action (v6) with optimized caching
+- **Upgrades npm to v11** (pinned to `^11.5.1` for OIDC trusted publishing support)
+- Installs dependencies with appropriate commands based on detected package manager
+- Supports `.node-version`, `.nvmrc`, and `package.json` `volta.node` for version specification
+- Intelligent caching of node_modules when lockfiles are present
+
+<!-- DOCTOC SKIP -->
+
+## Usage
+
+See [action.yml](action.yml).
+
+```yml
+steps:
+  - uses: actions/checkout@v6
+
+  # Will setup node, inferring node version from your codebase & installing your dependencies
+  - uses: codfish/actions/setup-node-and-install@v3
+
+  # Or if you want to be explicit
+  - uses: codfish/actions/setup-node-and-install@v3
+    with:
+      node-version: 24.4
+
+  - run: npm test
+```
+
+The `node-version` input is optional. If not supplied, this action will attempt to resolve a version using, in order:
+
+1. `.node-version`, 2) `.nvmrc`, 3) `package.json` `volta.node`. If none are present, `actions/setup-node` runs without
+   an explicit version and will use its default behavior.
+
+The `install-options` input is optional. If not supplied, the npm install commands will execute as defined without any
+additional options.
+
+**With `.nvmrc` file**
+
+```sh
+# .nvmrc
+v18.14.1
+```
+
+```yml
+steps:
+  - uses: actions/checkout@v6
+  # will install Node v18.14.1
+  - uses: codfish/actions/setup-node-and-install@v3
+  - run: npm test
+```
+
+**With `.node-version` file**
+
+```sh
+# .node-version
+20.10.0
+```
+
+```yml
+steps:
+  - uses: actions/checkout@v6
+  # will install Node v20.10.0
+  - uses: codfish/actions/setup-node-and-install@v3
+  - run: npm test
+```
+
+## Node Version Resolution Priority
+
+When multiple version specification methods are present, the action uses this priority order:
+
+1. **Input parameter** (`node-version`) - highest priority
+2. **`.node-version` file**
+3. **`.nvmrc` file**
+4. **`package.json` `volta.node` property**
+5. **`actions/setup-node` default behavior** when no version is specified
+
+## Inputs
+
+<!-- start inputs -->
+
+| Input               | Description                                                                                                                                                                                                                                                                                                     | Required | Default |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `node-version`      | Node.js version to install (e.g. "24", "lts/\*"). Precedence: node-version input > .node-version > .nvmrc > package.json volta.node.                                                                                                                                                                            | No       | -       |
+| `install-options`   | Extra command-line options to pass to npm/pnpm/yarn install.                                                                                                                                                                                                                                                    | No       | -       |
+| `working-directory` | Directory containing package.json and lockfile.                                                                                                                                                                                                                                                                 | No       | `.`     |
+| `registry-url`      | Optional registry URL to configure for publishing (e.g. "https://registry.npmjs.org/"). Creates .npmrc with NODE_AUTH_TOKEN placeholder. NOT recommended if using semantic-release (it handles auth independently). Only needed for publishing with manual npm publish or other non-semantic-release workflows. | No       | -       |
+| `upgrade-npm`       | Whether to upgrade npm to v11.5.1. This is required for OIDC trusted publishing but can be disabled if you want to shave off some run time and you are still using token-based authentication.                                                                                                                  | No       | `true`  |
+
+<!-- end inputs -->
+
+## Package Manager Detection
+
+The action automatically detects your package manager:
+
+- **pnpm**: Detected when `pnpm-lock.yaml` exists
+- **yarn**: Detected when `yarn.lock` exists
+- **npm**: Detected when `package-lock.json` exists or as fallback
+
+## npm Version Upgrade
+
+This action automatically upgrades npm to **v11** after Node.js setup (pinned to `^11.5.1`). This ensures:
+
+- npm 11.5.1+ is available for **OIDC trusted publishing** support (required as of January 2026)
+- Stable, predictable npm behavior across workflows
+- Security fixes and improvements within the v11 release line
+- No unexpected breaking changes from major version updates
+
+The upgrade happens transparently and is logged in the workflow output. The version is pinned to prevent unexpected
+breaking changes while still receiving patch and minor updates within v11.
+
+## Registry URL Configuration
+
+The `registry-url` input configures npm authentication by creating a `.npmrc` file with a `NODE_AUTH_TOKEN` placeholder.
+**In most cases, you should NOT set this parameter.**
+
+### When NOT to use registry-url (recommended)
+
+**Skip this parameter if:**
+
+- You're **only installing dependencies** (the primary use case for this action) - authentication is not needed for
+  public packages
+- You're using **semantic-release** for publishing - it handles npm authentication independently and `registry-url` can
+  cause conflicts
+  ([semantic-release docs](https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions#important-avoid-registry-url-in-setup-node))
+- You're using **OIDC trusted publishing** with npm - the upgraded npm v11 handles this automatically
+
+### When to use registry-url
+
+**Only set this parameter if:**
+
+- You're publishing to npm using **manual `npm publish`** (not semantic-release)
+- You need to authenticate to a **private npm registry**
+- You're using **legacy token-based publishing** and need the `.npmrc` file created
+
+### Example with registry-url
+
+```yml
+- uses: codfish/actions/setup-node-and-install@v3
+  with:
+    registry-url: 'https://registry.npmjs.org/'
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+- run: npm publish
+```
+
+## Examples
+
+### With specific Node version
+
+```yml
+- uses: codfish/actions/setup-node-and-install@v3
+  with:
+    node-version: '18'
+```
+
+### With pnpm in subdirectory
+
+```yml
+- uses: codfish/actions/setup-node-and-install@v3
+  with:
+    working-directory: './frontend'
+    install-options: '--frozen-lockfile'
+```
+
+## Migrating
+
+Replace multiple setup steps with this single action:
+
+```diff
+- - uses: actions/setup-node@v4
+-   with:
+-     node-version-file: '.nvmrc'
+-     cache: 'npm'
+- - run: npm ci --prefer-offline --no-audit
++ - uses: codfish/actions/setup-node-and-install@v3
+```