@codfish/actions 1.1.0

package/SECURITY.md

@@ -0,0 +1,208 @@
+# Security Policy
+
+<!-- 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
+
+- [Supported Versions](#supported-versions)
+- [Reporting a Vulnerability](#reporting-a-vulnerability)
+  - [🔒 Private Disclosure](#-private-disclosure)
+  - [📋 What to Include](#-what-to-include)
+  - [🕐 Response Timeline](#-response-timeline)
+- [Security Best Practices for Users](#security-best-practices-for-users)
+  - [🔐 Secrets Management](#-secrets-management)
+  - [🏷️ Action Versioning](#-action-versioning)
+  - [🔍 Workflow Permissions](#-workflow-permissions)
+  - [🛡️ Input Validation](#-input-validation)
+- [Security Features](#security-features)
+  - [🔒 Automated Security Scanning](#-automated-security-scanning)
+  - [🛡️ Secure Development Practices](#-secure-development-practices)
+  - [🔍 Supply Chain Security](#-supply-chain-security)
+- [Known Security Considerations](#known-security-considerations)
+  - [GitHub Actions Environment](#github-actions-environment)
+  - [npm Publishing (npm-pr-version)](#npm-publishing-npm-pr-version)
+  - [Comment Actions](#comment-actions)
+- [Incident Response](#incident-response)
+- [Security Contact](#security-contact)
+- [Acknowledgments](#acknowledgments)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- prettier-ignore-end -->
+
+## Supported Versions
+
+This project follows a rolling release model. We provide security updates for:
+
+| Version             | Supported           |
+| ------------------- | ------------------- |
+| main                | ✅ Always supported |
+| Latest release tags | ✅ Supported        |
+| Older releases      | ❌ Not supported    |
+
+## Reporting a Vulnerability
+
+If you discover a security issue, please follow these steps:
+
+### 🔒 Private Disclosure
+
+**Do NOT create a public issue for security vulnerabilities.**
+
+Instead, please report security issues privately using one of these methods:
+
+1. **GitHub Security Advisories** (preferred)
+   - Go to the [Security tab](https://github.com/codfish/actions/security/advisories)
+   - Click "Report a vulnerability"
+   - Fill out the form with details
+
+2. **Email**
+   - Send details to: [chris@codfish.dev](mailto:chris@codfish.dev)
+   - Include "SECURITY" in the subject line
+
+### 📋 What to Include
+
+When reporting a vulnerability, please include:
+
+- **Description** of the vulnerability
+- **Steps to reproduce** the issue
+- **Potential impact** of the vulnerability
+- **Suggested fix** (if you have one)
+- **Your contact information** for follow-up
+
+### 🕐 Response Timeline
+
+We aim to respond to security reports within:
+
+- **Initial response**: 24-48 hours
+- **Confirmation/triage**: 2-5 business days
+- **Resolution**: Varies based on complexity
+
+## Security Best Practices for Users
+
+When using these GitHub Actions in your workflows:
+
+### 🔐 Secrets Management
+
+- **Never log secrets** in workflows that use these actions
+- Use **GitHub Secrets** for sensitive information
+- **Limit secret scope** to only necessary workflows
+- **Rotate secrets** regularly
+
+```yaml
+# ✅ Good - Using secrets properly
+- uses: codfish/actions/npm-pr-version@v1
+  with:
+    npm-token: ${{ secrets.NPM_TOKEN }}
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+
+# ❌ Bad - Exposing secrets
+- name: Debug
+  run: echo "Token: ${{ secrets.NPM_TOKEN }}"
+```
+
+### 🏷️ Action Versioning
+
+- **Pin to specific versions or commit hashes** for production workflows
+- **Avoid using `@main`** in production (use for testing only)
+
+```yaml
+# ✅ Good - Pinned version
+- uses: codfish/actions/setup-node-and-install@v1.2.3
+
+# ⚠️ Caution - Latest main (testing only)
+- uses: codfish/actions/setup-node-and-install@main
+```
+
+### 🔍 Workflow Permissions
+
+- **Use minimal permissions** required
+- **Specify explicit permissions** when possible
+- **Avoid using `write-all`** permissions
+
+```yaml
+# ✅ Good - Minimal permissions
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+# ❌ Bad - Excessive permissions
+permissions: write-all
+```
+
+### 🛡️ Input Validation
+
+- **Validate user inputs** before using them in actions
+- **Sanitize outputs** when displaying them
+- **Be cautious with dynamic expressions**
+
+## Security Features
+
+This project implements several security measures:
+
+### 🔒 Automated Security Scanning
+
+- **Dependabot** for dependency updates
+- **CodeQL** for static analysis
+- **Dependency Review** for PR security checks
+- **Secret scanning** with TruffleHog
+- **npm audit** for vulnerability detection
+
+### 🛡️ Secure Development Practices
+
+- **Input validation** in all actions
+- **Error handling** without information disclosure
+- **No secret logging** in any action
+- **Least privilege** principle in action permissions
+
+### 🔍 Supply Chain Security
+
+- **Minimal dependencies** to reduce attack surface
+- **Regular dependency updates** via Dependabot
+- **Verified action references** in workflows
+
+## Known Security Considerations
+
+### GitHub Actions Environment
+
+- **Actions run in GitHub's infrastructure** - we cannot control the runner environment
+- **Secrets are available** to all steps in a job that has access
+- **Workflow logs are visible** to users with read access to the repository
+
+### npm Publishing (npm-pr-version)
+
+- **NPM tokens have broad permissions** - ensure tokens are scoped appropriately
+- **Published packages are public** by default - review package contents
+- **Version immutability** - published versions cannot be unpublished
+
+### Comment Actions
+
+- **GitHub tokens can comment** on behalf of the workflow user
+- **Comment content is public** - avoid including sensitive information
+- **Rate limiting applies** - excessive commenting may be throttled
+
+## Incident Response
+
+In case of a confirmed security vulnerability:
+
+1. **Assessment** - Evaluate severity and impact
+2. **Mitigation** - Develop and test fixes
+3. **Disclosure** - Coordinate with reporter on disclosure timeline
+4. **Release** - Deploy security fixes
+5. **Communication** - Notify users through appropriate channels
+
+## Security Contact
+
+- **Primary**: [security@codfish.dev](mailto:security@codfish.dev)
+- **GitHub**: [@codfish](https://github.com/codfish)
+
+## Acknowledgments
+
+We appreciate security researchers and users who responsibly disclose vulnerabilities. Contributors who report valid
+security issues will be acknowledged (with permission) in:
+
+- Security advisories
+- Release notes
+- This security policy
+
+Thank you for helping keep this project secure! 🔒

package/bin/generate-docs.js

@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import yaml from 'js-yaml';
+import path from 'path';
+
+/**
+ * Generate documentation for all GitHub Actions in the repository
+ */
+class DocumentationGenerator {
+  constructor() {
+    this.rootDir = process.cwd();
+    this.actions = [];
+  }
+
+  /**
+   * Find all action directories by looking for action.yml files
+   */
+  findActionDirectories() {
+    const entries = fs.readdirSync(this.rootDir, { withFileTypes: true });
+
+    return entries
+      .filter(entry => entry.isDirectory())
+      .filter(entry => !entry.name.startsWith('.') && entry.name !== 'node_modules')
+      .map(entry => entry.name)
+      .filter(dirName => {
+        const actionFile = path.join(this.rootDir, dirName, 'action.yml');
+        return fs.existsSync(actionFile);
+      });
+  }
+
+  /**
+   * Parse action.yml file to extract metadata
+   */
+  parseActionFile(dirName) {
+    const actionFile = path.join(this.rootDir, dirName, 'action.yml');
+
+    try {
+      const content = fs.readFileSync(actionFile, 'utf8');
+      const actionData = yaml.load(content);
+
+      return {
+        directory: dirName,
+        name: actionData.name || dirName,
+        description: actionData.description || 'No description available',
+        inputs: actionData.inputs || {},
+        outputs: actionData.outputs || {},
+        rawData: actionData,
+      };
+    } catch (error) {
+      console.error(`Error parsing ${actionFile}:`, error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Extract usage example from README.md
+   */
+  extractUsageExample(dirName) {
+    const readmeFile = path.join(this.rootDir, dirName, 'README.md');
+
+    if (!fs.existsSync(readmeFile)) {
+      return null;
+    }
+
+    try {
+      const content = fs.readFileSync(readmeFile, 'utf8');
+
+      // Look for usage examples in various sections
+      const patterns = [
+        // Look for "## Usage" section with yaml code block
+        /## Usage[\s\S]*?```yaml\n([\s\S]*?)\n```/i,
+        // Look for any yaml code block with "uses: "
+        /```yaml\n([\s\S]*?uses:\s*[.\w/-]+[\s\S]*?)\n```/i,
+        // Look for specific action usage
+        new RegExp(`\`\`\`yaml\\n([\\s\\S]*?uses:\\s*[^\\n]*${dirName}[\\s\\S]*?)\\n\`\`\``, 'i'),
+      ];
+
+      for (const pattern of patterns) {
+        const match = content.match(pattern);
+        if (match && match[1]) {
+          // Clean up the example and ensure it's properly formatted
+          const example = match[1].trim();
+
+          // If it doesn't start with a step name, add one
+          if (!example.match(/^\s*-\s*name:/m) && !example.match(/^\s*-\s*uses:/m)) {
+            return `- uses: codfish/actions/${dirName}@v1\n${example.replace(/^/gm, '  ')}`;
+          }
+
+          return example;
+        }
+      }
+
+      // Fallback: create a basic example based on inputs
+      return this.generateBasicExample(dirName);
+    } catch (error) {
+      console.error(`Error reading README for ${dirName}:`, error.message);
+      return this.generateBasicExample(dirName);
+    }
+  }
+
+  /**
+   * Generate a basic usage example based on action inputs
+   */
+  generateBasicExample(dirName, inputs = {}) {
+    let example = `- uses: codfish/actions/${dirName}@v1`;
+
+    const inputKeys = Object.keys(inputs);
+    if (inputKeys.length > 0) {
+      example += '\n  with:';
+
+      // Add required inputs first
+      const requiredInputs = inputKeys.filter(key => inputs[key].required);
+      const optionalInputs = inputKeys.filter(key => !inputs[key].required);
+
+      [...requiredInputs, ...optionalInputs.slice(0, 2)].forEach(key => {
+        const input = inputs[key];
+        let value = 'value';
+
+        // Smart defaults based on input name
+        if (key.includes('token')) value = '${{ secrets.TOKEN_NAME }}';
+        else if (key.includes('version')) value = 'lts/*';
+        else if (key.includes('message')) value = 'Your message here';
+        else if (key.includes('tag')) value = 'tag-name';
+        else if (input.default) value = input.default;
+
+        example += `\n    ${key}: ${value}`;
+      });
+    }
+
+    return example;
+  }
+
+  /**
+   * Generate markdown table for inputs or outputs
+   */
+  generateTable(items, type = 'inputs') {
+    if (!items || Object.keys(items).length === 0) {
+      return `*No ${type}*`;
+    }
+
+    const headers = type === 'inputs' ? '| Input | Description | Required | Default |' : '| Output | Description |';
+
+    const separator = type === 'inputs' ? '|-------|-------------|----------|---------|' : '|--------|-------------|';
+
+    let table = `${headers}\n${separator}`;
+
+    Object.entries(items).forEach(([key, config]) => {
+      const description = config.description || 'No description';
+
+      if (type === 'inputs') {
+        const required = config.required ? 'Yes' : 'No';
+        const defaultValue = config.default ? `\`${config.default}\` ` : '-';
+        table += `\n| \`${key}\` | ${description} | ${required} | ${defaultValue} |`;
+      } else {
+        table += `\n| \`${key}\` | ${description} |`;
+      }
+    });
+
+    return table;
+  }
+
+  /**
+   * Generate markdown section for a single action
+   */
+  generateActionSection(action) {
+    const { directory, name, description, inputs, outputs } = action;
+    const usageExample = this.extractUsageExample(directory);
+
+    let section = `### [${name}](./${directory}/)\n\n`;
+    section += `${description}\n\n`;
+
+    // Add inputs table
+    section += `**Inputs:**\n\n${this.generateTable(inputs, 'inputs')}\n\n`;
+
+    // Add outputs table if there are outputs
+    if (outputs && Object.keys(outputs).length > 0) {
+      section += `**Outputs:**\n\n${this.generateTable(outputs, 'outputs')}\n\n`;
+    }
+
+    // Add usage example
+    if (usageExample) {
+      section += `**Usage:**\n\n\`\`\`yaml\n${usageExample}\n\`\`\`\n\n`;
+    }
+
+    return section;
+  }
+
+  /**
+   * Generate just the content for actions (without the section header)
+   */
+  generateAvailableActionsContent() {
+    const actionDirs = this.findActionDirectories();
+
+    console.log(`Found ${actionDirs.length} action directories:`, actionDirs);
+
+    this.actions = actionDirs
+      .map(dir => this.parseActionFile(dir))
+      .filter(action => action !== null)
+      .sort((a, b) => a.name.localeCompare(b.name));
+
+    let content = '';
+
+    this.actions.forEach(action => {
+      content += this.generateActionSection(action);
+    });
+
+    return content.trim(); // Remove trailing newlines
+  }
+
+  /**
+   * Update the main README.md file using file descriptors for security
+   */
+  updateReadme() {
+    const readmePath = path.join(this.rootDir, 'README.md');
+
+    if (!fs.existsSync(readmePath)) {
+      console.error('README.md not found');
+      return false;
+    }
+
+    let fd;
+    try {
+      // Open file descriptor for reading and writing
+      fd = fs.openSync(readmePath, 'r+');
+
+      // Read content using file descriptor
+      const stats = fs.fstatSync(fd);
+      const buffer = Buffer.alloc(stats.size);
+      fs.readSync(fd, buffer, 0, stats.size, 0);
+      let content = buffer.toString('utf8');
+
+      // Find the action docs markers
+      const startMarker = '<!-- start action docs -->';
+      const endMarker = '<!-- end action docs -->';
+
+      const startIndex = content.indexOf(startMarker);
+      const endIndex = content.indexOf(endMarker);
+
+      if (startIndex === -1) {
+        console.error(`Could not find "${startMarker}" in README.md`);
+        console.error('Please add the marker where you want action documentation to be generated');
+        return false;
+      }
+
+      if (endIndex === -1) {
+        console.error(`Could not find "${endMarker}" in README.md`);
+        console.error('Please add the end marker after the start marker');
+        return false;
+      }
+
+      if (endIndex <= startIndex) {
+        console.error('End marker must come after start marker');
+        return false;
+      }
+
+      // Replace content between markers
+      const beforeMarker = content.substring(0, startIndex + startMarker.length);
+      const afterMarker = content.substring(endIndex);
+
+      const newContent = this.generateAvailableActionsContent();
+      const updatedContent = beforeMarker + '\n' + newContent + '\n' + afterMarker;
+
+      // Truncate and write back using file descriptor
+      fs.ftruncateSync(fd, 0);
+      fs.writeSync(fd, updatedContent, 0, 'utf8');
+
+      console.log('✅ README.md updated successfully!');
+      console.log(`📝 Generated documentation for ${this.actions.length} actions`);
+
+      return true;
+    } catch (error) {
+      console.error('Error updating README.md:', error.message);
+      return false;
+    } finally {
+      // Always close the file descriptor
+      if (fd !== undefined) {
+        try {
+          fs.closeSync(fd);
+        } catch (closeError) {
+          console.error('Error closing README.md file descriptor:', closeError.message);
+        }
+      }
+    }
+  }
+
+  /**
+   * Update individual action README files with inputs/outputs using file descriptors for security
+   */
+  updateActionReadmes() {
+    const actionDirs = this.findActionDirectories();
+    let updatedCount = 0;
+
+    actionDirs.forEach(dirName => {
+      const readmePath = path.join(this.rootDir, dirName, 'README.md');
+
+      if (!fs.existsSync(readmePath)) {
+        console.log(`⚠️  No README.md found in ${dirName}, skipping`);
+        return;
+      }
+
+      const actionData = this.parseActionFile(dirName);
+      if (!actionData) {
+        console.log(`⚠️  Could not parse action.yml for ${dirName}, skipping`);
+        return;
+      }
+
+      let fd;
+      try {
+        // Open file descriptor for reading and writing
+        fd = fs.openSync(readmePath, 'r+');
+
+        // Read content using file descriptor
+        const stats = fs.fstatSync(fd);
+        const buffer = Buffer.alloc(stats.size);
+        fs.readSync(fd, buffer, 0, stats.size, 0);
+        let content = buffer.toString('utf8');
+        let modified = false;
+
+        // Update inputs section
+        const inputsStartMarker = '<!-- start inputs -->';
+        const inputsEndMarker = '<!-- end inputs -->';
+        const inputsStart = content.indexOf(inputsStartMarker);
+        const inputsEnd = content.indexOf(inputsEndMarker);
+
+        if (inputsStart !== -1 && inputsEnd !== -1 && inputsEnd > inputsStart) {
+          const inputsTable = this.generateTable(actionData.inputs, 'inputs');
+          const beforeInputs = content.substring(0, inputsStart + inputsStartMarker.length);
+          const afterInputs = content.substring(inputsEnd);
+          content = beforeInputs + '\n\n' + inputsTable + '\n\n' + afterInputs;
+          modified = true;
+          console.log(`✅ Updated inputs section in ${dirName}/README.md`);
+        }
+
+        // Update outputs section
+        const outputsStartMarker = '<!-- start outputs -->';
+        const outputsEndMarker = '<!-- end outputs -->';
+        const outputsStart = content.indexOf(outputsStartMarker);
+        const outputsEnd = content.indexOf(outputsEndMarker);
+
+        if (outputsStart !== -1 && outputsEnd !== -1 && outputsEnd > outputsStart) {
+          const outputsTable = this.generateTable(actionData.outputs, 'outputs');
+          const beforeOutputs = content.substring(0, outputsStart + outputsStartMarker.length);
+          const afterOutputs = content.substring(outputsEnd);
+          content = beforeOutputs + '\n\n' + outputsTable + '\n\n' + afterOutputs;
+          modified = true;
+          console.log(`✅ Updated outputs section in ${dirName}/README.md`);
+        }
+
+        if (modified) {
+          // Truncate and write back using file descriptor
+          fs.ftruncateSync(fd, 0);
+          fs.writeSync(fd, content, 0, 'utf8');
+          updatedCount++;
+        }
+      } catch (error) {
+        console.error(`Error updating ${dirName}/README.md:`, error.message);
+      } finally {
+        // Always close the file descriptor
+        if (fd !== undefined) {
+          try {
+            fs.closeSync(fd);
+          } catch (closeError) {
+            console.error(`Error closing ${dirName}/README.md file descriptor:`, closeError.message);
+          }
+        }
+      }
+    });
+
+    return updatedCount;
+  }
+
+  /**
+   * Run prettier formatting on all documentation files
+   */
+  async formatDocs() {
+    const { execSync } = await import('child_process');
+
+    try {
+      console.log('\n🎨 Formatting documentation with prettier...');
+      execSync('pnpm format', {
+        stdio: 'inherit',
+        cwd: this.rootDir,
+      });
+      console.log('✅ Documentation formatting complete!');
+      return true;
+    } catch (error) {
+      console.error('❌ Prettier formatting failed:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Run the documentation generation
+   */
+  async run() {
+    console.log('🔍 Scanning for GitHub Actions...');
+
+    // Update main README
+    const mainSuccess = this.updateReadme();
+
+    // Update individual action READMEs
+    console.log('\n🔍 Updating individual action README files...');
+    const updatedActionCount = this.updateActionReadmes();
+
+    if (mainSuccess) {
+      console.log(`\n📚 Documentation generation complete!`);
+      console.log(`📝 Updated main README.md with ${this.actions.length} actions`);
+      if (updatedActionCount > 0) {
+        console.log(`📝 Updated ${updatedActionCount} action README files`);
+      }
+
+      // Format the documentation
+      const formatSuccess = await this.formatDocs();
+
+      if (formatSuccess) {
+        console.log('\n🎉 All documentation updated and formatted successfully!');
+        console.log('Run `git diff` to see all changes.');
+      } else {
+        console.log('\n⚠️  Documentation updated but formatting failed.');
+        console.log('You may want to run `pnpm format` manually.');
+      }
+    } else {
+      console.error('\n❌ Main README documentation generation failed!');
+      process.exit(1);
+    }
+  }
+}
+
+// Run the generator
+const generator = new DocumentationGenerator();
+generator.run();