yamine 0.13.2 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 122503332845c1bbee6034e7262b763d38c2d4c849723e9519dfc7e91f0739b6
-  data.tar.gz: 5ae28759ce2ba01f7c9239056ca49d0ceda6f0958e26a534561fdcab76a485f3
+  metadata.gz: ab7c7e888dc8066ad10a7ed2fa90dcd684b27aa171038ac0ae5ea4c06b22251b
+  data.tar.gz: '097d12693a71cf3969f481fd0f61b3f82e9a09d7958139e32b3fb79a7e667cd8'
 SHA512:
-  metadata.gz: 35f7dc98e1beaa8fcbf46dc2dbb735656789c193d2ed713e395fc038fa9a7801fcec6ea552c3affc67c82f0a3101b3200eb6126459f0588b723245318e257981
-  data.tar.gz: c3f54ddcc3cb3d0f6b99bca81770fc4addd61cadb22baf176c81042b9609edb079b69f2f41dd265378b08c44eb1a322dc00cffca580496741086750671950007
+  metadata.gz: 99ddf961f8fa7e50038cb093b592f692c4c90a94279dc200b9ab7ea9e8a70355e6bf67659bf0cb53aac66d2868d99c6fc138750e490aa1fa4ff5b606bbfacc3f
+  data.tar.gz: 825fb69b730125767e18472ca3d7d615514660b63dbcb7aa63697970f6733b1497997b505a6fde9f1e6b0c62785127fac0d2b1332544ff4d535b4076680623b8

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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

data/README.md

@@ -158,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
@@ -202,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

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yamine
-  VERSION = "0.13.2"
+  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.2
+  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