rails-worktrees 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19ad567125176f17f962138eaf218f8e8c91a7a6585b61db0bddfa4c259f7d17
-  data.tar.gz: 7c29590624ed404c362deb38866f134ba9516bbd3e6f83f3b04cfb00792caeb4
+  metadata.gz: 46ec0bdd9361eabe4925e37760bcd5d050c8f71072ec93cfdb427e244186ea8e
+  data.tar.gz: 965a2ea5c6d454739f833cf0a534a4b195903531d159e2fb25f5eff9bb71083c
 SHA512:
-  metadata.gz: f35103be9855cc4e262f12b4dbff0ff935cb65b67d3ae6d2ca619eb1d47bdfcf8829be5b03f2d8ff3cc587509098045d32ccea539fa48395a02c6180ca69546b
-  data.tar.gz: ef54f096ea64e518519b59f9f74af756bec7601ee492c0d1aec98736c485e62998cc6ec9149b251fa903f4acdb39f5e8cc36e4ed66aa650357df76090c3fd67b
+  metadata.gz: fa02fa0f6786fb3865326f8cef1e4beb804a25411cc7b5d15676236424b23a5cd4e5b55bd21550f1b1e3f422384f1c06662ff05b9d40e291e931b1bd09775af2
+  data.tar.gz: 43269ef67990a1a4986f407a96696b9b01faabf8a64930e676c3c505a214d38b228ba3dae5e9ffa76fc74dc59d96bbdad3eafceb42c99236c64a23954fbefced

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.2.2"}
+{".":"0.3.0"}

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/asjer/rails-worktrees/compare/v0.2.2...v0.3.0) (2026-03-30)
+
+
+### Features
+
+* **ob:** add `bin/ob` cli for opening `localhost:$DEV_PORT` routes in the browser ([1c94ade](https://github.com/asjer/rails-worktrees/commit/1c94adebd338cfe6e344095f3d6df089570f1e82))
+
 ## [0.2.2](https://github.com/asjer/rails-worktrees/compare/v0.2.1...v0.2.2) (2026-03-30)
 
 
@@ -42,6 +49,7 @@
 ## [Unreleased]
 
 - Add a gem-managed `wt` CLI for creating Rails worktrees.
+- Add an optional gem-managed `ob` CLI plus generated `bin/ob` wrapper for opening `localhost:$DEV_PORT` routes.
 - 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.

data/README.md

@@ -1,6 +1,6 @@
 # Rails::Worktrees
 
-`rails-worktrees` adds a Rails-friendly `bin/wt` command for creating Git worktrees with isolated development and test databases.
+`rails-worktrees` adds Rails-friendly `bin/wt` and `bin/ob` commands for creating Git worktrees and opening the right local browser URL for each worktree.
 
 ## Requirements
 
@@ -13,6 +13,8 @@
 ```bash
 bundle add rails-worktrees
 bin/rails generate worktrees:install
+# or, to also generate bin/ob without the yolo follow-ups:
+bin/rails generate worktrees:install --browser
 # or, to apply the common Procfile.dev + Puma + mise follow-ups automatically:
 bin/rails generate worktrees:install --yolo
 ```
@@ -20,12 +22,14 @@ bin/rails generate worktrees:install --yolo
 The installer adds:
 
 - `bin/wt` — a thin 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
 
 With `--yolo`, the installer also:
 
+- generates `bin/ob`
 - skips `Procfile.dev.worktree.example`
 - replaces the existing `web:` entry in `Procfile.dev` with the DEV_PORT-aware command when `Procfile.dev` already exists
 - updates `config/puma.rb` to use `port ENV['DEV_PORT'] || ENV.fetch('PORT', 3000)` when it still uses a supported default `PORT` binding
@@ -38,6 +42,11 @@ 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
+
+bin/ob                          # open http://localhost:$DEV_PORT/
+bin/ob contact                  # open http://localhost:$DEV_PORT/contact
+bin/ob '/contact?from=nav'      # open a local route with query params
+bin/ob --print-url '?from=nav'  # print the resolved URL without opening a browser
 ```
 
 ### Options
@@ -124,6 +133,33 @@ When `bin/wt` creates a worktree it writes a worktree-local `.env` with:
 
 Existing `.env` values are never overwritten.
 
+### Browser helper
+
+If you install with `--browser` or `--yolo`, the installer generates `bin/ob`.
+
+`bin/ob` reads `DEV_PORT` from the current app or worktree's `.env`, falls back to `ENV['DEV_PORT']`, then falls back to `3000`, and opens `http://localhost:$DEV_PORT/...` in your default browser.
+
+Route examples:
+
+```bash
+bin/ob
+bin/ob contact
+bin/ob admin/users
+bin/ob '/contact?from=footer'
+bin/ob --print-url '?from=footer'
+```
+
+`bin/ob` accepts a single optional local route argument. Query-only routes such as `?from=footer` resolve to the app root, and full URLs such as `https://example.com` are intentionally rejected.
+
+If `DEV_PORT` is missing from `.env`, `bin/ob` tells you when it falls back to `ENV['DEV_PORT']` or `3000`.
+
+Browser opening currently uses:
+
+- `open` on macOS
+- `xdg-open` on Linux and other Unix-like environments that provide it
+
+For scripts and debugging, `bin/ob --print-url [route]` prints the resolved localhost URL without opening a browser.
+
 By default, the installer does **not** edit your `Procfile.dev`, `config/puma.rb`, or `mise` config. It generates `Procfile.dev.worktree.example` with a ready-to-copy line:
 
 ```text
@@ -160,7 +196,7 @@ 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 worktrees:install --yolo`
-- verifies `bin/wt`, the generated initializer, that `--yolo` skips the Procfile example, yolo updates to `Procfile.dev`, `config/puma.rb`, and `mise.toml`, `config/database.yml` patching, and worktree `.env` bootstrapping
+- verifies `bin/wt`, `bin/ob`, the generated initializer, that `--yolo` skips the Procfile example, yolo updates to `Procfile.dev`, `config/puma.rb`, and `mise.toml`, `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.

data/exe/ob

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'rails/worktrees'
+
+exit(
+  Rails::Worktrees::BrowserCommand.new(
+    argv: ARGV,
+    io: { stdin: $stdin, stdout: $stdout, stderr: $stderr },
+    env: ENV,
+    cwd: Dir.pwd
+  ).run
+)

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

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

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

@@ -17,12 +17,24 @@ module Worktrees
       include ::Rails::Worktrees::Generators::PumaFollowUp
 
       namespace 'worktrees:install'
-      desc 'Installs bin/wt, a Rails::Worktrees initializer, and updates config/database.yml when safe.'
+      desc [
+        'Installs bin/wt, optional bin/ob, a Rails::Worktrees initializer,',
+        'and updates config/database.yml when safe.'
+      ].join(' ')
       source_root File.expand_path('../../rails/worktrees/templates', __dir__)
       class_option :conductor, type: :boolean, default: false,
                                desc: 'Configure the installer for ~/Sites/conductor/workspaces'
-      class_option :yolo, type: :boolean, default: false,
-                          desc: 'Apply common Procfile.dev, config/puma.rb, and mise .env follow-up edits when safe'
+      class_option :browser,
+                   type: :boolean,
+                   default: false,
+                   desc: 'Generate bin/ob to open localhost:$DEV_PORT routes for this app/worktree'
+      class_option :yolo,
+                   type: :boolean,
+                   default: false,
+                   desc: [
+                     'Apply common Procfile.dev, config/puma.rb, and mise .env',
+                     'follow-up edits when safe; also generate bin/ob'
+                   ].join(' ')
 
       FOLLOW_UP_TEMPLATE = <<~TEXT.freeze
           ============================================
@@ -46,6 +58,13 @@ module Worktrees
         chmod('bin/wt', 0o755)
       end
 
+      def create_browser_wrapper
+        return unless install_browser_wrapper?
+
+        template('bin/ob', 'bin/ob')
+        chmod('bin/ob', 0o755)
+      end
+
       def create_initializer
         template('rails_worktrees.rb.tt', 'config/initializers/rails_worktrees.rb')
       end
@@ -124,7 +143,7 @@ module Worktrees
       end
 
       def follow_up_notes_text
-        [super, puma_follow_up_notes_text].join
+        [super, browser_follow_up_notes_text, puma_follow_up_notes_text].join
       end
 
       def installed_items_text
@@ -132,6 +151,7 @@ module Worktrees
           '      • bin/wt',
           '      • config/initializers/rails_worktrees.rb'
         ]
+        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.join("\n")
@@ -211,6 +231,22 @@ module Worktrees
         say('Skipped mise yolo update because no supported mise config file was found.')
       end
 
+      def browser_follow_up_notes_text
+        return '' unless install_browser_wrapper?
+
+        [
+          '',
+          '      Open browser:',
+          '        $ bin/ob',
+          '        $ bin/ob contact',
+          "        $ bin/ob --print-url '?from=nav'"
+        ].join("\n")
+      end
+
+      def install_browser_wrapper?
+        options[:yolo] || options[:browser]
+      end
+
       def git_repo?
         _stdout_str, _stderr_str, status = Open3.capture3(
           'git', 'rev-parse', '--is-inside-work-tree', chdir: destination_root

data/lib/rails/worktrees/browser_command.rb

@@ -0,0 +1,264 @@
+require 'rbconfig'
+require 'uri'
+
+module Rails
+  module Worktrees
+    # Opens the current app/worktree in a browser using the local DEV_PORT.
+    # rubocop:disable Metrics/ClassLength
+    class BrowserCommand
+      APP_ROOT_ENV_KEY = 'RAILS_WORKTREES_APP_ROOT'.freeze
+      ENV_FILE_NAME = '.env'.freeze
+
+      def initialize(argv:, io:, env:, cwd:, host_os: RbConfig::CONFIG['host_os'])
+        @argv = argv.dup
+        @stdin = io.fetch(:stdin)
+        @stdout = io.fetch(:stdout)
+        @stderr = io.fetch(:stderr)
+        @env = env
+        @cwd = cwd
+        @host_os = host_os
+      end
+
+      def run
+        meta_command_result = handle_meta_command
+        return meta_command_result unless meta_command_result.nil?
+        return usage_error if @argv.length > 1
+
+        url = build_url(@argv.first)
+        open_browser(url)
+        @stdout.puts("🌐 Opening #{url}")
+        0
+      rescue Error => e
+        @stderr.puts("Error: #{e.message}")
+        1
+      end
+
+      private
+
+      def handle_meta_command
+        case @argv.first
+        when '-h', '--help'
+          @stdout.print(usage)
+          0
+        when '-v', '--version'
+          @stdout.puts("ob #{Rails::Worktrees::VERSION}")
+          0
+        when '--url', '--print-url'
+          print_url_command
+        end
+      end
+
+      def usage_error
+        @stderr.print(usage)
+        1
+      end
+
+      def usage
+        <<~USAGE
+          ob #{::Rails::Worktrees::VERSION}
+          Open the current app/worktree in your browser using DEV_PORT.
+
+          Usage: ob [route]
+                 ob --print-url [route]
+
+          Options:
+            -h, --help              Show this help message
+            -v, --version           Show the script version
+            --url, --print-url      Print the resolved URL without opening a browser
+
+          Quick start:
+            ob
+            ob contact
+            ob '/contact?ref=nav'
+            ob --print-url '?from=nav'
+
+          Route rules:
+            - route is optional; the default is /
+            - values like contact and admin/users become /contact and /admin/users
+            - query-only values like ?from=nav resolve to /?from=nav
+            - full URLs are rejected; ob only opens localhost routes
+            - DEV_PORT comes from .env first, then ENV['DEV_PORT'], then 3000
+        USAGE
+      end
+
+      def build_url(route)
+        raise Error, 'ob only accepts local routes, not full URLs' if full_url?(route)
+
+        path, query, fragment = route_components(route)
+        uri_options = { host: 'localhost', port: resolved_dev_port.to_i, path: path, query: query, fragment: fragment }
+        URI::HTTP.build(**uri_options).to_s
+      rescue URI::Error => e
+        raise Error, "Invalid route: #{e.message}"
+      end
+
+      def route_components(route)
+        raw_route = route.to_s.strip
+        route_without_fragment, fragment = raw_route.split('#', 2)
+        path_part, query = route_without_fragment.to_s.split('?', 2)
+
+        [normalized_path(path_part), presence(query), presence(fragment)]
+      end
+
+      def normalized_path(path_part)
+        cleaned = path_part.to_s
+        return '/' if cleaned.empty?
+
+        cleaned.start_with?('/') ? cleaned : "/#{cleaned}"
+      end
+
+      def resolved_dev_port
+        info = dev_port_resolution
+        note_port_fallback(info[:message])
+
+        port = info.fetch(:port)
+        raise Error, "DEV_PORT must be numeric, got #{port.inspect}" unless port.match?(/\A\d+\z/)
+        raise Error, "DEV_PORT must be between 1 and 65535, got #{port.inspect}" unless (1..65_535).cover?(port.to_i)
+
+        port.to_i
+      end
+
+      def print_url_command
+        return usage_error if @argv.length > 2
+
+        @stdout.puts(build_url(@argv[1]))
+        0
+      end
+
+      def dev_port_from_env_file
+        return unless File.file?(env_path)
+
+        lines = File.readlines(env_path, chomp: true)
+        env_value(lines, 'DEV_PORT')
+      rescue StandardError => e
+        raise Error, "Could not read #{env_path}: #{e.message}"
+      end
+
+      def env_value(lines, key)
+        line = lines.reverse.find { |entry| entry.start_with?("#{key}=") }
+        value = line&.split('=', 2)&.last
+        value unless value&.empty?
+      end
+
+      def dev_port_resolution
+        env_file_port = dev_port_from_env_file
+        return { port: env_file_port, message: nil } if env_file_port
+
+        env_file_fallback_resolution
+      end
+
+      def env_file_fallback_resolution
+        env_port = presence(@env['DEV_PORT'])
+        return existing_env_file_resolution(env_port) if File.file?(env_path)
+
+        missing_env_file_resolution(env_port)
+      end
+
+      def existing_env_file_resolution(env_port)
+        return env_resolution_from_env_var(env_port) if env_port
+
+        {
+          port: '3000',
+          message: [
+            "#{env_path} does not define DEV_PORT",
+            "and ENV['DEV_PORT'] is unset; falling back to localhost:3000."
+          ].join(' ')
+        }
+      end
+
+      def missing_env_file_resolution(env_port)
+        return missing_env_file_resolution_from_env_var(env_port) if env_port
+
+        {
+          port: '3000',
+          message: [
+            "#{env_path} was not found",
+            "and ENV['DEV_PORT'] is unset; falling back to localhost:3000."
+          ].join(' ')
+        }
+      end
+
+      def env_resolution_from_env_var(env_port)
+        {
+          port: env_port,
+          message: "#{env_path} does not define DEV_PORT; falling back to ENV['DEV_PORT']=#{env_port}."
+        }
+      end
+
+      def missing_env_file_resolution_from_env_var(env_port)
+        {
+          port: env_port,
+          message: "#{env_path} was not found; falling back to ENV['DEV_PORT']=#{env_port}."
+        }
+      end
+
+      def note_port_fallback(message)
+        return unless message
+        return if @port_fallback_noted
+
+        @stderr.puts("Info: #{message}")
+        @port_fallback_noted = true
+      end
+
+      def open_browser(url)
+        command = opener_command
+        raise Error, "Could not find a browser opener for #{@host_os.inspect}" unless command
+        raise Error, "Failed to open browser with #{command}" unless run_opener(command, url)
+      end
+
+      def opener_command
+        opener_candidates.find { |command| command_available?(command) }
+      end
+
+      def run_opener(command, url)
+        system(command, url)
+      end
+
+      def command_available?(command)
+        @env.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |directory|
+          candidate = File.join(directory, command)
+          File.file?(candidate) && File.executable?(candidate)
+        end
+      end
+
+      def opener_candidates
+        return ['open'] if @host_os.match?(/darwin/i)
+
+        ['xdg-open']
+      end
+
+      def env_path = File.join(app_root, ENV_FILE_NAME)
+
+      def app_root
+        @app_root ||= begin
+          explicit_root = presence(@env[APP_ROOT_ENV_KEY])
+          explicit_root ? File.expand_path(explicit_root) : discover_app_root(File.expand_path(@cwd))
+        end
+      end
+
+      def discover_app_root(start_dir)
+        current = start_dir
+
+        loop do
+          return current if File.file?(File.join(current, 'Gemfile'))
+
+          parent = File.dirname(current)
+          break if parent == current
+
+          current = parent
+        end
+
+        start_dir
+      end
+
+      def full_url?(route)
+        route.to_s.match?(%r{\A[a-z][a-z0-9+\-.]*://}i)
+      end
+
+      def presence(value)
+        value = value.to_s
+        value.empty? ? nil : value
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/rails/worktrees/version.rb

@@ -1,5 +1,5 @@
 module Rails
   module Worktrees
-    VERSION = '0.2.2'.freeze
+    VERSION = '0.3.0'.freeze
   end
 end

data/lib/rails/worktrees.rb

@@ -5,6 +5,7 @@ require_relative 'worktrees/configuration'
 require_relative 'worktrees/env_bootstrapper'
 require_relative 'worktrees/command'
 require_relative 'worktrees/cli'
+require_relative 'worktrees/browser_command'
 require_relative 'worktrees/database_config_updater'
 require_relative 'worktrees/procfile_updater'
 require_relative 'worktrees/mise_toml_updater'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-worktrees
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Asjer Querido
@@ -34,6 +34,7 @@ description: Rails::Worktrees is a Ruby gem intended to support working with git
 email:
 - asjer@johnyontherun.com
 executables:
+- ob
 - wt
 extensions: []
 extra_rdoc_files: []
@@ -43,15 +44,18 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/ob
 - exe/wt
 - lefthook.yml
 - lib/generators/rails/worktrees/mise_follow_up.rb
 - lib/generators/rails/worktrees/puma_follow_up.rb
 - lib/generators/rails/worktrees/templates/Procfile.dev.worktree.example.tt
+- lib/generators/rails/worktrees/templates/bin/ob
 - lib/generators/rails/worktrees/templates/bin/wt
 - lib/generators/rails/worktrees/templates/rails_worktrees.rb.tt
 - lib/generators/worktrees/install/install_generator.rb
 - lib/rails/worktrees.rb
+- lib/rails/worktrees/browser_command.rb
 - lib/rails/worktrees/cli.rb
 - lib/rails/worktrees/command.rb
 - lib/rails/worktrees/command/environment_support.rb