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/ryanb/letter_opener 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 2w ago
• 22+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 60% 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 ryanb/letter_opener repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ryanb/letter_opener.

What it runs against: a local clone of ryanb/letter_opener — 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 ryanb/letter_opener | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ryanb/letter_opener(\\.git)?\\b" \\
  && ok "origin remote is ryanb/letter_opener" \\
  || miss "origin remote is not ryanb/letter_opener (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

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

Letter Opener is a Rails gem that intercepts ActionMailer emails during development and displays them in the browser instead of sending them. It stores rendered mail as HTML files in tmp/letter_opener and uses the Launchy library to automatically open them in your default browser, eliminating the need to configure SMTP or risk sending test emails to real addresses. Simple single-gem structure: lib/letter_opener.rb is the entry point; lib/letter_opener/delivery_method.rb implements the ActionMailer delivery hook; lib/letter_opener/message.rb handles email parsing and HTML generation; lib/letter_opener/templates/ contains two ERB templates (:default with styling and :light minimal) for email rendering; lib/letter_opener/railtie.rb handles Rails integration.

Rails developers building applications in development environments who need to preview and debug email functionality without setting up mail servers or risking accidental production emails. Also useful for non-Rails projects using the Mail or Pony gems that want the same email preview capability.

Production-ready and stable. The repo shows a mature gem with comprehensive test coverage (specs in spec/letter_opener/), working CI pipeline (.github/workflows/ruby.yml), and clear documentation. However, the last commit recency and open issue count are not visible in the provided data — you should check GitHub directly to assess current maintenance tempo.

Low risk. The gem has a narrow, focused responsibility (email interception and preview), no heavy external dependencies beyond Launchy and Rails/Mail, and a simple codebase (~29KB Ruby). Risk factors: single maintainer (ryanb) and dependency on Launchy for browser launching. If Launchy breaks, this gem's auto-open feature fails, though the HTML files still generate.

No specific recent changes visible in provided data. Check the GitHub Actions workflow (.github/workflows/ruby.yml) status and CHANGELOG.md for recent activity, but based on the file list, this appears to be a stable, maintenance-mode project rather than actively feature-developing.

git clone https://github.com/ryanb/letter_opener.git
cd letter_opener
bundle install
bundle exec rspec

Daily commands:

bundle exec rspec  # Run test suite
bundle exec rake  # Run default tasks (check Rakefile for available tasks)

To integrate into a Rails app: add gem 'letter_opener', group: :development to Gemfile, run bundle install, then set config.action_mailer.delivery_method = :letter_opener in config/environments/development.rb.

• lib/letter_opener/delivery_method.rb: Core delivery hook that intercepts ActionMailer calls and saves emails to disk; the primary integration point for the gem
• lib/letter_opener/message.rb: Handles email parsing, metadata extraction, and HTML template rendering for each message
• lib/letter_opener/railtie.rb: Rails-specific integration that registers the delivery method and loads configuration in Rails initializers
• lib/letter_opener/configuration.rb: Defines user-facing config options (location, message_template, file_uri_scheme) that customize gem behavior
• lib/letter_opener/templates/default.html.erb: Primary template for styled email preview with metadata display; what users see by default in the browser
• spec/letter_opener/delivery_method_spec.rb: Tests the core email interception and file-writing logic; critical for regression prevention

Adding configuration options: edit lib/letter_opener/configuration.rb and update lib/letter_opener/railtie.rb to expose them. Changing email rendering: modify lib/letter_opener/templates/default.html.erb or lib/letter_opener/templates/light.html.erb. Changing email capture logic: edit lib/letter_opener/delivery_method.rb (the deliver! method). Adding tests: add test files following the pattern in spec/letter_opener/*_spec.rb.

Launchy dependency: the gem silently fails to open browsers if Launchy breaks or can't detect your system browser; emails still save but don't auto-open. WSL gotcha: Windows Subsystem for Linux users must set config.file_uri_scheme manually (example: 'file://///wsl$/Ubuntu-18.04') or file:// URIs won't work. perform_deliveries flag: setting config.action_mailer.perform_deliveries = false will skip email generation entirely, defeating the gem. Filename collisions: emails are stored with timestamp-based filenames; extremely high-volume mail generation in tests could theoretically cause collisions. Rails-specific coupling: the Railtie expects Rails to be loaded; non-Rails setups must directly instantiate LetterOpener::DeliveryMethod.

• ActionMailer Delivery Methods — Letter Opener works by implementing Rails' ActionMailer::DeliveryMethod interface; understanding this pattern is key to modifying how emails are captured and processed
• Rails Railtie — The gem uses Railtie to hook into Rails initialization and register itself as a delivery method; you'll see this pattern in lib/letter_opener/railtie.rb and need to understand it to extend Rails behavior
• MIME multipart email structure — Letter Opener must parse complex multipart emails (text/plain + text/html + attachments); the Message class decodes this structure, and understanding MIME is key to debugging email rendering issues
• ERB templating — Rendered emails are generated using ERB templates (default.html.erb, light.html.erb); modifying email appearance or creating custom templates requires ERB knowledge
• File URI scheme — The gem generates file:// URIs to open HTML emails in browsers; understanding URL encoding and cross-platform file URI differences (especially WSL) is important for the file_uri_scheme config option
• Browser launching via system commands — Launchy detects the OS and launches the default browser; the gem delegates this but you should understand that cross-platform browser launching is non-trivial and failure points exist here

• mailhog/MailHog — Alternative email testing tool that runs a standalone SMTP server and web UI; more heavyweight but works across multiple services/languages unlike Letter Opener which is Rails-specific
• rails/rails — The underlying ActionMailer framework that Letter Opener hooks into; understanding ActionMailer::DeliveryMethod is essential to comprehending how this gem integrates
• mikel/mail — The Mail gem that Letter Opener uses internally to parse and render email messages; source of email parsing logic and MIME handling
• copiousfreetime/launchy — The Launchy gem dependency that Letter Opener uses to automatically open rendered emails in the user's default browser across different OSes
• thoughtbot/mailcatcher — Similar development-time email tool that intercepts SMTP and provides a web UI; predecessor/spiritual relative to Letter Opener with different architectural approach (separate server vs in-process)

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 test coverage for lib/letter_opener/configuration.rb

The configuration.rb file is referenced in the file structure but has no corresponding spec file in spec/letter_opener/. This module likely handles the gem's configuration options (evidenced by the LAUNCHY_APPLICATION mention in the README). Adding tests would ensure configuration behavior is validated and prevent regressions when new configuration options are added.

• [ ] Create spec/letter_opener/configuration_spec.rb
• [ ] Add tests for default configuration values
• [ ] Add tests for configuration override behavior
• [ ] Test LAUNCHY_APPLICATION environment variable handling
• [ ] Run existing test suite to ensure no conflicts

Add tests for lib/letter_opener/railtie.rb

The railtie file integrates letter_opener with Rails but has no corresponding test. This is critical because the railtie handles Rails initialization hooks and would benefit from tests verifying proper rake task registration (see lib/letter_opener/tasks/letter_opener.rake) and delivery method setup.

• [ ] Create spec/letter_opener/railtie_spec.rb
• [ ] Add tests for Rails integration hooks
• [ ] Test that the delivery method is properly registered
• [ ] Test rake task accessibility within Rails environment
• [ ] Verify proper behavior in both development and test environments

Add GitHub Actions workflow for testing against multiple Ruby/Rails versions

The .github/workflows/ruby.yml exists but the README doesn't document it. The gem should be tested against multiple Ruby and Rails versions to ensure compatibility. This PR would add a comprehensive matrix build to .github/workflows/ruby.yml covering supported versions, improving confidence for contributors and maintainers.

• [ ] Review existing .github/workflows/ruby.yml
• [ ] Add Ruby version matrix (e.g., 2.7, 3.0, 3.1, 3.2, 3.3)
• [ ] Add Rails version matrix (e.g., 6.0, 6.1, 7.0, 7.1)
• [ ] Configure matrix to test relevant combinations only
• [ ] Update README with CI badge explanation and supported versions

• Add test coverage for Message class edge cases: spec/letter_opener/message_spec.rb exists but the Message class handles complex email parsing (attachments, plain-text vs HTML, headers) — add tests for multipart emails, missing Subject headers, and non-ASCII characters to improve robustness
• Document the template system and add examples for custom templates: README mentions :default and :light templates and config.message_template but doesn't show how users can create their own custom templates — add an example custom template in docs or create a new feature for user-provided template paths
• Add a Rake task to clean up old emails from tmp/letter_opener: lib/letter_opener/tasks/letter_opener.rake exists but likely only has basic tasks — add a rake letter_opener:cleanup task that deletes emails older than N days to help keep tmp/ directories tidy during development

Letter Opener has moderate security concerns primarily around command injection risks via environment variables, potential XSS vulnerabilities in template rendering, and insecure file storage practices. The tool is designed for development use only, but lacks enforcement mechanisms and has user-controllable code execution paths. The main risks would be mitigated in proper development environment setups, but the lack of input validation and secure defaults creates attack surfaces. Critical review of template files and environment variable handling is recommended.

• High · Arbitrary Command Execution via LAUNCHY_APPLICATION — lib/letter_opener/delivery_method.rb, README.md. The gem uses the LAUNCHY_APPLICATION environment variable to determine which application opens generated emails. An attacker who can control this environment variable could execute arbitrary commands. The README explicitly mentions overriding this environment variable, making it a user-configurable attack surface. Fix: Implement strict validation and whitelisting of allowed applications. Avoid directly passing user-controlled environment variables to shell execution. Use a safe list of approved browsers/applications only.
• High · Potential XSS via Email Content Rendering — lib/letter_opener/templates/default.html.erb, lib/letter_opener/templates/light.html.erb. The gem renders email content in browser templates (lib/letter_opener/templates/). If email content is not properly escaped, malicious HTML/JavaScript in email bodies could execute in the browser context. Rails templates may auto-escape but this depends on template syntax. Fix: Ensure all email content is properly HTML-escaped before rendering. Use Rails safe HTML helpers (html_safe only for trusted content). Review template files to verify proper escaping of <%= %> vs <%raw%> syntax.
• Medium · Insecure File Storage in tmp Directory — README.md, lib/letter_opener (email storage implementation). The gem stores generated emails in tmp/letter_opener as mentioned in the README. The tmp directory may have permissive file permissions, potentially exposing sensitive email content to other users on shared systems. Fix: Store emails in a secure directory with restricted permissions (0700). Implement automatic cleanup of old emails. Document security implications for shared hosting environments.
• Medium · Missing Input Validation in Message Handling — lib/letter_opener/message.rb. The Message class (lib/letter_opener/message.rb) may not properly validate or sanitize email headers and content. Malformed or specially crafted emails could cause unexpected behavior or information disclosure. Fix: Implement strict validation of email structure and headers. Sanitize all incoming email data. Add error handling for malformed emails.
• Low · Development-Only Gem Security Consideration — letter_opener.gemspec, lib/letter_opener.rb. While the gem is intended for development only, there is no strict enforcement preventing it from being used in production. If accidentally enabled in production, it would expose all sent emails in the file system. Fix: Add runtime checks to prevent usage in production environments. Implement warnings in configuration if detected in non-development Rails environments. Document in README that this is development-only.

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.