rails-worktrees 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46dd1369d93b3281d8182a90812164a1a245ff778b5af05306908989563e264e
-  data.tar.gz: 0d7e33ae49a56ea819e3a07ebfde966e1b1c18677af8c406bd15e93628ba8aff
+  metadata.gz: 698795e04a67284039d3beba2286f3a9aa156a5856832a345f22ffa57b6177e3
+  data.tar.gz: 0a57ef25c66c3226798498476abf8caf033c6a2989ae170b30a161fde66fddcf
 SHA512:
-  metadata.gz: 3d9e25b8d52ec84eb983d5b5ba28679394396232f61b8e9b626cf8a8f464b49e53d9f1898d0591bcd78e66620fa2b59869b1c781ed03b7a8a5f176f973a2ebbb
-  data.tar.gz: 795403173d6b6c8c375119b7427bebc620cc73deb9402a8c1c6aa25c863b703af882b4e4b01dd9bdbd123696f1949a1e00f830a92a227e93ddff3e09a1c763ee
+  metadata.gz: 06c8ae396186a19c08e45445e031a28198d48f7ea5125c02e63b2df39977f5399f75421e7f1897071d14b00d042051616ed4e447b83b570852d54756d8689377
+  data.tar.gz: 800a19ef60af420e03280b8a30c02c9012c4ded0d3eaecc421ed5e42e072b8024a0cbc93e7ba7aaf7d806dc972deacacbb0c5edfe45da40b2ab05659b1ccc5c5

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.4.0"}
+{".":"0.5.1"}

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.5.1](https://github.com/asjer/rails-worktrees/compare/v0.5.0...v0.5.1) (2026-04-02)
+
+
+### Bug Fixes
+
+* **initializer:** simplify generated config wiring ([bd7fd50](https://github.com/asjer/rails-worktrees/commit/bd7fd506f2c0106a0bd188e36b31329a9de2acbf))
+
+## [0.5.0](https://github.com/asjer/rails-worktrees/compare/v0.4.0...v0.5.0) (2026-04-02)
+
+
+### Features
+
+* **maintenance:** add doctor and update maintenance commands ([fce44f7](https://github.com/asjer/rails-worktrees/commit/fce44f757ce9835eb663010f30a192c23f82080c))
+
+
+### Bug Fixes
+
+* **install:** support development-only gem installs ([bf9e742](https://github.com/asjer/rails-worktrees/commit/bf9e74260a88ba37674a5318b48ad5c93f1c0399))
+
 ## [0.4.0](https://github.com/asjer/rails-worktrees/compare/v0.3.0...v0.4.0) (2026-03-30)
 
 
@@ -52,12 +71,3 @@
 ### Features
 
 * add wt command and rails installer ([5d798d5](https://github.com/asjer/rails-worktrees/commit/5d798d5129585331780f0259b39061194feb66e3))
-
-## [Unreleased]
-
-- Add a gem-managed `wt` CLI for creating Rails worktrees.
-- Add an optional gem-managed `ob` CLI plus generated `bin/ob` wrapper for opening `localhost:$DEV_PORT` routes.
-- Add a Rails installer generator that creates `bin/wt` and `config/initializers/rails_worktrees.rb`.
-- Add conservative `config/database.yml` patching for common development/test database names.
-- Add a manual-dispatch GitHub Actions workflow for the disposable Rails smoke test.
-- Add smoke-test workflow debug controls for retained artifacts and verbose output.

data/README.md

@@ -11,7 +11,7 @@
 ## Installation
 
 ```bash
-bundle add rails-worktrees
+bundle add rails-worktrees --group development
 bin/rails generate worktrees:install
 # or, to also generate bin/ob without the yolo follow-ups:
 bin/rails generate worktrees:install --browser
@@ -19,6 +19,8 @@ bin/rails generate worktrees:install --browser
 bin/rails generate worktrees:install --yolo
 ```
 
+The generated initializer writes app config under `Rails.application.config.x.rails_worktrees`, so the file stays safe to load even in environments like `test` where the gem is only bundled for `:development`. When `rails-worktrees` is loaded, the gem applies those settings for both the CLI and in-process Rails usage.
+
 The installer adds:
 
 - `bin/wt` — a thin wrapper that executes the gem-owned CLI
@@ -42,6 +44,9 @@ bin/wt                          # auto-pick a name from bundled *.txt lists
 bin/wt my-feature               # use an explicit worktree name
 bin/wt --dry-run my-feature     # preview the full setup without changing anything
 bin/wt --print-env my-feature   # preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
+bin/wt doctor                   # audit install/config drift and basic worktree health
+bin/wt update --dry-run         # preview safe maintenance fixes
+bin/wt update                   # apply safe maintenance fixes for managed files
 bin/wt remove my-feature        # remove a worktree and delete its local branch
 bin/wt delete my-feature        # alias for `bin/wt remove`
 bin/wt remove --force my-feature # also delete an unmerged local branch
@@ -111,6 +116,18 @@ If you want to see what `bin/wt prune` would clean up before saying yes, use `--
 bin/wt prune --dry-run
 ```
 
+### Maintenance commands
+
+`bin/wt` also includes a small maintenance surface for installer drift and checkout health:
+
+- `bin/wt doctor` — audit managed files plus basic Git/worktree health without changing anything
+- `bin/wt update --dry-run` — preview safe file-based fixes
+- `bin/wt update` — apply safe file-based fixes for supported managed files
+
+`bin/wt doctor` checks the generated initializer, `bin/wt`, optional `bin/ob`, supported config files such as `config/database.yml`, `Procfile.dev`, `config/puma.rb`, and `mise.toml`/`.mise.toml`, plus basic repository/worktree conditions like resolving `origin`'s default branch and spotting stale registered worktree paths.
+
+`bin/wt update` is intentionally conservative: it only applies safe file-based fixes for managed templates and supported config shapes. It does **not** delete branches, remove worktrees, or rewrite ambiguous custom files automatically.
+
 
 ### Interactive prompts
 
@@ -131,6 +148,8 @@ Worktree names must not contain `/` or whitespace, must not be `.` or `..`, and
 
 The installer generates `config/initializers/rails_worktrees.rb` where you can override:
 
+The initializer stays app-owned and gem-agnostic; `rails-worktrees` reads those settings whenever the gem is present in the current bundle groups.
+
 | Option | Default | Description |
 |--------|---------|-------------|
 | `bootstrap_env` | `true` | Write `.env` when creating a worktree |

data/lib/generators/rails/worktrees/templates/rails_worktrees.rb.tt

@@ -1,4 +1,4 @@
-Rails::Worktrees.configure do |config|
+Rails.application.config.x.rails_worktrees.tap do |config|
 <% if options['conductor'] -%>
   config.workspace_root = <%= conductor_workspace_root %>
 <% else -%>
@@ -16,4 +16,4 @@ Rails::Worktrees.configure do |config|
   #   'rails-worktrees',
   #   'used-names.tsv'
   # )
-end
+end

data/lib/rails/worktrees/application_configuration.rb

@@ -0,0 +1,36 @@
+module Rails
+  module Worktrees
+    # Copies explicit app configuration values onto the runtime configuration object.
+    module ApplicationConfiguration
+      module_function
+
+      def apply(source, configuration:)
+        return configuration unless source
+
+        Configuration::CONFIGURABLE_ATTRIBUTES.each do |attribute|
+          next unless assigned?(source, attribute)
+
+          configuration.public_send("#{attribute}=", value_for(source, attribute))
+        end
+
+        configuration
+      end
+
+      def assigned?(source, attribute)
+        key = attribute.to_sym
+        hash = source.is_a?(Hash) ? source : source.to_h if source.respond_to?(:to_h)
+        return hash.key?(key) || hash.key?(attribute.to_s) if hash
+
+        source.respond_to?(:key?) && (source.key?(key) || source.key?(attribute.to_s))
+      end
+
+      def value_for(source, attribute)
+        key = attribute.to_sym
+        hash = source.is_a?(Hash) ? source : source.to_h if source.respond_to?(:to_h)
+        return hash.fetch(key) { hash[attribute.to_s] } if hash
+
+        source.public_send(attribute)
+      end
+    end
+  end
+end

data/lib/rails/worktrees/cli.rb

@@ -2,6 +2,9 @@ module Rails
   module Worktrees
     # Shell entrypoint for the wt executable.
     class CLI
+      LOADER_OPTIONAL_COMMANDS = %w[doctor update -h --help -v --version].freeze
+      LOADER_IGNORED_FLAGS = %w[--dry-run --force].freeze
+
       def initialize(
         argv: ARGV,
         io: { stdin: $stdin, stdout: $stdout, stderr: $stderr },
@@ -15,13 +18,36 @@ module Rails
       end
 
       def start
-        Command.new(
-          argv: @argv,
-          io: @io,
-          env: @env,
-          cwd: @cwd,
-          configuration: ::Rails::Worktrees.configuration
-        ).run
+        configuration = ::Rails::Worktrees.configuration
+        load_project_configuration(configuration) if should_load_project_configuration?
+        command_for(configuration).run
+      rescue ::Rails::Worktrees::Error => e
+        @io.fetch(:stderr).puts("Error: #{e.message}")
+        1
+      end
+
+      private
+
+      def load_project_configuration(configuration)
+        ::Rails::Worktrees::ProjectConfigurationLoader.new(root: @cwd, configuration: configuration).call
+      rescue StandardError, ScriptError => e
+        raise ::Rails::Worktrees::Error, "Failed to load worktrees configuration: #{e.class}: #{e.message}"
+      end
+
+      def should_load_project_configuration?
+        argv_without_flags.empty? || !loader_optional_command?(argv_without_flags.first)
+      end
+
+      def argv_without_flags
+        @argv.reject { |arg| LOADER_IGNORED_FLAGS.include?(arg) }
+      end
+
+      def loader_optional_command?(command)
+        LOADER_OPTIONAL_COMMANDS.include?(command)
+      end
+
+      def command_for(configuration)
+        Command.new(argv: @argv, io: @io, env: @env, cwd: @cwd, configuration: configuration)
       end
     end
   end

data/lib/rails/worktrees/command/output.rb

@@ -32,6 +32,8 @@ module Rails
             Usage: wt [worktree-name]
                    wt --dry-run [worktree-name]
                    wt --print-env <worktree-name>
+                   wt doctor
+                   wt update [--dry-run]
                    wt remove [--dry-run] [--force] <worktree-name>
                    wt delete [--dry-run] [--force] <worktree-name>
                    wt prune [--dry-run]
@@ -48,6 +50,8 @@ module Rails
               wt my-feature      Use an explicit worktree name
               wt --dry-run my-feature
               wt --print-env my-feature
+              wt doctor
+              wt update --dry-run
               wt remove my-feature
               wt remove --force my-feature
               wt prune
@@ -57,6 +61,8 @@ module Rails
               - when workspace_root or WT_WORKSPACES_ROOT is set, creates worktrees in <root>/<project>/<name>
               - always uses the branch name #{@configuration.branch_prefix}/<name>
               - bases new branches on the repository's origin default branch
+              - wt doctor audits install/config drift plus basic worktree health without changing files
+              - wt update applies safe file-based fixes for managed installer artifacts and config hints
               - wt remove/delete can run from the main checkout or any sibling worktree, but never remove the worktree you're currently in
               - wt prune removes merged worktrees created by wt while skipping the main checkout and the checkout you're in
               - auto-discovers bundled *.txt files from #{@configuration.name_sources_path}
@@ -147,6 +153,29 @@ module Rails
           0
         end
 
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+        def print_doctor_report(checks)
+          checks.each do |check|
+            printer = check.ok? ? :info : :warning
+            send(printer, "#{check.category}: #{check.headline}")
+            Array(check.messages).each { |message| info(message) }
+          end
+
+          fixable_count = checks.count(&:fixable?)
+          warning_count = checks.count(&:warning?)
+
+          if fixable_count.zero? && warning_count.zero?
+            success('Doctor found no issues.')
+          else
+            warning(
+              "Doctor found #{fixable_count} fixable issue#{'s' unless fixable_count == 1} and " \
+              "#{warning_count} warning#{'s' unless warning_count == 1}."
+            )
+            info('Run `wt update --dry-run` to preview safe fixes.') if fixable_count.positive?
+          end
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
         def warning(message)
           @stderr.puts("⚠️  #{message}")
         end

data/lib/rails/worktrees/command.rb

@@ -11,6 +11,8 @@ module Rails
     # rubocop:disable Metrics/ClassLength
     class Command
       REMOVE_SUBCOMMANDS = %w[remove delete].freeze
+      DOCTOR_SUBCOMMAND = 'doctor'.freeze
+      UPDATE_SUBCOMMAND = 'update'.freeze
 
       include GitOperations
       include EnvironmentSupport
@@ -69,7 +71,17 @@ module Rails
         @argv.first == 'prune'
       end
 
+      def doctor_subcommand?
+        @argv.first == DOCTOR_SUBCOMMAND
+      end
+
+      def update_subcommand?
+        @argv.first == UPDATE_SUBCOMMAND
+      end
+
       def execute_requested_command
+        return execute_doctor_command if doctor_subcommand?
+        return execute_update_command if update_subcommand?
         return execute_remove_command if remove_subcommand?
         return execute_prune_command if prune_subcommand?
         return usage_error if @argv.length > 1 || force?
@@ -144,11 +156,71 @@ module Rails
         0
       end
 
+      # rubocop:disable Metrics/MethodLength
+      def execute_doctor_command
+        validate_doctor_args!
+
+        unless git_success?('rev-parse', '--is-inside-work-tree')
+          checks = [doctor_check(category: :git, status: :warning,
+                                 headline: 'Run wt doctor from inside a Git repository.')]
+          print_doctor_report(checks)
+          return 1
+        end
+
+        repository = resolve_repository_context
+        checks = project_maintenance_report(repository[:current_root]).checks + doctor_worktree_checks(repository)
+        print_doctor_report(checks)
+
+        checks.any? { |check| check.fixable? || check.warning? } ? 1 : 0
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def execute_update_command
+        require_git_repo
+        validate_update_args!
+        announce_dry_run if dry_run?
+
+        current_root = resolve_repository_context[:current_root]
+        report = project_maintenance_report(current_root)
+        updated_count = 0
+        identical_count = 0
+        skipped_count = 0
+
+        report.checks.each do |check|
+          if check.fixable?
+            apply_maintenance_check(check, current_root: current_root)
+            updated_count += 1
+          elsif check.ok?
+            identical_count += 1
+            info(check.headline)
+          else
+            skipped_count += 1
+            warning(check.headline)
+            check.messages.each { |message| info(message) }
+          end
+        end
+
+        complete_update(updated_count:, identical_count:, skipped_count:)
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
       def validate_prune_args!
         raise Error, 'Usage: wt prune' unless @argv.length == 1
         raise Error, 'The --force flag is only supported with wt remove.' if force?
       end
 
+      def validate_doctor_args!
+        raise Error, 'Usage: wt doctor' unless @argv.length == 1
+        raise Error, 'wt doctor does not support --dry-run.' if dry_run?
+        raise Error, 'The --force flag is only supported with wt remove.' if force?
+      end
+
+      def validate_update_args!
+        raise Error, 'Usage: wt update [--dry-run]' unless @argv.length == 1
+        raise Error, 'The --force flag is only supported with wt remove.' if force?
+      end
+
       def announce_prune_candidates(candidates)
         info("Found #{candidates.length} merged worktree#{'s' unless candidates.length == 1} created by wt:")
       end
@@ -343,6 +415,145 @@ module Rails
       def worktree_name_for_branch(branch_name)
         branch_name.delete_prefix("#{@configuration.branch_prefix}/")
       end
+
+      def project_maintenance_report(root)
+        ::Rails::Worktrees::ProjectMaintenance.new(root: root).call
+      end
+
+      def doctor_worktree_checks(repository)
+        [
+          doctor_check(
+            category: :git,
+            status: :ok,
+            headline: "Git repository detected at #{repository[:current_root]}."
+          ),
+          default_branch_doctor_check,
+          stale_worktree_doctor_check
+        ]
+      end
+
+      def default_branch_doctor_check
+        doctor_check(
+          category: :git,
+          status: :ok,
+          headline: "origin default branch resolves to '#{resolve_default_branch}'."
+        )
+      rescue Error => e
+        doctor_check(category: :git, status: :warning, headline: e.message)
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def stale_worktree_doctor_check
+        stale_paths = worktree_entries.reject { |entry| File.directory?(entry[:path]) }
+        if stale_paths.empty?
+          doctor_check(category: :worktree, status: :ok, headline: 'No stale registered worktree paths found.')
+        else
+          doctor_check(
+            category: :worktree,
+            status: :warning,
+            headline: "Found #{stale_paths.length} stale registered worktree " \
+                      "path#{'s' unless stale_paths.length == 1}.",
+            messages: stale_paths.map { |entry| entry[:path] }
+          )
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength
+      def doctor_check(category:, status:, headline:, messages: [])
+        ::Rails::Worktrees::ProjectMaintenance::Check.new(
+          identifier: nil,
+          category: category,
+          status: status,
+          headline: headline,
+          messages: messages,
+          relative_path: nil,
+          updated_content: nil,
+          make_executable: false,
+          apply_messages: []
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/AbcSize
+      def apply_maintenance_check(check, current_root:)
+        if dry_run?
+          info("Would update #{check.relative_path}")
+          Array(check.apply_messages).each { |message| info(message) }
+          return
+        end
+
+        path = maintenance_destination_path(check.relative_path, current_root)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, check.updated_content)
+        FileUtils.chmod(0o755, path) if check.make_executable
+
+        Array(check.apply_messages).each { |message| info(message) }
+      end
+
+      def maintenance_destination_path(relative_path, current_root)
+        root_path = File.realpath(current_root)
+        path = File.expand_path(relative_path, root_path)
+        assert_within_root!(path, root_path, "Refusing to write outside of repository root: #{path}")
+        parent_path = nearest_existing_parent(File.dirname(path))
+        assert_parent_within_root!(parent_path, root_path, path)
+        assert_not_symlink!(path)
+        path
+      end
+
+      def assert_within_root!(path, root_path, message)
+        raise Error, message unless within_root?(path, root_path)
+      end
+
+      def assert_parent_within_root!(parent_path, root_path, path)
+        assert_within_root!(
+          parent_path,
+          root_path,
+          "Refusing to write through symlinked directory outside repository root: #{path}"
+        )
+      end
+
+      def assert_not_symlink!(path)
+        raise Error, "Refusing to overwrite symlinked path: #{path}" if File.symlink?(path)
+      end
+
+      def within_root?(path, root_path)
+        path == root_path || path.start_with?("#{root_path}#{File::SEPARATOR}")
+      end
+
+      def nearest_existing_parent(path)
+        candidate = path
+        until File.exist?(candidate)
+          parent = File.dirname(candidate)
+          return candidate if parent == candidate
+
+          candidate = parent
+        end
+
+        File.realpath(candidate)
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/MethodLength
+      def complete_update(updated_count:, identical_count:, skipped_count:)
+        if dry_run?
+          success('Dry run complete')
+          info("Would update #{updated_count} file#{'s' unless updated_count == 1}.")
+          info('No changes were made.')
+          return 0
+        end
+
+        success('Update complete')
+        info(
+          [
+            "updated: #{updated_count}",
+            "already up to date: #{identical_count}",
+            "skipped: #{skipped_count}"
+          ].join(', ')
+        )
+        0
+      end
+      # rubocop:enable Metrics/MethodLength
     end
     # rubocop:enable Metrics/ClassLength
   end

data/lib/rails/worktrees/configuration.rb

@@ -2,6 +2,16 @@ module Rails
   module Worktrees
     # Stores application-level settings for the wt command.
     class Configuration
+      CONFIGURABLE_ATTRIBUTES = %i[
+        bootstrap_env
+        workspace_root
+        dev_port_range
+        branch_prefix
+        name_sources_path
+        used_names_file
+        worktree_database_suffix_max_length
+      ].freeze
+
       DEFAULT_BOOTSTRAP_ENV = true
       DEFAULT_BRANCH_PREFIX = '🚂'.freeze
       DEFAULT_DEV_PORT_RANGE = (3000..3999)

data/lib/rails/worktrees/initializer_updater.rb

@@ -0,0 +1,171 @@
+require 'erb'
+
+module Rails
+  module Worktrees
+    # Safely updates the generated initializer to use the current managed app-config format.
+    # rubocop:disable Metrics/ClassLength
+    class InitializerUpdater
+      Result = Struct.new(:content, :changed, :status, :messages) do
+        def changed?
+          changed
+        end
+      end
+
+      TEMPLATE_PATH = File.expand_path('../../generators/rails/worktrees/templates/rails_worktrees.rb.tt', __dir__)
+      CURRENT_WRAPPER_CALL = 'Rails.application.config.x.rails_worktrees.tap do |config|'.freeze
+      CONFIGURE_CALL = 'Rails::Worktrees.configure do |config|'.freeze
+      KNOWN_GUARD_FRAGMENTS = [
+        "Gem.loaded_specs.key?('rails-worktrees')",
+        'defined?(Rails::Worktrees)',
+        'Rails::Worktrees.respond_to?(:configure)'
+      ].freeze
+
+      def self.default_content = new(content: '').send(:render_default_template)
+
+      def initialize(content:) = @content = content
+
+      def call
+        return identical_result if current_guard_present?
+        return updated_result(self.class.default_content) if blank_content?
+
+        body = wrapped_body
+        return skip_result unless body
+
+        updated_result(rebuild_content(body))
+      end
+
+      private
+
+      def identical_result
+        Result.new(
+          @content,
+          false,
+          :identical,
+          ['config/initializers/rails_worktrees.rb already uses the current managed initializer format.']
+        )
+      end
+
+      def updated_result(content)
+        Result.new(
+          content,
+          content != @content,
+          :updated,
+          ['Updated config/initializers/rails_worktrees.rb to use the current managed initializer format.']
+        )
+      end
+
+      def skip_result
+        Result.new(
+          @content,
+          false,
+          :skip,
+          ['config/initializers/rails_worktrees.rb is too custom to update automatically; review it manually.']
+        )
+      end
+
+      def blank_content? = @content.to_s.strip.empty?
+
+      def current_wrapper_present?
+        !extract_current_wrapper_body(@content.to_s.strip.lines).nil?
+      end
+
+      def normalized_body = extract_existing_body&.then { |body| normalize_body(body) }
+
+      def extract_existing_body
+        stripped = @content.to_s.strip
+        return if stripped.empty?
+
+        body = extract_current_wrapper_body(stripped.lines)
+        return body if body
+
+        body = extract_guarded_configure_body(stripped.lines)
+        return body if body
+
+        body = extract_plain_configure_body(stripped.lines)
+        return body if body
+
+        nil
+      end
+
+      def extract_current_wrapper_body(lines)
+        return unless lines.first&.strip == CURRENT_WRAPPER_CALL && lines.last&.strip == 'end'
+
+        lines[1...-1].join.rstrip
+      end
+
+      def extract_guarded_configure_body(lines)
+        return unless guarded_configure_block?(lines)
+
+        configure_index = lines.index { |line| line.strip == CONFIGURE_CALL }
+        return unless guarded_configure_lines(lines, configure_index).all? { |line| known_guard_line?(line) }
+
+        lines[(configure_index + 1)...-2].join.rstrip
+      end
+
+      def extract_plain_configure_body(lines)
+        return unless lines.first&.strip == CONFIGURE_CALL && lines.last&.strip == 'end'
+
+        lines[1...-1].join.rstrip
+      end
+
+      def known_guard_line?(line)
+        stripped = line.strip
+        return true if stripped.empty?
+
+        normalized = stripped.delete_suffix('&&').strip.sub(/\Aif\s+/, '')
+        KNOWN_GUARD_FRAGMENTS.include?(normalized)
+      end
+
+      def normalize_body(body)
+        body_lines = body.rstrip.lines
+        return '' if body_lines.empty?
+
+        minimum_indent = body_indent(body_lines)
+
+        body_lines.map do |line|
+          next line if line.strip.empty?
+
+          normalize_body_line(line, minimum_indent)
+        end.join.rstrip
+      end
+
+      def rebuild_content(body)
+        content = [CURRENT_WRAPPER_CALL, body, 'end'].join("\n")
+        @content.end_with?("\n") || @content.empty? ? "#{content}\n" : content
+      end
+
+      def render_default_template
+        ERB.new(File.read(TEMPLATE_PATH), trim_mode: '-').result(template_context.instance_eval { binding })
+      end
+
+      def template_context
+        Struct.new(:options, :conductor_workspace_root).new({ 'conductor' => false },
+                                                            "File.expand_path('~/Sites/conductor/workspaces')")
+      end
+
+      def guarded_configure_block?(lines)
+        lines.last(2).map(&:strip) == %w[end end] && lines.any? { |line| line.strip == CONFIGURE_CALL }
+      end
+
+      def guarded_configure_lines(lines, configure_index)
+        lines[0...configure_index].reject { |line| line.strip.empty? }.map(&:rstrip)
+      end
+
+      def body_indent(body_lines)
+        body_lines.reject { |line| line.strip.empty? }
+                  .map { |line| line[/\A\s*/].length }
+                  .min || 0
+      end
+
+      def normalize_body_line(line, minimum_indent)
+        trimmed = line.sub(/\A\s{0,#{minimum_indent}}/, '')
+        "  #{trimmed}"
+      end
+
+      def current_guard_present? = current_wrapper_present?
+
+      def wrapped_body = normalized_body
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rails/worktrees/project_configuration_loader.rb

@@ -0,0 +1,205 @@
+require 'pathname'
+
+module Rails
+  module Worktrees
+    # Loads project-level configuration from the generated initializer without booting the full app.
+    class ProjectConfigurationLoader
+      CURRENT_WRAPPER_CALL = 'Rails.application.config.x.rails_worktrees.tap do |config|'.freeze
+      CONFIGURE_CALL = 'Rails::Worktrees.configure do |config|'.freeze
+      INITIALIZER_RELATIVE_PATH = 'config/initializers/rails_worktrees.rb'.freeze
+      KNOWN_GUARD_FRAGMENTS = [
+        "Gem.loaded_specs.key?('rails-worktrees')",
+        'defined?(Rails::Worktrees)',
+        'Rails::Worktrees.respond_to?(:configure)'
+      ].freeze
+      TEMP_RAILS_ROOT_MUTEX = Mutex.new
+
+      def initialize(root:, configuration: Rails::Worktrees.configuration)
+        @root = root
+        @configuration = configuration
+      end
+
+      def call
+        return configuration unless initializer_path && File.file?(initializer_path)
+
+        body = extract_configuration_body(File.read(initializer_path))
+        return configuration unless body
+
+        recorder = AssignmentRecorder.new(configuration)
+
+        with_temporary_rails_root do
+          evaluate_configuration_body(body, recorder)
+        end
+
+        Rails::Worktrees.apply_application_configuration(recorder.values, configuration: configuration)
+      end
+
+      private
+
+      attr_reader :configuration, :root
+
+      def initializer_path
+        return @initializer_path if defined?(@initializer_path)
+
+        @initializer_path = project_root&.join(INITIALIZER_RELATIVE_PATH)&.to_s
+      end
+
+      def project_root
+        return @project_root if defined?(@project_root)
+
+        @project_root = discover_project_root
+      end
+
+      def discover_project_root
+        current = Pathname(root).expand_path
+
+        current.ascend do |path|
+          return path if File.file?(path.join(INITIALIZER_RELATIVE_PATH))
+        end
+
+        nil
+      end
+
+      def evaluate_configuration_body(body, recorder)
+        # Evaluates a managed initializer body like:
+        #
+        #   proc do |config|
+        #     config.branch_prefix = '🌿'
+        #   end
+        # rubocop:disable Security/Eval, Style/DocumentDynamicEvalDefinition, Style/EvalWithLocation
+        Kernel.eval(
+          "proc do |config|\n#{body.rstrip}\nend",
+          TOPLEVEL_BINDING,
+          initializer_path,
+          1
+        ).call(recorder)
+        # rubocop:enable Security/Eval, Style/DocumentDynamicEvalDefinition, Style/EvalWithLocation
+      end
+
+      def extract_configuration_body(content)
+        stripped = content.to_s.strip
+        return if stripped.empty?
+
+        lines = stripped.lines
+
+        extract_single_block_body(lines, CURRENT_WRAPPER_CALL) ||
+          extract_guarded_configure_body(lines) ||
+          extract_single_block_body(lines, CONFIGURE_CALL)
+      end
+
+      def extract_single_block_body(lines, opening_line)
+        return unless lines.first&.strip == opening_line && lines.last&.strip == 'end'
+
+        lines[1...-1].join
+      end
+
+      def extract_guarded_configure_body(lines)
+        return unless guarded_configure_block?(lines)
+
+        configure_index = lines.index { |line| line.strip == CONFIGURE_CALL }
+        return unless guarded_configure_lines(lines, configure_index).all? { |line| known_guard_line?(line) }
+
+        lines[(configure_index + 1)...-2].join
+      end
+
+      def known_guard_line?(line)
+        normalized = line.strip.delete_suffix('&&').strip.sub(/\Aif\s+/, '')
+        KNOWN_GUARD_FRAGMENTS.include?(normalized)
+      end
+
+      def guarded_configure_block?(lines)
+        lines.last(2).map(&:strip) == %w[end end] && lines.any? { |line| line.strip == CONFIGURE_CALL }
+      end
+
+      def guarded_configure_lines(lines, configure_index)
+        lines[0...configure_index].reject { |line| line.strip.empty? }.map(&:rstrip)
+      end
+
+      def with_temporary_rails_root
+        self.class::TEMP_RAILS_ROOT_MUTEX.synchronize do
+          override_state = build_rails_root_override_state
+
+          apply_temporary_rails_root(override_state, project_root)
+          yield
+        ensure
+          restore_rails_root(override_state)
+        end
+      end
+
+      def build_rails_root_override_state
+        had_root = Rails.respond_to?(:root)
+        { singleton_class: Rails.singleton_class, had_root: had_root,
+          previous_root: (Rails.method(:root) if had_root), overridden: false }
+      end
+
+      def apply_temporary_rails_root(override_state, resolved_project_root)
+        override_state[:singleton_class].send(:define_method, :root) { resolved_project_root }
+        override_state[:overridden] = true
+      end
+
+      def restore_rails_root(override_state)
+        return unless override_state
+
+        override_state[:singleton_class].send(:remove_method, :root) if override_state[:overridden]
+        return unless override_state[:had_root]
+
+        override_state[:singleton_class].send(:define_method, :root, override_state[:previous_root])
+      end
+
+      # Records config.<name> = value assignments without raising on unknown keys.
+      class AssignmentRecorder
+        attr_reader :values
+
+        def initialize(configuration = nil)
+          @configuration = configuration
+          @values = {}
+        end
+
+        def method_missing(method_name, *args)
+          name = method_name.to_s
+
+          if setter_call?(name, args)
+            values[name.delete_suffix('=').to_sym] = args.first
+          elsif getter_call?(name, args)
+            values.fetch(name.to_sym) { configuration_value_for(method_name) }
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          name = method_name.to_s
+
+          setter_name?(name) || getter_name?(name) || super
+        end
+
+        private
+
+        attr_reader :configuration
+
+        def setter_call?(name, args)
+          setter_name?(name) && args.length == 1
+        end
+
+        def getter_call?(name, args)
+          getter_name?(name) && args.empty?
+        end
+
+        def setter_name?(name)
+          name.end_with?('=')
+        end
+
+        def getter_name?(name)
+          !setter_name?(name)
+        end
+
+        def configuration_value_for(method_name)
+          fallback_configuration = configuration
+          return unless fallback_configuration.respond_to?(method_name)
+
+          fallback_configuration.public_send(method_name)
+        end
+      end
+    end
+  end
+end

data/lib/rails/worktrees/project_maintenance.rb

@@ -0,0 +1,328 @@
+module Rails
+  module Worktrees
+    # Audits and prepares safe file-based maintenance updates for the current checkout.
+    # rubocop:disable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize
+    class ProjectMaintenance
+      # rubocop:disable Style/RedundantStructKeywordInit
+      Check = Struct.new(
+        :identifier,
+        :category,
+        :headline,
+        :messages,
+        :relative_path,
+        :status,
+        :updated_content,
+        :make_executable,
+        :apply_messages,
+        keyword_init: true
+      ) do
+        def ok?
+          status == :ok
+        end
+
+        def fixable?
+          status == :fixable
+        end
+
+        def warning?
+          status == :warning
+        end
+
+        def updatable?
+          !updated_content.nil?
+        end
+      end
+
+      Report = Struct.new(:checks, keyword_init: true) do
+        def fixable_checks
+          checks.select(&:fixable?)
+        end
+
+        def warning_checks
+          checks.select(&:warning?)
+        end
+
+        def ok?
+          fixable_checks.empty? && warning_checks.empty?
+        end
+      end
+      # rubocop:enable Style/RedundantStructKeywordInit
+
+      TEMPLATE_ROOT = File.expand_path('../../generators/rails/worktrees/templates', __dir__)
+
+      def initialize(root:)
+        @root = root
+      end
+
+      def call
+        Report.new(checks: maintenance_checks.compact)
+      end
+
+      private
+
+      attr_reader :root
+
+      def maintenance_checks
+        [
+          template_file_check(wrapper_config),
+          initializer_check,
+          database_check,
+          optional_updater_check(procfile_config) { |content| ProcfileUpdater.new(content: content).call },
+          optional_updater_check(puma_config) { |content| PumaConfigUpdater.new(content: content).call },
+          mise_check,
+          template_file_check(browser_wrapper_config)
+        ]
+      end
+
+      def wrapper_config
+        {
+          identifier: :bin_wt,
+          category: :install,
+          relative_path: 'bin/wt',
+          template_path: File.join(TEMPLATE_ROOT, 'bin/wt'),
+          make_executable: true,
+          optional: false
+        }
+      end
+
+      def browser_wrapper_config
+        {
+          identifier: :bin_ob,
+          category: :install,
+          relative_path: 'bin/ob',
+          template_path: File.join(TEMPLATE_ROOT, 'bin/ob'),
+          make_executable: true,
+          optional: true
+        }
+      end
+
+      def template_file_check(config)
+        path = absolute_path(config.fetch(:relative_path))
+        return nil if config.fetch(:optional) && !File.exist?(path)
+
+        desired_content = File.read(config.fetch(:template_path))
+        return template_missing_check(config, desired_content) unless File.exist?(path)
+
+        current_content = File.read(path)
+        if current_content == desired_content
+          if executable_mode_current?(config, path)
+            return ok_check(config, "#{config.fetch(:relative_path)} is up to date.")
+          end
+
+          return executable_permission_check(config, desired_content)
+        end
+
+        fixable_check(
+          config,
+          "#{config.fetch(:relative_path)} differs from the managed template.",
+          updated_content: desired_content,
+          apply_messages: ["Updated #{config.fetch(:relative_path)} to match the managed template."],
+          make_executable: config.fetch(:make_executable, false)
+        )
+      end
+
+      def executable_mode_current?(config, path)
+        !config.fetch(:make_executable, false) || File.executable?(path)
+      end
+
+      def executable_permission_check(config, desired_content)
+        relative_path = config.fetch(:relative_path)
+        fixable_check(
+          config,
+          "#{relative_path} needs its executable bit restored.",
+          updated_content: desired_content,
+          apply_messages: ["Restored executable permissions on #{relative_path}."],
+          make_executable: true
+        )
+      end
+
+      def template_missing_check(config, desired_content)
+        fixable_check(
+          config,
+          "#{config.fetch(:relative_path)} is missing.",
+          updated_content: desired_content,
+          apply_messages: ["Created #{config.fetch(:relative_path)} from the managed template."],
+          make_executable: config.fetch(:make_executable, false)
+        )
+      end
+
+      def initializer_check
+        config = {
+          identifier: :initializer,
+          category: :install,
+          relative_path: 'config/initializers/rails_worktrees.rb',
+          identical_headline: 'config/initializers/rails_worktrees.rb already uses the current managed initializer ' \
+                              'format.',
+          fixable_headline: 'config/initializers/rails_worktrees.rb can be updated automatically.',
+          warning_headline: 'config/initializers/rails_worktrees.rb needs manual review.'
+        }
+        path = absolute_path(config.fetch(:relative_path))
+
+        unless File.exist?(path)
+          return fixable_check(
+            config,
+            "#{config.fetch(:relative_path)} is missing.",
+            updated_content: InitializerUpdater.default_content,
+            apply_messages: ['Created config/initializers/rails_worktrees.rb in the current managed initializer ' \
+                             'format.']
+          )
+        end
+
+        updater_result_check(config, InitializerUpdater.new(content: File.read(path)).call)
+      end
+
+      def database_check
+        config = {
+          identifier: :database,
+          category: :config,
+          relative_path: 'config/database.yml'
+        }
+        path = absolute_path(config.fetch(:relative_path))
+
+        unless File.exist?(path)
+          return warning_check(
+            config,
+            'config/database.yml is missing.',
+            ['Add WORKTREE_DATABASE_SUFFIX support manually if this app uses a custom database setup.']
+          )
+        end
+
+        result = DatabaseConfigUpdater.new(content: File.read(path)).call
+        return updated_database_check(config, result) if result.changed?
+
+        if database_configured?(result)
+          return ok_check(
+            config,
+            'config/database.yml already includes WORKTREE_DATABASE_SUFFIX in supported entries.'
+          )
+        end
+
+        warning_check(
+          config,
+          result.messages.first || 'config/database.yml needs manual review.',
+          result.messages.drop(1)
+        )
+      end
+
+      def updated_database_check(config, result)
+        fixable_check(
+          config,
+          'config/database.yml can be updated automatically.',
+          messages: result.messages.drop(1),
+          updated_content: result.content,
+          apply_messages: result.messages
+        )
+      end
+
+      def database_configured?(result)
+        result.messages.first == 'Development/test database names already include WORKTREE_DATABASE_SUFFIX.'
+      end
+
+      def procfile_config
+        {
+          identifier: :procfile,
+          category: :config,
+          relative_path: 'Procfile.dev',
+          identical_headline: 'Procfile.dev already uses the DEV_PORT-aware web entry.',
+          fixable_headline: 'Procfile.dev can be updated automatically.',
+          warning_headline: 'Procfile.dev needs manual review.'
+        }
+      end
+
+      def puma_config
+        {
+          identifier: :puma,
+          category: :config,
+          relative_path: 'config/puma.rb',
+          identical_headline: 'config/puma.rb already prefers DEV_PORT.',
+          fixable_headline: 'config/puma.rb can be updated automatically.',
+          warning_headline: 'config/puma.rb needs manual review.'
+        }
+      end
+
+      def optional_updater_check(config)
+        path = absolute_path(config.fetch(:relative_path))
+        return unless File.exist?(path)
+
+        updater_result_check(config, yield(File.read(path)))
+      end
+
+      def mise_check
+        relative_path = %w[mise.toml .mise.toml].find { |candidate| File.exist?(absolute_path(candidate)) }
+        return unless relative_path
+
+        config = {
+          identifier: :mise,
+          category: :config,
+          relative_path: relative_path,
+          identical_headline: "#{relative_path} already loads .env from [env].",
+          fixable_headline: "#{relative_path} can be updated automatically.",
+          warning_headline: "#{relative_path} needs manual review."
+        }
+
+        updater_result_check(config, mise_updater_result(relative_path))
+      end
+
+      def mise_updater_result(relative_path)
+        MiseTomlUpdater.new(
+          content: File.read(absolute_path(relative_path)),
+          file_name: File.basename(relative_path)
+        ).call
+      end
+
+      def updater_result_check(config, result)
+        case result.status
+        when :identical
+          ok_check(config, config.fetch(:identical_headline))
+        when :updated
+          fixable_check(
+            config,
+            config.fetch(:fixable_headline),
+            updated_content: result.content,
+            apply_messages: result.messages
+          )
+        else
+          warning_check(config, config.fetch(:warning_headline), result.messages)
+        end
+      end
+
+      def ok_check(config, headline)
+        build_check(config, status: :ok, headline: headline)
+      end
+
+      def warning_check(config, headline, messages = [])
+        build_check(config, status: :warning, headline: headline, messages: messages)
+      end
+
+      def fixable_check(config, headline, updated_content:, apply_messages:, **attributes)
+        build_check(
+          config,
+          status: :fixable,
+          headline: headline,
+          updated_content: updated_content,
+          apply_messages: apply_messages,
+          **attributes
+        )
+      end
+
+      def build_check(config, status:, headline:, **attributes)
+        Check.new(
+          identifier: config.fetch(:identifier),
+          category: config.fetch(:category),
+          relative_path: config.fetch(:relative_path),
+          status: status,
+          headline: headline,
+          messages: attributes.fetch(:messages, []),
+          updated_content: attributes.fetch(:updated_content, nil),
+          make_executable: attributes.fetch(:make_executable, false),
+          apply_messages: attributes.fetch(:apply_messages, [])
+        )
+      end
+
+      def absolute_path(relative_path)
+        File.join(root, relative_path)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength, Metrics/MethodLength, Metrics/AbcSize
+  end
+end

data/lib/rails/worktrees/railtie.rb

@@ -5,6 +5,10 @@ module Rails
       initializer 'rails_worktrees.installation_hint' do
         Rails::Worktrees.warn_about_missing_installation
       end
+
+      initializer 'rails_worktrees.apply_application_config', after: :load_config_initializers do |app|
+        Rails::Worktrees.apply_application_configuration(app.config.x.rails_worktrees)
+      end
     end
   end
 end

data/lib/rails/worktrees/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Worktrees
-    VERSION = '0.4.0'.freeze
+    VERSION = '0.5.1'.freeze
   end
 end

data/lib/rails/worktrees.rb

@@ -2,14 +2,18 @@ require 'pathname'
 
 require_relative 'worktrees/version'
 require_relative 'worktrees/configuration'
+require_relative 'worktrees/application_configuration'
 require_relative 'worktrees/env_bootstrapper'
 require_relative 'worktrees/command'
 require_relative 'worktrees/cli'
 require_relative 'worktrees/browser_command'
 require_relative 'worktrees/database_config_updater'
+require_relative 'worktrees/initializer_updater'
 require_relative 'worktrees/procfile_updater'
 require_relative 'worktrees/mise_toml_updater'
 require_relative 'worktrees/puma_config_updater'
+require_relative 'worktrees/project_configuration_loader'
+require_relative 'worktrees/project_maintenance'
 
 module Rails
   # Rails-specific git worktree helpers and installer support.
@@ -37,6 +41,10 @@ module Rails
         @configuration = Configuration.new
       end
 
+      def apply_application_configuration(source, configuration: self.configuration)
+        ApplicationConfiguration.apply(source, configuration: configuration)
+      end
+
       def installation_complete?(root = resolve_root)
         return false unless root
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-worktrees
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Asjer Querido
@@ -55,6 +55,7 @@ files:
 - lib/generators/rails/worktrees/templates/rails_worktrees.rb.tt
 - lib/generators/worktrees/install/install_generator.rb
 - lib/rails/worktrees.rb
+- lib/rails/worktrees/application_configuration.rb
 - lib/rails/worktrees/browser_command.rb
 - lib/rails/worktrees/cli.rb
 - lib/rails/worktrees/command.rb
@@ -66,9 +67,12 @@ files:
 - lib/rails/worktrees/configuration.rb
 - lib/rails/worktrees/database_config_updater.rb
 - lib/rails/worktrees/env_bootstrapper.rb
+- lib/rails/worktrees/initializer_updater.rb
 - lib/rails/worktrees/mise_toml_updater.rb
 - lib/rails/worktrees/names/cities.txt
 - lib/rails/worktrees/procfile_updater.rb
+- lib/rails/worktrees/project_configuration_loader.rb
+- lib/rails/worktrees/project_maintenance.rb
 - lib/rails/worktrees/puma_config_updater.rb
 - lib/rails/worktrees/railtie.rb
 - lib/rails/worktrees/version.rb