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/heartcombo/simple_form 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 5w ago
• 18 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 heartcombo/simple_form repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/heartcombo/simple_form.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "heartcombo/simple_form(\\.git)?\\b" \\
  && ok "origin remote is heartcombo/simple_form" \\
  || miss "origin remote is not heartcombo/simple_form (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/simple_form.rb" \\
  && ok "lib/simple_form.rb" \\
  || miss "missing critical file: lib/simple_form.rb"
test -f "lib/simple_form/form_builder.rb" \\
  && ok "lib/simple_form/form_builder.rb" \\
  || miss "missing critical file: lib/simple_form/form_builder.rb"
test -f "lib/simple_form/inputs/base.rb" \\
  && ok "lib/simple_form/inputs/base.rb" \\
  || miss "missing critical file: lib/simple_form/inputs/base.rb"
test -f "lib/simple_form/wrappers/builder.rb" \\
  && ok "lib/simple_form/wrappers/builder.rb" \\
  || miss "missing critical file: lib/simple_form/wrappers/builder.rb"
test -f "lib/simple_form/map_type.rb" \\
  && ok "lib/simple_form/map_type.rb" \\
  || miss "missing critical file: lib/simple_form/map_type.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 68 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~38d)"
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/heartcombo/simple_form"
  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).

Simple Form is a Rails form builder gem that generates semantic form markup with minimal configuration, providing a flexible DSL for creating forms without imposing layout opinions. It wraps Rails' form helpers (text_field, select, checkbox, etc.) into a unified simple_form_for syntax and auto-generates wrapper divs, labels, error messages, and hints based on model attributes and ActiveRecord schema inspection. Modular architecture: lib/simple_form.rb is the entry point, lib/simple_form/form_builder.rb contains the core FormBuilder class, lib/simple_form/components/ holds ~8 reusable component classes (errors.rb, hints.rb, labels.rb, etc.), lib/simple_form/action_view_extensions/ patches Rails FormBuilder, and lib/generators/simple_form/ provides rails generate simple_form:install with templates for Bootstrap/Foundation/custom configs.

Rails developers building CRUD applications who want to reduce form boilerplate while maintaining full control over HTML structure and CSS framework integration (Bootstrap, Foundation). They need forms that work with ActiveRecord models without writing repetitive wrapper markup.

Highly mature and production-ready. The project has 8.2K+ GitHub stars, supports Rails 7.0–8.0 via gemfiles/, includes comprehensive CI (GitHub Actions in .github/workflows/test.yml), and maintains backward compatibility through a detailed CHANGELOG.md. Active maintenance with v5.0 as the current stable release.

Low risk overall. Single primary maintainer (heartcombo org) is mitigated by stable API and extensive test suite. No obvious high-risk dependencies listed in visible structure. Main risk: tight coupling to Rails versions—breaking changes in ActionView require gem updates. Minor risk: large gemfiles/ matrix (Rails 7.0–8.0, main) suggests ongoing version churn.

Repository is actively maintained with multi-version Rails support. The gemfiles/ directory shows ongoing testing against Rails 7.0, 7.1, 7.2, 8.0, and main (Rails development). CI workflow in .github/workflows/test.yml suggests regular test runs. CHANGELOG.md indicates recent features and bug fixes, though specific recent PR/commit activity cannot be determined from file list alone.

git clone https://github.com/heartcombo/simple_form.git
cd simple_form
bundle install
bin/test

Daily commands: This is a library, not an app. To test locally: bin/test (from file list). To use in a Rails app: add gem 'simple_form' to Gemfile, run bundle install, then rails generate simple_form:install (with optional --bootstrap flag).

• lib/simple_form.rb — Entry point that initializes the gem, loads all components, inputs, and wrappers—every contributor must understand how the gem bootstraps.
• lib/simple_form/form_builder.rb — Core FormBuilder class that extends Rails ActionView::FormBuilder with Simple Form DSL; the primary API surface for all form rendering.
• lib/simple_form/inputs/base.rb — Abstract base class for all input types; defines the interface and common logic that every input implementation inherits from.
• lib/simple_form/wrappers/builder.rb — Wrapper configuration engine that orchestrates how form components (labels, hints, errors) are rendered and nested; critical to layout flexibility.
• lib/simple_form/map_type.rb — Type mapping system that routes model attributes to the correct input class (e.g., :string → StringInput); foundational for input resolution.
• lib/generators/simple_form/install_generator.rb — Generator that sets up initial configuration and locale files; the user's first touch-point for customizing Simple Form behavior.
• lib/simple_form/components.rb — Component registry and loader that imports and manages all component modules (errors, hints, labels, html5 attributes); orchestrates component composition.

Add a new Input Type

1. Create a new input class inheriting from Base in lib/simple_form/inputs/ (lib/simple_form/inputs/your_input.rb)
2. Register the input in lib/simple_form/inputs.rb by adding it to the autoload (lib/simple_form/inputs.rb)
3. Add a mapping rule in lib/simple_form/map_type.rb if it should auto-detect for certain column types (lib/simple_form/map_type.rb)
4. Write tests in test/inputs/ to verify rendering and options (test/inputs/your_input_test.rb)

Add a new Component (e.g., validation styling)

1. Create a new component module in lib/simple_form/components/ (lib/simple_form/components/your_component.rb)
2. Register in lib/simple_form/components.rb so it's mixed into all inputs (lib/simple_form/components.rb)
3. Optionally add configuration in the install generator template (lib/generators/simple_form/templates/config/initializers/simple_form.rb)
4. Test integration in test/components/custom_components_test.rb (test/components/custom_components_test.rb)

Customize wrapper layout (Bootstrap, Foundation, etc.)

1. Run bundle exec rails generate simple_form:install --bootstrap (or equivalent) (lib/generators/simple_form/install_generator.rb)
2. Edit the generated config/initializers/simple_form.rb to define wrapper structure (lib/generators/simple_form/templates/config/initializers/simple_form.rb)
3. Wrappers are built by lib/simple_form/wrappers/builder.rb from your config (lib/simple_form/wrappers/builder.rb)

Extend FormBuilder with custom form methods

1. Monkey-patch SimpleForm::FormBuilder in an initializer or concern (lib/simple_form/form_builder.rb)
2. Or subclass FormBuilder and wire it in your Rails app via form_with builder: MyCustomBuilder (lib/simple_form/action_view_extensions/form_helper.rb)
3. Test in test/form_builder/general_test.rb or custom test file (test/form_builder/general_test.rb)

• Rails FormBuilder extension — Leverages existing Rails form infrastructure; minimal learning curve for Rails developers; integrates seamlessly with ActiveRecord and Action View
• Module composition (mixins) for components — Allows flexible, non-hierarchical composition of concerns (labels, hints, errors) into input classes without deep inheritance chains
• Wrapper configuration system — Decouples input rendering from markup structure; enables users to swap CSS frameworks (Bootstrap, Foundation) without code changes
• ActiveRecord introspection (column types, validators) — Enables intelligent input type inference; reduces boilerplate by automatically selecting correct input based on schema and validations

• No built-in styling; markup is left to user/wrapper config
  • Why: Provides maximum flexibility and framework-agnostic positioning
  • Consequence: Users must configure wrap

No required environment variables or external services. Key gotchas: (1) Wrappers API is opaque—the wrapper configuration in simple_form.rb initializer uses a custom DSL (b.use :html5, etc.) that is not documented in code comments; (2) Component ordering matters—components must be registered in the correct sequence in components.rb or rendering order breaks; (3) Form builder inheritance can conflict with other gems that patch FormBuilder (e.g., cocoon, nested_form); (4) I18n keys are deeply nested (simple_form.labels.user.name) and custom inputs must follow naming convention or labels won't auto-populate.

• FormBuilder Pattern — Simple Form IS a FormBuilder subclass; you must understand how Rails' FormBuilder compiles form fields into HTML to extend or debug Simple Form
• Wrappers API (Custom DSL) — Simple Form's killer feature—defines wrapper div structure, CSS classes, error/hint rendering via a domain-specific language in the initializer; this is non-standard Rails and requires reading the template config to understand
• Schema Inspection for Input Type Inference — Simple Form inspects ActiveRecord column types (string, integer, datetime, boolean) to auto-select input types (text_field, number_field, datetime_select); this is undocumented magic you'll encounter in form_builder.rb
• I18n Nested Key Convention — Labels, hints, error messages use Rails I18n with deeply nested keys (simple_form.labels.model.attribute); this convention is baked into components and must be followed for custom inputs
• Component Registry Pattern — Simple Form uses a registry (lib/simple_form/components.rb) to load and order components dynamically; adding custom components requires understanding this registration mechanism
• Monkey-Patching FormBuilder — lib/simple_form/action_view_extensions/ patches Rails' FormBuilder methods; this is a powerful but risky pattern that can conflict with other gems—understanding when and why Simple Form patches is critical
• Collection Rendering (Select/Radio/Checkbox) — Simple Form has special handling for :collection option to render multiple choices; this is more complex than single inputs and has dedicated helpers (collection_radio_buttons, collection_check_boxes)

• rails/rails — Simple Form wraps and extends Rails' form_with and FormBuilder; understanding ActionView::Helpers::FormBuilder is essential
• heartcombo/devise — Often used together in Rails auth workflows; both are maintained by Heartcombo and integrate seamlessly
• formtastic/formtastic — Predecessor to Simple Form; README acknowledges inheritance from Formtastic's DSL—useful for context on design decisions
• plataformatec/responders — Companion gem by Heartcombo for Rails responders; users often combine with Simple Form for full CRUD scaffolding
• twbs/bootstrap — Simple Form provides official Bootstrap 5 wrapper templates; Bootstrap knowledge required to use --bootstrap install option

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 HTML5 input components (color_input, numeric_input, date_time_input)

The lib/simple_form/inputs/ directory contains specialized input types (color_input.rb, numeric_input.rb, date_time_input.rb) but the file structure doesn't show corresponding test files for these. Adding unit tests for HTML5 input handling, validation attributes, and browser compatibility would improve reliability and help new contributors understand expected behavior.

• [ ] Create test/inputs/color_input_test.rb with tests for color picker rendering and value handling
• [ ] Create test/inputs/numeric_input_test.rb with tests for min/max attributes and step validation
• [ ] Create test/inputs/date_time_input_test.rb with tests for datetime formatting across Rails versions
• [ ] Verify tests pass against all supported Rails versions (7.0, 7.1, 7.2, 8.0) using existing Gemfile matrix

Add CI workflow for testing against Rails main branch with deprecation warnings

The repo has gemfiles/Gemfile-rails-main but the .github/workflows/test.yml workflow is not shown in the file structure. Adding or enhancing the CI to explicitly fail on Rails deprecation warnings would catch breaking changes earlier and help maintain forward compatibility as Rails evolves.

• [ ] Review .github/workflows/test.yml to check if Rails main is already tested
• [ ] Add a separate workflow job that runs tests with RUBYOPT='-W:deprecated' against Gemfile-rails-main
• [ ] Configure the job to fail if any deprecation warnings are emitted
• [ ] Document findings in CONTRIBUTING.md about deprecation handling

Extract and document component composition logic with examples in lib/simple_form/components/

The components directory (errors.rb, hints.rb, labels.rb, etc.) implements the DSL composition system, but there's no architectural guide for how components integrate or how to add new ones. Creating a COMPONENTS.md guide with examples would lower the barrier for contributors wanting to extend or customize components.

• [ ] Create docs/COMPONENTS.md documenting the component architecture and load order
• [ ] Add code examples showing how components like lib/simple_form/components/errors.rb and lib/simple_form/components/label_input.rb interact
• [ ] Document the component registration pattern in lib/simple_form/components.rb
• [ ] Add a 'Creating Custom Components' section with a worked example using an existing component as template

• Add tests for lib/simple_form/components/maxlength.rb, minlength.rb, min_max.rb, pattern.rb, readonly.rb—these are HTML5 attribute injectors but have no corresponding test files visible in lib/simple_form/components/
• Document the wrappers API with inline examples in lib/generators/simple_form/templates/config/initializers/simple_form.rb—the DSL (b.use :html5, b.wrapper :input, etc.) is used but never explained in code
• Add missing Slim template for form scaffold in lib/generators/simple_form/templates/ (_form.html.slim exists but should be verified for Bootstrap/Foundation variants like _form.html.haml does)

Simple Form is a well-established Rails form builder gem with moderate security posture. Primary concerns are XSS prevention in dynamic HTML generation and proper sanitization of user-supplied attributes. The library appears to follow Rails conventions but lacks explicit security hardening in the visible codebase. No hardcoded credentials or obvious SQL injection vectors detected in the file structure. Recommend implementing comprehensive input validation, attribute sanitization, and adding security-focused static analysis to the CI/CD pipeline. The project uses GitHub code scanning which is positive, but specific security tests for form-related vulnerabilities should be enhanced.

• High · Potential XSS Vulnerability in Form Rendering — lib/simple_form/components/*, lib/simple_form/inputs/*. Simple Form is a Rails form builder that generates HTML dynamically. Files like lib/simple_form/components/.rb and lib/simple_form/inputs/.rb process user input and generate form elements. Without explicit output escaping verification, there's risk of XSS attacks when rendering user-supplied attribute values, labels, hints, or error messages. Fix: Verify that all user-supplied data is properly escaped using Rails' h() helper or equivalent. Ensure ERB templates use <%= %> (escaped) instead of <%== %> (unescaped) for untrusted content. Add static analysis tests for XSS prevention.
• Medium · Dependency Supply Chain Risk — Gemfile, Gemfile.lock, gemfiles/*. No Gemfile.lock content was provided for analysis. This makes it impossible to verify if pinned dependency versions exist and whether any known vulnerabilities exist in transitive dependencies. Rails form builders like Simple Form depend on multiple gems that could have security issues. Fix: Maintain a Gemfile.lock with pinned versions. Regularly run 'bundle audit' or 'bundler-audit' to check for known vulnerabilities. Implement automated dependency scanning in CI/CD pipeline (already visible in .github/code-scanning.yml).
• Medium · HTML Attribute Injection Risk — lib/simple_form/action_view_extensions/builder.rb, lib/simple_form/form_builder.rb, lib/simple_form/inputs/base.rb. The form builder processes custom HTML attributes and options. If malicious attributes are passed through form options (e.g., onclick, data attributes with script content), they could execute unintended JavaScript without proper sanitization. Fix: Implement attribute whitelist validation. Sanitize user-provided HTML attributes using Rails' sanitize_attributes or similar mechanisms. Document which attributes are safe to accept from user input.
• Medium · Insufficient Input Validation in Collection Inputs — lib/simple_form/inputs/collection_select_input.rb, lib/simple_form/inputs/collection_radio_buttons_input.rb, lib/simple_form/inputs/collection_check_boxes_input.rb, lib/simple_form/inputs/grouped_collection_select_input.rb. Collection-based inputs (collection_select, collection_radio_buttons, collection_check_boxes) process dynamic collections. If the collection source is user-controlled without proper validation, it could lead to injection attacks or unauthorized data exposure. Fix: Validate collection sources and ensure they come from trusted data. Implement authorization checks before rendering collections. Use ActiveRecord scopes or pre-filtered collections rather than raw user input.
• Low · Missing CSRF Protection Documentation — README.md, lib/generators/simple_form/templates/_form.html.*. While Rails provides built-in CSRF protection, the Simple Form documentation should explicitly guide users on CSRF token inclusion. Misconfiguration by developers using Simple Form could result in CSRF vulnerabilities. Fix: Ensure all form templates generated by the installer include CSRF token protection (Rails' form_with/form_for automatically includes this). Add explicit security guidance in README and template comments.
• Low · Missing Security Headers Configuration — lib/generators/simple_form/templates/config/initializers/. No evidence of Content Security Policy (CSP) configuration or security headers guidance in the visible file structure. While Simple Form is a library, it should provide secure defaults and guidance. Fix: Consider adding optional security configuration templates. Provide documentation on implementing CSP for applications using Simple Form to prevent XSS and injection attacks.

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.