create-rails-app 0.1.0 → 0.2.0

data/lib/create_rails_app/compatibility/matrix.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  module Compatibility
+    # Static lookup table mapping Rails version ranges to the +rails new+
+    # options each range supports.
+    #
+    # This is the single source of truth for what each Rails version
+    # can do. The wizard, validator, and builder all consult it.
+    #
+    # @example Look up the entry for a specific Rails version
+    #   entry = Matrix.for('8.0.1')
+    #   entry.supports_option?(:kamal)  #=> true
+    class Matrix
+      # A single row in the compatibility table.
+      #
+      # @!attribute [r] requirement
+      #   @return [Gem::Requirement] Rails version range this entry covers
+      # @!attribute [r] supported_options
+      #   @return [Hash{Symbol => Array<String>, nil}] option keys to allowed
+      #     values (+nil+ means any boolean/skip value is accepted)
+      Entry = Struct.new(:requirement, :supported_options) do
+        # @param rails_version [Gem::Version] version to test
+        # @return [Boolean]
+        def match?(rails_version)
+          requirement.satisfied_by?(rails_version)
+        end
+
+        # @param option_key [Symbol, String]
+        # @return [Boolean]
+        def supports_option?(option_key)
+          supported_options.key?(option_key.to_sym)
+        end
+
+        # @param option_key [Symbol, String]
+        # @return [Array<String>, nil] allowed values, or nil for skips/flags
+        def allowed_values(option_key)
+          supported_options[option_key.to_sym]
+        end
+      end
+
+      # Supported Rails series for version detection and installation.
+      #
+      # @return [Array<String>]
+      SUPPORTED_SERIES = %w[7.2 8.0 8.1].freeze
+
+      # Options shared across all supported Rails versions.
+      # Enum values are derived from Catalog to prevent drift.
+      COMMON_OPTIONS = {
+        api: nil,
+        database: Options::Catalog::BASE_DATABASE_VALUES,
+        javascript: Options::Catalog::DEFINITIONS[:javascript][:values],
+        css: Options::Catalog::DEFINITIONS[:css][:values],
+        asset_pipeline: Options::Catalog::DEFINITIONS[:asset_pipeline][:values],
+        active_record: nil,
+        action_mailer: nil,
+        action_mailbox: nil,
+        action_text: nil,
+        active_job: nil,
+        active_storage: nil,
+        action_cable: nil,
+        hotwire: nil,
+        jbuilder: nil,
+        test: nil,
+        system_test: nil,
+        brakeman: nil,
+        rubocop: nil,
+        ci: nil,
+        docker: nil,
+        devcontainer: nil,
+        bootsnap: nil,
+        dev_gems: nil,
+        keeps: nil,
+        decrypted_diffs: nil,
+        git: nil,
+        bundle: nil
+      }.freeze
+
+      # Options added or changed in Rails 8.0+.
+      RAILS_8_OPTIONS = {
+        kamal: nil,
+        thruster: nil,
+        solid: nil,
+        database: Options::Catalog::DEFINITIONS[:database][:values],
+        asset_pipeline: nil
+      }.freeze
+
+      # Options added in Rails 8.1+.
+      RAILS_81_OPTIONS = {
+        bundler_audit: nil
+      }.freeze
+
+      # @return [Array<Entry>] all known Rails compatibility entries
+      TABLE = [
+        Entry.new(
+          requirement: Gem::Requirement.new('~> 7.2.0'),
+          supported_options: COMMON_OPTIONS.dup.freeze
+        ),
+        Entry.new(
+          requirement: Gem::Requirement.new('~> 8.0.0'),
+          supported_options: COMMON_OPTIONS.merge(RAILS_8_OPTIONS).freeze
+        ),
+        Entry.new(
+          requirement: Gem::Requirement.new('~> 8.1.0'),
+          supported_options: COMMON_OPTIONS.merge(RAILS_8_OPTIONS).merge(RAILS_81_OPTIONS).freeze
+        )
+      ].freeze
+
+      # Returns human-readable version range strings for all entries.
+      #
+      # @return [Array<String>]
+      def self.supported_ranges
+        TABLE.map { |entry| entry.requirement.requirements.map(&:join).join(', ') }
+      end
+
+      # Finds the compatibility entry for the given Rails version.
+      #
+      # @param rails_version [Gem::Version, String] the Rails version
+      # @return [Entry]
+      # @raise [UnsupportedRailsVersionError] if no entry matches
+      def self.for(rails_version)
+        version = Gem::Version.new(rails_version.to_s)
+        entry = TABLE.find { |candidate| candidate.match?(version) }
+        return entry if entry
+
+        message = "Unsupported Rails version: #{version}. "
+        message += "Supported ranges: #{supported_ranges.join(' | ')}"
+        raise UnsupportedRailsVersionError, message
+      end
+    end
+  end
+end

data/lib/create_rails_app/config/store.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+require 'yaml'
+
+module CreateRailsApp
+  module Config
+    # YAML persistence for presets and last-used options.
+    #
+    # Stores configuration at +~/.config/create-rails-app/config.yml+ (or
+    # +$XDG_CONFIG_HOME/create-rails-app/config.yml+). Writes are atomic
+    # via +Tempfile+ + rename.
+    class Store
+      # @return [Integer] current config file schema version
+      SCHEMA_VERSION = 1
+
+      # @param path [String, nil] override the default config file path
+      def initialize(path: nil)
+        @path = path || default_path
+      end
+
+      # @return [String] absolute path to the config file
+      attr_reader :path
+
+      # Returns the last-used option hash (empty hash if none saved).
+      #
+      # @return [Hash{String => Object}]
+      def last_used
+        data.fetch('last_used')
+      end
+
+      # Persists the given options as last-used.
+      #
+      # @param options [Hash{Symbol => Object}]
+      # @return [void]
+      def save_last_used(options)
+        payload = data
+        payload['last_used'] = stringify_keys(options)
+        write(payload)
+      end
+
+      # Returns a preset by name, or +nil+ if it does not exist.
+      #
+      # @param name [String]
+      # @return [Hash{String => Object}, nil]
+      def preset(name)
+        data.fetch('presets').fetch(name.to_s, nil)
+      end
+
+      # Returns all preset names sorted alphabetically.
+      #
+      # @return [Array<String>]
+      def preset_names
+        data.fetch('presets').keys.sort
+      end
+
+      # Saves a named preset.
+      #
+      # @param name [String]
+      # @param options [Hash{Symbol => Object}]
+      # @return [void]
+      def save_preset(name, options)
+        payload = data
+        payload.fetch('presets')[name.to_s] = stringify_keys(options)
+        write(payload)
+      end
+
+      # Deletes a named preset (no-op if it does not exist).
+      #
+      # @param name [String]
+      # @return [void]
+      def delete_preset(name)
+        payload = data
+        payload.fetch('presets').delete(name.to_s)
+        write(payload)
+      end
+
+      private
+
+      # @return [Hash{String => Object}]
+      def data
+        raw = load
+        {
+          'version' => raw.fetch('version', SCHEMA_VERSION),
+          'last_used' => (raw['last_used'].is_a?(Hash) ? raw['last_used'] : {}),
+          'presets' => (raw['presets'].is_a?(Hash) ? raw['presets'] : {})
+        }
+      end
+
+      # @return [Hash]
+      # @raise [ConfigError] if YAML is malformed
+      def load
+        return {} unless File.file?(path)
+
+        result = YAML.safe_load_file(path, aliases: false)
+        unless result.nil? || result.is_a?(Hash)
+          raise ConfigError, "Invalid config file at #{path}: expected a YAML mapping"
+        end
+
+        version = result&.fetch('version', SCHEMA_VERSION) || SCHEMA_VERSION
+        unless version.is_a?(Integer)
+          raise ConfigError, "Invalid config version at #{path}: expected integer, got #{version.inspect}"
+        end
+
+        if version > SCHEMA_VERSION
+          raise ConfigError,
+                "Config file at #{path} has unsupported version #{version} (expected #{SCHEMA_VERSION}). " \
+                'Please upgrade create-rails-app or delete the config file.'
+        end
+
+        result || {}
+      rescue Psych::SyntaxError, Psych::DisallowedClass => e
+        raise ConfigError, "Invalid config file at #{path}: #{e.message}"
+      end
+
+      # @param payload [Hash]
+      # @return [void]
+      def write(payload)
+        FileUtils.mkdir_p(File.dirname(path))
+        tmp = Tempfile.create(['create-rails-app', '.yml'], File.dirname(path))
+        tmp.write(YAML.dump(payload))
+        tmp.close
+        File.rename(tmp.path, path)
+      rescue SystemCallError => e
+        begin
+          File.unlink(tmp.path) if tmp&.path && File.exist?(tmp.path)
+        rescue SystemCallError # :nocov:
+          nil
+        end
+        raise ConfigError, "Failed to write config to #{path}: #{e.message}"
+      end
+
+      # @return [String]
+      def default_path
+        config_home = ENV.fetch('XDG_CONFIG_HOME', File.join(Dir.home, '.config'))
+        File.join(config_home, 'create-rails-app', 'config.yml')
+      rescue ArgumentError
+        raise ConfigError, 'Cannot determine home directory. Set HOME or XDG_CONFIG_HOME.'
+      end
+
+      # @param hash [Hash{Symbol => Object}]
+      # @return [Hash{String => Object}]
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/create_rails_app/detection/rails_versions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'timeout'
+
+module CreateRailsApp
+  module Detection
+    # Detects locally installed Rails versions using +gem list+.
+    #
+    # Groups installed versions by supported series (7.2, 8.0, 8.1)
+    # and returns the latest patch version for each installed series.
+    class RailsVersions
+      # @return [Regexp] pattern to extract version strings from gem list output
+      VERSION_PATTERN = /\d+\.\d+\.\d+(?:\.\w+)?/
+
+      # @param gem_command [String] path or name of the gem executable
+      def initialize(gem_command: 'gem')
+        @gem_command = gem_command
+      end
+
+      # Detects installed Rails versions grouped by supported series.
+      #
+      # @return [Hash{String => String}] series => latest patch version
+      #   e.g. { "8.0" => "8.0.7", "8.1" => "8.1.2" }
+      def detect
+        versions = installed_versions
+        group_by_series(versions)
+      end
+
+      private
+
+      # @return [Array<Gem::Version>] all installed Rails versions, sorted descending
+      def installed_versions
+        output, status = Timeout.timeout(10) do
+          if defined?(Bundler)
+            Bundler.with_unbundled_env do
+              Open3.capture2e(@gem_command, 'list', 'rails', '--local', '--exact')
+            end
+          else
+            Open3.capture2e(@gem_command, 'list', 'rails', '--local', '--exact')
+          end
+        end
+        return [] unless status.success?
+
+        rails_line = output.lines.find { |line| line.match?(/\Arails\s/) }
+        return [] unless rails_line
+
+        versions = rails_line.scan(VERSION_PATTERN).map { |v| Gem::Version.new(v) }
+        versions.sort.reverse
+      rescue SystemCallError, Timeout::Error
+        []
+      end
+
+      # @param versions [Array<Gem::Version>]
+      # @return [Hash{String => String}]
+      def group_by_series(versions)
+        result = {}
+        Compatibility::Matrix::SUPPORTED_SERIES.each do |series|
+          requirement = Gem::Requirement.new("~> #{series}.0")
+          match = versions.find { |v| requirement.satisfied_by?(v) }
+          result[series] = match.to_s if match
+        end
+        result
+      end
+    end
+  end
+end

data/lib/create_rails_app/detection/runtime.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  module Detection
+    # Holds detected Ruby and RubyGems versions.
+    #
+    # @!attribute [r] ruby
+    #   @return [Gem::Version]
+    # @!attribute [r] rubygems
+    #   @return [Gem::Version]
+    RuntimeInfo = Struct.new(:ruby, :rubygems)
+
+    # Detects the current Ruby and RubyGems versions.
+    class Runtime
+      # @return [RuntimeInfo]
+      def detect
+        RuntimeInfo.new(
+          ruby: Gem::Version.new(RUBY_VERSION),
+          rubygems: Gem::Version.new(Gem::VERSION)
+        )
+      end
+    end
+  end
+end

data/lib/create_rails_app/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  # Base error for all create-rails-app failures.
+  class Error < StandardError; end
+
+  # Raised when the config file is corrupt or unreadable.
+  class ConfigError < Error; end
+
+  # Raised when CLI flags or option values are invalid.
+  class ValidationError < Error; end
+
+  # Raised when no supported Rails version can be found or installed.
+  class UnsupportedRailsVersionError < Error; end
+end

data/lib/create_rails_app/options/catalog.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  module Options
+    # Registry of every +rails new+ option create-rails-app knows about.
+    #
+    # Each entry in {DEFINITIONS} describes the option's type and CLI flags.
+    # {ORDER} controls the sequence in which the wizard presents options.
+    #
+    # @see Options::Validator
+    # @see Wizard
+    module Catalog
+      # Option definitions keyed by symbolic name.
+      #
+      # Types:
+      # - +:flag+  — opt-in; emits +--flag+ when true, nothing when false
+      # - +:enum+  — emits +--flag=value+; +:none+ flag emits +--skip-flag+
+      # - +:skip+  — opt-out; emits nothing when true (include), +--skip-X+ when false (exclude)
+      #
+      # @return [Hash{Symbol => Hash}]
+      # Database adapters shared across all Rails versions.
+      BASE_DATABASE_VALUES = %w[sqlite3 postgresql mysql trilogy].freeze
+
+      # Database adapters added in Rails 8.0+.
+      MARIADB_DATABASE_VALUES = %w[mariadb-mysql mariadb-trilogy].freeze
+
+      DEFINITIONS = {
+        # Flags (opt-in)
+        api: { type: :flag, on: '--api' }.freeze,
+        # Enums
+        database: { type: :enum, flag: '--database',
+                    values: (BASE_DATABASE_VALUES + MARIADB_DATABASE_VALUES).freeze }.freeze,
+        javascript: { type: :enum, flag: '--javascript', none: '--skip-javascript',
+                      values: %w[importmap bun webpack esbuild rollup].freeze }.freeze,
+        css: { type: :enum, flag: '--css', none: true,
+               values: %w[tailwind bootstrap bulma postcss sass].freeze,
+               rails_default: 'none' }.freeze,
+        asset_pipeline: { type: :enum, flag: '--asset-pipeline', none: '--skip-asset-pipeline',
+                          values: %w[propshaft sprockets].freeze, rails_default: 'sprockets' }.freeze,
+        # Skip (included by default, --skip-X to exclude)
+        active_record: { type: :skip, skip_flag: '--skip-active-record' }.freeze,
+        action_mailer: { type: :skip, skip_flag: '--skip-action-mailer' }.freeze,
+        action_mailbox: { type: :skip, skip_flag: '--skip-action-mailbox' }.freeze,
+        action_text: { type: :skip, skip_flag: '--skip-action-text' }.freeze,
+        active_job: { type: :skip, skip_flag: '--skip-active-job' }.freeze,
+        active_storage: { type: :skip, skip_flag: '--skip-active-storage' }.freeze,
+        action_cable: { type: :skip, skip_flag: '--skip-action-cable' }.freeze,
+        hotwire: { type: :skip, skip_flag: '--skip-hotwire' }.freeze,
+        jbuilder: { type: :skip, skip_flag: '--skip-jbuilder' }.freeze,
+        test: { type: :skip, skip_flag: '--skip-test' }.freeze,
+        system_test: { type: :skip, skip_flag: '--skip-system-test' }.freeze,
+        brakeman: { type: :skip, skip_flag: '--skip-brakeman' }.freeze,
+        bundler_audit: { type: :skip, skip_flag: '--skip-bundler-audit' }.freeze,
+        rubocop: { type: :skip, skip_flag: '--skip-rubocop' }.freeze,
+        ci: { type: :skip, skip_flag: '--skip-ci' }.freeze,
+        docker: { type: :skip, skip_flag: '--skip-docker' }.freeze,
+        kamal: { type: :skip, skip_flag: '--skip-kamal' }.freeze,
+        thruster: { type: :skip, skip_flag: '--skip-thruster' }.freeze,
+        solid: { type: :skip, skip_flag: '--skip-solid' }.freeze,
+        devcontainer: { type: :flag, on: '--devcontainer' }.freeze,
+        bootsnap: { type: :skip, skip_flag: '--skip-bootsnap' }.freeze,
+        dev_gems: { type: :skip, skip_flag: '--skip-dev-gems' }.freeze,
+        keeps: { type: :skip, skip_flag: '--skip-keeps' }.freeze,
+        decrypted_diffs: { type: :skip, skip_flag: '--skip-decrypted-diffs' }.freeze,
+        git: { type: :skip, skip_flag: '--skip-git' }.freeze,
+        bundle: { type: :skip, skip_flag: '--skip-bundle' }.freeze
+      }.freeze
+
+      # Wizard step order — matches the sequence users see.
+      #
+      # Phase 1: Core architecture (flags + enums + active_record)
+      # Phase 2: Skip options with auto-skip consequences + dependents
+      # Phase 3: Independent skips + devcontainer flag
+      #
+      # @return [Array<Symbol>]
+      ORDER = %i[
+        api
+        active_record
+        database
+        javascript
+        css
+        asset_pipeline
+        test
+        system_test
+        hotwire
+        jbuilder
+        action_mailbox
+        action_text
+        active_storage
+        devcontainer
+        action_mailer
+        active_job
+        action_cable
+        brakeman
+        bundler_audit
+        rubocop
+        ci
+        docker
+        kamal
+        thruster
+        solid
+        bootsnap
+        dev_gems
+        keeps
+        decrypted_diffs
+        git
+        bundle
+      ].freeze
+
+      # Fetches the definition for a given option key.
+      #
+      # @param key [Symbol, String]
+      # @return [Hash] the option definition
+      # @raise [KeyError] if the key is unknown
+      def self.fetch(key)
+        DEFINITIONS.fetch(key.to_sym)
+      end
+    end
+  end
+end

data/lib/create_rails_app/options/validator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  module Options
+    # Validates user-selected options against the compatibility entry
+    # for the detected Rails version.
+    #
+    # Checks that: the app name is valid, every option key is known,
+    # every option is supported by this Rails version, and every
+    # value is valid for the option's type and allowed values.
+    class Validator
+      # @return [Regexp] pattern for valid Rails app names
+      APP_NAME_PATTERN = /\A[a-zA-Z][a-zA-Z0-9_-]*\z/
+
+      # @param compatibility_entry [Compatibility::Matrix::Entry]
+      def initialize(compatibility_entry)
+        @compatibility_entry = compatibility_entry
+      end
+
+      # Validates the app name and all options.
+      #
+      # @param app_name [String]
+      # @param options [Hash{Symbol => Object}]
+      # @return [true]
+      # @raise [ValidationError] if any validation fails
+      def validate!(app_name:, options:) # rubocop:disable Naming/PredicateMethod
+        validate_app_name!(app_name)
+
+        options.each do |key, value|
+          validate_option_key!(key)
+          validate_supported_option!(key)
+          validate_value!(key, value)
+          validate_supported_value!(key, value)
+        end
+
+        true
+      end
+
+      private
+
+      # @param app_name [String]
+      # @raise [ValidationError]
+      # @return [void]
+      def validate_app_name!(app_name)
+        return if app_name.is_a?(String) && app_name.match?(APP_NAME_PATTERN)
+
+        raise ValidationError, "Invalid app name: #{app_name.inspect}"
+      end
+
+      # @param key [Symbol]
+      # @raise [ValidationError]
+      # @return [void]
+      def validate_option_key!(key)
+        return if Catalog::DEFINITIONS.key?(key.to_sym)
+
+        raise ValidationError, "Unknown option: #{key}"
+      end
+
+      # @param key [Symbol]
+      # @raise [ValidationError]
+      # @return [void]
+      def validate_supported_option!(key)
+        return if @compatibility_entry.supports_option?(key)
+
+        raise ValidationError, "Option #{key} is not supported by this Rails version"
+      end
+
+      # @param key [Symbol]
+      # @param value [Object]
+      # @raise [ValidationError]
+      # @return [void]
+      def validate_value!(key, value)
+        definition = Catalog.fetch(key)
+        case definition[:type]
+        when :skip, :flag
+          return if value.nil? || value == true || value == false
+        when :enum
+          return if value.nil? || definition[:values].include?(value)
+          return if definition.key?(:none) && [true, false].include?(value)
+        end
+
+        raise ValidationError, "Invalid value for #{key}: #{value.inspect}"
+      end
+
+      # @param key [Symbol]
+      # @param value [Object]
+      # @raise [ValidationError]
+      # @return [void]
+      def validate_supported_value!(key, value)
+        return if value.nil? || value == true || value == false
+
+        supported_values = @compatibility_entry.allowed_values(key)
+        return if supported_values&.include?(value)
+
+        raise ValidationError, "Value #{value.inspect} for #{key} is not supported by this Rails version"
+      end
+    end
+  end
+end

data/lib/create_rails_app/runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'cli/kit'
+require 'shellwords'
+
+module CreateRailsApp
+  # Executes commands via the shell.
+  #
+  # Supports +--dry-run+ mode, which prints commands instead of running them.
+  # Can run multiple commands in sequence (e.g. gem install + rails new).
+  #
+  # @example
+  #   Runner.new.run!(['rails', '_8.1.2_', 'new', 'myapp', '--api'])
+  class Runner
+    # @param out [IO] output stream for dry-run printing
+    # @param system_runner [#call, nil] callable that executes a shell command
+    def initialize(out: $stdout, system_runner: nil)
+      @out = out
+      @system_runner = system_runner || ->(*command) { ::CLI::Kit::System.system(*command) }
+    end
+
+    # Executes the command or prints it in dry-run mode.
+    #
+    # @param command [Array<String>] the command to execute
+    # @param dry_run [Boolean] when true, prints instead of executing
+    # @return [true] on success
+    # @raise [Error] if the command exits with a non-zero status
+    def run!(command, dry_run: false)
+      if dry_run
+        @out.puts(command.shelljoin)
+        return true
+      end
+
+      status = if defined?(Bundler)
+                 Bundler.with_unbundled_env { @system_runner.call(*command) }
+               else
+                 @system_runner.call(*command)
+               end
+      return true if status.respond_to?(:success?) && status.success?
+
+      code = status.respond_to?(:exitstatus) ? status.exitstatus : nil
+      message = 'Command failed'
+      message += " (exit #{code})" if code
+      message += ": #{command.shelljoin}"
+      raise Error, message
+    end
+  end
+end