feat(groq): GitHub Action that posts a random zen quote as a comment on newly opened issues, adding a whimsical touch to the repository.

[polsala]

Implementation Summary

• Utility: nightly-issue-zen-quote-commenter
• Provider: groq
• Location: github-actions/nightly-nightly-issue-zen-quote-comm
• Files Created: 4
• Description: GitHub Action that posts a random zen quote as a comment on newly opened issues, adding a whimsical touch to the repository.

Rationale

• Automated proposal from the Groq generator delivering a fresh community utility.
• This utility was generated using the groq AI provider.

Why safe to merge

• Utility is isolated to github-actions/nightly-nightly-issue-zen-quote-comm.
• README + tests ship together (see folder contents).
• No secrets or credentials touched.
• All changes are additive and self-contained.

Test Plan

• Follow the instructions in the generated README at github-actions/nightly-nightly-issue-zen-quote-comm/README.md
• Run tests located in github-actions/nightly-nightly-issue-zen-quote-comm/tests/

Links

• Generated docs and examples committed alongside this change.

Mock Justification

• Not applicable; generator did not introduce new mocks.

[polsala]

🤖 Review by GROQ Agent

✅ What's solid

• Self‑contained composite action – the action lives entirely inside the repository, uses only Bash and the ubiquitous jq utility, and does not introduce any external runtime dependencies.
• Clear separation of concerns – the script (src/main.sh) only handles payload extraction, quote selection, and the API call; the action.yml simply wires it up.
• Deterministic test harness – by fixing RANDOM=0 and mocking curl, the test reliably validates the exact quote that should be posted.
• Good documentation – the README explains the purpose, usage, and testing steps in a concise, copy‑paste‑ready format.
• No secret leakage – the token is only passed to curl via an Authorization header; the script never echoes it or writes it to a file.

🧪 Tests

• Coverage gaps

  • Edge‑case handling: there are no tests for scenarios where GITHUB_EVENT_PATH is missing, the payload lacks an issue.number, or the curl request fails (non‑2xx response). Adding a couple of negative tests would give confidence that the script exits gracefully and does not leave the workflow in an ambiguous state.
  • Idempotency: a test that runs the script twice with the same event payload could verify that the action does not unintentionally duplicate comments (GitHub will allow duplicates, but you may want to guard against it).

• Suggested test additions

  # Test missing GITHUB_EVENT_PATH
  unset GITHUB_EVENT_PATH
  if bash src/main.sh 2>/dev/null; then
    echo "FAIL: script should have exited with error"
    exit 1
  fi
  
  # Test non‑issue event (null issue number)
  export GITHUB_EVENT_PATH=$(mktemp)
  cat >"$GITHUB_EVENT_PATH" <<'EOF'
  { "issue": { "number": null } }
  EOF
  if bash src/main.sh; then
    echo "FAIL: script should have exited early with status 0"
    exit 1
  fi
  
  # Test curl failure handling
  function curl() { return 22; }   # simulate HTTP error
  export -f curl
  if bash src/main.sh; then
    echo "FAIL: script should propagate curl error"
    exit 1
  fi

• Test hygiene – the current test leaves temporary files (CURL_LOG, EVENT_JSON) on the runner. Adding a trap 'rm -f "$CURL_LOG" "$EVENT_JSON"' EXIT ensures cleanup and avoids clutter in CI logs.

🔒 Security

• Token exposure – the script passes the token via an Authorization: token $TOKEN header, which is standard. Ensure that the action is not run with set -x or any debug flag that would echo the command line, as that would leak the token to the workflow log.

• Input validation – the script trusts the JSON payload from GitHub. While GitHub’s own events are well‑formed, adding a minimal sanity check (e.g., verify that ISSUE_NUMBER is a positive integer) can prevent malformed payloads from causing unexpected API calls.

  if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
    echo "Invalid issue number: $ISSUE_NUMBER"
    exit 1
  fi

• Network safety – the curl invocation uses -s (silent) but does not include -f (fail on HTTP errors). Adding -f will cause the script to exit with a non‑zero status if GitHub returns an error, preventing silent failures.

  curl -s -f -X POST ...

🧩 Docs/DX

• Usage snippet – the README shows a workflow that references the action via a relative path. Consider adding a versioned example (e.g., uses: ./github-actions/nightly-issue-zen-quote-commenter@v1) to illustrate how consumers can pin the action when the directory is exported as a submodule or released as a separate repository.
• Quote list visibility – the list of quotes lives inside the script. Documenting that the list can be extended by editing src/main.sh (or by providing an optional input in the future) would help contributors who want to add more sayings.
• Failure guidance – add a short “Troubleshooting” section that points users to the workflow logs when the comment is not posted (e.g., check that GITHUB_TOKEN has issues: write permission).

🧱 Mocks/Fakes

• Current mock strategy – redefining curl as a Bash function works well for the simple test case. However, if the action later evolves to use additional tools (e.g., git or sed), the test harness will need a more robust mocking framework.

• Potential improvement – use a temporary directory added to PATH that contains a mock curl executable. This isolates the mock from any other functions that might be defined in the test environment and mirrors how external binaries are normally invoked.

  mkdir -p "$TMPDIR/mock-bin"
  cat >"$TMPDIR/mock-bin/curl" <<'EOS'
  #!/usr/bin/env bash
  echo "curl called with args: $@" >> "$CURL_LOG"
  echo '{"id":1,"url":"https://api.github.com/..."}'
  EOS
  chmod +x "$TMPDIR/mock-bin/curl"
  export PATH="$TMPDIR/mock-bin:$PATH"

• Deterministic randomness – fixing RANDOM=0 is a clean way to make the quote selection predictable. Document this approach in the README’s “Testing” section so future contributors understand why the seed is set.

---

Overall, the implementation is tidy, well‑documented, and functional. The suggested enhancements focus on hardening edge‑case handling, improving test robustness, and tightening security best practices without adding unnecessary complexity.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Self-contained and minimal dependencies: The action is implemented as a composite action using only Bash and jq, avoiding external runtime dependencies. This design promotes portability, simplifies auditing, and reduces the supply chain risk.
• Robust script error handling: The src/main.sh script utilizes set -euo pipefail and includes explicit checks for critical environment variables like GITHUB_EVENT_PATH and ISSUE_NUMBER. This ensures the script fails fast and predictably when required context is missing.
• Effective deterministic testing: The tests/run_test.sh script demonstrates a well-executed strategy for deterministic testing. By mocking curl with a shell function and fixing the RANDOM seed, it ensures consistent test results and verifies the core logic without making actual network requests.
• Comprehensive documentation: The README.md provides a clear overview, detailed usage instructions with a practical example, and an explanation of the action's features. This significantly enhances the developer experience for users integrating the action.

🧪 Tests

• Expand test coverage for edge cases: The current test focuses on a successful comment post. Consider adding tests to verify the script's behavior in less ideal scenarios:
  • No issue number: Add a test case where GITHUB_EVENT_PATH points to an event payload that does not contain an issue.number, ensuring the script exits gracefully (exit code 0) as intended.
  • Missing GITHUB_EVENT_PATH: Create a test that simulates GITHUB_EVENT_PATH being unset, confirming the script exits with an error (exit code 1).
  • API call failure: While curl is mocked, a test could simulate a non-200 HTTP response from the GitHub API (e.g., by having the mock curl return an error code or an empty/malformed JSON response) to ensure the script handles such scenarios without unexpected behavior.
• Improve test output clarity: Enhance the run_test.sh script to provide more granular feedback. Instead of a single "Test passed/failed" message, output specific assertions being checked (e.g., "Verifying curl command...", "Checking payload content...") to aid in debugging.

🔒 Security

• Externalize hardcoded quotes: The zen quotes are currently hardcoded within src/main.sh. While simple, this requires a code change and PR for any updates to the quote list. Consider moving the quotes into a separate, version-controlled file (e.g., quotes.txt) within the action's directory. This would allow for easier management, updates, and potential community contributions without altering the core script logic.

  # In src/main.sh
  # ...
  QUOTE_FILE="${GITHUB_ACTION_PATH}/quotes.txt" # Assuming quotes.txt is in the action root
  if [[ ! -f "$QUOTE_FILE" ]]; then
    echo "Error: Quote file not found at $QUOTE_FILE"
    exit 1
  fi
  mapfile -t QUOTES < "$QUOTE_FILE"
  # ...

• Explicit GITHUB_TOKEN permissions: The action relies on GITHUB_TOKEN to post comments. While issues:write permission is often implicitly granted for issues:opened events, explicitly defining the required permissions in the workflow using the permissions key is a best practice for clarity and security.

  # In your workflow file (.github/workflows/zen-quote.yml)
  name: Zen Quote on New Issues
  on:
    issues:
      types: [opened]
  jobs:
    zen-comment:
      runs-on: ubuntu-latest
      permissions:
        issues: write # Explicitly grant write permission for issues
      steps:
        # ...

🧩 Docs/DX

• Consistent naming convention: The directory name github-actions/nightly-nightly-issue-zen-quote-comm contains a redundant "nightly". Consider renaming it to github-actions/nightly-issue-zen-quote-comm for brevity and consistency. This also applies to the utility name mentioned in the PR body.
• Clarify GITHUB_TOKEN requirement in action.yml: Although the README.md provides a usage example, the action.yml itself does not explicitly mention the necessity of GITHUB_TOKEN. Adding a comment within action.yml would inform users inspecting the action definition directly about this crucial environment variable.

  # action.yml
  name: Issue Zen Quote Commenter
  description: Posts a random zen quote as a comment on newly opened issues.
  author: ApocalypsAI
  runs:
    using: "composite"
    steps:
      - name: Run Zen Quote Script
        shell: bash
        run: |
          "${{ github.action_path }}/src/main.sh"
        # Note: This action requires GITHUB_TOKEN to be passed as an environment variable
        # in the calling workflow step, e.g., env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

• Add "Why Zen?" context to README: Briefly explain the rationale or intent behind adding zen quotes to issues. This could be for a whimsical touch, to encourage calm, or to align with a specific project philosophy, adding valuable context for users.

🧱 Mocks/Fakes

• Explicit cleanup of temporary files: The run_test.sh script creates temporary files (CURL_LOG, EVENT_JSON) using mktemp. While these are often cleaned up by the OS, explicitly adding a trap command ensures these files are removed in all scenarios, including early exits due to test failures.

  # In tests/run_test.sh
  #!/usr/bin/env bash
  set -euo pipefail
  
  CURL_LOG=$(mktemp)
  EVENT_JSON=$(mktemp)
  trap 'rm -f "$CURL_LOG" "$EVENT_JSON"' EXIT # Add this line
  
  # ... rest of the test script

• Consider dedicated Bash mocking frameworks for complexity: For this simple script, the custom curl function mock is effective. However, for future Bash actions with more intricate external command interactions or dependencies, exploring dedicated Bash mocking frameworks (e.g., bats-mock, shellspec) could improve test maintainability, readability, and reusability of mock implementations.

[polsala]

🤖 Review by OPENROUTER Agent

✅ What's solid

• Self-contained composite action: The action lives entirely within the repository, uses only Bash and the ubiquitous jq utility, and introduces no external runtime dependencies.
• Clear separation of concerns: The script (src/main.sh) handles payload extraction, quote selection, and the API call, while action.yml simply wires it up as a composite action.
• Deterministic testing approach: The test suite mocks curl, fixes the random seed, and validates that the correct quote is sent to the GitHub API, ensuring reliable behavior verification.

🧪 Tests

• The inclusion of a test script (run_test.sh) is commendable for verifying functionality in isolation.
• Consider expanding test coverage to include edge cases such as:
  • Missing or malformed event payloads.
  • Handling of special characters in quotes (to ensure proper JSON encoding).
  • Behavior when GITHUB_TOKEN is missing or invalid.
• Suggestion: Add an assertion to verify that exactly one curl call is made to prevent accidental duplicate comments.

🔒 Security

• No hardcoded secrets or credentials are present—security best practices are followed here.
• The use of ${{ secrets.GITHUB_TOKEN }} ensures secure access to GitHub’s API without exposing tokens.
• Input validation could be improved:

  if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
    echo "Invalid issue number: $ISSUE_NUMBER"
    exit 1
  fi

  Adding this check would mitigate potential injection risks from malformed payloads.

🧩 Docs/DX

• The README.md provides clear usage instructions and explains how to integrate the action into workflows.
• Minor improvements:
  • Clarify that users should adjust the relative path if they place the action elsewhere.
  • Mention any rate limits associated with commenting via GITHUB_TOKEN.
  • Include troubleshooting tips for common issues like permission errors or missing environment variables.
• Example enhancement:

  > ⚠️ Ensure `issues: write` permissions are granted to the job, otherwise the comment may silently fail.

🧱 Mocks/Fakes

• The test suite includes effective mocking of curl to simulate API interactions without side effects.
• The fixed RANDOM=0 seed ensures consistent test outcomes—a good practice for reproducibility.
• Future enhancements might involve abstracting the quote source to allow dynamic loading (e.g., from a file), which would benefit from additional mocking strategies during testing.

[polsalaTipoDeIncognito]

✅ Auto-approved: All AI agent reviews passed and CI checks succeeded.