openlanes 3.0.1 → 3.1.0

data/lib/openlanes/vcs/rename_date.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "open3"
+
+module OpenLanes
+  module Vcs
+    # The date a plan reached the state that sends it into an inactive
+    # subfolder, for the `[YYYY-MM-DD]` its archived name carries (N3).
+    #
+    # A state change is a folder rename, so the date of the folder's latest
+    # rename is the date it got there. Git knows it, through a file inside the
+    # folder: `--follow --diff-filter=R` returns the rename itself, where
+    # `git log -1 -- <folder>` returns whichever edit came last, and a spec
+    # touched up a month after the merge would date the archive by the edit.
+    #
+    # Git does not always know. The folder may never have been committed, the
+    # clone may be shallow, or the tree may not be a repository at all; then
+    # `state.json`'s `updated_at`, which the harness writes on every state
+    # change, and failing that, today.
+    module RenameDate
+      # Files tried first; a folder holding none of them (a ❌ plan may hold
+      # only `discarded.md`) is followed through whichever file it does hold.
+      PROBES = %w[spec.md plan.md pull-requests.md].freeze
+
+      class << self
+        # @param dir [String] a plan folder
+        # @param today [Date] the last resort
+        # @return [Date]
+        def for(dir, today: Date.today) = from_git(dir) || from_state(dir) || today
+
+        private
+
+        # @param dir [String]
+        # @return [Date, nil]
+        def from_git(dir)
+          probe = probe_in(dir) or return nil
+
+          out, status = Open3.capture2("git",
+            "-C",
+            dir,
+            "log",
+            "--follow",
+            "--diff-filter=R",
+            "--format=%cI",
+            "-1",
+            "--",
+            probe,
+            err: File::NULL)
+          status.success? ? parse(out.strip) : nil
+        rescue SystemCallError
+          nil
+        end
+
+        # @param dir [String]
+        # @return [String, nil] a file name inside +dir+
+        def probe_in(dir)
+          PROBES.find { File.file?(File.join(dir, it)) } ||
+            Dir.children(dir).sort.find { File.file?(File.join(dir, it)) && it != Plans::Lock::FILENAME }
+        end
+
+        # @param dir [String]
+        # @return [Date, nil]
+        def from_state(dir)
+          parse(JSON.parse(File.read(File.join(dir, Plans::PlanState::FILENAME)))["updated_at"])
+        rescue SystemCallError, JSON::ParserError, TypeError
+          nil
+        end
+
+        # @param text [String, nil] an ISO-8601 timestamp
+        # @return [Date, nil]
+        def parse(text)
+          return nil if text.to_s.empty?
+
+          Date.iso8601(text.to_s[0, 10])
+        rescue Date::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/vcs/review.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Vcs
+    # Moves a pull request from one review label to the next (M3, R3).
+    #
+    # The only way a review label is set: `gh pr edit` stays forbidden to
+    # agents (L3), so the CI rule below cannot be skipped by labelling by hand
+    # from inside a round.
+    class Review
+      # What happened, or under a dry run what would have.
+      Result = Data.define(:pr, :from, :to, :ci, :refused, :reason, :dry_run) do
+        alias_method :refused?, :refused
+        alias_method :dry_run?, :dry_run
+      end
+
+      # @param github [GitHub]
+      def initialize(github: GitHub.new)
+        @github = github
+      end
+
+      # @param pr [String, Integer] "12", "#12" or a pull request URL
+      # @param label [String] a {Plans::ReviewLabel} name
+      # @param dry_run [Boolean] compute the result, write nothing
+      # @return [Result]
+      # @raise [OpenLanes::Error] on an unknown label or a reference naming no
+      #   pull request, before any `gh` call
+      def call(pr:, label:, dry_run: false) # rubocop:disable Naming/MethodParameterName -- `pr` is the contract with CLI::Review
+        to = Plans::ReviewLabel.fetch(label)
+        number = GitHub.number_of(pr)
+        repo = GitHub.repo_of(pr)
+
+        from = @github.labels(number:, repo:) & Plans::ReviewLabel.known
+        ci = CiGate.verdict(@github.checks(number:, repo:))
+        reason = refusal(to, ci)
+        result = Result.new(pr: number,
+          from:,
+          to: to.name,
+          ci:,
+          refused: !reason.nil?,
+          reason: reason || (ci == :none ? NO_CHECKS : nil),
+          dry_run:)
+        return result if result.refused? || dry_run
+
+        @github.swap_label(number:, repo:, add: to, remove: from & Plans::ReviewLabel.displaced_by(to))
+        result
+      end
+
+      # Zero checks, or only skipped ones, counts as green (open question 2),
+      # said out loud.
+      NO_CHECKS = "no CI checks ran; treated as green"
+
+      private
+
+      # @return [String, nil] why `to` may not be set now
+      def refusal(label, verdict)
+        return unless label.passing?
+
+        case verdict
+        when :red then "CI is red"
+        when :pending then "CI pending"
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/vcs/worktree.rb

@@ -56,6 +56,18 @@ module OpenLanes
 
         # @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.
@@ -137,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.
       #
@@ -154,13 +178,14 @@ module OpenLanes
       def seed(path)
         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")
+                 "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)
 
-        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
 
@@ -199,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.
@@ -242,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
@@ -267,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.1"
+  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