rails-worktrees 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 698795e04a67284039d3beba2286f3a9aa156a5856832a345f22ffa57b6177e3
-  data.tar.gz: 0a57ef25c66c3226798498476abf8caf033c6a2989ae170b30a161fde66fddcf
+  metadata.gz: e86a789b2e56f07d95a626b67c9fafbf01862e9c8496043107914b4446e13702
+  data.tar.gz: 9f0dce854a6c7a20dfedb00dd181f7ecc5699ae6cf86ff61d24d60bce80be11e
 SHA512:
-  metadata.gz: 06c8ae396186a19c08e45445e031a28198d48f7ea5125c02e63b2df39977f5399f75421e7f1897071d14b00d042051616ed4e447b83b570852d54756d8689377
-  data.tar.gz: 800a19ef60af420e03280b8a30c02c9012c4ded0d3eaecc421ed5e42e072b8024a0cbc93e7ba7aaf7d806dc972deacacbb0c5edfe45da40b2ab05659b1ccc5c5
+  metadata.gz: 16513989c4364e4cf37d4eb0cf1fbde3fc95d8aa246223b5e9cca20da0035266d8f33e81a115d83b95b359ff93292796ba88889f06495c9d8b39fde11eb8d5b4
+  data.tar.gz: 1bcdfe219ef78dadeeaf7a8de8cc71662de4e0066b6bebf9941aa59d86c9349a38e3caf0671693dc321b54b672618e7b9b772994efb48511628f77718345aceb

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.7.0](https://github.com/asjer/rails-worktrees/compare/v0.6.0...v0.7.0) (2026-04-05)
+
+
+### Features
+
+* **wt:** add rerunnable setup workflow ([a609fcc](https://github.com/asjer/rails-worktrees/commit/a609fcc3c463da1d2ad9922b620f9c517dc6ed74))
+
+## [0.6.0](https://github.com/asjer/rails-worktrees/compare/v0.5.1...v0.6.0) (2026-04-03)
+
+
+### Features
+
+* **post-create:** bootstrap new worktrees after creation ([b429105](https://github.com/asjer/rails-worktrees/commit/b42910507d21c1d048d45cfdc4d7311a1ec8a96b))
+
 ## [0.5.1](https://github.com/asjer/rails-worktrees/compare/v0.5.0...v0.5.1) (2026-04-02)
 
 

data/README.md

@@ -42,8 +42,12 @@ With `--yolo`, the installer also:
 ```bash
 bin/wt                          # auto-pick a name from bundled *.txt lists
 bin/wt my-feature               # use an explicit worktree name
+bin/wt --skip-setup my-feature  # create now, run setup later
 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 setup                    # rerun setup for the current checkout/worktree
+bin/wt setup my-feature         # rerun setup for a managed worktree by name
+bin/wt setup ../my-project.worktrees/my-feature # setup a specific checkout without cd-ing into it
 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
@@ -65,6 +69,7 @@ bin/ob --print-url '?from=nav'  # print the resolved URL without opening a brows
 | `-h`, `--help` | Show the help message |
 | `-v`, `--version` | Show the script version |
 | `--dry-run [name]` | Preview worktree creation or cleanup without changing anything |
+| `--skip-setup` | Create a worktree without running setup steps |
 | `--force` | Force branch deletion for `bin/wt remove` / `bin/wt delete` |
 | `--env`, `--print-env <name>` | Preview `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX` |
 
@@ -78,6 +83,7 @@ By default `bin/wt`:
 - auto-picks names from bundled `.txt` files when no explicit name is given
 - retires bundled names so they are not picked twice
 - bootstraps a worktree-local `.env` with deterministic `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX` values
+- runs setup automatically after creation: credential linking, `bundle install`, `yarn install` when applicable, both `db:prepare` steps, test asset precompile, and a final `bin/rails assets:clobber`
 
 ```text
 workspace/
@@ -90,6 +96,32 @@ workspace/
 
 `WT_WORKSPACES_ROOT` or `config.workspace_root` overrides the destination root and uses the layout `<root>/<project>/<name>`.
 
+### Setup command
+
+`bin/wt setup` reruns setup for the **current checkout**. Run it from inside a linked worktree created by `bin/wt`, a worktree created manually with `git worktree`, or a checkout prepared by another tool.
+
+If the checkout was created by `bin/wt`, you can also point at it by managed worktree name from the main app checkout:
+
+```bash
+bin/wt setup my-feature
+```
+
+If you do not want to `cd` first, pass an explicit checkout path:
+
+```bash
+bin/wt setup ../my-project.worktrees/my-feature
+```
+
+This is the recovery path when you want to create first and bootstrap later:
+
+```bash
+bin/wt --skip-setup my-feature
+cd ../my-project.worktrees/my-feature
+bin/wt setup
+```
+
+`bin/wt setup --dry-run` previews the same steps without changing files.
+
 ### Cleanup commands
 
 `bin/wt` also supports cleanup commands for worktrees it manages:
@@ -181,7 +213,7 @@ If your `database.yml` is too custom to patch safely, the installer leaves it al
 When `bin/wt` creates a worktree it writes a worktree-local `.env` with:
 
 - `DEV_PORT` — deterministic port derived from the worktree name via CRC32, rotated through `dev_port_range`, skipping ports already claimed by peer worktrees
-- `WORKTREE_DATABASE_SUFFIX` — derived from the worktree name so the `database.yml` ERB works immediately
+- `WORKTREE_DATABASE_SUFFIX` — derived from the best available worktree identity (managed name when known, otherwise the current branch or checkout basename). When a readable suffix is already claimed by a peer checkout, `bin/wt` appends a short `DEV_PORT`-based token to keep the databases isolated.
 
 Existing `.env` values are never overwritten.
 

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

@@ -16,4 +16,15 @@ Rails.application.config.x.rails_worktrees.tap do |config|
   #   'rails-worktrees',
   #   'used-names.tsv'
   # )
+
+  # Post-create setup steps (run automatically after a new worktree is created)
+  # config.post_create_command = nil    # nil = built-in steps; false = skip all; 'script/worktree-setup' = custom command
+  # config.run_bundle_install = true
+  # config.run_yarn_install = true      # auto-skipped when yarn.lock is absent
+  # config.run_db_prepare = true
+  # config.run_test_db_prepare = true
+  # config.run_test_assets_precompile = true
+  # config.link_credential_keys = true  # link development.key from a sibling worktree (opt-out)
+  # config.link_test_credential_key = false
+  # config.link_production_credential_key = false
 end

data/lib/rails/worktrees/cli.rb

@@ -3,7 +3,8 @@ module Rails
     # 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
+      LOADER_IGNORED_FLAGS = %w[--dry-run --force --skip-setup].freeze
+      SETUP_SUBCOMMAND = 'setup'.freeze
 
       def initialize(
         argv: ARGV,
@@ -29,11 +30,17 @@ module Rails
       private
 
       def load_project_configuration(configuration)
-        ::Rails::Worktrees::ProjectConfigurationLoader.new(root: @cwd, configuration: configuration).call
+        ::Rails::Worktrees::ProjectConfigurationLoader.new(root: configuration_root, configuration: configuration).call
       rescue StandardError, ScriptError => e
         raise ::Rails::Worktrees::Error, "Failed to load worktrees configuration: #{e.class}: #{e.message}"
       end
 
+      def configuration_root
+        return expand_setup_target_path if explicit_setup_path_target?
+
+        @cwd
+      end
+
       def should_load_project_configuration?
         argv_without_flags.empty? || !loader_optional_command?(argv_without_flags.first)
       end
@@ -46,6 +53,19 @@ module Rails
         LOADER_OPTIONAL_COMMANDS.include?(command)
       end
 
+      def explicit_setup_path_target?
+        argv_without_flags.first == SETUP_SUBCOMMAND && argv_without_flags.length == 2 &&
+          path_like_setup_target?(argv_without_flags.last)
+      end
+
+      def expand_setup_target_path
+        File.expand_path(argv_without_flags.last, @cwd)
+      end
+
+      def path_like_setup_target?(value)
+        value.start_with?('/', '.', '~') || value.include?(File::SEPARATOR)
+      end
+
       def command_for(configuration)
         Command.new(argv: @argv, io: @io, env: @env, cwd: @cwd, configuration: configuration)
       end

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

@@ -20,6 +20,7 @@ module Rails
           EnvBootstrapper.new(
             target_dir: context[:target_dir],
             worktree_name: context[:worktree_name],
+            peer_roots: context.fetch(:peer_roots) { peer_roots_excluding(context[:target_dir]) },
             configuration: @configuration
           )
         end

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

@@ -30,9 +30,11 @@ module Rails
             Create and clean up Git worktrees for the current repository.
 
             Usage: wt [worktree-name]
+                   wt [--skip-setup] [worktree-name]
                    wt --dry-run [worktree-name]
                    wt --print-env <worktree-name>
                    wt doctor
+                   wt setup [--dry-run] [path|name]
                    wt update [--dry-run]
                    wt remove [--dry-run] [--force] <worktree-name>
                    wt delete [--dry-run] [--force] <worktree-name>
@@ -42,6 +44,7 @@ module Rails
               -h, --help                  Show this help message
               -v, --version               Show the script version
               --dry-run [name]            Preview worktree creation or cleanup without changing anything
+              --skip-setup               Create the worktree without running setup steps
               --force                     Delete an unmerged local branch with wt remove/delete
               --env, --print-env <name>   Preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
 
@@ -49,8 +52,12 @@ module Rails
               wt                 Auto-pick a name from a bundled *.txt list
               wt my-feature      Use an explicit worktree name
               wt --dry-run my-feature
+              wt --skip-setup my-feature
               wt --print-env my-feature
               wt doctor
+              wt setup
+              wt setup my-feature
+              wt setup ../my-project.worktrees/my-feature
               wt update --dry-run
               wt remove my-feature
               wt remove --force my-feature
@@ -61,6 +68,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
+              - by default wt <name> both creates the worktree and runs setup automatically
+              - wt setup reruns setup for the current checkout, a managed worktree name, or a specific checkout path, including manually-created worktrees
               - 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

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

@@ -0,0 +1,34 @@
+module Rails
+  module Worktrees
+    class Command
+      # Delegates post-create setup steps to PostCreateRunner.
+      module PostCreateSupport
+        private
+
+        def run_post_create_steps(context, bootstrapped_env: nil)
+          post_create_runner_for(context, bootstrapped_env: bootstrapped_env).call(dry_run: false)
+        end
+
+        def preview_post_create_steps(context, bootstrapped_env: nil)
+          post_create_runner_for(context, bootstrapped_env: bootstrapped_env).call(dry_run: true)
+        end
+
+        def post_create_runner_for(context, bootstrapped_env: nil)
+          PostCreateRunner.new(
+            target_dir: context[:target_dir],
+            peer_roots: context.fetch(:peer_roots) { peer_roots_excluding(context[:target_dir]) },
+            configuration: @configuration,
+            bootstrapped_env: bootstrapped_env,
+            io: { stdout: @stdout, stderr: @stderr }
+          )
+        end
+
+        def peer_roots_excluding(target_dir)
+          worktree_entries
+            .map { |entry| entry[:path] }
+            .reject { |path| path == target_dir }
+        end
+      end
+    end
+  end
+end

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

@@ -7,7 +7,19 @@ module Rails
 
         def resolve_repository_context
           current_root = canonical_path(git_capture('rev-parse', '--show-toplevel').strip)
-          common_dir = expand_git_path(git_capture('rev-parse', '--git-common-dir').strip)
+          common_dir = expand_git_path(git_capture('rev-parse', '--git-common-dir').strip, base_dir: @cwd)
+          primary_root = primary_checkout_root_for(current_root, common_dir)
+
+          repository_context_for(current_root, primary_root)
+        end
+
+        def resolve_repository_context_for(path)
+          expanded_path = File.expand_path(path, @cwd)
+          current_root = canonical_path(git_capture('-C', expanded_path, 'rev-parse', '--show-toplevel').strip)
+          common_dir = expand_git_path(
+            git_capture('-C', expanded_path, 'rev-parse', '--git-common-dir').strip,
+            base_dir: expanded_path
+          )
           primary_root = primary_checkout_root_for(current_root, common_dir)
 
           repository_context_for(current_root, primary_root)
@@ -66,10 +78,10 @@ module Rails
           canonical_path(File.dirname(common_dir))
         end
 
-        def expand_git_path(path)
+        def expand_git_path(path, base_dir: @cwd)
           return path if path.start_with?('/')
 
-          File.expand_path(path, @cwd)
+          File.expand_path(path, base_dir)
         end
 
         def present_path?(path)

data/lib/rails/worktrees/command.rb

@@ -3,6 +3,7 @@ require_relative 'command/environment_support'
 require_relative 'command/git_operations'
 require_relative 'command/name_picking'
 require_relative 'command/output'
+require_relative 'command/post_create_support'
 require_relative 'command/workspace_paths'
 
 module Rails
@@ -12,12 +13,14 @@ module Rails
     class Command
       REMOVE_SUBCOMMANDS = %w[remove delete].freeze
       DOCTOR_SUBCOMMAND = 'doctor'.freeze
+      SETUP_SUBCOMMAND = 'setup'.freeze
       UPDATE_SUBCOMMAND = 'update'.freeze
 
       include GitOperations
       include EnvironmentSupport
       include NamePicking
       include Output
+      include PostCreateSupport
       include WorkspacePaths
 
       def initialize(argv:, io:, env:, cwd:, configuration:)
@@ -47,9 +50,12 @@ module Rails
 
       def force? = @force
 
+      def skip_setup? = @skip_setup
+
       def extract_flags!
         @dry_run = extract_flag!('--dry-run')
         @force = extract_flag!('--force')
+        @skip_setup = extract_flag!('--skip-setup')
       end
 
       def extract_flag!(flag)
@@ -75,20 +81,37 @@ module Rails
         @argv.first == DOCTOR_SUBCOMMAND
       end
 
+      def setup_subcommand?
+        @argv.first == SETUP_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?
+        handler = requested_command_handler
+        return handler.call if handler
+        return usage_error if invalid_worktree_command?
 
         execute_worktree_command
       end
 
+      def requested_command_handler
+        case @argv.first
+        when DOCTOR_SUBCOMMAND then -> { execute_doctor_command }
+        when SETUP_SUBCOMMAND then -> { execute_setup_command }
+        when UPDATE_SUBCOMMAND then -> { execute_update_command }
+        when 'prune' then -> { execute_prune_command }
+        else
+          -> { execute_remove_command } if remove_subcommand?
+        end
+      end
+
+      def invalid_worktree_command?
+        @argv.length > 1 || force?
+      end
+
       def execute_worktree_command
         require_git_repo
         announce_dry_run if dry_run?
@@ -105,6 +128,16 @@ module Rails
         finish(context)
       end
 
+      def execute_setup_command
+        validate_setup_args!
+        announce_dry_run if dry_run?
+
+        context = resolve_setup_context(target_reference: setup_target_reference)
+        validate_setup_target!(context)
+
+        complete_setup_flow(context, success_message: 'Setup complete')
+      end
+
       def execute_remove_command
         require_git_repo
         announce_dry_run if dry_run?
@@ -208,17 +241,26 @@ module Rails
       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?
+        raise Error, 'The --skip-setup flag is only supported when creating a worktree.' if skip_setup?
       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?
+        raise Error, 'The --skip-setup flag is only supported when creating a worktree.' if skip_setup?
+      end
+
+      def validate_setup_args!
+        raise Error, 'Usage: wt setup [--dry-run] [path|name]' unless [1, 2].include?(@argv.length)
+        raise Error, 'The --force flag is only supported with wt remove.' if force?
+        raise Error, 'The --skip-setup flag is only supported when creating a worktree.' if skip_setup?
       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?
+        raise Error, 'The --skip-setup flag is only supported when creating a worktree.' if skip_setup?
       end
 
       def announce_prune_candidates(candidates)
@@ -256,6 +298,60 @@ module Rails
         )
       end
 
+      def resolve_setup_context(target_reference: nil, repository: nil)
+        if setup_target_name?(target_reference)
+          return resolve_named_setup_context(target_reference, repository: repository)
+        end
+
+        resolve_path_setup_context(target_reference, repository: repository)
+      end
+
+      def resolve_path_setup_context(target_reference, repository: nil)
+        target_dir = resolved_setup_target_path(target_reference)
+        repository ||= target_reference ? resolve_repository_context_for(target_dir) : resolve_repository_context
+        branch_name = current_checkout_branch_at(target_dir)
+
+        repository.merge(
+          worktree_name: setup_identity_for(repository[:current_root], branch_name),
+          branch_name: display_branch_name(branch_name, target_dir: repository[:current_root]),
+          target_dir: repository[:current_root],
+          peer_roots: peer_roots_for(repository[:current_root])
+        )
+      end
+
+      def resolve_named_setup_context(worktree_name, repository: nil)
+        repository ||= resolve_repository_context
+        context = resolve_worktree_context(explicit_worktree_name: worktree_name, repository: repository)
+        branch_name = resolved_named_setup_branch_name(context)
+
+        context.merge(
+          branch_name: display_branch_name(branch_name, target_dir: context[:target_dir]),
+          peer_roots: peer_roots_for(context[:target_dir])
+        )
+      end
+
+      def resolved_named_setup_branch_name(context)
+        return context[:branch_name] unless File.directory?(context[:target_dir])
+
+        current_checkout_branch_at(context[:target_dir])
+      end
+
+      def setup_target_reference = @argv[1]
+
+      def setup_target_name?(target_reference)
+        !target_reference.nil? && !path_like_setup_target?(target_reference)
+      end
+
+      def resolved_setup_target_path(target_path)
+        return @cwd if target_path.nil?
+
+        File.expand_path(target_path, @cwd)
+      end
+
+      def path_like_setup_target?(target_reference)
+        target_reference.start_with?('/', '.', '~') || target_reference.include?(File::SEPARATOR)
+      end
+
       def resolved_worktree_name(project_name, workspaces, explicit_worktree_name)
         return validate_worktree_name(explicit_worktree_name) if explicit_worktree_name
 
@@ -283,14 +379,52 @@ module Rails
 
       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?
+        complete_setup_flow(
+          context,
+          success_message: skip_setup? ? 'Worktree created' : 'Worktree ready',
+          run_post_create: !skip_setup?
+        )
+      end
 
-        success('Worktree ready')
+      def complete_dry_run_after_setup(context, bootstrap_result, run_post_create: true)
+        preview_post_create_steps(context, bootstrapped_env: bootstrap_result&.values) if run_post_create
+        info('Would skip setup steps; run `wt setup` inside the checkout when you are ready.') unless run_post_create
+        complete_dry_run(context, env_values: bootstrap_result&.values)
+      end
+
+      def complete_created_worktree(context, bootstrap_result, success_message:, run_post_create: true)
+        unless run_post_create
+          return complete_created_worktree_without_setup(context, bootstrap_result, success_message)
+        end
+
+        result = run_post_create_steps(context, bootstrapped_env: bootstrap_result&.values)
+        return result unless result.zero?
+
+        success(success_message)
         print_context_summary(context, env_values: bootstrap_result&.values)
         0
       end
 
+      def complete_created_worktree_without_setup(context, bootstrap_result, success_message)
+        success(success_message)
+        print_context_summary(context, env_values: bootstrap_result&.values)
+        info('Setup skipped. Run `wt setup` inside the checkout when you are ready.')
+        0
+      end
+
+      def complete_setup_flow(context, success_message:, run_post_create: true)
+        bootstrap_result = bootstrap_worktree_environment(context)
+
+        return complete_dry_run_after_setup(context, bootstrap_result, run_post_create: run_post_create) if dry_run?
+
+        complete_created_worktree(
+          context,
+          bootstrap_result,
+          success_message: success_message,
+          run_post_create: run_post_create
+        )
+      end
+
       def finish_reuse(context)
         target, branch = context.values_at(:target_dir, :branch_name)
 
@@ -323,6 +457,78 @@ module Rails
         "#{@configuration.branch_prefix}/#{worktree_name}"
       end
 
+      def validate_setup_target!(context)
+        raise Error, "Setup target does not exist: #{context[:target_dir]}" unless File.directory?(context[:target_dir])
+
+        rails_bin = File.join(context[:target_dir], 'bin', 'rails')
+
+        unless File.exist?(rails_bin)
+          raise Error,
+                "Setup target does not look like a Rails app. Expected #{rails_bin} to exist before running wt setup."
+        end
+
+        return if registered_worktree_path_for_setup?(context[:target_dir])
+
+        warning(
+          'Current checkout is not registered in git worktree list; peer credential key discovery may be limited.'
+        )
+      end
+
+      def current_checkout_branch_at(target_dir)
+        git_capture('-C', target_dir, 'branch', '--show-current', allow_failure: true).strip
+      end
+
+      def registered_worktree_path_for_setup?(target_dir)
+        normalized_target = canonical_path(target_dir)
+
+        worktree_entries_for_checkout(target_dir).any? { |entry| entry[:path] == normalized_target }
+      end
+
+      def peer_roots_for(target_dir)
+        normalized_target = canonical_path(target_dir)
+
+        worktree_entries_for_checkout(target_dir)
+          .map { |entry| entry[:path] }
+          .reject { |path| path == normalized_target }
+      end
+
+      def worktree_entries_for_checkout(target_dir)
+        git_capture('-C', target_dir, 'worktree', 'list', '--porcelain', allow_failure: true)
+          .split("\n\n")
+          .filter_map do |block|
+            entry = parse_worktree_entry(block)
+            entry[:path] ? entry : nil
+          end
+      end
+
+      def setup_identity_for(target_dir, branch_name)
+        stripped_branch = worktree_identity_from_branch(branch_name)
+        return stripped_branch unless stripped_branch.empty?
+
+        File.basename(target_dir)
+      end
+
+      def worktree_identity_from_branch(branch_name)
+        branch_name = branch_name.to_s.strip
+        return '' if branch_name.empty?
+
+        worktree_name_for_branch(branch_name)
+      end
+
+      def display_branch_name(branch_name, target_dir: nil)
+        branch_name = branch_name.to_s.strip
+        return branch_name unless branch_name.empty?
+
+        git_args = if target_dir.to_s.strip.empty?
+                     ['rev-parse', '--short', 'HEAD']
+                   else
+                     ['-C', target_dir, 'rev-parse', '--short', 'HEAD']
+                   end
+
+        short_sha = git_capture(*git_args, allow_failure: true).strip
+        short_sha.empty? ? '(detached HEAD)' : "(detached HEAD at #{short_sha})"
+      end
+
       def ensure_removable!(context, worktree_exists:, branch_exists:)
         ensure_remove_target_exists!(context, worktree_exists: worktree_exists, branch_exists: branch_exists)
         ensure_not_removing_protected_checkout!(context)

data/lib/rails/worktrees/configuration.rb

@@ -10,6 +10,15 @@ module Rails
         name_sources_path
         used_names_file
         worktree_database_suffix_max_length
+        post_create_command
+        run_bundle_install
+        run_yarn_install
+        run_db_prepare
+        run_test_db_prepare
+        run_test_assets_precompile
+        link_credential_keys
+        link_test_credential_key
+        link_production_credential_key
       ].freeze
 
       DEFAULT_BOOTSTRAP_ENV = true
@@ -25,9 +34,20 @@ module Rails
 
       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
+                    :worktree_database_suffix_max_length,
+                    :post_create_command,
+                    :run_bundle_install, :run_yarn_install,
+                    :run_db_prepare, :run_test_db_prepare, :run_test_assets_precompile,
+                    :link_credential_keys, :link_test_credential_key, :link_production_credential_key
 
       def initialize
+        assign_core_defaults
+        assign_post_create_defaults
+      end
+
+      private
+
+      def assign_core_defaults
         @bootstrap_env = DEFAULT_BOOTSTRAP_ENV
         @workspace_root = nil
         @branch_prefix = DEFAULT_BRANCH_PREFIX
@@ -38,7 +58,17 @@ module Rails
         @legacy_used_names_files = default_legacy_used_names_files
       end
 
-      private
+      def assign_post_create_defaults
+        @post_create_command = nil
+        @run_bundle_install = true
+        @run_yarn_install = true
+        @run_db_prepare = true
+        @run_test_db_prepare = true
+        @run_test_assets_precompile = true
+        @link_credential_keys = true
+        @link_test_credential_key = false
+        @link_production_credential_key = false
+      end
 
       def default_legacy_used_names_files
         state_home = ENV.fetch('XDG_STATE_HOME', File.join(Dir.home, '.local/state'))

data/lib/rails/worktrees/credential_key_linker.rb

@@ -0,0 +1,93 @@
+require 'fileutils'
+
+module Rails
+  module Worktrees
+    # Links credential key files from a sibling worktree into the new worktree.
+    class CredentialKeyLinker
+      Result = Struct.new(:messages)
+
+      CREDENTIALS_DIR = 'config/credentials'.freeze
+
+      KEY_TYPES = [
+        { name: 'development', config_attr: :link_credential_keys },
+        { name: 'test',        config_attr: :link_test_credential_key },
+        { name: 'production',  config_attr: :link_production_credential_key }
+      ].freeze
+
+      def initialize(target_dir:, peer_roots:, configuration:)
+        @target_dir = target_dir
+        @peer_roots = peer_roots
+        @configuration = configuration
+      end
+
+      def call(dry_run: false)
+        messages = []
+
+        KEY_TYPES.each do |key_type|
+          next unless @configuration.public_send(key_type[:config_attr])
+
+          message = process_key(key_type[:name], dry_run: dry_run)
+          messages << message if message
+        end
+
+        Result.new(messages)
+      end
+
+      private
+
+      def process_key(key_name, dry_run:)
+        destination = destination_path_for(key_name)
+        existing_message = existing_destination_message(destination, key_name)
+        return existing_message if existing_message
+
+        replace_existing_symlink = File.symlink?(destination)
+        return "#{key_name}.key already exists; leaving as-is" if File.exist?(destination)
+
+        source = find_source(key_name)
+        return "Could not find source for #{key_name}.key" unless source
+
+        link_key(destination, key_name, source, dry_run: dry_run, replace_existing_symlink: replace_existing_symlink)
+      end
+
+      def find_source(key_name)
+        @peer_roots.each do |peer_root|
+          candidate = File.join(peer_root, CREDENTIALS_DIR, "#{key_name}.key")
+          next if File.expand_path(peer_root) == File.expand_path(@target_dir)
+
+          return candidate if File.file?(candidate)
+        end
+
+        nil
+      end
+
+      def destination_path_for(key_name)
+        File.join(@target_dir, CREDENTIALS_DIR, "#{key_name}.key")
+      end
+
+      def existing_destination_message(destination, key_name)
+        return unless File.symlink?(destination) && File.exist?(destination)
+
+        "#{key_name}.key already linked"
+      end
+
+      def link_key(destination, key_name, source, dry_run:, replace_existing_symlink: false)
+        return dry_run_link_message(key_name, source, replace_existing_symlink) if dry_run
+
+        FileUtils.mkdir_p(File.dirname(destination))
+        FileUtils.rm_f(destination) if replace_existing_symlink
+        File.symlink(source, destination)
+        linked_key_message(key_name, source, replace_existing_symlink)
+      end
+
+      def dry_run_link_message(key_name, source, replace_existing_symlink)
+        verb = replace_existing_symlink ? 'Would relink' : 'Would link'
+        "#{verb} #{key_name}.key → #{source}"
+      end
+
+      def linked_key_message(key_name, source, replace_existing_symlink)
+        verb = replace_existing_symlink ? 'Relinked' : 'Linked'
+        "#{verb} #{key_name}.key → #{source}"
+      end
+    end
+  end
+end

data/lib/rails/worktrees/env_bootstrapper.rb

@@ -14,10 +14,11 @@ module Rails
 
       ENV_FILE_NAME = '.env'.freeze
 
-      def initialize(target_dir:, worktree_name:, configuration:)
+      def initialize(target_dir:, worktree_name:, configuration:, peer_roots: nil)
         @target_dir = target_dir
         @worktree_name = worktree_name
         @configuration = configuration
+        @peer_roots = peer_roots.nil? ? nil : Array(peer_roots).compact
       end
 
       def call(dry_run: false)
@@ -46,10 +47,12 @@ module Rails
       def existing_env_lines = File.exist?(env_path) ? File.readlines(env_path, chomp: true) : []
 
       def resolved_values(lines)
+        dev_port = (env_value(lines, 'DEV_PORT') || allocate_dev_port).to_s
+
         {
-          'DEV_PORT' => (env_value(lines, 'DEV_PORT') || allocate_dev_port).to_s,
+          'DEV_PORT' => dev_port,
           'WORKTREE_DATABASE_SUFFIX' => env_value(lines, 'WORKTREE_DATABASE_SUFFIX') ||
-            format_worktree_database_suffix(@worktree_name)
+            allocate_worktree_database_suffix(dev_port: dev_port)
         }
       end
 
@@ -108,8 +111,7 @@ module Rails
       end
 
       def claimed_peer_ports
-        Dir.glob(File.join(peers_root, '*')).filter_map do |path|
-          next unless File.directory?(path)
+        peer_paths.filter_map do |path|
           next if File.expand_path(path) == File.expand_path(@target_dir)
 
           port = env_value(peer_env_lines(path), 'DEV_PORT')
@@ -126,8 +128,21 @@ module Rails
 
       def peers_root = File.dirname(@target_dir)
 
+      def peer_paths
+        return @peer_roots unless @peer_roots.nil?
+
+        Dir.glob(File.join(peers_root, '*')).select { |path| File.directory?(path) }
+      end
+
       def configured_port_range = @configuration.dev_port_range
 
+      def allocate_worktree_database_suffix(dev_port:)
+        base_candidate = format_worktree_database_suffix(@worktree_name)
+        return base_candidate unless claimed_peer_suffixes.include?(base_candidate)
+
+        suffix_with_token(@worktree_name, dev_port.to_s)
+      end
+
       def format_worktree_database_suffix(value)
         suffix = value.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/\A_+|_+\z/, '').squeeze('_')
         suffix = suffix[0, @configuration.worktree_database_suffix_max_length]
@@ -136,6 +151,35 @@ module Rails
         "_#{suffix}"
       end
 
+      def suffix_with_token(value, token)
+        slug = normalized_suffix_slug(value)
+        normalized_token = token.to_s.downcase.gsub(/[^a-z0-9]+/, '')
+        max_length = @configuration.worktree_database_suffix_max_length
+        available_slug_length = max_length - normalized_token.length - 1
+
+        composed_slug = if available_slug_length.positive?
+                          [slug[0, available_slug_length], normalized_token].reject(&:empty?).join('_')
+                        else
+                          normalized_token[0, max_length]
+                        end
+
+        format_worktree_database_suffix(composed_slug)
+      end
+
+      def normalized_suffix_slug(value)
+        slug = value.to_s.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/\A_+|_+\z/, '').squeeze('_')
+        slug.empty? ? 'worktree' : slug
+      end
+
+      def claimed_peer_suffixes
+        peer_paths.each_with_object(Set.new) do |path, suffixes|
+          next if File.expand_path(path) == File.expand_path(@target_dir)
+
+          suffix = env_value(peer_env_lines(path), 'WORKTREE_DATABASE_SUFFIX')
+          suffixes << suffix if suffix
+        end
+      end
+
       def formatted_updates(updates) = updates.map { |key, value| "#{key}=#{value}" }.join(', ')
 
       def display_path(path)

data/lib/rails/worktrees/mise_environment.rb

@@ -0,0 +1,87 @@
+require 'json'
+require 'open3'
+
+module Rails
+  module Worktrees
+    # Resolves runtime environment variables from mise for setup subprocesses.
+    class MiseEnvironment
+      Result = Struct.new(:env, :messages)
+
+      CONFIG_FILES = %w[mise.toml .mise.toml].freeze
+
+      def initialize(target_dir:, env:)
+        @target_dir = target_dir
+        @env = env
+      end
+
+      def call
+        return Result.new(env: {}, messages: []) unless mise_available?
+
+        messages = []
+        trust_config!(messages)
+        env = resolved_env
+        messages << '🧰 Activating mise toolchain...' if project_config_file || !env.empty?
+
+        Result.new(env: env, messages: messages.uniq)
+      end
+
+      private
+
+      def mise_available?
+        _stdout_str, _stderr_str, status = Open3.capture3(@env, 'mise', '--version', chdir: @target_dir)
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      def trust_config!(messages)
+        config_file = project_config_file
+        return unless config_file
+
+        messages << '🔐 Trusting mise config...'
+
+        ensure_trusted!(config_file)
+      end
+
+      def ensure_trusted!(config_file)
+        _stdout_str, stderr_str, status = Open3.capture3(
+          @env,
+          'mise',
+          'trust',
+          config_file,
+          chdir: @target_dir
+        )
+
+        return if status.success?
+
+        raise Error, "mise trust failed: #{command_error(stderr_str)}"
+      end
+
+      def resolved_env
+        @resolved_env ||= begin
+          stdout_str, stderr_str, status = Open3.capture3(@env, 'mise', 'env', '--json', chdir: @target_dir)
+          raise Error, "mise env --json failed: #{command_error(stderr_str)}" unless status.success?
+
+          JSON.parse(stdout_str).each_with_object({}) do |(key, value), env|
+            next if value.nil?
+
+            env[key] = value.to_s
+          end
+        rescue JSON::ParserError => e
+          raise Error, "mise env --json returned invalid JSON: #{e.message}"
+        end
+      end
+
+      def project_config_file
+        @project_config_file ||= CONFIG_FILES
+                                 .map { |file_name| File.join(@target_dir, file_name) }
+                                 .find { |path| File.file?(path) }
+      end
+
+      def command_error(stderr_str)
+        message = stderr_str.to_s.strip
+        message.empty? ? 'unknown error' : message
+      end
+    end
+  end
+end

data/lib/rails/worktrees/post_create_runner.rb

@@ -0,0 +1,225 @@
+require 'open3'
+
+module Rails
+  module Worktrees
+    # Runs post-create setup steps in a newly created worktree.
+    # Steps run in order: credential linking, bundle install, yarn install,
+    # db:prepare (development), db:prepare (test), assets:precompile (test), assets:clobber.
+    # rubocop:disable Metrics/ClassLength
+    class PostCreateRunner
+      STEPS = [
+        { id: :bundle, argv: %w[bundle install],
+          header: '📦 Installing gems...' },
+        { id: :yarn, argv: %w[yarn install],
+          header: '🧶 Installing JS dependencies...' },
+        { id: :db_prepare, argv: %w[bin/rails db:prepare],
+          header: '🗄️  Preparing development database...', env: { 'RAILS_ENV' => 'development' } },
+        { id: :test_db_prepare, argv: %w[bin/rails db:prepare],
+          header: '🗄️  Preparing test database...', env: { 'RAILS_ENV' => 'test' } },
+        { id: :test_assets_precompile, argv: %w[bin/rails assets:precompile],
+          header: '🎨 Precompiling test assets...', env: { 'RAILS_ENV' => 'test' } },
+        { id: :assets_clobber, argv: %w[bin/rails assets:clobber],
+          header: '🧹 Clobbering compiled assets...' }
+      ].freeze
+
+      STEP_CONFIG = {
+        bundle: :run_bundle_install,
+        yarn: :run_yarn_install,
+        db_prepare: :run_db_prepare,
+        test_db_prepare: :run_test_db_prepare,
+        test_assets_precompile: :run_test_assets_precompile,
+        assets_clobber: :run_test_assets_precompile
+      }.freeze
+
+      def initialize(target_dir:, peer_roots:, configuration:, io:, bootstrapped_env: nil)
+        @target_dir    = target_dir
+        @peer_roots    = peer_roots
+        @configuration = configuration
+        @bootstrapped_env = (bootstrapped_env || {}).transform_values(&:to_s)
+        @stdout        = io.fetch(:stdout)
+        @stderr        = io.fetch(:stderr)
+      end
+
+      def call(dry_run: false)
+        return 0 if @configuration.post_create_command == false
+
+        @runtime_env = resolved_runtime_env(dry_run: dry_run)
+
+        return run_custom_command(dry_run: dry_run) if custom_command?
+
+        run_built_in_steps(dry_run: dry_run)
+      rescue Error => e
+        @stderr.puts("❌ #{e.message}")
+        1
+      end
+
+      private
+
+      def custom_command?
+        @configuration.post_create_command.is_a?(String) && !@configuration.post_create_command.empty?
+      end
+
+      def run_custom_command(dry_run:)
+        command = @configuration.post_create_command
+
+        if dry_run
+          info("Would run: #{command}")
+          return 0
+        end
+
+        info("Running: #{command}")
+        stream_shell_command(command)
+      end
+
+      def run_built_in_steps(dry_run:)
+        result = run_credential_linking(dry_run: dry_run)
+        return result unless result.zero?
+
+        STEPS.each do |step|
+          config_attr = STEP_CONFIG[step[:id]]
+          next unless @configuration.public_send(config_attr)
+          next if step[:id] == :yarn && !yarn_lock_present?
+
+          result = run_step(step, dry_run: dry_run)
+          return result unless result.zero?
+        end
+
+        0
+      end
+
+      def run_credential_linking(dry_run:)
+        # Missing peer key files are intentionally best-effort and should not abort
+        # worktree setup; the linker reports those cases in its messages while real
+        # filesystem errors still raise out of `credential_key_linker.call`.
+        return 0 unless credential_linking_enabled?
+
+        info('🔑 Linking credential keys...')
+
+        result = credential_key_linker.call(dry_run: dry_run)
+        print_credential_linking_messages(result)
+
+        0
+      end
+
+      def run_step(step, dry_run:)
+        if dry_run
+          info("Would run: #{display_command(step)}")
+          return 0
+        end
+
+        info(step[:header])
+        stream_step_command(step)
+      end
+
+      def stream_shell_command(command)
+        exit_status = capture_shell_command_exit_status(command)
+        report_failed_command(command, exit_status) unless exit_status.zero?
+        exit_status
+      end
+
+      def stream_step_command(step)
+        command = display_command(step)
+        exit_status = capture_step_command_exit_status(step)
+        report_failed_command(command, exit_status) unless exit_status.zero?
+        exit_status
+      end
+
+      def capture_shell_command_exit_status(command)
+        exit_status = nil
+
+        Open3.popen2e(runtime_env, command, chdir: @target_dir) do |_stdin, output, wait_thread|
+          output.each_line { |line| @stdout.print(line) }
+          exit_status = wait_thread.value.exitstatus
+        end
+
+        exit_status
+      rescue StandardError => e
+        report_failed_command_start(command, e)
+        1
+      end
+
+      def capture_step_command_exit_status(step)
+        exit_status = nil
+
+        Open3.popen2e(*step_command(step), chdir: @target_dir) do |_stdin, output, wait_thread|
+          output.each_line { |line| @stdout.print(line) }
+          exit_status = wait_thread.value.exitstatus
+        end
+
+        exit_status
+      rescue StandardError => e
+        report_failed_command_start(display_command(step), e)
+        1
+      end
+
+      def shell_env
+        # Pass through only the essentials so subprocess tools work correctly.
+        ENV.to_h.slice('PATH', 'HOME', 'LANG', 'TERM', 'SHELL',
+                       'BUNDLE_GEMFILE', 'BUNDLE_PATH', 'GEM_HOME', 'GEM_PATH',
+                       'RUBY_VERSION', 'RAILS_ENV', 'NODE_ENV',
+                       'XDG_STATE_HOME', 'XDG_DATA_HOME', 'XDG_CONFIG_HOME',
+                       'DEV_PORT', 'WORKTREE_DATABASE_SUFFIX')
+      end
+
+      attr_reader :runtime_env
+
+      def resolved_runtime_env(dry_run:)
+        env = shell_env.merge(@bootstrapped_env)
+        return env if dry_run
+
+        env.merge(toolchain_env)
+      end
+
+      def toolchain_env
+        result = MiseEnvironment.new(target_dir: @target_dir, env: shell_env.merge(@bootstrapped_env)).call
+        result.messages.each { |message| info(message) }
+        result.env
+      end
+
+      def yarn_lock_present?
+        File.exist?(File.join(@target_dir, 'yarn.lock'))
+      end
+
+      def display_command(step)
+        env_prefix = step.fetch(:env, {}).map { |key, value| "#{key}=#{value}" }.join(' ')
+        command = step.fetch(:argv).join(' ')
+        [env_prefix, command].reject(&:empty?).join(' ')
+      end
+
+      def step_command(step)
+        [runtime_env.merge(step.fetch(:env, {})), *step.fetch(:argv)]
+      end
+
+      def info(message)
+        @stdout.puts("→ #{message}")
+      end
+
+      def report_failed_command(command, exit_status)
+        @stderr.puts("❌ Command failed (exit #{exit_status}): #{command}")
+      end
+
+      def report_failed_command_start(command, error)
+        @stderr.puts("❌ Command failed to start: #{command} (#{error.message})")
+      end
+
+      def credential_linking_enabled?
+        @configuration.link_credential_keys ||
+          @configuration.link_test_credential_key ||
+          @configuration.link_production_credential_key
+      end
+
+      def credential_key_linker
+        CredentialKeyLinker.new(
+          target_dir: @target_dir,
+          peer_roots: @peer_roots,
+          configuration: @configuration
+        )
+      end
+
+      def print_credential_linking_messages(result)
+        result.messages.each { |message| info("   #{message}") }
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rails/worktrees/version.rb

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

data/lib/rails/worktrees.rb

@@ -3,7 +3,10 @@ require 'pathname'
 require_relative 'worktrees/version'
 require_relative 'worktrees/configuration'
 require_relative 'worktrees/application_configuration'
+require_relative 'worktrees/mise_environment'
 require_relative 'worktrees/env_bootstrapper'
+require_relative 'worktrees/credential_key_linker'
+require_relative 'worktrees/post_create_runner'
 require_relative 'worktrees/command'
 require_relative 'worktrees/cli'
 require_relative 'worktrees/browser_command'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-worktrees
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Asjer Querido
@@ -63,13 +63,17 @@ files:
 - lib/rails/worktrees/command/git_operations.rb
 - lib/rails/worktrees/command/name_picking.rb
 - lib/rails/worktrees/command/output.rb
+- lib/rails/worktrees/command/post_create_support.rb
 - lib/rails/worktrees/command/workspace_paths.rb
 - lib/rails/worktrees/configuration.rb
+- lib/rails/worktrees/credential_key_linker.rb
 - lib/rails/worktrees/database_config_updater.rb
 - lib/rails/worktrees/env_bootstrapper.rb
 - lib/rails/worktrees/initializer_updater.rb
+- lib/rails/worktrees/mise_environment.rb
 - lib/rails/worktrees/mise_toml_updater.rb
 - lib/rails/worktrees/names/cities.txt
+- lib/rails/worktrees/post_create_runner.rb
 - lib/rails/worktrees/procfile_updater.rb
 - lib/rails/worktrees/project_configuration_loader.rb
 - lib/rails/worktrees/project_maintenance.rb