openlanes 3.0.1 → 3.1.0

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