maquina-generators 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 217f011212f8bd0de1e98fe87fe41afeb48d2171eba4431cb82b219a69239a08
+  data.tar.gz: 927e664fc585adbe4a7d1e3f441a2fa49fb2514fe6ac239e742e240bf913ece3
+SHA512:
+  metadata.gz: 01b0e678645dca5f7a0a080a9b70d463d0d8da194a3f2fe9ad09d77fa6c0bc673863f4ac525000db990d441508560bee5b2ce3858cb68b61d59432d5bbefcdc8
+  data.tar.gz: b6277238ae34b753a3056b6f559ffd5bd4324e8e605568d624a79b1dca6b4a70e54a3c22cce5f4405de1848e837a540f12d6b022d6d2e746d0025d5afa3daba6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mario Alberto Chavez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# Maquina Generators
+
+A collection of Rails generators from the Maquina umbrella. Each generator produces standalone code with no runtime gem dependency -- the gem is only needed at generation time.
+
+## Available Generators
+
+### Clave -- Passwordless Email-Code Authentication
+
+**Clave** (Spanish: "code/key") generates a complete passwordless authentication system using email verification codes.
+
+#### What it generates
+
+- **Models:** `User`, `Session`, `EmailVerification`, `Current`
+- **Controllers:** Sign-in/sign-up flows with email code verification
+- **Views:** Minimal, responsive forms styled with Tailwind CSS
+- **Mailer:** Verification code emails (HTML + text)
+- **Job:** Cleanup job for expired sessions and verifications
+- **Locale files:** English and Spanish translations
+- **Migrations:** 3 migrations (users, sessions, email_verifications)
+- **Test helper:** `sign_in_as(user)` and `sign_out` for integration tests
+
+#### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "maquina_generators", group: :development
+```
+
+Run the generator:
+
+```bash
+rails g maquina:clave
+```
+
+Then:
+
+```bash
+bundle install    # Install bcrypt
+rails db:migrate  # Run migrations
+```
+
+#### Options
+
+```bash
+rails g maquina:clave                        # Full install
+rails g maquina:clave --skip-registration    # Sign-in only (no sign-up)
+rails g maquina:clave --skip-views           # Skip view templates
+```
+
+#### Customization
+
+All generated code lives in your app -- edit it directly:
+
+- **Redirect after login:** Edit `app/controllers/concerns/authentication.rb` (`after_authentication_url`)
+- **Session duration:** Edit `authentication.rb` (default: 30 days)
+- **Code expiration:** Edit controllers (default: 15 minutes)
+- **Cooldown between codes:** Edit `EmailVerification::COOLDOWN_MINUTES` (default: 15)
+- **Colors/styling:** Edit view templates (default: indigo)
+- **Email sender:** Edit `app/mailers/verification_mailer.rb`
+- **Translations:** Edit `config/locales/clave.*.yml`
+
+### Solid Errors -- Error Tracking Dashboard
+
+**Solid Errors** installs the [solid_errors](https://github.com/fractaledmind/solid_errors) gem with HTTP authentication and engine mounting.
+
+#### What it generates
+
+- **BackstageController:** Inherits from `ActionController::Base` (bypasses app's ApplicationController concerns)
+- **Initializer:** Credentials-first auth with ENV variable fallback, database connection config
+- **Route:** Mounts `SolidErrors::Engine` under a configurable prefix
+
+#### Usage
+
+```bash
+rails g maquina:solid_errors --prefix /admin
+```
+
+The generator automatically runs `bundle install` and `solid_errors:install`. After running, execute `bin/rails db:migrate`.
+
+#### Options
+
+```bash
+rails g maquina:solid_errors --prefix /admin                          # Default env vars
+rails g maquina:solid_errors --prefix /backstage \
+  --user-env-var ADMIN_USER --password-env-var ADMIN_PASSWORD         # Custom env vars
+```
+
+#### Authentication
+
+Credentials are resolved in order:
+
+1. `Rails.application.credentials.backstage.username` / `.password`
+2. `ENV["SOLID_ERRORS_USER"]` / `ENV["SOLID_ERRORS_PASSWORD"]` (configurable)
+
+---
+
+### Mission Control Jobs -- Job Queue Dashboard
+
+**Mission Control Jobs** installs the [mission_control-jobs](https://github.com/rails/mission_control-jobs) gem with HTTP authentication and engine mounting.
+
+#### What it generates
+
+- **BackstageController:** Inherits from `ActionController::Base` (bypasses app's ApplicationController concerns)
+- **Initializer:** Sets base controller class, credentials-first auth with ENV variable fallback
+- **Route:** Mounts `MissionControl::Jobs::Engine` under a configurable prefix
+
+#### Usage
+
+```bash
+rails g maquina:mission_control_jobs --prefix /admin
+```
+
+The generator automatically runs `bundle install`.
+
+#### Options
+
+```bash
+rails g maquina:mission_control_jobs --prefix /admin                  # Default env vars
+rails g maquina:mission_control_jobs --prefix /backstage \
+  --user-env-var ADMIN_USER --password-env-var ADMIN_PASSWORD         # Custom env vars
+```
+
+#### Authentication
+
+Credentials are resolved in order:
+
+1. `Rails.application.credentials.backstage.username` / `.password`
+2. `ENV["MISSION_CONTROL_JOBS_USER"]` / `ENV["MISSION_CONTROL_JOBS_PASSWORD"]` (configurable)
+
+---
+
+## Adding New Generators
+
+Create a new folder under `lib/generators/maquina/`:
+
+```
+lib/generators/maquina/your_generator/
+  your_generator_generator.rb
+  USAGE
+  templates/
+    ...
+```
+
+The generator class should be `Maquina::Generators::YourGeneratorGenerator` and it will be available as `rails g maquina:your_generator`.
+
+## Development
+
+```bash
+bundle install
+rake test
+bundle exec standardrb       # Lint
+bundle exec standardrb --fix # Auto-fix
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/generators/maquina/clave/USAGE

@@ -0,0 +1,11 @@
+Description:
+  Generates passwordless email-code authentication (Clave).
+
+  Creates models, controllers, views, mailer, job, locale files, and
+  migrations for a complete passwordless authentication system using
+  email verification codes.
+
+Examples:
+  rails g maquina:clave                        # Full install
+  rails g maquina:clave --skip-registration    # Sign-in only (no sign-up flow)
+  rails g maquina:clave --skip-views           # No view templates (API-only or custom views)

data/lib/generators/maquina/clave/clave_generator.rb

@@ -0,0 +1,184 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module Maquina
+  module Generators
+    class ClaveGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_views, type: :boolean, default: false,
+        desc: "Skip view templates"
+      class_option :skip_registration, type: :boolean, default: false,
+        desc: "Skip sign-up flow"
+
+      def self.next_migration_number(dirname)
+        sleep(1) if @prev_migration_nr == Time.now.utc.strftime("%Y%m%d%H%M%S")
+        @prev_migration_nr = Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      # 1. Models
+      def create_models
+        template "app/models/current.rb.tt", "app/models/current.rb"
+        template "app/models/session.rb.tt", "app/models/session.rb"
+        template "app/models/email_verification.rb.tt", "app/models/email_verification.rb"
+        template "app/models/user.rb.tt", "app/models/user.rb"
+      end
+
+      # 2. Controllers
+      def create_controllers
+        template "app/controllers/concerns/authentication.rb.tt",
+          "app/controllers/concerns/authentication.rb"
+        template "app/controllers/sessions_controller.rb.tt",
+          "app/controllers/sessions_controller.rb"
+        template "app/controllers/session/verifications_controller.rb.tt",
+          "app/controllers/session/verifications_controller.rb"
+        template "app/controllers/session/verification_resends_controller.rb.tt",
+          "app/controllers/session/verification_resends_controller.rb"
+
+        unless options[:skip_registration]
+          template "app/controllers/registrations_controller.rb.tt",
+            "app/controllers/registrations_controller.rb"
+          template "app/controllers/registration/verifications_controller.rb.tt",
+            "app/controllers/registration/verifications_controller.rb"
+          template "app/controllers/registration/verification_resends_controller.rb.tt",
+            "app/controllers/registration/verification_resends_controller.rb"
+        end
+      end
+
+      # 3. Mailer
+      def create_mailer
+        template "app/mailers/verification_mailer.rb.tt",
+          "app/mailers/verification_mailer.rb"
+      end
+
+      # 4. Helper
+      def create_helper
+        template "app/helpers/authentication_helper.rb.tt",
+          "app/helpers/authentication_helper.rb"
+      end
+
+      # 5. Job
+      def create_job
+        template "app/jobs/authentication_cleanup_job.rb.tt",
+          "app/jobs/authentication_cleanup_job.rb"
+      end
+
+      # 6. Views
+      def create_views
+        return if options[:skip_views]
+
+        template "app/views/sessions/new.html.erb.tt",
+          "app/views/sessions/new.html.erb"
+        template "app/views/session/verifications/new.html.erb.tt",
+          "app/views/session/verifications/new.html.erb"
+
+        unless options[:skip_registration]
+          template "app/views/registrations/new.html.erb.tt",
+            "app/views/registrations/new.html.erb"
+          template "app/views/registration/verifications/new.html.erb.tt",
+            "app/views/registration/verifications/new.html.erb"
+        end
+
+        template "app/views/verification_mailer/verification_code.html.erb.tt",
+          "app/views/verification_mailer/verification_code.html.erb"
+        template "app/views/verification_mailer/verification_code.text.erb.tt",
+          "app/views/verification_mailer/verification_code.text.erb"
+      end
+
+      # 7. Locale files
+      def create_locale_files
+        copy_file "config/locales/clave.en.yml", "config/locales/clave.en.yml"
+        copy_file "config/locales/clave.es.yml", "config/locales/clave.es.yml"
+      end
+
+      # 9. Test helper
+      def create_test_helper
+        template "test/test_helpers/session_test_helper.rb.tt",
+          "test/test_helpers/session_test_helper.rb"
+      end
+
+      # 10. Include Authentication in ApplicationController
+      def configure_application_controller
+        sentinel = "class ApplicationController < ActionController::Base\n"
+        inject_into_file "app/controllers/application_controller.rb",
+          "  include Authentication\n",
+          after: sentinel
+      end
+
+      # 11. Routes
+      def add_routes
+        route_content = <<~RUBY
+          # Authentication routes (generated by maquina:clave)
+          resource :session, only: [:new, :create, :destroy] do
+            resource :verification, only: [:new, :create], controller: "session/verifications"
+            resource :verification_resend, only: [:create], controller: "session/verification_resends"
+          end
+        RUBY
+
+        unless options[:skip_registration]
+          route_content += <<~RUBY
+
+            resource :registration, only: [:new, :create] do
+              resource :verification, only: [:new, :create], controller: "registration/verifications"
+              resource :verification_resend, only: [:create], controller: "registration/verification_resends"
+            end
+          RUBY
+        end
+
+        route route_content
+      end
+
+      # 12. Enable bcrypt
+      def enable_bcrypt
+        gemfile_path = File.join(destination_root, "Gemfile")
+        if File.exist?(gemfile_path)
+          content = File.read(gemfile_path)
+          if content.include?('# gem "bcrypt"')
+            gsub_file "Gemfile", '# gem "bcrypt"', 'gem "bcrypt"'
+          elsif !content.include?('gem "bcrypt"')
+            append_to_file "Gemfile", "\ngem \"bcrypt\"\n"
+          end
+        end
+      end
+
+      # 13. Migrations
+      def add_migrations
+        migration_template "migration_create_users.rb.tt",
+          "db/migrate/create_users.rb"
+        migration_template "migration_create_sessions.rb.tt",
+          "db/migrate/create_sessions.rb"
+        migration_template "migration_create_email_verifications.rb.tt",
+          "db/migrate/create_email_verifications.rb"
+      end
+
+      # 14. Post-install message
+      def show_post_install
+        say ""
+        say "Clave authentication has been installed!", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  1. bundle install                    # Install bcrypt"
+        say "  2. rails db:migrate                  # Run migrations"
+        say "  3. rails server                      # Start the app"
+        say "  4. Visit /session/new                # Sign-in page"
+        unless options[:skip_registration]
+          say "  5. Visit /registration/new           # Sign-up page"
+        end
+        say ""
+        say "Optional:", :yellow
+        say "  - Edit app/controllers/concerns/authentication.rb to customize redirect URLs"
+        say "  - Edit config/locales/clave.*.yml to customize messages"
+        say "  - Set up Action Mailer for email delivery (letter_opener for development)"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/maquina/clave/templates/app/controllers/concerns/authentication.rb.tt

@@ -0,0 +1,63 @@
+module Authentication
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :require_authentication
+    helper_method :authenticated?, :session_expires_at
+  end
+
+  class_methods do
+    def allow_unauthenticated_access(**options)
+      skip_before_action :require_authentication, **options
+    end
+  end
+
+  private
+
+  def authenticated?
+    resume_session
+  end
+
+  def require_authentication
+    resume_session || request_authentication
+  end
+
+  def resume_session
+    Current.session ||= find_session_by_cookie
+  end
+
+  def find_session_by_cookie
+    return nil unless cookies.signed[:session_id]
+
+    Session.active.find_by(id: cookies.signed[:session_id])
+  end
+
+  def request_authentication
+    session[:return_to_after_authenticating] = request.url
+    redirect_to new_session_path
+  end
+
+  def after_authentication_url
+    session.delete(:return_to_after_authenticating) || root_url
+  end
+
+  def start_new_session_for(user)
+    user.sessions.create!(
+      user_agent: request.user_agent,
+      ip_address: request.remote_ip,
+      expires_at: 30.days.from_now
+    ).tap do |session|
+      Current.session = session
+      cookies.signed.permanent[:session_id] = {value: session.id, httponly: true, same_site: :lax}
+    end
+  end
+
+  def terminate_session
+    Current.session.destroy
+    cookies.delete(:session_id)
+  end
+
+  def session_expires_at
+    Current.session&.expires_at
+  end
+end

data/lib/generators/maquina/clave/templates/app/controllers/registration/verification_resends_controller.rb.tt

@@ -0,0 +1,38 @@
+class Registration::VerificationResendsController < ApplicationController
+  allow_unauthenticated_access
+  rate_limit to: 5, within: 3.minutes, only: :create, with: -> { redirect_to new_registration_verification_path, alert: t("flash.general.rate_limited") }
+
+  # POST /registration/verification_resend
+  def create
+    old_verification = EmailVerification.find_by(id: session[:pending_verification_id])
+
+    unless old_verification
+      redirect_to new_registration_path
+      return
+    end
+
+    email = old_verification.email
+
+    if EmailVerification.for_email(email).recent.exists?
+      recent = EmailVerification.for_email(email).recent.first
+      redirect_to new_registration_verification_path,
+        alert: t("flash.registrations.cooldown", minutes: recent.minutes_until_resend)
+      return
+    end
+
+    verification = EmailVerification.create!(
+      email: email,
+      code: SecureRandom.hex(3).upcase,
+      verification_type: "signup",
+      locale: old_verification.locale || I18n.locale.to_s,
+      expires_at: 15.minutes.from_now
+    )
+
+    Rails.logger.info "[AUTH] Verification code resent for registration #{email} from #{request.remote_ip}"
+    VerificationMailer.verification_code(verification).deliver_later
+    session[:pending_verification_id] = verification.id
+
+    redirect_to new_registration_verification_path,
+      notice: t("flash.registrations.code_resent")
+  end
+end

data/lib/generators/maquina/clave/templates/app/controllers/registration/verifications_controller.rb.tt

@@ -0,0 +1,51 @@
+class Registration::VerificationsController < ApplicationController
+  allow_unauthenticated_access
+  rate_limit to: 10, within: 3.minutes, only: :create, with: -> { redirect_to new_registration_verification_path, alert: t("flash.general.rate_limited") }
+
+  # GET /registration/verification/new
+  def new
+    @verification = EmailVerification.find_by(id: session[:pending_verification_id])
+    @email = @verification&.email || session[:pending_signup_email]
+    redirect_to new_registration_path unless @email
+  end
+
+  # POST /registration/verification
+  def create
+    @verification = EmailVerification.find_by(id: session[:pending_verification_id])
+    @email = @verification&.email || session[:pending_signup_email]
+
+    unless @verification
+      flash.now[:alert] = t("flash.registrations.invalid_code")
+      render :new, status: :unprocessable_entity
+      return
+    end
+
+    if @verification.expired?
+      flash.now[:alert] = t("flash.registrations.code_expired")
+      render :new, status: :unprocessable_entity
+      return
+    end
+
+    if @verification.code != params[:code]&.upcase&.strip
+      @verification.increment!(:attempts)
+      Rails.logger.warn "[AUTH] Invalid verification code attempt for #{@email} from #{request.remote_ip} (attempt #{@verification.attempts})"
+      flash.now[:alert] = t("flash.registrations.invalid_code")
+      render :new, status: :unprocessable_entity
+      return
+    end
+
+    user = User.create!(
+      email_address: @verification.email,
+      password: User.generate_secure_password,
+      locale: @verification.locale || I18n.default_locale.to_s
+    )
+
+    @verification.mark_verified!
+    session.delete(:pending_verification_id)
+    session.delete(:pending_signup_email)
+
+    Rails.logger.info "[AUTH] Successful registration for #{user.email_address} from #{request.remote_ip}"
+    start_new_session_for(user)
+    redirect_to root_path, notice: t("flash.registrations.create.success")
+  end
+end

data/lib/generators/maquina/clave/templates/app/controllers/registrations_controller.rb.tt

@@ -0,0 +1,63 @@
+class RegistrationsController < ApplicationController
+  allow_unauthenticated_access
+  rate_limit to: 10, within: 3.minutes, only: :create, with: -> { redirect_to new_registration_path, alert: t("flash.general.rate_limited") }
+
+  def new
+  end
+
+  def create
+    email = registration_params[:email_address]&.downcase&.strip
+
+    if email&.include?("+")
+      Rails.logger.warn "[AUTH] Registration attempted with + in email #{email} from #{request.remote_ip}"
+      flash.now[:alert] = t("flash.registrations.email_plus_not_allowed")
+      render :new, status: :unprocessable_entity
+      return
+    end
+
+    existing_user = User.find_by(email_address: email)
+
+    if existing_user
+      if existing_user.blocked?
+        # Fail silently - show same UI but don't send email
+        Rails.logger.info "[AUTH] Registration attempted for blocked user #{email} from #{request.remote_ip}"
+        session[:pending_signup_email] = email
+        redirect_to new_registration_verification_path
+      else
+        Rails.logger.info "[AUTH] Registration attempted for existing email #{email} from #{request.remote_ip}"
+        flash.now[:alert] = t("flash.registrations.email_taken")
+        render :new, status: :unprocessable_entity
+      end
+      return
+    end
+
+    recent_verification = EmailVerification.for_email(email).recent.first
+    if recent_verification
+      session[:pending_verification_id] = recent_verification.id
+      session[:pending_signup_email] = email
+      redirect_to new_registration_verification_path,
+        notice: t("flash.registrations.code_already_sent", minutes: recent_verification.minutes_until_resend)
+      return
+    end
+
+    verification = EmailVerification.create!(
+      email: email,
+      code: SecureRandom.hex(3).upcase,
+      verification_type: "signup",
+      locale: I18n.locale.to_s,
+      expires_at: 15.minutes.from_now
+    )
+
+    Rails.logger.info "[AUTH] Verification code sent for new registration #{email} from #{request.remote_ip}"
+    VerificationMailer.verification_code(verification).deliver_later
+    session[:pending_verification_id] = verification.id
+
+    redirect_to new_registration_verification_path
+  end
+
+  private
+
+  def registration_params
+    params.permit(:email_address)
+  end
+end

data/lib/generators/maquina/clave/templates/app/controllers/session/verification_resends_controller.rb.tt

@@ -0,0 +1,44 @@
+class Session::VerificationResendsController < ApplicationController
+  allow_unauthenticated_access
+  rate_limit to: 5, within: 3.minutes, only: :create, with: -> { redirect_to new_session_verification_path, alert: t("flash.general.rate_limited") }
+
+  # POST /session/verification_resend
+  def create
+    old_verification = EmailVerification.find_by(id: session[:pending_verification_id])
+    email = old_verification&.email || session[:pending_login_email]
+
+    unless email
+      redirect_to new_session_path
+      return
+    end
+
+    if EmailVerification.for_email(email).recent.exists?
+      recent = EmailVerification.for_email(email).recent.first
+      redirect_to new_session_verification_path,
+        alert: t("flash.sessions.cooldown", minutes: recent.minutes_until_resend)
+      return
+    end
+
+    user = User.find_by(email_address: email)
+
+    if user && !user.blocked?
+      verification = EmailVerification.create!(
+        email: email,
+        code: SecureRandom.hex(3).upcase,
+        verification_type: "login",
+        locale: user.locale || I18n.default_locale.to_s,
+        expires_at: 15.minutes.from_now
+      )
+
+      Rails.logger.info "[AUTH] Verification code resent for login #{email} from #{request.remote_ip}"
+      VerificationMailer.verification_code(verification).deliver_later
+      session[:pending_verification_id] = verification.id
+    else
+      Rails.logger.info "[AUTH] Verification resend attempted for non-existent/blocked email #{email} from #{request.remote_ip}"
+    end
+
+    # Always show success (don't reveal if user exists)
+    redirect_to new_session_verification_path,
+      notice: t("flash.sessions.code_resent")
+  end
+end