railstart 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 291b9eb1edd2bd473da3d2da1ca08921b4320e7892926dfb6f4099e6c3c9b51a
-  data.tar.gz: bd917d5cc282fb789d57fe88eaa484cd86a83c079801f0ca32f701be70c9986a
+  metadata.gz: 675d33f74310aa870ad6a167cbd585cc643b3e37096d255732bcf900fa7ab65d
+  data.tar.gz: 460628c266ba316d4ad19e148b9e8044912865c98f6c091dd8a1be25653dab71
 SHA512:
-  metadata.gz: 001e22b7e5f50d84058280cee64a759da54fb60a77f2e895c6ed9d01f5b53a767dbe7e1ce3d67e6ac888cec3cb3daa66c237f1118e0e0680fa7603e02d0f02ca
-  data.tar.gz: 5fe74710ececff1600e82ceceff405f9bd5a5d068b3ea26ebb47558e98f530bd72c03f74b0872e63d9f5c0b25268aca731753b425571594c65fc4cba83a2361b
+  metadata.gz: 344c0860107725a5a56e88bf108a7e7a73891da7f0f7678850af5c47469ed63f91c8c22de71743dc68747557f7d34aac2d001814033dee29533f5b343d8b7e0d
+  data.tar.gz: 2252beeb778c40a048e1156aebd1786a904fa7cf5edec89fd89d924265b223ff742024ceee8491d5b2a5b459a8a560047be60e43a85c13d771ee96db6edd978a

data/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.4.0] - 2025-11-22
+
+### Added
+- CLI `--preset` flag now accepts explicit `.yaml`/`.yml` file paths in addition to preset names.
+- **Template post-actions**: New `type: template` post-action type for executing full Rails application templates
+- **TemplateRunner**: New `Railstart::TemplateRunner` class wraps Rails' AppGenerator to run templates with proper context
+- **Template variables**: Template actions support `variables` hash for injecting custom instance variables into templates
+- **Built-in variables**: Templates automatically receive `@app_name` and `@answers` instance variables
+- **Template DSL support**: Full access to Rails template DSL (`gem`, `route`, `initializer`, `after_bundle`, etc.)
+- **Error handling**: New `Railstart::TemplateError` for template execution failures with proper error wrapping
+- **Config validation**: Validation for template post-actions (requires `source`, validates `variables` as Hash)
+- **Documentation**: README section explaining template post-actions vs command actions with security guidance
+
+### Changed
+- **Post-action processing**: Refactored to support both command and template execution types
+- **Directory context**: `run_post_actions` now uses block form of `Dir.chdir` for proper scoping
+- **Config validation**: Enhanced `validate_post_action_entry` to handle multiple action types
+
+### Technical
+- New file: `lib/railstart/template_runner.rb` (77 lines, full YARD docs)
+- New test file: `test/template_runner_test.rb` (comprehensive coverage with mocks)
+- Enhanced `lib/railstart/generator.rb` with template execution flow
+- Enhanced `lib/railstart/config.rb` with template action validation
+- Version bump: 0.3.0 → 0.4.0
+- All tests pass (39 runs, 111 assertions, 0 failures)
+- RuboCop clean (20 files inspected, no offenses)
+
+## [0.3.0] - 2025-11-22
+
+### Added
+- **CSS framework**: Added Sass option to CSS framework choices
+- **CSS framework**: Added "None (skip CSS setup)" option for skipping CSS configuration
+- **JavaScript bundler**: Added Bun as a JavaScript bundler option (Rails 8 native support)
+- **JavaScript bundler**: Added Vite (via vite_rails gem) with automatic post-installation setup
+- **JavaScript bundler**: Added "None (skip JavaScript)" option using `--skip-javascript` flag
+- **Test framework**: New test framework selection question (Minitest default, RSpec option)
+- **Post-action**: RSpec automatic setup (`bundle add rspec-rails` + `rails generate rspec:install`) when selected
+- **Post-action**: Vite Rails automatic setup (`bundle add vite_rails` + `bundle exec vite install`) when selected
+- **Post-action**: Bundlebun optional setup (`bundle add bundlebun` + `rake bun:install`) for Bun packaged as a gem
+- **Preset**: New `vite-bun.yaml` preset for modern frontend with Vite + Bundlebun (use with `--preset vite-bun`)
+- **Command builder**: Choice-level `rails_flag` support for SELECT questions
+- **Command builder**: Different choices can now have different flags or no flag at all
+- **Tests**: Comprehensive test coverage for choice-level rails_flag feature
+
+### Changed
+- **JavaScript question**: Renamed prompt from "Which JavaScript bundler?" to "Which JavaScript approach?"
+- **Command builder**: SELECT questions now check for choice-level flags before falling back to question-level flags
+- **Command builder**: Vite choice doesn't add any rails flag (handled via post-action instead)
+- **Config**: JavaScript choices now use choice-level `rails_flag` instead of question-level for flexibility
+
+### Technical
+- Enhanced `CommandBuilder.process_select` to support per-choice flag configuration
+- Backward compatible with existing configs using question-level flags
+- All tests pass (33 runs, 97 assertions, 0 failures)
+- Rubocop clean (no offenses)
 
 ## [0.2.1] - 2025-11-22
 

data/README.md

@@ -141,6 +141,70 @@ railstart new my_app --preset api-only
 railstart new my_app --preset api-only --default
 ```
 
+## Creating Custom Presets
+
+Presets are powerful tools for defining opinionated Rails configurations for specific stacks or team standards. For comprehensive guidance on creating presets, see **[Creating Presets Guide](docs/railstart-preset-builder/SKILL.md)**.
+
+### Quick Preset Creation
+
+Create a new preset file in `config/presets/{name}.yaml`:
+
+```yaml
+---
+# My Team Preset - PostgreSQL + RSpec + Vite
+
+questions:
+  - id: database
+    choices:
+      - name: PostgreSQL
+        value: postgresql
+        default: true
+
+  - id: javascript
+    choices:
+      - name: Vite (via vite_rails gem)
+        value: vite
+        default: true
+
+  - id: test_framework
+    choices:
+      - name: RSpec
+        value: rspec
+        default: true
+
+post_actions:
+  - id: setup_vite
+    enabled: true
+
+  - id: setup_rspec
+    enabled: true
+```
+
+Then use it:
+
+```bash
+railstart new myapp --preset my-team
+```
+
+### Built-in Presets
+
+Railstart includes several ready-to-use presets:
+
+- **`default`** - PostgreSQL + Tailwind + Importmap (sensible defaults)
+- **`api-only`** - Minimal Rails for JSON APIs (no views, no frontend)
+- **`vite-bun`** - Modern SPA with Vite + Bundlebun
+
+### Learn More
+
+For detailed documentation including:
+- Available questions and post-actions
+- ID-based merging system
+- Step-by-step workflow
+- Real-world examples
+- Best practices and troubleshooting
+
+See the comprehensive **[Creating Presets Guide](docs/railstart-preset-builder/SKILL.md)**.
+
 ## Configuration
 
 ### Initialize Configuration Files
@@ -245,6 +309,28 @@ post_actions:
       equals: value                 # or includes: [array, values]
 ```
 
+#### Template Post-Actions
+
+Post-actions can now execute full Rails application templates (including [RailsBytes scripts](https://railsbytes.com)) instead of plain shell commands.
+
+```yaml
+post_actions:
+  - id: apply_tailwind_dash
+    name: "Apply Tailwind dashboard template"
+    type: template
+    enabled: false             # keep disabled unless you trust the source
+    prompt: "Run the sample template?"
+    source: "https://railsbytes.com/script/zAasQK"
+    variables:
+      app_label: "internal-tools"  # optional instance variables available inside template
+```
+
+Key differences from `command` actions:
+
+- Set `type: template` and provide a `source` (local path or URL). Railstart streams that template into Rails' own `apply` helper, so all standard DSL commands (`gem`, `route`, `after_bundle`, etc.) are available.
+- `variables` is optional; when present, its keys become instance variables accessible from the template (e.g., `@app_label`). Railstart always exposes `@app_name` and `@answers` for convenience.
+- Template actions still honor `prompt`, `default`, and `if` just like command actions. Keep remote templates disabled by default unless you explicitly trust them.
+
 ## Development
 
 ### Setup

data/config/presets/vite-bun.yaml

@@ -0,0 +1,59 @@
+---
+# Vite + Bundlebun Preset - Modern frontend with Vite and Bun packaged as a gem
+# This preset configures Rails with Vite for fast HMR and Bundlebun for unified JavaScript runtime
+
+questions:
+  - id: database
+    choices:
+      - name: PostgreSQL
+        value: postgresql
+        default: true
+
+  - id: css
+    choices:
+      - name: Tailwind
+        value: tailwind
+        default: true
+
+  - id: javascript
+    choices:
+      - name: Vite (via vite_rails gem)
+        value: vite
+        default: true
+
+  - id: test_framework
+    choices:
+      - name: Minitest (default)
+        value: minitest
+        default: true
+
+  - id: skip_features
+    default: []
+
+  - id: api_only
+    default: false
+
+  - id: skip_git
+    default: true
+
+  - id: skip_docker
+    default: false
+
+  - id: skip_bundle
+    default: false
+
+post_actions:
+  - id: setup_vite
+    name: "Setup Vite Rails"
+    enabled: true
+    command: "bundle add vite_rails && bundle install && bundle exec vite install"
+
+  - id: setup_bundlebun
+    name: "Setup Bundlebun (Bun packaged as a gem)"
+    enabled: true
+    command: "bundle add bundlebun && bundle install && bundle exec rake bun:install"
+
+  - id: init_git
+    name: "Initialize git repository"
+    enabled: true
+    command: "git init && git add . && git commit -m 'Initial commit with Vite + Bundlebun'"

data/config/rails8_defaults.yaml

@@ -30,24 +30,35 @@ questions:
         value: bulma
       - name: PostCSS (no framework)
         value: postcss
-      - name: None
+      - name: Sass
+        value: sass
+      - name: None (skip CSS setup)
         value: none
     rails_flag: "--css=%{value}"
 
   - id: javascript
     type: select
-    prompt: "Which JavaScript bundler?"
+    prompt: "Which JavaScript approach?"
     choices:
       - name: Importmap (default)
         value: importmap
         default: true
+        rails_flag: "--javascript=importmap"
+      - name: Bun
+        value: bun
+        rails_flag: "--javascript=bun"
       - name: esbuild
         value: esbuild
-      - name: Webpack
-        value: webpack
+        rails_flag: "--javascript=esbuild"
       - name: Rollup
         value: rollup
-    rails_flag: "--javascript=%{value}"
+        rails_flag: "--javascript=rollup"
+      - name: Webpack
+        value: webpack
+        rails_flag: "--javascript=webpack"
+      - name: None (skip JavaScript)
+        value: none
+        rails_flag: "--skip-javascript"
 
   - id: skip_features
     type: multi_select
@@ -102,6 +113,17 @@ questions:
     default: false
     rails_flag: "--skip-bundle"
 
+  - id: test_framework
+    type: select
+    prompt: "Which test framework?"
+    choices:
+      - name: Minitest (default)
+        value: minitest
+        default: true
+      - name: RSpec
+        value: rspec
+        rails_flag: "--skip-test"
+
 post_actions:
   - id: init_git
     name: "Initialize git repository"
@@ -122,3 +144,11 @@ post_actions:
       question: skip_bundle
       equals: true
     command: "bundle install"
+
+  - id: setup_rspec
+    name: "Setup RSpec"
+    enabled: true
+    if:
+      question: test_framework
+      equals: rspec
+    command: "bundle add rspec-rails --group development,test && bundle exec rails generate rspec:install"

data/lib/railstart/cli.rb

@@ -237,6 +237,10 @@ module Railstart
     end
 
     def preset_file_for(name)
+      if (direct_path = explicit_preset_path(name))
+        return direct_path
+      end
+
       # Check user presets first
       user_path = File.join(PRESET_DIR, "#{name}.yaml")
       return user_path if File.exist?(user_path)
@@ -319,5 +323,14 @@ module Railstart
             enabled: true
       YAML
     end
+
+    def explicit_preset_path(name)
+      return unless name&.match?(/\.ya?ml\z/)
+
+      expanded = File.expand_path(name)
+      return expanded if File.exist?(expanded)
+
+      raise Railstart::ConfigLoadError, "Preset file '#{name}' not found"
+    end
   end
 end

data/lib/railstart/command_builder.rb

@@ -42,13 +42,29 @@ module Railstart
 
       def process_question_flags(flags, question, answer)
         case question["type"]
-        when "select", "yes_no", "input"
+        when "select"
+          process_select(flags, question, answer)
+        when "yes_no", "input"
           add_flags(flags, question, answer)
         when "multi_select"
           process_multi_select(flags, question, answer)
         end
       end
 
+      def process_select(flags, question, answer)
+        # Check if the selected choice has a choice-level rails_flag
+        selected_choice = Array(question["choices"]).find { |choice| choice["value"] == answer }
+
+        if selected_choice && (selected_choice["rails_flag"] || selected_choice["rails_flags"])
+          # Use choice-level flag
+          add_flags(flags, selected_choice, answer)
+        elsif question["rails_flag"] || question["rails_flags"]
+          # Fall back to question-level flag
+          add_flags(flags, question, answer)
+        end
+        # If neither exists, no flag is added (e.g., for choices that don't need flags)
+      end
+
       def process_multi_select(flags, question, answer)
         Array(question["choices"]).each do |choice|
           next unless Array(answer).include?(choice["value"])

data/lib/railstart/config.rb

@@ -197,12 +197,7 @@ module Railstart
 
             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
+            issues.concat(validate_post_action_entry(entry, id || index)) if entry.fetch("enabled", true)
 
             if_condition = entry["if"] || entry[:if]
             if if_condition.is_a?(Hash)
@@ -246,6 +241,32 @@ module Railstart
         issues
       end
 
+      def validate_post_action_entry(entry, identifier)
+        action_type = (entry["type"] || entry[:type] || "command").to_s
+
+        case action_type
+        when "command"
+          command = entry["command"] || entry[:command]
+          if command.nil? || command.to_s.strip.empty?
+            ["Post-action #{identifier} is enabled but missing a command"]
+          else
+            []
+          end
+        when "template"
+          issues = []
+          source = entry["source"] || entry[:source]
+          if source.nil? || source.to_s.strip.empty?
+            issues << "Post-action #{identifier} is a template but missing a source"
+          end
+
+          variables = entry["variables"] || entry[:variables]
+          issues << "Post-action #{identifier} template variables must be a Hash" if variables && !variables.is_a?(Hash)
+          issues
+        else
+          ["Post-action #{identifier} has unsupported type '#{action_type}'"]
+        end
+      end
+
       def deep_dup(value)
         case value
         when Hash

data/lib/railstart/errors.rb

@@ -25,4 +25,7 @@ module Railstart
       super(detail)
     end
   end
+
+  # Raised when applying Rails templates fails.
+  class TemplateError < Error; end
 end

data/lib/railstart/generator.rb

@@ -2,6 +2,7 @@
 
 require "tty-prompt"
 require_relative "ui"
+require_relative "template_runner"
 
 module Railstart
   # Orchestrates the interactive Rails app generation flow.
@@ -221,20 +222,30 @@ module Railstart
     end
 
     def run_post_actions
-      Dir.chdir(@app_name)
+      Dir.chdir(@app_name) do
+        template_runner = nil
 
-      Array(@config["post_actions"]).each { |action| process_post_action(action) }
-      puts
-      UI.success("Rails app created successfully at ./#{@app_name}")
+        Array(@config["post_actions"]).each do |action|
+          template_runner ||= TemplateRunner.new(app_path: Dir.pwd) if template_action?(action)
+          process_post_action(action, template_runner)
+        end
+
+        puts
+        UI.success("Rails app created successfully at ./#{@app_name}")
+      end
     rescue Errno::ENOENT
       UI.warning("Could not change to app directory. Post-actions skipped.")
     end
 
-    def process_post_action(action)
+    def process_post_action(action, template_runner)
       return unless should_run_action?(action)
       return unless confirm_action?(action)
 
-      execute_action(action)
+      if template_action?(action)
+        run_template_action(action, template_runner)
+      else
+        run_command_action(action)
+      end
     end
 
     def confirm_action?(action)
@@ -243,12 +254,33 @@ module Railstart
       @prompt.yes?(action["prompt"], default: action.fetch("default", true))
     end
 
-    def execute_action(action)
+    def run_command_action(action)
       UI.info(action["name"].to_s)
       success = system(action["command"])
       UI.warning("Post-action '#{action["name"]}' failed. Continuing anyway.") unless success
     end
 
+    def run_template_action(action, template_runner)
+      return unless template_runner
+
+      UI.info(action["name"].to_s)
+      source = action["source"]
+      variables = template_variables(action)
+      template_runner.apply(source, variables: variables)
+    rescue TemplateError => e
+      UI.warning("Post-action '#{action["name"]}' failed. #{e.message}")
+    end
+
+    def template_variables(action)
+      base = { app_name: @app_name, answers: @answers }
+      extras = action["variables"].is_a?(Hash) ? action["variables"].transform_keys(&:to_sym) : {}
+      base.merge(extras)
+    end
+
+    def template_action?(action)
+      action["type"].to_s == "template"
+    end
+
     def should_run_action?(action)
       return false unless action.fetch("enabled", true)
 

data/lib/railstart/template_runner.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "errors"
+
+module Railstart
+  # Executes Rails application templates (including RailsBytes scripts)
+  # inside a generated application directory.
+  #
+  # Wraps Rails' own AppGenerator so existing template DSL helpers such as
+  # `gem`, `initializer`, `route`, etc. are available without reimplementing
+  # them in Railstart.
+  class TemplateRunner
+    # @param app_path [String] absolute path to the Rails application
+    # @param generator_factory [#call] optional factory for injecting a
+    #   generator (mainly used in tests)
+    # @param shell [Thor::Shell] Thor shell instance for output
+    def initialize(app_path:, generator_factory: nil, shell: Thor::Base.shell.new)
+      @app_path = app_path
+      @shell = shell
+      @generator_factory = generator_factory
+    end
+
+    # Apply a Rails template located at +source+.
+    #
+    # @param source [String] file path or URL
+    # @param variables [Hash] instance variables injected into the template
+    # @return [void]
+    # @raise [Railstart::TemplateError] when Rails cannot be loaded or
+    #   template execution fails
+    def apply(source, variables: {})
+      raise TemplateError, "Template source must be provided" if source.to_s.strip.empty?
+
+      generator = build_generator
+      assign_variables(generator, variables)
+      generator.apply(source)
+    rescue TemplateError
+      raise
+    rescue LoadError => e
+      raise TemplateError, "Rails must be installed to run template post-actions: #{e.message}"
+    rescue StandardError => e
+      raise TemplateError, "Failed to apply template #{source}: #{e.message}"
+    end
+
+    private
+
+    def assign_variables(generator, variables)
+      Array(variables).each do |key, value|
+        generator.instance_variable_set(:"@#{key}", value)
+      end
+    end
+
+    def build_generator
+      generator = generator_factory.call(@app_path)
+      if generator.respond_to?(:destination_root=)
+        generator.destination_root = @app_path
+      elsif generator.respond_to?(:destination_root)
+        generator.instance_variable_set(:@destination_root, @app_path)
+      end
+      generator
+    end
+
+    def generator_factory
+      @generator_factory ||= default_generator_factory
+    end
+
+    def default_generator_factory
+      require "rails/generators"
+      require "rails/generators/rails/app/app_generator"
+
+      shell = @shell
+      lambda do |_app_path|
+        Rails::Generators::AppGenerator.new([], {}, shell: shell)
+      end
+    end
+  end
+end

data/lib/railstart/version.rb

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

data/lib/railstart.rb

@@ -5,6 +5,7 @@ require_relative "railstart/errors"
 require_relative "railstart/config"
 require_relative "railstart/command_builder"
 require_relative "railstart/generator"
+require_relative "railstart/template_runner"
 require_relative "railstart/cli"
 
 # Main namespace for the Railstart gem.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railstart
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - dpaluy
@@ -69,6 +69,7 @@ files:
 - Rakefile
 - config/presets/api-only.yaml
 - config/presets/default.yaml
+- config/presets/vite-bun.yaml
 - config/rails8_defaults.yaml
 - exe/railstart
 - lib/railstart.rb
@@ -77,6 +78,7 @@ files:
 - lib/railstart/config.rb
 - lib/railstart/errors.rb
 - lib/railstart/generator.rb
+- lib/railstart/template_runner.rb
 - lib/railstart/ui.rb
 - lib/railstart/version.rb
 homepage: https://github.com/dpaluy/railstart