yamine 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e48f66da1b02dd9ea589c1a30225d6b1f9dc46cd1abd92ffad90c27422b6d4ca
-  data.tar.gz: '0209cb0ce1c976c5f6a934ba0a74283f3b8064e2fc9aed493208c74077dd5a62'
+  metadata.gz: 6f7c7127a262069469056cf55f94b5785de8e1890bc0814d84453159e1a01096
+  data.tar.gz: 0001bfbad73772c3caa7e615384a0c70dfa82732987174f55cbfbffac703dd15
 SHA512:
-  metadata.gz: 2626fc9696988148d9637ffd1ce14adc7d7d656b03d61854296ff3b6c818fd82ff840fce5904395ac8d2b54c027c9f7e63f47f0f077609f896542af06c282d28
-  data.tar.gz: 110d265a913ee76a3ff40328c40cfdc0475e195c3e1518a490294dd2bb7bca0536edbaeedba7bc37815625aa3975880efdb1b1a66252b3c2a9ed16d6a2b5abd1
+  metadata.gz: 702d9b80482ac8f541f16ab5946b8916b0c23750774e398eabe85cd940a5d39306bdc188e010065e17ecf91081feb79b94d021a24c71186978ba8d1e4ede7dba
+  data.tar.gz: f0f12d6cc5b32bcc46804ef3009a72ab4fac500f792b6d6ea39f05324857031b4cb0f06fe131ef291a61f2faf1d1fd87eb85520d6698b63a6a5b6dde394e637d

data/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## [0.13.0] — 2026-09-11
+
+### Changed
+
+- **The subdomain fallback is now opt-in: `proxy.subdomains`.** A route
+  used to answer its own subdomains unconditionally, so *any* label under
+  a live app silently resolved to that app. The expensive case is a
+  worktree: once `<branch>.myapp.localhost` became the worktree URL, the
+  same hostname with that worktree **stopped** answered as the main
+  checkout — HTTP 200, a real app, the wrong code, and nothing to
+  distinguish it from the right answer. You had to notice the branch
+  was running to know you were looking at someone else's build.
+
+  Unregistered hostnames now 404 instead, and the page names the parent
+  app and its directory: "`myapp.localhost` is running in `/code/myapp`.
+  If `my-branch.myapp.localhost` is a worktree or branch, start it there
+  (`yamine start`)." The failure states its own fix.
+
+  Opting in is one line per app that genuinely wants it:
+
+  ```yaml
+  proxy:
+    subdomains: true     # this app answers *.myapp.localhost
+  ```
+
+  `yamine alias <name> <port> --wildcard` is the same opt-in for a
+  single ad-hoc route. `yamine status` now reports which mode an app is
+  in, since it changes what an unregistered label resolves to.
+
+  Nothing depended on the ambient behavior: no sibling app config used
+  subdomains, and the only artifact was one test, now the opt-in test.
+  Route files written before this need no migration — the flag is absent
+  unless set, and absent means exact hostname only.
+
+### Fixed
+
+- **`proxy: false` on a process named `web` no longer fails validation.**
+  The EXAMPLE can only name one class per key (`true` → TrueClass), so a
+  literal `false` was compared as falseclass and rejected with the
+  self-contradictory "expected a boolean, got falseclass". Booleans are
+  now checked as booleans.
+
+## [0.12.0] — 2026-09-11
+
+### Fixed
+
+- **Worktrees get their own URL, as the README always claimed.**
+  `Variant.resolve`, the worktree detector, `Hostname.compose`'s variant
+  axis and their unit tests were all present, correct, and never
+  assembled: `Resolver.resolve` never called `Variant.resolve`, and
+  `hostname_for` built `{service}.{app}.{tld}` by hand, bypassing the
+  composer. So every worktree of a project answered on the *same*
+  hostname as its main checkout, and the ownership gate refused to boot
+  the second one — while telling the user to "work in your own worktree
+  (each branch gets its own URL)", advice that could not work.
+
+  A linked worktree is now reachable at `<branch>.<app>.<tld>`
+  (`work/next` → `work-next.myapp.localhost`) and boots beside its main
+  checkout, which keeps the bare name. Cross-checked by serving two
+  branches at once: distinct ports, distinct asset digests, no shared
+  route.
+
+  Found while trying to run a second checkout of a Rails app for UI work,
+  which is exactly the case the feature existed for.
+
+### Changed
+
+- **The variant axis is split in two: `overlay` and `variant`.** They
+  were one setting, which meant that as soon as a worktree supplied its
+  own variant, `config/local.<branch>.yml` became an implied file lookup
+  — so a branch named like a file on disk would silently change the
+  config. Now only an explicit `--variant` / `YAMINE_VARIANT` sets the
+  overlay to merge; a worktree branch supplies the hostname label and
+  nothing else. `status` prints both lines, so the two can no longer be
+  mistaken for each other.
+
+- **A branch label is the whole branch, not its last path segment.**
+  `feature/login` and `bugfix/login` are different worktrees and used to
+  collapse to the same `login` hostname. Overlong branches still resolve
+  through the existing hash-suffix truncation.
+
+- A worktree on a detached HEAD falls back to its directory name (the
+  same identity the per-worktree database uses) instead of returning no
+  prefix and quietly colliding with the main checkout.
+
+- `yamine status` now honors `--variant` / `--tld`, and accepts
+  `--branch`, which the README documented but `parse_flags` rejected as
+  an unknown flag.
+
+- `proxy.host` is never rewritten by a variant: an explicitly written
+  hostname is left exactly as written.
+
 ## [0.11.1] — 2026-09-11
 
 ### Fixed
@@ -34,10 +126,10 @@
 
 - **Ruby, git, and curl now trust the local CA — so an app can call
   another app at `https://<name>.localhost` with no configuration.** The
-  gap surfaced when anywaye (a Rails app) tried to reach anymark at
-  `https://anymark-directory.localhost`: `certificate verify failed`. The
-  CA was trusted everywhere a human looks (Safari, Chrome, curl) and
-  nowhere a child process looks — only Node was covered, via
+  gap surfaced when anywaye (a Rails app) tried to reach a second
+  checkout of anymark at its `.localhost` URL: `certificate verify
+  failed`. The CA was trusted everywhere a human looks (Safari, Chrome,
+  curl) and nowhere a child process looks — only Node was covered, via
   `NODE_EXTRA_CA_CERTS`.
 
   The naive fix is wrong in a way that shows up much later. `SSL_CERT_FILE`

data/README.md

@@ -91,6 +91,7 @@ of truth for service name, proxy TLD/host, processes, and env:
 service: myapp
 proxy:
   tld: localhost
+  subdomains: false      # opt in to answering *.myapp.localhost
 processes:
   web:
     cmd: bundle exec puma -b tcp://127.0.0.1:$PORT config.ru
@@ -117,7 +118,8 @@ whole tree, and cleans up when one exits.
 
 Variants are file overlays: `config/local.<variant>.yml` deep-merges on
 top of `config/local.yml`, selected by `YAMINE_VARIANT` (Kamal's
-destination pattern).
+destination pattern). Naming a variant also prefixes the hostname — see
+below for how that differs from a worktree's automatic prefix.
 
 `.localhost` resolves to loopback natively in Chrome, Firefox, and Edge —
 no DNS server, no `/etc/resolver`. Safari may need `yamine hosts sync`.
@@ -135,10 +137,24 @@ no DNS server, no `/etc/resolver`. Safari may need `yamine hosts sync`.
 | variant | `fix-ui.myapp` | `--variant`, `YAMINE_VARIANT`, linked worktree branch |
 | tld | `myapp.preview.example.com` | `--tld` (default `localhost`) |
 
+`proxy.host` is the one exception: an explicitly written full hostname
+bypasses composition entirely, variant included.
+
 Linked git worktrees get a branch prefix automatically
-(`fix-ui.myapp.localhost`); the main checkout keeps the bare name.
-Pass `--branch` (or `YAMINE_BRANCH=1`) to prefix by current branch
-outside worktrees. `main`/`master`/detached HEAD never prefix.
+(`ui-onboarding.myapp.localhost`); the main checkout keeps the bare name,
+so a worktree and its main checkout run side by side. The label is the
+whole branch (`feature/login` → `feature-login.myapp.localhost`), so two
+branches that share a last segment never share a hostname. A detached
+HEAD has no branch to name it and falls back to the worktree's directory
+— the same identity its per-worktree database uses. `main`/`master`
+never prefix. Pass `--branch` (or `YAMINE_BRANCH=1`) to prefix by the
+current branch outside worktrees.
+
+A variant is a hostname label, not a config file. Only an explicit
+`--variant` / `YAMINE_VARIANT` goes looking for
+`config/local.<name>.yml` to merge; a worktree branch never does, so a
+branch named like a file on disk cannot change your config by accident.
+`yamine status` prints both lines so the two are never confused.
 
 ```bash
 yamine                                          # -> https://myapp.localhost
@@ -147,6 +163,26 @@ yamine --variant demo                           # -> https://demo.myapp.localhos
 yamine --tld preview.example.com                # your own domain (OAuth parity)
 ```
 
+## Subdomains are opt-in
+
+A route answers its exact hostname. `*.myapp.localhost` reaches
+`myapp.localhost` only if that app asked for it:
+
+```yaml
+proxy:
+  subdomains: true     # this app answers its own subdomains
+```
+
+```bash
+yamine alias tenant1 4001 --wildcard   # one route, its subdomains
+```
+
+Off is the useful default. An unregistered label under a live app is far
+more likely to be a worktree whose stack is stopped than a tenant, and
+handing that label to the parent app means HTTP 200 with the wrong code.
+Instead the request 404s and names the parent app, its directory, and how
+to start it. `yamine status` reports which mode an app is in.
+
 ## Commands
 
 ```bash

data/lib/ask/skills/yamine/SKILL.md

@@ -78,16 +78,37 @@ yamine get backend --variant demo
 Use `get` output for frontend-to-API URLs, Cable URLs, and webhook
 targets. Do not guess ports.
 
-## Variants are files
+## Variants are files; worktrees are not
 
 A variant is a file overlay, Kamal-style: `config/local.<variant>.yml`
-deep-merges over `config/local.yml`. Select it with `YAMINE_VARIANT`
-or `--variant`. Worktrees get a branch prefix automatically.
+deep-merges over `config/local.yml`, selected with `YAMINE_VARIANT` or
+`--variant`. Naming one also prefixes the hostname.
+
+A git worktree needs none of that: it gets a branch prefix automatically
+(`ui-onboarding.myapp.localhost`) and boots alongside its main checkout,
+which keeps the bare name. The whole branch is the label, so
+`feature/login` and `bugfix/login` stay distinct. A detached worktree
+falls back to its directory name.
 
 ```bash
 YAMINE_VARIANT=fix-ui yamine    # boots with config/local.fix-ui.yml merged
 ```
 
+Only an explicit variant ever looks for an overlay file — a branch name
+that happens to match one on disk is ignored. `yamine status` shows
+`variant:` and `overlay:` separately.
+
+## Subdomains are opt-in
+
+A route answers its exact hostname. `*.myapp.localhost` reaches the app
+only if it asked (`proxy.subdomains: true` in `config/local.yml`, or
+`yamine alias <name> <port> --wildcard` for one route).
+
+So a worktree whose stack is not running gets a 404 that names the parent
+app, its directory, and `yamine start` — not the parent app's code. If
+you hit a `.localhost` URL that loads but looks wrong, check you started
+the worktree you think you did; `yamine status` in it prints the URL.
+
 ## First time on a machine
 
 Run `yamine start` — it does the one-shot CA trust, port 443, and

data/lib/yamine/cli/boot.rb

@@ -16,8 +16,9 @@ module Yamine
       # boots every process, supervises the tree, cleans up on exit.
       def run_inferred(ctx, args)
         variant = ENV["YAMINE_VARIANT"]
-        opts = ctx.parse_flags(args, %i[variant tld force app_port wait no_wait json])
-        resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld])
+        opts = ctx.parse_flags(args, %i[variant tld force app_port wait no_wait json branch])
+        resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld],
+          use_branch: opts[:branch])
         # Ownership gate before any side effects: no proxy spawn, no
         # port allocation when we'd refuse anyway.
         check_worktree_ownership!(ctx, resolved, force: opts[:force])
@@ -242,6 +243,7 @@ module Yamine
             url: item[:url], dir: Dir.pwd, command: item[:command],
             port: item[:port], force: opts[:force],
             rails_dev_host: item[:hostname], database_url: db_url,
+            subdomains: resolved.subdomains,
             extra_env: build_env(resolved, item[:entry], proc_name: item[:name]))
           routes_registered << { hostnames: item[:hostnames], app: app }
 
@@ -280,7 +282,8 @@ module Yamine
         if failed.empty?
           apps.each do |name, slot|
             runner.adopt(slot[:item][:hostname], slot[:app], force: opts[:force],
-              spec: { "dir" => File.expand_path(Dir.pwd), "proc" => name })
+              spec: { "dir" => File.expand_path(Dir.pwd), "proc" => name },
+              subdomains: resolved.subdomains)
             routes_registered << { hostnames: slot[:item][:hostnames], app: slot[:app] }
             say opts, "  -> #{slot[:item][:url]}"
           end
@@ -653,10 +656,10 @@ module Yamine
         end
       end
 
-      def resolve!(ctx, variant: nil, tld: nil)
+      def resolve!(ctx, variant: nil, tld: nil, use_branch: false)
         # The resolver calls Config.load, which raises ConfigError if
         # config/local.yml is missing — exactly what we want.
-        Yamine::Resolver.resolve(Dir.pwd, variant: variant, tld: tld)
+        Yamine::Resolver.resolve(Dir.pwd, variant: variant, tld: tld, use_branch: use_branch)
       end
 
       # json: keeps stdout free for the machine-readable stream — this runs

data/lib/yamine/cli/routes.rb

@@ -147,14 +147,20 @@ module Yamine
           puts "Removed alias #{hostname}."
           return
         end
-        name, port_or_url = args
-        raise Error, "Usage: yamine alias <name> <port|url>" unless name && port_or_url
+        name, port_or_url = args.reject { |a| a.start_with?("--") }
+        raise Error, "Usage: yamine alias <name> <port|url> [--wildcard]" unless name && port_or_url
 
         hostname = alias_hostname(name)
         target = port_or_url.match?(/\A\d+\z/) ? "127.0.0.1:#{port_or_url}" : port_or_url
         force = args.include?("--force")
-        ctx.store.add_route(hostname, target, 0, kind: "tcp", force: force)
-        puts "#{hostname} -> #{target}"
+        # --wildcard is the per-route escape hatch for the tenant case:
+        # this alias answers its own subdomains. Config `proxy.subdomains`
+        # is the same opt-in for a whole app at boot.
+        wildcard = args.include?("--wildcard")
+        ctx.store.add_route(hostname, target, 0, kind: "tcp", force: force,
+          subdomains: wildcard)
+        suffix = wildcard ? " (and its subdomains)" : ""
+        puts "#{hostname} -> #{target}#{suffix}"
       end
 
       # A name containing dots is treated as a full hostname (any TLD);
@@ -175,6 +181,9 @@ module Yamine
       # agent's cleanup). --force overrides and names the previous owner.
       def stop(ctx, args, out: $stdout)
         force = args.delete("--force")
+        # In a worktree this resolves that worktree's own hostname (the
+        # branch is the variant), so `stop` here never reaches across
+        # into the main checkout's running app.
         resolved = Resolver.resolve(Dir.pwd)
         hostnames = Resolver.hostnames(resolved)
         mine = Agent.name
@@ -261,9 +270,14 @@ module Yamine
       # `yamine` would boot here and why. Answers "why did I get
       # this URL" without booting anything. --json emits stable keys
       # for agents instead of prose.
-      def status(_ctx, args)
+      def status(ctx, args)
         json = args.delete("--json")
-        resolved = Resolver.resolve(Dir.pwd)
+        # The flags exist so `status --variant x` answers the same
+        # question boot would; in a worktree the branch supplies the
+        # variant anyway, so plain `status` is already the right answer.
+        opts = ctx.parse_flags(args, %i[variant tld branch])
+        resolved = Resolver.resolve(Dir.pwd, variant: opts[:variant], tld: opts[:tld],
+          use_branch: opts[:branch])
         hostnames = Resolver.hostnames(resolved)
         urls = hostnames.map do |h|
           Hostname.url(h, port: ProxyControl.default_port(true), tls: true)
@@ -273,6 +287,8 @@ module Yamine
           tld: resolved.tld, tld_source: resolved.sources[:tld],
           host: resolved.host, host_source: resolved.sources[:host],
           variant: resolved.variant, variant_source: resolved.sources[:variant],
+          overlay: resolved.overlay, overlay_source: resolved.sources[:overlay],
+          subdomains: resolved.subdomains,
           urls: urls,
           processes: resolved.processes.keys,
           framework: Framework.detect(Dir.pwd).to_s
@@ -288,7 +304,14 @@ module Yamine
         else
           puts "tld:       #{payload[:tld]} (from #{payload[:tld_source]})"
         end
-        puts "variant:   #{payload[:variant] || "(none)"} (from #{payload[:variant_source] || "no overlay file, flag, or env"})"
+        puts "variant:   #{payload[:variant] || "(none)"} (from #{payload[:variant_source] || "no flag, env, or worktree branch"})"
+        # The overlay is a different thing from the variant and only an
+        # explicit --variant / YAMINE_VARIANT ever sets it, so say so
+        # rather than letting the two look like one setting.
+        puts "overlay:   #{payload[:overlay] ? "#{payload[:overlay]} (merged)" : "(none)"}"
+        # Off by default; say when it is on, because it changes what an
+        # unregistered label under this app resolves to.
+        puts "subdomains: #{payload[:subdomains] ? "own subdomains resolve here" : "exact hostname only"}"
         puts "processes: #{payload[:processes].join(", ")}"
         puts "urls:"
         urls.each { |u| puts "  #{u}" }

data/lib/yamine/config.rb

@@ -51,7 +51,12 @@ module Yamine
       "service" => "myapp",
       "proxy" => {
         "tld" => "localhost",
-        "host" => "myapp.local.example.com"
+        "host" => "myapp.local.example.com",
+        # Opt this app into answering its own subdomains. Off by default:
+        # an unregistered label under a live app is far more likely to be
+        # a stopped worktree than a tenant, and resolving it to the wrong
+        # app is worse than not resolving it.
+        "subdomains" => false
       },
       # db: false opts out of per-worktree databases entirely (exotic
       # setups: manual establish_connection, shared staging DB, ...).
@@ -178,6 +183,14 @@ module Yamine
       data[key]
     end
 
+    # Whether this app answers its own subdomains. Off unless asked: the
+    # ambient fallback used to hand any unregistered label to whichever
+    # app owned the parent name, which reads as the right app running the
+    # wrong code — the worktree case that motivated the opt-in.
+    def subdomains?
+      proxy_config["subdomains"] == true
+    end
+
     private
 
     def load_secrets
@@ -274,6 +287,9 @@ module Yamine
       if value["tld"] && !Sanitize.valid_tld?(value["tld"].downcase)
         raise ConfigError, "#{context}: invalid tld #{value["tld"].inspect}"
       end
+      if value.key?("subdomains") && ![true, false].include?(value["subdomains"])
+        raise ConfigError, "#{context}: subdomains must be a boolean"
+      end
     end
 
     def validate_db(value, context)
@@ -364,13 +380,28 @@ module Yamine
         elsif example_value.is_a?(Array) && value.is_a?(Array)
           validate_array_of!(value, example_value.first.class) unless example_value.empty?
         elsif !example_value.nil?
-          expected = type_description(example_value.class)
-          unless value.is_a?(example_value.class) || (example_value.is_a?(String) && value.is_a?(String))
-            raise ConfigError, "#{current_context}: expected #{expected}, got #{value.class.name.downcase}"
+          # Booleans are one type, but the example can only name one class
+          # (TrueClass for `true`), so a literal `false` compared as
+          # falseclass and was rejected: `proxy: false` on a process
+          # raised "expected a boolean, got falseclass". Ask the value
+          # what it is instead of the example.
+          if boolean?(example_value)
+            unless boolean?(value)
+              raise ConfigError, "#{current_context}: expected a boolean, got #{value.class.name.downcase}"
+            end
+          else
+            expected = type_description(example_value.class)
+            unless value.is_a?(example_value.class) || (example_value.is_a?(String) && value.is_a?(String))
+              raise ConfigError, "#{current_context}: expected #{expected}, got #{value.class.name.downcase}"
+            end
           end
         end
       end
 
+      def boolean?(value)
+        value == true || value == false
+      end
+
       def validate_array_of!(array, type)
         array.each_with_index do |value, index|
           with_context(index) do

data/lib/yamine/proxy.rb

@@ -106,6 +106,17 @@ module Yamine
     end
 
     # Pure request-routing core, tested without sockets.
+    #
+    # Exact hostname first, then an opted-in wildcard. The wildcard is
+    # deliberately not ambient: a route only answers its own subdomains
+    # when it registered with `subdomains: true` (config
+    # `proxy.subdomains`, or `yamine alias --wildcard`).
+    #
+    # It used to be unconditional, which meant every unregistered label
+    # under any live app silently resolved to that app. The expensive
+    # case is a worktree: `<branch>.myapp.localhost` answered as the main
+    # checkout — a wrong-but-working app, indistinguishable from the
+    # right one. An unregistered hostname now 404s, and says so.
     def route(authority, routes)
       host = Hostname.strip_port(authority)
       return nil if host.empty? || host.bytesize > MAX_HOSTNAME_BYTES
@@ -113,8 +124,7 @@ module Yamine
       exact = routes.find { |r| r["hostname"] == host }
       return exact if exact
 
-      wildcard = routes.find { |r| host.end_with?(".#{r["hostname"]}") }
-      wildcard
+      routes.find { |r| r["subdomains"] && host.end_with?(".#{r["hostname"]}") }
     end
 
     def check_hops(headers)
@@ -452,9 +462,23 @@ module Yamine
         return respond(sock, 404, "<h1>Not Found</h1>")
       end
 
+      # A label in front of a live app is almost always a worktree or a
+      # branch whose stack is not running. Name the parent it would fall
+      # under and where it lives, so "the app loaded but it's the wrong
+      # code" becomes "that worktree isn't running" without a search.
+      parent = routes.find { |r| bare.end_with?(".#{r["hostname"]}") }
+      hint = if parent
+        dir = parent.dig("spec", "dir")
+        where = dir ? " in #{escape(dir)}" : ""
+        "<p><strong>#{escape(parent["hostname"])}</strong> is running#{where}.</p>" \
+          "<p>If #{escape(bare)} is a worktree or branch, start it there " \
+          "(<code>yamine start</code>), or open " \
+          "<strong>#{escape(parent["hostname"])}</strong> instead.</p>"
+      end
+
       items = routes.map { |r| "<li>#{escape(r["hostname"])}</li>" }.join
       body = "<h1>No app registered for #{escape(bare)}</h1>" \
-             "<ul>#{items}</ul>"
+             "#{hint}<ul>#{items}</ul>"
       respond(sock, 404, body)
     end
 

data/lib/yamine/resolver.rb

@@ -9,10 +9,26 @@ module Yamine
     module_function
 
     Result = Struct.new(:app, :tld, :host, :processes, :secrets,
-      :sources, :variant, :db, :env, keyword_init: true)
+      :sources, :variant, :overlay, :subdomains, :db, :env, keyword_init: true)
 
-    def resolve(dir = Dir.pwd, variant: nil, tld: nil, host: nil)
-      config = Config.load(dir, variant: variant)
+    # Two axes, and keeping them apart is the whole point:
+    #
+    #   overlay — an explicit `config/local.<name>.yml` to deep-merge.
+    #             Only --variant / YAMINE_VARIANT ever set it, so a
+    #             branch name can never select config by surprise.
+    #   variant — the leading hostname label, from that same explicit
+    #             name OR a linked worktree's branch. It is a name, not
+    #             a file: a worktree is reachable at
+    #             <branch>.<app>.localhost without inventing config.
+    #
+    # They share a value when the user asks for one explicitly. Only
+    # then does a variant mean both "merge this file" and "prefix this
+    # hostname", which is the documented `--variant` behavior.
+    def resolve(dir = Dir.pwd, variant: nil, tld: nil, host: nil, use_branch: false)
+      overlay = (variant || ENV["YAMINE_VARIANT"])&.strip
+      overlay = nil if overlay&.empty?
+
+      config = Config.load(dir, variant: overlay)
       unless config
         raise ConfigError, Config.missing_message(dir)
       end
@@ -21,8 +37,7 @@ module Yamine
       proxy = config.proxy_config
       processes = config.processes
 
-      variant_name = (variant || ENV["YAMINE_VARIANT"])&.strip
-      variant_name = nil if variant_name&.empty?
+      variant_name, variant_source = Variant.resolve(dir, explicit: variant, use_branch: use_branch)
 
       # host or tld: config proxy.host wins over proxy.tld; flags override.
       if host || proxy["host"]
@@ -41,7 +56,8 @@ module Yamine
         app: config.path.to_s,
         tld: proxy["tld"] ? "#{config.path} proxy.tld" : "default (localhost)",
         host: proxy["host"] ? "#{config.path} proxy.host" : nil,
-        variant: variant_name ? "config/local.#{variant_name}.yml" : nil
+        variant: variant_source,
+        overlay: overlay ? "config/local.#{overlay}.yml" : nil
       }
 
       Result.new(
@@ -52,20 +68,34 @@ module Yamine
         secrets: config.secrets,
         sources: sources,
         variant: variant_name,
+        overlay: overlay,
+        subdomains: config.subdomains?,
         db: config.data["db"],
         env: config.env_config
       )
     end
 
     # Hostname for one process: primary (first proxy:true) is bare;
-    # others are proc.app.tld; proxy:false have none.
+    # others are proc.app.tld; proxy:false have none. A variant — the
+    # explicit name or a worktree's branch — leads every one of them.
     def hostname_for(result, proc_name)
       entry = result.processes[proc_name]
       return nil unless entry
       return nil if entry["proxy"] == false
 
-      base = result.host ? result.host : "#{result.app}.#{result.tld}"
-      proc_name.to_s == primary_proc(result) ? base : "#{proc_name}.#{base}"
+      # An explicit proxy.host is a full hostname, so composition does
+      # not apply — and a variant must never silently rewrite a host
+      # the user wrote out in full.
+      if result.host
+        return proc_name.to_s == primary_proc(result) ? result.host : "#{proc_name}.#{result.host}"
+      end
+
+      Hostname.compose(
+        app: result.app,
+        tld: result.tld,
+        service: (proc_name.to_s == primary_proc(result) ? nil : proc_name.to_s),
+        variant: result.variant
+      )
     end
 
     def primary_proc(result)

data/lib/yamine/route_store.rb

@@ -76,7 +76,12 @@ module Yamine
     # `agent` records the owner (defaults to Agent.name); foreign-owned
     # live routes can only be taken with force: true, and the conflict
     # error names the other agent plus its worktree dir.
-    def add_route(hostname, target, pid, kind:, force: false, spec: nil, agent: nil)
+    #
+    # `subdomains` opts this route into answering its own subdomains.
+    # Absent (the default, and what every pre-existing route file has)
+    # means exact hostname only — see Proxy#route for why.
+    def add_route(hostname, target, pid, kind:, force: false, spec: nil, agent: nil,
+      subdomains: false)
       agent ||= Agent.name
       killed = nil
       with_lock do
@@ -101,6 +106,7 @@ module Yamine
         entry = { "hostname" => hostname, "target" => target, "kind" => kind,
                   "pid" => pid, "agent" => agent }
         entry["spec"] = spec if spec
+        entry["subdomains"] = true if subdomains
         routes << entry
         save_routes(routes)
       end

data/lib/yamine/runner.rb

@@ -99,7 +99,7 @@ module Yamine
     # win over it, because those describe the boot rather than the app.
     def boot_run(name:, hostname:, url:, dir:, command:, port: nil, force: false,
       rails_dev_host: nil, register: true, database_url: nil, spec: nil,
-      extra_env: nil)
+      extra_env: nil, subdomains: false)
       port ||= Ports.find_free
       env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host,
         database_url: database_url, extra_env: extra_env)
@@ -111,7 +111,7 @@ module Yamine
         begin
           spec ||= { "dir" => File.expand_path(dir), "proc" => name }
           @store.add_route(hostname, target, Process.pid, kind: "tcp",
-            force: force, spec: spec)
+            force: force, spec: spec, subdomains: subdomains)
           write_backend_pid(hostname, pid)
         rescue StandardError
           # Registration refused (quota, conflict): the backend is
@@ -140,9 +140,9 @@ module Yamine
     end
 
     # Register an already-spawned backend: route + sidecar, together.
-    def adopt(hostname, app, force: false, spec: nil)
+    def adopt(hostname, app, force: false, spec: nil, subdomains: false)
       @store.add_route(hostname, app.target, Process.pid, kind: app.kind,
-        force: force, spec: spec)
+        force: force, spec: spec, subdomains: subdomains)
       write_backend_pid(hostname, app.pid)
       nil
     end

data/lib/yamine/variant.rb

@@ -51,12 +51,27 @@ module Yamine
       label.empty? ? nil : [label, source]
     end
 
+    # The whole branch, not just its last path segment. `feature/login`
+    # and `bugfix/login` are different worktrees and must not end up
+    # sharing a hostname; taking the last segment alone collapsed them
+    # both to `login`.
     def branch_to_prefix(branch)
       return nil if branch.nil? || branch.empty?
       return nil if branch == "HEAD" || DEFAULT_BRANCHES.include?(branch)
 
-      last = branch.split("/").last.to_s
-      label = Sanitize.hostname_label(last)
+      label = Sanitize.hostname_label(branch)
+      label.empty? ? nil : label
+    end
+
+    # A detached HEAD has no branch to name it, so the worktree's
+    # directory does — the same identity the per-worktree database is
+    # keyed on. Without this, a detached worktree would fall back to the
+    # bare app name and answer on the main checkout's hostname.
+    def worktree_dir_prefix(cwd)
+      top, status = git(cwd, "rev-parse", "--show-toplevel")
+      return nil unless status.success?
+
+      label = Sanitize.hostname_label(File.basename(top.strip))
       label.empty? ? nil : label
     end
 
@@ -81,7 +96,7 @@ module Yamine
       branch, s3 = git(cwd, "rev-parse", "--abbrev-ref", "HEAD")
       return nil unless s3.success?
 
-      branch_to_prefix(branch.strip)
+      branch_to_prefix(branch.strip) || worktree_dir_prefix(cwd)
     rescue SystemCallError
       filesystem_worktree_prefix(cwd)
     end
@@ -98,8 +113,10 @@ module Yamine
           if match && match[1].match?(%r{[/\\]worktrees[/\\][^/\\]+\z})
             head = File.join(File.expand_path(match[1], dir.to_s), "HEAD")
             branch = read_branch_from_head(head)
-            prefix = branch_to_prefix(branch.to_s)
-            return prefix ? [prefix, "git worktree"].first : nil
+            # Same rule as the git path: branch when there is one, the
+            # worktree directory otherwise (detached HEAD).
+            prefix = branch_to_prefix(branch.to_s) || Sanitize.hostname_label(dir.basename.to_s)
+            return prefix.empty? ? nil : prefix
           end
           return nil
         end

data/lib/yamine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yamine
-  VERSION = "0.11.1"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Kaka Ruto