openlanes 3.0.0 → 3.1.0

data/lib/openlanes/apps.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # The app a plan builds, run on this machine (plan 012, M12, M13): the
+  # processes `.openlanes.yml` declares under `app:`, started in order on
+  # ports from 11100, kept ready, restarted when their files change, and
+  # shown in the control room's Preview tab.
+  #
+  # Plural, like `Agents` and `Adapters`, so it never reads as `Web::App`,
+  # the control room's own Sinatra application.
+  module Apps
+    module_function
+
+    # @param config [OpenLanes::Config]
+    # @return [OpenLanes::Apps::Definition, nil] nil when the project declares no app
+    def definition(config = Config.current) = config.app
+
+    # This machine's port registry.
+    #
+    # @return [OpenLanes::Apps::Ports]
+    def registry(**) = Ports.new(**)
+
+    # One plan's app, started by {Supervisor#start}. Plan 014 drives this
+    # directly in its clean checkout; `openlanes app start` drives it
+    # through {.runner}.
+    #
+    # @param definition [OpenLanes::Apps::Definition]
+    # @param root [String] the checkout
+    # @param plan [String]
+    # @param branch [String]
+    # @param publisher [#call, nil]
+    # @return [OpenLanes::Apps::Supervisor]
+    def supervisor(definition:, root:, plan:, branch:, publisher: nil, **) = Supervisor.new(definition:, root:, plan:, branch:, publisher:, **)
+
+    # @return [OpenLanes::Apps::Watcher]
+    def watcher(**) = Watcher.new(**)
+
+    # @return [OpenLanes::Apps::Runner]
+    def runner(**) = Runner.new(**)
+  end
+end

data/lib/openlanes/cli/api/api.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes api` — the OpenAPI contracts plans carry, one `openapi.yaml`
+    # per plan folder. See {OpenLanes::Presentation::ApiDocs}.
+    module API
+    end
+  end
+end

data/lib/openlanes/cli/api/subcommands/docs.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module API
+      # `openlanes api docs` — every plan's `openapi.yaml`, and how to read it.
+      #
+      # Read-only, so there is nothing to preview and no `--dry-run`.
+      class Docs < Base
+        desc "List the openapi.yaml files in the plan folders, and check each one parses"
+
+        example [
+          "                # every contract, with the command that renders it",
+          "-D other/.plans # another plans directory"
+        ]
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          quiet = quiet?(options)
+          tree = tree_for(options)
+          result = OpenLanes::Presentation.api_docs.call(tree)
+
+          result.found.each { puts entry(it) }
+          # Plain `path: reason` lines rather than {UI#warn}'s box, which
+          # truncates the path, the one thing a person needs. This shape is
+          # also what an editor's quickfix list already reads.
+          result.problems.each { Kernel.warn("#{shown(it.path)}: #{it.reason}") }
+          UI.line("No #{OpenLanes::Presentation::ApiDocs::FILE} in #{tree.dir}") if result.found.empty? && result.ok? && !quiet
+          exit 65 unless result.ok?
+        end
+
+        private
+
+        # A hosted Redoc page (redocly.github.io/redoc/?url=…) only loads a
+        # URL the browser can fetch over HTTP, and a path on this disk is not
+        # one, so that link would open on an error. Redocly's own CLI renders
+        # the local file to one static HTML page, offline, which is the honest
+        # thing to point at.
+        #
+        # @param found [OpenLanes::Presentation::ApiDocs::Found]
+        # @return [String]
+        def entry(found)
+          path = shown(found.path)
+          title = [found.title, "OpenAPI #{found.version}"].compact.join(" — ")
+          html = File.join(File.dirname(path), "openapi.html")
+          "#{path}  (#{title})\n  npx @redocly/cli build-docs #{path.shellescape} -o #{html.shellescape}"
+        end
+
+        # Relative to where the command runs, the project root, so the line
+        # can be pasted back into a shell as it is. A `-D` outside the root
+        # stays absolute: a path climbing out with `../..` reads as a typo.
+        #
+        # @param path [String]
+        # @return [String]
+        def shown(path)
+          root = "#{Dir.pwd}/"
+          path.start_with?(root) ? path.delete_prefix(root) : path
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/app/app.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes app` — the app a plan builds, run on this machine for the
+    # control room's Preview tab (plan 012). See {OpenLanes::Apps}.
+    module App
+      # Branch names carry the plan: `<user>/NNN.MM-slug` (see {Vcs::Worktree}).
+      BRANCH_PLAN = %r{\A[^/]+/(\d{3}\.\d{2})-}
+
+      # The ordinal a run without one is filed under.
+      NO_PLAN = "000.00"
+
+      # What every subcommand needs from the registry.
+      module Registry
+        private
+
+        # @return [OpenLanes::Apps::Ports]
+        def registry = OpenLanes::Apps.registry
+
+        # @param plan [String, nil] as typed
+        # @return [String, nil] canonical, nil when nothing was typed
+        def ordinal_of(plan)
+          return nil if plan.nil?
+
+          Plans::Ordinal.parse(plan.to_s)&.to_s || refuse("#{plan} is not a plan number like 012 or 012.00", 64)
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/app/subcommands/start.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_boolean"
+require "open3"
+
+module OpenLanes
+  module CLI
+    module App
+      # `openlanes app start` — run a plan's app in the foreground, as
+      # `.openlanes.yml` `app:` declares it, until Ctrl-C, `openlanes app
+      # stop`, or Stop in the Preview tab.
+      class Start < Base
+        include Registry
+
+        desc "Run a plan's app from .openlanes.yml app:, for the Preview tab"
+
+        argument :plan, required: false, desc: "Which plan: NNN or NNN.MM; its worktree when it has one"
+
+        option :redis_url, desc: "Redis the control room reads (default: .openlanes.yml redis_url, else $REDIS_URL, else #{Live::DEFAULT_URL})"
+        option :demo,
+          type:    :boolean,
+          default: false,
+          desc:    "Publish where `openlanes web --demo` reads, beside its sample board"
+        option :ready_timeout, default: Apps::Supervisor::READY_TIMEOUT.to_s, desc: "Seconds each process has to become ready"
+        option :control_room, default: Apps::Framing::ORIGIN, desc: "The control room's origin, which the app must allow to frame it"
+
+        example [
+          "                     # this checkout's app, filed under the plan its branch names",
+          "012                  # plan 012's app, in its worktree when it has one",
+          "--demo --no-quiet    # beside `openlanes web --demo`"
+        ]
+
+        # @param plan [String, nil]
+        # @param options [Hash]
+        # @return [void]
+        def call(plan: nil, **options)
+          quiet?(options)
+          root = checkout(ordinal_of(plan), options)
+          definition = definition_in(root)
+          branch = branch_of(root)
+          ordinal = ordinal_of(plan) || branch[BRANCH_PLAN, 1] || NO_PLAN
+          store, keys = board(options)
+          runner = Apps.runner(definition:,
+            root:,
+            plan: ordinal,
+            branch:,
+            store:,
+            keys:,
+            say:        ->(line) { UI.line("#{ordinal} #{line}") },
+            supervisor: { ready_timeout: Float(options[:ready_timeout]), origin: options[:control_room],
+                          output: ->(name, line) { UI.line("#{name}: #{line}", bullet: "│") } })
+          # A trap may not take a lock, and the flag takes one.
+          %w[INT TERM].each { |name| Signal.trap(name) { Thread.new { runner.stopping.make_true } } }
+          UI.line("Starting #{ordinal}'s app in #{root} (#{branch}); Ctrl-C stops it")
+          runner.call
+        rescue Apps::Supervisor::StartFailed => e
+          refuse("#{ordinal}'s app did not start: #{e.message}", 70)
+        ensure
+          store&.close
+        end
+
+        private
+
+        # The plan's worktree when it has one, else the project root.
+        #
+        # @return [String]
+        def checkout(ordinal, options)
+          return Dir.pwd unless ordinal
+
+          subject = tree_for(options).find(Plans::Ordinal.parse(ordinal))
+          refuse("No plan #{ordinal} in #{OpenLanes::PLANS_DIR}", 66) unless subject
+          path = Vcs.worktree(root: Dir.pwd).path_for(subject.feature)
+          File.directory?(path) ? path : Dir.pwd
+        end
+
+        # The checkout's own `.openlanes.yml`: on a plan's branch, luke may
+        # have written `app:` there and nowhere else yet (M12).
+        #
+        # @return [OpenLanes::Apps::Definition]
+        def definition_in(root)
+          definition = Apps.definition(OpenLanes::Config.load(root))
+          return definition if definition
+
+          refuse("#{File.join(root, Project::FILE)} declares no app:, so there is nothing to start.", 65)
+        rescue OpenLanes::Error => e
+          refuse(e.message, 65)
+        end
+
+        # `symbolic-ref` rather than `rev-parse`, so a branch with no commit
+        # yet still has its name.
+        #
+        # @return [String]
+        def branch_of(root)
+          out, status = Open3.capture2("git", "-C", root, "symbolic-ref", "--short", "HEAD", err: File::NULL)
+          status.success? ? out.strip : "(no branch)"
+        end
+
+        # The store and keys the control room reads, or neither when Redis
+        # is not there: the app runs either way.
+        #
+        # @return [Array(OpenLanes::Live::Store, OpenLanes::Live::Keys), Array(nil, nil)]
+        def board(options)
+          url = Live.redis_url(option: options[:redis_url], config: OpenLanes::Config.current)
+          store = Live.connect(url)
+          keys = Live.keys(root: Dir.pwd)
+          [store, options[:demo] ? keys.with(repo: "demo/#{keys.repo}") : keys]
+        rescue Live::Unavailable => e
+          UI.line("#{e.message}: the app runs, but the Preview tab will not hear of it")
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/app/subcommands/status.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module App
+      # `openlanes app status` — every port an app holds on this machine,
+      # read from the registry, so it answers with or without Redis.
+      class Status < Base
+        include Registry
+
+        desc "List the apps running on this machine: plan, process, port, pid, checkout"
+
+        # @param options [Hash]
+        # @return [void]
+        def call(**options)
+          quiet?(options)
+          entries = registry.entries
+          if entries.empty?
+            UI.line("No app is running on this machine.") unless quiet?(options)
+            return
+          end
+
+          rows = entries.map { |port, entry| [entry["plan"], entry["process"], port.to_s, entry["owner"].to_s, entry["root"]] }
+          puts table([%w[PLAN PROCESS PORT PID CHECKOUT], *rows.sort])
+        end
+
+        private
+
+        # @param rows [Array<Array<String>>]
+        # @return [String]
+        def table(rows)
+          widths = rows.transpose.map { |column| column.map { it.to_s.length }.max }
+          rows.map { |row| row.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ").rstrip }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/app/subcommands/stop.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    module App
+      # `openlanes app stop` — TERM to the `openlanes app start` holding a
+      # plan's ports, which stops its processes and frees them.
+      class Stop < Base
+        include Registry
+
+        desc "Stop a plan's app (every app on this machine when no plan is given)"
+
+        argument :plan, required: false, desc: "Which plan: NNN or NNN.MM"
+
+        # @param plan [String, nil]
+        # @param options [Hash]
+        # @return [void]
+        def call(plan: nil, **options)
+          quiet?(options)
+          ordinal = ordinal_of(plan)
+          owners = registry.entries.values.select { ordinal.nil? || it["plan"] == ordinal }.map { it["owner"] }.uniq
+          if owners.empty?
+            UI.line("No app is running#{" for #{ordinal}" if ordinal} on this machine.") unless quiet?(options)
+            return
+          end
+
+          owners.each { signal(it) }
+        end
+
+        private
+
+        # @return [void]
+        def signal(pid)
+          Process.kill("TERM", pid)
+          UI.line("Asked #{pid} to stop")
+        rescue Errno::ESRCH
+          UI.line("#{pid} had already stopped")
+        rescue Errno::EPERM
+          refuse("#{pid} is not yours to stop", 77)
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/cli/base.rb

@@ -144,8 +144,85 @@ module OpenLanes
           desc:
       end
 
+      # `-l`, `-L` and `--log-format`, for the commands that run something
+      # long enough to be worth a log. No defaults here: a flag left out must
+      # stay nil, so {Log::Settings.from} can fall back to what the engine
+      # handed its server through the environment.
+      #
+      # @return [void]
+      def self.log_options
+        option :log,
+          aliases: ["-l"],
+          desc:    "Write the log to FILE, appending; - for STDOUT (default: #{Log::DEFAULT_FILE} under the project root)"
+        option :log_level,
+          aliases: ["-L"],
+          values:  Log::LEVELS,
+          desc:    "The lowest level written (default: #{Log::DEFAULT_LEVEL})"
+        option :log_format,
+          values: Log::FORMATS.keys,
+          desc:   "color or standard (one line per entry, with or without colour) or json (default: #{Log::DEFAULT_FORMAT})"
+      end
+
+      # `--ips` (alias `--bind`), `-I` and `--admin-credentials`, for the
+      # commands that serve the control room: `web`, and `run` and `start`
+      # through the server they launch.
+      #
+      # @return [void]
+      def self.listen_options
+        option :ips,
+          aliases: ["-i", "--bind"],
+          desc:    "Comma-separated addresses the control room listens on, e.g. 127.0.0.1,192.168.1.20 " \
+                   "(default: #{OpenLanes::Web::HOST}). Any address past loopback needs --admin-credentials"
+        option :all_interfaces,
+          aliases: ["-I"],
+          type:    :boolean,
+          default: false,
+          desc:    "Listen on every interface, the same as --ips #{OpenLanes::Web::Listen::EVERYWHERE}"
+        option :admin_credentials,
+          desc: "USER:PASSWORD, the Basic auth login asked of every request from off this machine; required " \
+                "when listening past loopback (default: $#{OpenLanes::Web::AdminAuth::ENV_NAME})"
+      end
+
       private
 
+      # `--ips`, or `-I` for every interface. Both at once is refused rather
+      # than one quietly winning, since they disagree about who can reach it.
+      #
+      # @param options [Hash]
+      # @return [OpenLanes::Web::Listen]
+      def listen_for(options)
+        if options[:all_interfaces]
+          refuse("Pass --ips or -I, not both.", 64) unless options[:ips].to_s.strip.empty?
+          return OpenLanes::Web::Listen.parse(OpenLanes::Web::Listen::EVERYWHERE)
+        end
+        OpenLanes::Web::Listen.parse(options[:ips])
+      rescue OpenLanes::Web::Listen::Invalid => e
+        refuse("--ips: #{e.message}", 64)
+      end
+
+      # `--admin-credentials`, else the ones `openlanes run` hands its server
+      # through the environment. Listening past loopback without them is
+      # refused: the page can stop agents and answer for a person, and a
+      # server anyone on the network can drive is never a default.
+      #
+      # @param options [Hash]
+      # @param listen [OpenLanes::Web::Listen]
+      # @param env [Hash]
+      # @return [OpenLanes::Web::AdminAuth::Credentials, nil]
+      def credentials_for(options, listen, env: ENV)
+        text = [options[:admin_credentials], env[OpenLanes::Web::AdminAuth::ENV_NAME]].find { !it.to_s.empty? }
+        if text.nil?
+          return unless listen.public?
+
+          refuse("Listening on #{listen.public_ips.join(", ")} needs a login: pass --admin-credentials USER:PASSWORD, " \
+                 "or set $#{OpenLanes::Web::AdminAuth::ENV_NAME}.",
+            64)
+        end
+        OpenLanes::Web::AdminAuth.parse(text)
+      rescue OpenLanes::Web::AdminAuth::Invalid => e
+        refuse("--admin-credentials #{e.message}.", 64)
+      end
+
       # @param options [Hash]
       # @return [OpenLanes::Plans::Tree]
       def tree_for(options)
@@ -226,27 +303,23 @@ module OpenLanes
       # @return [Boolean]
       def dry_run?(options) = options.fetch(:dry_run, false)
 
-      # `claude` prefers a credential in the environment to a claude.ai login,
-      # so a project `.env` that direnv loads on `cd` can redirect every agent
-      # a run spawns to a key meant for the application itself.
-      #
-      # Say it once, before the run starts, because the failure arrives three
-      # minutes later, once per agent, and reads like an agent problem rather
-      # than an environment one.
+      # The credential warning {Execution.credentials_notice} words, drawn
+      # when there is one to give.
       #
       # @return [void]
       def credentials_warning
-        names = Execution::Executor.foreign_credentials
-        return if names.empty?
-
-        one = names.size == 1
-        warn("#{names.join(" and ")} #{one ? "is" : "are"} set in this shell, so every agent authenticates " \
-             "with #{one ? "it" : "them"} rather than with your claude.ai login.\n" \
-             "A stale one fails every agent in the run with `401 API key is invalid`, " \
-             "three minutes at a time.\n" \
-             "If it came from a project .env, run `unset #{names.join(" ")}` first.")
+        notice = Execution.credentials_notice
+        warn(notice) if notice
       end
 
+      # The success value of a workflow's result, or the refusal it failed
+      # with, reported and exited on. One shape for every workflow, so a
+      # command reads the same whichever one it calls.
+      #
+      # @param result [Dry::Monads::Result] Success(value) or Failure({Refusal})
+      # @return [Object] the success value; a failure never returns
+      def unwrap(result) = result.value_or { |refusal| refuse(refusal.message, refusal.status) }
+
       # The line every dry run ends with, so nobody mistakes a preview for the
       # thing having happened.
       #

data/lib/openlanes/cli/coverage/coverage.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module CLI
+    # `openlanes coverage PLAN` — the coverage gate (M15), by hand.
+    #
+    # Runs the declared test command in the plan's worktree, never in the main
+    # tree, and prints the verdict `ready-to-merge` will wait on. The verdict is
+    # the deliverable and goes to STDOUT; the command's own output, when the
+    # gate withholds, goes to STDERR. Exits 1 when the gate withholds, so a
+    # script or CI step can stop on it.
+    #
+    # `CLI::Coverage` shadows the library's namespace, so this file names
+    # `OpenLanes::Coverage` in full.
+    class Coverage < Base
+      desc "Run a plan's declared test command in its worktree and check line coverage"
+
+      argument :plan, required: true, desc: "Plan ordinal: NNN or NNN.MM"
+
+      dry_run_option "Print the declaration and where the command would run; run nothing"
+
+      example [
+        "013                  # run .openlanes.yml's coverage.command in plan 013's worktree",
+        "013 --dry-run        # show what would run, and where"
+      ]
+
+      # @param plan [String]
+      # @param options [Hash]
+      # @return [void]
+      def call(plan:, **options)
+        tree = tree_for(options)
+        ordinal = Plans::Ordinal.parse(plan.to_s)
+        subject = ordinal && tree.find(ordinal)
+        refuse("No plan #{plan} in #{tree.dir}.\n\nKnown: #{tree.ordinals.join(", ")}", 66) unless subject
+
+        worktree = OpenLanes::Vcs.worktree(root: File.dirname(tree.dir))
+        refuse("#{worktree.root} is not a git repository; the gate runs in a plan's worktree.", 66) unless worktree.repository?
+
+        return preview(worktree, subject.feature) if dry_run?(options)
+
+        verdict = OpenLanes::Engine.coverage_gate.call(checkout: worktree.checkout_for(subject.feature))
+        $stdout.puts(verdict.to_s)
+        return if verdict.passed?
+
+        warn(verdict.output.join("\n")) unless verdict.output.empty?
+        exit 1
+      end
+
+      private
+
+      # @return [void]
+      def preview(worktree, feature)
+        path = worktree.path_for(feature)
+        config = File.directory?(path) && OpenLanes::Coverage.config(path)
+        $stdout.puts("would run in #{path}")
+        if config
+          $stdout.puts("  #{config.command}", "  then read #{config.source}, minimum #{format("%g%%", config.minimum)}")
+        else
+          $stdout.puts("  the declaration is read from the #{OpenLanes::Coverage::Config::SECTION}: section of " \
+                       "#{OpenLanes::Config::FILE} there, once the worktree exists and has one")
+        end
+        dry_run_footer(1, "coverage run")
+      rescue OpenLanes::Coverage::Invalid => e
+        refuse(e.message, 65)
+      end
+    end
+  end
+end