openlanes 3.0.1 → 3.1.0

data/lib/openlanes/setup.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # Gets a machine ready to run the factory (plan 035): the tools in the
+  # gem's `Brewfile`, then what brew cannot install. `openlanes setup` and
+  # `openlanes init` both come through here, so the two ask the same
+  # questions of the machine and never disagree about whether it is ready.
+  module Setup
+    # The gem's own root, which an installed gem and a checkout both have.
+    GEM_ROOT = File.expand_path("../..", __dir__)
+
+    # The one Brewfile, shipped in the gem: the runtime tools and a
+    # contributor's, which `bin/setup` bundles from the same file.
+    BREWFILE = File.join(GEM_ROOT, "Brewfile")
+
+    module_function
+
+    # @return [OpenLanes::Setup::Machine]
+    def machine(**) = Machine.new(**)
+
+    # One line per check, ✓ or ✗, and under each ✗ the command that fixes it.
+    #
+    # @param checks [Array<OpenLanes::Setup::Check>]
+    # @return [String]
+    def render(checks)
+      width = checks.map { it.name.length }.max.to_i
+      checks.map do |check|
+        mark = check.ok? ? UI.paint("✓", :green) : UI.paint("✗", :red)
+        line = "#{mark} #{check.name.ljust(width)}  #{check.detail}".rstrip
+        check.ok? || check.fix.nil? ? "#{line}\n" : "#{line}\n    fix: #{check.fix}\n"
+      end.join
+    end
+  end
+end

data/lib/openlanes/support/clock.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # A time source, so a spec can move time instead of waiting for it.
+  #
+  # Not to be confused with {OpenLanes::Execution::Clock}, the timeout timer
+  # with a thread of its own; inside `Execution` a bare `Clock` means that
+  # one, so code there writes `OpenLanes::Clock` in full.
+  module Clock
+    # The real clock.
+    module System
+      module_function
+
+      # @return [Time]
+      def now = Time.now
+
+      # @return [Float] seconds on a clock no wall-clock change can move
+      def monotonic = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+
+      # @param seconds [Numeric]
+      # @return [void]
+      def sleep(seconds) = Kernel.sleep(seconds)
+    end
+
+    # A clock that only moves when told to. {#sleep} advances rather than
+    # blocks, so a loop that waits on it runs at once and still sees time pass.
+    # Shared between threads in the stress spec, hence the mutex.
+    class Fake
+      # @param now [Time]
+      def initialize(now: Time.utc(2026, 1, 1))
+        @now = now
+        @monotonic = 0.0
+        @mutex = Mutex.new
+      end
+
+      # @return [Time]
+      def now = @mutex.synchronize { @now }
+
+      # @return [Float]
+      def monotonic = @mutex.synchronize { @monotonic }
+
+      # @param seconds [Numeric]
+      # @return [self]
+      def advance(seconds)
+        @mutex.synchronize do
+          @now += seconds
+          @monotonic += seconds
+        end
+        self
+      end
+
+      # @param seconds [Numeric]
+      # @return [void]
+      def sleep(seconds) = advance(seconds)
+    end
+  end
+end

data/lib/openlanes/support/config.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "date"
 require "yaml"
 
 module OpenLanes
@@ -10,9 +11,37 @@ module OpenLanes
   #   frontend: false           # a spec's `frontend:` when spec.md omits it
   #   jobs: 4                   # how many plans `openlanes run` works on at once
   #   redis_url: redis://10.0.4.2:6379/0  # the Redis the live run shares (W16)
+  #   redis_outage_hours: 1     # how long agents stay paused for a lost Redis
+  #                             # before the run shuts down (W32); any positive number
+  #   redis_backoff:            # how a lost Redis is asked again (plan 022)
+  #     initial: 1              # seconds; the Fibonacci gaps are its multiples
+  #     cap: 30                 # seconds, the longest gap between two asks
+  #     jitter: true            # full jitter: each gap drawn from [0, gap)
+  #   desired_codebase_quality: high  # or mvp (R4): what a review that is ok but
+  #                             # not perfect does, and M5's column of defaults
+  #   merge:
+  #     by: human               # who merges a reviewed PR (M4); `openlanes start` watches it
+  #     max_rejections: 2       # rejections, hansolo's and chewie's together, before
+  #                             # the plan stops going back to its builders (M6)
   #   commands:                 # per-command option defaults
   #     run:
   #       timeout: 1800
+  #   questions:
+  #     model: anthropic/claude-haiku-5.5  # rewrites prose questions into choices (D9)
+  #   review:
+  #     max_hmm: 5              # most 🤔 a review may carry and be approved (R3);
+  #                             # $OPENLANES_REVIEW_MAX_HMM beats it
+  #   app:                      # how to run the app a plan builds (M12)
+  #     kind: web
+  #     processes:
+  #       - name: web
+  #         start: npx vite --port $PORT_WEB --strictPort
+  #         ready: /
+  #         preview: true
+  #   coverage:                 # what the coverage gate measures (M15)
+  #     command: bundle exec rspec
+  #     report_command: jq '.total.lines.percent' coverage/coverage.json
+  #     minimum: 95             # or report: + format: instead of report_command:
   #
   # Precedence, loudest first: a flag typed on the command line, the plan's
   # spec.md frontmatter, this file, the built-in default. The file supplies
@@ -40,14 +69,111 @@ module OpenLanes
   # @!attribute [r] redis_url
   #   @return [String, nil] where the live run keeps its board, its commands
   #     and its plan claims; `--redis-url` beats it, and it beats `$REDIS_URL`
+  # @!attribute [r] redis_outage_hours
+  #   @return [Numeric, nil] `redis_outage_hours` as the file says it; read
+  #     {#outage_limit}, which applies the default
+  # @!attribute [r] redis_backoff
+  #   @return [Hash{Symbol => Object}] `redis_backoff:` as typed, keyed
+  #     :initial, :cap, :jitter; {Live::Outage} applies the defaults
   # @!attribute [r] commands
   #   @return [Hash{String => Hash{Symbol => Object}}] by command name, as
   #     typed: "run", "resync dirs"
-  Config = Data.define(:path, :project, :lane, :frontend, :jobs, :redis_url, :commands) do
-    def initialize(path: nil, project: nil, lane: nil, frontend: nil, jobs: nil, redis_url: nil, commands: {})
+  # @!attribute [r] merge_by
+  #   @return [Symbol, nil] `merge.by`, one of {MERGERS}; nil reads as {#merger}'s default
+  # @!attribute [r] merge_max_rejections
+  #   @return [Integer, nil] `merge.max_rejections` as the file says it; read
+  #     {#max_rejections}, which applies the default
+  # @!attribute [r] app
+  #   @return [OpenLanes::Apps::Definition, nil] the processes `openlanes app
+  #     start` runs; nil when the project declares none, and then nothing
+  #     about apps happens anywhere
+  # @!attribute [r] aging_since
+  #   @return [Date, nil] `plans.aging_since`: no blocked plan ages from
+  #     before it, so weeks the project sat paused do not count; nil is no floor
+  # @!attribute [r] questions_model
+  #   @return [String, nil] `questions.model`: the OpenRouter model that
+  #     rewrites a prose question into lettered choices; nil takes
+  #     {Live::ChoiceConverter::DEFAULT_MODEL}
+  # @!attribute [r] review_max_hmm
+  #   @return [Integer, nil] `review.max_hmm` as the file says it; read
+  #     {#max_hmm}, which applies the environment and the default
+  # @!attribute [r] desired_codebase_quality
+  #   @return [Symbol, nil] one of {QUALITIES}, as the file says it; nil
+  #     while the project is still to be asked (R4)
+  # @!attribute [r] coverage
+  #   @return [OpenLanes::Coverage::Config, nil] the `coverage:` section; nil
+  #     when the project declares none, and then the gate sends the pull
+  #     request back to its builder to write one
+  Config = Data.define(:path,
+    :project,
+    :lane,
+    :frontend,
+    :jobs,
+    :redis_url,
+    :redis_outage_hours,
+    :redis_backoff,
+    :commands,
+    :merge_by,
+    :app,
+    :aging_since,
+    :questions_model,
+    :review_max_hmm,
+    :merge_max_rejections,
+    :desired_codebase_quality,
+    :coverage) do
+    def initialize(path: nil, project: nil, lane: nil, frontend: nil, jobs: nil, redis_url: nil,
+      redis_outage_hours: nil, redis_backoff: {}, commands: {}, merge_by: nil, app: nil, aging_since: nil, questions_model: nil, review_max_hmm: nil, merge_max_rejections: nil,
+      desired_codebase_quality: nil, coverage: nil)
       super
     end
 
+    # How many times a plan's pull request may be rejected, by hansolo and
+    # chewie counted together, before it stops going back to its builders
+    # (M6). `merge.max_rejections` when the file says it, otherwise M5's
+    # column for `desired_codebase_quality:` (R4); two, `high`'s, when neither is set.
+    #
+    # @return [Integer]
+    def max_rejections
+      merge_max_rejections || Config::MAX_REJECTIONS_BY_QUALITY.fetch(desired_codebase_quality, Config::DEFAULT_MAX_REJECTIONS)
+    end
+
+    # @return [Boolean] whether the file has no `desired_codebase_quality:`,
+    #   and so the person is still to be asked (R4)
+    def quality_unset? = desired_codebase_quality.nil?
+
+    # Seconds a run keeps its agents paused for a Redis that stopped
+    # answering before it gives up and shuts down (W32): an hour, unless
+    # `redis_outage_hours` says otherwise.
+    #
+    # @return [Float]
+    def outage_limit = (redis_outage_hours || Config::DEFAULT_OUTAGE_HOURS) * 3600.0
+
+    # The most 🤔 a review may carry and still be `review-approved` (R3).
+    # Loudest first: `$OPENLANES_REVIEW_MAX_HMM`, then `review.max_hmm`, then
+    # {Plans::Verdict::DEFAULT_MAX_HMM}. The variable is there so one run can
+    # be stricter or looser without editing a file the whole team shares.
+    #
+    # @param env [Hash] the environment, injectable for tests
+    # @return [Integer]
+    # @raise [OpenLanes::Error] when the variable is not a whole number
+    def max_hmm(env: ENV)
+      raw = env[Config::MAX_HMM_ENV].to_s.strip
+      return review_max_hmm || Plans::Verdict::DEFAULT_MAX_HMM if raw.empty?
+      return Integer(raw, 10) if raw.match?(/\A\d+\z/)
+
+      raise Error, "#{Config::MAX_HMM_ENV}=#{raw.inspect} is not a whole number"
+    end
+
+    # Who merges a pull request once its review passed (M4). A person, unless
+    # the file says otherwise, since merging is the one thing no agent may do.
+    #
+    # @return [Symbol] `:human` or `:auto`
+    def merger = merge_by || Config::MERGERS.first
+
+    # @return [Boolean] whether the engine waits on a person to merge, and so
+    #   watches the pull requests it opened
+    def human_merges? = merger == :human
+
     # One command's option defaults, the top-level spelling folded in.
     #
     # @param command [String, Symbol] e.g. :run or "resync dirs"
@@ -70,10 +196,25 @@ module OpenLanes
     # @return [String]
     def to_yaml
       settings = { "project" => project, "lane" => lane&.to_s, "frontend" => frontend, "jobs" => jobs,
-                   "redis_url" => redis_url }
+                   "redis_url" => redis_url, "redis_outage_hours" => redis_outage_hours,
+                   "redis_backoff" => (redis_backoff.transform_keys(&:to_s) unless redis_backoff.empty?),
+                   "desired_codebase_quality" => desired_codebase_quality&.to_s, "merge" => merge_settings }
       settings["commands"] = commands.transform_values { it.transform_keys(&:to_s) } unless commands.empty?
+      settings["app"] = app.to_h if app
+      settings["plans"] = { "aging_since" => aging_since.iso8601 } if aging_since
+      settings["questions"] = { "model" => questions_model } if questions_model
+      settings["review"] = { "max_hmm" => review_max_hmm } if review_max_hmm
+      settings["coverage"] = coverage.to_h if coverage
       YAML.dump(settings.compact).delete_prefix("---\n")
     end
+
+    private
+
+    # @return [Hash, nil] `merge:` as the file would hold it, nil when nothing is set
+    def merge_settings
+      merge = { "by" => merge_by&.to_s, "max_rejections" => merge_max_rejections }.compact
+      merge.empty? ? nil : merge
+    end
   end
 
   class Config
@@ -81,7 +222,42 @@ module OpenLanes
     FILE = Project::FILE
 
     # Every key the top level may hold.
-    KEYS = %w[project lane frontend jobs redis_url commands].freeze
+    KEYS = %w[project lane frontend jobs redis_url redis_outage_hours redis_backoff desired_codebase_quality merge commands app plans
+              questions review coverage].freeze
+
+    # What `desired_codebase_quality:` may say (R4), the default first. M5's
+    # `top_notch` and `medium` were dropped.
+    QUALITIES = %i[high mvp].freeze
+
+    # Who may merge, the default first.
+    MERGERS = %i[human auto].freeze
+
+    # Every key `merge:` may hold.
+    MERGE_KEYS = %w[by max_rejections].freeze
+
+    # {#max_rejections} when the file names none (M6).
+    DEFAULT_MAX_REJECTIONS = 2
+
+    # M5's `max_rejections` row, for the two columns R4 kept.
+    MAX_REJECTIONS_BY_QUALITY = { high: 2, mvp: 1 }.freeze
+
+    # {#outage_limit} when the file names none (W32).
+    DEFAULT_OUTAGE_HOURS = 1
+
+    # Every key `redis_backoff:` may hold.
+    BACKOFF_KEYS = %w[initial cap jitter].freeze
+
+    # Every key `plans:` may hold. Checked key by key, like the top level.
+    PLAN_KEYS = %w[aging_since].freeze
+
+    # Every key `questions:` may hold.
+    QUESTION_KEYS = %w[model].freeze
+
+    # Every key `review:` may hold.
+    REVIEW_KEYS = %w[max_hmm].freeze
+
+    # The variable that beats `review.max_hmm`.
+    MAX_HMM_ENV = "OPENLANES_REVIEW_MAX_HMM"
 
     # Schemes a `redis_url:` may use.
     REDIS_SCHEMES = %w[redis rediss unix].freeze
@@ -118,7 +294,7 @@ module OpenLanes
       # @param path [String] for every error message
       # @return [OpenLanes::Config]
       def parse(text, path:)
-        data = YAML.safe_load(text) || {}
+        data = YAML.safe_load(text, permitted_classes: [Date]) || {}
         fail_with(path, "expected a mapping of settings at the top") unless data.is_a?(Hash)
 
         settings = data.transform_keys(&:to_s)
@@ -135,7 +311,16 @@ module OpenLanes
           frontend:  frontend(settings, path),
           jobs:      jobs(settings, path),
           redis_url: redis_url(settings, path),
-          commands:  commands(settings["commands"], path))
+          redis_outage_hours: redis_outage_hours(settings, path),
+          redis_backoff: redis_backoff(settings["redis_backoff"], path),
+          desired_codebase_quality: quality(settings, path),
+          **merge(settings["merge"], path),
+          commands:  commands(settings["commands"], path),
+          app:       settings.key?("app") ? Apps::Definition.parse(settings["app"], path:) : nil,
+          **plans(settings["plans"], path),
+          **questions(settings["questions"], path),
+          **review(settings["review"], path),
+          coverage:  settings.key?("coverage") ? Coverage::Config.parse(settings["coverage"], path:) : nil)
         conflicts!(config, path)
         config
       rescue Psych::Exception => e
@@ -191,6 +376,74 @@ module OpenLanes
         fail_with(path, "redis_url: #{value.inspect} is not a #{REDIS_SCHEMES.map { "#{it}://" }.join(", ")} URL")
       end
 
+      # Any positive number: half an hour is `0.5`.
+      #
+      # @return [Numeric, nil]
+      def redis_outage_hours(settings, path)
+        value = settings["redis_outage_hours"]
+        return value if value.nil? || (value.is_a?(Numeric) && value.positive?)
+
+        fail_with(path, "redis_outage_hours: #{value.inspect} is not a number of hours above zero")
+      end
+
+      # @return [Hash{Symbol => Object}] `redis_backoff:`, checked key by key
+      def redis_backoff(value, path)
+        return {} if value.nil?
+
+        fail_with(path, "redis_backoff: must be a mapping of setting to value") unless value.is_a?(Hash)
+
+        value.transform_keys(&:to_s).to_h do |key, setting|
+          fail_with(path, "redis_backoff.#{key}: unknown key; known: #{BACKOFF_KEYS.join(", ")}") unless BACKOFF_KEYS.include?(key)
+          if key == "jitter"
+            fail_with(path, "redis_backoff.jitter: #{setting.inspect} is not true or false") unless [true, false].include?(setting)
+          elsif !(setting.is_a?(Numeric) && setting.positive?)
+            fail_with(path, "redis_backoff.#{key}: #{setting.inspect} is not a number of seconds above zero")
+          end
+          [key.to_sym, setting]
+        end
+      end
+
+      # @return [Symbol, nil]
+      def quality(settings, path)
+        return nil unless settings.key?("desired_codebase_quality")
+
+        value = settings["desired_codebase_quality"].to_s.strip.downcase.to_sym
+        return value if QUALITIES.include?(value)
+
+        fail_with(path, "desired_codebase_quality: #{settings["desired_codebase_quality"].inspect} is not one of #{QUALITIES.join(", ")}")
+      end
+
+      # @return [Hash{Symbol => Object}] the `merge:` settings, as keywords for {Config.new}
+      def merge(value, path)
+        return {} if value.nil?
+
+        fail_with(path, "merge: must be a mapping, e.g. `merge: { by: human }`") unless value.is_a?(Hash)
+
+        settings = value.transform_keys(&:to_s)
+        unknown = settings.keys - MERGE_KEYS
+        fail_with(path, "merge: unknown key #{unknown.join(", ")}; known: #{MERGE_KEYS.join(", ")}") unless unknown.empty?
+
+        { merge_by: merge_by(settings, path), merge_max_rejections: max_rejections(settings, path) }.compact
+      end
+
+      # @return [Symbol, nil]
+      def merge_by(settings, path)
+        return nil unless settings.key?("by")
+
+        by = settings["by"].to_s.strip.downcase.to_sym
+        return by if MERGERS.include?(by)
+
+        fail_with(path, "merge.by: #{settings["by"].inspect} is not one of #{MERGERS.join(", ")}")
+      end
+
+      # @return [Integer, nil]
+      def max_rejections(settings, path)
+        max = settings["max_rejections"]
+        return max if max.nil? || (max.is_a?(Integer) && max.positive?)
+
+        fail_with(path, "merge.max_rejections: #{max.inspect} is not a whole number above zero")
+      end
+
       # @return [Hash{String => Hash{Symbol => Object}}]
       def commands(value, path)
         return {} if value.nil?
@@ -204,6 +457,65 @@ module OpenLanes
         end
       end
 
+      # @return [Hash{Symbol => Object}] the `plans:` settings, as keywords for {Config.new}
+      def plans(value, path)
+        return {} if value.nil?
+
+        fail_with(path, "plans: must be a mapping of setting to value") unless value.is_a?(Hash)
+
+        settings = value.transform_keys(&:to_s)
+        (settings.keys - PLAN_KEYS).each do |key|
+          fail_with(path, "plans.#{key}: unknown key; known: #{PLAN_KEYS.join(", ")}")
+        end
+        { aging_since: aging_since(settings["aging_since"], path) }
+      end
+
+      # @return [Hash{Symbol => Object}] the `questions:` settings, as keywords for {Config.new}
+      def questions(value, path)
+        return {} if value.nil?
+
+        fail_with(path, "questions: must be a mapping of setting to value") unless value.is_a?(Hash)
+
+        settings = value.transform_keys(&:to_s)
+        (settings.keys - QUESTION_KEYS).each do |key|
+          fail_with(path, "questions.#{key}: unknown key; known: #{QUESTION_KEYS.join(", ")}")
+        end
+        model = settings["model"]
+        return {} if model.nil?
+        return { questions_model: model.strip } if model.is_a?(String) && !model.strip.empty?
+
+        fail_with(path, "questions.model: #{model.inspect} is not a model id, e.g. #{Live::ChoiceConverter::DEFAULT_MODEL}")
+      end
+
+      # @return [Hash{Symbol => Object}] the `review:` settings, as keywords for {Config.new}
+      def review(value, path)
+        return {} if value.nil?
+
+        fail_with(path, "review: must be a mapping of setting to value") unless value.is_a?(Hash)
+
+        settings = value.transform_keys(&:to_s)
+        (settings.keys - REVIEW_KEYS).each do |key|
+          fail_with(path, "review.#{key}: unknown key; known: #{REVIEW_KEYS.join(", ")}")
+        end
+        max = settings["max_hmm"]
+        return {} if max.nil?
+        return { review_max_hmm: max } if max.is_a?(Integer) && !max.negative?
+
+        fail_with(path, "review.max_hmm: #{max.inspect} is not a whole number")
+      end
+
+      # YAML hands an unquoted `2026-10-01` over as a Date already, and a
+      # quoted one as a String; both are the same day to whoever typed it.
+      #
+      # @return [Date, nil]
+      def aging_since(value, path)
+        return value if value.nil? || value.instance_of?(Date)
+
+        Date.iso8601(value.to_s)
+      rescue Date::Error
+        fail_with(path, "plans.aging_since: #{value.inspect} is not a date (YYYY-MM-DD)")
+      end
+
       # @return [void]
       def conflicts!(config, path)
         SHORTHANDS.each do |key, owner|