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/jamesrwhite/minicron 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.

WAIT — Stale — last commit 5y ago

• 10 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{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 jamesrwhite/minicron repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jamesrwhite/minicron.

What it runs against: a local clone of jamesrwhite/minicron — 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 jamesrwhite/minicron | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1849 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jamesrwhite/minicron. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jamesrwhite/minicron.git
#   cd minicron
#
# 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 jamesrwhite/minicron and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "client/main.go" \\
  && ok "client/main.go" \\
  || miss "missing critical file: client/main.go"
test -f "client/commands/root.go" \\
  && ok "client/commands/root.go" \\
  || miss "missing critical file: client/commands/root.go"
test -f "client/run/run.go" \\
  && ok "client/run/run.go" \\
  || miss "missing critical file: client/run/run.go"
test -f "client/api/api.go" \\
  && ok "client/api/api.go" \\
  || miss "missing critical file: client/api/api.go"
test -f "client/glide.yaml" \\
  && ok "client/glide.yaml" \\
  || miss "missing critical file: client/glide.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1849 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1819d)"
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/jamesrwhite/minicron"
  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).

minicron is a cron job monitoring and management system with a web UI that lets you define, execute, and track scheduled tasks across servers. It consists of a Go CLI client that runs on servers and relays job execution data (output, status, timing) back to a Ruby/Rails web server where you view logs, set up alerts (email, SMS, Slack, PagerDuty), and manage cron schedules via GUI. It solves the problem of invisible cron failures by providing centralized visibility and alerting. Split monorepo: /client is a standalone Go CLI application (using Cobra-like CLI pattern via commands/root.go, commands/run.go) that communicates with a Ruby/Rails backend server (presumed in root or server/ directory based on nginx/apache config files referenced). Client watches for changes via fsnotify and sends job execution data to the server API.

DevOps engineers and system administrators who run critical recurring tasks (database backups, data syncs, cleanups) and need to know immediately when a job fails or doesn't execute. They want to replace unreliable cron logging with centralized monitoring and alerting without rewriting their shell scripts.

Abandoned. The README explicitly states 'minicron is no longer being worked on' and is stuck at v0.9.6 (released 2015–2016 era). Master branch shows attempted v1.0 work but no active commits visible. Zero indication of CI passing, tests, or recent activity. Do not use in production without a maintenance commitment.

High risk: single-author project with no active maintenance since ~2016, no visible test coverage, complex cross-service architecture (Go client + Ruby server + database + reverse proxy), tight coupling to old versions of Go and Ruby gems (glide.lock shows ancient dependencies). If a security issue or compatibility problem arises, you're on your own.

Nothing. The master branch is a frozen snapshot of incomplete v1.0 work. The latest stable release is v0.9.6 on a separate branch. No open PRs, commits, or issues are being addressed.

git clone https://github.com/jamesrwhite/minicron.git
cd minicron/client
glide install
make build
./minicron help run

Daily commands: Client only: cd client && make build && ./minicron run 'your command'. Full stack: Requires a running Rails server (not present in this listing—check main project directory or server/ if it exists). See .travis.yml for CI setup hints. Currently broken: Makefile and build.sh exist but no clear entrypoint documented.

• client/main.go — Entry point for the minicron client application; initializes CLI commands and configuration.
• client/commands/root.go — Root command definition; sets up the CLI structure and command routing for all client operations.
• client/run/run.go — Core execution logic that runs cron jobs locally and handles job invocation semantics.
• client/api/api.go — API client for communication with the minicron server; handles all remote job data relay.
• client/glide.yaml — Dependency manifest for Go vendored packages; critical for understanding all external dependencies.
• client/Dockerfile — Container image definition; shows how the client is packaged and deployed in production.
• .travis.yml — CI/CD pipeline configuration; defines build, test, and release processes for the project.

• CLI Entry Point (main.go, commands/root.go) (Go CLI framework (likely Cobra or similar)) — Parses command-line arguments and routes to appropriate subcommand handler
  • Failure mode: Invalid arguments or missing subcommand causes usage error and early exit
• Job Executor (run/run.go) (Go os/exec package for process spawning) — Invokes job process, captures stdout/stderr/exit code, and collects execution metadata
  • Failure mode: Process failure, timeout, or signal handling may not fully capture output; network delivery still attempted
• API Client (api/api.go) (Go net/http for HTTP requests) — Encapsulates HTTP communication to relay job results to the minicron server
  • Failure mode: Network unavailability or server downtime causes local failure logging; results may be lost if not retried by cron
• Build & Packaging (Makefile, Dockerfile) (Go toolchain, Docker, shell scripts) — Compiles client binary and packages it as a Docker image for deployment
  • Failure mode: Build failures prevent release; missing dependencies cause compilation errors

• System Cron → minicron Client — Scheduled invocation with job ID and optional arguments
• minicron Client → Job Executor — CLI args trigger job process invocation with captured output
• Job Executor → API Client — Process exit code, stdout, stderr, and timing metadata
• API Client → minicron Server — HTTP POST with job execution result (output, status, timestamps)
• minicron Server → Web UI / Alerts — Server stores and displays job history; triggers alerts based on rules

Add a new CLI command

1. Create a new file under client/commands/ (e.g., client/commands/mycommand.go) (client/commands/mycommand.go)
2. Define a Command struct and implement Execute() method following the pattern in client/commands/run.go (client/commands/run.go)
3. Register the command in the root command's initialization code (client/commands/root.go)

Modify job execution behavior

1. Update the job invocation logic in the Run() function (client/run/run.go)
2. Adjust output capture or error handling as needed (client/run/run.go)

Change server API communication

1. Edit the API client methods to modify request/response handling (client/api/api.go)
2. Update endpoint URLs or authentication if needed (client/api/api.go)

Add a new Go dependency

1. Update the dependency spec in the dependency manifest (client/glide.yaml)
2. Run glide install to update the lock file and vendor directory (client/glide.lock)

• Go — Lightweight, compiled language ideal for a small distributed client agent that must be deployed across many servers with minimal resource overhead.
• Docker — Containerization enables simple, reproducible deployment of the client across diverse infrastructure without dependency conflicts.
• Glide (Go dependency manager) — Provides vendoring and lock files for reproducible builds in an era before Go modules, ensuring consistent dependency resolution.
• Travis CI — GitHub-integrated CI/CD enables automated testing, building, and multi-platform binary distribution on every commit.

• Client-server architecture with client polling/pushing to server

  • Why: Avoids need for persistent inbound connections or open firewall ports on monitored servers; clients initiate all communication.
  • Consequence: Server cannot push alerts or commands to clients in real-time; relies on eventual consistency and client-initiated heartbeats.

• Single-purpose client agent focused only on job execution and reporting

  • Why: Minimizes client footprint and complexity; keeps agent maintainable and lightweight.
  • Consequence: All monitoring logic, alerting, and UI live on the server; more centralized but creates a single point of failure for visibility.

• Local output capture and relay over HTTP

  • Why: Avoids heavy instrumentation; captures standard Unix job semantics (exit codes, streams).
  • Consequence: No real-time streaming of long-running job output; all output must complete and be batched before transmission.

• Real-time streaming of job output during execution
• Authentication/authorization on the client (security delegated to server and network layer)
• Persistent local job queue or retry logic (expected to be handled by system cron or orchestrator)
• Windows cron support (Unix/Linux cron-focused)

• Unmaintained project state (High) — README.md: Project explicitly states it is no longer actively developed; v0.9.x is final stable release and v1.0 is stalled.
• Potential error swallowing in API communication (Medium) — client/api/api.go: If API calls fail, errors may be logged but not propagated to caller; no clear retry or fallback strategy visible.
• Vendored dependencies in version control (Low) — client/vendor/: Large vendor/ directory committed directly; modern Go practice prefers go.mod and go.sum with lazy module loading.

• client/api/api.go (I/O latency) — All job result relay goes through a single synchronous HTTP POST; network latency or server unavailability blocks client exit.
• client/run/run.go (undefined) —

1. No Rails code visible in listing: The actual backend server code is not shown; you must locate it (likely in a server/ directory or separate branch). The file list only shows client/. 2. Vendored dependencies are ancient: glide was deprecated in favor of go mod around 2019; fsnotify and hcl versions are locked but may have security issues. 3. Config parsing via HCL: Client reads job definitions using HashiCorp HCL, not YAML or JSON—check docs for syntax. 4. Docker Compose missing: Client Dockerfile exists but no docker-compose.yml to orchestrate client + server + database locally. 5. Environment variable assumptions: Client likely needs MINICRON_SERVER_URL and auth tokens to communicate; undocumented. 6. Database migrations: Server expects a database; no migration scripts visible in listing, so you must find them separately.

• Distributed Agent-Server Architecture — minicron's core: lightweight agents (Go CLI) on target servers report back to a central server (Rails). Understanding this pattern is essential for debugging communication failures, scaling to multiple servers, and securing the data channel.
• File System Notifications (fsnotify) — The client uses fsnotify to watch for job execution events; minicron likely monitors config files or job output directories to trigger server syncs without polling.
• HCL (HashiCorp Configuration Language) — Job definitions are parsed via HCL, not YAML; you must learn HCL syntax to understand how cron schedules and commands are defined in minicron config files.
• Reverse Proxy (Nginx/Apache) — Example configs in server/config/ show that the Rails server sits behind a reverse proxy; understanding proxy headers, path rewriting, and SSL termination is critical for deployment.
• Cron Schedule Expression Parsing — minicron must parse and validate cron syntax (0 9 * * MON), likely using a Go library; failures in parsing lead to jobs that never run or run at wrong times.
• Docker Multi-Stage Builds — Both client/Dockerfile and root Dockerfile are present; understanding layering and artifact copying is needed to optimize image size and reduce the attack surface.
• Go Package Vendoring (Glide) — Dependencies are vendored in client/vendor/ using the deprecated Glide tool; understanding how to add, update, and lock transitive dependencies is essential for maintenance despite Glide being obsolete.

• prometheus/node_exporter — Monitoring agent pattern: like minicron's client, it's a daemon that collects metrics and pushes to a central server.
• elastic/beats — Lightweight agent framework for shipping telemetry; minicron's client architecture mirrors this agent-server pattern.
• hashicorp/nomad — Orchestrates scheduled jobs across a cluster; competes with minicron's goal of centralizing cron job management.
• urfave/cli — Popular Go CLI framework; minicron's client uses a similar pattern and could migrate to this for cleaner command handling.
• ofelia/ofelia — Modern alternative to minicron: Docker-native job scheduler; targets the same DevOps pain point but with container-first design.

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 unit tests for client/api/api.go

The client/api/api.go file handles communication between the minicron client and server, but there are no corresponding test files visible in the repo. Adding comprehensive unit tests for API request/response handling, error cases, and retries would improve reliability and make it safer for contributors to modify this critical integration layer.

• [ ] Create client/api/api_test.go with test cases for HTTP client initialization
• [ ] Add tests for API request methods (mocking server responses)
• [ ] Add tests for error handling and timeout scenarios
• [ ] Run tests locally with go test ./client/api/... and verify coverage

Add unit tests for client/run/run.go

The client/run/run.go module handles job execution logic, but no test file exists. This is critical for ensuring jobs run correctly and capture output/exit codes properly. Unit tests here would catch regressions and provide confidence for refactoring.

• [ ] Create client/run/run_test.go with test cases for command execution
• [ ] Add tests for stdout/stderr capture and parsing
• [ ] Add tests for timeout and signal handling
• [ ] Add tests for exit code reporting

Migrate from glide to Go modules and update .travis.yml

The repo uses glide.yaml and glide.lock (dated Go dependency management) instead of modern Go modules (go.mod/go.sum). The .travis.yml likely uses outdated Go versions and doesn't leverage Go module caching. Modernizing this would improve build times, simplify local development, and align with current Go best practices.

• [ ] In client/ directory, run go mod init github.com/jamesrwhite/minicron/client to create go.mod
• [ ] Run go mod tidy to populate go.mod and go.sum from existing glide.lock dependencies
• [ ] Remove client/glide.yaml and client/glide.lock files
• [ ] Update .travis.yml to use modern Go versions (1.16+) and add module caching: go mod download step
• [ ] Test locally that builds work with go build ./client and update build.sh if needed

• Add unit tests to client/api/api.go: currently 0 tests visible for HTTP client code; write tests using Go's net/http/httptest for POST/GET endpoints.
• Migrate client/glide.yaml to Go modules (go.mod): Replace glide with modern Go 1.13+ module system; update fsnotify and HCL to latest versions and verify compatibility.
• Create a quickstart guide in README.md for the v1.0 branch: Document how to build both client and server, what environment variables are needed, and a working example using Docker Compose.

The minicron project presents significant security concerns due to its unmaintained status combined with limited code visibility. The project is no longer actively developed, meaning new vulnerabilities will not receive patches. Vendored dependencies lack visible version information and may contain known CVEs. Without access to actual implementation code, critical vulnerabilities in API authentication, input handling, and secure communication cannot be assessed. The use of Docker without visible security configuration, absence of security governance documentation, and lack of modern dependency management practices further reduce confidence in the security posture. This project should not be used in production environments without substantial additional security hardening and ongoing monitoring.

• High · Outdated and Unmaintained Project — README.md, Project Repository. The project is explicitly marked as no longer being actively developed or supported. The latest stable release is v0.9.6, and the master branch is in an incomplete state toward v1.0. This means security vulnerabilities discovered will not receive patches or fixes. Fix: Consider using an actively maintained alternative for cron job monitoring. If using this project, conduct a thorough security audit and implement additional security controls at the infrastructure level.
• High · Unverified Vendored Dependencies — client/vendor/, client/glide.yaml, client/glide.lock. The project uses vendored dependencies (client/vendor directory) including fsnotify and HCL parser. Without access to the actual glide.lock content, the specific versions and known vulnerabilities cannot be determined. Vendored dependencies may contain outdated or vulnerable packages that are not automatically updated. Fix: Audit all vendored dependencies for known CVEs. Update to latest secure versions. Consider using Go modules instead of vendoring for better dependency management and security tracking.
• Medium · Insufficient Code Visibility — client/api/api.go, client/commands/*, client/run/*. The actual implementation code (client/api/api.go, client/commands/, client/run/) content is not provided for review. Without examining the actual code, common vulnerabilities like improper authentication, insecure API communication, command injection, or unvalidated input handling cannot be assessed. Fix: Perform comprehensive code review focusing on: API authentication/authorization mechanisms, input validation and sanitization, secure credential handling, TLS/SSL certificate validation, and protection against command injection attacks.
• Medium · Docker Image Security Not Visible — client/Dockerfile. A Dockerfile exists (client/Dockerfile) but its content is not provided for review. Docker images may contain security misconfigurations such as running as root, using outdated base images, or exposing unnecessary ports. Fix: Review Dockerfile to ensure: base image is minimal and regularly updated, application runs with least privilege (non-root user), unnecessary packages are not included, and security scanning is integrated into the build pipeline.
• Medium · No Visible Security Configuration Files — Repository Root. The codebase lacks visible security-related configuration files such as SECURITY.md, security policies, or security headers configuration. This suggests minimal security governance and no clear vulnerability disclosure process. Fix: Create SECURITY.md with vulnerability disclosure policy, implement security headers (HSTS, CSP, X-Frame-Options), add security linting tools to CI/CD pipeline, and establish dependency scanning.
• Low · Lack of HTTPS Enforcement Clarity — client/api/api.go, build.sh. Based on the file structure showing API communication between client and server, there is no visible evidence of HTTPS/TLS enforcement configuration or certificate pinning strategies. Fix: Ensure all client-server communication uses HTTPS with TLS 1.2+, implement certificate pinning for sensitive operations, and validate SSL/TLS certificates properly.

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.