rails-worktrees 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46dd1369d93b3281d8182a90812164a1a245ff778b5af05306908989563e264e
-  data.tar.gz: 0d7e33ae49a56ea819e3a07ebfde966e1b1c18677af8c406bd15e93628ba8aff
+  metadata.gz: 9f11c54fe45c6061774b7181c80c7a25ba1c824d04fe06668ca0d6fe0bc3c453
+  data.tar.gz: 9470d8a967f77f0188679e8f9b50fd5a78c4aebe6f10e268cba00ffaff1ebea0
 SHA512:
-  metadata.gz: 3d9e25b8d52ec84eb983d5b5ba28679394396232f61b8e9b626cf8a8f464b49e53d9f1898d0591bcd78e66620fa2b59869b1c781ed03b7a8a5f176f973a2ebbb
-  data.tar.gz: 795403173d6b6c8c375119b7427bebc620cc73deb9402a8c1c6aa25c863b703af882b4e4b01dd9bdbd123696f1949a1e00f830a92a227e93ddff3e09a1c763ee
+  metadata.gz: c3775b72de293d0cf888f9b94cbbeae5b6031f001c641a1365f8f2662caa38de8b04bd4235a4e5c3f7b81279f6a23ce4637f4b2cfa6d6e1ba9d0fd0619daede2
+  data.tar.gz: 0c07249ae8bad61d6ae0cdad68f58752579145175e0d43005772e0d91f2f04b8d672f99a1952ce168e881d04e0b88ab4bbb8603183d4a9a2ace12f5c1767584e

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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 +64,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 checks that `rails-worktrees` is actually loaded before it calls `Rails::Worktrees.configure`, so the app can still boot in environments like `test` when the gem is only bundled for `:development`.
+
 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 becomes a no-op whenever `rails-worktrees` is not loaded 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,19 +1,23 @@
-Rails::Worktrees.configure do |config|
+if Gem.loaded_specs.key?('rails-worktrees') &&
+    defined?(Rails::Worktrees) &&
+    Rails::Worktrees.respond_to?(:configure)
+  Rails::Worktrees.configure do |config|
 <% if options['conductor'] -%>
-  config.workspace_root = <%= conductor_workspace_root %>
+    config.workspace_root = <%= conductor_workspace_root %>
 <% else -%>
-  # By default, worktrees go in a sibling "<project>.worktrees" directory.
-  # Uncomment to override with a custom parent directory that uses <root>/<project>/<name>.
-  # config.workspace_root = File.expand_path('~/worktrees')
+    # By default, worktrees go in a sibling "<project>.worktrees" directory.
+    # Uncomment to override with a custom parent directory that uses <root>/<project>/<name>.
+    # config.workspace_root = File.expand_path('~/worktrees')
 <% end -%>
-  # config.bootstrap_env = false
-  # config.dev_port_range = 3000..3999
-  # config.worktree_database_suffix_max_length = 18
-  # config.branch_prefix = '🚂'
-  # config.name_sources_path = Rails.root.join('config/worktree_names').to_s
-  # config.used_names_file = File.join(
-  #   ENV.fetch('XDG_STATE_HOME', File.expand_path('~/.local/state')),
-  #   'rails-worktrees',
-  #   'used-names.tsv'
-  # )
+    # config.bootstrap_env = false
+    # config.dev_port_range = 3000..3999
+    # config.worktree_database_suffix_max_length = 18
+    # config.branch_prefix = '🚂'
+    # config.name_sources_path = Rails.root.join('config/worktree_names').to_s
+    # config.used_names_file = File.join(
+    #   ENV.fetch('XDG_STATE_HOME', File.expand_path('~/.local/state')),
+    #   'rails-worktrees',
+    #   'used-names.tsv'
+    # )
+  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/initializer_updater.rb

@@ -0,0 +1,148 @@
+require 'erb'
+
+module Rails
+  module Worktrees
+    # Safely updates the generated initializer to use the current gem-loading guard.
+    # 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_GUARD_LINES = [
+        "if Gem.loaded_specs.key?('rails-worktrees') &&",
+        '    defined?(Rails::Worktrees) &&',
+        '    Rails::Worktrees.respond_to?(:configure)'
+      ].freeze
+      KNOWN_GUARD_FRAGMENTS = [
+        "Gem.loaded_specs.key?('rails-worktrees')",
+        'defined?(Rails::Worktrees)',
+        'Rails::Worktrees.respond_to?(:configure)'
+      ].freeze
+      CONFIGURE_CALL = 'Rails::Worktrees.configure do |config|'.freeze
+      LEGACY_GUARD = /\Aif defined\?\(Rails::Worktrees\)\n(?<body>.*)\nend\z/m
+
+      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 safety guard.']
+        )
+      end
+
+      def updated_result(content)
+        Result.new(
+          content,
+          content != @content,
+          :updated,
+          ['Updated config/initializers/rails_worktrees.rb to use the current safety guard.']
+        )
+      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_guard_present?
+        !extract_known_guard_body(@content.to_s.strip.lines, required_guard_lines: CURRENT_GUARD_LINES).nil?
+      end
+
+      def wrapped_body = extract_existing_body&.then { |body| normalize_body(body) }
+
+      def extract_existing_body
+        stripped = @content.to_s.strip
+        return if stripped.empty?
+
+        return Regexp.last_match[:body] if stripped.match(LEGACY_GUARD)
+
+        body = extract_known_guard_body(stripped.lines)
+        return body if body
+
+        body = extract_plain_configure_body(stripped.lines)
+        return body if body
+
+        nil
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def extract_known_guard_body(lines, required_guard_lines: nil)
+        return if lines.empty? || lines.last.strip != 'end'
+
+        configure_index = lines.index { |line| line.strip == CONFIGURE_CALL }
+        return unless configure_index
+
+        guard_lines = lines[0...configure_index].reject { |line| line.strip.empty? }.map(&:rstrip)
+        return unless guard_lines.all? { |line| known_guard_line?(line) }
+        return if required_guard_lines && guard_lines != required_guard_lines
+
+        lines[configure_index...-1].join.rstrip
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def extract_plain_configure_body(lines)
+        return unless lines.first&.strip == CONFIGURE_CALL && lines.last&.strip == 'end'
+
+        lines.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?
+
+        return body.rstrip if body_lines.first.start_with?('  ')
+
+        body_lines.map { |line| line.strip.empty? ? line : "  #{line}" }.join.rstrip
+      end
+
+      def rebuild_content(body)
+        content = [CURRENT_GUARD_LINES.join("\n"), 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
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rails/worktrees/project_maintenance.rb

@@ -0,0 +1,326 @@
+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 safety guard.',
+          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 with the current safety guard.']
+          )
+        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/version.rb

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

data/lib/rails/worktrees.rb

@@ -7,9 +7,11 @@ 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_maintenance'
 
 module Rails
   # Rails-specific git worktree helpers and installer support.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-worktrees
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Asjer Querido
@@ -66,9 +66,11 @@ 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_maintenance.rb
 - lib/rails/worktrees/puma_config_updater.rb
 - lib/rails/worktrees/railtie.rb
 - lib/rails/worktrees/version.rb