create-rails-app 0.1.0 → 0.2.0

data/lib/create_rails_app/ui/palette.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  module UI
+    # Color constants for terminal output.
+    #
+    # Maps semantic roles (e.g. +:summary_label+, +:arg_name+) to ANSI 256-color
+    # codes or +cli-ui+ basic color names, depending on terminal capabilities.
+    class Palette
+      # ANSI reset sequence.
+      RESET = "\e[0m"
+
+      # Role-to-color mappings for 256-color terminals.
+      #
+      # @return [Hash{Symbol => Integer}]
+      ROLE_COLORS_256 = {
+        control_back: 45,
+        control_exit: 203,
+        summary_label: 213,
+        runtime_name: 111,
+        runtime_value: 190,
+        command_base: 39,
+        command_app: 82,
+        arg_name: 117,
+        arg_eq: 250,
+        arg_value: 214,
+        install_cmd: 178,
+        exit_message: 82
+      }.freeze
+
+      # Role-to-color mappings for basic (8/16-color) terminals.
+      #
+      # @return [Hash{Symbol => String}]
+      ROLE_COLORS_BASIC = {
+        control_back: 'cyan',
+        control_exit: 'red',
+        summary_label: 'magenta',
+        runtime_name: 'blue',
+        runtime_value: 'green',
+        command_base: 'blue',
+        command_app: 'green',
+        arg_name: 'blue',
+        arg_eq: 'white',
+        arg_value: 'yellow',
+        install_cmd: 'yellow',
+        exit_message: 'green'
+      }.freeze
+
+      # @param env [Hash] environment variables (defaults to +ENV+)
+      def initialize(env: ENV)
+        @env = env
+      end
+
+      # Wraps text in the appropriate ANSI color for the given role.
+      #
+      # @param role [Symbol] a key from {ROLE_COLORS_256}/{ROLE_COLORS_BASIC}
+      # @param text [String] the text to colorize
+      # @return [String]
+      def color(role, text)
+        if no_color?
+          ROLE_COLORS_256.fetch(role) # validate role key exists
+          text
+        elsif supports_256_colors?
+          "\e[38;5;#{ROLE_COLORS_256.fetch(role)}m#{text}#{RESET}"
+        else
+          "{{#{ROLE_COLORS_BASIC.fetch(role)}:#{text}}}"
+        end
+      end
+
+      private
+
+      # @return [Boolean]
+      def no_color?
+        @env.key?('NO_COLOR') || @env['TERM'] == 'dumb'
+      end
+
+      # @return [Boolean]
+      def supports_256_colors?
+        return false if no_color?
+
+        term = @env.fetch('TERM', '')
+        colorterm = @env.fetch('COLORTERM', '')
+        term.include?('256color') || colorterm.match?(/truecolor|24bit/i)
+      end
+    end
+  end
+end

data/lib/create_rails_app/ui/prompter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'cli/ui'
+
+module CreateRailsApp
+  module UI
+    # Raised when the user presses Ctrl+B during a prompt.
+    class BackKeyPressed < StandardError; end
+
+    # Thin wrapper around +cli-ui+ for all user interaction.
+    #
+    # Every prompt the wizard issues goes through this class, making it
+    # easy to inject a test double.
+    class Prompter
+      CTRL_B = "\u0002"
+
+      module ReadCharPatch
+        def read_char
+          char = super
+          raise BackKeyPressed if char == CTRL_B
+
+          char
+        end
+      end
+
+      # Enables the +cli-ui+ stdout router and applies the Ctrl+B patch.
+      #
+      # Call once before creating a Prompter instance. Idempotent.
+      #
+      # @return [void]
+      def self.setup!
+        ::CLI::UI::StdoutRouter.enable
+
+        unless ::CLI::UI::Prompt.respond_to?(:read_char)
+          raise Error, 'CLI::UI::Prompt does not respond to read_char; back-navigation patch cannot be applied'
+        end
+
+        singleton = ::CLI::UI::Prompt.singleton_class
+        return if singleton.ancestors.include?(ReadCharPatch)
+
+        singleton.prepend(ReadCharPatch)
+      end
+
+      # @param out [IO] output stream
+      def initialize(out: $stdout)
+        @out = out
+      end
+
+      # Opens a visual frame with a title.
+      #
+      # @param title [String]
+      # @yield block executed inside the frame
+      # @return [void]
+      def frame(title, &)
+        ::CLI::UI::Frame.open(title, &)
+      end
+
+      # Presents a single-choice list.
+      #
+      # @param question [String]
+      # @param options [Array<String>]
+      # @param default [String, nil]
+      # @return [String] selected option, or {Wizard::BACK} on Ctrl+B
+      def choose(question, options:, default: nil)
+        ::CLI::UI.ask(question, options: options, default: default, filter_ui: false)
+      rescue BackKeyPressed
+        Wizard::BACK
+      end
+
+      # Prompts for free-text input.
+      #
+      # @param question [String]
+      # @param default [String, nil]
+      # @param allow_empty [Boolean]
+      # @return [String]
+      def text(question, default: nil, allow_empty: true)
+        ::CLI::UI.ask(question, default: default, allow_empty: allow_empty)
+      rescue BackKeyPressed
+        Wizard::BACK
+      end
+
+      # Prompts for yes/no confirmation.
+      #
+      # @param question [String]
+      # @param default [Boolean]
+      # @return [Boolean]
+      def confirm(question, default: true)
+        ::CLI::UI.confirm(question, default: default)
+      rescue BackKeyPressed
+        # Confirm callers (preset save, overwrite prompts) don't handle BACK;
+        # swallowing the key press and returning the default is intentional.
+        default
+      end
+
+      # Prints a formatted message to the output stream.
+      #
+      # @param message [String] message with optional +cli-ui+ formatting tags
+      # @return [void]
+      def say(message)
+        @out.puts(::CLI::UI.fmt(message))
+      end
+    end
+  end
+end

data/lib/create_rails_app/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CreateRailsApp
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/create_rails_app/wizard.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+module CreateRailsApp
+  # Step-by-step interactive prompt loop for choosing +rails new+ options.
+  #
+  # Walks through each supported option in {Options::Catalog::ORDER},
+  # presenting only the options supported by the detected Rails version.
+  # Supports back-navigation via +Ctrl+B+ and smart filtering via {SKIP_RULES}.
+  #
+  # @see CLI#run_interactive_wizard!
+  class Wizard
+    # Sentinel returned by the prompter when the user presses Ctrl+B.
+    BACK = Object.new.tap { |o| o.define_singleton_method(:inspect) { '#<BACK>' } }.freeze
+
+    # Human-readable labels for each option key.
+    #
+    # @return [Hash{Symbol => String}]
+    LABELS = {
+      api: 'API-only mode',
+      active_record: 'Active Record (ORM)',
+      database: 'Database',
+      javascript: 'JavaScript approach',
+      css: 'CSS framework',
+      asset_pipeline: 'Asset pipeline',
+      hotwire: 'Hotwire (Turbo + Stimulus)',
+      jbuilder: 'Jbuilder (JSON templates)',
+      action_mailer: 'Action Mailer',
+      action_mailbox: 'Action Mailbox',
+      action_text: 'Action Text (rich text)',
+      active_job: 'Active Job',
+      active_storage: 'Active Storage (file uploads)',
+      action_cable: 'Action Cable (WebSockets)',
+      test: 'Tests',
+      system_test: 'System tests',
+      brakeman: 'Brakeman (security scanner)',
+      bundler_audit: 'Bundler Audit (dependency checker)',
+      rubocop: 'RuboCop (linter)',
+      ci: 'CI files',
+      docker: 'Dockerfile',
+      kamal: 'Kamal (deployment)',
+      thruster: 'Thruster (HTTP/2 proxy)',
+      solid: 'Solid (Cache/Queue/Cable)',
+      devcontainer: 'Dev Container',
+      bootsnap: 'Bootsnap (boot speedup)',
+      dev_gems: 'Dev gems',
+      keeps: 'Source control .keep files',
+      decrypted_diffs: 'Decrypted diffs',
+      git: 'Initialize git',
+      bundle: 'Run bundle install'
+    }.freeze
+
+    # Short explanations shown below each wizard step.
+    #
+    # @return [Hash{Symbol => String}]
+    HELP_TEXT = {
+      api: 'Generates a slimmed-down app optimized for API backends.',
+      active_record: 'Database ORM layer. Skipping also skips the database choice.',
+      database: 'Which database adapter to configure.',
+      javascript: 'How JavaScript is managed in the asset pipeline.',
+      css: 'Which CSS framework to pre-install.',
+      asset_pipeline: 'Which asset pipeline to use for JS/CSS bundling.',
+      hotwire: 'Turbo + Stimulus for SPA-like behavior over HTML.',
+      jbuilder: 'DSL for building JSON views.',
+      action_mailer: 'Framework for sending emails.',
+      action_mailbox: 'Routes inbound emails to controller-like mailboxes.',
+      action_text: 'Rich text content and editing with Trix.',
+      active_job: 'Framework for declaring and running background jobs.',
+      active_storage: 'Upload files to cloud services like S3 or GCS.',
+      action_cable: 'WebSocket framework for real-time features.',
+      test: 'Generates test directory and helpers.',
+      system_test: 'Browser-based integration tests via Capybara.',
+      brakeman: 'Static analysis for security vulnerabilities.',
+      bundler_audit: 'Checks dependencies for known vulnerabilities.',
+      rubocop: 'Ruby style and lint checking.',
+      ci: 'Generates CI workflow configuration.',
+      docker: 'Generates Dockerfile for containerized deployment.',
+      kamal: 'Generates Kamal deploy configuration.',
+      thruster: 'HTTP/2 proxy with asset caching and X-Sendfile.',
+      solid: 'Solid Cache, Solid Queue, and Solid Cable adapters.',
+      devcontainer: 'Generates VS Code dev container configuration.',
+      bootsnap: 'Speeds up boot times with caching.',
+      dev_gems: 'Development gems like web-console.',
+      keeps: 'Empty directories preserved via .keep files.',
+      decrypted_diffs: 'Show decrypted diffs of encrypted credentials in git.',
+      git: 'Initializes a git repository for the new app.',
+      bundle: 'Runs bundle install after generating the app.'
+    }.freeze
+
+    # Per-choice hints displayed next to enum choices.
+    #
+    # @return [Hash{Symbol => Hash{String => String}}]
+    CHOICE_HELP = {
+      database: {
+        'sqlite3' => 'simple file-based, great for development',
+        'postgresql' => 'full-featured, most popular for production',
+        'mysql' => 'widely used relational database',
+        'trilogy' => 'modern MySQL-compatible client',
+        'mariadb-mysql' => 'MariaDB with mysql2 adapter',
+        'mariadb-trilogy' => 'MariaDB with Trilogy adapter'
+      },
+      javascript: {
+        'importmap' => 'no bundler, uses browser-native import maps',
+        'bun' => 'fast all-in-one JS runtime and bundler',
+        'webpack' => 'established full-featured bundler',
+        'esbuild' => 'extremely fast JS bundler',
+        'rollup' => 'ES module-focused bundler',
+        'none' => 'no JavaScript setup'
+      },
+      asset_pipeline: {
+        'propshaft' => 'modern, lightweight asset pipeline',
+        'sprockets' => 'classic asset pipeline with preprocessing',
+        'none' => 'no asset pipeline'
+      },
+      css: {
+        'tailwind' => 'utility-first CSS framework',
+        'bootstrap' => 'popular component-based framework',
+        'bulma' => 'modern CSS-only framework',
+        'postcss' => 'CSS transformations via plugins',
+        'sass' => 'CSS with variables, nesting, and mixins',
+        'none' => 'no CSS framework'
+      }
+    }.freeze
+
+    # Rules that determine when a wizard step should be silently skipped.
+    # Each lambda receives the current values hash and returns true to skip.
+    #
+    # @return [Hash{Symbol => Proc}]
+    SKIP_RULES = {
+      database: ->(values) { values[:active_record] == false },
+      javascript: ->(values) { values[:api] == true },
+      css: ->(values) { values[:api] == true },
+      asset_pipeline: ->(values) { values[:api] == true },
+      hotwire: ->(values) { values[:api] == true },
+      jbuilder: ->(values) { values[:api] == true },
+      action_mailbox: ->(values) { values[:active_record] == false },
+      action_text: ->(values) { values[:api] == true || values[:active_record] == false },
+      active_storage: ->(values) { values[:active_record] == false },
+      system_test: ->(values) { values[:test] == false || values[:api] == true }
+    }.freeze
+
+    attr_reader :last_presented_index
+
+    # @param compatibility_entry [Compatibility::Matrix::Entry]
+    # @param defaults [Hash{Symbol => Object}] initial default values (e.g. last-used)
+    # @param prompter [UI::Prompter]
+    def initialize(compatibility_entry:, defaults:, prompter:)
+      @compatibility_entry = compatibility_entry
+      @prompter = prompter
+      @values = sanitize_defaults(defaults)
+      @stashed = {}
+      @last_presented_index = 0
+    end
+
+    # Runs the wizard and returns the selected options.
+    #
+    # @param start_index [Integer] step index to resume from
+    # @return [Hash{Symbol => Object}]
+    def run(start_index: 0)
+      keys = Options::Catalog::ORDER.select { |key| @compatibility_entry.supports_option?(key) }
+      index = [start_index, keys.length - 1].min
+      while index < keys.length
+        key = keys[index]
+
+        if skip_step?(key)
+          @stashed[key] = @values.delete(key) if @values.key?(key)
+          index += 1
+          next
+        end
+
+        @values[key] = @stashed.delete(key) if @stashed.key?(key) && !@values.key?(key)
+
+        @last_presented_index = index
+        answer = ask_for(key, index:, total: keys.length)
+        case answer
+        when BACK
+          index = find_previous_unskipped(keys, index)
+        else
+          assign_value(key, answer)
+          index += 1
+        end
+      end
+      @values.dup
+    end
+
+    private
+
+    # @param key [Symbol]
+    # @return [Boolean]
+    def skip_step?(key)
+      rule = SKIP_RULES[key]
+      rule&.call(@values)
+    end
+
+    # Finds the previous unskipped step index.
+    #
+    # @param keys [Array<Symbol>]
+    # @param current_index [Integer]
+    # @return [Integer]
+    def find_previous_unskipped(keys, current_index)
+      i = current_index - 1
+      # i.positive? (not i >= 0) stops the loop at i==0 so we can check
+      # the first step explicitly below.  If every preceding step is
+      # skipped, we stay at current_index (nowhere to go back to).
+      i -= 1 while i.positive? && skip_step?(keys[i])
+      return current_index if i >= 0 && skip_step?(keys[i])
+
+      [i, 0].max
+    end
+
+    # @param key [Symbol]
+    # @param index [Integer]
+    # @param total [Integer]
+    # @return [Object] user answer or {BACK}
+    def ask_for(key, index:, total:)
+      definition = Options::Catalog.fetch(key)
+      label = LABELS.fetch(key)
+      skip_question = definition[:type] == :skip ||
+                      (definition[:type] == :enum && !@compatibility_entry.allowed_values(key))
+      question = render_question(index: index, total: total, key: key, label: label, skip: skip_question)
+      case definition[:type]
+      when :skip
+        ask_skip(question, key)
+      when :flag
+        ask_flag(question, key)
+      when :enum
+        # When the Matrix provides nil (no enum values), the option is a
+        # simple include/skip for this Rails version (e.g. asset_pipeline in 8.0+).
+        if @compatibility_entry.allowed_values(key)
+          ask_enum(question, key, definition)
+        else
+          ask_skip(question, key)
+        end
+      else
+        raise Error, "Unknown option type for #{key}"
+      end
+    end
+
+    # @param question [String]
+    # @param key [Symbol]
+    # @return [true, false, BACK]
+    def ask_skip(question, key)
+      choices = %w[no yes]
+      current = @values[key]
+      selected = current == false ? 'yes' : 'no'
+      answer = choose_with_default_marker(question, key:, choices:, rails_default: 'no', selected:)
+      return BACK if answer == BACK
+      return false if answer == 'yes'
+
+      true
+    end
+
+    # @param question [String]
+    # @param key [Symbol]
+    # @return [true, nil, BACK]
+    def ask_flag(question, key)
+      choices = %w[yes no]
+      current = @values[key]
+      selected = current == true ? 'yes' : 'no'
+      answer = choose_with_default_marker(question, key:, choices:, rails_default: 'no', selected:)
+      return BACK if answer == BACK
+      return true if answer == 'yes'
+
+      nil
+    end
+
+    # @param question [String]
+    # @param key [Symbol]
+    # @param definition [Hash]
+    # @return [String, false, BACK]
+    def ask_enum(question, key, definition)
+      choices = @compatibility_entry.allowed_values(key).dup
+      choices << 'none' if definition[:none]
+      current = @values[key]
+      selected = enum_selected_choice(current, choices)
+      rails_default = definition[:rails_default] || choices.first
+      answer = choose_with_default_marker(question, key:, choices:, rails_default:, selected:)
+      return BACK if answer == BACK
+      return false if answer == 'none'
+
+      answer
+    end
+
+    # @param key [Symbol]
+    # @param value [Object]
+    # @return [void]
+    def assign_value(key, value)
+      if value.nil?
+        @values.delete(key)
+      else
+        @values[key] = value
+      end
+    end
+
+    # Filters defaults to only supported options.
+    #
+    # @param hash [Hash]
+    # @return [Hash{Symbol => Object}]
+    def sanitize_defaults(hash)
+      hash.transform_keys(&:to_sym)
+          .select { |key, _| @compatibility_entry.supports_option?(key) }
+    end
+
+    # Resolves which enum choice to pre-select based on the user's last pick.
+    #
+    # @param current [Object]
+    # @param choices [Array<String>]
+    # @return [String]
+    def enum_selected_choice(current, choices)
+      return 'none' if current == false && choices.include?('none')
+      return choices.first if current == true
+      return current if current.is_a?(String) && choices.include?(current)
+
+      choices.first
+    end
+
+    # Presents a choice list with the Rails default labeled and the user's
+    # last pick reordered first (pre-selected).
+    #
+    # @param question [String]
+    # @param key [Symbol]
+    # @param choices [Array<String>]
+    # @param rails_default [String] the true Rails default (labeled "(default)")
+    # @param selected [String] the user's last pick (reordered first)
+    # @return [String] the raw choice value, or {BACK}
+    def choose_with_default_marker(question, key:, choices:, rails_default:, selected:)
+      actual_selected = choices.include?(selected) ? selected : choices.first
+      ordered = choices.include?(rails_default) ? [rails_default] + (choices - [rails_default]) : choices
+      rendered_pairs = ordered.map do |choice|
+        [render_choice_label(key, choice, rails_default: rails_default), choice]
+      end
+      rendered = rendered_pairs.map(&:first)
+      selected_label = rendered_pairs.find { |_, raw| raw == actual_selected }&.first || rendered.first
+      answer = @prompter.choose(question, options: rendered, default: selected_label)
+      return BACK if answer == BACK
+
+      rendered_index = rendered.index(answer)
+      return ordered[rendered_index] if rendered_index
+
+      actual_selected
+    end
+
+    # @param index [Integer]
+    # @param total [Integer]
+    # @param key [Symbol]
+    # @param label [String]
+    # @return [String]
+    def render_question(index:, total:, key:, label:, skip: false)
+      step = format('%<current>02d/%<total>02d', current: index + 1, total: total)
+      if skip
+        "{{cyan:#{step}}} {{bold:Skip #{label}?}} - #{HELP_TEXT.fetch(key)}"
+      else
+        "{{cyan:#{step}}} {{bold:#{label}}} - #{HELP_TEXT.fetch(key)}"
+      end
+    end
+
+    # @param key [Symbol]
+    # @param choice [String]
+    # @param default_choice [String]
+    # @return [String]
+    def render_choice_label(key, choice, rails_default:)
+      label = choice
+      hint = CHOICE_HELP.dig(key, choice)
+      label = "#{label} - #{hint}" if hint
+      label = "#{label} (default)" if choice == rails_default
+      label
+    end
+  end
+end

data/lib/create_rails_app.rb

@@ -1,7 +1,28 @@
 # frozen_string_literal: true
 
 require_relative 'create_rails_app/version'
+require_relative 'create_rails_app/error'
+require_relative 'create_rails_app/detection/runtime'
+require_relative 'create_rails_app/detection/rails_versions'
+require_relative 'create_rails_app/options/catalog'
+require_relative 'create_rails_app/compatibility/matrix'
+require_relative 'create_rails_app/options/validator'
+require_relative 'create_rails_app/command_builder'
+require_relative 'create_rails_app/config/store'
+require_relative 'create_rails_app/runner'
+require_relative 'create_rails_app/ui/palette'
+require_relative 'create_rails_app/ui/prompter'
+require_relative 'create_rails_app/wizard'
+require_relative 'create_rails_app/cli'
 
+# Interactive TUI wizard for +rails new+.
+#
+# Detects installed Rails versions, shows version-aware options
+# via a static compatibility matrix, and builds the correct +rails new+
+# command. Config (presets, last-used options) is stored in
+# +~/.config/create-rails-app/config.yml+.
+#
+# @see CreateRailsApp::CLI Entry point
+# @see CreateRailsApp::Compatibility::Matrix Rails version compatibility
 module CreateRailsApp
-  class Error < StandardError; end
 end

metadata

@@ -1,16 +1,45 @@
 --- !ruby/object:Gem::Specification
 name: create-rails-app
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Leonid Svyatov
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: Interactive CLI wizard for rails new. Walks you through every option,
-  saves presets, and remembers your choices. Work in progress!
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cli-kit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: cli-ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: Stop memorizing rails new flags. This interactive CLI wizard walks you
+  through every option, remembers your last choices, and saves reusable presets. Supports
+  Rails 7.2+ with version-aware option filtering, back navigation, and dry-run mode.
 email:
 - leonid@svyatov.com
 executables:
@@ -23,7 +52,20 @@ files:
 - README.md
 - exe/create-rails-app
 - lib/create_rails_app.rb
+- lib/create_rails_app/cli.rb
+- lib/create_rails_app/command_builder.rb
+- lib/create_rails_app/compatibility/matrix.rb
+- lib/create_rails_app/config/store.rb
+- lib/create_rails_app/detection/rails_versions.rb
+- lib/create_rails_app/detection/runtime.rb
+- lib/create_rails_app/error.rb
+- lib/create_rails_app/options/catalog.rb
+- lib/create_rails_app/options/validator.rb
+- lib/create_rails_app/runner.rb
+- lib/create_rails_app/ui/palette.rb
+- lib/create_rails_app/ui/prompter.rb
 - lib/create_rails_app/version.rb
+- lib/create_rails_app/wizard.rb
 homepage: https://github.com/svyatov/create-rails-app
 licenses:
 - MIT
@@ -51,5 +93,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Interactive CLI wizard for rails new (coming soon)
+summary: Interactive CLI wizard for rails new that remembers your choices and saves
+  presets.
 test_files: []