rails-worktrees 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc7ddb67fbc5fde18c04ab164229207c6f54284dc4bb5c1fb955f40544706cbb
+  data.tar.gz: a4005286b6c1dbad990d94ca3999b1490f2532c981fa8e5a7fb9b5768e4f30d6
+SHA512:
+  metadata.gz: 8eef6c43ad39e5fc38c3dbdc10fc2618fc07f0ccd65c5c25bef94ae3991aeff143687ee45a37983846cc7ec8fc4c031d39b2b4cd6abcdd37d31243bb705a24a0
+  data.tar.gz: dfdeeb6c73a81e8c3c8147883b5ca752b79ff4a63e318db409792c6723c4fd84ae3f9effc93edc1d456f74fa22f326e954ac7239d044a27709436d1e462810b6

data/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.1.0"}

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 (2026-03-30)
+
+
+### Features
+
+* add wt command and rails installer ([5d798d5](https://github.com/asjer/rails-worktrees/commit/5d798d5129585331780f0259b39061194feb66e3))
+
+## [Unreleased]
+
+- Add a gem-managed `wt` CLI for creating Rails worktrees.
+- Add a Rails installer generator that creates `bin/wt` and `config/initializers/rails_worktrees.rb`.
+- Add conservative `config/database.yml` patching for common development/test database names.
+- Add a manual-dispatch GitHub Actions workflow for the disposable Rails smoke test.
+- Add smoke-test workflow debug controls for retained artifacts and verbose output.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Asjer Querido
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# Rails::Worktrees
+
+`rails-worktrees` adds a Rails-friendly `bin/wt` command for creating Git worktrees with isolated development and test databases.
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Rails >= 7.1, < 8.2
+- Git
+
+## Installation
+
+```bash
+bundle add rails-worktrees
+bin/rails generate rails:worktrees:install
+```
+
+The installer adds:
+
+- `bin/wt` — a thin wrapper that executes the gem-owned CLI
+- `config/initializers/rails_worktrees.rb` — optional configuration
+- `Procfile.dev.worktree.example` — a copy-paste helper for `${DEV_PORT:-3000}` in `Procfile.dev`
+- a safe update to `config/database.yml` for common development/test database names
+
+## Usage
+
+```bash
+bin/wt                          # auto-pick a name from bundled *.txt lists
+bin/wt my-feature               # use an explicit worktree name
+bin/wt --dry-run my-feature     # preview the full setup without changing anything
+bin/wt --print-env my-feature   # preview DEV_PORT and WORKTREE_DATABASE_SUFFIX
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-h`, `--help` | Show the help message |
+| `-v`, `--version` | Show the script version |
+| `--dry-run [name]` | Preview the full worktree setup without changing anything |
+| `--env`, `--print-env <name>` | Preview `DEV_PORT` and `WORKTREE_DATABASE_SUFFIX` |
+
+### Default behavior
+
+By default `bin/wt`:
+
+- creates a sibling directory next to your app: `workspace/my-project.worktrees/<name>`
+- uses a branch named `🚂/<name>`
+- creates new branches from `origin`'s default branch
+- 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
+
+```text
+workspace/
+├── my-project/
+└── my-project.worktrees/
+    ├── feature-auth/
+    ├── bugfix-123/
+    └── experiment/
+```
+
+`WT_WORKSPACES_ROOT` or `config.workspace_root` overrides the destination root and uses the layout `<root>/<project>/<name>`.
+
+### Interactive prompts
+
+`bin/wt` handles several edge cases interactively:
+
+- **Branch already exists locally** — asks whether to attach a new worktree to it
+- **Branch already exists on origin** — asks whether to create a local tracking worktree
+- **Target directory already exists with matching branch** — asks whether to reuse it
+- **Target directory already exists with a different branch** — asks whether to remove and recreate it
+- **Retired bundled name used explicitly** — rejects it and suggests running `wt` with no argument
+
+### Name validation
+
+Worktree names must not contain `/` or whitespace, must not be `.` or `..`, and must be a valid Git ref component.
+
+### Configuration
+
+The installer generates `config/initializers/rails_worktrees.rb` where you can override:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `bootstrap_env` | `true` | Write `.env` when creating a worktree |
+| `workspace_root` | `nil` | Override the destination root (sibling layout when `nil`) |
+| `dev_port_range` | `3000..3999` | Port range for deterministic `DEV_PORT` allocation |
+| `branch_prefix` | `🚂` | Prefix for worktree branch names |
+| `name_sources_path` | bundled `names/` | Directory containing `.txt` name lists |
+| `used_names_file` | `~/.local/state/rails-worktrees/used-names.tsv` | TSV tracking retired names |
+| `worktree_database_suffix_max_length` | `18` | Max length for generated database suffixes |
+
+### Database naming
+
+The installer adds `WORKTREE_DATABASE_SUFFIX` to common `development` and `test` database names in `config/database.yml`. For a multi-database app, the target shape is:
+
+```yaml
+development:
+  primary:
+    database: my_app_development<%= ENV.fetch('WORKTREE_DATABASE_SUFFIX', '') %>_primary
+
+test:
+  primary:
+    database: my_app_test<%= ENV.fetch('WORKTREE_DATABASE_SUFFIX', '') %>_primary
+```
+
+If your `database.yml` is too custom to patch safely, the installer leaves it alone and tells you what to update manually.
+
+### Environment bootstrap
+
+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
+
+Existing `.env` values are never overwritten.
+
+The gem does **not** edit your `Procfile.dev` or add dotenv. The installer generates `Procfile.dev.worktree.example` with a ready-to-copy line:
+
+```text
+web: env RUBY_DEBUG_OPEN=true bin/rails server -b 0.0.0.0 -p ${DEV_PORT:-3000}
+```
+
+Use a project-local env loader like `mise` with `_.file = ".env"` to keep values scoped per-worktree.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Smoke testing
+
+RSpec remains the main automated test suite. For installer and integration changes, you can also run a disposable Rails app smoke test:
+
+```bash
+bundle exec rake smoke_test
+```
+
+This smoke test:
+
+- creates a temporary Rails app from a compatible Rails version
+- installs `rails-worktrees` from the current checkout path
+- runs `bin/rails generate rails:worktrees:install`
+- verifies `bin/wt`, the generated initializer, the Procfile example, `config/database.yml` patching, and worktree `.env` bootstrapping
+- creates a temporary bare `origin` and confirms `bin/wt smoke-branch` creates a real worktree
+
+By default, the script cleans up all temp directories after the run. Set `KEEP_SMOKE_TEST_ARTIFACTS=1` to keep them around for debugging, or set `RAILS_WORKTREES_SMOKE_RAILS_VERSION` to try a different compatible Rails version.
+
+There is also a manually triggered GitHub Actions workflow named `Smoke Test` for running the same disposable-app verification in CI without slowing down the default pull request checks.
+
+The workflow accepts optional `ruby_version`, `rails_version`, `keep_artifacts`, and `verbose` inputs. Enable `keep_artifacts` when you want the disposable app, bare origin, and worktree directories uploaded from CI for debugging, and enable `verbose` when you want shell tracing in the smoke-test log.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/asjer/rails-worktrees.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+namespace :smoke do
+  desc 'Run the disposable Rails app smoke test'
+  task :test do
+    script = File.expand_path('spec/integration/smoke_test.sh', __dir__)
+
+    Bundler.with_unbundled_env do
+      success = system(script)
+      abort('Smoke test failed') unless success
+    end
+  end
+end
+
+desc 'Run the disposable Rails app smoke test'
+task smoke_test: 'smoke:test'
+
+task default: %i[spec rubocop]

data/exe/wt

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'rails/worktrees'
+
+exit(Rails::Worktrees::CLI.new.start)

data/lefthook.yml

@@ -0,0 +1,5 @@
+remotes:
+  - git_url: https://github.com/asjer/lefthook-configs
+    refetch_frequency: 24h
+    configs: 
+      lefthook-gem.yml

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'rails/generators'
+require_relative 'mise_follow_up'
+require_relative '../../../rails/worktrees/database_config_updater'
+
+module Rails
+  module Worktrees
+    module Generators
+      # Installs the wt wrapper, configuration, and safe database.yml updates.
+      class InstallGenerator < ::Rails::Generators::Base
+        include MiseFollowUp
+
+        namespace 'rails:worktrees:install'
+        desc 'Installs bin/wt, a Rails::Worktrees initializer, and updates config/database.yml when safe.'
+        source_root File.expand_path('templates', __dir__)
+        class_option :conductor, type: :boolean, default: false,
+                                 desc: 'Configure the installer for ~/Sites/conductor/workspaces'
+
+        FOLLOW_UP_TEMPLATE = <<~TEXT
+            ============================================
+              rails-worktrees installed successfully! 🚂
+
+              Installed:
+          %<installed>s
+
+              Get started:
+                $ bin/wt
+                $ bin/wt my-feature
+
+              Configure:
+                config/initializers/rails_worktrees.rb
+          %<notes>s
+            ============================================
+        TEXT
+
+        def create_bin_wrapper
+          template('bin/wt', 'bin/wt')
+          chmod('bin/wt', 0o755)
+        end
+
+        def create_initializer
+          template('rails_worktrees.rb.tt', 'config/initializers/rails_worktrees.rb')
+        end
+
+        def create_procfile_worktree_example
+          template('Procfile.dev.worktree.example.tt', 'Procfile.dev.worktree.example')
+        end
+
+        def update_database_configuration
+          unless File.exist?(database_config_path)
+            say_status(:skip, 'config/database.yml not found', :yellow)
+            @database_outcome = :not_found
+            return
+          end
+
+          result = database_update_result
+          @database_outcome = result.changed? ? :updated : :identical
+          announce_database_update(result)
+        end
+
+        def verify_installation
+          if git_repo?
+            say_status(:ok, 'git repository detected', :green)
+          else
+            say_status(:warning, 'run inside a git repository for bin/wt to work', :yellow)
+          end
+        end
+
+        def show_follow_up
+          say(follow_up_message)
+        end
+
+        private
+
+        def database_config_path
+          File.join(destination_root, 'config/database.yml')
+        end
+
+        def database_update_result
+          result = ::Rails::Worktrees::DatabaseConfigUpdater.new(
+            content: File.read(database_config_path)
+          ).call
+
+          File.write(database_config_path, result.content) if result.changed?
+
+          result
+        end
+
+        def follow_up_message
+          "\n#{format(FOLLOW_UP_TEMPLATE, installed: installed_items_text, notes: follow_up_notes_text)}"
+        end
+
+        def installed_items_text
+          items = [
+            '      • bin/wt',
+            '      • config/initializers/rails_worktrees.rb',
+            '      • Procfile.dev.worktree.example'
+          ]
+          items << database_follow_up_line if database_follow_up_line
+          items.join("\n")
+        end
+
+        def database_follow_up_line
+          case @database_outcome
+          when :updated
+            '      • config/database.yml (updated with WORKTREE_DATABASE_SUFFIX)'
+          when :not_found
+            '      • config/database.yml was not found — see README for manual setup'
+          end
+        end
+
+        def announce_database_update(result)
+          status = result.changed? ? :update : :identical
+          color = result.changed? ? :green : :blue
+
+          say_status(status, 'config/database.yml', color)
+          result.messages.each { |message| say(message) }
+        end
+
+        def git_repo?
+          _stdout_str, _stderr_str, status = Open3.capture3(
+            'git', 'rev-parse', '--is-inside-work-tree', chdir: destination_root
+          )
+          status.success?
+        rescue Errno::ENOENT
+          false
+        end
+
+        def conductor_workspace_root
+          "File.expand_path('~/Sites/conductor/workspaces')"
+        end
+      end
+    end
+  end
+end

data/lib/generators/rails/worktrees/mise_follow_up.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    module Generators
+      # Detects common mise.toml setups and suggests loading the worktree-local .env.
+      module MiseFollowUp
+        private
+
+        def follow_up_notes_text
+          return '' unless suggest_mise_env_file?
+
+          [
+            '',
+            '      Tip:',
+            '        Detected mise.toml. To auto-load the worktree-local .env when you enter a worktree,',
+            '        consider adding:',
+            '          [env]',
+            '          _.file = ".env"'
+          ].join("\n")
+        end
+
+        def suggest_mise_env_file?
+          File.file?(mise_toml_path) && !mise_env_file_configured?
+        end
+
+        def mise_env_file_configured?
+          File.read(mise_toml_path).match?(/^\s*_.file\s*=\s*["']\.env["']\s*$/)
+        end
+
+        def mise_toml_path
+          File.join(destination_root, 'mise.toml')
+        end
+      end
+    end
+  end
+end

data/lib/generators/rails/worktrees/templates/Procfile.dev.worktree.example.tt

@@ -0,0 +1,4 @@
+# Example Procfile.dev entry for worktree-aware DEV_PORT usage.
+# Copy the web line into your Procfile.dev if you want bin/dev, Foreman, or Overmind
+# to respect the worktree-local DEV_PORT that bin/wt writes into .env.
+web: env RUBY_DEBUG_OPEN=true bin/rails server -b 0.0.0.0 -p ${DEV_PORT:-3000}

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'
+load Gem.bin_path('rails-worktrees', 'wt')

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Rails::Worktrees.configure do |config|
+<% if options['conductor'] -%>
+  config.workspace_root = <%= conductor_workspace_root %>
+<% else -%>
+  # By default, worktrees go in a sibling "<project>.worktrees" directory.
+  # Uncomment to override with a custom parent directory that uses <root>/<project>/<name>.
+  # config.workspace_root = File.expand_path('~/worktrees')
+<% end -%>
+  # config.bootstrap_env = false
+  # config.dev_port_range = 3000..3999
+  # config.worktree_database_suffix_max_length = 18
+  # config.branch_prefix = '🚂'
+  # config.name_sources_path = Rails.root.join('config/worktree_names').to_s
+  # config.used_names_file = File.join(
+  #   ENV.fetch('XDG_STATE_HOME', File.expand_path('~/.local/state')),
+  #   'rails-worktrees',
+  #   'used-names.tsv'
+  # )
+end

data/lib/rails/worktrees/cli.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    # Shell entrypoint for the wt executable.
+    class CLI
+      def initialize(
+        argv: ARGV,
+        io: { stdin: $stdin, stdout: $stdout, stderr: $stderr },
+        env: ENV,
+        cwd: Dir.pwd
+      )
+        @argv = argv
+        @io = io
+        @env = env
+        @cwd = cwd
+      end
+
+      def start
+        Command.new(
+          argv: @argv,
+          io: @io,
+          env: @env,
+          cwd: @cwd,
+          configuration: ::Rails::Worktrees.configuration
+        ).run
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Rails
+  module Worktrees
+    class Command
+      # Env bootstrap helpers and preview output.
+      module EnvironmentSupport
+        private
+
+        def preview_worktree_environment_command
+          raise Error, 'Usage: wt --print-env <worktree-name>' unless @argv.length == 2
+
+          require_git_repo
+          context = resolve_worktree_context(explicit_worktree_name: @argv[1])
+          result = env_bootstrapper_for(context).preview
+
+          print_env_preview(result.values)
+          0
+        end
+
+        def env_bootstrapper_for(context)
+          EnvBootstrapper.new(
+            target_dir: context[:target_dir],
+            worktree_name: context[:worktree_name],
+            configuration: @configuration
+          )
+        end
+
+        def bootstrap_worktree_environment(context)
+          result = env_bootstrapper_for(context).call(dry_run: dry_run?)
+
+          result.messages.each { |message| info(message) }
+          result
+        rescue StandardError => e
+          warning("Could not bootstrap #{context[:target_dir]}/.env: #{e.message}")
+        end
+
+        def preview_worktree_environment(context)
+          env_bootstrapper_for(context).preview
+        rescue StandardError => e
+          warning("Could not inspect #{context[:target_dir]}/.env: #{e.message}")
+          nil
+        end
+      end
+    end
+  end
+end