openlanes 3.0.0

data/lib/openlanes/cli/eval/eval.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes eval` — score the agents against their cases.
+    #
+    # Offline by default: every case's recorded folder is scored, which costs
+    # nothing and runs in CI. `--live` runs the real agents and is never the
+    # default, because it spends tokens.
+    class Eval < Base
+      standalone!
+      desc "Score agents against evals/cases: recorded folders by default, real runs with --live"
+
+      option :agent, aliases: ["-a"], desc: "Only this agent's cases"
+      option :case, aliases: ["-c"], desc: "Only the case with this id"
+      option :depth,
+        values: Plans::Spec::DEPTHS.map(&:to_s),
+        desc:   "Hold every case to this depth's bounds instead of its own"
+      option :recording,
+        values:  %w[pass fail],
+        default: "pass",
+        desc:    "Which recording to score offline"
+      option :live,
+        type:    :boolean,
+        default: false,
+        desc:    "Run the real agent in a temp repository (spends tokens)"
+      option :max_tokens,
+        type: :integer,
+        desc: "Token cap per live case (default #{Evals::Live::DEFAULT_MAX_TOKENS})"
+      option :cases, desc: "Directory of <agent>/<id>.yml cases (default: the gem's evals/cases)"
+
+      example [
+        "                              # score every pass/ recording",
+        "--recording fail              # the fail/ ones, which should all FAIL",
+        "-a leah-researcher --depth deep",
+        "--live -c research-fast --max-tokens 100000"
+      ]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        quiet?(options)
+        refuse("--max-tokens only applies to --live runs.", 64) if options[:max_tokens] && !options[:live]
+        cases = selected(options)
+        scores = options[:live] ? live(cases, options) : offline(cases, options.fetch(:recording, "pass"))
+        $stdout.write(report(scores))
+        exit 1 unless scores.all? { |s, _| s.passed? }
+      end
+
+      private
+
+      # @return [Array<OpenLanes::Evals::Case>]
+      def selected(options)
+        all = Evals.cases(options[:cases] || Evals::DEFAULT_DIR)
+        picked = all.select do |kase|
+          (options[:agent].nil? || kase.agent == options[:agent]) && (options[:case].nil? || kase.id == options[:case])
+        end
+        refuse("No eval case matches #{filters(options)}.", 66) if picked.empty?
+        picked.map { |kase| kase.at(options[:depth]) }
+      rescue Evals::Invalid => e
+        refuse(e.message, 65)
+      end
+
+      # @return [String]
+      def filters(options) = options.slice(:agent, :case).map { |k, v| "--#{k} #{v}" }.join(" ").then { it.empty? ? "(none)" : it }
+
+      # @return [Array<Array(OpenLanes::Evals::Score, OpenLanes::Evals::Run)>]
+      def offline(cases, kind)
+        cases.filter_map do |kase|
+          recording = kase.recording(kind)
+          unless recording
+            UI.line("#{kase} has no #{kind}/ recording, skipped")
+            next
+          end
+          [Evals.score_recording(kase, kind.to_sym), recording.run]
+        end
+      end
+
+      # @return [Array<Array(OpenLanes::Evals::Score, OpenLanes::Evals::Run)>]
+      def live(cases, options)
+        credentials_warning
+        cap = options[:max_tokens] || Evals::Live::DEFAULT_MAX_TOKENS
+        cases.map do |kase|
+          UI.line("running #{kase} at #{kase.depth}, capped at #{cap} tokens")
+          outcome = Evals.run_live(kase, max_tokens: cap)
+          result = outcome.result
+          [outcome.score, Evals::Run.new(seconds: result.seconds, tokens: result.fresh)]
+        end
+      end
+
+      # The table, then what failed and why: the deliverable, on STDOUT.
+      #
+      # @return [String]
+      def report(scores)
+        rows = scores.map do |score, run|
+          kase = score.kase
+          [kase.id, kase.agent, kase.depth, score.tally, run.seconds&.round || "-", run.tokens || "-",
+           score.passed? ? "PASS" : "FAIL"]
+        end
+        table = UI.table(rows, header: %w[Case Agent Depth Checks Seconds Tokens Result])
+        details = scores.reject { |s, _| s.passed? }.map do |score, _|
+          lines = score.failures.map { |v| "  - #{v.name}: #{v.detail}" }
+          lines = ["  - no checks apply at #{score.kase.depth}"] if lines.empty?
+          "#{score.kase} FAIL\n#{lines.join("\n")}\n"
+        end
+        [table, *details].join("\n")
+      end
+    end
+  end
+end

data/lib/openlanes/cli/index/index.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes index` — the plans as one browsable page.
+    class Index < Base
+      desc "Create or update .plans/INDEX.md — a global index of every plan."
+
+      option :output,
+        aliases: ["-o"],
+        desc:    "Write somewhere other than <plans>/INDEX.md; - for STDOUT"
+      option :project,
+        aliases: ["-p"],
+        desc:    "Heading for the page, default: the repository's directory name"
+
+      example [
+        "                     # write .plans/INDEX.md",
+        "-o -                 # print it instead",
+        "-p 'Equilibris App'  # override the heading"
+      ]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        index = OpenLanes::Plans.index(tree: tree_for(options), project: options[:project])
+
+        if options[:output] == "-"
+          $stdout.write(index.render)
+          return
+        end
+
+        path = index.write(typed_path(options[:output]))
+        puts path
+        return if quiet?(options)
+
+        success("Wrote #{path}\n\nRegenerate it after any `resync dirs`, which renames folders\nand would otherwise leave every link here pointing at nothing.")
+      end
+    end
+  end
+end

data/lib/openlanes/cli/init/init.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tty-prompt"
+
+module OpenLanes
+  module CLI
+    # `openlanes init` — make a directory a project: `.openlanes.yml` and `.plans/`.
+    #
+    # It decides its own root rather than searching for one, because it is
+    # the command that creates what the search looks for.
+    class Init < Base
+      standalone!
+      desc "Write .openlanes.yml at the project root and create the plans directory"
+
+      option :project, desc: "Heading for INDEX.md and similar (default: the root's directory name)"
+      option :lane,
+        values: Plans::Spec::LANES.map(&:to_s),
+        desc:   "Default lane for `openlanes create`: full, plan or quick (default: full)"
+      option :frontend,
+        type: :boolean,
+        desc: "Whether plans have a front end; leave it out to let each plan decide"
+      option :jobs, aliases: ["-j"], desc: "How many plans `openlanes run` works on at once (default: cores - 2)"
+      option :yes,
+        type:    :boolean,
+        default: false,
+        aliases: ["-y"],
+        desc:    "Ask nothing; take the flags and the defaults"
+      dry_run_option "Write nothing; print the file that would be written"
+      option :overwrite,
+        type:    :boolean,
+        default: false,
+        desc:    "Replace an existing .openlanes.yml, which is otherwise kept"
+
+      example [
+        "                                   # ask for each value on a terminal",
+        "-y --project 'Equilibris App'       # ask nothing",
+        "-y --lane plan --no-frontend -j 4   # a command-line tool, four plans at once",
+        "-n                                  # show the file, write nothing"
+      ]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        quiet?(options)
+        root = Project.init_root
+        path = File.join(root, Config::FILE)
+        plans = File.expand_path(options.fetch(:dir, OpenLanes::PLANS_DIR), root)
+        keep = File.file?(path) && !options[:overwrite]
+
+        config = keep ? Config.load(root) : settings(root, options)
+        return preview(path, plans, config, keep) if dry_run?(options)
+        return unless keep || confirmed?(path, options)
+
+        File.write(path, config.to_yaml) unless keep
+        FileUtils.mkdir_p(plans)
+        puts path
+        report(path, plans, keep, options)
+      rescue OpenLanes::Error => e
+        refuse(e.message, 65)
+      end
+
+      private
+
+      # The four values, each from its flag, else asked on a terminal, else
+      # its default. The result is parsed back as the file would be, so
+      # `init` cannot write a file every other command then refuses.
+      #
+      # @param root [String]
+      # @param options [Hash]
+      # @return [OpenLanes::Config]
+      def settings(root, options)
+        ask = interactive?(options)
+        project = options[:project] || (ask ? prompt.ask("Project name:", default: File.basename(root)) : File.basename(root))
+        lane = options[:lane] || (ask ? prompt.select("Default lane for new plans:", Plans::Spec::LANES.map(&:to_s)) : "full")
+        frontend = options.key?(:frontend) ? options[:frontend] : (ask_frontend if ask)
+        jobs = options[:jobs] || (prompt.ask("Plans to run at once (blank: cores - 2):") if ask)
+
+        draft = Config.new(project:, lane: lane.to_sym, frontend:, jobs: count(jobs))
+        Config.parse(draft.to_yaml, path: File.join(root, Config::FILE))
+      end
+
+      # @return [Boolean, nil]
+      def ask_frontend
+        choice = prompt.select("Do plans have a front end?", ["each plan decides", "YES", "NO"])
+        { "YES" => true, "NO" => false }[choice]
+      end
+
+      # @param value [String, Integer, nil]
+      # @return [Integer, nil]
+      def count(value)
+        return nil if value.nil? || value.to_s.strip.empty?
+        return value.to_s.to_i if value.to_s.match?(/\A[1-9]\d*\z/)
+
+        refuse("--jobs must be a whole number above zero, not #{value.inspect}.", 64)
+      end
+
+      # @param path [String]
+      # @param options [Hash]
+      # @return [Boolean]
+      def confirmed?(path, options)
+        return true unless interactive?(options)
+        return true if prompt.select("Write #{path}?", %w[YES NO]) == "YES"
+
+        warn("Nothing was written.") unless quiet?(options)
+        false
+      end
+
+      # Prompts only for a person at a terminal who did not say -y: a script
+      # or a pipe gets the flags and the defaults, never a question it
+      # cannot answer.
+      #
+      # @param options [Hash]
+      # @return [Boolean]
+      def interactive?(options) = !options[:yes] && tty?
+
+      # @return [Boolean]
+      def tty? = $stdin.tty? && $stderr.tty?
+
+      # A named seam, so a spec can answer the questions.
+      #
+      # @return [TTY::Prompt]
+      def prompt
+        @prompt ||= TTY::Prompt.new(output: $stderr)
+      end
+
+      # @return [void]
+      def preview(path, plans, config, keep)
+        $stdout.write(config.to_yaml)
+        warn("Dry run — nothing was written.\n" \
+             "#{keep ? "Would keep" : "Would write"} #{path}" \
+             "#{"\nWould create #{plans}" unless File.directory?(plans)}\n\n" \
+             "Re-run without --dry-run to apply.")
+      end
+
+      # @return [void]
+      def report(path, plans, keep, options)
+        return if quiet?(options)
+
+        success("#{keep ? "Kept" : "Wrote"} #{path}#{" (--overwrite replaces it)" if keep}\n" \
+                "Plans live in #{plans}\n\nNext: openlanes create <a few words>")
+      end
+    end
+  end
+end

data/lib/openlanes/cli/linear/linear.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes linear …`
+    module Linear
+      # Shared by both linear commands: the team is which workspace this is
+      # about, so it is an argument rather than a flag. There is no default —
+      # a tool that picks a team for you when you forget to say which is a
+      # tool that files a quarter of somebody's work in the wrong place.
+      class Team < Base
+        def self.inherited(klass)
+          super
+          klass.argument :team,
+            required: true,
+            desc:     "The Linear team key that prefixes its issues, e.g. TAX"
+        end
+
+        private
+
+        # The key is checked before anything reaches for a token, so a typo in
+        # the team name reports the typo rather than an authentication
+        # problem the user does not have.
+        #
+        # @param team [String]
+        # @return [OpenLanes::Linear::Survey]
+        def survey_for(team, tree)
+          key = OpenLanes::Linear.key!(team)
+          api = OpenLanes::Linear::API.new(token: OpenLanes::Linear::API.token_from_env)
+          projects = UI.spinning("Listing #{key} projects") { api.projects(api.team(key)[:id]) }
+          [api, OpenLanes::Linear::Survey.new(tree:, projects:)]
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/linear/subcommands/import.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes linear …`
+    module Linear
+      # `linear import` — the plans, as Linear issues under one of your projects.
+      class Import < Team
+        desc "Create Linear issues from the plans: one per folder, one child per work unit"
+
+        option :project,
+          aliases: ["-p", "--project-url", "--project-id"],
+          desc:    "The project to file everything under: its URL, its name, or its id"
+        dry_run_option "Send nothing to Linear; print what would be created and updated"
+        option :format,
+          default: "text",
+          values:  %w[text json],
+          desc:    "json emits the exact arguments the Linear MCP tools take"
+        option :since,
+          aliases: ["-s"],
+          desc:    "Skip plans numbered below this, e.g. 010.00"
+        option :status,
+          desc: "Only plans in these states: a comma-separated list of status keys"
+        option :update_unchanged,
+          type:    :boolean,
+          default: false,
+          desc:    "Update everything, whether the plan has changed or not"
+
+        example [
+          "TAX -p 'US Tax Law: Self Contained Ruby Gem'   # list what would be created",
+          "TAX -p https://linear.app/acme/project/…       # a URL works too",
+          "TAX -p 'Ruby Gem' -n                           # preview, sending nothing",
+          "TAX -p 'Ruby Gem' --format json                # hand it to the MCP transport instead",
+          "TAX -p 'Ruby Gem' --since 010.00               # only the recent plans",
+          "TAX -p 'Ruby Gem' --status building,in_review"
+        ]
+
+        # @param team [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(team:, **options)
+          tree = tree_for(options)
+          require_project!(options)
+          import = build(tree, team, resolve_project(team, tree, options), options)
+
+          return $stdout.puts(import.to_json) if options[:format] == "json"
+
+          if import.pending.empty?
+            success("Linear is already in step with #{tree.dir}.") unless quiet?(options)
+            return
+          end
+
+          preview(import, options)
+        rescue OpenLanes::Error => e
+          refuse(e.message, 69)
+        end
+
+        private
+
+        # Looking the project up costs a token, and the whole point of
+        # `--format json` is to work without one. A name needs no lookup — the
+        # MCP server resolves a project by name itself — so only a URL or an
+        # id, which do not carry a name, force the network.
+        #
+        # @return [Hash] `{"id", "name", "url"}`
+        def resolve_project(team, tree, options)
+          reference = options[:project].to_s
+          looks_up = reference.match?(%r{\Ahttps?://}) || reference.match?(/\A[0-9a-f-]{32,}\z/)
+          return { "id" => nil, "name" => reference, "url" => nil } if !looks_up && offline?
+
+          _api, survey = survey_for(team, tree)
+          survey.project(reference)
+        end
+
+        # @return [Boolean]
+        def offline? = OpenLanes::Linear::API.token_from_env.nil?
+
+        # @param options [Hash]
+        # @return [void]
+        def require_project!(options)
+          return if options[:project]
+
+          raise OpenLanes::Error,
+            "which project? Pass -p with a project's URL, name or id.\n\n" \
+            "This never creates one: a team's project list is something you curated, and " \
+            "every plan is filed under one you named.\n\n  " \
+            "openlanes linear projects <TEAM>   lists them"
+        end
+
+        # @return [OpenLanes::Linear::Import]
+        def build(tree, team, project, options)
+          OpenLanes::Linear::Import.new(tree:,
+            team: OpenLanes::Linear.key!(team),
+            project:,
+            since: options[:since],
+            statuses: statuses(options),
+            update_unchanged: options.fetch(:update_unchanged, false))
+        end
+
+        # @param options [Hash]
+        # @return [Array<Symbol>, nil]
+        def statuses(options)
+          return nil unless options[:status]
+
+          options[:status].to_s.split(",").map { |word|
+            OpenLanes::Plans.status(word.strip)&.key ||
+              raise(OpenLanes::Error, "no such state: #{word.strip}")
+          }
+        end
+
+        # @param import [OpenLanes::Linear::Import]
+        # @param options [Hash]
+        # @return [void]
+        def preview(import, options)
+          import.pending.each { |action| puts row(action) }
+          return if quiet?(options)
+
+          import.pending.each { |action| say(line(action)) }
+          report_unplaced(import)
+          what = "Linear change#{"s" unless import.pending.size == 1}"
+          return dry_run_footer(import.pending.size, what) if dry_run?(options)
+
+          # There is no push of its own here yet: the MCP transport is what
+          # applies these. Saying so beats implying something was sent.
+          warn("#{import.pending.size} #{what} pending — nothing was sent.\n" \
+               "This command does not write to Linear itself: pipe --format json to the Linear MCP tools.")
+        end
+
+        # @param action [OpenLanes::Linear::Action]
+        # @return [String]
+        def row(action)
+          [action.op, action.kind, action.ordinal, action.unit || "-",
+           action.identifier || "-", action.title].join("\t")
+        end
+
+        # @param action [OpenLanes::Linear::Action]
+        # @return [String]
+        def line(action)
+          verb = paint(action.op.to_s.ljust(6), action.op == :create ? :green : :yellow)
+          indent = action.child? ? "    " : ""
+          "#{verb} #{indent}#{action.title}  #{paint("(#{action.reason})", :bright_black)}"
+        end
+
+        # @param import [OpenLanes::Linear::Import]
+        # @return [void]
+        def report_unplaced(import)
+          return if import.unplaced.empty?
+
+          listed = import.unplaced.map { |status, ordinals|
+            "  #{status} — #{ordinals.join(", ")}\n#{wrapped(OpenLanes::Linear.reason_unplaced(status))}"
+          }
+          warn("Not imported, because nothing here knows where they belong:\n\n" \
+               "#{listed.join("\n\n")}\n\n" \
+               "Decide where they go on your board and add it to Linear::PLACEMENTS.")
+        end
+
+        # A box re-wraps a line that overruns it, and the wrapped remainder
+        # comes back at column zero — which reads as a new entry rather than
+        # the continuation of one. Wrapping it here keeps the indent.
+        #
+        # @param text [String]
+        # @param width [Integer] narrower than the narrowest box
+        # @return [String]
+        def wrapped(text, width: 58)
+          text.split.each_with_object([+""]) { |word, lines|
+            lines << +"" if lines.last.length + word.length + 1 > width
+            lines.last << " " unless lines.last.empty?
+            lines.last << word
+          }.map { |line| "    #{line}" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/linear/subcommands/projects.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes linear …`
+    module Linear
+      # `linear projects` — what the team already has.
+      class Projects < Team
+        desc "List the Linear projects a team owns, and which plans they already cover"
+
+        example [
+          "TAX        # every project the team owns, matched against .plans"
+        ]
+
+        # @param team [String]
+        # @param options [Hash]
+        # @return [void]
+        def call(team:, **options)
+          tree = tree_for(options)
+          _api, survey = survey_for(team, tree)
+
+          survey.projects.each { |project| puts row(project) }
+          return if quiet?(options)
+
+          survey.projects.each do |project|
+            say("#{paint(project["name"], :cyan)}\n    #{paint(project["url"].to_s, :bright_black)}")
+          end
+          report_descriptions(survey)
+        rescue OpenLanes::Error => e
+          refuse(e.message, 69)
+        end
+
+        private
+
+        # @param project [Hash]
+        # @return [String]
+        def row(project)
+          [project["name"], project.dig("status", "name") || "-", project["url"]].join("\t")
+        end
+
+        # @param survey [OpenLanes::Linear::Survey]
+        # @return [void]
+        def report_descriptions(survey)
+          return if survey.undescribed.empty?
+
+          warn("#{survey.undescribed.size} of these say nothing about themselves:\n\n" \
+               "#{survey.undescribed.map { |p| "  #{p["name"]}" }.join("\n")}\n\n" \
+               "A name is three or four words and half of them are the company's. If you " \
+               "want anything here to reason about which project a plan belongs to, that " \
+               "reasoning has to have a sentence to read.")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/list_plans/list_plans.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes list-plans` — backs /plan-status.
+    class ListPlans < Base
+      desc "Print every plan, its state, and its pull requests"
+
+      example ["", "-D .plans", "| less -R"]
+
+      # @param options [Hash]
+      # @return [void]
+      def call(**options)
+        reporter = Presentation.reporter(tree: tree_for(options))
+        $stdout.write(reporter.render)
+
+        exit 1 unless reporter.inconsistent.empty?
+      end
+    end
+  end
+end

data/lib/openlanes/cli/mail/mail.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes mail` — the two halves of a pair talking through the plan
+    # folder. See {OpenLanes::Plans::Mailbox} for why a file rather than a session.
+    module Mail
+      # Both subcommands name a plan and need its folder.
+      module Locating
+        private
+
+        # An unknown number is refused rather than given an empty mailbox:
+        # an agent polling the wrong plan for a whole round would read
+        # silence as "my partner has nothing to say".
+        #
+        # @param options [Hash]
+        # @return [OpenLanes::Plans::Mailbox]
+        def mailbox_for(options)
+          tree = tree_for(options)
+          ordinal = Plans::Ordinal.parse(options[:plan].to_s)
+          subject = ordinal && tree.find(ordinal)
+          unless subject
+            refuse("No plan #{options[:plan]} in #{tree.dir}.\n\nKnown: #{tree.ordinals.join(", ")}", 66)
+          end
+
+          Plans.mailbox(subject.feature.path)
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/mail/subcommands/read.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module Mail
+      # `openlanes mail read` — what is waiting for one agent.
+      #
+      # Nothing waiting is the ordinary result of a poll, so it is not an
+      # error and not even STDOUT: the messages are the deliverable, and an
+      # empty one is empty.
+      class Read < Base
+        include Locating
+
+        desc "Print the messages waiting for an agent in a plan's mailbox"
+
+        option :plan, required: true, desc: "Which plan: NNN or NNN.MM"
+        option :for, required: true, desc: "The agent reading"
+        option :after, default: "0", desc: "Only messages numbered above this, so a poll shows what is new"
+
+        example [
+          "--plan 003 --for rey-frontend            # everything addressed to rey",
+          "--plan 003 --for rey-frontend --after 4  # only what arrived since #4"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          quiet?(options)
+          mailbox = mailbox_for(options)
+          after = options[:after].to_i
+          waiting = mailbox.for(options[:for], after:)
+
+          if waiting.empty?
+            UI.line("Nothing for #{options[:for]}#{" after ##{after}" if after.positive?}") unless quiet?(options)
+            return
+          end
+
+          puts waiting.join("\n")
+        end
+      end
+    end
+  end
+end