Railwyrm 🐉

Railwyrm is a Ruby CLI that bootstraps Rails apps with an opinionated default stack and an interactive feature wizard.

Project page: docs/index.html (Tailwind CSS / GitHub Pages-ready)

Product Focus

• Deterministic Rails app generation
• Interactive wizard for auth/features
• Reproducible defaults for local development

See VISION.md for broader product direction.

Default Stack

Every generated app includes:

• PostgreSQL (rails new --database=postgresql)
• Tailwind CSS (rails new --css=tailwind + ./bin/rails tailwindcss:install)
• RSpec (gem "rspec-rails" + bin/rails generate rspec:install)
• Dotenv (gem "dotenv-rails" in development/test)
• Ruby LSP (gem "ruby-lsp", require: false in development)
• Brakeman (gem "brakeman", require: false in development/test)
• RuboCop (gem "rubocop" + gem "rubocop-rails" in development/test)
• Bullet (gem "bullet" in development + auto-configured in config/environments/development.rb)
• GitHub Actions CI (.github/workflows/ci.yml running RSpec, RuboCop, and Brakeman)
• Devise (gem "devise" + install + user generation by default)
• Active Storage (bin/rails active_storage:install)
• ActionText (bin/rails action_text:install)

Rails compatibility behavior:

• Railwyrm pins generated apps to Ruby 3.3.0 by writing .ruby-version and ruby "3.3.0" in the generated Gemfile.
• Because generated apps target Ruby 3.3.0, Railwyrm pins Rails to ~> 8.0.3 before bundle install.

Wizard Features

During railwyrm new, the wizard can configure:

• Devise user generation (on/off)
• Devise optional modules:
  • confirmable
  • lockable
  • timeoutable
  • trackable
  • magic_link (via devise-passwordless)
  • passkeys (via devise-webauthn)

Magic-link behavior:

• Installs devise-passwordless
• Adds passwordless sign-in routes and UI
• Enables Devise.paranoid = true
• Auto-enables trackable
• Configures development mail delivery to file output at tmp/mails
• Installs a plain-text magic-link template for copy/paste-friendly URLs in development

Passkeys behavior:

• Installs devise-webauthn
• Runs bin/rails generate devise:webauthn:install --force
• Adds :passkey_authenticatable to the Devise model
• Configures config/initializers/webauthn.rb defaults for rp_name (generated app name), rp_id, and localhost origins
• Populates .env.example with WEBAUTHN_RP_NAME, WEBAUTHN_RP_ID, and WEBAUTHN_ALLOWED_ORIGINS
• Ensures WebAuthn JavaScript is loaded as an ES module
• Adds passkey sign-in button on Devise sign-in page
• Redirects first sign-in users (without passkeys) to passkey enrollment
• Runs migrations for the generated WebAuthn tables

Passkeys production checklist:

1. Run the app under HTTPS in production.
2. Set WEBAUTHN_RP_ID to your real domain (for example app.example.com).
3. Set WEBAUTHN_ALLOWED_ORIGINS to your exact HTTPS origin list (for example https://app.example.com).

Passkeys smoke test checklist (generated app):

1. Sign in with email/password and verify you are redirected to the passkey enrollment page on first sign-in.
2. Create a passkey and confirm the page no longer forces enrollment on next sign-in.
3. Sign out and use "Sign in with passkey" from the sign-in page to confirm passwordless passkey authentication works.

CI behavior:

• Generates .github/workflows/ci.yml by default for new apps
• Provides railwyrm feature install ci --app /path/to/app for existing apps
• Workflow runs database prep, RSpec, RuboCop, and Brakeman on push/pull_request
• Generator normalizes default Bullet/Devise config formatting to keep RuboCop green in fresh apps

Quality feature behavior:

• Provides railwyrm feature install quality --app /path/to/app for existing apps
• Automatically installs dependency ci (workflow setup) when missing
• Ensures brakeman, rubocop, rubocop-rails, and bullet gems are present
• Injects Bullet development config (Bullet.enable, alerts, and Rails logger hooks)

Quick Start

cd /path/to/railwyrm
bundle install
bundle exec ruby exe/railwyrm new

Non-interactive example:

bundle exec ruby exe/railwyrm new my_app --interactive=false --path /tmp --devise_magic_link

Install features into an existing app:

bundle exec ruby exe/railwyrm feature list
bundle exec ruby exe/railwyrm feature status --app /path/to/existing_app
bundle exec ruby exe/railwyrm feature sync --app /path/to/existing_app
bundle exec ruby exe/railwyrm feature install magic_link --app /path/to/existing_app
bundle exec ruby exe/railwyrm feature install ci --app /path/to/existing_app
bundle exec ruby exe/railwyrm feature install quality --app /path/to/existing_app

Feature state tracking:

• Railwyrm records installed features in .railwyrm/features.yml inside each generated app.
• feature install uses tracked state plus app detection to skip already-installed features safely.
• feature status shows installed, tracked_only, and detected_only feature sets for diagnostics.
• feature sync rebuilds .railwyrm/features.yml from detected app state.

CLI Commands

bundle exec ruby exe/railwyrm new [APP_NAME]
bundle exec ruby exe/railwyrm feature list
bundle exec ruby exe/railwyrm feature status --app /path/to/app
bundle exec ruby exe/railwyrm feature sync --app /path/to/app
bundle exec ruby exe/railwyrm feature install FEATURE [FEATURE ...] --app /path/to/app
bundle exec ruby exe/railwyrm serve
bundle exec ruby exe/railwyrm doctor
bundle exec ruby exe/railwyrm version

Common flags:

• --no-banner hide mascot/banner
• --verbose stream command output
• --dry_run print commands without executing
• --skip_devise_user skip Devise model generation
• --devise_confirmable enable Devise confirmable
• --devise_lockable enable Devise lockable
• --devise_timeoutable enable Devise timeoutable
• --devise_trackable enable Devise trackable
• --devise_magic_link enable magic-link sign-in
• --devise_passkeys enable passkeys sign-in (WebAuthn)

Feature install options:

• --app path to the existing Rails app
• --devise_user_model Devise model name (default User)
• --dry_run show commands without executing
• --verbose stream command output

Installable features:

• confirmable
• lockable
• timeoutable
• trackable
• magic_link (automatically installs trackable)
• passkeys
• ci
• quality (automatically installs ci)

Development

Run tests:

bundle exec rspec

Project Layout

• exe/railwyrm CLI entrypoint
• lib/railwyrm/cli.rb Thor commands
• lib/railwyrm/generator.rb generation workflow
• lib/railwyrm/rails_blueprint.rb stack defaults and setup commands
• lib/railwyrm/templates/devise/{passkeys,passwordless} magic-link and passkey auth templates
• AGENTS.md Codex repo instructions