copse 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08369533669364d4fdb1d9f8f3b634392c4ac690dceeecd0b236965bccbffa26'
-  data.tar.gz: b19a227b24020e7564a1789840ae0e0401ad0cef97f9c0f2a5f5d95067de62f6
+  metadata.gz: a8272bcb50acd3e7cdd810ec98b4be8d2af79c461b83f001dda7dd406e36dd7f
+  data.tar.gz: ab24056f37f69404a7f2182ef1ef2b3045b34ed3cb0b6a33511286b6e5d490c6
 SHA512:
-  metadata.gz: 3543263f409eda9b9dd5960250ab2d3a851af4868bad5d5b493a91b91886bacf6b8ebafbe9c5c4d470b19bce7eeab0423c0ee1710971e6a40a023a1299f14088
-  data.tar.gz: 38792c0ba1a9e9155ba9f11acf9ab7b48823953d11a8e60a1101faef7513735bb547aac492f533d42396a353614a33333f601645dca4398cc910fa4a50786921
+  metadata.gz: 41ddd256af9c44ea14c6edd638167d0c1e4540f3c0fe52a2b21b45800ebb272ba81271a03d11329410b6090e981b4e490af4693d67e02f49602a679c7c48dbac
+  data.tar.gz: a5e6859a15cba6b1476eea240b92636f79b2744e292688b96f624012f3082b10935357fbbbe7d119a04204a4a389f071628e1e3f334d8122d489e46f4d695adf

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.2.0 (2026-09-10)
+
+- Adds an optional second naming mode: `<branch>.<project>.<machine>.local`,
+  published over multicast DNS, instead of `<branch>.<project>.localhost`
+  published to nobody. `.localhost` is a *SHOULD* that Safari on macOS ≤ 15 and
+  bare-glibc Linux do not honour; `.local` is answered by the mDNS responder every
+  desktop and phone already runs, and is answered for every device on the network
+  — so the app can be opened from a phone. Opt in per machine with
+  `COPSE_ZEROCONF=1`, or for a team with `Copse.start(zeroconf: true)`.
+  One trade to know about: `.local` is not a secure context and `.localhost` is,
+  so service workers, `getUserMedia`, geolocation, WebAuthn, `crypto.subtle` and
+  the rest of the secure-context features stop working under it. See the README.
+- The derived port is now a function of the `.localhost` hostname whatever mode is
+  in use, so turning zeroconf naming on moves no port — not for the developer
+  turning it on, and not against teammates who have not. Nothing changes for an
+  app on `.localhost`.
+- Exports `BINDING=0.0.0.0` and appends the advertised name to
+  `RAILS_DEVELOPMENT_HOSTS`, on the zeroconf path only. A `.local` name resolves
+  to this machine's network address rather than loopback, and Rails' development
+  host allowlist covers `.localhost` and `.test` but not `.local`. An inherited
+  `BINDING` wins, as does an explicit `-b` or a `bind` in `config/puma.rb`.
+- `COPSE_SUBDOMAINS=jane,peter` (or `subdomains:`) publishes extra names under the
+  app's own, for apps that serve one subdomain per tenant. Under `.localhost`
+  every label resolves for free; mDNS answers only for names something announced.
+- The names are withdrawn when the session ends. Under Overmind, which replaces
+  Copse's process, the advertiser is forked into a process that watches Overmind's
+  pid rather than being kept in a thread that the `exec` would destroy.
+- The `zeroconf` gem (>= 1.2.0) stays an optional dependency and is required only
+  when the mode is asked for. A machine without it says so in one line and boots
+  on `.localhost`, the same fallback as a teammate without Overmind — and since
+  the port does not move, the fallback costs the name and nothing else.
+
 ## 0.1.0 (2026-07-24)
 
 First release.

data/README.md

@@ -53,12 +53,16 @@ Copse runs `web` in the foreground, holding your terminal's stdin and process gr
 
 `<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`.
 
+The suffix is the one thing here you can change: `.localhost` resolves on the machine and nowhere else, and [not on every client](#where-localhost-resolves). [Zeroconf names](#zeroconf-local-names) swap it for `<machine>.local` and put the app on the network.
+
 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.
 
+Always the `.localhost` hostname, even when the app is published under another suffix. Switching a machine to [zeroconf names](#zeroconf-local-names) is about names, so it must not move a port your bookmarks, your OAuth callback registrations, and your teammates still on `.localhost` all point at.
+
 Uncoordinated means collisions are possible. Measured over 20,000 seeded trials against 6,975 available ports:
 
 | Worktrees at once | Chance two share a port |
@@ -81,6 +85,8 @@ Changing the range or the reserved list would move nearly every derived port, so
 | `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 |
+| `BINDING` | `0.0.0.0` — **[zeroconf names](#zeroconf-local-names) only**, and never over one you set |
+| `RAILS_DEVELOPMENT_HOSTS` | `.cora.thicc.local` — **zeroconf names only**, appended to any you set |
 
 `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.
 
@@ -176,15 +182,96 @@ For a ❌ row, add a hosts entry — with two caveats:
 
 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.
+On macOS ≤ 15 or bare-glibc Linux and need Safari or `curl`? Either use zeroconf names below, or puma-dev, whose resolver approach doesn't have this gap.
+
+## Zeroconf (`.local`) names
+
+Two reasons to want this:
+
+- **Other devices reach the app by name.** Your phone, a tablet, a real iOS Safari, a VM running end-to-end tests — all of them resolve it, with no `/etc/hosts` entry on any of them. This is the only way to check a mobile layout, or a JS-heavy page on a slow phone, on the actual device.
+- **Clients that don't resolve `.localhost` at all.** Safari and `curl` on macOS before 26 (Tahoe), and bare-glibc Linux — see [the table above](#where-localhost-resolves). On those, `.localhost` isn't a preference, it's a dead end.
+
+`.localhost` is a *SHOULD* that each client decides to honour or not. `.local` is the opposite: [RFC 6762](https://www.rfc-editor.org/rfc/rfc6762) reserves it for multicast DNS, and every desktop and phone already runs a responder for it. Nothing has to special-case the name, because the name gets *answered*.
+
+So Copse can publish the derived hostname over mDNS instead — the technique from [Julik Tarkhanov's write-up](https://blog.julik.nl/2025/05/dev-subdomains-with-zeroconf), using [tenderlove's `zeroconf`](https://github.com/tenderlove/zeroconf) gem:
+
+```ruby
+group :development do
+  gem "copse"
+  gem "zeroconf" # only this mode needs it; Copse itself has no dependencies
+end
+```
+
+```sh
+COPSE_ZEROCONF=1 bin/dev
+```
+
+```
+~/code/cora             on main         →  http://cora.thicc.local:5368
+~/code/cora-fix-billing on fix-billing  →  http://fix-billing.cora.thicc.local:4783
+```
+
+**The ports are the same ones.** Only the suffix moved: `.localhost` became `<machine>.local`, where `thicc` is this machine's own Bonjour name.
+
+That machine label is not decoration. mDNS is a shared namespace, so two people on one network working on one repository would otherwise announce the same `fix-billing.cora.local` and whoever spoke last would win — your browser would land on your colleague's laptop.
+
+### Opting in
+
+`COPSE_ZEROCONF=1` in your shell profile, because which naming mode you need is a property of your machine, not of the repository: same branch, Chrome on Linux is fine with `.localhost` and Safari on macOS 15 is not. `bin/dev` is committed and shared; this doesn't touch it.
+
+For a whole team, put it in `bin/dev` instead:
+
+```ruby
+exit Copse.start(zeroconf: true)
+```
+
+Either way, a machine without the `zeroconf` gem installed says so in one line and boots on `.localhost` — same fallback as a teammate without Overmind. The port doesn't move, so the fallback costs you the name and nothing else.
+
+### What changes
+
+- **The app binds `0.0.0.0`**, via `BINDING`. A `.local` name resolves to this machine's address *on the network*, so a server on loopback would answer at an address the name never points at — unreachable from your phone, and unreachable from your own browser under that name. An inherited `BINDING`, an explicit `-b` on the `web` line, or a `bind` in `config/puma.rb` all still win.
+- **`RAILS_DEVELOPMENT_HOSTS` gets `.<host>`.** Rails' development allowlist is `.localhost`, `.test`, and the two IP ranges — which match address literals, not names — so without this every request under the advertised name gets a 403. Anything you already set is kept. Two limits, both Rails': the leading dot covers the host and **one** subdomain level, so `jane.cora.thicc.local` passes and `deep.jane.cora.thicc.local` does not; and an app that *assigns* `config.hosts` in `config/environments/development.rb` replaces the list this was appended to. Appending (`config.hosts <<`) is fine.
+- **Everything else is unchanged**: the port, the database suffix, `default_url_options`, foreman, Overmind.
+
+### Being on the network
+
+Reachable by every device is the feature, and it is also the cost: someone browsing Bonjour services on the same café Wi-Fi can see the app and connect to it. Fine on a network you trust; think twice on one you don't.
+
+Advertising stops when the session does, including the goodbye packets that withdraw the names. Under Overmind — which replaces Copse's process, so threads can't do it — the advertiser is forked into a process that watches Overmind's pid and withdraws the names when it exits.
+
+### Several subdomains at once
+
+Under `.localhost` every label resolves for free. mDNS answers only for names something announced, so an app serving one subdomain per tenant has to name them:
+
+```sh
+COPSE_SUBDOMAINS=jane,peter,tom COPSE_ZEROCONF=1 bin/dev
+```
+
+```
+jane.cora.thicc.local   peter.cora.thicc.local   tom.cora.thicc.local
+```
+
+All on the same port, all covered by the `RAILS_DEVELOPMENT_HOSTS` entry above. `Copse.start(zeroconf: true, subdomains: %w[jane peter tom])` is the committed form.
+
+### When it doesn't work
+
+- **`.local` is not a secure context, and `.localhost` is.** An origin is [potentially trustworthy](https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy) if it is HTTPS, a loopback address, or a host named `localhost` or ending in `.localhost`. `http://cora.thicc.local` is none of those, so everything [gated on a secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts/features_restricted_to_secure_contexts) turns off: service workers, `getUserMedia`, geolocation, WebAuthn and passkeys, `crypto.subtle`, the async clipboard API, Web Bluetooth/USB/Serial. That bites hardest exactly where this mode is most useful — camera and passkeys are half the reason you wanted the phone. Nothing short of HTTPS fixes it, which is [out of scope](#notes) here; on desktop Chrome you can list the origin in `chrome://flags/#unsafely-treat-insecure-origin-as-secure`, and mobile Safari has no such escape hatch. **If a feature works on `.localhost` and dies on `.local`, this is why** — and switching back is one environment variable.
+- **Multicast has to cross your network.** Most do; some routers bridging Wi-Fi and Ethernet drop it.
+- **Two interfaces, one machine.** The gem announces on the first interface the system returns — on a Mac, the top of Service Order in System Settings. Wired and wireless on different networks means the name may be announced to the one you're not browsing from. Copse prints the address it announced on; if that isn't the one you expect, that's the reason.
+- **On Linux, announcing and resolving are separate installs.** Copse announces fine anywhere a multicast packet can leave the machine — **verified here** in a bare Debian container, which has no responder of its own. Whether the *host* then resolves `.local` is up to it: macOS always does, and Linux needs `avahi` with `nss-mdns` in `/etc/nsswitch.conf`, or `systemd-resolved` with `MulticastDNS=yes`. Without one, the name is answered on the wire and `getaddrinfo` still says no — **verified here**, same container. Other devices on the network are unaffected; this is only about the machine running the app.
+- **`.local` as a corporate search domain.** Windows-era networks sometimes configure it, and those DNS servers then compete with mDNS for the same names.
+- **Nothing to announce on.** With no multicast-capable interface up, Copse says so and boots anyway — the app is still on its port.
+
+`dns-sd -B _http._tcp` lists what's being advertised, and the app appears there under a dotless instance name (`fix-billing-cora-thicc-local`) because mDNS instance names can't contain dots. The hostname keeps them.
 
 ## 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
+- `zeroconf` >= 1.2.0, only for [zeroconf names](#zeroconf-local-names) — 1.2.0 is where `instance_name:` arrived, without which a hostname containing dots cannot be advertised at all
 
-Rails 8's development host allowlist already includes `.localhost`, so no `config.hosts` change is needed.
+Rails 8's development host allowlist already includes `.localhost`, so no `config.hosts` change is needed. Zeroconf names are not in it; Copse passes those through `RAILS_DEVELOPMENT_HOSTS` instead.
 
 ## Notes
 

data/lib/copse/session.rb

@@ -26,10 +26,11 @@ module Copse
 
     attr_reader :worktree, :root
 
-    def initialize(worktree, root: nil, out: $stdout)
+    def initialize(worktree, root: nil, out: $stdout, advertiser: nil)
       @worktree = worktree
       @root = File.expand_path(root || worktree.root)
       @out = out
+      @advertiser = advertiser
     end
 
     # Boots the app and returns the foreground process's exit status.
@@ -46,6 +47,11 @@ module Copse
       # used to escape the handler entirely -- which surfaced as a bogus "cannot run
       # foreman" error rather than a clean interrupt.
       guarded do
+        # Inside the guard, not before it: the announcement opens sockets and
+        # starts threads, and a signal arriving during that has to reach the
+        # teardown that withdraws the names again.
+        @advertiser&.start
+
         # No secondaries means no foreman -- not even a preflight. The Procfile the
         # install generator writes has only a `web` line, so preflighting a tool
         # this run will never use would refuse to boot the most common app. Running
@@ -148,6 +154,11 @@ module Copse
     # foreman up front means its own 5s SIGTERM-to-SIGKILL escalation runs in
     # parallel with the web process shutting down.
     def teardown
+      # First, and before anything is waited on: withdrawing a name is a packet,
+      # not a wait, and the reaping below can take seconds. A name left announced
+      # after the port stops answering is a name that resolves to a closed door,
+      # cached for its TTL on every device that heard it.
+      stop_advertising
       signal_foreman
       terminate_web
       reap_foreman
@@ -155,6 +166,12 @@ module Copse
       restore_term_trap
     end
 
+    def stop_advertising
+      @advertiser&.stop
+    rescue StandardError => e
+      @out.puts "copse: could not stop advertising cleanly: #{e.message} (#{e.class})"
+    end
+
     def terminate_web
       return if @web_pid.nil?
 
@@ -272,6 +289,10 @@ module Copse
       @out.puts overmind_web_position_warning if web_out_of_position?
       @out.puts overmind_port_flag_warning if web_port_flag?
 
+      # Threads do not survive the exec below, so the advertiser is forked into a
+      # process that watches this pid instead. See Advertiser#fork_watching_parent.
+      @advertiser&.fork_watching_parent
+
       # Matches the `chdir: root` both foreman and the foreground web spawn use, but
       # for a different reason. The processes themselves are fine either way --
       # Overmind takes their working directory from the Procfile's own directory, so
@@ -351,6 +372,32 @@ module Copse
         "COPSE_URL" => worktree.url,
         "VITE_RUBY_PORT" => worktree.companion_port.to_s,
         "COPSE_DATABASE_SUFFIX" => worktree.database_suffix
+      }.merge(reachability_env)
+    end
+
+    # What an advertised name needs on top of a derived one, and nothing when
+    # there is no advertised name.
+    #
+    # A `.local` name resolves to this machine's address on the network, not to
+    # loopback. `rails server` binds `localhost` in development, so without
+    # BINDING the app would answer only on an address the advertised name does not
+    # point at -- unreachable from a phone, and unreachable from this machine's own
+    # browser under that name. An inherited BINDING wins, as does an explicit `-b`
+    # on the `web` line or a `bind` in config/puma.rb: Copse sets the default here,
+    # it does not take the decision away.
+    #
+    # Rails' development host allowlist covers `.localhost` and `.test`, not
+    # `.local`, so every request under the advertised name would be blocked. The
+    # leading dot also covers one level of subdomain, which is exactly the shape
+    # `subdomains` publishes.
+    def reachability_env
+      return {} if @advertiser.nil?
+
+      allowed = [ENV["RAILS_DEVELOPMENT_HOSTS"], ".#{worktree.host}"]
+
+      {
+        "BINDING" => ENV["BINDING"] || "0.0.0.0",
+        "RAILS_DEVELOPMENT_HOSTS" => allowed.reject { |value| value.to_s.strip.empty? }.join(",")
       }
     end
 

data/lib/copse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Copse
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/copse/worktree.rb

@@ -11,24 +11,44 @@ module Copse
   class Worktree
     LABEL_LIMIT = 63
 
-    attr_reader :root
+    # RFC 6761's own loopback TLD, and the default: a name under it needs no
+    # advertising, no listener, and no /etc/hosts entry on a client that honours
+    # it. Copse::Zeroconf swaps in `<machine>.local` for the clients that do not.
+    LOCALHOST_DOMAIN = "localhost"
 
-    def initialize(root = Dir.pwd)
+    attr_reader :root, :domain
+
+    def initialize(root = Dir.pwd, domain: LOCALHOST_DOMAIN)
       @root = File.expand_path(root)
+      @domain = domain
     end
 
-    # `<project>.localhost` for a main worktree, `<branch>.<project>.localhost`
-    # for a linked one.
+    # `<project>.<domain>` for a main worktree, `<branch>.<project>.<domain>` for
+    # a linked one.
     def host
-      @host ||= [slug, project, "localhost"].compact.join(".")
+      @host ||= [slug, project, domain].compact.join(".")
+    end
+
+    # The name the port is derived from, which is the `.localhost` one whatever
+    # domain the app is published under.
+    #
+    # Deriving from `host` instead would make the port a function of the naming
+    # mode, and both directions of that are wrong. A developer switching their own
+    # machine to zeroconf naming would find every port moved -- bookmarks, OAuth
+    # callback registrations, a `-p` typed into a script -- for a change that is
+    # supposed to be about names. And the zeroconf name carries the *machine's*
+    # name, so every teammate would derive a different port for the same branch,
+    # which is the coordination-free promise (R4) going the wrong way.
+    def canonical_host
+      @canonical_host ||= [slug, project, LOCALHOST_DOMAIN].compact.join(".")
     end
 
     def port
-      @port ||= Copse.port_for(host)
+      @port ||= Copse.port_for(canonical_host)
     end
 
     def companion_port
-      @companion_port ||= Copse.companion_port_for(host)
+      @companion_port ||= Copse.companion_port_for(canonical_host)
     end
 
     def url

data/lib/copse/zeroconf.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Copse
+  # An optional second naming mode, for machines where `.localhost` does not
+  # resolve.
+  #
+  # `.localhost` is a *SHOULD* (RFC 6761 §6.3), so whether a name under it
+  # resolves is up to each client -- Safari and `curl` on macOS 15 and earlier do
+  # not, and neither does bare glibc. `.local` is the opposite: RFC 6762 reserves
+  # it for multicast DNS, and every desktop and phone OS already runs a responder
+  # for it. Nothing has to special-case the name, because the name is *answered*.
+  #
+  # The trade is that an answer has to come from somewhere. Under `.localhost`
+  # Copse advertises nothing and binds nothing; here it publishes the derived
+  # hostname over mDNS for as long as the session runs, and the server has to bind
+  # a real interface rather than loopback -- so the app is reachable by every
+  # device on the network, phones included. That is the feature (it is how you
+  # open the app on a phone) and the cost (it is on the network).
+  #
+  # See https://blog.julik.nl/2025/05/dev-subdomains-with-zeroconf for the
+  # technique this implements.
+  module Zeroconf
+    # RFC 6762's TLD. Not configurable: a name outside `.local` is not a name
+    # multicast DNS will answer for.
+    TLD = "local"
+
+    # The DNS-SD service type a web UI advertises -- the same one a printer's
+    # admin page uses, which is what makes the app show up in `dns-sd -B _http._tcp`
+    # and in Bonjour browsers.
+    SERVICE = "_http._tcp.#{TLD}.".freeze
+
+    # Accepted as "yes" in COPSE_ZEROCONF. Anything else, including `0` and an
+    # empty value, is no: the variable is likely to end up in a shell profile, and
+    # `COPSE_ZEROCONF=0` must be a way to turn it off rather than a way to spell
+    # "any value is truthy".
+    TRUTHY = %w[1 true yes on].freeze
+
+    # Whether zeroconf naming was asked for. An explicit argument -- `bin/dev`
+    # passing `zeroconf: true` -- always wins; otherwise the environment decides.
+    #
+    # The environment matters more than it looks. `bin/dev` is committed and
+    # shared, but which naming mode a developer needs is a property of *their
+    # machine*: same repo, same branch, Chrome on Linux is fine with `.localhost`
+    # and Safari on macOS 15 is not. COPSE_ZEROCONF is how one teammate opts in
+    # from their shell profile without changing the file everyone else runs.
+    def self.requested?(flag = nil, env: ENV)
+      return !!flag unless flag.nil?
+
+      TRUTHY.include?(env["COPSE_ZEROCONF"].to_s.strip.downcase)
+    end
+
+    # Whether the optional dependency is installed. Copse declares no runtime
+    # dependencies, so this is a require rather than a constant check.
+    def self.available?
+      require "zeroconf"
+      true
+    rescue LoadError
+      false
+    end
+
+    # `<machine>.local` -- the apex the derived name is published under.
+    #
+    # The machine's own name is in there deliberately. Two developers on one
+    # network working on one repository derive the same `<branch>.<project>`, and
+    # mDNS is a shared namespace: without this, whoever announced last would own
+    # the name and the other's browser would land on a colleague's laptop.
+    def self.domain(hostname = Socket.gethostname)
+      "#{machine(hostname)}.#{TLD}"
+    end
+
+    # The machine's name as one DNS label. `Socket.gethostname` already returns
+    # `thicc.local` on a Mac, so only the first label is kept -- appending `.local`
+    # to a name that ends in it would publish `thicc.local.local`.
+    def self.machine(hostname = Socket.gethostname)
+      Worktree.slug(hostname.to_s.split(".").first) || "workstation"
+    end
+
+    # Extra names to publish alongside the app's own, for apps that serve several
+    # subdomains (one per tenant, per site, per brand). Under `.localhost` these
+    # cost nothing -- the resolver answers for every label -- but mDNS answers only
+    # for names something announced, so each one has to be named here.
+    #
+    # Slugged through the same whitelist as a branch name: these arrive from an
+    # environment variable and end up in a DNS record.
+    def self.subdomains(list = nil, env: ENV)
+      values = list || env["COPSE_SUBDOMAINS"].to_s.split(",")
+      Array(values).filter_map { |value| Worktree.slug(value) }.uniq
+    end
+
+    # The full set of names to advertise: the app's own, plus one per subdomain.
+    def self.hostnames(host, subdomains = [])
+      [host, *subdomains.map { |subdomain| "#{subdomain}.#{host}" }]
+    end
+
+    # Publishes hostnames over multicast DNS for as long as the session runs, and
+    # withdraws them when it ends.
+    #
+    # Each name is a separate announcement on its own thread, because that is the
+    # shape the zeroconf gem offers: `Service#start` binds a socket and loops
+    # answering queries until told to stop. The threads are pure IO -- they hold no
+    # lock the web process cares about and spend their lives in `IO.select` -- so
+    # they sit alongside the foreground `Process.waitpid` without contending with
+    # it.
+    class Advertiser
+      # How long `start` waits for the announcements to actually go out. Only a
+      # bound on a callback the gem fires once its socket is open; the normal case
+      # is milliseconds. Waiting at all is what makes `stop` reliable -- a service
+      # that has not started yet ignores it.
+      START_TIMEOUT = 2
+
+      # How long `stop` waits for a thread to leave its `IO.select` before killing
+      # it. Either way the thread's `ensure` sends the goodbye packet that
+      # withdraws the name; this only decides whether it does so on request.
+      STOP_TIMEOUT = 2
+
+      # How often the forked advertiser checks whether the process it was forked
+      # from is still alive. See `fork_watching_parent`.
+      PARENT_POLL = 1
+
+      attr_reader :hostnames, :port
+
+      def initialize(hostnames, port:, out: $stdout)
+        @hostnames = Array(hostnames).uniq
+        @port = port
+        @out = out
+        @services = []
+        @threads = []
+      end
+
+      # Returns whether anything is being advertised. False is not fatal anywhere:
+      # the app still boots and still answers on its port, it just cannot be
+      # reached by name.
+      def start
+        return false unless Zeroconf.available?
+
+        interfaces = ::ZeroConf.service_interfaces
+        if interfaces.empty?
+          @out.puts "copse: no multicast-capable network interface is up, so #{@hostnames.first} " \
+                    "is not being advertised. The app is still on port #{port}."
+          return false
+        end
+
+        announced = Queue.new
+        @hostnames.each { |hostname| advertise(hostname, interfaces, announced) }
+        await(announced)
+        # Every announcement died on the spot -- each one has already said why.
+        return false unless advertising?
+
+        @out.puts "=> Copse: advertising #{@hostnames.join(', ')} over mDNS on " \
+                  "#{interfaces.map { |iface| iface.addr.ip_address }.join(', ')}"
+        true
+      end
+
+      def stop
+        @services.each do |service|
+          service.stop
+        rescue StandardError
+          # Never started, or already stopped. Either way there is nothing to
+          # withdraw.
+        end
+
+        @threads.each { |thread| thread.kill unless thread.join(STOP_TIMEOUT) }
+        @services.clear
+        @threads.clear
+      end
+
+      def advertising? = @threads.any?(&:alive?)
+
+      # Advertises from a forked child that outlives this process, for the Overmind
+      # path -- which `exec`s, and threads do not survive an `exec`.
+      #
+      # The child watches its parent rather than being signalled by it, because
+      # after the `exec` there is no Copse left to do the signalling. `exec`
+      # preserves the pid, so the pid the child remembers is Overmind's; when
+      # Overmind exits the child is reparented and `Process.ppid` changes, which is
+      # the cue to withdraw the names and go. Ctrl-C gets there first in the usual
+      # case: the child shares the terminal's foreground process group, so it takes
+      # the same SIGINT, unwinds, and sends its goodbye packets.
+      #
+      # Returns the child's pid, or nil if this platform cannot fork.
+      def fork_watching_parent
+        return nil unless Process.respond_to?(:fork)
+
+        parent = Process.pid
+        fork do
+          Signal.trap("TERM") { raise Interrupt }
+          begin
+            sleep PARENT_POLL while Process.ppid == parent if start
+          rescue Interrupt
+            # Ctrl-C, or the SIGTERM converted above.
+          ensure
+            stop
+          end
+        end
+      end
+
+      # mDNS service instance names may not contain dots -- the gem raises on one --
+      # so the hostname is flattened into a single label. This is the name that
+      # shows up in `dns-sd -B _http._tcp` and in Bonjour browsers; the hostname
+      # itself keeps its dots and is what a browser is pointed at.
+      def self.instance_name(hostname)
+        hostname.tr(".", "-")[0, Worktree::LABEL_LIMIT]
+      end
+
+      private
+
+      def advertise(hostname, interfaces, announced)
+        service = ::ZeroConf::Service.new(
+          SERVICE, port, hostname,
+          instance_name: self.class.instance_name(hostname),
+          service_interfaces: interfaces,
+          started_callback: -> { announced << hostname }
+        )
+        @services << service
+
+        @threads << Thread.new do
+          # One clear line, never a backtrace. This is background work the
+          # developer did not ask about by name, and a multicast socket giving up
+          # must not read like an application error.
+          Thread.current.report_on_exception = false
+          service.start
+        rescue StandardError => e
+          @out.puts "copse: stopped advertising #{hostname}: #{e.message} (#{e.class})"
+        end
+      end
+
+      # Waits for every announcement to report itself, or for the deadline, or for
+      # every thread to have died -- whichever comes first. A thread that died
+      # already printed its own line.
+      def await(announced)
+        deadline = Time.now + START_TIMEOUT
+        @hostnames.size.times do
+          remaining = deadline - Time.now
+          break if remaining <= 0 || !advertising?
+
+          announced.pop(timeout: remaining)
+        end
+      end
+    end
+  end
+end

data/lib/copse.rb

@@ -8,6 +8,7 @@ require_relative "copse/worktree"
 require_relative "copse/database"
 require_relative "copse/procfile"
 require_relative "copse/session"
+require_relative "copse/zeroconf"
 
 # 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
@@ -67,8 +68,19 @@ module Copse
   #
   # `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))
+  #
+  # `zeroconf: true` publishes the derived hostname under `.local` over multicast
+  # DNS instead of `.localhost`, for machines whose clients do not resolve
+  # `.localhost` -- and for reaching the app from a phone. Left nil it follows
+  # COPSE_ZEROCONF, so a single developer can opt in without editing the committed
+  # `bin/dev`. `subdomains` names extra labels to publish under the app's own
+  # hostname (`jane.cora.thicc.local`), for apps that serve several; it follows
+  # COPSE_SUBDOMAINS the same way, and does nothing without zeroconf, where the
+  # resolver answers for every label already.
+  def self.start(root: Dir.pwd, process_manager: :foreman, args: [], zeroconf: nil, subdomains: nil,
+                 out: $stdout)
+    worktree, advertiser = derive(root: root, zeroconf: zeroconf, subdomains: subdomains, out: out)
+    session = Session.new(worktree, out: out, advertiser: advertiser)
 
     # `exec_overmind` never returns, so falling through to the foreman session
     # means overmind is not installed *on this machine*. That is a fallback rather
@@ -79,6 +91,30 @@ module Copse
     session.start
   end
 
+  # The naming decision, split out of `start` so it can be tested without booting
+  # anything. Returns the worktree and, when zeroconf naming is on, the advertiser
+  # that will publish its hostname.
+  #
+  # A missing `zeroconf` gem is a fallback rather than an error, for the same
+  # reason a missing overmind is: the request can come from a committed `bin/dev`,
+  # and a machine that cannot honour it should still boot. The port is unchanged
+  # by the fallback -- it is derived from the `.localhost` name either way -- so
+  # what is lost is the name, not the session.
+  def self.derive(root: Dir.pwd, zeroconf: nil, subdomains: nil, out: $stdout, env: ENV)
+    return [Worktree.new(root), nil] unless Zeroconf.requested?(zeroconf, env: env)
+
+    unless Zeroconf.available?
+      out.puts "copse: zeroconf naming was asked for, but the `zeroconf` gem is not installed " \
+               "for this Ruby. Add `gem \"zeroconf\"` to the development group. " \
+               "Booting under .localhost instead."
+      return [Worktree.new(root), nil]
+    end
+
+    worktree = Worktree.new(root, domain: Zeroconf.domain)
+    hostnames = Zeroconf.hostnames(worktree.host, Zeroconf.subdomains(subdomains, env: env))
+    [worktree, Zeroconf::Advertiser.new(hostnames, port: worktree.port, out: out)]
+  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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: copse
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kieran Klaassen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-09-10 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.
@@ -31,6 +31,7 @@ files:
 - lib/copse/url_options.rb
 - lib/copse/version.rb
 - lib/copse/worktree.rb
+- lib/copse/zeroconf.rb
 - lib/generators/copse/install_generator.rb
 - lib/generators/copse/templates/Procfile.dev.tt
 - lib/generators/copse/templates/dev.tt