openlanes 3.0.0

data/lib/openlanes/vcs/github.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+require "tty/command"
+
+module OpenLanes
+  module Vcs
+    # The `gh` CLI, wrapped thinly.
+    #
+    # It is a seam rather than a convenience: every example in the suite injects
+    # a double here, so nothing in the tests reaches the network or a real
+    # repository.
+    class GitHub
+      # Fields asked of `gh pr list`.
+      FIELDS = %w[number title url headRefName files state isDraft mergedAt].freeze
+
+      # @param command [TTY::Command] runner, injectable for tests
+      # @param limit [Integer] how many pull requests to fetch
+      def initialize(command: TTY::Command.new(printer: :null), limit: 200)
+        @command = command
+        @limit = limit
+      end
+
+      # Every pull request, normalised into plain hashes.
+      #
+      # @param state [String] "open", "closed", "merged" or "all"
+      # @return [Array<Hash>] `{number:, title:, url:, branch:, files:}`
+      def pulls(state: "all")
+        out = UI.spinning("Fetching pull requests from GitHub") {
+          @command.run("gh",
+            "pr",
+            "list",
+            "--state",
+            state,
+            "--limit",
+            @limit.to_s,
+            "--json",
+            FIELDS.join(",")).out
+        }
+
+        # `gh` can exit 0 having printed NOTHING — most often when it cannot reach
+        # the credential store, as in a non-interactive shell that has no keyring
+        # access, or when GH_TOKEN is set to something invalid and shadows a
+        # working login. Left alone this parses as a JSON error and reports as
+        # "bad output", sending you to look at the wrong thing entirely.
+        raise Error, no_output_message if out.to_s.strip.empty?
+
+        JSON.parse(out).map do |pr|
+          {
+            number: pr["number"],
+            title:  pr["title"].to_s,
+            url:    pr["url"],
+            branch: pr["headRefName"].to_s,
+            files:  Array(pr["files"]).map { |f| f["path"] }.compact,
+            state:  self.class.state_label(pr),
+            open:   pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN"
+          }
+        end
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not list pull requests via `gh`: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # @return [String] the diagnosis for a silent `gh`
+      def no_output_message
+        <<~MESSAGE.strip
+          `gh` produced no output and did not report an error.
+
+          That is almost always authentication rather than an empty repository:
+
+            - Check `gh auth status`. An invalid GH_TOKEN in the environment
+              shadows a working keyring login and fails without saying so.
+
+            - A non-interactive shell may have no access to the system keyring
+              even when an interactive one does.
+
+          Verify with: gh pr list --state all --limit 1
+        MESSAGE
+      end
+
+      # Fields asked of `gh pr view`, which unlike `pr list` can be told about
+      # one pull request in another repository.
+      VIEW_FIELDS = %w[number title url headRefName state isDraft mergedAt body].freeze
+
+      # A reference to one pull request: a bare number, a `#`-prefixed number,
+      # or a full URL to a GitHub pull request or a GitLab merge request.
+      REF = %r{\A(?:\#?\d+|https?://\S+?/(?:pull|merge_requests)/\d+/?)\z}
+
+      # Split and validate a `--prs` value before any of it reaches the network,
+      # so a typo fails in a hundredth of a second with the offending token named
+      # rather than after four round trips with a `gh` diagnostic.
+      #
+      # @param text [String] e.g. "12,15,18" or "https://…/pull/12, #15"
+      # @return [Array<String>] references, in the order given, de-duplicated
+      # @raise [OpenLanes::Error] on anything that is not a reference
+      def self.parse_refs(text)
+        refs = text.to_s.split(",").map(&:strip).reject(&:empty?)
+        raise Error, "no pull requests given" if refs.empty?
+
+        bad = refs.reject { |r| r.match?(REF) }
+        unless bad.empty?
+          raise Error, "not a pull request number or URL: #{bad.join(", ")}"
+        end
+
+        refs.uniq
+      end
+
+      # One pull request, by number or URL.
+      #
+      # @param ref [String] "12", "#12" or "https://github.com/o/r/pull/12"
+      # @return [Hash] `{number:, title:, url:, branch:, state:, body:}`
+      # @raise [OpenLanes::Error]
+      def pull_request(ref)
+        out = @command.run("gh", "pr", "view", ref.to_s, "--json", VIEW_FIELDS.join(",")).out
+        raise Error, no_output_message if out.to_s.strip.empty?
+
+        pr = JSON.parse(out)
+        {
+          number: pr["number"],
+          title:  pr["title"].to_s,
+          url:    pr["url"].to_s,
+          branch: pr["headRefName"].to_s,
+          state:  self.class.state_label(pr),
+          body:   pr["body"].to_s
+        }
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not read pull request #{ref}: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # Several pull requests, in the order asked for.
+      #
+      # @param refs [Array<String>]
+      # @return [Array<Hash>]
+      def pull_requests(refs)
+        UI.stepping(refs, "Fetching pull requests") { |ref| ref }
+        refs.map { |ref| pull_request(ref) }
+      end
+
+      # `gh` speaks in enums; `pull-requests.md` speaks in the words the state
+      # machine parses. Translate once, here, rather than at each call site.
+      #
+      # @param pr [Hash] a decoded `gh pr view` payload
+      # @return [String] one of the labels in {PullRequests::STATES}
+      def self.state_label(pr)
+        return "Merged 🟣" if pr["mergedAt"]
+        return "WIP 🟡" if pr["isDraft"]
+
+        case pr["state"].to_s.upcase
+        when "OPEN" then "Open 🟡"
+        when "CLOSED" then "Closed 🔴"
+        else "Unknown"
+        end
+      end
+
+      # Change a pull request's title.
+      #
+      # @param number [Integer]
+      # @param title [String]
+      # @return [void]
+      def retitle(number:, title:)
+        @command.run("gh", "pr", "edit", number.to_s, "--title", title)
+      rescue TTY::Command::ExitError => e
+        raise Error, "could not retitle ##{number}: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # @return [Boolean] whether `gh` is installed and authenticated
+      def available?
+        @command.run!("gh", "auth", "status").success?
+      end
+    end
+  end
+end

data/lib/openlanes/vcs/publisher.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "tty/command"
+
+module OpenLanes
+  module Vcs
+    # Turns a finished worktree into a pushed branch and a pull request.
+    #
+    # This is the one place the harness reaches off the machine, so it does
+    # nothing under `--dry-run`, is skipped with `--no-git-push`, and refuses anything
+    # it is not certain about. Everything it does is reported before it does it.
+    #
+    # Titles follow the convention the whole system joins on:
+    #
+    #     [002.00](A) Tenancy Households       — a plan's first pull request
+    #     [002.00](B) Tenancy Households       — its second
+    #
+    # The slug is title-cased from the folder name, so the title reads as a
+    # sentence rather than as a path fragment.
+    class Publisher
+      # A published, or publishable, pull request.
+      #
+      # @!attribute [r] ordinal
+      #   @return [OpenLanes::Plans::Ordinal]
+      # @!attribute [r] branch
+      #   @return [String]
+      # @!attribute [r] title
+      #   @return [String]
+      # @!attribute [r] url
+      #   @return [String, nil] nil on a dry run or a refusal
+      # @!attribute [r] refusal
+      #   @return [String, nil]
+      # @!attribute [r] updated
+      #   @return [Boolean] whether the push went to a pull request the plan
+      #     already had open, rather than opening a new one
+      Publication = Data.define(:ordinal, :branch, :title, :url, :refusal, :updated) do
+        def initialize(updated: false, **rest) = super
+
+        # @return [Boolean]
+        def published? = !url.nil?
+      end
+
+      # A..Z, which is more parts than any feature should be split into.
+      LETTERS = ("A".."Z").to_a.freeze
+
+      # @param root [String] repository the worktree belongs to
+      # @param command [TTY::Command]
+      # @param base [String] the branch pull requests target
+      # @param dry_run [Boolean]
+      # @param github [OpenLanes::Vcs::GitHub] asked which branch an open pull
+      #   request is built from
+      def initialize(root:, command: TTY::Command.new(printer: :null), base: "main", dry_run: true, github: GitHub.new)
+        @root = root
+        @command = command
+        @github = github
+        @base = base
+        @dry_run = dry_run
+      end
+
+      # Push one plan's branch and open its pull request, or, when the plan
+      # already has one open, push to it.
+      #
+      # A re-build after 🔴 Changes Requested is the second case. Its branch
+      # already carries the open pull request the reviewer asked changes of,
+      # and `gh pr create` on that branch fails ("a pull request for branch
+      # ... already exists") after the push has gone through, so the fixes
+      # reached the pull request and the run reported a refusal. One branch per
+      # plan means at most one open pull request per plan, so the open row in
+      # `pull-requests.md` is the one to push to.
+      #
+      # Only if that pull request is built from this checkout's branch, though.
+      # `pull-requests.md` does not record the head branch, and an adopted or
+      # hand-opened pull request can come from any branch at all; pushing the
+      # worktree branch then reaches no pull request while reporting one as
+      # updated. So the head is asked of GitHub first, and anything other than
+      # the checkout's own branch, or no answer, is a refusal.
+      #
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param letter [String, nil] force a part letter; nil auto-assigns
+      # @return [OpenLanes::Vcs::Publisher::Publication]
+      def publish(checkout:, subject:, letter: nil)
+        open = subject.pull_requests.select(&:open?).last
+        title = open&.title || title_for(subject, letter)
+
+        unless checkout.dirty?
+          return refuse(subject, checkout, title, "nothing to publish — the worktree is unchanged")
+        end
+
+        return Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: nil) if @dry_run
+
+        mismatch = open && head_mismatch(open, checkout)
+        return refuse(subject, checkout, title, mismatch) if mismatch
+
+        commit(checkout, title)
+        push(checkout)
+        url = open ? open.url : create_pull_request(checkout, subject, title)
+
+        Publication.new(**base_fields(subject, checkout, title), url:, refusal: nil, updated: !open.nil?)
+      rescue TTY::Command::ExitError => e
+        refuse(subject, checkout, title, git_complaint(e))
+      end
+
+      # git and gh put the useful sentence in stderr, several lines below the
+      # command they echo. Reporting only the first line reports "it failed".
+      #
+      # @param error [TTY::Command::ExitError]
+      # @return [String]
+      def git_complaint(error)
+        lines = error.message.lines.map(&:strip).reject(&:empty?)
+        stderr = lines.find { |l| l.start_with?("stderr:") }
+        complaint = stderr&.delete_prefix("stderr:")&.strip
+
+        complaint.to_s.empty? || complaint == "Nothing written" ? lines.first.to_s : complaint
+      end
+
+      # The title a plan's next pull request should carry.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param letter [String, nil]
+      # @return [String]
+      def title_for(subject, letter = nil)
+        "[#{subject.feature.ordinal}](#{letter || auto_letter(subject)}) #{subject.feature.title}"
+      end
+
+      # Which part this is. Always a letter, starting at A: a plan that turns out
+      # to need only one pull request still reads consistently with every other,
+      # and nothing has to be renamed when a second arrives.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def auto_letter(subject) = LETTERS.fetch(subject.pull_requests.size, LETTERS.last)
+
+      private
+
+      # Why the open pull request cannot receive this checkout's push, if it
+      # cannot.
+      #
+      # @param open [OpenLanes::Plans::PullRequest]
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @return [String, nil] nil when the pull request is built from the checkout's branch
+      def head_mismatch(open, checkout)
+        head = @github.pull_request(open.number || open.url).fetch(:branch)
+        return if head == checkout.branch
+
+        "publish refused — ##{open.number} is built from #{head.empty? ? "an unknown branch" : head}, " \
+          "not #{checkout.branch}, so a push would not reach it"
+      rescue Error => e
+        "publish refused — could not tell which branch ##{open.number} is built from: #{e.message}"
+      end
+
+      # @return [Hash]
+      def base_fields(subject, checkout, title)
+        { ordinal: subject.feature.ordinal, branch: checkout.branch, title: }
+      end
+
+      # @return [OpenLanes::Vcs::Publisher::Publication]
+      def refuse(subject, checkout, title, why)
+        Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: why)
+      end
+
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @param title [String]
+      # @return [void]
+      def commit(checkout, title)
+        run(checkout, "git", "add", "-A")
+        # The subject line drops the bracketed prefix: it belongs in the pull
+        # request title, where things join on it, not in every commit message.
+        run(checkout, "git", "commit", "-m", title.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
+      end
+
+      # @param checkout [OpenLanes::Vcs::Worktree::Checkout]
+      # @return [void]
+      def push(checkout) = run(checkout, "git", "push", "-u", "origin", checkout.branch)
+
+      # @return [String, nil] the pull request URL
+      def create_pull_request(checkout, subject, title)
+        Tempfile.create(["pr", ".md"]) do |file|
+          file.write(description(subject, title))
+          file.flush
+          result = run(checkout, "gh", "pr", "create", "-a", "@me", "-B", @base, "-t", title, "-F", file.path)
+          return result.out.to_s[%r{https://\S+}]
+        end
+      end
+
+      # The body `/create-pr` would have written: a title line, a summary lifted
+      # from the specification, and a link back to the plan folder so a reviewer
+      # can find the rest.
+      #
+      # @return [String]
+      def description(subject, title)
+        <<~MARKDOWN
+          # #{title}
+
+          ## Summary
+
+          #{summary_text(subject)}
+
+          ## Plan
+
+          Implements `#{subject.feature.dirname}`. The specification and the plan
+          for this work live in that folder.
+        MARKDOWN
+      end
+
+      # The specification's own Goal section, verbatim. A pull request body that
+      # paraphrases the spec is a second copy that drifts; quoting it is not.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [String]
+      def summary_text(subject)
+        text = subject.goal.join("\n\n")
+        text.empty? ? "See `#{subject.feature.dirname}/spec.md`." : text
+      end
+
+      # @return [TTY::Command::Result]
+      def run(checkout, *argv) = @command.run(*argv, chdir: checkout.path)
+    end
+  end
+end

data/lib/openlanes/vcs/worktree.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "shellwords"
+
+module OpenLanes
+  module Vcs
+    # A git worktree per plan, so agents working on different plans cannot
+    # collide at all.
+    #
+    # A lock coordinates a shared tree; a worktree removes the sharing. That
+    # matters more than it sounds for an agent loop: two agents editing one
+    # checkout produce no git conflict — same branch, same files — so the last
+    # writer simply wins and the loser's work vanishes with nothing anywhere to
+    # say it happened.
+    #
+    # The branch carries the plan number (`<user>/NNN.MM-slug`), which is not
+    # decoration: it is the first thing `resync prs` reads when deciding which
+    # plan a pull request implements. Naming branches this way means the number
+    # 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__)
+
+      # One plan's isolated checkout.
+      #
+      # @!attribute [r] ordinal
+      #   @return [OpenLanes::Plans::Ordinal]
+      # @!attribute [r] branch
+      #   @return [String]
+      # @!attribute [r] path
+      #   @return [String] absolute
+      # @!attribute [r] created
+      #   @return [Boolean] false when an existing worktree was reused
+      Checkout = Data.define(:ordinal, :branch, :path, :created) do
+        # @return [Boolean] whether the agent left anything behind
+        def dirty? = !`git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
+
+        # @return [String] the plans directory inside this checkout
+        def plans_dir = File.join(path, OpenLanes::PLANS_DIR)
+
+        # @return [Boolean] whether this round made it, rather than reusing one
+        def created? = created
+      end
+
+      # @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")
+        @root = File.expand_path(root)
+        @user = user
+        @dir = File.expand_path(dir || default_dir)
+      end
+
+      # @return [String] the main repository
+      attr_reader :root
+
+      # @return [String] where worktrees are kept
+      attr_reader :dir
+
+      # @return [Boolean] whether root is a git repository at all
+      def repository? = system("git", "-C", root, "rev-parse", "--git-dir", out: File::NULL, err: File::NULL)
+
+      # Get, or create, the isolated checkout for one plan.
+      #
+      # The checkout is seeded before it is handed back, on both paths. `git
+      # worktree add` brings every TRACKED file and nothing else, so an agent
+      # given a bare one cannot run the suite it was told to keep green: a Rails
+      # project dies on `MissingKeyError` because `config/credentials/*.key` is
+      # gitignored. The agent then reports a broken checkout as a broken plan,
+      # which is the worst failure this loop has, because the diagnosis points
+      # at the code rather than at the tree.
+      #
+      # A reused worktree is seeded too. {#seed} only ever adds a missing file,
+      # so running it again costs one fast subprocess and repairs the worktrees
+      # that were created before any of this existed.
+      #
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [OpenLanes::Vcs::Worktree::Checkout]
+      # @raise [OpenLanes::Error] when git refuses
+      def checkout_for(feature)
+        branch = branch_for(feature)
+        path = path_for(feature)
+
+        if File.directory?(path)
+          seed(path)
+          return Checkout.new(ordinal: feature.ordinal, branch:, path:, created: false)
+        end
+
+        # git keeps a registration for a worktree whose directory was deleted by
+        # hand, marks it `prunable`, and then refuses to create a new one at that
+        # path. Anybody who has ever `rm -rf`d a worktree meets this, and the
+        # error says only "already exists" about a directory that does not.
+        forget_stale
+
+        FileUtils.mkdir_p(dir)
+        add(branch, path)
+        seed(path)
+        Checkout.new(ordinal: feature.ordinal, branch:, path:, created: true)
+      end
+
+      # Copy in the files git ignores and a new checkout therefore lacks: `.env`
+      # and friends, and credential keys.
+      #
+      # Never fatal. A repository with no ignored files is perfectly normal, and
+      # a plan is not worth abandoning over a seeding step, so this notes it and
+      # carries on.
+      #
+      # The note goes to the progress log, never the terminal: this runs while
+      # agents' spinner lines are live on STDERR, and a stray line lands in the
+      # middle of them. The seeder's own output is silenced for the same reason. A suite that later dies on a missing key is explained
+      # by the log line.
+      #
+      # @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")
+          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")
+        false
+      end
+
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [String] e.g. "kig/002.00-tenancy-households"
+      def branch_for(feature) = "#{@user}/#{feature.ordinal}-#{feature.slug}"
+
+      # Every worktree this class manages, as git sees them.
+      #
+      # @return [Array<String>] absolute paths
+      def list
+        # Compare canonical paths. git reports resolved ones, and on macOS the
+        # temp and home trees run through symlinks (/var -> /private/var), so a
+        # raw string compare matches nothing and prune silently does nothing.
+        mine = canonical(dir)
+
+        `git -C #{root.shellescape} worktree list --porcelain 2>/dev/null`
+          .lines(chomp: true)
+          .filter_map { |l| l.delete_prefix("worktree ") if l.start_with?("worktree ") }
+          .select { |p| canonical(p).start_with?(mine) }
+      end
+
+      # @param path [String]
+      # @return [String] the symlink-resolved path, or the input when it is gone
+      def canonical(path)
+        File.realpath(path)
+      rescue Errno::ENOENT
+        path
+      end
+
+      # Remove worktrees the agents left untouched.
+      #
+      # An agent that ran and changed nothing has produced a checkout that is
+      # pure cost: it looks like work in progress and is not. Dirty ones are
+      # always kept — that is the output.
+      #
+      # @return [Array<String>] paths removed
+      def prune
+        list.select { |path| clean?(path) }.each { |path| remove(path) }
+      end
+
+      # Where one plan's checkout lives, whether or not it has been made.
+      #
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [String]
+      def path_for(feature) = File.join(dir, "#{feature.ordinal}-#{feature.slug}")
+
+      # Throw away what has not been committed in one plan's checkout: every
+      # change to a tracked file, and every untracked file that is not
+      # ignored, so the seeded `.env` and keys stay. This is the reset behind
+      # a person's discard (W9). Agents never commit, so everything a round
+      # did is uncommitted, and the branch's own last commit is the base it
+      # started from; going further back would drop work already published
+      # behind an open pull request.
+      #
+      # It only ever runs inside a worktree this class manages. The main
+      # checkout, or a directory git does not list as one of these
+      # worktrees, is refused, because `reset --hard` there would take a
+      # person's own work with it.
+      #
+      # @param feature [OpenLanes::Plans::Feature]
+      # @return [Boolean] false when the plan has no checkout, so nothing to reset
+      # @raise [OpenLanes::Error] when the path is not one of these worktrees,
+      #   or git refuses
+      def reset(feature)
+        path = path_for(feature)
+        return false unless File.directory?(path)
+
+        mine = list.map { canonical(it) }
+        unless mine.include?(canonical(path)) && canonical(path) != canonical(root)
+          raise Error, "#{path} is not a worktree openlanes made, so it is not reset"
+        end
+
+        [%w[reset --hard --quiet], %w[clean -fd --quiet]].each do |args|
+          next if system("git", "-C", path, *args, out: File::NULL, err: File::NULL)
+
+          raise Error, "git #{args.first} failed in #{path}"
+        end
+        true
+      end
+
+      # @param path [String]
+      # @return [void]
+      def remove(path)
+        system("git", "-C", root, "worktree", "remove", "--force", path, out: File::NULL, err: File::NULL)
+      end
+
+      private
+
+      # Sibling of the repository, not inside it: a worktree under the repo shows
+      # up in its own `git status` and in every glob anybody writes.
+      #
+      # @return [String]
+      def default_dir = "#{@root}.worktrees"
+
+      # Drop registrations whose directory is gone.
+      #
+      # @return [void]
+      def forget_stale
+        system("git", "-C", root, "worktree", "prune", out: File::NULL, err: File::NULL)
+      end
+
+      # @param path [String]
+      # @return [Boolean]
+      def clean?(path) = `git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
+
+      # @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]
+
+        return if system("git", "-C", root, *args, out: File::NULL, err: File::NULL)
+
+        raise Error, "could not create a worktree for #{branch} at #{path}"
+      end
+    end
+  end
+end

data/lib/openlanes/vcs.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # Git and GitHub: a checkout per plan, pushing a branch, and reading
+  # pull requests. Everything that leaves the machine leaves through here.
+  module Vcs
+    module_function
+
+    # @return [OpenLanes::Vcs::GitHub]
+    def github = GitHub.new
+
+    # @param root [String] repository root
+    # @return [OpenLanes::Vcs::Worktree]
+    def worktree(root:, **) = Worktree.new(root:, **)
+
+    # @return [OpenLanes::Vcs::Publisher]
+    def publisher(**) = Publisher.new(**)
+  end
+end

data/lib/openlanes/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Alone in its own file, requiring nothing, so the gemspec can read the version
+# without loading the library — and therefore without the library's own
+# dependencies having to be installed before the gemspec can be evaluated.
+#
+# © 2026 Konstantin Gredeskoul
+module OpenLanes
+  VERSION = "3.0.0"
+end