rails-worktrees 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de8cd30214f81e827aee0e2fabba426a1c0cfca6f172d03fb36fad408fc8bfe7
-  data.tar.gz: 604eb3468c743e91b3b5ad19f9943fa94d9fe891b45732de491ddc8219c4b943
+  metadata.gz: e86a789b2e56f07d95a626b67c9fafbf01862e9c8496043107914b4446e13702
+  data.tar.gz: 9f0dce854a6c7a20dfedb00dd181f7ecc5699ae6cf86ff61d24d60bce80be11e
 SHA512:
-  metadata.gz: 8f33f141355afb0dbc9ee06cdaab2e2f242c7d49b7ac72b6c2aa21202aabc8fb709cf79aa88a0b43f2357240b19b88dab37cc284f3fd4f712cc2b6c1057b743b
-  data.tar.gz: c9bc8caa8f38b496e2d7dd4bc0693251ec18606863b349cf949398e2cc131c448277869e04ac873e80f8b3dfff3f1fc59604e7ba2207fff21a97c255376524f3
+  metadata.gz: 16513989c4364e4cf37d4eb0cf1fbde3fc95d8aa246223b5e9cca20da0035266d8f33e81a115d83b95b359ff93292796ba88889f06495c9d8b39fde11eb8d5b4
+  data.tar.gz: 1bcdfe219ef78dadeeaf7a8de8cc71662de4e0066b6bebf9941aa59d86c9349a38e3caf0671693dc321b54b672618e7b9b772994efb48511628f77718345aceb

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

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/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

@@ -5,19 +5,20 @@ module Rails
       module PostCreateSupport
         private
 
-        def run_post_create_steps(context)
-          post_create_runner_for(context).call(dry_run: false)
+        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)
-          post_create_runner_for(context).call(dry_run: true)
+        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)
+        def post_create_runner_for(context, bootstrapped_env: nil)
           PostCreateRunner.new(
             target_dir: context[:target_dir],
-            peer_roots: peer_roots_excluding(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

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

@@ -13,6 +13,7 @@ module Rails
     class Command
       REMOVE_SUBCOMMANDS = %w[remove delete].freeze
       DOCTOR_SUBCOMMAND = 'doctor'.freeze
+      SETUP_SUBCOMMAND = 'setup'.freeze
       UPDATE_SUBCOMMAND = 'update'.freeze
 
       include GitOperations
@@ -49,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)
@@ -77,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?
@@ -107,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?
@@ -210,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)
@@ -258,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
 
@@ -285,27 +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_after_setup(context, bootstrap_result) if dry_run?
-
-        complete_created_worktree(context, bootstrap_result)
+        complete_setup_flow(
+          context,
+          success_message: skip_setup? ? 'Worktree created' : 'Worktree ready',
+          run_post_create: !skip_setup?
+        )
       end
 
-      def complete_dry_run_after_setup(context, bootstrap_result)
-        preview_post_create_steps(context)
+      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)
-        result = run_post_create_steps(context)
+      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('Worktree ready')
+        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)
 
@@ -338,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/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

@@ -4,7 +4,7 @@ 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).
+    # db:prepare (development), db:prepare (test), assets:precompile (test), assets:clobber.
     # rubocop:disable Metrics/ClassLength
     class PostCreateRunner
       STEPS = [
@@ -17,7 +17,9 @@ module Rails
         { 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' } }
+          header: '🎨 Precompiling test assets...', env: { 'RAILS_ENV' => 'test' } },
+        { id: :assets_clobber, argv: %w[bin/rails assets:clobber],
+          header: '🧹 Clobbering compiled assets...' }
       ].freeze
 
       STEP_CONFIG = {
@@ -25,13 +27,15 @@ module Rails
         yarn: :run_yarn_install,
         db_prepare: :run_db_prepare,
         test_db_prepare: :run_test_db_prepare,
-        test_assets_precompile: :run_test_assets_precompile
+        test_assets_precompile: :run_test_assets_precompile,
+        assets_clobber: :run_test_assets_precompile
       }.freeze
 
-      def initialize(target_dir:, peer_roots:, configuration:, io:)
+      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
@@ -39,9 +43,14 @@ module Rails
       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
@@ -118,7 +127,7 @@ module Rails
       def capture_shell_command_exit_status(command)
         exit_status = nil
 
-        Open3.popen2e(base_env, command, chdir: @target_dir) do |_stdin, output, wait_thread|
+        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
@@ -143,7 +152,7 @@ module Rails
         1
       end
 
-      def base_env
+      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',
@@ -152,6 +161,21 @@ module Rails
                        '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
@@ -163,7 +187,7 @@ module Rails
       end
 
       def step_command(step)
-        [base_env.merge(step.fetch(:env, {})), *step.fetch(:argv)]
+        [runtime_env.merge(step.fetch(:env, {})), *step.fetch(:argv)]
       end
 
       def info(message)

data/lib/rails/worktrees/version.rb

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

data/lib/rails/worktrees.rb

@@ -3,6 +3,7 @@ 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'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-worktrees
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Asjer Querido
@@ -70,6 +70,7 @@ files:
 - 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