railstart 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06f6eda8bd62deeef7ba87448cd471a783f36a31c8a0026a6f4813883dc4ea7e
+  data.tar.gz: d493a6c6f85c095e45f0fbc8f5c380488af1fc57fbdd07802f7fe8481e528f4d
+SHA512:
+  metadata.gz: 0a45f5201a19322362da2029b79b5a96439c4c68d0f1201f605bc88008adfc602a28bba0423f3db3a7b43acc5d4ded66a42ad11f3ed281483b417ec31ab32c16
+  data.tar.gz: 95f319acae2e68a8ed747cb98fc20f6194e9d85947c5b63a345bf4b0d95b72c21f3a08a9638347f75ca7a619f278e10ef29ea26d52b620c2d18f7ffc34006c5a

data/.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--output-dir doc
+--protected
+--private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [0.1.0] - 2025-11-21
+
+### Added
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dpaluy
+
+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,240 @@
+# Railstart
+
+[![Gem Version](https://badge.fury.io/rb/railstart.svg)](https://badge.fury.io/rb/railstart)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/railstart)
+[![CI](https://github.com/dpaluy/railstart/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/railstart/actions/workflows/ci.yml)
+
+Interactive CLI wizard for generating Rails 8 applications with customizable configuration and smart defaults.
+
+Think of it as `rails new` with an opinion and a friendly interactive experience.
+
+## Installation
+
+```bash
+gem install railstart
+```
+
+## Usage
+
+### Generate a new Rails app
+
+```bash
+railstart new my_app
+
+# Or run without arguments for help
+railstart
+```
+
+This launches an interactive wizard that guides you through Rails app setup:
+
+```
+Which database?
+1) SQLite (default)
+2) PostgreSQL
+3) MySQL
+> 2
+
+Which CSS framework?
+1) Tailwind (default)
+2) Bootstrap
+3) Bulma
+4) PostCSS
+5) None
+> 1
+
+Which JavaScript bundler?
+1) Importmap (default)
+2) esbuild
+3) Webpack
+4) Rollup
+> 1
+
+Skip any features?
+(space to select, enter when done)
+‣ ⓞ Action Mailer
+  ⓞ Action Mailbox
+  ⓞ Action Text
+  ...
+
+Generate API-only app?
+> No
+
+... (more questions) ...
+
+Summary
+════════════════════════════════════════
+App name: my_app
+Database: postgresql
+CSS: tailwind
+JavaScript: importmap
+Skipped: (none)
+API: No
+════════════════════════════════════════
+
+Proceed with app generation? Yes
+
+Running: rails new my_app --database=postgresql --css=tailwind ...
+
+Creating Rails app...
+✨ Rails app created successfully at ./my_app
+```
+
+### Skip interactive mode (use defaults)
+
+Use the `--default` flag to skip all questions and apply built-in defaults:
+
+```bash
+railstart new my_app --default
+```
+
+This creates a PostgreSQL + Tailwind + Importmap Rails app instantly.
+
+## Configuration
+
+### Built-in Defaults
+
+Railstart ships with sensible Rails 8 defaults defined in `config/rails8_defaults.yaml`. These drive the interactive questions and their defaults.
+
+### Customize for Your Team
+
+Create a `~/.config/railstart/config.yaml` file to override defaults:
+
+```yaml
+questions:
+  - id: database
+    choices:
+      - name: PostgreSQL (recommended)
+        value: postgresql
+        default: true  # Your team's preference
+
+post_actions:
+  - id: bundle_install
+    enabled: false  # Your team manages gems differently
+  
+  - id: setup_auth
+    name: "Setup authentication"
+    enabled: true
+    command: "bundle exec rails generate devise:install"
+```
+
+**Merge behavior:**
+
+- User config (at `~/.config/railstart/config.yaml`) overrides built-in config
+- By `id`: questions and post-actions are merged by their unique `id`
+- If you override a question's `choices`, the entire choice list is replaced
+- New questions/actions are appended in order
+
+### Configuration Schema
+
+#### Questions
+
+```yaml
+questions:
+  - id: database                    # unique identifier
+    type: select|multi_select|yes_no|input
+    prompt: "User-facing question"
+    help: "Optional inline help text"
+    default: value_or_true_or_false
+    
+    # For select/multi_select
+    choices:
+      - name: "Display name"
+        value: "internal_value"
+        default: true              # at most one per select
+        rails_flag: "--flag=%{value}"
+    
+    # For yes_no/input
+    rails_flag: "--flag"            # or --flag=%{value}
+    
+    # Optional: only ask if condition is met
+    depends_on:
+      question: other_question_id
+      value: expected_value
+```
+
+**Question types:**
+
+- `select` - Single choice; returns scalar value
+- `multi_select` - Multiple choices; returns array
+- `yes_no` - Boolean; returns true/false
+- `input` - Free text; returns string
+
+#### Post-actions
+
+```yaml
+post_actions:
+  - id: my_action                   # unique identifier
+    name: "Human readable name"
+    enabled: true                   # can be disabled
+    command: "shell command to run"
+    
+    # Optional: prompt user before running
+    prompt: "Run this action?"
+    default: true
+    
+    # Optional: only run if condition is met
+    if:
+      question: question_id
+      equals: value                 # or includes: [array, values]
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+bundle install
+
+# Or use the setup script
+bin/setup
+```
+
+### Testing the CLI
+
+```bash
+# Test the executable during development
+bundle exec exe/railstart new my_app
+bundle exec exe/railstart new my_app --default
+
+# Interactive console for experimenting
+bin/console
+# Then in IRB:
+# Railstart::CLI.start(["new", "my_app"])
+
+# Install locally to test as a real gem
+gem build railstart.gemspec
+gem install railstart-0.1.0.gem
+railstart new my_app
+```
+
+### Running Tests
+
+```bash
+# Run tests
+bundle exec rake test
+
+# Lint code
+bundle exec rubocop
+
+# Lint and auto-fix
+bundle exec rubocop -a
+
+# Full check
+bundle exec rake test && bundle exec rubocop
+```
+
+## Architecture
+
+- **Config System** (`lib/railstart/config.rb`) - Loads and merges YAML configurations
+- **Generator** (`lib/railstart/generator.rb`) - Orchestrates interactive flow
+- **Command Builder** (`lib/railstart/command_builder.rb`) - Translates answers to `rails new` flags
+- **CLI** (`lib/railstart/cli.rb`) - Thor command interface
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/railstart.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+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
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = ["--output-dir", "doc", "--markup", "markdown"]
+  end
+rescue LoadError
+  # YARD not available
+end
+
+task default: :test

data/config/rails8_defaults.yaml

@@ -0,0 +1,124 @@
+---
+# Railstart Rails 8 Default Configuration
+# This configuration defines all available questions and post-generation actions
+# Users can override this by creating ~/.config/railstart/config.yaml
+
+questions:
+  - id: database
+    type: select
+    prompt: "Which database?"
+    choices:
+      - name: SQLite
+        value: sqlite3
+        default: true
+      - name: PostgreSQL
+        value: postgresql
+      - name: MySQL
+        value: mysql
+    rails_flag: "--database=%<value>s"
+
+  - id: css
+    type: select
+    prompt: "Which CSS framework?"
+    choices:
+      - name: Tailwind
+        value: tailwind
+        default: true
+      - name: Bootstrap
+        value: bootstrap
+      - name: Bulma
+        value: bulma
+      - name: PostCSS (no framework)
+        value: postcss
+      - name: None
+        value: none
+    rails_flag: "--css=%{value}"
+
+  - id: javascript
+    type: select
+    prompt: "Which JavaScript bundler?"
+    choices:
+      - name: Importmap (default)
+        value: importmap
+        default: true
+      - name: esbuild
+        value: esbuild
+      - name: Webpack
+        value: webpack
+      - name: Rollup
+        value: rollup
+    rails_flag: "--javascript=%{value}"
+
+  - id: skip_features
+    type: multi_select
+    prompt: "Skip any features?"
+    choices:
+      - name: Action Mailer
+        value: action_mailer
+        rails_flag: "--skip-action-mailer"
+      - name: Action Mailbox
+        value: action_mailbox
+        rails_flag: "--skip-action-mailbox"
+      - name: Action Text
+        value: action_text
+        rails_flag: "--skip-action-text"
+      - name: Active Record
+        value: active_record
+        rails_flag: "--skip-active-record"
+      - name: Active Job
+        value: active_job
+        rails_flag: "--skip-active-job"
+      - name: Active Storage
+        value: active_storage
+        rails_flag: "--skip-active-storage"
+      - name: Action Cable
+        value: action_cable
+        rails_flag: "--skip-action-cable"
+      - name: Hotwire (Turbo + Stimulus)
+        value: hotwire
+        rails_flag: "--skip-hotwire"
+
+  - id: api_only
+    type: yes_no
+    prompt: "Generate API-only app? (no views, minimal middleware)"
+    default: false
+    rails_flag: "--api"
+
+  - id: skip_git
+    type: yes_no
+    prompt: "Skip git initialization?"
+    default: false
+    rails_flag: "--skip-git"
+
+  - id: skip_docker
+    type: yes_no
+    prompt: "Skip Docker setup?"
+    default: false
+    rails_flag: "--skip-docker"
+
+  - id: skip_bundle
+    type: yes_no
+    prompt: "Skip bundle install? (run manually later)"
+    default: false
+    rails_flag: "--skip-bundle"
+
+post_actions:
+  - id: init_git
+    name: "Initialize git repository"
+    enabled: true
+    prompt: "Initialize git and create first commit?"
+    default: true
+    if:
+      question: skip_git
+      equals: false
+    command: "git init && git add . && git commit -m 'Initial commit'"
+
+  - id: bundle_install
+    name: "Install gems"
+    enabled: true
+    prompt: "Run bundle install?"
+    default: true
+    if:
+      question: skip_bundle
+      equals: true
+    command: "bundle install"

data/exe/railstart

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "railstart"
+
+Railstart::CLI.start(ARGV)

data/lib/railstart/cli.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "generator"
+
+module Railstart
+  # CLI commands for Railstart, exposing Thor tasks for interactive generation.
+  #
+  # @example Run the wizard with defaults
+  #   Railstart::CLI.start(%w[new my_app --default])
+  # @example Print version
+  #   Railstart::CLI.start(%w[version])
+  class CLI < Thor
+    desc "new [APP_NAME]", "Start a new interactive Rails app setup"
+    option :default, type: :boolean, default: false, desc: "Use default configuration without prompting"
+    #
+    # @param app_name [String, nil] desired Rails app name, prompted if omitted
+    # @return [void]
+    # @raise [Railstart::Error] when generation fails due to configuration or runtime errors
+    # @example Start wizard with prompts
+    #   Railstart::CLI.start(%w[new my_app])
+    def new(app_name = nil)
+      generator = Generator.new(app_name, use_defaults: options[:default])
+      generator.run
+    rescue Railstart::Error => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "version", "Print Railstart version"
+    #
+    # @return [void]
+    # @example Display version string
+    #   Railstart::CLI.start(%w[version])
+    def version
+      puts "Railstart v#{Railstart::VERSION}"
+    end
+  end
+end

data/lib/railstart/command_builder.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Railstart
+  # Translates configuration and user answers into a `rails new` command string.
+  #
+  # This class provides deterministic, side-effect-free command construction.
+  #
+  # @example Build a command from answers
+  #   config = { "questions" => [{ "id" => "database", "type" => "select", "rails_flag" => "--database=%{value}" }] }
+  #   answers = { "database" => "postgresql" }
+  #   Railstart::CommandBuilder.build("blog", config, answers)
+  #   # => "rails new blog --database=postgresql"
+  class CommandBuilder
+    class << self
+      #
+      # Build a `rails new` command string using config metadata and answers.
+      #
+      # @param app_name [String] target Rails app name
+      # @param config [Hash] merged configuration from {Railstart::Config.load}
+      # @param answers [Hash] user answers keyed by question id
+      # @return [String] fully assembled CLI command
+      # @raise [Railstart::ConfigError] when flag interpolation fails
+      # @example
+      #   Railstart::CommandBuilder.build("todo", config, answers)
+      def build(app_name, config, answers)
+        flags = collect_flags(config["questions"], answers)
+        "rails new #{app_name} #{flags.join(" ")}".strip
+      end
+
+      private
+
+      def collect_flags(questions, answers)
+        flags = []
+        Array(questions).each do |question|
+          answer = answers[question["id"]]
+          next unless answer
+
+          process_question_flags(flags, question, answer)
+        end
+        flags
+      end
+
+      def process_question_flags(flags, question, answer)
+        case question["type"]
+        when "select", "yes_no", "input"
+          add_flags(flags, question, answer)
+        when "multi_select"
+          process_multi_select(flags, question, answer)
+        end
+      end
+
+      def process_multi_select(flags, question, answer)
+        Array(question["choices"]).each do |choice|
+          next unless Array(answer).include?(choice["value"])
+
+          add_flags(flags, choice, choice["value"])
+        end
+      end
+
+      def add_flags(flags, source, value)
+        flag_list = source["rails_flags"] || [source["rails_flag"]].compact
+
+        flag_list.each do |flag|
+          interpolated = Config.interpolate_flag(flag, value)
+          flags << interpolated
+        end
+      end
+    end
+  end
+end

data/lib/railstart/config.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "errors"
+
+module Railstart
+  # Provides loading, merging, and validation of Railstart configuration data.
+  #
+  # Combines built-in defaults with optional user overrides and exposes helpers
+  # for downstream components.
+  class Config
+    BUILTIN_CONFIG_PATH = File.expand_path("../../config/rails8_defaults.yaml", __dir__)
+    USER_CONFIG_PATH = File.expand_path("~/.config/railstart/config.yaml")
+    QUESTION_TYPES = %w[select multi_select yes_no input].freeze
+    CHOICE_REQUIRED_TYPES = %w[select multi_select].freeze
+    MERGEABLE_COLLECTIONS = %w[questions post_actions].freeze
+
+    class << self
+      #
+      # Load, merge, and validate configuration from built-in and user sources.
+      #
+      # @param builtin_path [String] path to default config YAML shipped with the gem
+      # @param user_path [String] optional user override YAML path
+      # @return [Hash] deep-copied, merged, validated configuration hash
+      # @raise [Railstart::ConfigLoadError] when YAML files are missing or unreadable
+      # @raise [Railstart::ConfigValidationError] when validation fails
+      # @example
+      #   config = Railstart::Config.load
+      def load(builtin_path: BUILTIN_CONFIG_PATH, user_path: USER_CONFIG_PATH)
+        builtin = read_yaml(builtin_path, required: true)
+        user = read_yaml(user_path, required: false)
+        merged = merge_config(builtin, user)
+        validate!(merged)
+        merged
+      end
+
+      #
+      # Interpolate `%{value}` placeholders within Rails flags.
+      #
+      # @param template [String] flag template
+      # @param value [Object] value to substitute into the template
+      # @return [String] interpolated flag string
+      # @raise [Railstart::ConfigError] when placeholder tokens are invalid
+      # @example
+      #   Railstart::Config.interpolate_flag("--database=%{value}", "postgresql")
+      #   # => "--database=postgresql"
+      def interpolate_flag(template, value)
+        return template if template.nil? || (!template.include?("%{") && !template.include?("%<"))
+
+        format(template, value: value)
+      rescue KeyError => e
+        raise ConfigError, "Invalid interpolation token in rails_flag \"#{template}\": #{e.message}"
+      end
+
+      private
+
+      def read_yaml(path, required:)
+        return {} if path.nil? || path.to_s.empty?
+
+        unless File.exist?(path)
+          raise ConfigLoadError, "Missing required config file: #{path}" if required
+
+          return {}
+        end
+
+        data = YAML.safe_load_file(path, aliases: true) || {}
+        raise ConfigLoadError, "Config file #{path} must define a Hash at the top level" unless data.is_a?(Hash)
+
+        deep_dup(data)
+      rescue Errno::EACCES => e
+        raise ConfigLoadError, "Cannot read #{path}: #{e.message}"
+      rescue Psych::Exception => e
+        raise ConfigLoadError, "Failed to parse #{path}: #{e.message}"
+      end
+
+      def merge_config(base, override)
+        normalized_base = base || {}
+        return deep_dup(normalized_base) if override.nil? || override.empty?
+
+        deep_merge_hash(normalized_base, override)
+      end
+
+      def deep_merge_hash(base, override)
+        return deep_dup(base || {}) if override.nil? || override.empty?
+
+        result = deep_dup(base || {})
+        override.each do |key, override_value|
+          result[key] = deep_merge_value(key, result[key], override_value)
+        end
+        result
+      end
+
+      def deep_merge_value(key, left, right)
+        return deep_dup(left) if right.nil?
+        return deep_dup(right) if left.nil?
+
+        if special_array_key?(key)
+          merge_id_array(left, right)
+        elsif left.is_a?(Hash) && right.is_a?(Hash)
+          deep_merge_hash(left, right)
+        else
+          deep_dup(right)
+        end
+      end
+
+      def merge_id_array(base, override)
+        base_entries = Array(base)
+        override_entries = Array(override)
+
+        map = {}
+        order = []
+        base_without_id = []
+
+        base_entries.each do |entry|
+          copy = deep_dup(entry)
+          id = fetch_id(copy)
+          if id
+            order << id unless order.include?(id)
+            map[id] = copy
+          else
+            base_without_id << copy
+          end
+        end
+
+        override_without_id = []
+        override_entries.each do |entry|
+          copy = deep_dup(entry)
+          id = fetch_id(copy)
+          if id
+            order << id unless order.include?(id)
+            map[id] = merge_entries(map[id], copy)
+          else
+            override_without_id << copy
+          end
+        end
+
+        order.map { |id| map[id] } + base_without_id + override_without_id
+      end
+
+      def merge_entries(left, right)
+        return deep_dup(right) if left.nil?
+        return deep_dup(left) if right.nil?
+
+        if left.is_a?(Hash) && right.is_a?(Hash)
+          deep_merge_hash(left, right)
+        else
+          deep_dup(right)
+        end
+      end
+
+      def fetch_id(entry)
+        return unless entry.respond_to?(:[])
+
+        entry["id"] || entry[:id]
+      end
+
+      def validate!(config)
+        issues = []
+        question_ids = Array(config["questions"]).map { |e| fetch_id(e) }.compact
+
+        MERGEABLE_COLLECTIONS.each do |collection|
+          entries = Array(config[collection])
+          issues.concat(validate_collection(collection, entries, question_ids))
+        end
+        raise ConfigValidationError.new("Invalid configuration", issues: issues) unless issues.empty?
+      end
+
+      def validate_collection(name, entries, question_ids = [])
+        issues = []
+        id_counts = Hash.new(0)
+
+        entries.each_with_index do |entry, index|
+          unless entry.is_a?(Hash)
+            issues << "#{name} entry at index #{index} must be a Hash"
+            next
+          end
+
+          id = fetch_id(entry)
+          if id.nil? || id.to_s.strip.empty?
+            issues << "#{name} entry at index #{index} is missing an id"
+          else
+            id_counts[id] += 1
+          end
+
+          if name == "questions"
+            type = entry["type"] || entry[:type]
+            unless QUESTION_TYPES.include?(type)
+              issues << "Question #{id || index} has invalid type #{type.inspect}"
+              next
+            end
+
+            issues.concat(validate_question_choices(entry, id || index)) if CHOICE_REQUIRED_TYPES.include?(type)
+          elsif name == "post_actions"
+            if entry.fetch("enabled", true)
+              command = entry["command"] || entry[:command]
+              if command.nil? || command.to_s.strip.empty?
+                issues << "Post-action #{id || index} is enabled but missing a command"
+              end
+            end
+
+            if_condition = entry["if"] || entry[:if]
+            if if_condition.is_a?(Hash)
+              ref_question_id = if_condition["question"] || if_condition[:question]
+              if ref_question_id && !question_ids.include?(ref_question_id)
+                issues << "Post-action #{id || index} references unknown question '#{ref_question_id}'"
+              end
+            end
+          end
+        end
+
+        id_counts.each do |id, count|
+          issues << "#{name} entry id #{id} is defined #{count} times" if count > 1
+        end
+
+        issues
+      end
+
+      def validate_question_choices(entry, question_id)
+        issues = []
+        choices = entry["choices"] || entry[:choices]
+
+        if !choices.is_a?(Array) || choices.empty?
+          issues << "Question #{question_id} (#{entry["type"]}) must define at least one choice"
+          return issues
+        end
+
+        choices.each_with_index do |choice, cidx|
+          unless choice.is_a?(Hash)
+            issues << "Question #{question_id} choice at index #{cidx} must be a Hash"
+            next
+          end
+          unless choice["name"] || choice[:name]
+            issues << "Question #{question_id} choice at index #{cidx} missing 'name'"
+          end
+          unless choice["value"] || choice[:value]
+            issues << "Question #{question_id} choice at index #{cidx} missing 'value'"
+          end
+        end
+
+        issues
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.transform_values { |v| deep_dup(v) }
+        when Array
+          value.map { |v| deep_dup(v) }
+        else
+          value
+        end
+      end
+
+      def special_array_key?(key)
+        key && MERGEABLE_COLLECTIONS.include?(key.to_s)
+      end
+    end
+  end
+end

data/lib/railstart/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Railstart
+  # Base error class for all Railstart-specific failures.
+  class Error < StandardError; end
+
+  # Raised for configuration-related issues within Railstart.
+  class ConfigError < Error; end
+
+  # Raised when configuration files cannot be read or parsed.
+  class ConfigLoadError < ConfigError; end
+
+  # Raised when configuration validation fails with one or more issues.
+  #
+  # @attr_reader issues [Array<String>] collection of validation error descriptions
+  class ConfigValidationError < ConfigError
+    attr_reader :issues
+
+    #
+    # @param message [String] base message explaining the failure
+    # @param issues [Array<String>] detailed validation error messages
+    def initialize(message = "Invalid configuration", issues: [])
+      @issues = Array(issues)
+      detail = @issues.empty? ? message : "#{message}:\n- #{@issues.join("\n- ")}"
+      super(detail)
+    end
+  end
+end

data/lib/railstart/generator.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+
+module Railstart
+  # Orchestrates the interactive Rails app generation flow.
+  #
+  # Handles configuration loading, prompting, summary display, command execution,
+  # and optional post-generation actions while remaining easy to test.
+  #
+  # @example Run generator with provided config
+  #   config = Railstart::Config.load
+  #   Railstart::Generator.new("blog", config: config).run
+  class Generator
+    #
+    # @param app_name [String, nil] preset app name, prompted if nil
+    # @param config [Hash, nil] injected config for testing, defaults to Config.load
+    # @param use_defaults [Boolean] skip interactive mode and use all defaults
+    # @param prompt [TTY::Prompt] injectable prompt for testing
+    def initialize(app_name = nil, config: nil, use_defaults: false, prompt: nil)
+      @app_name = app_name
+      @config = config || Config.load
+      @use_defaults = use_defaults
+      @prompt = prompt || TTY::Prompt.new
+      @answers = {}
+    end
+
+    #
+    # Run the complete generation flow, prompting the user and invoking Rails.
+    #
+    # @return [void]
+    # @raise [Railstart::ConfigError, Railstart::ConfigValidationError] when configuration is invalid
+    # @example Run interactively using defaults or custom answers
+    #   Railstart::Generator.new.run
+    def run
+      ask_app_name unless @app_name
+      ask_questions
+      show_summary
+      return unless confirm_proceed?
+
+      generate_app
+      run_post_actions
+    end
+
+    private
+
+    def ask_app_name
+      @app_name = @prompt.ask("App name?", default: "my_app") do |q|
+        q.validate(/\A[a-z0-9_-]+\z/, "Must be lowercase letters, numbers, underscores, or hyphens")
+      end
+    end
+
+    def ask_questions
+      if @use_defaults
+        collect_defaults
+      else
+        ask_interactive_questions
+      end
+    end
+
+    def collect_defaults
+      Array(@config["questions"]).each do |question|
+        default_value = find_default(question)
+        @answers[question["id"]] = default_value unless default_value.nil?
+      end
+    end
+
+    def ask_interactive_questions
+      Array(@config["questions"]).each do |question|
+        handle_question(question)
+      end
+    end
+
+    def handle_question(question)
+      return if should_skip_question?(question)
+
+      @answers[question["id"]] = ask_question(question)
+    end
+
+    def should_skip_question?(question)
+      depends = question["depends_on"]
+      return false unless depends
+
+      dep_question_id = depends["question"]
+      dep_value = depends["value"]
+
+      actual_value = @answers[dep_question_id]
+      actual_value != dep_value
+    end
+
+    def ask_question(question)
+      case question["type"]
+      when "select"
+        ask_select(question)
+      when "multi_select"
+        ask_multi_select(question)
+      when "yes_no"
+        ask_yes_no?(question)
+      when "input"
+        ask_input(question)
+      end
+    end
+
+    def ask_select(question)
+      choices = question["choices"].map { |c| [c["name"], c["value"]] }
+      default_val = find_default(question)
+
+      @prompt.select(question["prompt"], choices, default: default_val)
+    end
+
+    def ask_multi_select(question)
+      choices = question["choices"].map { |c| [c["name"], c["value"]] }
+      defaults = question["default"] || []
+
+      @prompt.multi_select(question["prompt"], choices, default: defaults)
+    end
+
+    def ask_yes_no?(question)
+      @prompt.yes?(question["prompt"], default: question.fetch("default", false))
+    end
+
+    def ask_input(question)
+      @prompt.ask(question["prompt"], default: question["default"])
+    end
+
+    def find_default(question)
+      # Support both default at question level and default: true on choice
+      return question["default"] if question.key?("default")
+
+      Array(question["choices"]).find { |c| c["default"] }&.[]("value")
+    end
+
+    def show_summary
+      puts "\n════════════════════════════════════════"
+      puts "Summary"
+      puts "════════════════════════════════════════"
+      puts "App name: #{@app_name}"
+
+      Array(@config["questions"]).each do |question|
+        question_id = question["id"]
+        next unless @answers.key?(question_id)
+
+        answer = @answers[question_id]
+        label = question["prompt"].delete_suffix("?").delete_suffix(":").strip
+
+        value_str = case answer
+                    when Array
+                      answer.empty? ? "none" : answer.join(", ")
+                    when false
+                      "No"
+                    when true
+                      "Yes"
+                    else
+                      answer.to_s
+                    end
+
+        puts "#{label}: #{value_str}"
+      end
+      puts "════════════════════════════════════════\n"
+    end
+
+    def confirm_proceed?
+      return true if @use_defaults
+
+      @prompt.yes?("Proceed with app generation?")
+    end
+
+    def generate_app
+      command = CommandBuilder.build(@app_name, @config, @answers)
+
+      puts "Running: #{command}\n\n"
+      success = system(command)
+
+      return if success
+
+      raise Error, "Failed to generate Rails app. Check the output above for details."
+    end
+
+    def run_post_actions
+      Dir.chdir(@app_name)
+      Array(@config["post_actions"]).each { |action| process_post_action(action) }
+      puts "\n✨ Rails app created successfully at ./#{@app_name}"
+    rescue Errno::ENOENT
+      warn "Could not change to app directory. Post-actions skipped."
+    end
+
+    def process_post_action(action)
+      return unless should_run_action?(action)
+      return unless confirm_action?(action)
+
+      execute_action(action)
+    end
+
+    def confirm_action?(action)
+      return true unless action["prompt"]
+
+      @prompt.yes?(action["prompt"], default: action.fetch("default", true))
+    end
+
+    def execute_action(action)
+      puts "→ #{action["name"]}"
+      success = system(action["command"])
+      warn "Warning: Post-action '#{action["name"]}' failed. Continuing anyway." unless success
+    end
+
+    def should_run_action?(action)
+      return false unless action.fetch("enabled", true)
+
+      if_condition = action["if"]
+      return true unless if_condition
+
+      question_id = if_condition["question"]
+      answer = @answers[question_id]
+
+      if if_condition.key?("equals")
+        answer == if_condition["equals"]
+      elsif if_condition.key?("includes")
+        expected = Array(if_condition["includes"])
+        actual = Array(answer)
+        expected.intersect?(actual)
+      else
+        true
+      end
+    end
+  end
+end

data/lib/railstart/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Railstart
+  VERSION = "0.1.0"
+end

data/lib/railstart.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "railstart/version"
+require_relative "railstart/errors"
+require_relative "railstart/config"
+require_relative "railstart/command_builder"
+require_relative "railstart/generator"
+require_relative "railstart/cli"
+
+# Main namespace for the Railstart gem.
+#
+# Provides an interactive CLI wizard for generating Rails 8 applications
+# with customizable configuration and post-generation hooks.
+#
+# @example Generate a new Rails app
+#   $ railstart new my_app
+#
+# @see CLI
+# @see Generator
+# @see Config
+module Railstart
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: railstart
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dpaluy
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tty-prompt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Interactive CLI wizard for Rails app generation with customizable config
+email:
+- dpaluy@users.noreply.github.com
+executables:
+- railstart
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- config/rails8_defaults.yaml
+- exe/railstart
+- lib/railstart.rb
+- lib/railstart/cli.rb
+- lib/railstart/command_builder.rb
+- lib/railstart/config.rb
+- lib/railstart/errors.rb
+- lib/railstart/generator.rb
+- lib/railstart/version.rb
+homepage: https://github.com/dpaluy/railstart
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/dpaluy/railstart
+  documentation_uri: https://rubydoc.info/gems/railstart
+  source_code_uri: https://github.com/dpaluy/railstart
+  changelog_uri: https://github.com/dpaluy/railstart/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dpaluy/railstart/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Rails application starter and development utilities
+test_files: []