railstart 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 502fb0b7fcebbc0983a28f858979bac1d540106adb74dd8de4324115cef97de7
-  data.tar.gz: 18501279259afc8e1636ab8b5687c0c8d1fbc79f4b4c5159c9675c05b035c74c
+  metadata.gz: 43c88184e8a592416bb521ca50fcccecbe331caf46851218cd1edd31e6134827
+  data.tar.gz: 3f6084258ec5d559ef064c75ebb4937208a0e56373427a6983c883bbfae1ff74
 SHA512:
-  metadata.gz: e0aff7a354d36a1b99881895bd1e37b429ba059f16d55a628b8c227c1d5c1437add24e6c08b778827cc3769399cbe174bc5fe1af3e0149a4895050f539b7d561
-  data.tar.gz: 576ea5f508618c3b10a5dc09727e061c27f3669d50bbd12bf201d510f830d75de0182e1fdac7f5bb6ebc6b7765dd1a10bab21dc59fe5a331a2e10a8f2f7fdc68
+  metadata.gz: f4fa31d2a8ab8f838a8c269f0c952b997c857b296567c291c70b7647f92780ec1cae26ecbfd8a04121d882e565e479761a829b4ba6e6f076dafe3d4551e352ad
+  data.tar.gz: 2485f48632b2a43d415ef717d111ee87cc48da6e3b9a23c7b6c04ea9c9e5b08cc7bbdfd1bf3915b8427c56b239ddf3d9b4849cbc00efbe548d8564f491b0c888

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-03
+
+### Added
+- `railstart new --yes` (`-y`) fully headless mode that implies defaults, never prompts, requires `APP_NAME`, and uses post-action `default` values for prompted actions.
+- **File post-actions**: New `type: file` post-action that writes a file into the generated app from inline `content` or a `source` template (relative sources resolve against `config/templates/`), with `%{app_name}` interpolation, path traversal protection, and skip-on-existing `overwrite` semantics.
+- **Shipped templates**: New `config/templates/AGENTS.md` (opinionated Rails 8 guide for coding agents, written by the enabled `write_agents_md` action) and `config/templates/bin/ci` (curated CI script behind the opt-in `setup_bin_ci` action).
+
 ## [0.5.1] - 2026-07-26
 
 ### Changed

data/README.md

@@ -94,7 +94,8 @@ Presets are configuration overlays that let you define different defaults and ev
 **Modes:**
 - **Interactive** (default): prompts for each question from the config schema
 - **With --default**: skips questions, loads "default" preset, shows summary and confirms
-- **With --preset**: loads specified preset as config overlay (can be interactive or with --default)
+- **With --yes / -y**: fully headless, implies `--default`, requires `APP_NAME`, skips all confirmations (post-action prompts follow each action's `default`)
+- **With --preset**: loads specified preset as config overlay (can be interactive or with --default/--yes)
 
 ```bash
 # Interactive mode (builtin defaults)
@@ -104,11 +105,14 @@ railstart new my_app
 # Note: --default automatically loads the "default" preset (user or gem)
 railstart new my_app --default
 
+# Fully headless mode (implies --default, no prompts at all)
+railstart new my_app --yes
+
 # Interactive with custom preset
 railstart new my_app --preset api-only
 
-# Non-interactive with custom preset
-railstart new my_app --preset api-only --default
+# Fully headless with custom preset
+railstart new my_app --preset api-only --yes
 ```
 
 **Create custom presets** at `~/.config/railstart/presets/my-preset.yaml`:
@@ -348,6 +352,33 @@ Key differences from `command` actions:
 - `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.
 
+#### File Post-Actions
+
+For lightweight files (AGENTS.md, scripts, dotfiles) you can skip Rails templates entirely and write a file directly into the generated app. File actions never load Rails in-process.
+
+```yaml
+post_actions:
+  - id: write_agents_md
+    name: "Create AGENTS.md for coding agents"
+    type: file
+    enabled: true
+    prompt: "Create AGENTS.md for coding agents?"
+    default: true
+    path: AGENTS.md              # required, relative to the app root
+    source: AGENTS.md            # template file (or use `content:` for an inline string)
+    overwrite: false             # optional; skip instead of overwriting existing files
+```
+
+Key differences from `template` actions:
+
+- `path` is required and must stay inside the app (absolute, `~`-prefixed, and `..` paths are rejected).
+- Provide exactly one of `content` (inline string) or `source` (file path). Relative `source` paths resolve against the gem's `config/templates/` directory; absolute or `~/` paths are used as-is.
+- Content supports `%{app_name}` interpolation, like `%{value}` in `rails_flag`. Other `%` sequences pass through unchanged.
+- `overwrite` defaults to `false`: existing files are skipped with a warning. Source-based writes keep the source file's executable bit.
+- `prompt`, `default`, and `if` behave exactly like command actions.
+
+The built-in config ships two file actions: `write_agents_md` (enabled by default, writes an opinionated AGENTS.md for coding agents) and `setup_bin_ci` (opt-in; Rails 8.1+ already generates `bin/ci`).
+
 ## Development
 
 ### Setup

data/config/rails8_defaults.yaml

@@ -126,6 +126,29 @@ questions:
         rails_flag: "--skip-test"
 
 post_actions:
+  - id: write_agents_md
+    name: "Create AGENTS.md for coding agents"
+    type: file
+    enabled: true
+    prompt: "Create AGENTS.md for coding agents?"
+    default: true
+    path: AGENTS.md
+    source: AGENTS.md
+    overwrite: false
+
+  # Opt-in: Rails 8.1+ already generates bin/ci, so this action stays
+  # disabled by default and never overwrites an existing script. Enable it
+  # to have Railstart write a curated CI script (keeps its executable bit).
+  - id: setup_bin_ci
+    name: "Create bin/ci script"
+    type: file
+    enabled: false
+    prompt: "Create bin/ci script?"
+    default: false
+    path: bin/ci
+    source: bin/ci
+    overwrite: false
+
   - id: init_git
     name: "Initialize git repository"
     enabled: true

data/config/templates/AGENTS.md

@@ -0,0 +1,30 @@
+# %{app_name}: Agent Guide
+
+Guidance for AI coding agents working in this Rails 8 application.
+
+## Setup
+
+```bash
+bin/setup
+```
+
+## Everyday Commands
+
+- Run the test suite: `bin/rails test` (system tests: `bin/rails test:system`)
+- Run a single test file: `bin/rails test test/models/user_test.rb`
+- Lint: `bundle exec rubocop`
+- Security scan: `bin/brakeman` (when the gem is installed)
+- Console: `bin/rails console`
+
+## Conventions
+
+- Follow standard Ruby and Rails style; keep the existing code style consistent.
+- Use `bin/rails generate` for new models, controllers, and migrations instead of hand-writing boilerplate.
+- Keep controllers thin; put business logic in models or plain service objects.
+- Write tests for new behavior; prefer fixtures and plain assertions over heavy mocking.
+
+## Before Committing
+
+1. `bin/rails test` passes.
+2. `bundle exec rubocop` reports no offenses.
+3. New or changed behavior is covered by tests.

data/config/templates/bin/ci

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# bin/ci — curated CI script written by Railstart.
+# Rails 8.1+ generates its own bin/ci; enable the setup_bin_ci post-action
+# only when the generated app does not already ship one.
+set -euo pipefail
+
+echo "== Running RuboCop =="
+bundle exec rubocop
+
+if bundle exec brakeman --version >/dev/null 2>&1; then
+  echo "== Running Brakeman =="
+  bundle exec brakeman --quiet --no-pager
+fi
+
+echo "== Running tests =="
+bin/rails test

data/lib/railstart/cli.rb

@@ -32,6 +32,7 @@ module Railstart
         puts "  railstart init                      # Create config files (optional)"
         puts "  railstart new my_app                # Interactive mode"
         puts "  railstart new my_app --default      # Use defaults"
+        puts "  railstart new my_app --yes          # Fully headless"
         puts "  railstart new my_app --preset api-only  # Use preset"
         puts ""
         puts "Run 'railstart help init' or 'railstart help new' for details"
@@ -122,17 +123,20 @@ module Railstart
 
       Modes:
         - Interactive (default): prompts for each question
+        - With default mode (--default or --yes): uses config defaults
         - With preset: uses preset config (different questions/defaults), interactive or non-interactive
 
       Examples:
         railstart new my_app                          # Interactive mode
-        railstart new my_app --default                # Non-interactive with default preset (if exists)
+        railstart new my_app --default                # Non-interactive with default preset (if exists), still confirms
+        railstart new my_app --yes                    # Fully headless (no prompts, requires APP_NAME)
         railstart new my_app --preset api-only        # Interactive with api-only preset config
-        railstart new my_app --preset api-only --default  # Non-interactive with api-only preset
+        railstart new my_app --preset api-only --yes  # Fully headless with api-only preset
 
       Presets are stored in: ~/.config/railstart/presets/*.yaml
     DESC
     option :default, type: :boolean, default: false, desc: "Use defaults non-interactively"
+    option :yes, type: :boolean, aliases: "-y", default: false, desc: "Headless mode: implies --default; no prompts"
     option :preset, type: :string, desc: "Preset name from ~/.config/railstart/presets/", banner: "NAME"
     #
     # @param app_name [String, nil] desired Rails app name, prompted if omitted
@@ -144,6 +148,8 @@ module Railstart
     #   Railstart::CLI.start(%w[new my_app --preset api-only])
     # @example Use default preset non-interactively
     #   Railstart::CLI.start(%w[new my_app --default])
+    # @example Run fully headless
+    #   Railstart::CLI.start(%w[new my_app --yes])
     def new(app_name = nil)
       preset_name = determine_preset_name
       preset_path = preset_name ? preset_file_for(preset_name) : nil
@@ -153,7 +159,8 @@ module Railstart
       generator = Generator.new(
         app_name,
         config: config,
-        use_defaults: options[:default]
+        use_defaults: options[:default] || options[:yes],
+        assume_yes: options[:yes]
       )
 
       generator.run
@@ -230,8 +237,8 @@ module Railstart
       # Explicit --preset flag takes priority
       return options[:preset] if options[:preset]
 
-      # --default maps to "default" preset
-      return "default" if options[:default]
+      # --default and --yes map to "default" preset
+      return "default" if options[:default] || options[:yes]
 
       nil
     end

data/lib/railstart/config.rb

@@ -157,7 +157,7 @@ module Railstart
       end
 
       def fetch_id(entry)
-        return unless entry.respond_to?(:[])
+        return unless entry.is_a?(Hash)
 
         entry["id"] || entry[:id]
       end
@@ -406,11 +406,38 @@ module Railstart
             end
           end
           issues
+        when "file"
+          validate_file_action(entry, identifier, enabled)
         else
           ["Post-action #{identifier} has unsupported type '#{action_type}'"]
         end
       end
 
+      def validate_file_action(entry, identifier, enabled)
+        issues = []
+        path = value_for(entry, "path")
+        if enabled && (path.nil? || path.to_s.strip.empty?)
+          issues << "Post-action #{identifier} is a file but missing a path"
+        elsif path && !path.to_s.strip.empty? && unsafe_file_path?(path.to_s)
+          issues << "Post-action #{identifier} has unsafe file path #{path.inspect}"
+        end
+
+        if enabled
+          has_content = key_present?(entry, "content") && !value_for(entry, "content").nil?
+          has_source = !value_for(entry, "source").to_s.strip.empty?
+          if has_content && has_source
+            issues << "Post-action #{identifier} is a file but defines both content and source"
+          elsif !has_content && !has_source
+            issues << "Post-action #{identifier} is a file but missing content or source"
+          end
+        end
+        issues
+      end
+
+      def unsafe_file_path?(path)
+        path.start_with?("/", "~") || path.match?(%r{\A[A-Za-z]:[\\/]}) || path.split(%r{[/\\]+}).include?("..")
+      end
+
       def validate_post_action_condition(entry, identifier, question_ids)
         return [] unless key_present?(entry, "if")
 

data/lib/railstart/file_writer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require_relative "errors"
+
+module Railstart
+  # Writes lightweight files into a generated application directory.
+  #
+  # Backs `type: file` post-actions, providing a way to ship small files
+  # (AGENTS.md, scripts, dotfiles) without loading Rails in-process like
+  # template post-actions do.
+  #
+  # @example Write a file from inline content
+  #   writer = Railstart::FileWriter.new(app_path: Dir.pwd, app_name: "blog")
+  #   writer.write(path: "AGENTS.md", content: "# %{app_name}")
+  class FileWriter
+    # Directory inside the gem where relative `source` paths resolve.
+    TEMPLATES_DIR = File.expand_path("../../config/templates", __dir__)
+
+    #
+    # @param app_path [String] absolute path to the generated application
+    # @param app_name [String] application name used for `%{app_name}` interpolation
+    def initialize(app_path:, app_name:)
+      @app_path = app_path
+      @app_name = app_name
+    end
+
+    #
+    # Write a file into the application directory.
+    #
+    # @param path [String] target path relative to the application root
+    # @param content [String, nil] inline file content (mutually exclusive with `source`)
+    # @param source [String, nil] template file path; relative paths resolve
+    #   against the gem's config/templates directory, absolute or ~/ paths are used as-is
+    # @param overwrite [Boolean] replace an existing file when true
+    # @return [Symbol] :written when the file was written, :skipped when it
+    #   already existed and `overwrite` is false
+    # @raise [Railstart::Error] when the target path escapes the app, the
+    #   source escapes config/templates, or the source file cannot be read
+    def write(path:, content: nil, source: nil, overwrite: false)
+      source = nil if source.to_s.strip.empty?
+      target = safe_target(path)
+      if File.symlink?(target)
+        raise Error, "Unsafe file post-action path #{path.inspect}: refusing to write through a symlink"
+      end
+      return :skipped if File.exist?(target) && !overwrite
+
+      source_path = resolve_source(source) if source
+      body = interpolate(source_path ? read_source(source_path) : content.to_s)
+      ensure_resolved_within_app!(target, path)
+      FileUtils.mkdir_p(File.dirname(target))
+      File.write(target, body)
+      FileUtils.chmod(File.stat(source_path).mode & 0o777, target) if source_path
+      :written
+    end
+
+    private
+
+    def safe_target(path)
+      root = File.expand_path(@app_path)
+      target = File.expand_path(path.to_s, root)
+      return target if target.start_with?("#{root}#{File::SEPARATOR}")
+
+      raise Error, "Unsafe file post-action path #{path.inspect}: must stay inside the app directory"
+    end
+
+    # Lexical checks cannot see directory symlinks inside the app. Resolve the
+    # nearest existing ancestor BEFORE mkdir_p so a symlinked directory can
+    # neither receive the write nor absorb the created directories outside
+    # the app.
+    def ensure_resolved_within_app!(target, path)
+      root = File.realpath(@app_path)
+      resolved = File.realpath(nearest_existing_ancestor(target))
+      return if resolved == root || resolved.start_with?("#{root}#{File::SEPARATOR}")
+
+      raise Error, "Unsafe file post-action path #{path.inspect}: resolves outside the app directory"
+    end
+
+    def nearest_existing_ancestor(target)
+      dir = File.dirname(target)
+      dir = File.dirname(dir) until File.exist?(dir) || File.dirname(dir) == dir
+      dir
+    end
+
+    def resolve_source(source)
+      raw = source.to_s
+      expanded = raw.start_with?("~") ? File.expand_path(raw) : raw
+      return expanded if Pathname.new(expanded).absolute?
+
+      resolved = File.expand_path(expanded, TEMPLATES_DIR)
+      return resolved if resolved.start_with?("#{TEMPLATES_DIR}#{File::SEPARATOR}")
+
+      raise Error, "Unsafe file post-action source #{source.inspect}: must stay inside #{TEMPLATES_DIR}"
+    end
+
+    def read_source(source_path)
+      File.read(source_path)
+    rescue SystemCallError => e
+      raise Error, "Cannot read file post-action source #{source_path}: #{e.message}"
+    end
+
+    # Replaces only the documented `%{app_name}` token so literal `%`
+    # characters in file content (printf, percentages) pass through unchanged.
+    def interpolate(body)
+      # rubocop:disable-next Style/FormatStringToken -- `%{token}` is the documented interpolation style
+      body.gsub("%{app_name}", @app_name.to_s)
+    end
+  end
+end

data/lib/railstart/generator.rb

@@ -2,13 +2,15 @@
 
 require "tty-prompt"
 require_relative "ui"
-require_relative "template_runner"
+require_relative "question_asker"
+require_relative "post_action_runner"
 
 module Railstart
-  # Orchestrates the interactive Rails app generation flow.
+  # Orchestrates the Rails app generation flow: welcome screen, app name,
+  # questions, summary, `rails new`, and post-actions.
   #
-  # Handles configuration loading, prompting, summary display, command execution,
-  # and optional post-generation actions while remaining easy to test.
+  # Question answering lives in QuestionAsker, post-action execution in
+  # PostActionRunner; this class only sequences the steps.
   #
   # @example Run generator with provided config
   #   config = Railstart::Config.load
@@ -23,11 +25,13 @@ module Railstart
     # @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 questions, use config defaults
+    # @param assume_yes [Boolean] fully headless mode, implies defaults and bypasses confirmations
     # @param prompt [TTY::Prompt] injectable prompt for testing
-    def initialize(app_name = nil, config: nil, use_defaults: false, prompt: nil)
+    def initialize(app_name = nil, config: nil, use_defaults: false, assume_yes: false, prompt: nil)
       @app_name = app_name
       @config = config || Config.load
-      @use_defaults = use_defaults
+      @assume_yes = assume_yes
+      @use_defaults = use_defaults || @assume_yes
       @prompt = prompt || TTY::Prompt.new
       @answers = {}
     end
@@ -48,14 +52,8 @@ module Railstart
     def run
       show_welcome_screen unless @use_defaults
 
-      ask_app_name unless @app_name
-      validate_app_name!
-
-      if @use_defaults
-        collect_defaults
-      else
-        ask_interactive_questions
-      end
+      resolve_app_name
+      @answers = collect_answers
 
       show_summary
       return unless confirm_proceed?
@@ -71,6 +69,15 @@ module Railstart
       UI.show_welcome
     end
 
+    def resolve_app_name
+      if @app_name.nil?
+        raise Error, "APP_NAME is required when running in --yes mode" if @assume_yes
+
+        ask_app_name
+      end
+      validate_app_name!
+    end
+
     def ask_app_name
       @app_name = @prompt.ask("App name?", default: "my_app") do |q|
         q.validate(APP_NAME_PATTERN, APP_NAME_ERROR)
@@ -83,91 +90,9 @@ module Railstart
       raise Error, "Invalid app name '#{@app_name}': #{APP_NAME_ERROR}"
     end
 
-    def collect_defaults
-      Array(@config["questions"]).each do |question|
-        next if should_skip_question?(question)
-
-        question_id = question["id"]
-        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)
-      # Convert to hash format: { 'Display Name' => 'value' }
-      choices = question["choices"].to_h { |choice| [choice["name"], choice["value"]] }
-      default_val = find_default(question)
-
-      # TTY::Prompt expects 1-based index for default
-      default_index = (question["choices"].index { |c| c["value"] == default_val }&.+(1) if default_val)
-
-      @prompt.select(question["prompt"], choices, default: default_index)
-    end
-
-    def ask_multi_select(question)
-      # Convert to hash format: { 'Display Name' => 'value' }
-      choices = question["choices"].to_h { |choice| [choice["name"], choice["value"]] }
-
-      # Transform value-based defaults to name-based defaults for TTY::Prompt
-      # Config uses stable values (e.g., "action_mailer"), TTY::Prompt needs display names
-      value_defaults = question["default"] || []
-      name_defaults = value_defaults.map do |value|
-        choice = question["choices"].find { |c| c["value"] == value }
-        choice ? choice["name"] : nil
-      end.compact
-
-      @prompt.multi_select(question["prompt"], choices, default: name_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")
+    def collect_answers
+      asker = QuestionAsker.new(questions: @config["questions"], prompt: @prompt)
+      @use_defaults ? asker.collect_defaults : asker.ask_all
     end
 
     def show_summary
@@ -212,9 +137,17 @@ module Railstart
     end
 
     def confirm_proceed?
+      return true if @assume_yes
+
       @prompt.yes?("Proceed with app generation?")
     end
 
+    def confirm_action?(action)
+      return action.fetch("default", true) if @assume_yes
+
+      @prompt.yes?(action["prompt"], default: action.fetch("default", true))
+    end
+
     def generate_app
       arguments = CommandBuilder.arguments(@app_name, @config, @answers)
       command = CommandBuilder.build(@app_name, @config, @answers)
@@ -237,12 +170,13 @@ module Railstart
 
     def run_post_actions
       Dir.chdir(@app_name) do
-        template_runner = nil
-
-        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
+        PostActionRunner.new(
+          actions: @config["post_actions"],
+          answers: @answers,
+          app_name: @app_name,
+          confirmer: ->(action) { confirm_action?(action) },
+          command_runner: ->(command) { system(command) }
+        ).run
 
         puts
         UI.success("Rails app created successfully at ./#{@app_name}")
@@ -250,69 +184,5 @@ module Railstart
     rescue Errno::ENOENT
       UI.warning("Could not change to app directory. Post-actions skipped.")
     end
-
-    def process_post_action(action, template_runner)
-      return unless should_run_action?(action)
-      return unless confirm_action?(action)
-
-      if template_action?(action)
-        run_template_action(action, template_runner)
-      else
-        run_command_action(action)
-      end
-    end
-
-    def confirm_action?(action)
-      return true unless action["prompt"]
-
-      @prompt.yes?(action["prompt"], default: action.fetch("default", true))
-    end
-
-    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)
-
-      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/post_action_runner.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "file_writer"
+require_relative "template_runner"
+
+module Railstart
+  # Executes post-generation actions (commands, Rails templates, file writes)
+  # inside a generated application directory.
+  #
+  # @example Run enabled actions for a generated app
+  #   Railstart::PostActionRunner.new(
+  #     actions: config["post_actions"], answers: answers,
+  #     app_name: "blog", prompt: prompt, assume_yes: false
+  #   ).run
+  class PostActionRunner
+    #
+    # @param actions [Array<Hash>] post_action entries from the merged config
+    # @param answers [Hash] question answers used by action conditions
+    # @param app_name [String] application name for file interpolation and template variables
+    # @param confirmer [#call] decides whether a prompted action runs, given the action
+    # @param command_runner [#call, nil] executes shell commands; injectable for testing
+    def initialize(actions:, answers:, app_name:, confirmer:, command_runner: nil)
+      @actions = Array(actions)
+      @answers = answers
+      @app_name = app_name
+      @confirmer = confirmer
+      @command_runner = command_runner || ->(command) { system(command) }
+    end
+
+    #
+    # Run every enabled action whose condition passes. The current working
+    # directory must be the generated app root.
+    #
+    # @return [void]
+    def run
+      template_runner = nil
+
+      @actions.each do |action|
+        template_runner ||= TemplateRunner.new(app_path: Dir.pwd) if template_action?(action)
+        process(action, template_runner)
+      end
+    end
+
+    private
+
+    def process(action, template_runner)
+      return unless should_run?(action)
+      return unless confirm?(action)
+
+      if template_action?(action)
+        run_template(action, template_runner)
+      elsif file_action?(action)
+        run_file(action)
+      else
+        run_command(action)
+      end
+    end
+
+    def confirm?(action)
+      return true unless action["prompt"]
+
+      @confirmer.call(action)
+    end
+
+    def run_command(action)
+      UI.info(action["name"].to_s)
+      success = @command_runner.call(action["command"])
+      UI.warning("Post-action '#{action["name"]}' failed. Continuing anyway.") unless success
+    end
+
+    def run_template(action, template_runner)
+      return unless template_runner
+
+      UI.info(action["name"].to_s)
+      template_runner.apply(action["source"], variables: template_variables(action))
+    rescue TemplateError => e
+      UI.warning("Post-action '#{action["name"]}' failed. #{e.message}")
+    end
+
+    def run_file(action)
+      UI.info(action["name"].to_s)
+      writer = FileWriter.new(app_path: Dir.pwd, app_name: @app_name)
+      result = writer.write(
+        path: action["path"],
+        content: action["content"],
+        source: action["source"],
+        overwrite: action.fetch("overwrite", false)
+      )
+      if result == :skipped
+        UI.warning("Skipped '#{action["path"]}' (already exists)")
+      else
+        UI.success("Created #{action["path"]}")
+      end
+    rescue Error, SystemCallError => 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 file_action?(action)
+      action["type"].to_s == "file"
+    end
+
+    def should_run?(action)
+      return false unless action.fetch("enabled", true)
+
+      if_condition = action["if"]
+      return true unless if_condition
+
+      answer = @answers[if_condition["question"]]
+
+      if if_condition.key?("equals")
+        answer == if_condition["equals"]
+      elsif if_condition.key?("includes")
+        expected = Array(if_condition["includes"])
+        expected.intersect?(Array(answer))
+      else
+        true
+      end
+    end
+  end
+end

data/lib/railstart/question_asker.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Railstart
+  # Answers configuration questions, either by collecting their defaults
+  # (non-interactive) or by prompting the user via TTY::Prompt.
+  #
+  # @example Collect defaults without prompting
+  #   Railstart::QuestionAsker.new(questions: config["questions"], prompt: prompt).collect_defaults
+  # @example Ask every question interactively
+  #   Railstart::QuestionAsker.new(questions: config["questions"], prompt: prompt).ask_all
+  class QuestionAsker
+    #
+    # @param questions [Array<Hash>] question entries from the merged config
+    # @param prompt [TTY::Prompt] prompt used for interactive questions
+    def initialize(questions:, prompt:)
+      @questions = Array(questions)
+      @prompt = prompt
+    end
+
+    #
+    # Build an answers hash from question defaults, skipping conditional
+    # questions whose dependency is not met.
+    #
+    # @return [Hash] question id => default value
+    def collect_defaults
+      answers = {}
+      @questions.each do |question|
+        next if skip_question?(question, answers)
+
+        default_value = find_default(question)
+        answers[question["id"]] = default_value unless default_value.nil?
+      end
+      answers
+    end
+
+    #
+    # Prompt for every question, respecting depends_on conditions.
+    #
+    # @return [Hash] question id => answer
+    def ask_all
+      answers = {}
+      @questions.each do |question|
+        next if skip_question?(question, answers)
+
+        answers[question["id"]] = ask_question(question)
+      end
+      answers
+    end
+
+    private
+
+    def skip_question?(question, answers)
+      depends = question["depends_on"]
+      return false unless depends
+
+      answers[depends["question"]] != depends["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)
+      # Convert to hash format: { 'Display Name' => 'value' }
+      choices = question["choices"].to_h { |choice| [choice["name"], choice["value"]] }
+      default_val = find_default(question)
+
+      # TTY::Prompt expects 1-based index for default
+      default_index = (question["choices"].index { |c| c["value"] == default_val }&.+(1) if default_val)
+
+      @prompt.select(question["prompt"], choices, default: default_index)
+    end
+
+    def ask_multi_select(question)
+      # Convert to hash format: { 'Display Name' => 'value' }
+      choices = question["choices"].to_h { |choice| [choice["name"], choice["value"]] }
+
+      # Transform value-based defaults to name-based defaults for TTY::Prompt
+      # Config uses stable values (e.g., "action_mailer"), TTY::Prompt needs display names
+      value_defaults = question["default"] || []
+      name_defaults = value_defaults.map do |value|
+        choice = question["choices"].find { |c| c["value"] == value }
+        choice ? choice["name"] : nil
+      end.compact
+
+      @prompt.multi_select(question["prompt"], choices, default: name_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
+  end
+end

data/lib/railstart/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railstart
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - dpaluy
@@ -71,13 +71,18 @@ files:
 - config/presets/default.yaml
 - config/presets/vite-bun.yaml
 - config/rails8_defaults.yaml
+- config/templates/AGENTS.md
+- config/templates/bin/ci
 - exe/railstart
 - lib/railstart.rb
 - lib/railstart/cli.rb
 - lib/railstart/command_builder.rb
 - lib/railstart/config.rb
 - lib/railstart/errors.rb
+- lib/railstart/file_writer.rb
 - lib/railstart/generator.rb
+- lib/railstart/post_action_runner.rb
+- lib/railstart/question_asker.rb
 - lib/railstart/template_runner.rb
 - lib/railstart/ui.rb
 - lib/railstart/version.rb