copse 0.1.0

data/lib/copse/worktree.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Copse
+  # Answers "what am I called, and what port do I get" by shelling out to git.
+  #
+  # Holds no state and touches no files. Nothing here needs git to succeed --
+  # git only answers the naming question more precisely. A plain directory, or a
+  # machine with no git at all, degrades to the directory name.
+  class Worktree
+    LABEL_LIMIT = 63
+
+    attr_reader :root
+
+    def initialize(root = Dir.pwd)
+      @root = File.expand_path(root)
+    end
+
+    # `<project>.localhost` for a main worktree, `<branch>.<project>.localhost`
+    # for a linked one.
+    def host
+      @host ||= [slug, project, "localhost"].compact.join(".")
+    end
+
+    def port
+      @port ||= Copse.port_for(host)
+    end
+
+    def companion_port
+      @companion_port ||= Copse.companion_port_for(host)
+    end
+
+    def url
+      "http://#{host}:#{port}"
+    end
+
+    # What a linked worktree's development database name is suffixed with, or nil
+    # in a main worktree -- which keeps the app's plain database.
+    #
+    # The same slug the hostname uses, with `-` swapped for `_`: a hyphen is
+    # legal in a database name but has to be quoted on every `psql` and `mysql`
+    # command line, and `_` is what Rails' own `<app>_development` already uses.
+    def database_suffix
+      slug&.tr("-", "_")
+    end
+
+    # The project name: the main worktree's directory name, even when called from
+    # a linked worktree.
+    def project
+      @project ||= self.class.slug(File.basename(main_root)) || "app"
+    end
+
+    # nil for a main worktree; the branch name (or this directory's name on a
+    # detached HEAD) for a linked one.
+    def slug
+      return @slug if defined?(@slug)
+
+      @slug = if linked?
+                self.class.slug(branch) || self.class.slug(File.basename(toplevel))
+              end
+    end
+
+    def linked?
+      return @linked if defined?(@linked)
+
+      @linked = !main_root.nil? && !toplevel.nil? && main_root != toplevel
+    end
+
+    def branch
+      return @branch if defined?(@branch)
+
+      name = git("rev-parse", "--abbrev-ref", "HEAD")
+      # "HEAD" means detached; there is no branch to name the worktree after.
+      @branch = (name == "HEAD" ? nil : name)
+    end
+
+    # Reduces an arbitrary string to a single valid DNS label.
+    #
+    # A whitelist, not a substitution list. Git accepts branch names containing
+    # `;`, `$(`, `&&`, quotes, and more, and the slug flows into COPSE_HOST,
+    # COPSE_URL, every child process's environment, and a generated Procfile that
+    # a shell will execute -- so anything outside [a-z0-9-] is replaced rather
+    # than passed through. Branch names also arrive from collaborators via
+    # `git fetch`; they are not necessarily the developer's own input.
+    #
+    # Returns nil when nothing survives, so callers can fall back.
+    def self.slug(value)
+      collapsed = value.to_s.downcase.gsub(/[^a-z0-9]+/, "-")
+      trimmed = collapsed[0, LABEL_LIMIT].to_s.gsub(/\A-+|-+\z/, "")
+      trimmed.empty? ? nil : trimmed
+    end
+
+    private
+
+    def toplevel
+      return @toplevel if defined?(@toplevel)
+
+      path = git("rev-parse", "--show-toplevel")
+      @toplevel = path && File.realpath(path)
+    rescue Errno::ENOENT
+      @toplevel = nil
+    end
+
+    # The main worktree's root. `--git-common-dir` points at the shared `.git`
+    # directory from anywhere in the repository, including a linked worktree, so
+    # its parent is the main checkout.
+    def main_root
+      return @main_root if defined?(@main_root)
+
+      common = git("rev-parse", "--git-common-dir")
+      @main_root =
+        if common
+          File.realpath(File.dirname(File.expand_path(common, @root)))
+        else
+          # Not a git worktree, or no git: fall back to this directory's name.
+          @root
+        end
+    rescue Errno::ENOENT
+      @main_root = @root
+    end
+
+    # Returns the trimmed stdout, or nil when git fails for any reason --
+    # including not being installed.
+    def git(*args)
+      out, _err, status = Open3.capture3("git", "-C", @root, *args)
+      status.success? ? out.strip : nil
+    rescue Errno::ENOENT, Errno::EACCES
+      # No git on PATH. Not an error: derivation does not require it.
+      nil
+    end
+  end
+end

data/lib/copse.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+require_relative "copse/version"
+require_relative "copse/url_options"
+require_relative "copse/worktree"
+require_relative "copse/database"
+require_relative "copse/procfile"
+require_relative "copse/session"
+
+# Copse gives every Rails app and every git worktree its own hostname and its
+# own port, derived rather than assigned, so nothing collides and nothing has to
+# be chosen.
+module Copse
+  # The port space derivation draws from.
+  PORT_RANGE = (3000..9999).freeze
+
+  # Well-known service ports inside PORT_RANGE. These are excluded from the
+  # available set rather than probed around, so derivation stays a pure function
+  # of the hostname -- a reserved port is unreachable by construction.
+  #
+  # Changing this list shifts every index in AVAILABLE_PORTS above the change and
+  # therefore moves most derived ports. That is a breaking change to the promise
+  # that teammates derive the same port (R4); it requires a major version bump.
+  RESERVED_PORTS = [
+    3036, # vite_ruby dev server default
+    3306, # MySQL
+    3389, # RDP
+    4200, # Angular dev server
+    4369, # Erlang EPMD
+    5000, # macOS AirPlay Receiver, Flask
+    5060, # SIP
+    5173, # Vite default
+    5432, # PostgreSQL
+    5601, # Kibana
+    5672, # RabbitMQ
+    5900, # VNC
+    6379, # Redis
+    6432, # PgBouncer
+    7000, # macOS AirPlay Receiver, Cassandra
+    8000, # common alternate HTTP
+    8025, # Mailhog / Mailpit web UI
+    8080, # common alternate HTTP
+    8443, # common alternate HTTPS
+    8500, # Consul
+    8888, # Jupyter
+    9000, # PHP-FPM, SonarQube
+    9092, # Kafka
+    9200, # Elasticsearch
+    9418  # git protocol
+  ].freeze
+
+  # The ordered set derivation indexes into. Frozen at load: there is no
+  # configuration accessor, so there is no memoized state that can go stale.
+  AVAILABLE_PORTS = (PORT_RANGE.to_a - RESERVED_PORTS).freeze
+
+  # The supervisors `bin/dev` can be generated against. Only the supervisor
+  # differs: the derivation is a pure function of the worktree and knows nothing
+  # about either one.
+  PROCESS_MANAGERS = %w[foreman overmind].freeze
+
+  # Boots the app. This is what `bin/dev` calls.
+  #
+  # Returns the exit status of the foreground process so `bin/dev` can propagate
+  # it, which matters for shell `&&` chains and scripted use.
+  #
+  # `process_manager: :overmind` hands the whole Procfile to Overmind instead,
+  # replacing this process, and `args` is forwarded to it (`bin/dev -l web`).
+  def self.start(root: Dir.pwd, process_manager: :foreman, args: [])
+    session = Session.new(Worktree.new(root))
+
+    # `exec_overmind` never returns, so falling through to the foreman session
+    # means overmind is not installed *on this machine*. That is a fallback rather
+    # than an error on purpose: `bin/dev` is committed, and a teammate without
+    # overmind should still boot.
+    session.exec_overmind(args) if process_manager.to_s == "overmind" && session.overmind_available?
+
+    session.start
+  end
+
+  # The derived port for a hostname. A pure function: same hostname, same port,
+  # on every machine, in every terminal, across reboots and Ruby versions.
+  def self.port_for(hostname)
+    AVAILABLE_PORTS.fetch(Zlib.crc32(hostname) % AVAILABLE_PORTS.size)
+  end
+
+  # A second port derived from the same hostname, for a JS bundler's own dev
+  # server. Salting keeps it stable (R4) and inside the available set (so it can
+  # never land on a reserved service port) while guaranteeing it differs from the
+  # primary port for that same hostname.
+  def self.companion_port_for(hostname)
+    primary = port_for(hostname)
+    index = Zlib.crc32("vite:#{hostname}") % AVAILABLE_PORTS.size
+    candidate = AVAILABLE_PORTS.fetch(index)
+    return candidate unless candidate == primary
+
+    AVAILABLE_PORTS.fetch((index + 1) % AVAILABLE_PORTS.size)
+  end
+end
+
+require_relative "copse/railtie" if defined?(Rails::Railtie)

data/lib/generators/copse/install_generator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+require "copse"
+
+module Copse
+  module Generators
+    # `bin/rails generate copse:install`
+    #
+    # Wires an app to Copse the way `tailwindcss:install` wires up Tailwind: the
+    # app commits a `bin/dev` the whole team shares.
+    class InstallGenerator < ::Rails::Generators::Base
+      BIN_DEV = "bin/dev"
+      PROCFILE = "Procfile.dev"
+      MARKER = "Copse.start"
+      OVERMIND_MARKER = "process_manager: :overmind"
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :process_manager, type: :string, default: nil,
+                                     desc: "Supervisor bin/dev uses: #{Copse::PROCESS_MANAGERS.join(' or ')}"
+
+      def create_bin_dev
+        # Resolved before anything is written: detection reads the very bin/dev
+        # this method is about to overwrite.
+        process_manager
+
+        if exists?(BIN_DEV)
+          existing = File.read(absolute(BIN_DEV))
+
+          if existing.include?(MARKER)
+            if existing.include?(OVERMIND_MARKER) == overmind?
+              # Already wired to this supervisor. Running the generator twice is a
+              # no-op.
+              say_status :identical, BIN_DEV, :blue
+              return
+            end
+
+            # Same wiring, other supervisor. Switching is the whole point of the
+            # flag, and a Copse bin/dev holds nothing of the app's own to preserve,
+            # so this one is rewritten without a backup.
+            say_status :force, "#{BIN_DEV} (#{process_manager})", :yellow
+          else
+            # Teams keep real setup logic in bin/dev -- dependency checks, database
+            # bootstrapping. Replacing it without a copy would destroy that in one
+            # command with nothing to recover from, and prompting is not an option
+            # in a scripted run.
+            backup = "#{BIN_DEV}.before-copse"
+            FileUtils.cp(absolute(BIN_DEV), absolute(backup))
+            say_status :backup, backup, :yellow
+          end
+        end
+
+        template "dev.tt", BIN_DEV, force: true
+        chmod BIN_DEV, 0o755
+      end
+
+      def create_procfile_dev
+        if exists?(PROCFILE)
+          # R10: never overwritten, and never silently. Whatever the app already
+          # runs -- a tailwindcss:watch line, a vite line -- is left exactly as is.
+          say_status :skip, "#{PROCFILE} already exists, leaving it untouched", :yellow
+          return
+        end
+
+        template "Procfile.dev.tt", PROCFILE
+      end
+
+      def report_process_manager
+        return unless File.exist?(absolute(PROCFILE))
+
+        secondaries = Copse::Procfile.parse(File.read(absolute(PROCFILE))).secondaries
+
+        if overmind?
+          say ""
+          say "bin/dev hands all of Procfile.dev to overmind; attach with `overmind connect web`."
+          say "Keep `web` first in Procfile.dev: overmind gives each process base + index * 100."
+          say "Without overmind installed, bin/dev falls back to the foreman session."
+          # The fallback is not hypothetical -- overmind is probed per machine, so a
+          # teammate without it lands on foreman and needs it for these entries.
+          say "Which needs foreman, so keep `gem \"foreman\"` available too." if secondaries.any?
+          return
+        end
+
+        return if secondaries.empty?
+
+        say ""
+        say "Copse runs the `web` process in the foreground and hands the rest to foreman."
+        say "Add `gem \"foreman\"` to your Gemfile, or install it for the Ruby you use here."
+      end
+
+      private
+
+      # foreman unless asked otherwise -- with one exception. An app whose bin/dev
+      # already drives overmind gets the overmind variant by default, because the
+      # alternative is what this generator used to do: force-overwrite a working
+      # overmind setup with one that drops back to foreman.
+      def process_manager
+        @process_manager ||= begin
+          requested = options[:process_manager]
+
+          if requested.nil?
+            existing_overmind? ? "overmind" : "foreman"
+          else
+            unless Copse::PROCESS_MANAGERS.include?(requested)
+              raise Thor::Error, "--process-manager must be one of: #{Copse::PROCESS_MANAGERS.join(', ')}"
+            end
+
+            requested
+          end
+        end
+      end
+
+      def overmind? = process_manager == "overmind"
+
+      # Detection looks for a bin/dev that *runs* overmind, not one that merely says
+      # the word: `# migrated off overmind` in a comment of a foreman script must
+      # not flip the supervisor. Either the Copse marker, or an `overmind start`
+      # invocation (`s` is overmind's own alias for it).
+      OVERMIND_INVOCATION = /\bovermind\s+s(?:tart)?\b/
+
+      def existing_overmind?
+        return false unless exists?(BIN_DEV)
+
+        contents = File.read(absolute(BIN_DEV))
+        contents.include?(OVERMIND_MARKER) || contents.match?(OVERMIND_INVOCATION)
+      end
+
+      # Interpolated into the bin/dev template. ARGV is forwarded only on the
+      # overmind path, where it has somewhere to go (`bin/dev -l web`); the foreman
+      # session takes no arguments.
+      def copse_start_arguments
+        overmind? ? "(#{OVERMIND_MARKER}, args: ARGV)" : ""
+      end
+
+      def exists?(relative) = File.exist?(absolute(relative))
+
+      def absolute(relative) = File.join(destination_root, relative)
+    end
+  end
+end

data/lib/generators/copse/templates/Procfile.dev.tt

@@ -0,0 +1 @@
+web: bin/rails server

data/lib/generators/copse/templates/dev.tt

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "copse"
+
+exit Copse.start<%= copse_start_arguments %>

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: copse
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kieran Klaassen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-24 00:00:00.000000000 Z
+dependencies: []
+description: Copse derives a hostname and a port for each Rails app and each git worktree,
+  so several can run at once without colliding and without anyone choosing numbers.
+  The web process stays in the foreground and owns the TTY, so binding.irb and debug
+  keep working. No daemon, no reverse proxy, no privileged listener, and no runtime
+  dependencies.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/copse.rb
+- lib/copse/database.rb
+- lib/copse/procfile.rb
+- lib/copse/railtie.rb
+- lib/copse/session.rb
+- lib/copse/url_options.rb
+- lib/copse/version.rb
+- lib/copse/worktree.rb
+- lib/generators/copse/install_generator.rb
+- lib/generators/copse/templates/Procfile.dev.tt
+- lib/generators/copse/templates/dev.tt
+homepage: https://github.com/kieranklaassen/copse
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kieranklaassen/copse
+  source_code_uri: https://github.com/kieranklaassen/copse
+  changelog_uri: https://github.com/kieranklaassen/copse/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A hostname and a port for every Rails app and every git worktree.
+test_files: []