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/mileszs/wicked_pdf 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
• 28+ active contributors
• Distributed ownership (top contributor 48% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 10mo ago

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

What it runs against: a local clone of mileszs/wicked_pdf — 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 mileszs/wicked_pdf | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 319 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mileszs/wicked_pdf(\\.git)?\\b" \\
  && ok "origin remote is mileszs/wicked_pdf" \\
  || miss "origin remote is not mileszs/wicked_pdf (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"

# 4. Critical files exist
test -f "lib/wicked_pdf.rb" \\
  && ok "lib/wicked_pdf.rb" \\
  || miss "missing critical file: lib/wicked_pdf.rb"
test -f "lib/wicked_pdf/binary.rb" \\
  && ok "lib/wicked_pdf/binary.rb" \\
  || miss "missing critical file: lib/wicked_pdf/binary.rb"
test -f "lib/wicked_pdf/option_parser.rb" \\
  && ok "lib/wicked_pdf/option_parser.rb" \\
  || miss "missing critical file: lib/wicked_pdf/option_parser.rb"
test -f "lib/wicked_pdf/pdf_helper.rb" \\
  && ok "lib/wicked_pdf/pdf_helper.rb" \\
  || miss "missing critical file: lib/wicked_pdf/pdf_helper.rb"
test -f "lib/wicked_pdf/railtie.rb" \\
  && ok "lib/wicked_pdf/railtie.rb" \\
  || miss "missing critical file: lib/wicked_pdf/railtie.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 319 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~289d)"
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/mileszs/wicked_pdf"
  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).

Wicked PDF is a Rails plugin that generates PDFs from HTML views by wrapping the wkhtmltopdf command-line binary. Instead of using a PDF generation DSL, developers write standard HTML/CSS views and Wicked PDF converts them to PDF files, handling asset pipeline integration, layout customization, and binary invocation. Gem-based Rails plugin with modular design: lib/wicked_pdf.rb is the main entry point; lib/wicked_pdf/binary.rb handles binary invocation; lib/wicked_pdf/pdf_helper.rb and lib/wicked_pdf/wicked_pdf_helper.rb provide Rails controller/view integration; lib/wicked_pdf/option_parser.rb parses wkhtmltopdf options; lib/wicked_pdf/middleware.rb provides Rack integration.

Rails developers (versions 4–7.0) building applications that need to generate PDFs dynamically (invoices, reports, documents) from existing HTML templates without learning a separate PDF API.

Production-ready and actively maintained. Supports Ruby 2.2–3.2 and Rails 4–7.0; has comprehensive test coverage across unit, functional tests (.github/workflows/ci.yml runs CI); visible Git history and gemfiles for multiple Rails versions indicate long-term support.

External binary dependency risk: the plugin relies entirely on the wkhtmltopdf system binary, which must be installed separately (typically via wkhtmltopdf-binary gem) and can have system-specific issues. Single-maintainer repository increases bus-factor risk; no recent commit timestamp visible in provided data, so currency is unclear.

No specific recent activity visible in provided metadata. Codebase appears stable with support for Rails 7.0 and Ruby 3.2; .github/workflows/ci.yml suggests continuous testing, but commit recency unknown.

git clone https://github.com/mileszs/wicked_pdf.git && cd wicked_pdf && bundle install && bundle exec rake test

Daily commands: In a Rails app: add gem 'wicked_pdf' to Gemfile, run rails generate wicked_pdf, then use respond_to { format.pdf { render pdf: 'filename' } } in a controller. Locally: bundle exec rake test runs the full test suite.

• lib/wicked_pdf.rb — Main entry point and core API for the gem; handles PDF generation orchestration and configuration
• lib/wicked_pdf/binary.rb — Manages wkhtmltopdf binary detection and execution; critical for platform compatibility
• lib/wicked_pdf/option_parser.rb — Parses and validates wkhtmltopdf command-line options; core to configuration handling
• lib/wicked_pdf/pdf_helper.rb — Rails view helper providing render_to_string and render methods for controllers
• lib/wicked_pdf/railtie.rb — Rails engine initialization; registers middleware and integration points with Rails
• lib/wicked_pdf/wicked_pdf_helper.rb — Primary view helper methods (render_to_pdf, render_pdf_page); exposes gem functionality to views
• lib/wicked_pdf/wicked_pdf_helper/assets.rb — Handles asset pipeline integration for CSS and JavaScript inclusion in PDFs

• WickedPdf (lib/wicked_pdf.rb) (Ruby, File I/O, subprocess execution) — Orchestrator for PDF generation; manages option validation, asset parsing, binary invocation, and error handling
  • Failure mode: Raises WickedPdfError if wkhtmltopdf fails, binary missing, or invalid options; returns nil on silent failure mode
• Binary (lib/wicked_pdf/binary.rb) (Ruby Process, Shell execution, PATH resolution) — Locates wkhtmltopdf binary in PATH or custom locations; constructs and executes shell command; captures output/errors
  • Failure mode: Raises when binary not found; propagates wkhtmltopdf stderr as exception; potential shell injection if options not sanitized
• OptionParser (lib/wicked_pdf/option_parser.rb) (Ruby hash mapping, string formatting) — Converts Ruby options hash (e.g., {page_size: 'A4'}) into wkhtmltopdf command-line flags; validates known options
  • Failure mode: Unknown options silently dropped or passed

Add a new wkhtmltopdf command-line option

1. Define the option in lib/wicked_pdf/option_parser.rb by adding a mapping in the LONG_OPTIONS or SHORT_OPTIONS hash (lib/wicked_pdf/option_parser.rb)
2. Test the parsing logic by adding a test case to test/unit/wicked_pdf_option_parser_test.rb (test/unit/wicked_pdf_option_parser_test.rb)
3. Document the option in generators/wicked_pdf/templates/wicked_pdf.rb as a commented example (generators/wicked_pdf/templates/wicked_pdf.rb)
4. Update README.md with usage examples if user-facing (README.md)

Customize PDF rendering for a specific Rails view

1. In your Rails controller action, use render_pdf method from lib/wicked_pdf/pdf_helper.rb with custom options hash (lib/wicked_pdf/pdf_helper.rb)
2. Pass wkhtmltopdf-compatible options (e.g., page_size, margin, etc.) via the options parameter (lib/wicked_pdf/option_parser.rb)
3. For asset inlining needs, the lib/wicked_pdf/wicked_pdf_helper/assets.rb handles automatic CSS/JS inclusion from app/assets (lib/wicked_pdf/wicked_pdf_helper/assets.rb)

Add support for a new binary location detection strategy

1. Modify lib/wicked_pdf/binary.rb to add logic in the find_binary_path method or add a new detection helper (lib/wicked_pdf/binary.rb)
2. Allow the binary path to be overridden via initializer configuration in generators/wicked_pdf/templates/wicked_pdf.rb (generators/wicked_pdf/templates/wicked_pdf.rb)
3. Add unit tests in test/unit/wkhtmltopdf_location_test.rb to verify binary detection works on your platform (test/unit/wkhtmltopdf_location_test.rb)

• wkhtmltopdf (external binary) — Industry-standard open-source tool using WebKit rendering engine; eliminates need for custom PDF DSL by rendering HTML/CSS natively
• Ruby on Rails plugin/gem — Deep Rails integration via Railtie; provides ActionController helpers and view layer abstraction for natural PDF generation from ERB templates
• Rack middleware — Allows request/response interception for transparent PDF rendering without controller changes

• Shell invocation of external wkhtmltopdf binary vs. direct PDF library

  • Why: Simplifies rendering of complex HTML/CSS/JavaScript; avoids reimplementing a rendering engine
  • Consequence: Requires wkhtmltopdf binary on deployment environment; slower than in-process libraries; potential security considerations with shell execution

• Asset inlining (CSS/JS) vs. URL-based asset serving

  • Why: Wkhtmltopdf may not have access to same file paths or asset host as development environment
  • Consequence: Adds complexity to assets.rb; must detect and inline all dependencies; slows PDF generation; risk of asset inlining failures

• Synchronous PDF generation vs. job-based async rendering

  • Why: Simpler API and immediate response for small PDFs; matches Rails conventions for render methods
  • Consequence: Long PDF generation blocks request thread; not suitable for high-volume or very large PDFs; must manage externally for async needs

• Does not handle PDF-specific features like form fields, annotations, or encryption (wkhtmltopdf limitations)
• Does not provide async/background PDF generation out-of-the-box (relies on Rails job queues)
• Does not support non-WebKit rendering engines or alternative PDF generation backends
• Does not manage wkhtmltopdf binary installation (user must provide via system package, bundler, or manual installation)

1. wkhtmltopdf must be installed separately and on PATH; if exe_path is not configured and binary is not found, renders will silently fail or throw 'command not found'. 2) Layouts don't work by default—CSS, JS, and images must use absolute URLs (wicked_pdf_stylesheet_link_tag etc.) or enable_local_file_access must be set. 3) Tempfiles are created during rendering and cleaned up; on Windows or high-concurrency setups, permission/cleanup issues can occur. 4) The binary runs outside Rails context, so Rails methods (helpers, partials) must be rendered to HTML first before PDF conversion. 5) test/fixtures/manifest.js and subdirectory/nested.js suggest the test suite requires asset pipeline setup; Gemfile must match the target Rails version.

• HTML-to-PDF conversion via webkit rendering engine — Wicked PDF's core capability relies on wkhtmltopdf, which uses QtWebKit to render HTML/CSS before converting to PDF; understanding this explains why layouts must be absolute-path URLs and why some CSS features may behave differently than in browsers.
• Rack middleware integration — lib/wicked_pdf/middleware.rb implements Rack middleware to intercept PDF requests; essential for understanding how Wicked PDF integrates with the Rails request/response cycle.
• Rails Railtie and engine pattern — lib/wicked_pdf/railtie.rb uses the Railtie pattern to auto-initialize the gem into Rails; key to understanding how Wicked PDF hooks into Rails boot without explicit require.
• Asset pipeline and absolute URL resolution — lib/wicked_pdf/wicked_pdf_helper/assets.rb must resolve fingerprinted asset paths to absolute file:// URLs because wkhtmltopdf runs outside the Rails app; critical for CSS/JS/image inclusion in PDFs.
• Tempfile management in subprocess handling — lib/wicked_pdf/tempfile.rb and lib/wicked_pdf/binary.rb manage temporary files for HTML input and PDF output; understanding lifecycle prevents resource leaks and concurrency issues.
• Shell command escaping and option parsing — lib/wicked_pdf/option_parser.rb translates Ruby hashes into wkhtmltopdf command-line flags; proper escaping prevents injection attacks and ensures options reach the binary correctly.
• Respond_to and MIME type registration in Rails — Wicked PDF leverages Rails' respond_to(:pdf) block pattern; requires Mime::Type.register 'application/pdf', :pdf or similar in mime_types.rb to function.

• unixmonkey/pdfkit — Alternative Rails PDF gem; also wraps wkhtmltopdf but with a different API and middleware approach.
• prawnpdf/prawn — Pure-Ruby PDF generation library; does not require wkhtmltopdf binary, useful for Ruby-only DSL-driven PDF workflows.
• zakird/wkhtmltopdf_binary_gem — Companion gem that bundles wkhtmltopdf binaries; directly referenced in README as the recommended binary installer for wicked_pdf.
• rails/rails — Rails itself; wicked_pdf is a plugin that integrates with ActionController rendering and the Rails asset pipeline.
• wkhtmltopdf/wkhtmltopdf — The upstream wkhtmltopdf project; the binary that wicked_pdf wraps and depends on for all PDF conversion.

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/wicked_pdf/middleware.rb

The middleware.rb file exists in the lib/wicked_pdf directory but there are no corresponding test files in test/unit or test/functional that specifically test middleware functionality. This is a critical component for request/response handling in Rails, and comprehensive tests would ensure reliability across Rails versions 4-7.0.

• [ ] Create test/unit/wicked_pdf_middleware_test.rb with tests for middleware initialization
• [ ] Add tests for PDF content-type detection and header manipulation
• [ ] Test middleware behavior across different Rails versions using gemfiles/*/gemfile configs
• [ ] Verify integration with Rails request/response cycle

Add integration tests for lib/wicked_pdf/wicked_pdf_helper/assets.rb asset handling

The assets.rb file handles CSS/JS asset inclusion in PDFs (critical for styled output), but test/functional/wicked_pdf_helper_assets_test.rb appears minimal. Asset path resolution differs across Rails versions and deployment environments (sprockets, asset pipeline, webpacker), requiring thorough integration testing.

• [ ] Expand test/functional/wicked_pdf_helper_assets_test.rb with tests for stylesheet_link_tag and javascript_include_tag conversion
• [ ] Add tests for asset fingerprinting across Rails 5.0-7.0 (using gemfiles/ configs)
• [ ] Test subdirectory asset resolution (reference: test/fixtures/subdirectory/)
• [ ] Add tests for CDN-hosted assets and external URLs in PDF context

Add CI workflow tests for wkhtmltopdf binary detection and fallback on multiple platforms

The lib/wicked_pdf/binary.rb handles wkhtmltopdf binary location detection (critical for deployment), and test/unit/wkhtmltopdf_location_test.rb exists but the .github/workflows/ci.yml likely only tests one platform. This needs multi-platform testing (Linux, macOS, Windows) and various installation methods (apt, brew, direct binary).

• [ ] Extend .github/workflows/ci.yml with matrix strategy for ubuntu-latest, macos-latest, and windows-latest
• [ ] Add test jobs that verify binary detection with wkhtmltopdf installed via package manager vs. system PATH
• [ ] Add test for graceful error handling when wkhtmltopdf is missing (from lib/wicked_pdf/binary.rb)
• [ ] Test against both wkhtmltopdf 0.12.x and latest versions

• Add integration tests for the asset pipeline in test/functional/—currently wicked_pdf_helper_assets_test.rb exists but test/fixtures/manifest.js and subdirectory/nested.js are underutilized. Create a test that verifies stylesheets and images resolve correctly in complex Rails app structures.
• Document the common wkhtmltopdf options (headers, footers, page breaks, orientation) with working examples in the README or a new doc/USAGE_EXAMPLES.md, since README snippet is truncated and does not cover real-world use cases.
• Expand lib/wicked_pdf/option_parser.rb test coverage (test/unit/wicked_pdf_option_parser_test.rb)—add test cases for edge cases like nil values, invalid option types, and conflicting options (e.g., both page-size and width specified).

• High · Command Injection via wkhtmltopdf Binary Execution — lib/wicked_pdf/binary.rb, lib/wicked_pdf/option_parser.rb. Wicked PDF executes the external wkhtmltopdf binary with user-supplied input. The lib/wicked_pdf/option_parser.rb and lib/wicked_pdf/binary.rb files process options that could be passed from user input without proper sanitization. If user input is directly incorporated into command-line arguments for wkhtmltopdf, it could lead to command injection attacks. Fix: Implement strict input validation and sanitization for all parameters passed to wkhtmltopdf. Use parameterized execution methods that prevent shell interpretation. Whitelist allowed options and values. Never pass unsanitized user input directly to shell commands.
• High · Path Traversal in File Handling — lib/wicked_pdf/tempfile.rb, lib/wicked_pdf/wicked_pdf_helper/assets.rb. The gem handles file paths for HTML templates and assets (lib/wicked_pdf/wicked_pdf_helper/assets.rb, lib/wicked_pdf/tempfile.rb). Without proper path validation, an attacker could potentially use '../' sequences or absolute paths to access files outside the intended directory, leading to information disclosure or file manipulation. Fix: Implement strict path validation using File.expand_path() and verify that resolved paths remain within expected directories. Use allowlists for accessible directories. Reject paths containing '..' or absolute paths that escape the base directory.
• High · Potential XSS via HTML Content Generation — lib/wicked_pdf/wicked_pdf_helper.rb, lib/wicked_pdf/pdf_helper.rb. Wicked PDF generates PDF output from HTML templates. If user-controlled data is embedded into these templates without proper escaping, it could lead to XSS attacks when the HTML is processed. The lib/wicked_pdf/wicked_pdf_helper.rb may render user input unsafely. Fix: Ensure all user-supplied data is properly HTML-escaped before rendering in templates. Use Rails' built-in escaping helpers (h, sanitize). Never use raw() or html_safe on untrusted input. Implement Content Security Policy headers.
• Medium · Middleware Security Configuration — lib/wicked_pdf/middleware.rb. The lib/wicked_pdf/middleware.rb file implements middleware that could have security implications. Without proper authentication/authorization checks, it may expose PDF generation capabilities to unauthorized users or allow abuse for denial-of-service attacks. Fix: Implement authentication and authorization checks in the middleware. Rate limit PDF generation requests. Validate all input parameters. Log suspicious activities. Consider restricting access by IP or user role.
• Medium · Temporary File Security — lib/wicked_pdf/tempfile.rb. The lib/wicked_pdf/tempfile.rb creates temporary files for PDF generation. Insecure temporary file handling could lead to race conditions, information disclosure, or privilege escalation if temp files are created with overly permissive permissions or in shared temp directories. Fix: Use secure temporary file creation with restrictive permissions (0600). Ensure proper cleanup of temporary files. Use Ruby's Tempfile class with proper directory specifications. Consider using unique, unpredictable filenames.
• Medium · Missing Security Headers Configuration — lib/wicked_pdf/railtie.rb, lib/wicked_pdf/middleware.rb. No evidence of security headers configuration (CSP, X-Frame-Options, X-Content-Type-Options) in the codebase. This could expose the application to clickjacking, MIME-type sniffing, and other header-based attacks. Fix: Configure security headers in the Rails initializer or middleware. Implement Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and other security headers. Use gems like 'secure_headers' for comprehensive header management.
• Low · Dependency Version Management — wicked_pdf.gemspec, Gemfile, gemfiles/. The gemfile structure shows support for multiple Rails versions (4.x through 7.x), but without visible dependency pinning or security update policies, there's potential risk of using outdated or vulnerable dependency versions. Fix: Implement automated dependency scanning using tools like Dependabot. Regularly update dependencies

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.