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/laserlemon/figaro 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 all four use cases

• Last commit 10mo ago
• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 10mo ago
• ⚠ Single-maintainer risk — top contributor 90% of recent commits

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

What it runs against: a local clone of laserlemon/figaro — 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 laserlemon/figaro | 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 ≤ 344 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "laserlemon/figaro(\\.git)?\\b" \\
  && ok "origin remote is laserlemon/figaro" \\
  || miss "origin remote is not laserlemon/figaro (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/figaro.rb" \\
  && ok "lib/figaro.rb" \\
  || miss "missing critical file: lib/figaro.rb"
test -f "lib/figaro/application.rb" \\
  && ok "lib/figaro/application.rb" \\
  || miss "missing critical file: lib/figaro/application.rb"
test -f "lib/figaro/rails/railtie.rb" \\
  && ok "lib/figaro/rails/railtie.rb" \\
  || miss "missing critical file: lib/figaro/rails/railtie.rb"
test -f "lib/figaro/cli.rb" \\
  && ok "lib/figaro/cli.rb" \\
  || miss "missing critical file: lib/figaro/cli.rb"
test -f "lib/figaro/env.rb" \\
  && ok "lib/figaro/env.rb" \\
  || miss "missing critical file: lib/figaro/env.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 344 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~314d)"
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/laserlemon/figaro"
  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).

Figaro is a Ruby gem that securely manages Rails application configuration by parsing a Git-ignored YAML file (config/application.yml) and loading its values into ENV variables. It implements the Twelve-Factor App methodology for handling sensitive credentials and environment-specific settings without storing them in version control. Modular gem structure: lib/figaro.rb is the entry point; lib/figaro/application.rb handles YAML parsing and ENV loading; lib/figaro/cli/ contains the install and heroku_set commands; lib/figaro/rails/ provides Rails integration via a Railtie (rails/railtie.rb) and tasks (rails/tasks.rake). Tests mirror this structure under spec/.

Rails developers building multi-environment applications who need simple, secure configuration management for API keys, database URLs, and other secrets. They want a convention-based approach that works seamlessly with Heroku deployments without writing custom config logic.

Production-ready but in maintenance mode. The gem has established widespread adoption (31KB of Ruby code, comprehensive test suite, CI/CD via GitHub Actions for Rails 5.2–8.0), but the maintainer explicitly notes v2 development is stalled and seeking sponsorship. Current main branch is stable, though new feature development has slowed.

Single-maintainer risk is the primary concern—the README openly calls for sponsorship and notes limited time availability. Dependency count is minimal (pure Ruby, no external gems needed for core functionality), reducing supply-chain risk. The v2 branch being stalled means new Rails features may lag behind Rails releases, though current v1 supports through Rails 8.0.

Active maintenance of v1 with Rails 8.0 support added (via gemfiles/rails80.gemfile). No new features visible. The stalled v2 branch suggests architectural refactoring was planned but paused. CI pipeline is green across supported Rails versions.

git clone https://github.com/laserlemon/figaro.git
cd figaro
bundle install
bundle exec rspec

To use in a Rails project: add gem "figaro" to Gemfile, run bundle exec figaro install (creates config/application.yml and adds to .gitignore), then edit the YAML file with your config.

Daily commands: Local development: bundle exec rspec (run full test suite against current Rails). Per-version testing: BUNDLE_GEMFILE=gemfiles/rails80.gemfile bundle exec rspec (test against Rails 8.0). Install into a test Rails app: bundle exec figaro install inside a Rails project root.

• lib/figaro.rb — Main entry point and public API for the gem; exposes configuration loading and ENV access
• lib/figaro/application.rb — Core abstraction for loading YAML configuration files and merging with ENV variables
• lib/figaro/rails/railtie.rb — Rails integration hook that initializes Figaro during Rails boot process
• lib/figaro/cli.rb — CLI command dispatcher for install and heroku-set operations
• lib/figaro/env.rb — Typed environment variable accessor with fallback and type coercion support
• lib/figaro/rails/tasks.rake — Rake tasks for managing configuration; entry point for development workflows
• figaro.gemspec — Gem metadata and dependency declarations; defines supported Rails versions

• Figaro::Application (YAML, Ruby File I/O) — Loads YAML configuration file and merges with ENV variables; maintains in-memory config hash
  • Failure mode: Missing application.yml silently falls back to ENV; malformed YAML raises parsing error
• Figaro::Env (ENV, method_missing) — Provides typed accessors for environment variables with optional type coercion and defaults
  • Failure mode: Missing required variables return nil; invalid type coercions may raise or return default
• Figaro::Rails::Railtie (Rails::Railtie) — Hooks into Rails initialization to load configuration early, before app code runs
  • Failure mode: Configuration load errors crash Rails boot; no graceful degradation
• CLI Command Dispatcher (figaro install / heroku:set) (OptionParser, Heroku CLI subprocess) — Executes developer workflows: generates application.yml template or syncs config to Heroku
  • Failure mode: heroku:set fails if Heroku CLI not installed or user not authenticated

• config/application.yml → Figaro::Application instance — YAML file parsed and stored in @configuration hash during initialization
• Figaro::Application @configuration hash → ENV (system environment) — Merged configuration written to ENV during Rails boot via Railtie
• ENV (system environment) → Figaro::Env accessors — App code reads environment variables via Figaro.env.KEY_NAME syntax
• Local application.yml → Heroku environment variables — figaro heroku:set command parses YAML and calls heroku config:set for each key

Add a new environment variable accessor with type coercion

1. Define a new public method in lib/figaro/env.rb that wraps ENV access with type casting (lib/figaro/env.rb)
2. Add tests in spec/figaro/env_spec.rb covering normal, missing, and invalid type cases (spec/figaro/env_spec.rb)

Add a new configuration file source (e.g., JSON support)

1. Extend lib/figaro/application.rb to add a new file loader method (e.g., load_json) (lib/figaro/application.rb)
2. Parse the new format and merge into @configuration hash following existing YAML merge pattern (lib/figaro/application.rb)
3. Add test cases in spec/figaro/application_spec.rb for the new source (spec/figaro/application_spec.rb)

Add a new CLI command (e.g., for another deployment platform)

1. Create a new task file at lib/figaro/cli/PLATFORM_set.rb inheriting from lib/figaro/cli/task.rb (lib/figaro/cli/task.rb)
2. Register the command in lib/figaro/cli.rb by adding a case branch and method dispatch (lib/figaro/cli.rb)
3. Add Rake task wrapper in lib/figaro/rails/tasks.rake following existing figaro:heroku_set pattern (lib/figaro/rails/tasks.rake)
4. Write command tests in spec/figaro/cli/PLATFORM_set_spec.rb following existing heroku_set_spec.rb structure (spec/figaro/cli/heroku_set_spec.rb)

• YAML configuration files — Human-readable, hierarchical, and version-controllable local configuration; standard Rails convention
• ENV-based runtime overrides — Heroku and cloud-native deployment standard; allows environment-specific secrets without changing code
• Rails Railtie hooks — Ensures configuration loads early in Rails boot lifecycle before application code runs
• Rake tasks and CLI — Provides developer workflow for setup (figaro install) and deployment (figaro heroku:set)

• YAML file committed to version control (but with template/example)

  • Why: Makes local development straightforward without secrets management complexity
  • Consequence: Developers must remember not to commit actual secrets; relies on .gitignore discipline

• ENV variables take precedence over YAML values

  • Why: Allows runtime environment to override defaults without code changes
  • Consequence: Harder to debug when ENV shadows YAML values; requires checking both sources

• Single application.yml file per Rails app (not multi-environment per file)

  • Why: Simpler mental model and fewer file operations
  • Consequence: All environments share one YAML structure; environment-specific secrets must come from ENV

• Does not encrypt secrets at rest in YAML files (relies on .gitignore and ENV for sensitive values)
• Does not provide built-in secret rotation or expiration
• Does not support non-Rails applications (Rails-specific integration via Railtie)
• Does not validate configuration schema or enforce required keys

• Silent fallback on missing YAML file (Medium) — lib/figaro/application.rb: If application.yml does not exist, the gem silently proceeds with only ENV variables; no warning logged. This can hide configuration setup mistakes.
• ENV precedence hides: undefined

YAML file required: Figaro silently succeeds even if config/application.yml doesn't exist—no error is raised, just empty ENV. ERB in YAML: The application.yml file is parsed as ERB, so <%= ENV['VAR'] %> works but can be confusing if unexpected. Heroku integration via CLI: The figaro heroku:set command invokes the heroku CLI directly (mocked in tests via spec/support/bin/heroku)—it will fail silently if the Heroku CLI is not installed. Rails eager loading: Configuration must be loaded early in the boot process; custom initializers added after Figaro's Railtie will not see the values. v1 vs v2 confusion: README mentions v2 is stalled, but no major version bump released—users will clone v1 main and may expect v2 features.

• Twelve-Factor App — Figaro's entire design philosophy is based on the Twelve-Factor App methodology; understanding factor III (Config) explains why ENV variables are preferred over config files.
• Rails Railtie — The core integration point (lib/figaro/rails/railtie.rb) uses Railtie to hook into Rails initialization; understanding Railtie is essential to modifying or extending Figaro's Rails integration.
• ERB (Embedded Ruby) — Figaro parses config/application.yml as ERB before YAML parsing, allowing dynamic config values; not obvious from the code and frequently misunderstood.
• Git .gitignore Patterns — Figaro's security model depends on adding config/application.yml to .gitignore via the install command; understanding gitignore syntax is critical to the security guarantee.
• Environment Variables & ENV Hash — Figaro's entire purpose is to populate Ruby's ENV Hash; understanding ENV semantics (immutability, string-only keys/values, case sensitivity on Unix vs Windows) is foundational.
• YAML Syntax & Parsing — The config/application.yml file is YAML with ERB; misunderstanding YAML indentation, string quoting, or type coercion (e.g., yes as boolean vs string) is a common source of config bugs.
• Convention over Configuration — Figaro embraces Rails' CoC philosophy—the file location, naming, and behavior are all conventional, not configurable, which is why the figaro install command is so simple and why users rarely need to read docs.

• bkeepers/dotenv — Alternative approach to local development config: loads .env files instead of a single YAML, but doesn't integrate as tightly with Rails or Heroku
• thoughtbot/climate_control — Lightweight gem for managing ENV in tests; often used alongside Figaro to mock configuration in specs
• rails/rails — Figaro is a Rails plugin; understanding Rails Railtie and initialization hooks (in railties/) is essential to Figaro's integration layer
• heroku/heroku-cli — Figaro's heroku:set command wraps the Heroku CLI; users often pair Figaro with Heroku deployment workflows
• hashicorp/vault — Enterprise alternative to Figaro for secrets management; understanding when Vault is needed over Figaro helps frame Figaro's design philosophy (simplicity over security depth)

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 integration tests for Rails 8.0+ compatibility

The repo has gemfiles for Rails 5.2 through 8.0, but spec/rails_spec.rb is minimal. With Rails 8.0 introducing significant changes (removal of Sprockets by default, new authentication patterns), there's an opportunity to add integration tests that validate Figaro works correctly across all supported Rails versions, especially newer ones where edge cases may exist.

• [ ] Expand spec/rails_spec.rb with tests for Rails 8.0 specific features
• [ ] Add tests in spec/figaro/rails/ to verify Railtie initialization works across all gemfile versions
• [ ] Test ENV variable loading in Rails console, rake tasks, and runtime contexts
• [ ] Verify lib/figaro/rails/tasks.rake executes correctly in each Rails version

Add error handling and validation tests for malformed YAML configs

The lib/figaro/cli/install/application.yml template exists, but there are no specific tests for what happens when users have invalid YAML, missing required keys, or type mismatches in their config files. This directly impacts the user experience when misconfiguring the gem.

• [ ] Add tests in spec/figaro/application_spec.rb for invalid YAML parsing scenarios
• [ ] Add tests for missing config files vs. optional configs
• [ ] Test lib/figaro/error.rb usage for all error cases
• [ ] Add validation tests for environment-specific config overrides failing gracefully

Add GitHub Actions workflow for testing against multiple Ruby versions

The .github/workflows/test.yml exists but likely tests only one Ruby version. Given Figaro supports Rails 5.2-8.0 (spanning Ruby 2.7-3.3), adding a matrix build in the existing test workflow to test against multiple Ruby versions (2.7, 3.0, 3.1, 3.2, 3.3) would catch version-specific issues early.

• [ ] Modify .github/workflows/test.yml to add a Ruby version matrix strategy
• [ ] Ensure Gemfile and gemfiles/* pin appropriate Ruby versions
• [ ] Test against at least Ruby 2.7 (EOL but supported by Rails 5.2) and 3.3 (latest)
• [ ] Document minimum Ruby version requirement in README.md if not already stated

• Add YAML validation: Create a method in lib/figaro/application.rb that validates required keys are present before loading ENV, with helpful error messages when keys are missing. Tests would go in spec/figaro/application_spec.rb.
• Document ERB support: The README and config/application.yml.example hint at ERB but don't show concrete examples. Add a 'Advanced Configuration' section with ERB interpolation examples and edge cases.
• Test Figaro::Env class more thoroughly: lib/figaro/env.rb exists but spec/figaro/env_spec.rb is minimal. Add tests for accessing undefined config values, type coercion (string-to-integer), and the accessor pattern.
• CI coverage for Ruby 3.2/3.3: The test.yml workflow tests Rails versions but may not pin Ruby versions explicitly. Ensure the workflow matrix includes modern Ruby and document the minimum supported Ruby version in README.

Figaro is a configuration management gem with generally sound design principles (using ENV and YAML files). The main security concerns are: (1) potential YAML deserialization vulnerabilities if unsafe parsing is used, (2) lack of visible input validation in CLI commands that process user arguments, and (3) risk of developers committing secrets to version control despite the tool's intent to prevent this. The codebase shows good test coverage and multi-Rails-version support, indicating maintenance quality. Recommendations focus on implementing safe YAML parsing, input validation, and clearer documentation around secret management best practices.

• High · Potential Hardcoded Secrets in application.yml Template — lib/figaro/cli/install/application.yml. The file lib/figaro/cli/install/application.yml is a template for configuration that may be committed to version control. If developers copy this template and add actual secrets, they risk committing credentials to the repository. Fix: Ensure application.yml is added to .gitignore. Provide clear documentation that application.yml should never be committed. Consider using environment variable validation at runtime to catch missing secrets early.
• Medium · No Input Validation Apparent in CLI Commands — lib/figaro/cli/, lib/figaro/cli/heroku_set.rb, lib/figaro/cli/install.rb. The CLI module (lib/figaro/cli/) handles heroku_set and install operations. Without visible input validation or sanitization, there could be risks when processing user input or environment variable names passed through CLI arguments. Fix: Implement strict input validation for all CLI parameters. Validate environment variable names against allowed character sets (alphanumeric and underscore only). Sanitize any user input before using in system commands.
• Medium · Potential YAML Deserialization Risk — lib/figaro/application.rb, lib/figaro.rb. Figaro reads configuration from YAML files (application.yml). If YAML parsing is not configured safely, it could be vulnerable to YAML deserialization attacks where malicious YAML can execute arbitrary code. Fix: Use YAML.safe_load() instead of YAML.load(). Explicitly pass permitted_classes and permitted_symbols parameters to restrict deserialization to safe types only.
• Medium · Mock Heroku CLI in Tests May Mask Security Issues — spec/support/bin/heroku, spec/support/command_interceptor.rb. The test support file spec/support/bin/heroku is a mock that intercepts heroku commands. This could mask security issues with actual credential handling when using the real Heroku CLI in production. Fix: Ensure integration tests with actual Heroku CLI also perform security audits. Document credential handling procedures. Consider using Heroku's official credentials management when possible.
• Low · Missing Security Headers Documentation — lib/figaro/rails/. No evidence of security header configuration (CSP, X-Frame-Options, etc.) in the visible Rails integration code. Fix: While Figaro's scope is configuration management, document best practices for security headers in the README. Consider providing example secure configurations for common scenarios.
• Low · Development Dependencies May Include Vulnerabilities — Gemfile, gemfiles/. The Gemfile content was not provided. Dependencies should be regularly audited for known vulnerabilities using tools like bundler-audit. Fix: Run 'bundle audit' regularly. Implement dependency scanning in CI/CD pipeline. Keep Rails and other gems updated to latest secure versions as shown by the multiple Rails version gemfiles.

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.