feat(groq): A whimsical Bash utility that watches disk usage and alerts with playful messages when a mount exceeds a configurable threshold.

[polsala]

Implementation Summary

• Utility: nightly-disk-guardian
• Provider: groq
• Location: bash-utils/nightly-nightly-disk-guardian
• Files Created: 3
• Description: A whimsical Bash utility that watches disk usage and alerts with playful messages when a mount exceeds a configurable threshold.

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 bash-utils/nightly-nightly-disk-guardian.
• 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 bash-utils/nightly-nightly-disk-guardian/README.md
• Run tests located in bash-utils/nightly-nightly-disk-guardian/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

• Isolation & Scope – The utility lives entirely under bash-utils/nightly-nightly-disk-guardian; no other parts of the repo are touched.
• Robust Bash Practices – Uses #!/usr/bin/env bash with set -euo pipefail, a shebang that works on most platforms, and fails fast on unset variables or pipeline errors.
• Configurable Threshold – Default of 80 % is sensible and can be overridden via the first positional argument.
• Test‑able Design – Accepting an optional DF_FILE lets the script be exercised without touching the host system.
• Clear Exit‑code Contract – 0 = all good, 1 = at least one mount over the limit; this is documented and exercised by the tests.
• Playful UX – The emoji‑prefixed warning makes the output pleasant without sacrificing clarity.

🧪 Tests

The test suite validates the core happy‑path logic, but a few enhancements would make it more resilient:

Issue	Suggested improvement
Edge‑case thresholds – non‑numeric or out‑of‑range values are not exercised.	Add a test that passes foo or 150 and asserts the script exits with a helpful error (e.g. status 2).
Missing/Unreadable DF_FILE – script will cat a non‑existent file and abort with a generic error.	Create a test that points to a non‑existent file and checks for a clear error message (`[[ -r "$DF_FILE" ]]
Empty or malformed df output – ensure the script handles an empty file or a line missing the % column gracefully.	Add a mock file with just the header or with a malformed line and verify the script still exits 0.
Mount points containing spaces – on some systems the “Mounted on” column can contain spaces, breaking $6.	Use a mock where the filesystem name includes spaces (e.g., "/dev/mapper/Vol Group‑LV"). Consider switching to awk '{print $5,$NF}' in the script.
Test framework – plain Bash if …; then works but lacks expressive assertions.	Adopt BATS (Bash Automated Testing System) for clearer @test blocks and run helpers, e.g.: bash\n@test "warns when usage > threshold" {\n run ../src/disk_guardian.sh 80 mock_df.txt\n [ "$status" -eq 1 ]\n [[ "$output" =~ "/" ]]\n}\n
Cleanup – mock_df.txt is left in the repo after test runs.	Use a temporary file via mktemp and trap 'rm -f "$tmp"' EXIT to avoid polluting the working tree.

🔒 Security

• Input validation – The script trusts the first argument to be a numeric percentage. Add a guard:
  bash\nif ! [[ "$THRESHOLD" =~ ^[0-9]+$ ]] || (( THRESHOLD < 0 || THRESHOLD > 100 )); then\n echo \"Error: THRESHOLD must be an integer between 0 and 100\" >&2\n exit 2\nfi\n
• File existence check – Before cat "$DF_FILE" verify it is a regular readable file:
  bash\nif [[ -n "$DF_FILE" ]]; then\n [[ -f "$DF_FILE" && -r "$DF_FILE" ]] || { echo \"Cannot read $DF_FILE\" >&2; exit 2; }\nfi\n
• No command injection – The script does not use eval or construct commands from user input, so the attack surface is minimal. The above checks further harden it.

🧩 Docs / Developer Experience

The README is concise and functional, yet a few additions would improve onboarding:

• Installation tip – Mention making the script executable (chmod +x src/disk_guardian.sh) or providing a wrapper in bin/.
• Sample output – Show the exact warning line, e.g.:
  \n⚠️ / is 85% full – time to clean up!\n
• Error handling section – Document the new exit code 2 for invalid arguments or missing files (once implemented).
• Cross‑platform note – df -h output varies slightly between GNU coreutils and BSD/macOS; advise that the script has been tested on Linux and may need tweaks on macOS.
• Contribution guide – Briefly point contributors to the test conventions (e.g., “use BATS for new tests”).

🧱 Mocks / Fakes

• The current test harness creates a static mock_df.txt file in the repository. Switching to an in‑memory temporary file (via mktemp) prevents accidental commits of test artefacts and ensures isolation between parallel CI runs.
• If the project adopts BATS, the mock can be generated inside a setup function and automatically torn down with teardown.

---

Overall, the utility is a delightful addition with solid fundamentals. Addressing the input‑validation, edge‑case testing, and a few documentation tweaks will make it production‑ready and easier for future contributors to maintain.

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Robust Bash Practices: The use of #!/usr/bin/env bash and set -euo pipefail demonstrates strong adherence to best practices for shell scripting, ensuring portability and early failure detection.
• Clear Exit Codes: The script's defined exit codes (0 for no warning, 1 for warning) are well-documented and provide a clear interface for integration into other scripts or monitoring systems.
• Testability via DF_FILE: The DF_FILE parameter is an excellent design choice, enabling straightforward and reliable testing by allowing mock df -h output to be injected.
• Self-contained and Isolated: The utility is entirely self-contained within its directory, minimizing potential side effects on other parts of the repository.

🧪 Tests

• Test Cleanup: The mock_df.txt file created by test_disk_guardian.sh is not removed after the tests complete. This can leave artifacts in the filesystem.
  • Consider adding a trap command to ensure the mock file is cleaned up automatically, even if tests fail.

  # In tests/test_disk_guardian.sh
  trap 'rm -f mock_df.txt' EXIT

• Edge Case Testing:
  • Add a test case for an empty or malformed DF_FILE to ensure the script handles these scenarios gracefully without unexpected errors or infinite loops.
  • Include tests for THRESHOLD values at the boundaries, such as 0 and 100, to confirm correct behavior.
  • Test with df output that contains only the header line and no actual mount points.

🔒 Security

• Input Validation for THRESHOLD: The THRESHOLD variable is taken directly from the first argument. If a non-numeric or out-of-range value is provided, the arithmetic comparison (( usage > THRESHOLD )) could lead to unexpected errors or incorrect behavior.
  • Implement explicit validation to ensure THRESHOLD is a numeric value between 0 and 100.

  # In src/disk_guardian.sh, after THRESHOLD is set
  if ! [[ "$THRESHOLD" =~ ^[0-9]+$ ]] || (( THRESHOLD < 0 || THRESHOLD > 100 )); then
    echo "Error: THRESHOLD must be a number between 0 and 100." >&2
    exit 2 # Use a distinct exit code for script errors
  fi

• df -h Output Parsing Robustness: The script relies on awk '{print $5}' and awk '{print $6}' to extract usage and mount points. The exact column positions in df -h output can vary slightly across different operating systems or df versions.
  • While awk is generally robust, consider if there are edge cases (e.g., mount points with spaces or special characters, or different df output formats) that could cause parsing issues. A more defensive parsing approach might involve looking for specific patterns rather than fixed column numbers, or using read -a if the column count is guaranteed.

🧩 Docs/DX

• Error Exit Codes: The script currently uses exit code 1 for both "threshold exceeded" and potential script errors (e.g., if set -e triggers due to an invalid THRESHOLD).
  • Consider using distinct exit codes for different types of failures. For example, 1 for "threshold exceeded" (as currently defined) and 2 for "script execution error" (e.g., invalid arguments, parsing issues). This provides more granular feedback for automated systems.
• README Example for Default Threshold: The README.md shows ./src/disk_guardian.sh which uses the default 80% threshold. It might be helpful to explicitly state the default in the example for clarity, e.g., ./src/disk_guardian.sh # checks with default 80% threshold.

🧱 Mocks/Fakes

• Effective Mocking Strategy: The DF_FILE parameter is an excellent and simple mocking mechanism for a Bash utility. It allows for complete control over the df -h output without complex setup or external tools.
• Self-contained Test Data: The test script's method of generating mock_df.txt dynamically ensures that tests are self-contained and reproducible, which is ideal for maintaining test integrity.
• No Further Mocks Needed: Given the utility's scope and its reliance on a single external command (df), the current mocking strategy is highly effective and sufficient. No additional complex mocks or fakes appear necessary.