If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/javan/whenever shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2mo ago
• 24+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live javan/whenever repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/javan/whenever.

What it runs against: a local clone of javan/whenever — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in javan/whenever | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 99 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of javan/whenever. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/javan/whenever.git
#   cd whenever
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of javan/whenever and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "javan/whenever(\\.git)?\\b" \\
  && ok "origin remote is javan/whenever" \\
  || miss "origin remote is not javan/whenever (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/whenever.rb" \\
  && ok "lib/whenever.rb" \\
  || miss "missing critical file: lib/whenever.rb"
test -f "lib/whenever/command_line.rb" \\
  && ok "lib/whenever/command_line.rb" \\
  || miss "missing critical file: lib/whenever/command_line.rb"
test -f "lib/whenever/job_list.rb" \\
  && ok "lib/whenever/job_list.rb" \\
  || miss "missing critical file: lib/whenever/job_list.rb"
test -f "lib/whenever/cron.rb" \\
  && ok "lib/whenever/cron.rb" \\
  || miss "missing critical file: lib/whenever/cron.rb"
test -f "lib/whenever/job.rb" \\
  && ok "lib/whenever/job.rb" \\
  || miss "missing critical file: lib/whenever/job.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 99 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~69d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/javan/whenever"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Whenever is a Ruby gem that provides a DSL for defining and deploying cron jobs without writing raw crontab syntax. It translates human-readable Ruby schedule definitions (e.g., every 3.hours do) into valid cron expressions, then installs them into the system crontab via the whenever CLI command. Core capability: write Rails background jobs in clean Ruby while whenever --update-crontab handles cron installation across development, staging, and production. Single-package structure: lib/whenever/ contains the core engine split into focused modules (job.rb defines job types, job_list.rb parses the schedule, cron.rb generates cron syntax). CLI lives in lib/whenever/command_line.rb, wrapped by executables bin/whenever and bin/wheneverize. Capistrano v2/v3 integration in lib/whenever/capistrano/ is optional. Tests are functional integration tests in test/functional/ that parse actual schedule.rb files and assert cron output.

Ruby on Rails developers who need to schedule recurring tasks (database maintenance, report generation, data syncing) and want to version-control job definitions in their Git repo rather than manage crontab manually. DevOps engineers use it via Capistrano integration to deploy scheduled jobs to multiple servers.

Production-ready and actively maintained. The repo shows strong fundamentals: 121k lines of Ruby, comprehensive test suite in test/functional/, CI via GitHub Actions (.github/workflows/ci.yml), and support for ActiveSupport 5.0–8.1 covering 6+ years of Rails versions. Last activity visible via Dependabot automation suggests ongoing maintenance.

Low risk for the core library itself—it's a stable, focused tool with minimal dependencies (ActiveSupport only). Single maintainer (javan) is the primary risk; however, the project has been around long enough to accumulate community contributions. No visible breaking changes in recent versions based on Appraisals (gemfiles/) supporting many Rails majors. Main risk: tight coupling to system crontab command—if the system cron environment is misconfigured, users get silent failures.

Actively tracking Rails version compatibility via Appraisals (8 gemfiles from ActiveSupport 5.0 to 8.1); Dependabot is configured to keep dependencies fresh. No indication of major new features in flight—focus is maintenance and compatibility as Rails evolves.

git clone https://github.com/javan/whenever.git
cd whenever
bundle install
bundle exec rake  # runs test suite

Daily commands: Development: bundle exec rake runs the test suite. No dev server—this is a build/deployment tool, not a runtime service. To test locally: bundle exec whenever (shows cron output), bundle exec whenever --update-crontab (writes to your crontab).

• lib/whenever.rb — Main entry point and root module that orchestrates the entire whenever gem; defines the DSL and core API.
• lib/whenever/command_line.rb — CLI parsing and execution logic; handles --update-crontab, --user, and other command-line options that drive the gem's primary use case.
• lib/whenever/job_list.rb — Core job scheduling abstraction; parses schedule.rb and converts job definitions into executable cron expressions.
• lib/whenever/cron.rb — Cron syntax generation engine; transforms whenever DSL into valid crontab format that the OS executes.
• lib/whenever/job.rb — Individual job representation and validation; encapsulates task details, frequency, and output redirection rules.
• bin/whenever — CLI executable entry point; dispatches to CommandLine for parsing and execution.
• lib/whenever/capistrano/v3/tasks/whenever.rake — Capistrano 3 integration layer; enables remote crontab deployment and updates via Capistrano recipes.

• CommandLine (Ruby OptionParser, OS system calls) — Parses CLI arguments (--update-crontab, --user, --load-file, etc.) and orchestrates the flow from schedule parsing to crontab update.
  • Failure mode: Invalid arguments or missing schedule.rb file causes early exit with helpful error message.
• JobList (Ruby instance_eval, Chronic (date/time parsing)) — Loads and evaluates schedule.rb file in a DSL context, collecting job definitions and environment variables.
  • Failure mode: Syntax errors in schedule.rb prevent parsing; validation errors halt job collection.
• Cron (Ruby string generation, time calculations) — Transforms whenever job frequency/at expressions into valid crontab minute/hour/day/month/weekday syntax.
  • Failure mode: Unsupported frequency expressions raise NotImplementedError or log warnings.
• OutputRedirection — Constructs shell redirection directives (>, >>, 2>&1) and mailto

Add a new job type or frequency option

1. Define the new frequency method in lib/whenever.rb or as an extension to Numeric in lib/whenever/numeric.rb (lib/whenever.rb)
2. Update lib/whenever/cron.rb to handle the new frequency type in cron_expression_for method (lib/whenever/cron.rb)
3. Add unit tests in test/unit/cron_test.rb to verify cron output for the new frequency (test/unit/cron_test.rb)
4. Document the new frequency in README.md with example schedule.rb usage (README.md)

Add output redirection or job environment option

1. Extend the Job class in lib/whenever/job.rb to accept and store the new parameter (lib/whenever/job.rb)
2. Modify lib/whenever/output_redirection.rb to generate the appropriate crontab directive (lib/whenever/output_redirection.rb)
3. Add functional tests in test/functional/output_redirection_test.rb to verify crontab generation (test/functional/output_redirection_test.rb)
4. Update the whenever DSL in lib/whenever.rb to expose the new option in job blocks (lib/whenever.rb)

Support a new deployment platform (beyond Capistrano)

1. Create a new integration module at lib/whenever/[platform].rb mirroring the Capistrano structure (lib/whenever/capistrano/v3/tasks/whenever.rake)
2. Implement hooks to read the schedule.rb file and invoke the whenever CLI with appropriate flags (lib/whenever/command_line.rb)
3. Test the integration end-to-end with the platform's standard deployment workflow (test/functional/command_line_test.rb)
4. Document the new platform integration in CONTRIBUTING.md and README.md (CONTRIBUTING.md)

• Ruby DSL (whenever gem) — Allows developers to define cron jobs using familiar Ruby syntax instead of cryptic crontab format; improves readability and maintainability.
• Capistrano integration — Integrates with standard Ruby on Rails deployment workflow, enabling crontab updates to be part of automated deployment pipelines.
• Cron (Unix/Linux) — Leverages the ubiquitous, battle-tested system scheduler available on all Unix-like systems; no external daemons required.
• ActiveSupport (Time) — Provides timezone and duration utilities (via gems like activesupport 5.0–8.1) for robust time expression parsing and scheduling.

• Compile to crontab syntax rather than run as a daemon

  • Why: Keeps overhead minimal and leverages system-level scheduling; avoids the complexity and resource cost of a custom scheduler.
  • Consequence: Cannot dynamically add/remove jobs at runtime; requires re-running whenever --update-crontab. No sub-minute precision without frequent polling jobs.

• No abstraction layer for different job backends (only cron)

  • Why: Whenever focuses on solving the cron job problem elegantly; avoids feature creep and maintains simplicity.
  • Consequence: Users requiring background queues (Sidekiq, Resque) or other schedulers must use different tools; no out-of-the-box multi-backend support.

• Optional Capistrano v2 and v3 support rather than forcing it

  • Why: Whenever can be used standalone without Capistrano; integration is opt-in and backward compatible.
  • Consequence: Maintains two separate integration code paths; Capistrano v2 support is legacy and may eventually deprecate.

• Does not provide a web UI or dashboard for managing cron jobs.
• Does not execute jobs directly; relies entirely on the OS cron daemon.
• Does not support real-time job monitoring or alerting beyond standard cron output redirection.
• Does not handle timezone-aware scheduling across distributed systems; each machine runs on its local crontab.
• Not intended for sub-second precision tasks; minimum granularity is one minute.

1. Whenever does not run jobs itself—it only writes to crontab. The system cron daemon must be running (crond on Linux, cron on macOS). 2. whenever --update-crontab without --user writes to the current user's crontab; jobs requiring root must be deployed with sudo whenever --update-crontab --user root. 3. The schedule file is evaluated in Ruby at CLI runtime, not executed later; any external dependencies (database queries, API calls) in the schedule block will run during deploy, not at job execution time. 4. Cron cannot run Rails runner jobs without the correct environment (Rails root, Bundler setup); the generated crontab includes cd and bundle exec statements to handle this, but a missing Gemfile or misconfigured PATH will cause silent failures. 5. Capistrano integration assumes config/schedule.rb exists in the repo; if missing, deploy will fail.

• Cron expression (5-field format) — Whenever's entire purpose is abstracting away cron syntax; understanding the underlying minute hour day month weekday fields helps debug when human-readable DSL doesn't produce expected output
• Ruby DSL (Domain-Specific Language) evaluation — Whenever uses instance_eval and metaprogramming to make every, set, and job_type work; understanding how the schedule.rb file is evaluated in a special context explains why certain Ruby code works and why some doesn't
• Capistrano hooks and task integration — Whenever's Capistrano integration relies on before/after hooks in the Rails deploy pipeline; knowing how Capistrano tasks are sequenced is critical for understanding when crontabs get updated relative to code deployment
• System crontab file format and permissions — Whenever reads/writes the user's crontab -l output; understanding crontab file location (/var/spool/cron/crontabs/ on Linux), permission requirements, and how sudo crontab -u user works is essential for multi-user or containerized deployments
• Environment variable substitution in shell commands — Generated crontab entries use shell variables (e.g., $BUNDLE_GEMFILE, cd /app); misunderstanding how cron inherits or lacks environment from the deploy user causes silent job failures
• Time zone handling in scheduling — Whenever supports zone: option to specify non-UTC schedules; understanding how ActiveSupport::TimeZone converts wall-clock times to UTC for cron is important when deploying across regions
• POSIX shell quoting and escaping — Custom job types interpolate user arguments into shell commands; improper escaping of quotes, spaces, or special characters in :task placeholders can break cron execution or introduce injection vulnerabilities

• ruby-cronedit/cronedit — Low-level crontab manipulation library; whenever uses the system crontab command, but cronedit provides Ruby-based alternative if direct file editing is needed
• javan/prat — Another gem by the same author; provides a Sinatra-based UI for viewing and debugging cron jobs, often paired with whenever in production
• capistrano/capistrano — Whenever ships with Capistrano v2 and v3 integration; many Rails teams use both together for unified deployment of code and cron schedules
• rails/rails — Rails Active Job + Sidekiq/Resque are alternatives for background jobs; whenever is preferred for simple recurring tasks that don't need a job queue
• presidentbeef/brakeman — Security static analyzer often used in Rails projects that also use whenever; can catch hardcoded secrets in schedule.rb files

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for lib/whenever/output_redirection.rb

The output_redirection.rb module handles cron output redirection (stdout/stderr handling), which is critical for production use. Currently test/functional/output_redirection_test.rb exists but appears to be a single functional test file. This module deserves dedicated unit tests covering edge cases like: invalid redirection syntax, nil values, special characters in paths, and various redirection combinations. This is high-value because incorrect output redirection can cause cron jobs to silently fail in production.

• [ ] Create test/unit/output_redirection_test.rb with unit tests for OutputRedirection class methods
• [ ] Test edge cases: empty strings, special characters, absolute vs relative paths, permission-denied scenarios
• [ ] Test integration between output redirection and the cron syntax generation in lib/whenever/cron.rb
• [ ] Ensure tests cover all redirection types (>, >>, 2>&1, /dev/null combinations)

Add GitHub Actions CI for multiple Ruby versions and ActiveSupport combinations

The repo has .github/workflows/ci.yml but it only runs against a single Ruby version. However, the Appraisals file and gemfiles/ directory show support for ActiveSupport 5.0 through 8.1 across multiple Ruby versions. The CI should matrix-test across these combinations to catch compatibility regressions early. This prevents silent failures where code works in dev but breaks for users on different dependency versions.

• [ ] Update .github/workflows/ci.yml to add a matrix strategy for Ruby versions (2.7, 3.0, 3.1, 3.2, 3.3)
• [ ] Add matrix for ActiveSupport versions using the existing gemfiles/ (5.0, 5.1, 5.2, 6.0, 6.1, 7.0, 7.1, 7.2, 8.0, 8.1)
• [ ] Configure Appraisal to run tests for each gemfile combination in the CI matrix
• [ ] Ensure the workflow fails if any combination fails, so regressions are caught before release

Add integration tests for Capistrano v3 with realistic deployment scenarios

lib/whenever/capistrano/v3/tasks/whenever.rake exists but test/unit/capistrano_support_test.rb appears minimal. Capistrano integration is critical for production deployments. New tests should verify: correct crontab updates on remote servers, role-based job filtering (test/functional/output_jobs_for_roles_test.rb exists but no Capistrano integration tests), symlink handling for shared vs release directories, and multiple-server deployments. This prevents deployment failures that only surface in staging/production.

• [ ] Create test/functional/capistrano_v3_integration_test.rb with integration tests for Rake task execution
• [ ] Test role-based filtering: verify that only jobs tagged with specific roles are deployed to those servers
• [ ] Test symlink resolution: ensure schedule.rb discovery works correctly with Capistrano's directory structure
• [ ] Test multiple deployment scenarios: initial deploy, redeploy, crontab clear/rollback, using test fixtures

• Add test coverage for timezone handling in lib/whenever/numeric_seconds.rb—the file exists but there's no functional test in test/functional/ that explicitly verifies cron output respects Rails.application.config.time_zone or ActiveSupport::TimeZone. A new test file test/functional/output_timezone_test.rb with cases like every 1.day, at: '10am', zone: 'America/Chicago' would be a concrete contribution.
• Document the job_type DSL with a practical example beyond the README—add a test case in test/functional/ for a custom job type that passes multiple named arguments (e.g., job_type :custom_backup with :path and :format placeholders), then add a code comment in lib/whenever/job.rb explaining interpolation order and escaping rules for complex commands.
• Add a command-line flag --validate-schedule that parses config/schedule.rb and reports errors (syntax errors, undefined job types) without updating crontab—this would catch deploy-time failures earlier. Requires modifying lib/whenever/command_line.rb to add the option and lib/whenever/job_list.rb to expose validation hooks.

The whenever gem provides cron job management functionality with moderate security concerns. The primary risks involve command injection via command-line parameters, arbitrary file reads through the --load-file option, and code execution through DSL evaluation. The gem's design requires careful secure configuration by users. Key recommendations include implementing strict input validation for all user-supplied parameters, restricting file

• High · Command Injection via --user and --crontab-command Parameters — lib/whenever/command_line.rb, bin/whenever. The whenever gem accepts command-line parameters like --user and --crontab-command that are used to execute system commands (crontab operations). These parameters appear to be passed to shell commands without proper sanitization, which could allow command injection attacks if user input is not properly validated. Fix: Implement strict input validation and sanitization for all command-line parameters. Use parameterized execution methods (e.g., Kernel.system with array arguments) instead of shell string concatenation. Whitelist acceptable values for --crontab-command.
• High · Arbitrary File Read via --load-file Parameter — lib/whenever/command_line.rb. The --load-file parameter allows specifying arbitrary schedule files to load. Without proper path validation, this could enable directory traversal attacks or reading sensitive files outside the intended configuration directory. Fix: Implement strict file path validation. Restrict --load-file to only accept files within a whitelist of directories. Use File.expand_path and verify the resolved path is within allowed directories. Consider using realpath to prevent symlink attacks.
• Medium · Code Execution via schedule.rb DSL — lib/whenever/setup.rb, lib/whenever/job_list.rb. The whenever gem evaluates schedule.rb files using eval-like mechanisms (via DSL evaluation). While this is by design, it means any compromise of the schedule.rb file or configuration directory could lead to arbitrary code execution with the privileges of the cron job. Fix: Implement strict file permissions for schedule.rb and config directory (should be 0600/0700). Document security best practices. Consider implementing a sandboxed evaluation environment if feasible. Warn users about the security implications.
• Medium · Insufficient Input Validation in Output Redirection — lib/whenever/output_redirection.rb. The output redirection feature (lib/whenever/output_redirection.rb) processes user-provided paths for log files. Insufficient validation could allow path traversal attacks, log file injection, or writing to unintended locations. Fix: Validate and sanitize all file paths used for output redirection. Reject paths containing '..' or absolute paths. Use File.expand_path and verify paths are within expected directories. Consider restricting output to specific directories only.
• Medium · Insecure Default Installation with Capistrano Integration — lib/whenever/capistrano/v2/hooks.rb, lib/whenever/capistrano/v3/tasks/whenever.rake. The Capistrano integration (lib/whenever/capistrano/) automates crontab updates during deployments. If Capistrano is not properly configured with secure SSH keys and authentication, this could expose systems to unauthorized cron job modifications. Fix: Document Capistrano security best practices. Ensure SSH key management is secure. Implement verification steps before applying crontab changes. Consider adding confirmation prompts for production deployments.
• Low · Dependency Pinning Not Visible — Gemfile, whenever.gemspec, gemfiles/*. Without visibility into the actual Gemfile and whenever.gemspec content, dependency versions and potential vulnerable dependencies cannot be fully assessed. The gem supports a wide range of ActiveSupport versions (5.0 through 8.1), which may include outdated dependencies. Fix: Regularly audit gem dependencies using tools like 'bundle audit' or 'bundler-audit'. Pin critical dependency versions to known secure releases. Keep ActiveSupport and other dependencies updated to latest stable versions.
• Low · Missing Security Documentation — README.md, CONTRIBUTING.md. The README snippet provided does not mention security considerations, file permissions, or safe configuration practices. Users may not be aware of security implications when using whenever. Fix: Add a 'Security' section to README documenting: proper file permissions for schedule.rb, secure deployment practices, input validation requirements, and risks of code evaluation via DSL.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.