yamine 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e48f66da1b02dd9ea589c1a30225d6b1f9dc46cd1abd92ffad90c27422b6d4ca
-  data.tar.gz: '0209cb0ce1c976c5f6a934ba0a74283f3b8064e2fc9aed493208c74077dd5a62'
+  metadata.gz: 4a9a67fc55d6a6514571970b0a4ee40a682878c28b4a2bdf3a140a7a509715c8
+  data.tar.gz: e3332534d4123efbc4fea82c06c0af753866d4ca48db335860e921121baf2e12
 SHA512:
-  metadata.gz: 2626fc9696988148d9637ffd1ce14adc7d7d656b03d61854296ff3b6c818fd82ff840fce5904395ac8d2b54c027c9f7e63f47f0f077609f896542af06c282d28
-  data.tar.gz: 110d265a913ee76a3ff40328c40cfdc0475e195c3e1518a490294dd2bb7bca0536edbaeedba7bc37815625aa3975880efdb1b1a66252b3c2a9ed16d6a2b5abd1
+  metadata.gz: 7306ce065ecb6ff40ee10465f3fffc5108d6786a596c2783194459ec143e42649026f7b14ba170e3bbc9561d14738a613b0da8654ed59a335ba2e54e818a6345
+  data.tar.gz: fb1603c3b379c8067ce51a9aec0baf51a669aec3a9a74002493d9d750e7d224ebb9c8feeb46d786a84f1c0f035d590960e4943feb56e0fb9da7c3c8da1b1b186

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [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

data/README.md

@@ -117,7 +117,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 +136,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 +162,11 @@ yamine --variant demo                           # -> https://demo.myapp.localhos
 yamine --tld preview.example.com                # your own domain (OAuth parity)
 ```
 
+Because a registered route answers `*.` subdomains of itself, any
+`<label>.myapp.localhost` reaches the main checkout until a worktree
+registers that exact name — at which point the exact route wins and the
+worktree takes over.
+
 ## Commands
 
 ```bash

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

@@ -78,16 +78,26 @@ 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.
+
 ## 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])
@@ -653,10 +654,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

@@ -175,6 +175,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 +264,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 +281,7 @@ 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],
           urls: urls,
           processes: resolved.processes.keys,
           framework: Framework.detect(Dir.pwd).to_s
@@ -288,7 +297,11 @@ 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)"}"
         puts "processes: #{payload[:processes].join(", ")}"
         puts "urls:"
         urls.each { |u| puts "  #{u}" }

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, :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,33 @@ module Yamine
         secrets: config.secrets,
         sources: sources,
         variant: variant_name,
+        overlay: overlay,
         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/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.12.0"
 end

metadata

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