yamine 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43ea000326072db8f0173360b3ef58a6cce132e20f372b65f0e777bafbb97e9d
-  data.tar.gz: 3e878d2cae8afffd1dca255a006a5863e12dbd4471a4b6214656dda5bc97d37f
+  metadata.gz: ab7c7e888dc8066ad10a7ed2fa90dcd684b27aa171038ac0ae5ea4c06b22251b
+  data.tar.gz: '097d12693a71cf3969f481fd0f61b3f82e9a09d7958139e32b3fb79a7e667cd8'
 SHA512:
-  metadata.gz: 272dae53dfac6b0521c09c00ae096cdc10620dcabf8064a286a0fe25813a61738b3fefc4bb34cf8fdfdd8dd1467a0064ec4e8ceb6ec7b262a8ed638b66101bda
-  data.tar.gz: e16540d1830850c50a54451ec5f0bfb0ad87fd770b111a0b4276aad9a6916dadeeed4c106b61392e5fc5794e6276f003f718a5e53135885f36cc142944d1a12f
+  metadata.gz: 99ddf961f8fa7e50038cb093b592f692c4c90a94279dc200b9ab7ea9e8a70355e6bf67659bf0cb53aac66d2868d99c6fc138750e490aa1fa4ff5b606bbfacc3f
+  data.tar.gz: 825fb69b730125767e18472ca3d7d615514660b63dbcb7aa63697970f6733b1497997b505a6fde9f1e6b0c62785127fac0d2b1332544ff4d535b4076680623b8

data/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [0.14.0] — 2026-09-13
+
+### Added
+
+- **yamine now owns the worktree lifecycle, from `add` to `clean`.**
+  It already gave every linked worktree its own URL, database, and
+  routes; it just never managed the worktree itself. Creating one meant
+  a manual `git worktree add`, re-creating the gitignored config by
+  hand, a bundle install, and a first boot that discovered everything
+  the hard way — and cleanup was hand-run `git worktree remove` with
+  routes, databases, and hosts entries left to rot.
+
+  `yamine worktree add <name>` creates the worktree beside the repo
+  (branch = name), copies `config/local.yml` and
+  `config/local.secrets` — the gitignored per-checkout files git does
+  not carry and the single largest follow-up cost — runs
+  `bundle install`, pre-creates the per-worktree database with schema,
+  and prints the URL the worktree will serve. `yamine worktree remove
+  <name>` is the full teardown of one worktree: stop its backends,
+  remove its routes, drop its database, `git worktree remove`, delete
+  the branch. `yamine worktree clean [--all] [--dry-run]` is the
+  done-and-merged sweep: full teardown of every merged worktree plus
+  the old orphan sweep, `list` shows every worktree with its database,
+  dirty, and merged status.
+
+  The safety rails are load-bearing: the main checkout is never a
+  candidate; `clean` never touches a worktree with uncommitted changes
+  (and disregards only the config yamine itself copied, so a fresh
+  worktree is not born dirty); branches go with `git branch -d`, so
+  `clean --all` may remove an unmerged worktree but never its branch —
+  only `remove --force` discards changes or unmerged refs; a failed
+  database drop aborts before the directory is touched, keeping the
+  claim for a retry. A sqlite or template-less app needs no server
+  drop, so its claims are forgotten instead of failing forever — the
+  same honesty 0.13.1 gave postgres, extended to the apps that never
+  had a server to begin with.
+
+## [0.13.2] — 2026-09-12
+
+### Fixed
+
+- **"Resolves" now means "resolves for every client", not "the system
+  resolver said yes".** `Hosts.resolves?` asked `Addrinfo.getaddrinfo`,
+  which on macOS answers any `.localhost` name unconditionally — so
+  doctor and boot reported every `.localhost` route as fully resolved
+  even with no `/etc/hosts` entry, while a client that resolves only
+  from the hosts file (a CGO-disabled Go binary; AnyGit is the case
+  that found it) could not resolve any of them. That invisible gap is
+  why `sudo yamine hosts sync` existed as a manual step at all.
+
+  The check is now state-based. `Hosts.hosts_entry?` reads the hosts
+  file directly — any loopback mapping counts, hand-added entries
+  included, not just yamine's managed block — and `Hosts.resolution`
+  classifies each route as `ok` (every client resolves it), `warn`
+  (browsers and curl fine via the RFC 6761 `.localhost` special case;
+  file-only resolvers cannot see it), or `fail` (nothing resolves it).
+  Doctor renders the warn class with its existing `[warn]` state instead
+  of a failure — the 0.7.0 lesson, kept by severity and wording rather
+  than by a probe — and boot names the two gaps separately.
+
+  `.localhost` names are classified on file absence alone: the system
+  resolver's unconditional yes carries no information, and acting on it
+  was the bug. getaddrinfo now runs only for custom-TLD names the file
+  does not answer (real DNS or `/etc/resolver` setups stay `ok`), so
+  the common doctor path does no probing at all.
+
 ## [0.13.1] — 2026-09-12
 
 ### Fixed

data/README.md

@@ -122,7 +122,9 @@ 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`.
+no DNS server, no `/etc/resolver`. Safari, custom TLDs, and resolvers
+that read only `/etc/hosts` (CGO-disabled Go binaries are the common
+case) need `yamine hosts sync`.
 
 ## Hostname shape
 
@@ -156,6 +158,32 @@ A variant is a hostname label, not a config file. Only an explicit
 branch named like a file on disk cannot change your config by accident.
 `yamine status` prints both lines so the two are never confused.
 
+## Worktree lifecycle
+
+yamine owns a worktree from creation to removal:
+
+```bash
+yamine worktree add feature/login    # worktree + config + database, ready to boot
+yamine worktree list                 # every worktree: db, dirty, merged
+yamine worktree remove feature/login # stop, drop db, remove worktree
+yamine worktree clean                # tear down everything already merged
+```
+
+`add` lands the worktree beside the repo, copies the gitignored
+per-checkout config (`config/local.yml`, `config/local.secrets`) the
+branch needs, runs `bundle install`, and pre-creates the per-worktree
+database with schema — the next step is just `yamine start` in it.
+
+`clean` is the done-and-merged sweep: it tears down every worktree
+whose branch is merged (stop, drop database, remove worktree, delete
+branch) and forgets claims of directories that no longer exist. It
+never touches a worktree with uncommitted changes, and unmerged
+branches survive every path except `remove --force` — `git branch -d`
+refuses to delete what git has not seen merged, so a wrong merge
+detection cannot lose a branch. `--all` includes clean-but-unmerged
+worktrees (the branch stays); `--dry-run` prints the plan; `remove
+--force` is the only command that discards uncommitted changes.
+
 ```bash
 yamine                                          # -> https://myapp.localhost
 yamine --service api                            # -> https://api.myapp.localhost
@@ -200,7 +228,7 @@ yamine trust                  # add local CA to system trust store
 yamine clean                  # remove state and hosts entries
 yamine prune                  # remove stale routes
 yamine db list|create|drop    # per-worktree databases
-yamine worktree list|clean    # worktree databases + orphan cleanup
+yamine worktree list|add|remove|clean   # worktree lifecycle
 yamine stop                   # stop this app's backend + routes
 yamine restart                # touch tmp/restart.txt (managed apps reboot)
 yamine log [-f] [n]           # tail (or follow) this app's backend log

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

@@ -98,6 +98,26 @@ 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.
 
+## Worktree lifecycle
+
+```bash
+yamine worktree add feature/login   # create + make bootable
+yamine worktree list                # branch, dir, db, dirty/merged
+yamine worktree remove feature/login
+yamine worktree clean [--dry-run]
+```
+
+`add` creates the git worktree beside the repo, copies the gitignored
+per-checkout config (`config/local.yml`, `config/local.secrets`), runs
+`bundle install`, and pre-creates the per-worktree database — then boot
+with `yamine start` inside it. `clean` tears down every worktree whose
+branch is merged (stops backends, drops the database, removes the
+worktree, deletes the branch) and forgets claims of directories that
+vanished. It never touches uncommitted work; unmerged branches survive
+everything except `remove --force`. Prefer `clean --dry-run` first, and
+`clean` over `rm -rf` — a removed worktree leaves no routes, database,
+or stale hosts entries behind.
+
 ## Subdomains are opt-in
 
 A route answers its exact hostname. `*.myapp.localhost` reaches the app
@@ -144,8 +164,10 @@ yamine prune                  # clear stale routes from crashed sessions
 yamine start --json           # boot readiness payload (pass/fail + log tail)
 ```
 
-If a hostname does not resolve: `yamine hosts sync`. If the browser
-warns about TLS: `yamine trust`.
+If a hostname does not resolve — or boot/doctor report it as not in
+`/etc/hosts` and you use clients that read only that file (CGO-disabled
+Go binaries): `yamine hosts sync`. If the browser warns about TLS:
+`yamine trust`.
 
 ## When NOT to use yamine
 

data/lib/yamine/cli/boot.rb

@@ -157,7 +157,7 @@ module Yamine
         end
 
         say opts
-        ctx.report_unresolved(routes_registered.flat_map { |r| r[:hostnames] })
+        ctx.report_resolution_gaps(routes_registered.flat_map { |r| r[:hostnames] })
 
         # Supervisor: exit when ANY child dies (loud cleanup). pid => name
         # so the message names the casualty instead of "a process".

data/lib/yamine/cli/context.rb

@@ -35,11 +35,22 @@ module Yamine
         ProxyControl.proxy_tls(store)
       end
 
-      def report_unresolved(hostnames)
-        missing = Hosts.unresolved(hostnames)
-        return if missing.empty?
+      # Boot-time DNS report. Two distinct gaps, named separately: a fail
+      # resolves nowhere; a warn resolves in browsers and curl (the RFC
+      # 6761 .localhost special case) but not for clients that read only
+      # /etc/hosts — which is exactly the gap `hosts sync` closes.
+      def report_resolution_gaps(hostnames)
+        groups = Hosts.resolution(hostnames)
+        return if groups[:fail].empty? && groups[:warn].empty?
 
-        warn "Warning: #{missing.join(", ")} will not resolve. Run: yamine hosts sync"
+        unless groups[:fail].empty?
+          warn "Warning: #{groups[:fail].join(", ")} will not resolve. Run: yamine hosts sync"
+        end
+        unless groups[:warn].empty?
+          warn "Warning: #{groups[:warn].join(", ")} not in /etc/hosts — browsers and curl " \
+            "resolve them anyway, but clients that only read /etc/hosts (CGO-disabled Go " \
+            "binaries) cannot. Run: yamine hosts sync if you use such clients."
+        end
       end
 
       def wait_for_exit(pid, timeout:)

data/lib/yamine/cli/system.rb

@@ -955,57 +955,6 @@ module Yamine
       def boot_env_name
         ENV.fetch("RAILS_ENV", "development")
       end
-
-      # Worktree helpers: list claimed databases with liveness, clean
-      # drops databases whose worktree dirs are gone.
-      def worktree(ctx, args)
-        sub = args.first
-        case sub
-        when "list", nil
-          map = Database.load_map(ctx.store.dir)
-          if map.empty?
-            puts "No worktree databases claimed yet."
-            return
-          end
-          map.each do |name, info|
-            alive = File.directory?(info["dir"]) ? "alive" : "gone"
-            puts "  #{name}  #{info["dir"]}  (#{alive})"
-          end
-        when "clean"
-          orphaned = Database.orphaned(ctx.store.dir)
-          if orphaned.empty?
-            puts "No orphaned worktree databases."
-            return
-          end
-          template = drop_template
-          unless template && !template.strip.empty?
-            $stderr.puts "Error: no DATABASE_URL template found (ENV or env.clear in config/local.yml) — cannot drop the orphaned databases."
-            exit 1
-          end
-          dropped, missing, failed = [], [], []
-          orphaned.each do |name, _info|
-            case Database.drop(name, template)
-            when :dropped then dropped << name
-            when :missing then missing << name
-            when :failed then failed << name
-            end
-          end
-          dropped.each { |n| puts "  dropped #{n}" }
-          missing.each { |n| puts "  #{n} did not exist — nothing to drop" }
-          failed.each { |n| warn "  could not drop #{n} — is the server running? Claim kept for a retry." }
-          # Forget only the claims we actually handled; a failed drop
-          # stays recorded so the next clean can retry it.
-          map = Database.load_map(ctx.store.dir)
-          (dropped + missing).each { |n| map.delete(n) }
-          Database.save_map(ctx.store.dir, map)
-          summary = "Cleaned #{orphaned.length} orphaned claim(s): #{dropped.length} dropped, #{missing.length} already gone"
-          summary += ", #{failed.length} failed" if failed.any?
-          puts "#{summary}."
-          exit 1 if failed.any?
-        else
-          raise Error, "Usage: yamine worktree [list|clean]"
-        end
-      end
     end
   end
-end
+end

data/lib/yamine/cli/worktree.rb

@@ -0,0 +1,534 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Yamine
+  class CLI
+    # Worktree lifecycle. yamine already gives every linked worktree its
+    # own URL, database, and routes; these commands let it own the whole
+    # span, from `add` (create + make it bootable with no follow-up
+    # work) to `clean` (when a branch is merged, take down everything
+    # the worktree stood up, including the worktree itself).
+    #
+    # Safety rails, in order of hardness:
+    #   * the main checkout is never a candidate (Worktrees filters it);
+    #   * `clean` never touches a worktree with uncommitted changes;
+    #   * branches are deleted with `git branch -d`, so git itself
+    #     refuses to drop unmerged refs — `clean --all` may remove an
+    #     unmerged worktree but never its branch;
+    #   * only `worktree remove --force` (git --force + branch -D)
+    #     overrides, and it names what it discarded;
+    #   * a database drop that fails aborts the teardown before the
+    #     directory is touched, keeping the claim for a retry.
+    module WorktreeCommand
+      module_function
+
+      # Per-checkout config that git does not carry: a fresh worktree
+      # boots without these (missing secrets, no proxy config) — the
+      # single largest follow-up cost of a new worktree.
+      LOCAL_CONFIG_FILES = %w[config/local.yml config/local.secrets].freeze
+
+      def run(ctx, args)
+        sub = args.first
+        case sub
+        when "list", nil then list(ctx, args[1..] || [])
+        when "add" then add(ctx, args[1..] || [])
+        when "remove" then remove(ctx, args[1..] || [])
+        when "clean" then clean(ctx, args[1..] || [])
+        else
+          raise Error,
+            "Usage: yamine worktree list | add <name> [--dir <path>] [--no-install] | " \
+            "remove <name> [--force] | clean [--all] [--dry-run]"
+        end
+      end
+
+      def list(ctx, _args)
+        map = Database.load_map(ctx.store.dir)
+        repo = repo_top
+        printed = false
+
+        if repo
+          default_branch = Worktrees.default_branch(repo)
+          Worktrees.list(repo).each do |entry|
+            next if entry.bare
+            puts "  #{entry_line(entry, claim_for(map, entry.path), repo, default_branch)}"
+            printed = true
+          end
+        end
+        map.select { |_, info| !File.directory?(info["dir"]) }.each do |name, info|
+          puts "  #{name}  #{info["dir"]}  (gone)"
+          printed = true
+        end
+        puts "No worktrees or database claims." unless printed
+      end
+
+      def entry_line(entry, claim, repo, default_branch)
+        name = entry.main? ? "main" : (entry.branch || "(detached)")
+        line = "#{name}  #{entry.path}"
+        line += "  db #{claim[0]}" if claim
+
+        flags = []
+        flags << "main checkout" if entry.main?
+        flags << "detached" if entry.detached && !entry.main?
+        flags << "dir gone" unless entry.exists?
+        if !entry.main? && entry.exists?
+          flags << "dirty" if Worktrees.dirty?(entry.path, ignore: LOCAL_CONFIG_FILES)
+          if entry.detached
+            flags << "unmerged"
+          else
+            merged = Worktrees.merged?(repo, entry.branch, into: default_branch)
+            flags << (merged ? "merged" : "unmerged")
+          end
+        end
+        line += "  (#{flags.join(", ")})" unless flags.empty?
+        line
+      end
+
+      # yamine worktree add <name> [--dir <path>] [--no-install]
+      #
+      # `name` is the branch (feature/login stays feature/login — the
+      # whole branch is the hostname label). The worktree lands beside
+      # the repo as <repo>-<label>, receives the gitignored per-checkout
+      # config, a bundle install, and its own database with schema, so
+      # the next step is just `yamine start` in it.
+      def add(ctx, args)
+        opts, rest = take_flags(args, value_flags: %w[--dir], flags: %w[--no-install])
+        name = rest.first
+        unless name
+          raise Error, "Usage: yamine worktree add <name> [--dir <path>] [--no-install]"
+        end
+
+        repo = repo_top || abort_not_in_repo
+        label = Sanitize.hostname_label(name)
+        if label.empty?
+          raise Error, "#{name.inspect} has no usable hostname label"
+        end
+        if Variant::DEFAULT_BRANCHES.include?(name)
+          raise Error, "refusing to create a worktree on the default branch #{name.inspect}"
+        end
+
+        dir = opts[:dir] || File.expand_path("../#{File.basename(repo)}-#{label}", repo)
+        if File.exist?(dir)
+          raise Error, "#{dir} already exists — remove it first or pass --dir"
+        end
+
+        out, status = Worktrees.add(repo, name, dir)
+        unless status&.success?
+          $stderr.puts "Error: git worktree add failed:"
+          $stderr.puts out.to_s.gsub(/^/, "  ")
+          exit 1
+        end
+        puts "  created #{dir} (branch #{name})"
+
+        copied = copy_local_config(repo, dir)
+        copied.each { |f| puts "  copied #{f}" }
+        if copied.empty?
+          puts "  no config/local.yml in #{repo} — run `yamine init` in the worktree before booting"
+        end
+
+        install_deps(dir) unless opts[:no_install]
+
+        db_name = prepare_database(ctx, dir)
+        say_ready(ctx, dir, name, db_name)
+      end
+
+      def copy_local_config(from_dir, to_dir)
+        copied = []
+        LOCAL_CONFIG_FILES.each do |rel|
+          src = File.join(from_dir, rel)
+          next unless File.file?(src)
+
+          dst = File.join(to_dir, rel)
+          FileUtils.mkdir_p(File.dirname(dst))
+          FileUtils.cp(src, dst)
+          copied << rel
+        end
+        copied
+      end
+
+      # The deps phase would fail-fast on a missing bundle anyway; doing
+      # it here turns "add" into "ready to boot". Failure warns and
+      # continues — boot's own pre-flight reports it with the fix.
+      def install_deps(dir)
+        return unless File.file?(File.join(dir, "Gemfile"))
+
+        puts "  bundle install..."
+        system("bundle", "install", chdir: dir)
+        puts "  bundle install did not finish — run it in #{dir} before booting" unless $?.success?
+      end
+
+      # Claim the per-worktree database and create it now (with the
+      # app's schema) so server problems surface at creation time, not
+      # at first boot. Boot reuses an existing database idempotently, so
+      # this is never wasted work. SQLite and template-less apps need
+      # nothing; setup_database says so itself.
+      def prepare_database(ctx, dir)
+        return nil unless Config.load(dir)
+
+        db_name = Database.name_for(dir, env: BootCommand.rails_env,
+          state_dir: ctx.store.dir)
+        Dir.chdir(dir) do
+          BootCommand.setup_database(ctx, Resolver.resolve(dir), db_name)
+        end
+        db_name
+      end
+
+      def say_ready(ctx, dir, name, db_name)
+        puts "Worktree ready:"
+        puts "  dir      #{dir}"
+        puts "  branch   #{name}"
+        puts "  db       #{db_name}" if db_name
+        if (resolved = resolved_quietly(dir))
+          Resolver.urls(resolved, port: ctx.proxy_port, tls: ctx.proxy_tls)
+            .each { |u| puts "  url      #{u}" }
+        end
+        puts "  boot it: cd #{dir} && yamine start"
+      end
+
+      def resolved_quietly(dir)
+        Resolver.resolve(dir)
+      rescue StandardError
+        nil
+      end
+
+      # yamine worktree remove <name> [--force]
+      #
+      # Full teardown of one worktree, merge state regardless (the flag
+      # only decides whether git may discard uncommitted changes and
+      # delete an unmerged branch). --force is the only path that can
+      # do either.
+      def remove(ctx, args)
+        opts, rest = take_flags(args, value_flags: [], flags: %w[--force])
+        name = rest.first
+        raise Error, "Usage: yamine worktree remove <name> [--force]" unless name
+
+        repo = repo_top || abort_not_in_repo
+        entry = Worktrees.find(repo, name)
+        if entry.nil? || entry.main?
+          raise Error, "no worktree named #{name.inspect} here — `yamine worktree list` shows what exists"
+        end
+
+        unless entry.exists?
+          abandon(ctx, repo, entry)
+          return
+        end
+
+        if Worktrees.dirty?(entry.path, ignore: LOCAL_CONFIG_FILES) && !opts[:force]
+          $stderr.puts "Error: #{entry.path} has uncommitted changes."
+          $stderr.puts "  Commit or stash them, or re-run with --force to discard them."
+          exit 1
+        end
+
+        exit 1 unless teardown(ctx, repo, entry, force: opts[:force])
+        Worktrees.prune(repo)
+        resync_hosts(ctx)
+      end
+
+      # yamine worktree clean [--all] [--dry-run]
+      #
+      # The done-and-merged sweep: databases of worktree directories
+      # that no longer exist (any repo), plus full teardown of this
+      # repo's merged worktrees. Unmerged and dirty worktrees are kept,
+      # with the reason — they are work in progress, not leftovers.
+      def clean(ctx, args)
+        opts, rest = take_flags(args, value_flags: [], flags: %w[--all --dry-run])
+        unless rest.empty?
+          raise Error, "Usage: yamine worktree clean [--all] [--dry-run]"
+        end
+
+        repo = repo_top
+        plan = build_plan(ctx, repo, all: opts[:all])
+        if plan.empty?
+          puts "Nothing to clean."
+          return
+        end
+
+        if opts[:dry_run]
+          plan.each { |step| puts "  would #{step.describe}" }
+          return
+        end
+
+        failures = 0
+        changed = false
+        plan.each do |step|
+          case step[0]
+          when :drop_db
+            if drop_orphan(ctx, step[1], step[2])
+              changed = true
+            else
+              failures += 1
+            end
+          when :teardown
+            if teardown(ctx, repo, step[1], force: false)
+              changed = true
+            else
+              failures += 1
+            end
+          when :prune
+            changed = true
+          when :keep
+            puts "  kept #{step[1]} — #{step[2]}"
+          end
+        end
+        Worktrees.prune(repo) if repo
+        resync_hosts(ctx) if repo && changed
+        ran = plan.count { |s| %i[drop_db teardown prune].include?(s[0]) }
+        summary = "Cleaned #{ran} item(s)"
+        summary += ", #{failures} failed" if failures.positive?
+        puts "#{summary}."
+        exit 1 if failures.positive?
+      end
+
+      Plan = Struct.new(:action, :subject, :reason) do
+        def describe
+          case action
+          when :drop_db then "drop database #{subject} (#{reason} is gone)"
+          when :teardown then "remove worktree #{subject.path} (#{reason})"
+          when :prune then "prune stale git entry #{subject}"
+          when :keep then "keep #{subject} — #{reason}"
+          end
+        end
+      end
+
+      def build_plan(ctx, repo, all:)
+        plan = []
+        Database.orphaned(ctx.store.dir).each do |name, info|
+          plan << Plan.new(:drop_db, name, info["dir"])
+        end
+        return plan unless repo
+
+        default_branch = Worktrees.default_branch(repo)
+        Worktrees.list(repo).each do |entry|
+          next if entry.bare || entry.main?
+
+          unless entry.exists?
+            plan << Plan.new(:prune, entry.path)
+            next
+          end
+          if Worktrees.dirty?(entry.path, ignore: LOCAL_CONFIG_FILES)
+            plan << Plan.new(:keep, entry.path, "uncommitted changes are never cleaned automatically")
+            next
+          end
+          merged = Worktrees.merged?(repo, entry.branch, into: default_branch)
+          if merged
+            plan << Plan.new(:teardown, entry, "branch merged into #{default_branch}")
+          elsif all
+            plan << Plan.new(:teardown, entry,
+              "--all; branch #{entry.branch} stays (unmerged into #{default_branch})")
+          else
+            plan << Plan.new(:keep, entry.path,
+              "branch not merged into #{default_branch} (--all to override)")
+          end
+        end
+        plan
+      end
+
+      # An admin entry whose directory vanished (rm -rf, a crashed
+      # agent): drop the database it claimed, forget the claim. The git
+      # entry itself is cleared by the trailing prune. A template with
+      # no server behind it (sqlite) means there is nothing to drop and
+      # no retry that could help — the claim is simply forgotten.
+      def drop_orphan(ctx, name, _dir)
+        template = orphan_template(ctx)
+        unless template
+          $stderr.puts "Error: no DATABASE_URL template found (ENV or env.clear in " \
+            "config/local.yml) — cannot drop #{name}."
+          return false
+        end
+        unless %i[postgres mysql].include?(Database.adapter_for(template))
+          puts "  #{name} has no server database (sqlite/unknown adapter) — claim forgotten"
+          forget_claim(ctx, name)
+          return true
+        end
+        case Database.drop(name, template)
+        when :dropped then puts "  dropped #{name}"
+        when :missing then puts "  #{name} did not exist — nothing to drop"
+        when :failed
+          warn "  could not drop #{name} — is the server running? Claim kept for a retry."
+          return false
+        end
+        forget_claim(ctx, name)
+        true
+      end
+
+      def forget_claim(ctx, name)
+        map = Database.load_map(ctx.store.dir)
+        map.delete(name)
+        Database.save_map(ctx.store.dir, map)
+      end
+
+      # Orphan directories are gone, so their configs are unreadable —
+      # the template comes from the environment or whatever checkout the
+      # command runs in, exactly as `db drop` has always done.
+      def orphan_template(ctx)
+        env = ENV["DATABASE_URL"]
+        return env if env && !env.strip.empty?
+
+        config = Config.load(Dir.pwd)
+        config && Database.template_for(config)
+      end
+
+      # A worktree whose directory is already gone: nothing to stop or
+      # remove, just its database claim and the stale git entry.
+      def abandon(ctx, repo, entry)
+        map = Database.load_map(ctx.store.dir)
+        claim = claim_for(map, entry.path)
+        if claim
+          exit 1 unless drop_orphan(ctx, claim[0], entry.path)
+        end
+        Worktrees.prune(repo)
+        puts "  pruned #{entry.path} (directory was already gone)"
+      end
+
+      # The teardown shared by `remove` and `clean`. Returns true when
+      # the worktree is gone; false means abort with state intact for a
+      # retry. The database drop happens BEFORE git removes the
+      # directory: a failed drop must not leave a database behind with
+      # no config to reach it.
+      def teardown(ctx, repo, entry, force:)
+        dir = entry.path
+        map = Database.load_map(ctx.store.dir)
+        claim = claim_for(map, dir)
+
+        stop_routes(ctx, dir)
+
+        if claim
+          outcome = drop_database(repo, dir, claim[0])
+          if outcome == :failed
+            warn "  kept #{dir} — database drop failed; fix the server and re-run"
+            return false
+          end
+          map = Database.load_map(ctx.store.dir)
+          map.delete(claim[0])
+          Database.save_map(ctx.store.dir, map)
+        end
+
+        out, status = Worktrees.remove(repo, dir, force: force)
+        unless status&.success?
+          $stderr.puts "Error: git worktree remove failed:"
+          $stderr.puts out.to_s.gsub(/^/, "  ")
+          return false
+        end
+        puts "  removed #{dir}"
+
+        if entry.branch
+          flag = force ? "-D" : "-d"
+          _o, deleted = Open3.capture2("git", "branch", flag, entry.branch, chdir: repo,
+            err: File::NULL)
+          if deleted&.success?
+            puts "  deleted branch #{entry.branch}"
+          else
+            puts "  kept branch #{entry.branch} (git refuses to delete an unmerged branch)"
+          end
+        end
+        true
+      end
+
+      # Routes registered from this worktree (spec.dir marks
+      # boot-registered backends). The directory is about to disappear,
+      # so live backends are stopped regardless of which agent owns
+      # them — no route could survive the removal anyway, and leaving a
+      # live process with its working directory deleted is worse.
+      def stop_routes(ctx, dir)
+        routes = ctx.store.load_routes_raw.select do |r|
+          r.dig("spec", "dir") == File.expand_path(dir)
+        end
+        routes.each do |entry|
+          hostname = entry["hostname"]
+          backend_pid = ctx.backend_pid_for(entry)
+          if backend_pid && ProxyControl.pid_alive?(backend_pid)
+            begin
+              Process.kill("TERM", backend_pid)
+              ctx.wait_for_exit(backend_pid, timeout: 10)
+            rescue SystemCallError
+              nil
+            end
+          end
+          ctx.store.remove_route(hostname)
+          FileUtils.rm_f(File.join(ctx.store.dir, "backend-#{hostname}.pid"))
+          puts "  stopped #{hostname}"
+        end
+      end
+
+      def drop_database(repo, dir, name)
+        template = drop_template_for(repo, dir)
+        adapter = template && Database.adapter_for(template)
+        unless %i[postgres mysql].include?(adapter)
+          puts "  no server database to drop for #{name} " \
+            "(#{template ? "sqlite/unknown adapter" : "no DATABASE_URL template"})"
+          return :missing
+        end
+
+        outcome = Database.drop(name, template)
+        case outcome
+        when :dropped then puts "  dropped #{name}"
+        when :missing then puts "  #{name} did not exist — nothing to drop"
+        when :failed then puts "  could not drop #{name} — is the database server running?"
+        end
+        outcome
+      end
+
+      # Reach the database server from the worktree's own config (read
+      # BEFORE the directory is removed), falling back to the main
+      # checkout, then the environment.
+      def drop_template_for(repo, dir)
+        [dir, repo].each do |base|
+          config = Config.load(base) rescue nil
+          next unless config
+
+          template = Database.template_for(config)
+          return template if template && !template.strip.empty?
+        end
+        ENV["DATABASE_URL"]
+      end
+
+      # The removed routes should leave the hosts block too. Best-effort:
+      # the file is root-owned, and the next boot's workstation check
+      # re-syncs anyway.
+      def resync_hosts(ctx)
+        ctx.store.prune_stale
+        hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
+        return if Hosts.sync(hostnames)
+
+        warn "Warning: could not update /etc/hosts (try sudo yamine hosts sync)."
+      end
+
+      def claim_for(map, dir)
+        expanded = File.expand_path(dir)
+        map.find { |_, info| info["dir"] == expanded }
+      end
+
+      def repo_top
+        out, status = Open3.capture2("git", "rev-parse", "--show-toplevel",
+          chdir: Dir.pwd, err: File::NULL)
+        status&.success? ? out.strip : nil
+      rescue SystemCallError
+        nil
+      end
+
+      def abort_not_in_repo
+        $stderr.puts "Error: not inside a git repository — run from the app's checkout."
+        exit 1
+      end
+
+      def take_flags(args, value_flags:, flags:)
+        opts = {}
+        rest = []
+        until args.empty?
+          arg = args.shift
+          next rest << arg unless arg.start_with?("--")
+
+          if value_flags.include?(arg)
+            opts[arg.sub(/\A--/, "").tr("-", "_").to_sym] = args.shift
+          elsif flags.include?(arg)
+            opts[arg.sub(/\A--/, "").tr("-", "_").to_sym] = true
+          else
+            raise Error, "Unknown flag #{arg}"
+          end
+        end
+        [opts, rest]
+      end
+    end
+  end
+end

data/lib/yamine/cli.rb

@@ -60,7 +60,7 @@ module Yamine
       when "init" then SystemCommand.init(ctx, args)
       when "start" then SystemCommand.start(ctx, args)
       when "db" then SystemCommand.db(ctx, args)
-      when "worktree" then SystemCommand.worktree(ctx, args)
+      when "worktree" then WorktreeCommand.run(ctx, args)
       when "kamal" then SystemCommand.kamal(ctx, args)
       when "stop"
         exit RoutesCommand.stop(ctx, args)
@@ -96,7 +96,7 @@ module Yamine
           yamine clean                  Remove state and hosts entries
           yamine prune                  Remove stale routes
           yamine db list|create|drop      Per-worktree databases
-          yamine worktree list|clean     Worktree databases + orphan cleanup
+          yamine worktree list|add|remove|clean   Worktrees: create, inspect, full cleanup
           yamine proxy start|stop       Control the proxy
           yamine service install|status|uninstall   OS startup service
           yamine sudoers                Print scoped passwordless-sudo rules for port 443

data/lib/yamine/doctor.rb

@@ -160,12 +160,24 @@ module Yamine
       hostnames = store.load_routes.map { |r| r["hostname"] }
       return Check.new(name: "dns", ok: true, message: "no routes to resolve") if hostnames.empty?
 
-      missing = Hosts.unresolved(hostnames)
-      if missing.empty?
+      groups = Hosts.resolution(hostnames)
+      problems = []
+      problems << "#{groups[:fail].join(", ")} do not resolve — run: yamine hosts sync" unless groups[:fail].empty?
+      unless groups[:warn].empty?
+        problems << "#{groups[:warn].join(", ")} not in /etc/hosts — browsers and curl " \
+          "resolve them anyway, but clients that only read the hosts file " \
+          "(CGO-disabled Go binaries) cannot — run: yamine hosts sync if you use such clients"
+      end
+
+      if problems.empty?
         Check.new(name: "dns", ok: true, message: "all #{hostnames.length} hostname(s) resolve")
+      elsif groups[:fail].empty?
+        # Only the file-only-resolver gap: most clients are fine, so this
+        # is a warn, not a failure — failing here sent browser-only users
+        # to an elevated hosts write they did not need (the 0.7.0 lesson).
+        Check.new(name: "dns", ok: true, warn: true, message: problems.join("; "))
       else
-        Check.new(name: "dns", ok: false,
-          message: "#{missing.join(", ")} do not resolve — run: yamine hosts sync")
+        Check.new(name: "dns", ok: false, message: problems.join("; "))
       end
     end
 

data/lib/yamine/hosts.rb

@@ -4,9 +4,11 @@ require "socket"
 require "timeout"
 
 module Yamine
-  # /etc/hosts sync for Safari + custom TLDs (.localhost resolves natively
-  # in Chrome/Firefox/Edge; Safari uses the system resolver).
-  # Same managed-block approach as portless hosts.ts.
+  # /etc/hosts sync for the client classes that cannot resolve the routes
+  # on their own: custom TLDs, and resolvers that read only the hosts file
+  # (a CGO-disabled Go binary is the common case — no system resolver, no
+  # RFC 6761 special-casing). Same managed-block approach as portless
+  # hosts.ts.
   module Hosts
     BEGIN_MARKER = "# --- yamine begin ---"
     END_MARKER = "# --- yamine end ---"
@@ -44,14 +46,13 @@ module Yamine
     # Bring the managed block to exactly these hostnames. Idempotent: when
     # the block already matches, this is a no-op returning true.
     #
-    # The short-circuit is load-bearing, not an optimization. /etc/hosts is
+    # The sync short-circuit is load-bearing, not an optimization. /etc/hosts is
     # root-owned on a normal machine, so a rewrite fails without sudo — and
     # `setup` and every boot's workstation check run this. Without the
     # guard, a machine whose hosts file was already correct got a
     # "could not write /etc/hosts (try sudo yamine hosts sync)" warning on
     # every run, sending people to an elevated write for a file that
-    # needed nothing. (Chrome/Firefox/Edge resolve *.localhost natively;
-    # /etc/hosts only matters for Safari and custom TLDs.)
+    # needed nothing.
     def sync(hostnames, path = PATH)
       return true if synced?(hostnames, path)
 
@@ -85,26 +86,60 @@ module Yamine
       false
     end
 
-    # Does the hostname resolve for the programs that will actually use
-    # it — browsers, curl, the app's own HTTP clients? That question can
-    # only be answered by the SYSTEM resolver (getaddrinfo), which reads
-    # nsswitch (so /etc/hosts counts) and implements the RFC 6761
-    # special-use TLDs.
+    # Loopback mappings that count as "this name reaches the proxy".
+    LOOPBACK = %w[127.0.0.1 ::1].freeze
+
+    # Does the hosts file map this hostname to loopback? That is the one
+    # resolution source every client shares — browsers and curl, the
+    # system resolver, and resolvers that read only the file (a
+    # CGO-disabled Go binary is the common case). The whole file is
+    # searched, not just the managed block, so a hand-added entry counts;
+    # only loopback mappings count, since the proxy serves on loopback
+    # and any other address points the name away from yamine.
+    def hosts_entry?(hostname, path = PATH)
+      target = hostname.to_s.downcase
+      File.foreach(path) do |line|
+        parts = line.split("#", 2).first.to_s.split
+        next unless parts.length > 1 && LOOPBACK.include?(parts.first.downcase)
+        return true if parts[1..].any? { |name| name.downcase == target }
+      end
+      false
+    rescue SystemCallError
+      false
+    end
+
+    # Where one hostname stands for the clients that will actually use
+    # it — a question with three answers no single resolver probe can
+    # produce:
+    #
+    #   :ok   — every client resolves it: mapped in the hosts file, or
+    #           found by the system resolver without it (real DNS or an
+    #           /etc/resolver entry for a custom TLD).
+    #   :warn — browsers and curl handle it (the RFC 6761 .localhost
+    #           special case), but file-only resolvers cannot see it.
+    #   :fail — nothing resolves it.
     #
-    # Ruby's Resolv is a pure-Ruby DNS client: it never sees /etc/hosts
-    # and knows nothing about RFC 6761, so it reports "no address for
-    # myapp.localhost" on a machine where .localhost resolves perfectly.
-    # That false negative sent users to `sudo yamine hosts sync` — an
-    # elevated write to /etc/hosts — to fix a problem they did not have.
-    def resolves?(hostname)
+    # .localhost names are classified :warn on file absence alone. The
+    # system resolver answers any .localhost unconditionally, so probing
+    # it carries no information — and acting on that probe is how doctor
+    # and boot once reported every .localhost as fully resolved while a
+    # CGO-disabled Go binary could not resolve any of them.
+    def classification(hostname, path = PATH)
+      return :ok if hosts_entry?(hostname, path)
+      return :warn if hostname.to_s.downcase.end_with?(".localhost")
+
       Timeout.timeout(2) { Addrinfo.getaddrinfo(hostname, nil) }
-      true
+      :ok
     rescue SocketError, SystemCallError, Timeout::Error
-      false
+      :fail
     end
 
-    def unresolved(hostnames)
-      hostnames.reject { |h| resolves?(h) }
+    # Partition hostnames into { ok:, warn:, fail: } for the consumers
+    # that report one line per state (doctor, boot).
+    def resolution(hostnames, path = PATH)
+      groups = { ok: [], warn: [], fail: [] }
+      hostnames.each { |h| groups[classification(h, path)] << h }
+      groups
     end
   end
 end

data/lib/yamine/version.rb

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

data/lib/yamine/worktrees.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Yamine
+  # Git worktree plumbing for `yamine worktree add|list|remove|clean`.
+  #
+  # Thin wrappers over the git CLI: failures carry git's own stderr so
+  # the user sees git's reason, not a paraphrase. Every caller filters
+  # out the main checkout (Entry#main?) — cleanup commands must never
+  # be able to touch it, so the filter lives in the data, not in
+  # whoever remembers to check.
+  module Worktrees
+    module_function
+
+    Entry = Struct.new(:path, :head, :branch, :detached, :bare, keyword_init: true) do
+      def main?
+        Database.main_checkout?(path)
+      end
+
+      def exists?
+        File.directory?(path)
+      end
+    end
+
+    # All worktrees of the repo `dir` belongs to, main checkout first
+    # (git always lists it first). Empty when `dir` is not a repo.
+    def list(dir = Dir.pwd)
+      out, status = git(dir, "worktree", "list", "--porcelain")
+      return [] unless status&.success?
+
+      parse(out)
+    end
+
+    def parse(porcelain)
+      entries = []
+      entry = nil
+      porcelain.lines.each do |line|
+        key, value = line.strip.split(" ", 2)
+        case key
+        when "worktree"
+          entries << entry if entry
+          entry = Entry.new(path: File.expand_path(value.to_s), head: nil,
+            branch: nil, detached: false, bare: false)
+        when "HEAD" then entry&.head = value
+        when "branch" then entry&.branch = value.to_s.sub(%r{\Arefs/heads/}, "")
+        when "detached" then entry&.detached = true
+        when "bare" then entry&.bare = true
+        end
+      end
+      entries << entry if entry
+      entries
+    end
+
+    # The worktree whose branch or directory basename is `name`.
+    def find(dir, name)
+      list(dir).find do |entry|
+        next false if entry.bare
+
+        entry.branch == name || File.basename(entry.path) == name
+      end
+    end
+
+    # Create a worktree on `branch`: checked out when the branch already
+    # exists, created otherwise. Returns [stderr, status]; stderr is
+    # user-facing on failure.
+    def add(base_dir, branch, path)
+      if branch_exists?(base_dir, branch)
+        run(base_dir, "worktree", "add", path, branch)
+      else
+        run(base_dir, "worktree", "add", "-b", branch, path)
+      end
+    end
+
+    def remove(base_dir, path, force: false)
+      args = ["worktree", "remove"]
+      args << "--force" if force
+      run(base_dir, *args, path)
+    end
+
+    # Forget worktree admin entries whose directories are gone.
+    def prune(base_dir)
+      run(base_dir, "worktree", "prune")
+    end
+
+    def branch_exists?(base_dir, branch)
+      _out, status = git(base_dir, "rev-parse", "--verify", "--quiet",
+        "refs/heads/#{branch}")
+      status&.success?
+    end
+
+    # Uncommitted changes at `path`, disregarding `ignore` paths. The
+    # per-checkout config yamine copies (config/local.yml, local.secrets)
+    # is supposed to be present and is usually gitignored anyway —
+    # without the ignore list a freshly-added worktree reads as dirty
+    # and no cleanup could ever take it down without --force.
+    def dirty?(path, ignore: [])
+      out, status = git(path, "status", "--porcelain")
+      return false unless status&.success?
+
+      # Porcelain is column-based: XY then a space, path at index 3 —
+      # XY itself is often " M" or "??", so the path must be cut by
+      # position, never by stripping whitespace first.
+      out.lines.any? do |line|
+        next false if line.strip.empty?
+
+        !ignore.include?(line[3..].to_s.strip)
+      end
+    end
+
+    # Is `branch` fully merged into `into`? Anything git cannot answer
+    # is reported unmerged, so deletion stays the explicit choice.
+    def merged?(base_dir, branch, into:)
+      return false unless branch && into
+
+      _out, status = git(base_dir, "merge-base", "--is-ancestor", branch, into)
+      status&.success?
+    end
+
+    # The branch cleanup merges against: a local main or master when one
+    # exists, else whatever origin/HEAD points at, else master.
+    def default_branch(base_dir)
+      Variant::DEFAULT_BRANCHES.each do |candidate|
+        return candidate if branch_exists?(base_dir, candidate)
+      end
+
+      out, status = git(base_dir, "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+      return out.strip.sub(%r{\Arefs/remotes/origin/}, "") if status&.success? && !out.strip.empty?
+
+      "master"
+    end
+
+    # Capture stderr: for add/remove, git's message IS the error.
+    def run(dir, *args)
+      out, status = Open3.capture2e("git", *args, chdir: dir)
+      [out, status]
+    rescue SystemCallError, ArgumentError => e
+      [e.message, nil]
+    end
+
+    def git(dir, *args)
+      Open3.capture2("git", *args, chdir: dir, err: File::NULL)
+    rescue SystemCallError, ArgumentError
+      ["", nil]
+    end
+  end
+end

data/lib/yamine.rb

@@ -8,6 +8,7 @@ require_relative "yamine/sanitize"
 require_relative "yamine/hostname"
 require_relative "yamine/inference"
 require_relative "yamine/variant"
+require_relative "yamine/worktrees"
 require_relative "yamine/framework"
 require_relative "yamine/config"
 require_relative "yamine/ownership"
@@ -30,6 +31,7 @@ require_relative "yamine/procfile"
 require_relative "yamine/cli/boot"
 require_relative "yamine/cli/routes"
 require_relative "yamine/cli/system"
+require_relative "yamine/cli/worktree"
 require_relative "yamine/cli"
 
 # Stable named .localhost URLs for Ruby development.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -89,6 +89,7 @@ files:
 - lib/yamine/cli/context.rb
 - lib/yamine/cli/routes.rb
 - lib/yamine/cli/system.rb
+- lib/yamine/cli/worktree.rb
 - lib/yamine/command.rb
 - lib/yamine/config.rb
 - lib/yamine/database.rb
@@ -113,6 +114,7 @@ files:
 - lib/yamine/trust.rb
 - lib/yamine/variant.rb
 - lib/yamine/version.rb
+- lib/yamine/worktrees.rb
 homepage: https://github.com/ask-rb/yamine
 licenses:
 - MIT