copse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08369533669364d4fdb1d9f8f3b634392c4ac690dceeecd0b236965bccbffa26'
+  data.tar.gz: b19a227b24020e7564a1789840ae0e0401ad0cef97f9c0f2a5f5d95067de62f6
+SHA512:
+  metadata.gz: 3543263f409eda9b9dd5960250ab2d3a851af4868bad5d5b493a91b91886bacf6b8ebafbe9c5c4d470b19bce7eeab0423c0ee1710971e6a40a023a1299f14088
+  data.tar.gz: 38792c0ba1a9e9155ba9f11acf9ab7b48823953d11a8e60a1101faef7513735bb547aac492f533d42396a353614a33333f601645dca4398cc910fa4a50786921

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.1.0 (2026-07-24)
+
+First release.
+
+- Derives a hostname per app and per git worktree: `<project>.localhost` for a
+  main worktree, `<branch>.<project>.localhost` for a linked one, falling back to
+  the directory name on a detached `HEAD` or outside git entirely.
+- Derives a stable port from the hostname — `CRC32` indexed into `3000..9999`
+  minus 25 well-known service ports. A pure function, identical across machines,
+  terminals, reboots, and Ruby versions, with no stored state and no coordination.
+- Runs the `web` process in the foreground with the terminal's stdin, stdout, and
+  stderr, so `binding.irb` and `debug` work as they do under a bare
+  `rails server`. Remaining `Procfile.dev` entries run under foreman and are
+  terminated when the foreground process exits.
+- Exports `PORT`, `COPSE_PORT`, `COPSE_HOST`, `COPSE_URL`, and `VITE_RUBY_PORT`.
+  Non-`web` processes should read `COPSE_PORT`: foreman rewrites `PORT` per child.
+- Sets `default_url_options` for routes and Action Mailer in development, only
+  when Copse booted the app and only when the app has not set its own `host`.
+- Gives a linked worktree its own development database, derived from the same slug
+  as the hostname: `cora_development` becomes `cora_development_fix_billing`. A
+  main worktree keeps the database it already has, and `config/database.yml` is
+  never modified — the loaded configuration is renamed at boot. Development only;
+  file-backed databases (SQLite) and entries marked `database_tasks: false` are
+  left alone, replicas follow their primary, and names are capped at 63 bytes.
+  Copse does not create the database: run `bin/rails db:prepare`. The suffix is
+  derived from the checkout on disk rather than from Copse's own environment, so
+  `db:prepare` and `bin/rails console` reach the same database as `bin/dev`, and
+  a stale `COPSE_DATABASE_SUFFIX` cannot rename a main worktree's database.
+- Exports `COPSE_DATABASE_SUFFIX` in a linked worktree, for other processes to
+  read; Copse never reads it back. In a main worktree it is removed from the child
+  environment, so a stale value inherited from another worktree's session cannot
+  be believed there either.
+- `bin/rails generate copse:install` wires up `bin/dev` and creates a minimal
+  `Procfile.dev` only when the app has none.
+- Supports Overmind as an alternative supervisor:
+  `copse:install --process-manager=overmind` writes a `bin/dev` that hands the
+  whole `Procfile.dev`, `web` included, to `overmind start` with the derived
+  environment — no split session, because Overmind's per-process pty already
+  keeps the debugger working. An app whose `bin/dev` already drives Overmind gets
+  that variant by default rather than being downgraded to foreman. Overmind is
+  probed at run time, so a teammate without it falls back to the foreman session.
+  The derived port is passed to Overmind as `-p` and `OVERMIND_SKIP_ENV=1` is set,
+  so no env file can beat it — the same reason foreman is given `--env /dev/null`.
+- Warns when a Procfile entry runs the Tailwind CLI with a bare `--watch`, which
+  exits when stdin closes and so ends the whole foreman session with status 0.
+
+### Notes
+
+- Zero runtime dependencies. Foreman is invoked as a subprocess, never required,
+  and is only needed for apps with non-`web` Procfile entries.
+- Requires Ruby >= 3.2.0.
+- Pipelines and background (`&`) Procfile lines cannot be made signal-transparent;
+  Copse warns and leaves them alone. See the README.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kieran Klaassen
+
+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,220 @@
+# Copse
+
+A hostname and a port for every Rails app and every git worktree — while the debugger keeps working.
+
+```
+~/code/cora             on main         →  http://cora.localhost:5368
+~/code/cora-fix-billing on fix-billing  →  http://fix-billing.cora.localhost:4783
+~/code/other-app        on main         →  http://other-app.localhost:8119
+```
+
+Derived from the directory name and the branch, so nothing collides and nothing has to be chosen. No daemon, no reverse proxy, no privileged listener, zero runtime dependencies.
+
+A linked worktree gets its own development database from the same derivation — `cora_development_fix_billing`. See [Databases](#databases).
+
+## Installation
+
+```ruby
+group :development do
+  gem "copse"
+end
+```
+
+```sh
+bundle install
+bin/rails generate copse:install
+bin/dev
+```
+
+The generator writes a `bin/dev` that calls Copse, and creates `Procfile.dev` only if you don't have one. An existing `Procfile.dev` is never modified; an existing `bin/dev` is copied to `bin/dev.before-copse` first.
+
+Already on [Overmind](https://github.com/DarthSim/overmind)? The generator sees it in your `bin/dev` and keeps it. Ask for either supervisor explicitly with `--process-manager=overmind` or `--process-manager=foreman`.
+
+## Why
+
+Two apps both want port 3000, so you hand-assign `-p 3001` and then forget which app owns which number — and your teammates picked different ones. Worse, everything lands on `localhost`, so every app shares one cookie jar and one `localStorage`: signing into one signs you out of another.
+
+The hostname is not routing traffic. It gives each app a distinct **browser origin**, which is the half that fixes the cookie jar, and that needs no listener.
+
+### Versus puma-dev
+
+[puma-dev](https://github.com/puma/puma-dev) gives you a bare `https://app.test` with no port. It buys that by running your app as a background daemon, which takes the web process off your terminal — and `binding.irb` with it. Rails' own `bin/dev` stays local but multiplexes stdin through foreman, which breaks the debugger too ([rails/rails#52459](https://github.com/rails/rails/issues/52459)).
+
+Copse runs `web` in the foreground, holding your terminal's stdin and process group; everything else in `Procfile.dev` goes to foreman. The trade is explicit: **you keep the `:5368`.** If a bare hostname matters more than your debugger, use puma-dev.
+
+## Names
+
+| Where you are | Hostname |
+|---|---|
+| Main worktree | `<project>.localhost` |
+| Linked worktree | `<branch>.<project>.localhost` |
+| Linked worktree, detached `HEAD` | `<directory>.<project>.localhost` |
+| Not a git repository | `<directory>.localhost` |
+
+`<project>` is always the **main** worktree's directory name, so `~/code/cora-fix-billing` on `fix-billing` is `fix-billing.cora.localhost`, not `cora-fix-billing.cora.localhost`.
+
+Names reduce to one DNS label: lowercased, anything outside `[a-z0-9]` collapsed to `-`, capped at 63 characters. `feat/billing-v2` → `feat-billing-v2`. It's a whitelist, not a substitution — git permits `;`, `$(`, and quotes in branch names, and the result reaches your environment and a generated Procfile.
+
+## Ports
+
+`CRC32(hostname)` indexed into `3000..9999` minus 25 well-known service ports. A pure function: same hostname, same port, on every machine and across reboots and Ruby versions, with no stored state and no coordination.
+
+Uncoordinated means collisions are possible. Measured over 20,000 seeded trials against 6,975 available ports:
+
+| Worktrees at once | Chance two share a port |
+|---|---|
+| 10 | ~0.6% |
+| 10, using Vite | ~2.5% |
+| 40 | ~10% |
+
+Vite doubles it because a Vite app draws two ports. On a collision Copse names the port and the hostname instead of leaving you with Puma's bare `Address already in use`; rename a worktree or branch to fix it.
+
+Changing the range or the reserved list would move nearly every derived port, so it's a breaking change gated by a test that pins the whole set.
+
+## Environment
+
+| Variable | Value |
+|---|---|
+| `COPSE_HOST` | `cora.localhost` |
+| `COPSE_URL` | `http://cora.localhost:5368` |
+| `COPSE_PORT` | the derived port |
+| `PORT` | the derived port — **`web` process only** |
+| `VITE_RUBY_PORT` | the derived companion port |
+| `COPSE_DATABASE_SUFFIX` | `fix_billing` — **linked worktrees only**, actively unset in a main one |
+
+`COPSE_DATABASE_SUFFIX` is exported for your processes to read; Copse never reads it back. In a main worktree it's *removed* from the child environment rather than merely left unset, so a copy inherited from another worktree's session can't be believed. And the rename below is derived from the checkout on disk, so no stale copy of this variable — a shell opened from a linked worktree, a leftover line in `.env` — can rename a main worktree's database.
+
+**In a non-`web` process, read `COPSE_PORT`, not `PORT`.** Foreman assigns its children `base_port + index * 100`, so a secondary's `PORT` is a number Copse never derived. Copse deliberately hands foreman an offset base, so no secondary is ever given the `web` process's own port.
+
+In development Copse also sets `default_url_options` for routes and Action Mailer. It stays out of the way otherwise: not in other environments, not under a plain `bin/rails server`, and not when your app set its own `host`. Puma still prints `Listening on http://127.0.0.1:5368` — that's the address it bound; Copse's line is the name to visit.
+
+`VITE_RUBY_PORT` is picked up by `vite_ruby` automatically. Vite is the only bundler that needs it: esbuild via `jsbundling-rails`, `cssbundling-rails`, `tailwindcss-rails`, Propshaft, and importmap have no port at all.
+
+## Databases
+
+A hostname and a port keep two worktrees from colliding in the browser; they still share one schema. So in **development**, a linked worktree also gets its own database — named after the same slug the hostname uses, with `_` instead of `-`:
+
+```
+~/code/cora             on main         →  cora_development
+~/code/cora-fix-billing on fix-billing  →  cora_development_fix_billing
+```
+
+**A main worktree keeps the database it already has**, which is what makes this safe to add to an existing app: the database you've been using never moves. `config/database.yml` is not modified — Copse renames the loaded configuration at boot.
+
+Copse doesn't create it. Rails already tells you when a database is missing, and creating one is not something `bin/dev` should do behind your back:
+
+```sh
+bin/rails db:prepare
+```
+
+That works because the rename is derived from the checkout on disk, not from the environment `bin/dev` exports — so `db:prepare`, `bin/rails console`, and `bin/dev` all reach the same database, whether or not Copse started them.
+
+What is left alone:
+
+- **Every environment but development.** Production has one checkout, and Rails already partitions the test database per parallel worker.
+- **SQLite and any other file-backed database.** A linked worktree is its own directory, so `storage/development.sqlite3` is already a separate database; renaming would only move the file.
+- **Databases marked `database_tasks: false`** — that's how an app says Rails doesn't own it. Replicas *are* renamed, since they point at the same database as their primary.
+
+Every development entry in a multi-database `database.yml` is renamed, not just `primary`. Names are capped at 63 bytes (PostgreSQL truncates past that with only a notice, MySQL rejects past 64); the suffix is what gets trimmed, so two very long branch names can share a database the same way they can share a hostname.
+
+## foreman
+
+Needed only if `Procfile.dev` has anything besides a `web` line:
+
+```ruby
+gem "foreman", group: :development
+```
+
+Teardown is verified against **0.90.0+**; older versions warn. Under a version manager gems are per-Ruby-version, so switching Ruby can make foreman vanish with no change to your code.
+
+## overmind
+
+```sh
+bin/rails generate copse:install --process-manager=overmind
+```
+
+Overmind fixes the debugger the other way: every process gets its own tmux pty, so stdin is never multiplexed and you attach with `overmind connect web`. That makes the foreground-`web` split pointless — under Overmind, Copse contributes only the environment and hands the whole `Procfile.dev` over:
+
+```ruby
+exit Copse.start(process_manager: :overmind, args: ARGV)
+```
+
+Consequences of Overmind supervising everything, `web` included:
+
+- **`PORT` is Overmind's, `base + index * 100`.** So `web` must be the **first** entry in `Procfile.dev` to get the derived port. Copse warns if it isn't. Every process still gets the derived port under `COPSE_PORT`.
+- **The derived port is passed as `-p`, and `OVERMIND_SKIP_ENV=1` is set.** Overmind applies env files *over* the environment it's handed, so a stale `PORT` in one would otherwise win. `-p` is what defeats that — including in `.overmind.env`, which `OVERMIND_SKIP_ENV` doesn't skip. Neither touches your app's own loading: `dotenv-rails` still reads `.env` inside Rails, exactly as on the foreman path.
+- `bin/dev`'s arguments go to `overmind start` *after* Copse's, so `bin/dev -l web` works and `bin/dev -p 4000` still overrides the derived port.
+- **An explicit `--port` on the `web` line wins, and Copse only warns.** `rails server` honours the flag over `PORT`. The foreman path strips it, but that's Copse building the command itself; here Overmind runs your Procfile, and rewriting it into a copy would mean the file you edit and the file `overmind restart` reloads were different things. Remove the flag.
+- No pty problems, so none of the stdin traps below apply.
+
+`bin/dev` is committed, and Overmind is a binary rather than a gem, so it's checked at run time, not generate time: a teammate without Overmind falls back to the foreman session automatically. Which is a reason to keep `foreman` in the Gemfile anyway if `Procfile.dev` has non-`web` entries — that machine will need it.
+
+## Where `*.localhost` resolves
+
+RFC 6761 §6.3 makes `.localhost` special with a *SHOULD*, not a MUST, so support is uneven. Two separate questions: does the client resolve the name, and does it then reach a server bound to IPv4 loopback — which is what Rails binds, while `*.localhost` resolves `::1` first.
+
+Measured on macOS 26.5.2, no `/etc/hosts` entry:
+
+| Client | Resolves | Connects | |
+|---|---|---|---|
+| Chromium / Chrome / Edge | ✅ | ✅ | **verified here**, nested labels included |
+| `curl` 8.2.1 | ✅ | ✅ | **verified here** — falls back past `::1` |
+| System resolver | ✅ | — | **verified here** — `["::1", "127.0.0.1"]` |
+| Firefox | ✅ | ✅ | *unverified* — built in since Firefox 84 |
+| Safari, macOS 26+ | ✅ | ✅ | *unverified* — fix is in the OS resolver, which **is** verified |
+| Safari / `curl`, macOS ≤ 15 | ❌ | — | *unverified* — [WebKit #160504](https://bugs.webkit.org/show_bug.cgi?id=160504) |
+| Linux + `systemd-resolved` | ✅ | — | *unverified* — `systemd-resolved.service(8)` |
+| Linux, bare glibc | ❌ | — | *unverified* — no `.localhost` case in glibc |
+
+Rows marked *unverified* come from primary sources, not from this machine.
+
+For a ❌ row, add a hosts entry — with two caveats:
+
+```
+127.0.0.1  fix-billing.cora.localhost
+```
+
+Neither glibc nor the macOS resolver supports wildcards, so that's **one line per hostname, meaning one per branch**. And it does nothing for Chrome, which hardcodes `.localhost` and [ignores your hosts file](https://issues.chromium.org/issues/41175806) for these names.
+
+On macOS ≤ 15 or bare-glibc Linux and need Safari or `curl`? puma-dev's resolver approach doesn't have this gap. That's a real reason to prefer it.
+
+## Requirements
+
+- Ruby >= 3.2.0 (Rails 8.1's own floor; note 3.2 reached EOL 2026-04-01)
+- Rails 7.1+ for the generator and URL options — the derivation itself needs neither Rails nor git
+- `foreman` >= 0.90.0, only for apps with non-`web` Procfile entries — or Overmind instead, on the `--process-manager=overmind` path
+
+Rails 8's development host allowlist already includes `.localhost`, so no `config.hosts` change is needed.
+
+## Notes
+
+- `Ctrl-C` can take up to foreman's shutdown timeout (5s default) if a watcher doesn't exit promptly.
+- **Coming from Overmind, a bare `tailwindcss --watch` will take your whole session down.** The Tailwind CLI exits when stdin closes; Overmind's pty kept it open, foreman gives it none. The watcher exits **0** a second or two after boot and foreman's cascade ends `web` with it, so a CSS problem reads as an intentional shutdown. Use `--watch=always`. Copse warns when it sees the bare flag.
+- Some Procfile lines cannot be made signal-transparent, so Copse warns and leaves them exactly as written rather than rewriting them into something subtly different. Their children may survive teardown; split them into separate entries to fix it. The shapes are a **pipeline** (`a | b`), a **background `&`**, a **command substitution** (`$(...)` or backticks), and a **subshell** (`(...)`). Each keeps a shell in front of the real process, and no `exec` placement collapses that into one signalable pid — `exec (cd x && y)` is not even valid shell syntax.
+- Out of scope: reverse proxy, daemon, TLS, port registry, and `/etc/hosts` management.
+
+## History
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+Issues and pull requests are welcome. Especially useful:
+
+- **A `.localhost` row you can verify.** The resolution table above marks rows *unverified* when they come from primary sources rather than a machine — replacing one with a measurement is a real contribution.
+- **A Procfile line Copse handles wrongly.** Include the line verbatim.
+
+To get set up:
+
+```sh
+git clone https://github.com/kieranklaassen/copse.git
+cd copse
+bundle install
+bundle exec rake test
+```
+
+The suite drives real processes rather than mocking them, so it needs `foreman` (a dev dependency) and takes about a minute. Two tests bind a derived port; they fail if something else on your machine already holds it. `BUNDLE_GEMFILE=gemfiles/rails71.gemfile bundle exec rake test` checks the oldest supported Rails.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/copse/database.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "worktree"
+
+module Copse
+  # Decides whether Copse renames the development database, and to what.
+  #
+  # Same shape as UrlOptions and for the same reason: the decisions are
+  # Rails-free so they can be tested without booting an application, and the
+  # railtie is only the wiring.
+  #
+  # The suffix is derived from the checkout on disk rather than from the
+  # environment Copse exports, so `bin/rails db:prepare` and `bin/rails console`
+  # in a linked worktree reach the same database `bin/dev` does. A database that
+  # only existed when Copse booted the app would be a database no rake task could
+  # create.
+  module Database
+    # A main worktree keeps its plain database name, so only a linked worktree is
+    # renamed. That is what makes this safe to add to an existing app: the
+    # database you already have is never the one that moves.
+    #
+    # PostgreSQL silently truncates identifiers past 63 bytes and MySQL rejects
+    # them past 64, so the composed name is capped here rather than left to the
+    # server. The cap trims the suffix, never the app's own database name --
+    # which can make two very long branch names share a database, exactly as the
+    # 63-character DNS label cap can make them share a hostname.
+    NAME_LIMIT = 63
+
+    # Adapters whose "database" is a path rather than a name on a shared server.
+    # A linked worktree is a separate directory, so these are already separate
+    # databases; renaming would only move the file inside the worktree.
+    FILE_BACKED_ADAPTERS = %w[sqlite3 sqlite].freeze
+
+    # Development only. The point of the rename is that several worktrees of one
+    # app can run at once; production has one, and a test database is already
+    # partitioned per worker by Rails itself.
+    def self.apply?(rails_env:)
+      rails_env.to_s == "development"
+    end
+
+    # The suffix for this checkout, or nil in a main worktree.
+    #
+    # The checkout on disk is the only authority, never the exported
+    # COPSE_DATABASE_SUFFIX -- which is deliberate rather than just simple. That
+    # variable can outlive the session that set it: a shell opened from a linked
+    # worktree's `bin/dev`, or a stale line in the app's own `.env` that
+    # dotenv-rails loads. Reading it here would let either one rename a *main*
+    # worktree's database, which is the one promise this feature makes.
+    def self.suffix(root: Dir.pwd)
+      Worktree.new(root).database_suffix
+    end
+
+    # The renamed database, or nil when this configuration is left alone.
+    def self.rename(database:, adapter:, suffix:)
+      name = database.to_s
+      return nil if suffix.to_s.empty? || name.empty?
+      return nil if FILE_BACKED_ADAPTERS.include?(adapter.to_s) || name.include?("/")
+      # Idempotent: the railtie can run again in the same process (a reload, a
+      # second `db:prepare` in one rake invocation) and must not keep appending.
+      return nil if name.end_with?("_#{suffix}")
+
+      compose(name, suffix.to_s)
+    end
+
+    # Renames every development database in an
+    # ActiveRecord::DatabaseConfigurations, in place.
+    #
+    # In place is the load-bearing part. Active Record's own
+    # `active_record.initialize_database` initializer calls `establish_connection`
+    # before this runs, so a *replacement* configuration object would be ignored
+    # by the pool that already exists. Mutating the object the pool holds works
+    # because the adapter is built from it lazily, at first checkout.
+    #
+    # Returns the names that changed, for reporting.
+    def self.apply(configurations, suffix:, env_name: "development")
+      configurations.configs_for(env_name: env_name, include_hidden: true).filter_map do |config|
+        # `database_tasks: false` is how an app says Rails does not own this
+        # database -- a legacy or shared server it only reads. Copse does not get
+        # to rename something the app cannot create.
+        #
+        # The key is read directly rather than through `database_tasks?`, which is
+        # also false for every replica. A replica points at the same database as
+        # its primary, so leaving it behind would send reads to another worktree's
+        # data.
+        next unless config.configuration_hash.fetch(:database_tasks, true)
+
+        renamed = rename(database: config.database, adapter: config.adapter, suffix: suffix)
+        next if renamed.nil?
+
+        config._database = renamed
+        renamed
+      end
+    end
+
+    # Composes the name, or nil when the cap leaves no room for a suffix at all
+    # -- in which case the database is left alone rather than renamed to
+    # something that cannot be told apart from another worktree's.
+    def self.compose(database, suffix)
+      room = NAME_LIMIT - database.bytesize - 1
+      return nil if room < 1
+
+      "#{database}_#{suffix[0, room]}"
+    end
+    private_class_method :compose
+  end
+end

data/lib/copse/procfile.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Copse
+  # Reads a Procfile and splits it into the foreground `web` process and the rest.
+  #
+  # Parsing only. The lifecycle -- spawning, teardown, signal handling -- lives in
+  # Session, so everything here is a pure function that can be tested without a
+  # process tree.
+  class Procfile
+    Entry = Struct.new(:name, :command, keyword_init: true)
+
+    WEB = "web"
+
+    # Control operators that make Ruby's Process.spawn hand the string to
+    # /bin/sh, which then becomes the pid foreman records.
+    FIXABLE_SEPARATORS = [";", "&&", "||"].freeze
+
+    # Shapes no `exec` placement can make signal-transparent.
+    #
+    # A pipeline or a background `&` keeps a shell waiting on the whole thing. A
+    # command substitution or subshell is worse: splicing `exec` before the last
+    # operator would put it *inside* the parentheses, so the outer command is never
+    # exec'd at all -- and `exec (cd x && y)` is not even valid shell syntax, so
+    # there is no prefix form to fall back to. Refusing to rewrite what cannot be
+    # reasoned about beats producing something subtly wrong.
+    UNFIXABLE_SEPARATORS = ["|", "&"].freeze
+    UNFIXABLE_GROUPINGS = ["$(", "`", "("].freeze
+    UNFIXABLE = (UNFIXABLE_SEPARATORS + UNFIXABLE_GROUPINGS).freeze
+
+    # The characters Ruby itself treats as requiring a shell (mirrors
+    # rb_exec_fillarg). A command containing any of these is spawned via
+    # `/bin/sh -c` even when it is a single command.
+    SHELL_REQUIRED = /[*?{}\[\]<>()~&|\\$;'"`\n#]/.freeze
+
+    # Matches an explicit port flag on a command line: `-p 3000`, `--port 3000`,
+    # or `--port=3000`.
+    PORT_FLAG = /\s+(?:-p|--port)(?:=|\s+)\d+\b/.freeze
+
+    attr_reader :entries
+
+    def initialize(entries)
+      @entries = entries
+    end
+
+    def self.parse(text)
+      entries = text.to_s.lines.filter_map do |line|
+        stripped = line.strip
+        next if stripped.empty? || stripped.start_with?("#")
+
+        name, command = stripped.split(":", 2)
+        next if command.nil?
+
+        command = command.strip
+        next if command.empty?
+
+        Entry.new(name: name.strip, command: command)
+      end
+      new(entries)
+    end
+
+    def self.load(path)
+      File.exist?(path) ? parse(File.read(path)) : nil
+    end
+
+    # The `web` entry, matched by name. Real templates ship
+    # `web: env RUBY_DEBUG_OPEN=true bin/rails server`, so never assume a bare
+    # `bin/rails server`.
+    def web
+      entries.find { |entry| entry.name == WEB }
+    end
+
+    # Everything that is not `web`. These go to foreman.
+    def secondaries
+      entries.reject { |entry| entry.name == WEB }
+    end
+
+    # Removes an explicit port flag from a command.
+    #
+    # An explicit `--port` beats the PORT environment variable in `rails server`,
+    # so a Procfile shipping `web: bin/rails s --port 3000` -- which vite_ruby's
+    # own example does -- would silently boot on 3000 and defeat the derived
+    # port. Stripping the flag is what makes the stock template work unchanged.
+    def self.strip_port_flag(command)
+      command.gsub(PORT_FLAG, "")
+    end
+
+    def self.port_flag?(command)
+      command.match?(PORT_FLAG)
+    end
+
+    # Rewrites a command so the process foreman records is the real one, not a
+    # `/bin/sh` that will not forward SIGTERM.
+    #
+    # Returns [rewritten_command, warning_or_nil].
+    #
+    # Three nearby forms are wrong and were measured wrong:
+    #   `exec sh -c "a; b"`   -> recorded pid is still sh; the orphan survives
+    #   `exec a; b`           -> exec replaces the shell with `a`; `b` never runs
+    #   `a | exec b`          -> the recorded pid is the shell awaiting the pipeline
+    # What works is inserting `exec` before the *final* command of a chain.
+    #
+    # A pipeline or a background `&` cannot be collapsed into one pid by any exec
+    # placement, so those are left alone and warned about instead of silently
+    # "fixed".
+    def self.signal_transparent(command)
+      # A trailing separator would otherwise splice a bare `exec ` with nothing
+      # after it -- a silent no-op that leaves the shell in front of the process.
+      command = command.sub(/[\s;]+\z/, "")
+      operators = top_level_operators(command)
+
+      if operators.any? { |op| UNFIXABLE.include?(op[:token]) }
+        return [command, unfixable_warning(command, operators)]
+      end
+
+      return [command, nil] if operators.empty? && !command.match?(SHELL_REQUIRED)
+
+      # A single command that still needs a shell (a redirect, a glob, a quoted
+      # argument): prefixing exec replaces the shell with it, which is correct.
+      return [exec_prefixed(command), nil] if operators.empty?
+
+      # A chain: exec the last command. A Procfile entry whose final command is
+      # short-lived would exit immediately and stop being a long-running process
+      # at all, so "the process we care about is last" is forced by what a
+      # Procfile entry is, not merely a convention.
+      last = operators.last
+      cut = last[:at] + last[:token].length
+      head = command[0, cut]
+      tail = command[cut..].to_s
+      indent = tail[/\A\s*/]
+      ["#{head}#{indent}#{exec_prefixed(tail.lstrip)}", nil]
+    end
+
+    # `exec` cannot take a leading VAR=value assignment: `exec FOO=1 cmd` makes the
+    # shell look for a program literally named `FOO=1` and fail with exit 127. Going
+    # through env(1) preserves the assignment and still replaces the shell, so the
+    # recorded pid is the real process either way.
+    ASSIGNMENT_PREFIX = /\A[A-Za-z_][A-Za-z0-9_]*=/.freeze
+
+    def self.exec_prefixed(command)
+      return "exec env #{command}" if command.match?(ASSIGNMENT_PREFIX)
+
+      "exec #{command}"
+    end
+
+    # Finds control operators outside quotes.
+    #
+    # Quote-awareness matters: `bin/rails runner 'A.watch; B.watch'` is a single
+    # command with a quoted semicolon, not a chain, and treating it as one would
+    # rewrite a working line.
+    def self.top_level_operators(command)
+      operators = []
+      in_single = false
+      in_double = false
+      index = 0
+
+      while index < command.length
+        char = command[index]
+
+        if in_single
+          in_single = false if char == "'"
+        elsif in_double
+          if char == "\\"
+            index += 1
+          elsif char == '"'
+            in_double = false
+          end
+        else
+          case char
+          when "'" then in_single = true
+          when '"' then in_double = true
+          when "\\" then index += 1
+          when "`" then operators << { token: "`", at: index }
+          when "$"
+            if command[index + 1] == "("
+              operators << { token: "$(", at: index }
+              index += 1
+            end
+          when "("
+            operators << { token: "(", at: index }
+          when ";", "\n" then operators << { token: ";", at: index }
+          when "&"
+            if command[index + 1] == "&"
+              operators << { token: "&&", at: index }
+              index += 1
+            elsif redirect_ampersand?(command, index)
+              # Part of a redirect (`2>&1`, `>&2`, `&>file`), not a control
+              # operator. Reading it as a background `&` made a perfectly ordinary
+              # `yarn build --watch 2>&1` skip the exec transform and keep a shell
+              # in front of the process -- a real orphan on any /bin/sh that forks.
+              nil
+            else
+              operators << { token: "&", at: index }
+            end
+          when "|"
+            if command[index + 1] == "|"
+              operators << { token: "||", at: index }
+              index += 1
+            else
+              operators << { token: "|", at: index }
+            end
+          end
+        end
+
+        index += 1
+      end
+
+      operators
+    end
+
+    # True when the `&` at `index` belongs to a redirect rather than being a
+    # control operator: `2>&1` and `>&2` have `>` (or `<`) before it, `&>file` has
+    # `>` after it.
+    def self.redirect_ampersand?(command, index)
+      return true if command[index + 1] == ">"
+
+      before = command[0, index].rstrip
+      before.end_with?(">", "<")
+    end
+
+    # A bare `--watch` on the Tailwind CLI, which is fatal under foreman.
+    #
+    # `tailwindcss --watch` exits when stdin closes. Overmind gives every process a
+    # pty so stdin stays open; foreman does not, so the watcher exits **0** a
+    # second or two after boot and foreman's cascade takes `web` down with it. The
+    # zero status makes it read like an intentional shutdown with nothing linking
+    # it to CSS, which is why this is worth a line of output. `--watch=always` is
+    # the fix.
+    TAILWIND_BARE_WATCH = /\btailwindcss\b/.freeze
+    BARE_WATCH_FLAG = /--watch(?![=\w])/.freeze
+
+    def self.stdin_sensitive_warning(command)
+      return nil unless command.match?(TAILWIND_BARE_WATCH) && command.match?(BARE_WATCH_FLAG)
+
+      "runs the tailwindcss CLI with a bare `--watch`, which exits when stdin closes. " \
+        "Under foreman that ends the whole session a moment after boot, with exit status 0. " \
+        "Use `--watch=always`."
+    end
+
+    def self.unfixable_warning(_command, operators)
+      tokens = operators.map { |op| op[:token] }
+      # Groupings are named before separators: a pipe inside `$( )` is incidental,
+      # and the substitution is the reason the line cannot be rewritten.
+      kind =
+        if tokens.include?("$(") || tokens.include?("`") then "a command substitution"
+        elsif tokens.include?("(") then "a subshell"
+        elsif tokens.include?("|") then "a pipeline"
+        else "a background &"
+        end
+
+      "uses #{kind}, which keeps a shell in front of it -- its child processes may " \
+        "survive teardown. Consider splitting it into separate Procfile entries."
+    end
+  end
+end