@codfish/actions 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,316 @@
+# Contributing to codfish/actions
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to this repository.
+
+<!-- prettier-ignore-start -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+  - [1. Create a Branch](#1-create-a-branch)
+  - [2. Make Your Changes](#2-make-your-changes)
+  - [3. Test Your Changes](#3-test-your-changes)
+  - [4. Commit Your Changes](#4-commit-your-changes)
+- [Action Development Guidelines](#action-development-guidelines)
+  - [Directory Structure](#directory-structure)
+  - [Action Naming](#action-naming)
+  - [Action Definition (action.yml)](#action-definition-actionyml)
+  - [Implementation Guidelines](#implementation-guidelines)
+  - [Error Handling](#error-handling)
+  - [Package Manager Detection](#package-manager-detection)
+- [Testing](#testing)
+  - [Test Structure](#test-structure)
+  - [Writing Tests](#writing-tests)
+  - [Running Tests](#running-tests)
+- [Documentation](#documentation)
+  - [README Structure](#readme-structure)
+  - [Documentation Updates](#documentation-updates)
+  - [Auto-Generated Documentation](#auto-generated-documentation)
+- [Submitting Changes](#submitting-changes)
+  - [Pull Request Process](#pull-request-process)
+  - [PR Requirements](#pr-requirements)
+  - [Review Process](#review-process)
+- [Action Ideas](#action-ideas)
+- [Getting Help](#getting-help)
+- [Recognition](#recognition)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- prettier-ignore-end -->
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected
+to uphold this code.
+
+## Getting Started
+
+1. **Fork the repository** and clone it locally
+2. **Install dependencies**: `pnpm install`
+3. **Set up your development environment**:
+   ```bash
+   # Install act for local testing (optional but recommended)
+   brew install act  # macOS
+   # or
+   curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash  # Linux
+   ```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Your Changes
+
+Follow the [Action Development Guidelines](#action-development-guidelines) below.
+
+### 3. Test Your Changes
+
+```bash
+# Run all tests
+pnpm test
+
+# Run specific test types
+pnpm test:integration
+pnpm test:unit
+
+# Run linting
+pnpm lint
+```
+
+### 4. Commit Your Changes
+
+Use clear, descriptive commit messages:
+
+```bash
+git commit -m "feat(setup-node): add yarn berry support"
+git commit -m "fix(comment): handle empty tag input properly"
+git commit -m "docs(npm-pr-version): update README with new examples"
+```
+
+## Action Development Guidelines
+
+### Directory Structure
+
+Each action should be in its own directory at the repository root:
+
+```
+action-name/
+├── action.yml          # Action definition
+├── README.md          # Action documentation
+└── [implementation files]
+```
+
+### Action Naming
+
+- Use **kebab-case** for action directory names
+- Action names should be descriptive and follow the pattern: `verb-noun` or `noun-verb`
+- Examples: `setup-node-and-install`, `npm-pr-version`, `comment`
+
+### Action Definition (action.yml)
+
+```yaml
+name: action-name
+description: Clear, concise description of what the action does
+
+inputs:
+  input-name:
+    description: Clear description of the input parameter
+    required: true|false
+    default: 'default-value' # if applicable
+
+outputs:
+  output-name:
+    description: Clear description of the output
+    value: '${{ steps.step-id.outputs.output-name }}'
+
+runs:
+  using: composite
+  steps:
+    # Implementation steps
+```
+
+### Implementation Guidelines
+
+1. **Use composite actions** for consistency and transparency
+2. **Validate inputs** early with clear error messages
+3. **Handle errors gracefully** with actionable feedback
+4. **Use consistent formatting**:
+   - ❌ for errors
+   - ✅ for success messages
+   - 📦 for package manager operations
+   - 📋 for informational messages
+5. **Support multiple package managers** when applicable (npm/yarn/pnpm)
+6. **Follow security best practices** - never log secrets or sensitive data
+
+### Error Handling
+
+```bash
+# Good error handling example
+if [ ! -f "package.json" ]; then
+  echo "❌ ERROR: package.json not found in current directory"
+  echo "Make sure you're running this action in a directory with a package.json file"
+  exit 1
+fi
+```
+
+### Package Manager Detection
+
+When applicable, detect package managers in this order:
+
+1. `yarn.lock` → yarn
+2. `pnpm-lock.yaml` → pnpm
+3. `package-lock.json` → npm
+4. No lockfile → npm (default)
+
+## Testing
+
+### Test Structure
+
+```
+tests/
+├── integration/           # Full action tests
+│   └── action-name/
+│       └── basic.bats
+├── fixtures/              # Test data
+│   ├── package-json/
+│   └── lockfiles/
+└── scripts/
+    ├── test-runner.sh
+    └── test-helpers.sh
+```
+
+### Writing Tests
+
+1. **Create integration tests** for each action in `tests/integration/action-name/`
+2. **Use the bats testing framework** for shell script testing
+3. **Test error conditions** as well as success scenarios
+4. **Use test fixtures** from `tests/fixtures/` when possible
+
+Example test:
+
+```bash
+@test "action-name: handles valid input" {
+    # Setup
+    cp "$BATS_TEST_DIRNAME/../../../tests/fixtures/package-json/valid.json" package.json
+
+    # Test
+    run bash -c 'your-test-command'
+
+    # Assertions
+    assert_success
+    assert_output_contains "expected-output"
+}
+```
+
+### Running Tests
+
+```bash
+# All tests
+pnpm test
+
+# Specific action tests
+./tests/scripts/test-runner.sh integration
+```
+
+## Documentation
+
+### README Structure
+
+Each action should have a comprehensive README.md with:
+
+1. **Title and description**
+2. **Table of contents** (for longer READMEs)
+3. **Usage section** with basic example
+4. **Inputs table** with descriptions
+5. **Outputs table** (if applicable)
+6. **Examples section** with various use cases
+7. **Special features** (package manager detection, etc.)
+
+### Documentation Updates
+
+- Update action README when changing inputs/outputs
+- **Run `pnpm docs:generate`** to auto-update the main project README
+- Update CLAUDE.md when changing project structure
+- Add inline comments for complex logic
+
+### Auto-Generated Documentation
+
+The main project README's "Available Actions" section is automatically generated from:
+
+- `action.yml` files (name, description, inputs, outputs)
+- Individual action README files (usage examples)
+
+**When to regenerate documentation:**
+
+- After adding a new action
+- After changing action.yml inputs/outputs
+- After updating action descriptions
+- Before submitting a PR
+
+```bash
+# Generate updated documentation
+pnpm docs:generate
+
+# Review the changes
+git diff README.md
+```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. **Create a descriptive PR title**: `feat(action-name): add new feature`
+2. **Fill out the PR template** completely
+3. **Link related issues** using keywords (Closes #123)
+4. **Request review** from maintainers
+5. **Address feedback** promptly and respectfully
+
+### PR Requirements
+
+- [ ] All tests pass
+- [ ] Code follows existing style guidelines
+- [ ] Documentation is updated
+- [ ] Changes are tested in real GitHub Actions workflows
+- [ ] No security vulnerabilities introduced
+
+### Review Process
+
+1. **Automated checks** must pass (tests, linting, security scans)
+2. **Manual review** by maintainers
+3. **Testing** in real-world scenarios
+4. **Approval** and merge
+
+## Action Ideas
+
+Looking for contribution ideas? Here are some actions that would be valuable:
+
+- `slack-notify` - Send Slack notifications
+- `docker-build-push` - Build and push Docker images
+- `semantic-release` - Automated semantic versioning
+- `cache-restore-save` - Advanced caching patterns
+- `monorepo-changed` - Detect changed packages in monorepos
+- `performance-test` - Lighthouse/performance testing
+
+## Getting Help
+
+- **GitHub Discussions**: Ask questions and discuss ideas
+- **Issues**: Report bugs or request features
+- **Discord/Slack**: [Link if available]
+
+## Recognition
+
+Contributors will be recognized in:
+
+- Commit messages with `Co-authored-by`
+- Release notes
+- Contributors section (if added)
+
+Thank you for contributing! 🎉

package/README.md

@@ -0,0 +1,207 @@
+# codfish/actions
+
+A collection of reusable GitHub Actions for common development workflows. Each action is self-contained and designed for
+maximum reusability across different projects.
+
+<!-- prettier-ignore-start -->
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+## Table of Contents
+
+- [Usage](#usage)
+- [Available Actions](#available-actions)
+  - [comment](#comment)
+  - [npm-pr-version](#npm-pr-version)
+  - [setup-node-and-install](#setup-node-and-install)
+- [Contributing](#contributing)
+- [Example Workflow](#example-workflow)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- prettier-ignore-end -->
+
+## Usage
+
+Reference actions using the following format:
+
+```yaml
+uses: codfish/actions/{action-name}@main
+uses: codfish/actions/{action-name}@v1
+uses: codfish/actions/{action-name}@v1.0.1
+uses: codfish/actions/{action-name}@feature-branch
+uses: codfish/actions/{action-name}@aff1a9d
+```
+
+## Available Actions
+
+<!-- start action docs -->
+
+### [comment](./comment/)
+
+Creates or updates a comment in a pull request with optional tagging for upsert functionality
+
+**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` |
+
+**Usage:**
+
+```yaml
+- name: Comment on PR
+  uses: codfish/actions/comment@v1
+  with:
+    message: '✅ Build successful!'
+    tag: 'build-status'
+    upsert: true
+```
+
+### [npm-pr-version](./npm-publish-pr/)
+
+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:**
+
+| 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` |
+
+**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                                        |
+
+**Usage:**
+
+```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 }}
+```
+
+### [setup-node-and-install](./setup-node-and-install/)
+
+Sets up Node.js environment and installs dependencies with automatic package manager detection (npm/pnpm/yarn),
+intelligent caching, and .nvmrc/.node-version support
+
+**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       | `.`     |
+
+**Usage:**
+
+```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
+```
+
+<!-- end action docs -->
+
+## Contributing
+
+Each action follows these conventions:
+
+- **Directory structure**: Actions are in kebab-case directories at the repository root
+- **Required files**: `action.yml`, `README.md`
+- **Composite actions**: All actions use `composite` type for simplicity and transparency
+- **Documentation**: Each action includes comprehensive usage examples and input/output documentation
+
+## Example Workflow
+
+Complete workflow using multiple actions together:
+
+```yaml
+name: CI/CD Pipeline
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  test-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: codfish/actions/setup-node-and-install@v1
+        with:
+          node-version: 'lts/*'
+
+      - name: Run tests
+        run: |
+          npm test 2>&1 | tee test-output.txt
+          if grep -q "All tests passed" test-output.txt; then
+            echo "status=✅ passed" >> $GITHUB_OUTPUT
+          else
+            echo "status=❌ failed" >> $GITHUB_OUTPUT
+          fi
+          echo "count=$(grep -c "✓\|√\|PASS" test-output.txt || echo "unknown")" >> $GITHUB_OUTPUT
+        id: test
+
+      - name: Build package
+        run: npm run build
+
+      - name: Calculate build size
+        run: |
+          if [ -d "dist" ]; then
+            size=$(du -sh dist | cut -f1)
+          elif [ -d "build" ]; then
+            size=$(du -sh build | cut -f1)
+          elif [ -f "package.json" ]; then
+            size=$(du -sh . --exclude=node_modules | cut -f1)
+          else
+            size="unknown"
+          fi
+          echo "size=$size" >> $GITHUB_OUTPUT
+        id: build
+
+      - uses: codfish/actions/comment@v1
+        with:
+          message: |
+            ## 🚀 **Build Summary**
+
+            **Tests**: ${{ steps.test.outputs.status }} (${{ steps.test.outputs.count }} tests)
+            **Build**: ✅ completed successfully
+            **Size**: ${{ steps.build.outputs.size }}
+
+            Ready for testing! 🎉
+          tag: 'build-summary'
+          upsert: true
+
+      - uses: codfish/actions/npm-pr-version@v1
+        with:
+          npm-token: ${{ secrets.NPM_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          comment-tag: 'pr-package'
+```