rails-worktrees 0.1.0

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Rails
+  module Worktrees
+    class Command
+      # Shell-level git helpers, branch/worktree queries, and worktree creation.
+      module GitOperations
+        private
+
+        def require_git_repo
+          return if git_success?('rev-parse', '--is-inside-work-tree')
+
+          raise Error, 'Run wt from inside a Git repository.'
+        end
+
+        def resolve_default_branch
+          unless git_success?('remote', 'get-url', 'origin')
+            raise Error, "This repository does not have an 'origin' remote."
+          end
+
+          ref = git_capture('symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD', allow_failure: true).strip
+          if ref.empty?
+            raise Error,
+                  "Could not resolve origin's default branch. Run 'git fetch origin' and " \
+                  "'git remote set-head origin -a', then try again."
+          end
+
+          ref.delete_prefix('refs/remotes/origin/')
+        end
+
+        def branch_exists_locally?(branch_name)
+          git_success?('show-ref', '--verify', '--quiet', "refs/heads/#{branch_name}")
+        end
+
+        def branch_exists_on_origin?(branch_name)
+          git_success?('show-ref', '--verify', '--quiet', "refs/remotes/origin/#{branch_name}")
+        end
+
+        def branch_is_checked_out_elsewhere?(branch_name)
+          worktree_branch_checked_out?(branch_name, worktree_list_output)
+        end
+
+        def registered_worktree_path?(target_dir)
+          normalized_target = canonical_path(target_dir)
+
+          worktree_list_output.each_line.any? do |line|
+            next unless line.start_with?('worktree ')
+
+            canonical_path(line.delete_prefix('worktree ').strip) == normalized_target
+          end
+        end
+
+        def worktree_branch_checked_out?(branch_name, output)
+          target_branch = "branch refs/heads/#{branch_name}"
+          output.each_line.slice_after { |line| line.chomp.empty? }.any? do |lines|
+            lines.first&.start_with?('worktree ') && lines.any? { |line| line.chomp == target_branch }
+          end
+        end
+
+        def worktree_list_output = git_capture('worktree', 'list', '--porcelain')
+
+        def canonical_path(path)
+          File.realpath(path)
+        rescue Errno::ENOENT then File.expand_path(path)
+        end
+
+        def create_new_branch_worktree(branch_name, target_dir)
+          default_branch = resolve_default_branch
+          if dry_run?
+            info("Would create '#{branch_name}' from 'origin/#{default_branch}'")
+            return
+          end
+
+          info("Creating '#{branch_name}' from 'origin/#{default_branch}'")
+          git!('worktree', 'add', '-b', branch_name, target_dir, "origin/#{default_branch}")
+        end
+
+        def attach_existing_branch_worktree(branch_name, target_dir)
+          if branch_is_checked_out_elsewhere?(branch_name)
+            return attach_checked_out_branch_worktree(branch_name, target_dir)
+          end
+
+          info("#{dry_run? ? 'Would attach' : 'Attaching'} existing local branch '#{branch_name}'")
+          return if dry_run?
+
+          git!('worktree', 'add', target_dir, branch_name)
+        end
+
+        def track_remote_branch_worktree(branch_name, target_dir)
+          if dry_run?
+            info("Would create local tracking branch '#{branch_name}' from 'origin/#{branch_name}'")
+            return
+          end
+
+          info("Creating local tracking branch '#{branch_name}' from 'origin/#{branch_name}'")
+          git!('worktree', 'add', '--track', '-b', branch_name, target_dir, "origin/#{branch_name}")
+        end
+
+        def remove_registered_worktree(target_dir)
+          info("Removing registered worktree at '#{target_dir}'")
+          git!('worktree', 'remove', '--force', target_dir)
+        end
+
+        def git!(*)
+          stdout_str, stderr_str, status = Open3.capture3(@env.to_h, 'git', *, chdir: @cwd)
+          return stdout_str if status.success?
+
+          raise Error, combined_output(stdout_str, stderr_str)
+        end
+
+        def git_capture(*, allow_failure: false)
+          stdout_str, stderr_str, status = Open3.capture3(@env.to_h, 'git', *, chdir: @cwd)
+          return stdout_str if status.success? || allow_failure
+
+          raise Error, combined_output(stdout_str, stderr_str)
+        end
+
+        def git_success?(*)
+          _stdout_str, _stderr_str, status = Open3.capture3(@env.to_h, 'git', *, chdir: @cwd)
+          status.success?
+        end
+
+        def combined_output(stdout_str, stderr_str)
+          output = [stdout_str, stderr_str].map(&:strip).reject(&:empty?).join("\n")
+          return output unless output.empty?
+
+          'git command failed'
+        end
+
+        def attach_checked_out_branch_worktree(branch_name, target_dir)
+          confirm_or_abort!(
+            "'#{branch_name}' is already checked out in another worktree. Create another checkout anyway?"
+          )
+          info("#{dry_run? ? 'Would create' : 'Creating'} another checkout for '#{branch_name}'")
+          return if dry_run?
+
+          git!('worktree', 'add', '--force', target_dir, branch_name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    class Command
+      # Auto-picking names from bundled .txt files and tracking retired names.
+      # rubocop:disable Metrics/ModuleLength
+      module NamePicking
+        private
+
+        def resolve_worktree_name(project_name, workspaces)
+          worktree_name = @argv.first
+          return validate_worktree_name(worktree_name) if worktree_name && !worktree_name.empty?
+
+          source_file, auto_name = pick_random_source_name(project_name, workspaces)
+          info("Selected #{name_source_label(source_file)} name '#{auto_name}'")
+          auto_name
+        end
+
+        def pick_random_source_name(project_name, workspaces)
+          eligible_sources = name_source_files.filter_map do |source_file|
+            available_names = list_available_names(source_file, project_name, workspaces)
+            next if available_names.empty?
+
+            [source_file, available_names]
+          end
+
+          if eligible_sources.empty?
+            raise Error, "No unused names are available in #{@configuration.name_sources_path}/*.txt"
+          end
+
+          selected_source, available_names = eligible_sources.sample
+          [selected_source, available_names.sample]
+        end
+
+        def name_source_files
+          path = @configuration.name_sources_path
+          files = Dir.glob(File.join(path, '*.txt')).select { |file| File.file?(file) }
+          raise Error, "No name list files found in #{path}" if files.empty?
+
+          files
+        end
+
+        def name_source_label(source_file) = File.basename(source_file, '.txt')
+
+        def list_available_names(source_file, project_name, workspaces)
+          source_names(source_file).select do |candidate|
+            valid_auto_name?(candidate) && available_for_auto_pick?(candidate, project_name, workspaces)
+          end
+        end
+
+        def source_names(source_file)
+          File.readlines(source_file, chomp: true).filter_map do |line|
+            name = line.delete_suffix("\r").strip
+            next if name.empty? || name.start_with?('#')
+
+            name
+          end
+        end
+
+        def available_for_auto_pick?(candidate, project_name, workspaces)
+          branch_name = branch_name_for(candidate)
+          target_dir = target_dir_for(project_name, candidate, workspaces)
+
+          !name_is_retired?(candidate) &&
+            !branch_exists_locally?(branch_name) &&
+            !branch_exists_on_origin?(branch_name) &&
+            !File.exist?(target_dir)
+        end
+
+        def name_exists_in_any_source?(candidate)
+          name_source_files.any? { |f| source_names(f).include?(candidate) }
+        end
+
+        def name_is_retired?(candidate)
+          state_file = retired_names_file
+          return false unless state_file
+
+          File.foreach(state_file).any? { |line| line.split("\t", 2).first == candidate }
+        end
+
+        def record_retired_name(worktree_name, project_name)
+          return unless bundled_name_needs_retirement?(worktree_name)
+
+          ensure_state_store
+          timestamp = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+          File.open(@configuration.used_names_file, 'a') do |file|
+            file.puts([worktree_name, project_name, timestamp].join("\t"))
+          end
+        end
+
+        def ensure_state_store
+          state_file = @configuration.used_names_file
+          FileUtils.mkdir_p(File.dirname(state_file))
+          return if File.exist?(state_file)
+
+          legacy_path = Array(@configuration.legacy_used_names_files).find { |path| File.file?(path) }
+          FileUtils.cp(legacy_path, state_file) if legacy_path
+        end
+
+        def bundled_name_needs_retirement?(worktree_name)
+          name_exists_in_any_source?(worktree_name) && !name_is_retired?(worktree_name)
+        end
+
+        def settle_retired_name(worktree_name, project_name, dry_run: false)
+          return record_retired_name(worktree_name, project_name) unless dry_run
+
+          return unless bundled_name_needs_retirement?(worktree_name)
+
+          info("Would retire bundled name '#{worktree_name}'")
+        end
+
+        def reject_retired_name_for_new_branch(worktree_name)
+          return unless name_exists_in_any_source?(worktree_name)
+          return unless name_is_retired?(worktree_name)
+
+          raise Error,
+                "Bundled name '#{worktree_name}' has already been used and retired. " \
+                "Pick another name or run 'wt' with no argument for a fresh one."
+        end
+
+        def validate_worktree_name(worktree_name)
+          raise Error, 'Worktree name is required.' if worktree_name.nil? || worktree_name.empty?
+          raise Error, "Worktree name must not be '.' or '..'." if %w[. ..].include?(worktree_name)
+          raise Error, "Worktree name must not contain '/'." if worktree_name.include?('/')
+          raise Error, 'Worktree name must not contain spaces.' if worktree_name.match?(/\s/)
+          unless git_valid_ref_name?(worktree_name)
+            raise Error, "Worktree name '#{worktree_name}' is not a valid Git ref component."
+          end
+
+          worktree_name
+        end
+
+        def git_valid_ref_name?(name)
+          git_success?('check-ref-format', '--branch', name)
+        end
+
+        def valid_auto_name?(worktree_name)
+          validate_worktree_name(worktree_name)
+          true
+        rescue Error
+          false
+        end
+
+        def retired_names_file
+          if File.file?(@configuration.used_names_file)
+            @configuration.used_names_file
+          else
+            Array(@configuration.legacy_used_names_files).find { |path| File.file?(path) }
+          end
+        end
+      end
+      # rubocop:enable Metrics/ModuleLength
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    class Command
+      # User-facing output, prompts, and help text.
+      module Output
+        private
+
+        def handle_meta_command
+          case @argv.first
+          when '-h', '--help'
+            @stdout.print(usage)
+            0
+          when '-v', '--version'
+            @stdout.puts("wt #{Rails::Worktrees::VERSION}")
+            0
+          when '--env', '--print-env'
+            preview_worktree_environment_command
+          end
+        end
+
+        def usage_error
+          @stderr.print(usage)
+          1
+        end
+
+        def usage
+          <<~USAGE
+            wt #{::Rails::Worktrees::VERSION}
+            Create Git worktrees for the current repository.
+
+            Usage: wt [worktree-name]
+                   wt --dry-run [worktree-name]
+                   wt --print-env <worktree-name>
+
+            Options:
+              -h, --help                  Show this help message
+              -v, --version               Show the script version
+              --dry-run [name]            Preview the full worktree setup without changing anything
+              --env, --print-env <name>   Preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
+
+            Quick start:
+              wt                 Auto-pick a name from a bundled *.txt list
+              wt my-feature      Use an explicit worktree name
+              wt --dry-run my-feature
+              wt --print-env my-feature
+
+            How it works:
+              - by default creates worktrees beside the repo in ../<project>.worktrees/<name>
+              - 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
+              - auto-discovers bundled *.txt files from #{@configuration.name_sources_path}
+              - retires bundled names in #{@configuration.used_names_file}
+          USAGE
+        end
+
+        def confirm_or_abort!(prompt)
+          if dry_run?
+            info("Would confirm: #{prompt}")
+            return
+          end
+
+          raise Error, 'Aborted.' unless confirm?(prompt)
+        end
+
+        def confirm?(prompt)
+          return false unless @stdin.respond_to?(:tty?) && @stdin.tty?
+
+          @stdout.print("#{prompt} [y/N] ")
+          response = @stdin.gets.to_s.strip
+          response.match?(/\A(?:y|yes)\z/i)
+        end
+
+        def info(message)
+          @stdout.puts("→ #{message}")
+        end
+
+        def announce_dry_run = info('Dry run: previewing worktree setup without making changes')
+
+        def complete_dry_run(context, env_values:)
+          success('Dry run complete')
+          print_context_summary(context, env_values: env_values)
+          info('No changes were made.')
+          0
+        end
+
+        def complete_reuse_dry_run(context, target:, branch:)
+          preview_result = preview_worktree_environment(context)
+          info("Would reuse existing worktree at '#{target}' on '#{branch}'")
+          complete_dry_run(context, env_values: preview_result&.values)
+        end
+
+        def warning(message)
+          @stderr.puts("⚠️  #{message}")
+        end
+
+        def success(message)
+          @stdout.puts("✅ #{message}")
+        end
+
+        def print_env_preview(values)
+          values.each { |key, value| @stdout.puts("#{key}=#{value}") }
+        end
+
+        def print_context_summary(context, target_dir: context[:target_dir], branch_name: context[:branch_name],
+                                  env_values: nil)
+          print_worktree_summary(
+            target_dir,
+            branch_name,
+            context[:workspaces_root],
+            uses_default_workspace_root: context[:uses_default_workspace_root],
+            env_values: env_values
+          )
+        end
+
+        def print_worktree_summary(target_dir, branch_name, workspaces_root, uses_default_workspace_root:, env_values:)
+          @stdout.puts("Root:   #{workspaces_root}") unless uses_default_workspace_root
+          @stdout.puts("Path:   #{target_dir}")
+          @stdout.puts("Branch: #{branch_name}")
+          @stdout.puts("Port:   #{env_values['DEV_PORT']}") if env_values && env_values['DEV_PORT']
+          suffix = env_values && env_values['WORKTREE_DATABASE_SUFFIX']
+          return unless suffix
+
+          @stdout.puts("Suffix: #{suffix}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    class Command
+      # Resolves the default and explicit workspace path layouts.
+      module WorkspacePaths
+        private
+
+        def resolve_workspaces(repo_root, project_name)
+          explicit_root = configured_workspaces_root
+          return { root: explicit_root, uses_default_root: false } if explicit_root
+
+          { root: File.join(File.dirname(repo_root), "#{project_name}.worktrees"), uses_default_root: true }
+        end
+
+        def configured_workspaces_root
+          env_root = @env['WT_WORKSPACES_ROOT']
+          return expand_home(env_root) if present_path?(env_root)
+
+          config_root = @configuration.workspace_root
+          return expand_home(config_root) if present_path?(config_root)
+
+          nil
+        end
+
+        def target_dir_for(project_name, worktree_name, workspaces)
+          if workspaces[:uses_default_root]
+            File.join(workspaces[:root], worktree_name)
+          else
+            File.join(workspaces[:root], project_name, worktree_name)
+          end
+        end
+
+        def prepare_target_parent(target_dir)
+          parent_dir = File.dirname(target_dir)
+          return if File.directory?(parent_dir)
+          return info("Would create workspace directory '#{parent_dir}'") if dry_run?
+
+          FileUtils.mkdir_p(parent_dir)
+        end
+
+        def present_path?(path)
+          !path.nil? && !path.empty?
+        end
+
+        def expand_home(path)
+          case path
+          when '~'
+            Dir.home
+          when %r{\A~/}
+            File.join(Dir.home, path.delete_prefix('~/'))
+          else
+            path
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/worktrees/command.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'command/environment_support'
+require_relative 'command/git_operations'
+require_relative 'command/name_picking'
+require_relative 'command/output'
+require_relative 'command/workspace_paths'
+
+module Rails
+  module Worktrees
+    # Creates or attaches worktrees for the current repository.
+    # rubocop:disable Metrics/ClassLength
+    class Command
+      include GitOperations
+      include EnvironmentSupport
+      include NamePicking
+      include Output
+      include WorkspacePaths
+
+      def initialize(argv:, io:, env:, cwd:, configuration:)
+        @argv = argv.dup
+        @stdin = io.fetch(:stdin)
+        @stdout = io.fetch(:stdout)
+        @stderr = io.fetch(:stderr)
+        @env = env
+        @cwd = cwd
+        @configuration = configuration
+        @dry_run = @argv.first == '--dry-run'
+        @argv.shift if dry_run?
+      end
+
+      def run
+        return usage_error if dry_run? && @argv.first&.start_with?('-')
+
+        meta_command_result = handle_meta_command
+        return meta_command_result unless meta_command_result.nil?
+        return usage_error if @argv.length > 1
+
+        execute_worktree_command
+      rescue Error => e
+        @stderr.puts("Error: #{e.message}")
+        1
+      end
+
+      private
+
+      def dry_run? = @dry_run
+
+      def execute_worktree_command
+        require_git_repo
+        announce_dry_run if dry_run?
+        context = resolve_worktree_context
+
+        if File.exist?(context[:target_dir])
+          return finish_reuse(context) if worktree_matches_branch?(context)
+
+          confirm_and_remove_target(context[:target_dir])
+        end
+
+        prepare_target_parent(context[:target_dir])
+        attach_or_create_worktree(context)
+        finish(context)
+      end
+
+      def resolve_worktree_context(explicit_worktree_name: nil)
+        repo_root = git_capture('rev-parse', '--show-toplevel').strip
+        project_name = File.basename(repo_root)
+        workspaces = resolve_workspaces(repo_root, project_name)
+        worktree_name = resolved_worktree_name(project_name, workspaces, explicit_worktree_name)
+
+        { project_name: project_name, workspaces_root: workspaces[:root], worktree_name: worktree_name,
+          uses_default_workspace_root: workspaces[:uses_default_root],
+          branch_name: branch_name_for(worktree_name),
+          target_dir: target_dir_for(project_name, worktree_name, workspaces) }
+      end
+
+      def resolved_worktree_name(project_name, workspaces, explicit_worktree_name)
+        return validate_worktree_name(explicit_worktree_name) if explicit_worktree_name
+
+        resolve_worktree_name(project_name, workspaces)
+      end
+
+      def attach_or_create_worktree(context)
+        branch, target = context.values_at(:branch_name, :target_dir)
+
+        if branch_exists_locally?(branch)
+          confirm_or_abort!("Branch '#{branch}' already exists locally. Attach a new worktree to it?")
+          attach_existing_branch_worktree(branch, target)
+        elsif branch_exists_on_origin?(branch)
+          confirm_or_abort!("Branch '#{branch}' already exists on origin. Create a local tracking worktree?")
+          track_remote_branch_worktree(branch, target)
+        else
+          create_fresh_branch_worktree(context)
+        end
+      end
+
+      def create_fresh_branch_worktree(context)
+        reject_retired_name_for_new_branch(context[:worktree_name])
+        create_new_branch_worktree(context[:branch_name], context[:target_dir])
+      end
+
+      def finish(context)
+        settle_retired_name(context[:worktree_name], context[:project_name], dry_run: dry_run?)
+        bootstrap_result = bootstrap_worktree_environment(context)
+        return complete_dry_run(context, env_values: bootstrap_result&.values) if dry_run?
+
+        success('Worktree ready')
+        print_context_summary(context, env_values: bootstrap_result&.values)
+        0
+      end
+
+      def finish_reuse(context)
+        target, branch = context.values_at(:target_dir, :branch_name)
+
+        confirm_or_abort!("Worktree already exists at '#{target}' on '#{branch}'. Reuse it?")
+        settle_retired_name(context[:worktree_name], context[:project_name], dry_run: dry_run?)
+        return complete_reuse_dry_run(context, target: target, branch: branch) if dry_run?
+
+        bootstrap_result = bootstrap_worktree_environment(context)
+        success('Reusing existing worktree')
+        print_context_summary(context, target_dir: target, branch_name: branch, env_values: bootstrap_result&.values)
+        0
+      end
+
+      def worktree_matches_branch?(context)
+        target = context[:target_dir]
+        return false unless git_success?('-C', target, 'rev-parse', '--is-inside-work-tree')
+
+        existing = git_capture('-C', target, 'branch', '--show-current', allow_failure: true).strip
+        existing == context[:branch_name]
+      end
+
+      def confirm_and_remove_target(target_dir)
+        confirm_or_abort!("Target path '#{target_dir}' already exists. Remove it and recreate the worktree?")
+        return info("Would remove existing target path '#{target_dir}'") if dry_run?
+
+        if registered_worktree_path?(target_dir)
+          remove_registered_worktree(target_dir)
+        else
+          FileUtils.rm_rf(target_dir)
+        end
+      end
+
+      def branch_name_for(worktree_name)
+        "#{@configuration.branch_prefix}/#{worktree_name}"
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rails/worktrees/configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    # Stores application-level settings for the wt command.
+    class Configuration
+      DEFAULT_BOOTSTRAP_ENV = true
+      DEFAULT_BRANCH_PREFIX = '🚂'
+      DEFAULT_DEV_PORT_RANGE = (3000..3999)
+      DEFAULT_USED_NAMES_DIRECTORY = File.join(
+        ENV.fetch('XDG_STATE_HOME', File.join(Dir.home, '.local/state')),
+        'rails-worktrees'
+      )
+      DEFAULT_USED_NAMES_FILE = File.join(DEFAULT_USED_NAMES_DIRECTORY, 'used-names.tsv')
+      DEFAULT_NAME_SOURCES_PATH = File.expand_path('names', __dir__)
+      DEFAULT_WORKTREE_DATABASE_SUFFIX_MAX_LENGTH = 18
+
+      attr_accessor :bootstrap_env, :branch_prefix, :dev_port_range, :legacy_used_names_files,
+                    :name_sources_path, :used_names_file, :workspace_root,
+                    :worktree_database_suffix_max_length
+
+      def initialize
+        @bootstrap_env = DEFAULT_BOOTSTRAP_ENV
+        @workspace_root = nil
+        @branch_prefix = DEFAULT_BRANCH_PREFIX
+        @dev_port_range = DEFAULT_DEV_PORT_RANGE
+        @name_sources_path = DEFAULT_NAME_SOURCES_PATH
+        @used_names_file = DEFAULT_USED_NAMES_FILE
+        @worktree_database_suffix_max_length = DEFAULT_WORKTREE_DATABASE_SUFFIX_MAX_LENGTH
+        @legacy_used_names_files = default_legacy_used_names_files
+      end
+
+      private
+
+      def default_legacy_used_names_files
+        state_home = ENV.fetch('XDG_STATE_HOME', File.join(Dir.home, '.local/state'))
+
+        [
+          File.join(state_home, 'wt', 'used-names.tsv'),
+          File.join(state_home, 'wt', 'used-cities.tsv')
+        ]
+      end
+    end
+  end
+end