openlanes 3.0.0 → 3.1.0

data/lib/openlanes/vcs/worktree.rb

@@ -20,11 +20,55 @@ module OpenLanes
     # carries itself from worktree creation through to a merged pull request with
     # nobody having to remember it.
     class Worktree
-      # `bin/setup-worktree`, which copies in the ignored-but-required files a new
-      # checkout does not get. Shelling out rather than reimplementing the rules
-      # here keeps one answer to "what does a worktree need", and keeps that answer
-      # usable from a shell on a machine that has never run `bundle install`.
-      SEEDER = File.expand_path("../../../bin/setup-worktree", __dir__)
+      # `setup-worktree`, which copies in the ignored-but-required files a new
+      # checkout does not get. It is the user's own script, not this gem's:
+      # shelling out rather than reimplementing the rules here keeps one answer
+      # to "what does a worktree need", usable from a shell on a machine that
+      # has never run `bundle install`.
+      SEEDER_NAME = "setup-worktree"
+
+      # Names the seeder outright, ahead of every place {.seeder} searches.
+      SEEDER_ENV = "OPENLANES_SETUP_WORKTREE"
+
+      # Searched after `PATH`, where the user's own tooling keeps it.
+      SEEDER_HOMES = %w[~/.claude/bin ~/.agents/bin].freeze
+
+      class << self
+        # The seeder to run, or nil when none is installed.
+        #
+        # It used to be `bin/setup-worktree` beside this file, which the gem
+        # never shipped, so every installed run seeded nothing and said so
+        # once per agent.
+        #
+        # @param env [Hash] the environment, for `PATH` and {SEEDER_ENV}
+        # @return [String, nil] an executable path
+        def seeder(env = ENV) = seeder_candidates(env).find { File.file?(it) && File.executable?(it) }
+
+        # Every place {.seeder} looks, in order.
+        #
+        # @param env [Hash]
+        # @return [Array<String>]
+        def seeder_candidates(env = ENV)
+          on_path = env.fetch("PATH", "").split(File::PATH_SEPARATOR).reject(&:empty?).map { File.join(it, SEEDER_NAME) }
+          homes = SEEDER_HOMES.map { File.join(File.expand_path(it), SEEDER_NAME) }
+          [env[SEEDER_ENV].to_s, *on_path, *homes].reject(&:empty?).uniq
+        end
+
+        # @return [String] where {.seeder} looks, for a person
+        def seeder_search = "$#{SEEDER_ENV}, #{SEEDER_NAME} on PATH, #{SEEDER_HOMES.join(", ")}"
+
+        # The main checkout of the repository +path+ is in, even when +path+
+        # is itself a worktree. Worktrees live beside the main checkout, so a
+        # command run from inside one and rooted there looks for
+        # `<worktree>.worktrees` and finds nothing.
+        #
+        # @param path [String] any checkout of the repository
+        # @return [String] the main checkout; +path+ when git cannot say
+        def main_root(path)
+          common = `git -C #{path.shellescape} rev-parse --path-format=absolute --git-common-dir 2>/dev/null`.strip
+          common.empty? ? path : File.dirname(common)
+        end
+      end
 
       # One plan's isolated checkout.
       #
@@ -50,9 +94,11 @@ module OpenLanes
       # @param root [String] the main repository
       # @param dir [String, nil] where worktrees go; defaults to a sibling
       # @param user [String] branch namespace
-      def initialize(root:, dir: nil, user: ENV["USER"] || "agent")
+      # @param seeder [String, nil] the seeder to run; nil runs none
+      def initialize(root:, dir: nil, user: ENV["USER"] || "agent", seeder: self.class.seeder)
         @root = File.expand_path(root)
         @user = user
+        @seeder = seeder
         @dir = File.expand_path(dir || default_dir)
       end
 
@@ -103,6 +149,18 @@ module OpenLanes
         Checkout.new(ordinal: feature.ordinal, branch:, path:, created: true)
       end
 
+      # Bring a plan's checkout up to date with the default branch before an
+      # agent runs in it, and say what happened in the progress log.
+      #
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @param hold [String, nil] see {Refresh#call}
+      # @return [OpenLanes::Vcs::Refresh::Outcome]
+      def refresh(checkout, hold: nil)
+        outcome = Refresh.new(path: checkout.path).call(hold:)
+        UI.log(outcome.summary, plan: checkout.ordinal.to_s) unless outcome.kind == :current
+        outcome
+      end
+
       # Copy in the files git ignores and a new checkout therefore lacks: `.env`
       # and friends, and credential keys.
       #
@@ -118,14 +176,16 @@ module OpenLanes
       # @param path [String] the worktree to seed
       # @return [Boolean] whether the seeder ran and succeeded
       def seed(path)
-        unless File.executable?(SEEDER)
-          UI.log("worktree: #{SEEDER} is missing, so #{path} has no .env or credential keys")
+        unless @seeder && File.executable?(@seeder)
+          UI.log("worktree: no #{SEEDER_NAME} found (searched #{self.class.seeder_search}), " \
+                 "so #{path} has no .env or credential keys",
+            level: :warn)
           return false
         end
 
-        return true if system(SEEDER, "--quiet", path, out: File::NULL, err: File::NULL)
+        return true if system(@seeder, "--quiet", path, out: File::NULL, err: File::NULL)
 
-        UI.log("worktree: could not seed #{path}; its suite may fail on a missing key")
+        UI.log("worktree: could not seed #{path}; its suite may fail on a missing key", level: :warn)
         false
       end
 
@@ -164,7 +224,82 @@ module OpenLanes
       #
       # @return [Array<String>] paths removed
       def prune
-        list.select { |path| clean?(path) }.each { |path| remove(path) }
+        list.select { |path| clean?(path) }.select { |path| remove(path) }
+      end
+
+      # @param path [String] a checkout
+      # @return [String] the branch it has checked out; empty when detached
+      def branch_of(path) = `git -C #{path.shellescape} branch --show-current 2>/dev/null`.strip
+
+      # Every checkout of one plan: the one at {#path_for}, and any other
+      # whose folder starts with the same ordinal. A folder-name parse that
+      # once leaked the status into the slug (`018.00-018.00━━🟡━━❯x`) gave a
+      # plan three checkouts, and only the ordinal finds all of them.
+      #
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [Array<String>] absolute paths, as git lists them
+      def checkouts_of(feature)
+        prefix = "#{feature.ordinal}-"
+        list.select { File.basename(it).start_with?(prefix) }
+      end
+
+      # Remove a checkout whose work is on the default branch, and its local
+      # branch with it.
+      #
+      # A merged pull request ends a plan's worktree; left behind, they piled
+      # up to forty-eight in one repository, each looking like work in
+      # progress. Removal cannot be undone for anything that never left the
+      # machine, so every condition below has to hold first, and a refusal
+      # says which one failed and leaves the checkout exactly as it was.
+      #
+      # "On the default branch" is a tree comparison, never `git log
+      # main..branch`: a squash merge rewrites every hash, so that log lists
+      # every commit of a branch that landed whole. A stacked pull request
+      # merged into its parent's branch reports MERGED too, which is why the
+      # base is checked.
+      #
+      # @param path [String] a checkout from {#list}
+      # @param merge_commit [String] the commit the pull request merged as
+      # @param base [String] the branch the pull request merged into
+      # @param default_branch [String]
+      # @param held [#call, nil] path -> who holds a lock in it, or nil
+      # @param dry_run [Boolean] check everything, remove nothing
+      # @return [Retirement]
+      def retire(path, merge_commit:, base:, default_branch: Refresh.default_branch(root), held: nil, dry_run: false)
+        branch = branch_of(path)
+        sha = `git -C #{path.shellescape} rev-parse HEAD 2>/dev/null`.strip
+        refusal = retire_refusal(path, sha, merge_commit, base, default_branch, held)
+        return Retirement.new(path:, branch:, sha:, removed: false, reason: refusal) if refusal
+        return Retirement.new(path:, branch:, sha:, removed: false, reason: "would be removed: landed in #{merge_commit[0, 8]}") if dry_run
+        return Retirement.new(path:, branch:, sha:, removed: false, reason: "git refused to remove it") unless remove(path)
+
+        # -D, not -d: a squash-merged branch looks unmerged to -d. The tree
+        # comparison above is the check that makes this safe.
+        system("git", "-C", root, "branch", "-D", branch, out: File::NULL, err: File::NULL) unless branch.empty?
+        Retirement.new(path:, branch:, sha:, removed: true, reason: "landed in #{merge_commit[0, 8]}")
+      end
+
+      # What {#retire} did with one checkout.
+      #
+      # @!attribute [r] path
+      #   @return [String]
+      # @!attribute [r] branch
+      #   @return [String] empty for a detached checkout
+      # @!attribute [r] sha
+      #   @return [String] the branch's last commit, so it can be restored
+      # @!attribute [r] removed
+      #   @return [Boolean]
+      # @!attribute [r] reason
+      #   @return [String] why it was removed, or why not
+      Retirement = Data.define(:path, :branch, :sha, :removed, :reason) do
+        # @return [Boolean]
+        def removed? = removed
+
+        # @return [String] one line for the progress log
+        def to_s
+          name = File.basename(path)
+          removed? ? "worktree #{name} removed (#{branch} was #{sha[0, 8]}): #{reason}" : "worktree #{name} kept: #{reason}"
+        end
       end
 
       # Where one plan's checkout lives, whether or not it has been made.
@@ -207,10 +342,14 @@ module OpenLanes
         true
       end
 
+      # Never `--force`: git refuses a checkout with uncommitted or untracked
+      # work, and that refusal is the last guard against deleting it.
+      # Ignored files, the seeded `.env` among them, do not count.
+      #
       # @param path [String]
-      # @return [void]
+      # @return [Boolean] whether git removed it
       def remove(path)
-        system("git", "-C", root, "worktree", "remove", "--force", path, out: File::NULL, err: File::NULL)
+        system("git", "-C", root, "worktree", "remove", path, out: File::NULL, err: File::NULL)
       end
 
       private
@@ -232,12 +371,69 @@ module OpenLanes
       # @return [Boolean]
       def clean?(path) = `git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
 
+      # The first reason {#retire} must not remove a checkout, or nil.
+      #
+      # @return [String, nil]
+      def retire_refusal(path, sha, merge_commit, base, default_branch, held)
+        return "not a worktree openlanes manages" unless managed?(path)
+        return "its pull request merged into #{base}, not #{default_branch}" unless base == default_branch
+        return "it has uncommitted changes" unless clean?(path)
+
+        holder = held&.call(path)
+        return "#{holder} holds a lock in it" if holder
+        return "merge commit #{merge_commit[0, 8]} is not in this repository, even after a fetch" unless commit?(merge_commit)
+
+        "its branch has work that is not in #{merge_commit[0, 8]}" unless landed?(sha, merge_commit)
+      end
+
+      # @param path [String]
+      # @return [Boolean] one of {#list}, and not the main checkout
+      def managed?(path)
+        here = canonical(path)
+        here != canonical(root) && list.any? { canonical(it) == here }
+      end
+
+      # Present locally, fetching once if not: the engine merged it a moment
+      # ago on GitHub, and nothing has fetched since.
+      #
+      # @param sha [String]
+      # @return [Boolean]
+      def commit?(sha)
+        known = -> { system("git", "-C", root, "cat-file", "-e", "#{sha}^{commit}", out: File::NULL, err: File::NULL) }
+        known.call || (system("git", "-C", root, "fetch", "--quiet", "origin", out: File::NULL, err: File::NULL) && known.call)
+      end
+
+      # The branch tip's tree is the merge commit's, or every file the branch
+      # changed reads the same in the merge commit. The second covers a
+      # default branch that moved on before the merge.
+      #
+      # @param sha [String] the branch tip
+      # @param merge_commit [String]
+      # @return [Boolean]
+      def landed?(sha, merge_commit)
+        tree = ->(ref) { `git -C #{root.shellescape} rev-parse #{"#{ref}^{tree}".shellescape} 2>/dev/null`.strip }
+        return true if tree.call(sha) == tree.call(merge_commit)
+
+        fork = `git -C #{root.shellescape} merge-base #{sha.shellescape} #{merge_commit.shellescape} 2>/dev/null`.strip
+        return false if fork.empty?
+
+        files = `git -C #{root.shellescape} diff --name-only #{fork.shellescape} #{sha.shellescape} 2>/dev/null`.lines(chomp: true)
+        files.empty? || system("git", "-C", root, "diff", "--quiet", sha, merge_commit, "--", *files, out: File::NULL, err: File::NULL)
+      end
+
+      # A new branch starts from the freshly fetched default branch on
+      # `origin`, not from whatever the main checkout has checked out: that
+      # is often a branch of its own, or a `main` nobody has pulled in weeks,
+      # and the plan's agent then builds against code that is not there.
+      # Without such a remote branch it falls back to the main checkout's
+      # HEAD, as it always did.
+      #
       # @param branch [String]
       # @param path [String]
       # @return [void]
       def add(branch, path)
         exists = system("git", "-C", root, "show-ref", "--verify", "--quiet", "refs/heads/#{branch}")
-        args = exists ? ["worktree", "add", path, branch] : ["worktree", "add", "-b", branch, path]
+        args = exists ? ["worktree", "add", path, branch] : ["worktree", "add", "-b", branch, path, *Refresh.fetch(root)]
 
         return if system("git", "-C", root, *args, out: File::NULL, err: File::NULL)
 

data/lib/openlanes/vcs.rb

@@ -15,5 +15,23 @@ module OpenLanes
 
     # @return [OpenLanes::Vcs::Publisher]
     def publisher(**) = Publisher.new(**)
+
+    # @param github [OpenLanes::Vcs::GitHub]
+    # @return [OpenLanes::Vcs::Review]
+    def review(github: GitHub.new) = Review.new(github:)
+
+    # @param root [String, nil] the checkout whose repository is synced; nil
+    #   means the current directory's
+    # @param github [OpenLanes::Vcs::GitHub]
+    # @return [OpenLanes::Vcs::LabelSync]
+    def label_sync(root: nil, github: GitHub.new(chdir: root)) = LabelSync.new(github:)
+
+    # Run before {label_sync}, once per repository: the repository's
+    # {Plans::ReviewLabel::MIGRATED} label marks it done.
+    #
+    # @param root [String, nil] as for {label_sync}
+    # @param github [OpenLanes::Vcs::GitHub]
+    # @return [OpenLanes::Vcs::LabelMigration]
+    def label_migration(root: nil, github: GitHub.new(chdir: root)) = LabelMigration.new(github:)
   end
 end

data/lib/openlanes/version.rb

@@ -6,5 +6,5 @@
 #
 # © 2026 Konstantin Gredeskoul
 module OpenLanes
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

data/lib/openlanes/web/admin_auth.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "rack/auth/basic"
+require "rack/utils"
+
+module OpenLanes
+  module Web
+    # Basic auth for every request from off this machine. The page can stop
+    # agents, answer their questions and message them, so a server listening
+    # past loopback is refused unless it is given credentials
+    # (`--admin-credentials`), and this asks for them.
+    #
+    # A request from loopback passes untouched: it already reached the
+    # machine, the browser `openlanes start` opens is on it, and so is the
+    # launcher's `/healthz` probe.
+    #
+    #   use AdminAuth, credentials: AdminAuth::Credentials.parse("admin:s3cret")
+    class AdminAuth
+      # Where `openlanes run` hands its server the credentials. argv is
+      # world-readable through `ps`; a child's environment is not.
+      ENV_NAME = "OPENLANES_ADMIN_CREDENTIALS"
+
+      # What the browser's login prompt names.
+      REALM = "openlanes control room"
+
+      # Raised for credentials that are not `USER:PASSWORD`.
+      class Invalid < OpenLanes::Error; end
+
+      # One user and one password. The password may itself hold a colon;
+      # the user may not, since Basic auth splits at the first one.
+      Credentials = Data.define(:user, :password) do
+        # @param user [String]
+        # @param password [String]
+        # @return [Boolean] whether both match, compared in constant time
+        def match?(user, password)
+          # Both compared, always, so the time taken says nothing about
+          # which of the two was wrong.
+          [Rack::Utils.secure_compare(self.user, user.to_s),
+           Rack::Utils.secure_compare(self.password, password.to_s)].all?
+        end
+
+        # Never the password, so a credential that reaches a log or an
+        # exception message leaks nothing.
+        #
+        # @return [String]
+        def inspect = "#<#{self.class.name} user=#{user.inspect}>"
+        alias_method :to_s, :inspect
+      end
+
+      class << self
+        # @param text [String] `USER:PASSWORD`
+        # @return [Credentials]
+        # @raise [Invalid] when either half is missing
+        def parse(text)
+          user, password = text.to_s.split(":", 2)
+          unless user.to_s.strip.empty? || password.to_s.empty?
+            return Credentials.new(user: user.strip, password:)
+          end
+
+          raise Invalid, "takes USER:PASSWORD, both non-empty"
+        end
+
+        # @param address [String, nil] `REMOTE_ADDR`
+        # @return [Boolean] whether it is this machine, IPv4-mapped IPv6 included
+        def loopback?(address)
+          ip = IPAddr.new(address.to_s)
+          ip = ip.native if ip.ipv4_mapped?
+          ip.loopback?
+        rescue IPAddr::Error
+          false
+        end
+      end
+
+      # @param app [#call]
+      # @param credentials [Credentials]
+      def initialize(app, credentials:)
+        @app = app
+        @credentials = credentials
+      end
+
+      # @param env [Hash] the Rack environment
+      # @return [Array] the Rack response
+      def call(env)
+        return @app.call(env) if self.class.loopback?(env["REMOTE_ADDR"])
+
+        auth = Rack::Auth::Basic::Request.new(env)
+        return challenge unless auth.provided? && auth.basic? && @credentials.match?(*auth.credentials)
+
+        env["REMOTE_USER"] = auth.username
+        @app.call(env)
+      end
+
+      private
+
+      # @return [Array] a 401 the browser answers with its login prompt
+      def challenge
+        [401,
+         { "content-type" => "text/plain", "content-length" => "0", "www-authenticate" => %(Basic realm="#{REALM}") },
+         []]
+      end
+    end
+  end
+end