rails-worktrees 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ca5bda1caef0299d08ce62341cebeb9fe2cf35be6acb2c84438af5cfcb11f8e
-  data.tar.gz: c3278894ecf06ef752d15ff56ab64c47b56bdb2f0cf39e0773012ce71eda8823
+  metadata.gz: f0a2cb7e1644d4ec842daf14fcdf96d6b53d810e548d908a6ea651df4ebaface
+  data.tar.gz: 05ae0690974fed85a0862b0fc296681d7de1b037c03d973bef746a1872b62f41
 SHA512:
-  metadata.gz: bdb2583a6e1f1e8785599a31907c5a69c50eed1a8ebc9909fa139a59d4dd0ae5df0e941403aff68b3742f3c5c565461021418320b7a98054e7c710b491f3405a
-  data.tar.gz: 9ee5cc2bbd46b0b1cf152576be8269ee03bc0b3f749c3d878ce01976a6166fb2de2d4862dd4789b45569161e3f04802cdb2864a2973514a11f9184f0923e3fd4
+  metadata.gz: d23f7e9e0e070624ebff11c04f050a88e11ea43b61b893139d337c3df992a4ac3642db5344c491923ee36e94b6864d903dec72cbe8bbbf16c899dd3714bad6c7
+  data.tar.gz: 919e046dd0c73ad18ae90a9dc6745dbe5484f00766c8c58302f4981fa44b9e0a730455fa9eb5c7c07b929d02abb1c448e150e587495941ac4c8a9dcc20c5dc73

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.7.3"}
+{".":"0.8.0"}

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.0](https://github.com/asjer/rails-worktrees/compare/v0.7.4...v0.8.0) (2026-10-24)
+
+
+### Features
+
+* **pi:** add opt-in pi-worktree setup hook generation ([ccaa0ea](https://github.com/asjer/rails-worktrees/commit/ccaa0ead9fe31a01ac2c8016a51fd60b1611daef)), closes [#53](https://github.com/asjer/rails-worktrees/issues/53)
+
+## [0.7.4](https://github.com/asjer/rails-worktrees/compare/v0.7.3...v0.7.4) (2026-08-15)
+
+
+### Bug Fixes
+
+* **wt:** bootstrap Ruby through mise for legacy wrappers ([#45](https://github.com/asjer/rails-worktrees/issues/45)) ([b3326ab](https://github.com/asjer/rails-worktrees/commit/b3326ab737fb814d826a1b4870433028a455f582))
+
 ## [0.7.3](https://github.com/asjer/rails-worktrees/compare/v0.7.2...v0.7.3) (2026-07-08)
 
 

data/README.md

@@ -17,17 +17,20 @@ bin/rails generate worktrees:install
 bin/rails generate worktrees:install --browser
 # or, to apply the common Procfile.dev + Puma + mise follow-ups automatically:
 bin/rails generate worktrees:install --yolo
+# optionally, to let the pi-worktree extension run bin/wt setup in new Pi worktrees:
+bin/rails generate worktrees:install --pi
 ```
 
 The generated initializer writes app config under `Rails.application.config.x.rails_worktrees`, so the file stays safe to load even in environments like `test` where the gem is only bundled for `:development`. When `rails-worktrees` is loaded, the gem applies those settings for both the CLI and in-process Rails usage.
 
 The installer adds:
 
-- `bin/wt` — a thin wrapper that executes the gem-owned CLI
+- `bin/wt` — a mise-aware bootstrap wrapper that executes the gem-owned CLI
 - `bin/ob` — an optional browser helper generated by `--browser` or `--yolo`
 - `config/initializers/rails_worktrees.rb` — optional configuration
 - `Procfile.dev.worktree.example` — a copy-paste helper for `${DEV_PORT:-3000}` in `Procfile.dev` on regular installs
 - a safe update to `config/database.yml` for common development/test database names
+- `.pi/worktree.json` — only with `--pi`; see [Pi worktrees](#pi-worktrees-pi-worktree-extension)
 
 With `--yolo`, the installer also:
 
@@ -51,6 +54,7 @@ bin/wt setup ../my-project.worktrees/my-feature # setup a specific checkout with
 bin/wt doctor                   # audit install/config drift and basic worktree health
 bin/wt update --dry-run         # preview safe maintenance fixes
 bin/wt update                   # apply safe maintenance fixes for managed files
+bin/wt update --pi              # also add the pi-worktree hook in .pi/worktree.json
 bin/wt remove my-feature        # remove a worktree and delete its local branch
 bin/wt delete my-feature        # alias for `bin/wt remove`
 bin/wt remove --force my-feature # also delete an unmerged local branch
@@ -72,6 +76,7 @@ bin/ob --print-url '?from=nav'  # print the resolved URL without opening a brows
 | `--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` |
+| `--pi` | With `bin/wt update`, create or merge `.pi/worktree.json` for the pi-worktree extension |
 
 ### Default behavior
 
@@ -160,6 +165,72 @@ bin/wt prune --dry-run
 
 `bin/wt update` is intentionally conservative: it only applies safe file-based fixes for managed templates and supported config shapes. It does **not** delete branches, remove worktrees, or rewrite ambiguous custom files automatically.
 
+`bin/wt doctor` and `bin/wt update` only look at `.pi/worktree.json` once it already runs `bin/wt setup`, or when you pass `bin/wt update --pi`.
+
+### Pi worktrees (pi-worktree extension)
+
+If you create worktrees from [Pi](https://github.com/badlogic/pi-mono) with `pi --worktree` or `/worktree`, rails-worktrees can configure them to run `bin/wt setup` automatically. This is opt-in:
+
+```bash
+bin/rails generate worktrees:install --pi
+# or, in an app that already has rails-worktrees installed:
+bin/wt update --pi
+```
+
+Both commands create or update `.pi/worktree.json`:
+
+```json
+{
+  "linkEnvFiles": false,
+  "postCreate": [
+    "bin/wt setup"
+  ]
+}
+```
+
+`.pi/worktree.json` is read by the [pi-worktree](https://www.npmjs.com/package/pi-worktree) npm extension (`pi install pi-worktree`), **not** by Pi core. Without that extension, the file has no effect. pi-worktree places worktrees in `.worktrees/` inside the repository by default, so add that directory to `.gitignore`.
+
+`linkEnvFiles: false` matters. By default, pi-worktree symlinks the main checkout's gitignored `.env*` files into a new worktree before `postCreate` runs. `bin/wt setup` keeps existing `.env` values, so every Pi worktree would then reuse the main checkout's `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX`, and setup would write through the symlink into the main checkout. With linking disabled, each worktree gets its own `.env` and database identity.
+
+Existing configuration is merged, not replaced:
+
+- other keys (`dir`, `branchPrefix`, `preRemove`, …) and custom `postCreate` hooks are preserved; `bin/wt setup` is appended once and never duplicated
+- `linkEnvFiles` is only added when it is absent; an explicit `"linkEnvFiles": true`, invalid JSON, or a non-list `postCreate` is left untouched with a message explaining what to change by hand
+- no `preRemove` hook is added, and the worktree directory and branch prefix stay under your control
+
+pi-worktree runs each `postCreate` step with a 120-second timeout. If a first `bundle install` or `db:prepare` takes longer, run `bin/wt setup` again inside the worktree.
+
+### Updating old `bin/wt` wrappers
+
+Versions before 0.7.1 generated `bin/wt` as a Ruby shebang wrapper. On hosts where Ruby is provided by mise but not already on `PATH`, that legacy wrapper can fail with `/usr/bin/env: ruby: No such file or directory` before rails-worktrees can activate mise.
+
+Use the current gem executable once to repair the app-owned wrapper. Scope mise discovery to the checkout and treat in-repository mise configs as trusted for this recovery shell, so `mise exec` loads Ruby from the same configuration the repaired wrapper will use:
+
+```bash
+# From the Rails app root
+root=$(pwd -P)
+trust_root=$(
+  unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE \
+    GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+  git -C "$root" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$root"
+)
+trust_root=$(cd "$trust_root" && pwd -P)
+MISE_CEILING_PATHS=$(dirname "$trust_root")
+MISE_TRUSTED_CONFIG_PATHS="$trust_root"
+export MISE_CEILING_PATHS MISE_TRUSTED_CONFIG_PATHS
+
+mise exec -C "$root" -- ruby -v
+mise exec -C "$root" -- gem install rails-worktrees --no-document
+mise exec -C "$root" -- ruby -e 'load Gem.bin_path("rails-worktrees", "wt")' -- update --dry-run "$root"
+mise exec -C "$root" -- ruby -e 'load Gem.bin_path("rails-worktrees", "wt")' -- update "$root"
+git status --short
+git diff --stat
+```
+
+Review the diff before committing. `wt update` applies every safe managed maintenance fix it finds, so the resulting commit can include `bin/wt` plus other generated installer drift such as the initializer, database configuration, Procfile, Puma config, mise config, or `bin/ob`.
+
+New installs and repaired apps use a bash bootstrap wrapper that activates mise from the app root before loading Ruby/Bundler, trusting mise configs only inside the repository root and bounding discovery above the checkout. That covers app-local, in-repository higher-scope, local override, and environment-specific mise configuration without trusting an unrelated caller directory or configs above the checkout. The wrapper also falls back to the globally installed `wt` executable for bootstrap-safe commands such as `wt setup --dry-run` when the app bundle is incomplete.
+
 
 ### Interactive prompts
 

data/lib/generators/rails/worktrees/templates/bin/wt

@@ -47,18 +47,29 @@ fi
 WT_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 WT_SCRIPT_PATH="$WT_SCRIPT_DIR/$(basename "${BASH_SOURCE[0]}")"
 WT_APP_ROOT="$(cd "$WT_SCRIPT_DIR/.." && pwd -P)"
-WT_MISE_CONFIG=""
 
-if [ -f "$WT_APP_ROOT/mise.toml" ]; then
-  WT_MISE_CONFIG="$WT_APP_ROOT/mise.toml"
-elif [ -f "$WT_APP_ROOT/.mise.toml" ]; then
-  WT_MISE_CONFIG="$WT_APP_ROOT/.mise.toml"
+wt_path_within() {
+  case "$1" in
+    "$2"|"$2"/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+WT_MISE_TRUST_ROOT="$WT_APP_ROOT"
+if command -v git >/dev/null 2>&1; then
+  WT_GIT_ROOT="$(unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES; git -C "$WT_APP_ROOT" rev-parse --show-toplevel 2>/dev/null || true)"
+  if [ -n "$WT_GIT_ROOT" ]; then
+    WT_GIT_ROOT="$(cd "$WT_GIT_ROOT" && pwd -P)"
+    wt_path_within "$WT_APP_ROOT" "$WT_GIT_ROOT" && WT_MISE_TRUST_ROOT="$WT_GIT_ROOT"
+  fi
 fi
+WT_MISE_CEILING_PATH="$(dirname "$WT_MISE_TRUST_ROOT")"
 
-if [ -n "$WT_MISE_CONFIG" ] && [ -z "${RAILS_WORKTREES_BOOTSTRAPPED:-}" ] && command -v mise >/dev/null 2>&1; then
-  mise trust "$WT_MISE_CONFIG" >/dev/null || true
+if [ -z "${RAILS_WORKTREES_BOOTSTRAPPED:-}" ] && command -v mise >/dev/null 2>&1; then
+  export MISE_CEILING_PATHS="$WT_MISE_CEILING_PATH"
+  export MISE_TRUSTED_CONFIG_PATHS="$WT_MISE_TRUST_ROOT"
   export RAILS_WORKTREES_BOOTSTRAPPED=1
-  exec mise exec -- "$WT_SCRIPT_PATH" "$@"
+  exec mise exec -C "$WT_APP_ROOT" -- "$WT_SCRIPT_PATH" "$@"
 fi
 
 export BUNDLE_GEMFILE="${BUNDLE_GEMFILE:-$WT_APP_ROOT/Gemfile}"
@@ -69,7 +80,7 @@ def rails_worktrees_bootstrap_safe_invocation?(argv)
   return true if %w[-h --help -v --version].include?(args.first)
   return true if %w[--env --print-env].include?(args.first)
 
-  command_args = args.reject { |arg| %w[--dry-run --skip-setup --env --print-env].include?(arg) }
+  command_args = args.reject { |arg| %w[--dry-run --skip-setup --pi --env --print-env].include?(arg) }
   command = command_args.first
 
   return true if %w[setup doctor update].include?(command)

data/lib/generators/worktrees/install/install_generator.rb

@@ -7,6 +7,7 @@ require_relative '../../../rails/worktrees/database_config_updater'
 require_relative '../../../rails/worktrees/procfile_updater'
 require_relative '../../../rails/worktrees/mise_toml_updater'
 require_relative '../../../rails/worktrees/puma_config_updater'
+require_relative '../../../rails/worktrees/pi_worktree_config_updater'
 
 module Worktrees
   module Generators
@@ -35,8 +36,13 @@ module Worktrees
                      'Apply common Procfile.dev, config/puma.rb, and mise .env',
                      'follow-up edits when safe; also generate bin/ob'
                    ].join(' ')
+      class_option :pi,
+                   type: :boolean,
+                   default: false,
+                   desc: 'Generate .pi/worktree.json so the pi-worktree extension runs bin/wt setup in new worktrees'
 
       FILE_ENCODING = 'UTF-8'.freeze
+      PI_WORKTREE_CONFIG = ::Rails::Worktrees::PiWorktreeConfigUpdater::RELATIVE_PATH
 
       FOLLOW_UP_TEMPLATE = <<~TEXT.freeze
           ============================================
@@ -97,6 +103,21 @@ module Worktrees
         announce_database_update(result)
       end
 
+      def configure_pi_worktree
+        return unless options[:pi]
+
+        path = pi_worktree_config_path
+        unsafe_reason = ::Rails::Worktrees::PiWorktreeConfigPath.conflict(destination_root)
+        return announce_unsafe_pi_worktree_config(unsafe_reason) if unsafe_reason
+
+        result = ::Rails::Worktrees::PiWorktreeConfigUpdater.new(
+          content: File.exist?(path) ? File.read(path, encoding: FILE_ENCODING) : nil
+        ).call
+        write_pi_worktree_config(path, result.content) if result.changed?
+        @pi_worktree_outcome = result.status
+        announce_updater_result(PI_WORKTREE_CONFIG, result)
+      end
+
       def verify_installation
         if git_repo?
           say_status(:ok, 'git repository detected', :green)
@@ -130,6 +151,21 @@ module Worktrees
         ]
       end
 
+      def pi_worktree_config_path
+        File.join(destination_root, PI_WORKTREE_CONFIG)
+      end
+
+      def write_pi_worktree_config(path, content)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+      end
+
+      def announce_unsafe_pi_worktree_config(reason)
+        @pi_worktree_outcome = :conflict
+        say_status(:skip, PI_WORKTREE_CONFIG, :yellow)
+        say("#{PI_WORKTREE_CONFIG} #{reason}; leaving it unchanged. Add the bin/wt setup hook manually.")
+      end
+
       def database_update_result
         result = ::Rails::Worktrees::DatabaseConfigUpdater.new(
           content: File.read(database_config_path, encoding: FILE_ENCODING)
@@ -145,7 +181,7 @@ module Worktrees
       end
 
       def follow_up_notes_text
-        [super, browser_follow_up_notes_text, puma_follow_up_notes_text].join
+        [super, browser_follow_up_notes_text, puma_follow_up_notes_text, pi_worktree_follow_up_notes_text].join
       end
 
       def installed_items_text
@@ -156,9 +192,31 @@ module Worktrees
         items << '      • bin/ob' if install_browser_wrapper?
         items << '      • Procfile.dev.worktree.example' unless options[:yolo]
         items << database_follow_up_line if database_follow_up_line
+        items << pi_worktree_follow_up_line if pi_worktree_follow_up_line
         items.join("\n")
       end
 
+      def pi_worktree_follow_up_line
+        case @pi_worktree_outcome
+        when :updated, :identical
+          "      • #{PI_WORKTREE_CONFIG} (pi-worktree postCreate runs bin/wt setup)"
+        when :conflict
+          "      • #{PI_WORKTREE_CONFIG} needs manual review — see the message above"
+        end
+      end
+
+      def pi_worktree_follow_up_notes_text
+        return '' unless options[:pi]
+
+        [
+          '',
+          '      Pi worktrees:',
+          "        #{PI_WORKTREE_CONFIG} is read by the pi-worktree extension",
+          '        ($ pi install pi-worktree); it is not native Pi core configuration.',
+          '        Add the worktree directory (default .worktrees/) to .gitignore.'
+        ].join("\n")
+      end
+
       def database_follow_up_line
         case @database_outcome
         when :updated

data/lib/rails/worktrees/cli.rb

@@ -3,7 +3,7 @@ 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 --skip-setup].freeze
+      LOADER_IGNORED_FLAGS = %w[--dry-run --force --skip-setup --pi].freeze
       SETUP_SUBCOMMAND = 'setup'.freeze
 
       def initialize(

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

@@ -35,7 +35,7 @@ module Rails
                    wt --print-env <worktree-name>
                    wt doctor
                    wt setup [--dry-run] [path|name]
-                   wt update [--dry-run]
+                   wt update [--dry-run] [--pi]
                    wt remove [--dry-run] [--force] <worktree-name>
                    wt delete [--dry-run] [--force] <worktree-name>
                    wt prune [--dry-run]
@@ -47,6 +47,7 @@ module Rails
               --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
+              --pi                        With wt update, add the pi-worktree bin/wt setup hook
 
             Quick start:
               wt                 Auto-pick a name from a bundled *.txt list
@@ -72,6 +73,7 @@ module Rails
               - 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 update --pi also writes .pi/worktree.json for the pi-worktree extension (not Pi core)
               - wt remove/delete can run from the main checkout or any sibling worktree, but never remove the worktree you're currently in
               - wt prune removes merged worktrees created by wt while skipping the main checkout and the checkout you're in
               - auto-discovers bundled *.txt files from #{@configuration.name_sources_path}

data/lib/rails/worktrees/command.rb

@@ -15,6 +15,7 @@ module Rails
       DOCTOR_SUBCOMMAND = 'doctor'.freeze
       SETUP_SUBCOMMAND = 'setup'.freeze
       UPDATE_SUBCOMMAND = 'update'.freeze
+      PI_FLAG_EXEMPT_META_COMMANDS = %w[-h --help -v --version].freeze
 
       include GitOperations
       include EnvironmentSupport
@@ -35,6 +36,7 @@ module Rails
       end
 
       def run
+        validate_pi_flag!
         meta_command_result = handle_meta_command
         return meta_command_result unless meta_command_result.nil?
 
@@ -52,10 +54,13 @@ module Rails
 
       def skip_setup? = @skip_setup
 
+      def pi? = @pi
+
       def extract_flags!
         @dry_run = extract_flag!('--dry-run')
         @force = extract_flag!('--force')
         @skip_setup = extract_flag!('--skip-setup')
+        @pi = extract_flag!('--pi')
       end
 
       def extract_flag!(flag)
@@ -89,6 +94,13 @@ module Rails
         @argv.first == UPDATE_SUBCOMMAND
       end
 
+      def validate_pi_flag!
+        return unless pi?
+        return if update_subcommand? || PI_FLAG_EXEMPT_META_COMMANDS.include?(@argv.first)
+
+        raise Error, 'The --pi flag is only supported with wt update.'
+      end
+
       def execute_requested_command
         handler = requested_command_handler
         return handler.call if handler
@@ -214,7 +226,8 @@ module Rails
         validate_update_args!
         announce_dry_run if dry_run?
 
-        current_root = resolve_repository_context[:current_root]
+        repository_root = resolve_repository_context[:current_root]
+        current_root = update_target_root(repository_root)
         report = project_maintenance_report(current_root)
         updated_count = 0
         identical_count = 0
@@ -258,11 +271,25 @@ module Rails
       end
 
       def validate_update_args!
-        raise Error, 'Usage: wt update [--dry-run]' unless @argv.length == 1
+        raise Error, 'Usage: wt update [--dry-run] [--pi] [path]' 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 update_target_root(repository_root)
+        return repository_root unless @argv[1]
+
+        target_root = canonical_path(File.expand_path(@argv[1], @cwd))
+        raise Error, "Update target does not exist: #{target_root}" unless File.directory?(target_root)
+
+        assert_within_root!(
+          target_root,
+          repository_root,
+          "Refusing to update a path outside the current Git repository: #{target_root}"
+        )
+        target_root
+      end
+
       def announce_prune_candidates(candidates)
         info("Found #{candidates.length} merged worktree#{'s' unless candidates.length == 1} created by wt:")
       end
@@ -623,7 +650,7 @@ module Rails
       end
 
       def project_maintenance_report(root)
-        ::Rails::Worktrees::ProjectMaintenance.new(root: root).call
+        ::Rails::Worktrees::ProjectMaintenance.new(root: root, pi_worktree: pi?).call
       end
 
       def doctor_worktree_checks(repository)

data/lib/rails/worktrees/mise_environment.rb

@@ -7,7 +7,7 @@ module Rails
     class MiseEnvironment
       Result = Struct.new(:env, :messages)
 
-      CONFIG_FILES = %w[mise.toml .mise.toml].freeze
+      CONFIG_FILES = %w[mise.toml .mise.toml mise.local.toml .mise.local.toml].freeze
 
       def initialize(target_dir:, env:)
         @target_dir = target_dir

data/lib/rails/worktrees/pi_worktree_config_path.rb

@@ -0,0 +1,44 @@
+module Rails
+  module Worktrees
+    # Decides whether .pi/worktree.json under an app root can be safely read and written in place.
+    class PiWorktreeConfigPath
+      RELATIVE_PATH = '.pi/worktree.json'.freeze
+
+      def self.conflict(root)
+        new(root).conflict
+      end
+
+      def initialize(root)
+        @root = root
+        @path = File.join(root, RELATIVE_PATH)
+        @parent = File.dirname(@path)
+      end
+
+      # Returns why the config path is unsafe, or nil when it can be used.
+      def conflict
+        return 'is a symlink' if File.symlink?(@path)
+        return 'is not a regular file' if File.exist?(@path) && !File.file?(@path)
+        return "cannot be created because #{File.basename(@parent)} is not a directory" if parent_not_directory?
+        return if within_root?(nearest_existing_realpath(@parent))
+
+        'resolves outside the app through a symlinked directory'
+      end
+
+      private
+
+      def parent_not_directory?
+        (File.exist?(@parent) || File.symlink?(@parent)) && !File.directory?(@parent)
+      end
+
+      def nearest_existing_realpath(path)
+        path = File.dirname(path) until File.exist?(path)
+        File.realpath(path)
+      end
+
+      def within_root?(path)
+        root = File.realpath(@root)
+        path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+      end
+    end
+  end
+end

data/lib/rails/worktrees/pi_worktree_config_updater.rb

@@ -0,0 +1,123 @@
+require 'json'
+require_relative 'pi_worktree_config_path'
+
+module Rails
+  module Worktrees
+    # Safely merges the bin/wt setup hook into the pi-worktree extension's .pi/worktree.json.
+    class PiWorktreeConfigUpdater
+      Result = Struct.new(:content, :changed, :status, :messages) do
+        def changed?
+          changed
+        end
+      end
+
+      RELATIVE_PATH = PiWorktreeConfigPath::RELATIVE_PATH
+      SETUP_COMMAND = 'bin/wt setup'.freeze
+      # Horizontal whitespace only: a newline would make the shell run two separate commands.
+      SETUP_COMMAND_PATTERN = %r{\A[ \t]*(?:\./)?bin/wt[ \t]+setup[ \t]*\z}
+
+      def self.configured?(content)
+        return false if content.nil? || !content.valid_encoding?
+
+        config = JSON.parse(content)
+        config.is_a?(Hash) && setup_hook?(config['postCreate'])
+      rescue JSON::ParserError
+        false
+      end
+
+      def self.setup_hook?(commands)
+        return false unless commands.is_a?(Array)
+
+        commands.any? { |command| command.is_a?(String) && command.match?(SETUP_COMMAND_PATTERN) }
+      end
+
+      def initialize(content:)
+        @content = content
+      end
+
+      def call
+        config = parse_config
+        return config if config.is_a?(Result)
+
+        conflict = conflict_message(config)
+        return conflict_result(conflict) if conflict
+
+        merge_setup_hook(config)
+      end
+
+      private
+
+      def parse_config
+        return {} if @content.nil?
+        unless @content.valid_encoding?
+          return conflict_result("#{RELATIVE_PATH} is not valid UTF-8; leaving it unchanged.")
+        end
+        return {} if @content.strip.empty?
+
+        config = JSON.parse(@content)
+        return config if config.is_a?(Hash)
+
+        conflict_result("#{RELATIVE_PATH} must contain a JSON object; leaving it unchanged.")
+      rescue JSON::ParserError => e
+        conflict_result("#{RELATIVE_PATH} is not valid JSON (#{e.message.lines.first.strip}); leaving it unchanged.")
+      end
+
+      def conflict_message(config)
+        if config.key?('linkEnvFiles') && config['linkEnvFiles'] != false
+          return [
+            "#{RELATIVE_PATH} sets \"linkEnvFiles\": #{JSON.generate(config['linkEnvFiles'])}, so pi-worktree " \
+            "would symlink the main checkout's .env into new worktrees before bin/wt setup runs.",
+            'Set "linkEnvFiles": false yourself to give each worktree its own DEV_PORT and ' \
+            'WORKTREE_DATABASE_SUFFIX, then rerun this command; the file was left unchanged.'
+          ]
+        end
+
+        return if !config.key?('postCreate') || string_list?(config['postCreate'])
+
+        "#{RELATIVE_PATH} postCreate must be a list of shell commands; leaving it unchanged."
+      end
+
+      def merge_setup_hook(config)
+        updated = config.dup
+        messages = [add_setup_hook(updated), disable_env_file_linking(updated)].compact
+        return identical_result if messages.empty?
+
+        Result.new("#{JSON.pretty_generate(ordered_new_config(config, updated))}\n", true, :updated, messages)
+      end
+
+      def add_setup_hook(config)
+        return if self.class.setup_hook?(config['postCreate'])
+
+        config['postCreate'] = Array(config['postCreate']) + [SETUP_COMMAND]
+        "Added \"#{SETUP_COMMAND}\" to postCreate in #{RELATIVE_PATH}."
+      end
+
+      def disable_env_file_linking(config)
+        return if config.key?('linkEnvFiles')
+
+        config['linkEnvFiles'] = false
+        "Disabled linkEnvFiles in #{RELATIVE_PATH} so each worktree keeps its own .env."
+      end
+
+      # Fresh configs list linkEnvFiles first so the safety switch is visible above the hooks.
+      def ordered_new_config(original, updated)
+        return updated unless original.empty?
+
+        { 'linkEnvFiles' => updated['linkEnvFiles'], 'postCreate' => updated['postCreate'] }
+      end
+
+      def string_list?(value)
+        value.is_a?(Array) && value.all?(String)
+      end
+
+      def identical_result
+        Result.new(@content, false, :identical,
+                   ["#{RELATIVE_PATH} already runs bin/wt setup with env-file linking disabled."])
+      end
+
+      def conflict_result(messages)
+        Result.new(@content, false, :conflict, Array(messages))
+      end
+    end
+  end
+end

data/lib/rails/worktrees/post_create_runner.rb

@@ -164,18 +164,66 @@ module Rails
       attr_reader :runtime_env
 
       def resolved_runtime_env(dry_run:)
-        env = shell_env.merge(@bootstrapped_env)
+        env = shell_env.merge(@bootstrapped_env).merge(target_mise_scope_env)
         return env if dry_run
 
-        env.merge(toolchain_env)
+        env.merge(toolchain_env(env))
       end
 
-      def toolchain_env
-        result = MiseEnvironment.new(target_dir: @target_dir, env: shell_env.merge(@bootstrapped_env)).call
+      def toolchain_env(env)
+        result = MiseEnvironment.new(target_dir: @target_dir, env: env).call
         result.messages.each { |message| info(message) }
         result.env
       end
 
+      def target_mise_scope_env
+        trust_root = target_git_root || canonical_target_dir
+
+        {
+          'MISE_CEILING_PATHS' => File.dirname(trust_root),
+          'MISE_TRUSTED_CONFIG_PATHS' => trust_root
+        }
+      end
+
+      def target_git_root
+        stdout_str, status = capture_target_git_root
+        return nil unless status.success?
+
+        root = File.realpath(stdout_str.strip)
+        target_within_root?(root) ? root : nil
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        nil
+      end
+
+      def capture_target_git_root
+        stdout_str, _stderr_str, status = Open3.capture3(
+          git_discovery_env,
+          'git', '-C', @target_dir, 'rev-parse', '--show-toplevel'
+        )
+        [stdout_str, status]
+      end
+
+      def git_discovery_env
+        shell_env.merge(
+          'GIT_DIR' => nil,
+          'GIT_WORK_TREE' => nil,
+          'GIT_COMMON_DIR' => nil,
+          'GIT_INDEX_FILE' => nil,
+          'GIT_OBJECT_DIRECTORY' => nil,
+          'GIT_ALTERNATE_OBJECT_DIRECTORIES' => nil
+        )
+      end
+
+      def target_within_root?(root)
+        canonical_target_dir.start_with?("#{root}#{File::SEPARATOR}") || canonical_target_dir == root
+      end
+
+      def canonical_target_dir
+        @canonical_target_dir ||= File.realpath(@target_dir)
+      rescue Errno::ENOENT
+        File.expand_path(@target_dir)
+      end
+
       def yarn_lock_present?
         File.exist?(File.join(@target_dir, 'yarn.lock'))
       end

data/lib/rails/worktrees/project_maintenance.rb

@@ -50,8 +50,9 @@ module Rails
       TEMPLATE_ROOT = File.expand_path('../../generators/rails/worktrees/templates', __dir__)
       FILE_ENCODING = 'UTF-8'.freeze
 
-      def initialize(root:)
+      def initialize(root:, pi_worktree: false)
         @root = root
+        @pi_worktree = pi_worktree
       end
 
       def call
@@ -60,7 +61,7 @@ module Rails
 
       private
 
-      attr_reader :root
+      attr_reader :root, :pi_worktree
 
       def maintenance_checks
         [
@@ -70,7 +71,8 @@ module Rails
           optional_updater_check(procfile_config) { |content| ProcfileUpdater.new(content: content).call },
           optional_updater_check(puma_config) { |content| PumaConfigUpdater.new(content: content).call },
           mise_check,
-          template_file_check(browser_wrapper_config)
+          template_file_check(browser_wrapper_config),
+          pi_worktree_check
         ]
       end
 
@@ -263,6 +265,31 @@ module Rails
         updater_result_check(config, mise_updater_result(relative_path))
       end
 
+      # Only audit .pi/worktree.json when explicitly requested or when it already runs bin/wt setup,
+      # so configs owned purely by other pi-worktree users stay untouched.
+      def pi_worktree_check
+        relative_path = PiWorktreeConfigUpdater::RELATIVE_PATH
+        path = absolute_path(relative_path)
+        content = File.file?(path) ? read_text(path) : nil
+        return unless pi_worktree || PiWorktreeConfigUpdater.configured?(content)
+
+        config = {
+          identifier: :pi_worktree,
+          category: :config,
+          relative_path: relative_path,
+          identical_headline: "#{relative_path} already runs bin/wt setup with env-file linking disabled.",
+          fixable_headline: "#{relative_path} can be updated automatically.",
+          warning_headline: "#{relative_path} needs manual review."
+        }
+        path_conflict = PiWorktreeConfigPath.conflict(root)
+        if path_conflict
+          return warning_check(config, config.fetch(:warning_headline),
+                               ["#{relative_path} #{path_conflict}; leaving it unchanged."])
+        end
+
+        updater_result_check(config, PiWorktreeConfigUpdater.new(content: content).call)
+      end
+
       def mise_updater_result(relative_path)
         MiseTomlUpdater.new(
           content: read_text(absolute_path(relative_path)),

data/lib/rails/worktrees/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Worktrees
-    VERSION = '0.7.3'.freeze
+    VERSION = '0.8.0'.freeze
   end
 end

data/lib/rails/worktrees.rb

@@ -15,6 +15,8 @@ require_relative 'worktrees/initializer_updater'
 require_relative 'worktrees/procfile_updater'
 require_relative 'worktrees/mise_toml_updater'
 require_relative 'worktrees/puma_config_updater'
+require_relative 'worktrees/pi_worktree_config_path'
+require_relative 'worktrees/pi_worktree_config_updater'
 require_relative 'worktrees/project_configuration_loader'
 require_relative 'worktrees/project_maintenance'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-worktrees
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Asjer Querido
@@ -73,6 +73,8 @@ files:
 - lib/rails/worktrees/mise_environment.rb
 - lib/rails/worktrees/mise_toml_updater.rb
 - lib/rails/worktrees/names/cities.txt
+- lib/rails/worktrees/pi_worktree_config_path.rb
+- lib/rails/worktrees/pi_worktree_config_updater.rb
 - lib/rails/worktrees/post_create_runner.rb
 - lib/rails/worktrees/procfile_updater.rb
 - lib/rails/worktrees/project_configuration_loader.rb