@codfish/actions 1.1.0

package/comment/README.md

@@ -0,0 +1,82 @@
+# comment
+
+Creates or updates pull request comments with intelligent upsert functionality using unique tags.
+
+<!-- DOCTOC SKIP -->
+
+## Usage
+
+See [action.yml](action.yml).
+
+```yaml
+- name: Comment on PR
+  uses: codfish/actions/comment@v1
+  with:
+    message: '✅ Build successful!'
+    tag: 'build-status'
+    upsert: true
+```
+
+## Inputs
+
+<!-- start inputs -->
+
+| Input     | Description                                                                           | Required | Default |
+| --------- | ------------------------------------------------------------------------------------- | -------- | ------- |
+| `message` | The comment message content (supports markdown formatting)                            | Yes      | -       |
+| `tag`     | Unique identifier to find and update existing comments (required when upsert is true) | No       | -       |
+| `upsert`  | Update existing comment with matching tag instead of creating new comment             | No       | `false` |
+
+<!-- end inputs -->
+
+## Examples
+
+### Basic comment
+
+```yaml
+- uses: codfish/actions/comment@v1
+  with:
+    message: 'Hello from GitHub Actions! 👋'
+```
+
+### Updating comments with upsert
+
+Use the `upsert` feature to update the same comment instead of creating multiple comments:
+
+```yaml
+- name: Update build status
+  uses: codfish/actions/comment@v1
+  with:
+    message: |
+      ## Build Status
+      ⏳ Build in progress...
+    tag: 'build-status'
+    upsert: true
+
+# Later in the workflow...
+- name: Update build status
+  uses: codfish/actions/comment@v1
+  with:
+    message: |
+      ## Build Status
+      ✅ Build completed successfully!
+    tag: 'build-status'
+    upsert: true
+```
+
+### Multi-line markdown comment
+
+```yaml
+- uses: codfish/actions/comment@v1
+  with:
+    message: |
+      ## 📊 Test Results
+
+      - ✅ Unit tests: 42 passed
+      - ✅ Integration tests: 12 passed
+      - 📦 Coverage: 98%
+
+      Great work! 🎉
+    tag: 'test-results'
+    upsert: true
+```

package/comment/action.yml

@@ -0,0 +1,102 @@
+name: comment
+
+description: Creates or updates a comment in a pull request with optional tagging for upsert functionality
+
+inputs:
+  message:
+    description: The comment message content (supports markdown formatting)
+    required: true
+  tag:
+    description: Unique identifier to find and update existing comments (required when upsert is true)
+    required: false
+  upsert:
+    description: Update existing comment with matching tag instead of creating new comment
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+
+  steps:
+    - name: Validate inputs and set globals
+      id: globals
+      shell: bash
+      run: |
+        # Validate required inputs
+        if [ -z "${{ inputs.message }}" ]; then
+          echo "❌ ERROR: 'message' input is required"
+          exit 1
+        fi
+
+        # Validate upsert logic
+        if [ "${{ inputs.upsert }}" = "true" ] && [ -z "${{ inputs.tag }}" ]; then
+          echo "❌ ERROR: 'tag' input is required when upsert is true"
+          exit 1
+        fi
+
+        # Create dynamic tag based on repository name
+        repo_namespace="${{ github.repository }}"
+        tag="<!-- ${repo_namespace}/comment ${{ inputs.tag }} -->"
+        body=$(printf '${{ inputs.message }}')
+
+        echo "💬 Comment tag: $tag"
+        echo "tag=$tag" >> $GITHUB_OUTPUT
+        echo "body<<EOF"$'\n'"$body"'\n'"$tag"$'\n'EOF >> "$GITHUB_OUTPUT"
+
+    - name: Check existing comments
+      id: check-comments
+      if: inputs.upsert == 'true'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          try {
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existingComment = comments.data.find(comment => comment.body.includes('${{ steps.globals.outputs.tag }}'));
+            core.setOutput('comment-id', existingComment ? existingComment.id : null);
+
+            if (existingComment) {
+              console.log(`Found existing comment with ID: ${existingComment.id}`);
+            } else {
+              console.log('No existing comment found, will create new one');
+            }
+          } catch (error) {
+            core.setFailed(`Failed to check existing comments: ${error.message}`);
+          }
+
+    - name: Update existing comment
+      if: steps.check-comments.outputs.comment-id != null
+      uses: actions/github-script@v7
+      with:
+        script: |
+          try {
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: ${{ steps.check-comments.outputs.comment-id }},
+              body: `${{ steps.globals.outputs.body }}`,
+            });
+            console.log('✅ Successfully updated existing comment');
+          } catch (error) {
+            core.setFailed(`Failed to update comment: ${error.message}`);
+          }
+
+    - name: Create new comment
+      if: steps.check-comments.outputs.comment-id == null
+      uses: actions/github-script@v7
+      with:
+        script: |
+          try {
+            const response = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: `${{ steps.globals.outputs.body }}`,
+            });
+            console.log(`✅ Successfully created new comment with ID: ${response.data.id}`);
+          } catch (error) {
+            core.setFailed(`Failed to create comment: ${error.message}`);
+          }

package/eslint.config.js

@@ -0,0 +1,8 @@
+import codfish from '@codfish/eslint-config';
+import { defineConfig } from 'eslint/config';
+
+export default defineConfig(codfish, {
+  rules: {
+    'no-console': 'off',
+  },
+});

package/npm-publish-pr/README.md

@@ -0,0 +1,145 @@
+# npm-pr-version
+
+Publishes packages with PR-specific version numbers for testing in downstream applications before merging. Automatically
+detects your package manager (npm, yarn, or pnpm) and uses the appropriate publish command. The action generates
+versions in the format `0.0.0-PR-{number}--{short-sha}` and automatically comments on the pull request with the
+published version.
+
+**Key Features:**
+
+- Automatic package manager detection (npm/yarn/pnpm)
+- Automatic PR version generation
+- Publishes to registry with `pr` tag
+- Automatic PR commenting with version info
+- No git history modification
+
+<!-- DOCTOC SKIP -->
+
+## Usage
+
+See [action.yml](action.yml).
+
+```yaml
+steps:
+  - uses: actions/checkout@v5
+
+  - uses: codfish/actions/setup-node-and-install@v1
+    with:
+      node-version: lts/*
+
+  - run: npm run build
+
+  - uses: codfish/actions/npm-pr-version@v1
+    with:
+      npm-token: ${{ secrets.NPM_TOKEN }}
+      github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Disable PR Comments
+
+```yaml
+- uses: codfish/actions/npm-pr-version@v1
+  with:
+    npm-token: ${{ secrets.NPM_TOKEN }}
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    comment: false
+```
+
+### Custom Comment Tag
+
+```yaml
+- uses: codfish/actions/npm-pr-version@v1
+  with:
+    npm-token: ${{ secrets.NPM_TOKEN }}
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    comment-tag: my-custom-tag
+```
+
+## Complete Workflow Example
+
+```yaml
+name: PR Package Testing
+
+on: pull_request_target
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  publish-pr-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: codfish/actions/setup-node-and-install@v1
+        with:
+          node-version: 'lts/*'
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish PR package
+        uses: codfish/actions/npm-pr-version@v1
+        with:
+          npm-token: ${{ secrets.NPM_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Testing Downstream
+
+After the action runs, you can install the PR version in downstream projects:
+
+```bash
+npm install my-package@0.0.0-PR-123--abc1234
+```
+
+The package is published under the `pr` tag, so it won't interfere with your regular releases.
+
+## Inputs
+
+<!-- start inputs -->
+
+| Input          | Description                                                                         | Required | Default          |
+| -------------- | ----------------------------------------------------------------------------------- | -------- | ---------------- |
+| `npm-token`    | Registry authentication token with publish permissions (works with npm/yarn/pnpm)   | No       | -                |
+| `github-token` | GitHub token with pull request comment permissions (typically secrets.GITHUB_TOKEN) | Yes      | -                |
+| `comment`      | Whether to comment on the PR with the published version (true/false)                | No       | `true`           |
+| `comment-tag`  | Tag to use for PR comments (for comment identification and updates)                 | No       | `npm-publish-pr` |
+
+<!-- end inputs -->
+
+## Package Manager Support
+
+The action automatically detects your package manager and uses the appropriate publish command:
+
+- **npm**: Uses `npm publish --access public --tag pr`
+- **yarn**: Uses `yarn publish --access public --tag pr --new-version {version} --no-git-tag-version`
+- **pnpm**: Uses `pnpm publish --access public --tag pr`
+
+Detection is based on lockfile presence:
+
+- `yarn.lock` → yarn
+- `pnpm-lock.yaml` → pnpm
+- `package-lock.json` or no lockfile → npm
+
+## Outputs
+
+<!-- start outputs -->
+
+| Output          | Description                                                           |
+| --------------- | --------------------------------------------------------------------- |
+| `version`       | Generated PR-specific version number (0.0.0-PR-{number}--{short-sha}) |
+| `package-name`  | Package name from package.json                                        |
+| `error-message` | Error message if publish fails                                        |
+
+<!-- end outputs -->
+
+## Version Format
+
+Published versions follow the pattern: `0.0.0-PR-{pr-number}--{short-sha}`
+
+Examples:
+
+- `0.0.0-PR-123--abc1234` (PR #123, commit abc1234)
+- `0.0.0-PR-456--def5678` (PR #456, commit def5678)

package/npm-publish-pr/action.yml

@@ -0,0 +1,171 @@
+name: npm-pr-version
+
+description:
+  Publishes package with PR-specific version (0.0.0-PR-123--abc1234) using detected package manager (npm/yarn/pnpm) and
+  automatically comments on PR
+
+inputs:
+  npm-token:
+    required: false
+    description: Registry authentication token with publish permissions (works with npm/yarn/pnpm)
+  github-token:
+    required: true
+    description: GitHub token with pull request comment permissions (typically secrets.GITHUB_TOKEN)
+  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)
+
+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@v1
+      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=""
+
+        # Validate package.json exists
+        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=$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=$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=$error_message" >> $GITHUB_OUTPUT
+          exit 1
+        fi
+
+        # Output package name for use in error handling
+        echo "package-name=$package_name" >> $GITHUB_OUTPUT
+
+        # Detect package manager
+        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
+
+        # Generate version
+        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=$error_message" >> $GITHUB_OUTPUT
+          exit 1
+        fi
+
+        # Publish package based on detected package manager
+        case "$package_manager" in
+          "yarn")
+            publish_output=$(yarn publish --access public --tag pr --new-version $version --no-git-tag-version 2>&1)
+            publish_exit_code=$?
+            if [ $publish_exit_code -ne 0 ]; then
+              error_message="❌ ERROR: Failed to publish package with yarn. Error: $publish_output"
+              echo "$error_message"
+              echo "error-message=$error_message" >> $GITHUB_OUTPUT
+              exit 1
+            fi
+            ;;
+          "pnpm")
+            publish_output=$(pnpm publish --access public --tag pr 2>&1)
+            publish_exit_code=$?
+            if [ $publish_exit_code -ne 0 ]; then
+              error_message="❌ ERROR: Failed to publish package with pnpm. Error: $publish_output"
+              echo "$error_message"
+              echo "error-message=$error_message" >> $GITHUB_OUTPUT
+              exit 1
+            fi
+            ;;
+          *)
+            publish_output=$(npm publish --access public --tag pr 2>&1)
+            publish_exit_code=$?
+            if [ $publish_exit_code -ne 0 ]; then
+              error_message="❌ ERROR: Failed to publish package with npm. Error: $publish_output"
+              echo "$error_message"
+              echo "error-message=$error_message" >> $GITHUB_OUTPUT
+              exit 1
+            fi
+            ;;
+        esac
+
+        echo "✅ Successfully published $package_name@$version using $package_manager"
+      env:
+        NODE_AUTH_TOKEN: ${{ inputs.npm-token }}
+        PR: ${{ github.event.number }}
+        SHA: ${{ github.event.pull_request.head.sha }}
+
+    - uses: codfish/actions/comment@v1
+      if: failure() && inputs.comment == 'true'
+      with:
+        message: |
+          ❌ **PR package publish failed!**
+
+          Error: ${{ steps.publish.outputs.error-message }}
+
+          Please check the workflow logs for more details.
+        upsert: true
+        tag: ${{ inputs.comment-tag }}
+
+    - uses: codfish/actions/comment@v1
+      if: success() && inputs.comment == 'true'
+      with:
+        message: |
+          ✅ **PR package published successfully!**
+
+          Install with: `npm install ${{ steps.publish.outputs.package-name }}@${{ steps.publish.outputs.version }}`
+        upsert: true
+        tag: ${{ inputs.comment-tag }}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@codfish/actions",
+  "type": "module",
+  "description": "Composite GitHub Actions for my projects.",
+  "author": "Chris O'Donnell <chris@codfish.dev>",
+  "license": "MIT",
+  "version": "1.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "volta": {
+    "node": "24.8.0"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.{json,css,md}\" --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.1.1",
+    "bats": "^1.10.0",
+    "doctoc": "^2.2.1",
+    "eslint": "^9.36.0",
+    "husky": "^9.1.7",
+    "js-yaml": "^4.1.0",
+    "lint-staged": "^16.2.0",
+    "prettier": "^3.6.2"
+  },
+  "packageManager": "pnpm@10.17.1",
+  "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,139 @@
+# setup-node-and-install
+
+Sets up Node.js environment and installs dependencies with automatic package manager detection, intelligent caching, and
+.nvmrc/.node-version support.
+
+This action provides the following functionality:
+
+- Automatically detects package manager (npm, yarn, or pnpm) from lockfiles
+- Uses GitHub's official `setup-node` action with optimized caching
+- Installs dependencies with appropriate commands based on detected package manager
+- Supports .nvmrc and .node-version files for version specification
+- Intelligent caching of node_modules when lockfiles are present
+
+<!-- DOCTOC SKIP -->
+
+## Usage
+
+See [action.yml](action.yml).
+
+```yaml
+steps:
+  - uses: actions/checkout@v5
+
+  # will install latest Node v18.x
+  - uses: codfish/actions/setup-node-and-install@v1
+    with:
+      node-version: 18
+      cache-key-suffix: '-${{ github.head_ref || github.event.release.tag_name }}'
+
+  - run: npm test
+```
+
+The `node-version` input is optional. If not supplied, this action will attempt to use an `.nvmrc` file in your project.
+If neither is supplied, it will fail your workflow.
+
+The `cache-key-suffix` input is optional. If not supplied, no suffix will be applied to the cache key used to restore
+cache in subsequent workflow runs.
+
+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
+```
+
+```yaml
+steps:
+  - uses: actions/checkout@v5
+  # will install Node v18.14.1
+  - uses: codfish/actions/setup-node-and-install@v1
+  - run: npm test
+```
+
+**With `.node-version` file**
+
+```sh
+# .node-version
+20.10.0
+```
+
+```yaml
+steps:
+  - uses: actions/checkout@v5
+  # will install Node v20.10.0
+  - uses: codfish/actions/setup-node-and-install@v1
+  - run: npm test
+```
+
+## Node Version File Priority
+
+When multiple version specification methods are present, the action uses this priority order:
+
+1. **Input parameter** (`node-version`) - highest priority
+2. **`.nvmrc` file** - takes precedence over .node-version
+3. **`.node-version` file** - used if no .nvmrc exists
+4. **Error** - if none of the above are present
+
+## Inputs
+
+<!-- start inputs -->
+
+| Input               | Description                                                                                           | Required | Default |
+| ------------------- | ----------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `node-version`      | Node.js version to install (e.g. '24', 'lts/\*'). Defaults to .nvmrc or .node-version file if present | No       | -       |
+| `cache-key-suffix`  | Additional suffix for cache key to enable multiple caches per workflow                                | No       | -       |
+| `install-options`   | Extra command-line options to pass to npm/pnpm/yarn install                                           | No       | -       |
+| `working-directory` | Directory containing package.json and lockfile                                                        | No       | `.`     |
+
+<!-- end inputs -->
+
+## Package Manager Detection
+
+The action automatically detects your package manager:
+
+- **pnpm**: Detected when `pnpm-lock.yaml` exists
+- **npm**: Detected when `package-lock.json` exists or as fallback
+
+## Examples
+
+### With specific Node version
+
+```yaml
+- uses: codfish/actions/setup-node-and-install@v1
+  with:
+    node-version: '18'
+```
+
+### With pnpm in subdirectory
+
+```yaml
+- uses: codfish/actions/setup-node-and-install@v1
+  with:
+    working-directory: './frontend'
+    install-options: '--frozen-lockfile'
+```
+
+### With custom cache key
+
+```yaml
+- uses: codfish/actions/setup-node-and-install@v1
+  with:
+    cache-key-suffix: '-${{ github.head_ref }}'
+```
+
+## 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@v1
+```