openlanes 3.0.0

data/lib/openlanes/web/app.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "json"
+require "rack/utils"
+require "sinatra/base"
+
+module OpenLanes
+  module Web
+    # The routes of contract.md, "HTTP". One subclass per server, built by
+    # {.serving}, carries that server's {Context} as a setting, so two apps in
+    # one process (the suite) never share a token or a store.
+    class App < Sinatra::Base
+      # The plan files the drawer and the preview may read. A name is looked
+      # up in this list and never joined onto a path as typed, which is what
+      # makes `../` meaningless here rather than merely refused.
+      PLAN_FILES = %w[spec.md plan.md blocked.md research.md design.md].freeze
+
+      # Host headers the server answers. Loopback only, so a page on another
+      # site cannot reach it through DNS rebinding.
+      LOCAL_HOSTS = ["localhost", IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")].freeze
+
+      # What `/` says when the page was never built.
+      UNBUILT = <<~HTML
+        <!doctype html>
+        <html lang="en"><head><meta charset="utf-8"><title>openlanes: page not built</title></head>
+        <body><h1>The control room page is not built</h1>
+        <p>Run <code>just web-build</code> first, then reload.</p></body></html>
+      HTML
+
+      configure do
+        set :environment, :production
+        set :show_exceptions, false
+        set :raise_errors, false
+        set :dump_errors, false
+        set :logging, false
+        set :static, true
+        set :static_cache_control, [:public, { max_age: 3600 }]
+        # Rack::Protection's defaults (frame options, origin check on writes,
+        # JSON CSRF, path traversal, IP spoofing, XSS header), answering 403.
+        # Sinatra's own reaction is to drop the session and carry on, which
+        # with no session is no reaction at all. The token is the guard the
+        # session would otherwise have been.
+        set :protection, except: %i[remote_token], reaction: :deny
+        set :host_authorization, { permitted_hosts: LOCAL_HOSTS }
+      end
+
+      class << self
+        # @param context [OpenLanes::Web::Context]
+        # @return [Class] a subclass serving that context
+        def serving(context)
+          Class.new(self) do
+            set :context, context
+            set :public_folder, context.dist
+          end
+        end
+      end
+
+      helpers do
+        # @return [OpenLanes::Web::Context]
+        def context = settings.context
+
+        # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+        def store = context.store
+
+        # @param data [Object]
+        # @return [String]
+        def json(data)
+          content_type :json
+          JSON.generate(data)
+        end
+
+        # @return [Boolean]
+        def csrf? = Rack::Utils.secure_compare(request.env["HTTP_X_CSRF_TOKEN"].to_s, context.csrf)
+
+        # The machine this server speaks for, as the engine last described
+        # it, so the session and the board never disagree about who "me" is.
+        #
+        # @return [Hash, nil]
+        def node
+          snapshot = store.get(context.keys.snapshot)
+          return JSON.parse(snapshot)["node"] if snapshot
+
+          context.node&.wire(heartbeat_at: Time.now)
+        end
+
+        # @param body [String]
+        # @return [String] the command's id when it has a usable one
+        def id_in(body)
+          id = JSON.parse(body)["id"].to_s
+          id.match?(Live::Command::ID) ? id : ""
+        rescue JSON::ParserError, TypeError, NoMethodError
+          ""
+        end
+      end
+
+      before "/api/*" do
+        cache_control :no_store
+      end
+
+      error Live::Unavailable do
+        status 503
+        json(error: env["sinatra.error"].message)
+      end
+
+      get "/healthz" do
+        store.ping
+        content_type :text
+        "ok #{Live.mask(context.url)}\n"
+      end
+
+      get "/api/session" do
+        json(csrf: context.csrf, node:, repo: context.keys.repo)
+      end
+
+      get "/api/board" do
+        json(Live.board(store:, keys: context.keys))
+      end
+
+      get "/api/events" do
+        content_type "text/event-stream"
+        headers "Cache-Control" => "no-cache, no-transform", "X-Accel-Buffering" => "no"
+        events = Events.new(context:, store:, last_id: request.env["HTTP_LAST_EVENT_ID"])
+        stream { |out| events.run(out) }
+      end
+
+      post "/api/commands" do
+        body = request.body.read
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        reply = Live.enqueue(store:, keys: context.keys, input: body)
+        status 202
+        json(reply.wire)
+      rescue Live::Command::Invalid => e
+        status 422
+        json(Live::Reply.new(id: id_in(body), status: "refused", reason: e.message).wire)
+      end
+
+      # Demo only: the board back to the fixture, for a test that wants a
+      # known start. A real engine's run has no such thing.
+      post "/api/demo/reset" do
+        halt 404, json(error: "no such endpoint") unless context.demo
+        halt 403, json(error: "X-CSRF-Token does not match; fetch /api/session again") unless csrf?
+
+        context.demo.reset
+        status 204
+      end
+
+      get "/api/plans/:ordinal/files/:name" do
+        name = PLAN_FILES.find { it == params[:name] } or halt 404, json(error: "not a plan file: #{params[:name]}")
+        ordinal = Plans::Ordinal.parse(params[:ordinal]) or halt 404, json(error: "not a plan number")
+        subject = Plans.tree(context.plans_dir).find(ordinal) or halt 404, json(error: "there is no plan #{ordinal}")
+        path = File.join(subject.feature.path, name)
+        halt 404, json(error: "#{ordinal} has no #{name}") unless File.file?(path)
+
+        content_type "text/markdown", charset: "utf-8"
+        File.read(path)
+      end
+
+      get "/api/*" do
+        halt 404, json(error: "no such endpoint")
+      end
+
+      # Every other path is the page's own route: the page decides what it
+      # means. A path naming a file is not one, so a missing asset is a 404
+      # rather than the page served as JavaScript.
+      get "/*" do
+        halt 404, { "Content-Type" => "text/plain" }, "not found\n" unless File.extname(request.path_info).empty?
+        halt 503, { "Content-Type" => "text/html; charset=utf-8" }, UNBUILT unless context.dist?
+
+        cache_control :no_cache
+        send_file context.index
+      end
+    end
+  end
+end

data/lib/openlanes/web/context.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "concurrent/atomic/atomic_boolean"
+
+module OpenLanes
+  module Web
+    # Everything one API server knows, fixed when it starts: where Redis is,
+    # whose keys it reads, the token every write must carry, and how often
+    # the event stream looks for news.
+    #
+    # @!attribute [r] stores
+    #   @return [OpenLanes::Web::Stores] a store per request thread
+    # @!attribute [r] keys
+    #   @return [OpenLanes::Live::Keys] this node's
+    # @!attribute [r] plans_dir
+    #   @return [String] the `.plans` directory plan files are read from
+    # @!attribute [r] url
+    #   @return [String] the Redis address
+    # @!attribute [r] csrf
+    #   @return [String] what `X-CSRF-Token` must equal
+    # @!attribute [r] dist
+    #   @return [String] the built page
+    # @!attribute [r] node
+    #   @return [OpenLanes::Live::Node, nil] this machine, for `/api/session`
+    #     while no engine has published a snapshot
+    # @!attribute [r] tick
+    #   @return [Float] seconds between the event stream's looks (contract: 250 ms)
+    # @!attribute [r] ping_every
+    #   @return [Float] seconds between `: ping` comments
+    # @!attribute [r] lifetime
+    #   @return [Float, nil] seconds an event stream lives; nil for as long as
+    #     the browser holds it. The suite sets one so a stream ends.
+    # @!attribute [r] demo
+    #   @return [OpenLanes::Web::Demo, nil] the demo engine, under `--demo`,
+    #     which `POST /api/demo/reset` puts back to the start
+    # @!attribute [r] stopping
+    #   @return [Concurrent::AtomicBoolean] set when the server shuts down, so
+    #     open streams end within a tick
+    Context = Data.define(:stores,
+      :keys,
+      :plans_dir,
+      :url,
+      :csrf,
+      :dist,
+      :node,
+      :tick,
+      :ping_every,
+      :lifetime,
+      :demo,
+      :stopping) do
+      def initialize(dist: DIST, node: nil, tick: 0.25, ping_every: 15.0, lifetime: nil, demo: nil,
+        stopping: Concurrent::AtomicBoolean.new, **rest)
+        super
+      end
+
+      # @return [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore] this thread's
+      def store = stores.current
+
+      # @return [String] the page's entry point
+      def index = File.join(dist, "index.html")
+
+      # @return [Boolean]
+      def dist? = File.file?(index)
+    end
+  end
+end

data/lib/openlanes/web/demo.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Web
+    # `openlanes web --demo`: an engine with no agents. Every second it publishes
+    # a {DemoBoard} snapshot for this node and for one pretend other machine,
+    # through the same keys and in the same shape as {Live::Publisher}, and
+    # it answers the page's commands as {Live::Commands} does: read through
+    # the `engine` group, applied once, a `done` or `refused` reply written
+    # to `replies` and `done`, then acknowledged.
+    #
+    # Cypress and the front end's dev server run against it.
+    class Demo
+      # Seconds between snapshots.
+      INTERVAL = 1.0
+
+      # The other machine's checkout id, fixed so its keys are stable.
+      OTHER_CHECKOUT = Live::Node.digest("openlanes-demo-other", Live::Node::CHECKOUT_LENGTH)
+
+      # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
+      # @param keys [OpenLanes::Live::Keys] this node's
+      # @param board [OpenLanes::Web::DemoBoard]
+      # @param interval [Float]
+      # @param clock [Proc] wall time
+      def initialize(store:, keys:, board: DemoBoard.new, interval: INTERVAL, clock: -> { Time.now })
+        @store = store
+        @keys = keys
+        @board = board
+        @interval = interval
+        @clock = clock
+        @seqs = {}
+        @ready = false
+        @running = false
+        @mutex = Mutex.new
+      end
+
+      # @return [OpenLanes::Web::DemoBoard]
+      def board = @mutex.synchronize { @board }
+
+      # Back to the fixture as it was, so each Cypress spec starts from the
+      # same board whatever the last one answered or stopped.
+      #
+      # @return [void]
+      def reset = @mutex.synchronize { @board = DemoBoard.new }
+
+      # Publish and answer every {INTERVAL}, on a thread of its own.
+      #
+      # @return [self]
+      def start
+        @running = true
+        @thread = Thread.new do
+          while @running
+            tick
+            sleep @interval
+          end
+        end
+        self
+      end
+
+      # Stop, and take this demo's snapshots down so no page shows them.
+      #
+      # @return [void]
+      def stop
+        @running = false
+        @thread&.join(@interval * 2)
+        @store.del(@keys.snapshot, @keys.snapshot(other))
+        @store.hdel(@keys.nodes, @keys.node, other)
+      rescue Live::Unavailable
+        nil
+      end
+
+      # One second: commands first, as the engine applies them at the top of
+      # its tick, then the board moves and is published.
+      #
+      # @return [Array<OpenLanes::Live::Reply>] the commands answered
+      def tick
+        @mutex.synchronize do
+          replies = commands
+          @board.advance(@clock.call)
+          publish(@keys.node, @board.me)
+          @board.others.each { publish(other, it) }
+          replies
+        end
+      rescue Live::Unavailable => e
+        UI.log("demo: #{e.message}")
+        []
+      end
+
+      private
+
+      # @return [String] the pretend other machine's node name
+      def other = "#{@board.others.first&.dig("node", "id")}:#{OTHER_CHECKOUT}"
+
+      # @return [void]
+      def publish(name, snapshot)
+        snapshot["seq"] = next_seq(name)
+        json = JSON.generate(snapshot)
+        @store.multi do |tx|
+          tx.set(@keys.snapshot(name), json, ex: Live::Keys::SNAPSHOT_TTL)
+          tx.xadd(@keys.board(name), { seq: snapshot["seq"], json: }, maxlen: Live::Keys::BOARD_LENGTH)
+          tx.hset(@keys.nodes, name, JSON.generate(snapshot["node"]))
+        end
+      end
+
+      # Carries on from the last seq in the stream, as the engine does, so a
+      # restarted demo never looks like the past to an open page.
+      #
+      # @return [Integer]
+      def next_seq(name)
+        @seqs[name] ||= @store.xrevrange(@keys.board(name), count: 1).first&.fields&.fetch("seq", nil).to_i
+        @seqs[name] += 1
+      end
+
+      # @return [Array<OpenLanes::Live::Reply>]
+      def commands
+        unless @ready
+          # "$": commands left in the stream by an earlier demo were meant for
+          # a board that no longer exists.
+          @store.xgroup_create(@keys.commands, Live::Keys::GROUP, from: "$")
+          @ready = true
+        end
+        @store.xreadgroup(@keys.commands, Live::Keys::GROUP, @keys.node, id: ">", count: Live::Commands::BATCH)
+              .map { answer(it) }
+      end
+
+      # @param entry [OpenLanes::Live::Store::Entry]
+      # @return [OpenLanes::Live::Reply]
+      def answer(entry)
+        command = Live::Command.parse(entry.fields["json"].to_s)
+        first = @store.hget(@keys.done, command.id)
+        reply = first ? parse(first) : outcome(command)
+        @store.multi do |tx|
+          tx.hset(@keys.done, reply.id, reply.to_json) unless first
+          tx.xadd(@keys.replies, { json: reply.to_json }, maxlen: Live::Keys::REPLIES_LENGTH)
+          tx.xack(@keys.commands, Live::Keys::GROUP, entry.id)
+        end
+        reply
+      rescue Live::Command::Invalid => e
+        refuse(entry, e.message)
+      end
+
+      # @return [OpenLanes::Live::Reply]
+      def outcome(command)
+        reason = @board.apply(command)
+        Live::Reply.new(id: command.id, status: "done", reason: reason.is_a?(String) ? reason : nil, at: @clock.call)
+      rescue DemoBoard::Refusal => e
+        Live::Reply.new(id: command.id, status: "refused", reason: e.message, at: @clock.call)
+      end
+
+      # @return [OpenLanes::Live::Reply]
+      def refuse(entry, reason)
+        reply = Live::Reply.new(id: entry.id, status: "refused", reason:, at: @clock.call)
+        @store.multi do |tx|
+          tx.xadd(@keys.replies, { json: reply.to_json }, maxlen: Live::Keys::REPLIES_LENGTH)
+          tx.xack(@keys.commands, Live::Keys::GROUP, entry.id)
+        end
+        reply
+      end
+
+      # @return [OpenLanes::Live::Reply]
+      def parse(json)
+        data = JSON.parse(json)
+        Live::Reply.new(id: data["id"], status: data["status"], reason: data["reason"], at: Time.iso8601(data["at"]))
+      end
+    end
+  end
+end

data/lib/openlanes/web/demo_board.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Web
+    # The demo's run, as plain snapshot hashes the shape of
+    # `web/src/api/fixtures/board.json`: what {Demo} publishes, and what its
+    # commands change. No plan folder is touched and no agent runs.
+    #
+    # Each command kind is one method, named as {Live::Commands} names its
+    # handlers, raising {Refusal} with the reason the engine would give.
+    class DemoBoard
+      # A command the demo will not apply.
+      class Refusal < StandardError; end
+
+      # Activity lines a running car cycles through, so the board moves.
+      CHATTER = [
+        "Reading the plan's work units",
+        "Running the suite: 412 examples",
+        "Editing lib/openlanes/web/app.rb",
+        "Writing the spec for the event stream",
+        "Checking rubocop: no offenses",
+        "Waiting on the reviewer's mailbox"
+      ].freeze
+
+      # The status a plan takes once its last question is answered.
+      UNBLOCKED = { "key" => "building", "emoji" => "🟡", "label" => "Building" }.freeze
+
+      # What each car-signal kind does to the car.
+      SIGNALS = {
+        "hold"    => { "held" => true },
+        "wrap_up" => { "phase" => "wrap_up" },
+        "compact" => { "phase" => "calm" },
+        "stop"    => { "phase" => "stopped", "state" => "done" }
+      }.freeze
+
+      # @param fixture [String] path to a `Board` JSON
+      # @param random [Random]
+      def initialize(fixture: FIXTURE, random: Random.new(4747))
+        board = JSON.parse(File.read(fixture))
+        @me = board.fetch("me")
+        @others = board.fetch("others")
+        @random = random
+        @ticks = 0
+      end
+
+      # @return [Hash] this node's snapshot
+      attr_reader :me
+
+      # @return [Array<Hash>] the other nodes' snapshots
+      attr_reader :others
+
+      # One second of pretend work: tokens grow, clocks run, messages turn.
+      #
+      # @param now [Time]
+      # @return [void]
+      def advance(now)
+        @ticks += 1
+        [@me, *@others].each { |snapshot| advance_snapshot(snapshot, now) }
+      end
+
+      # @param command [OpenLanes::Live::Command]
+      # @return [String, nil] a reason to show beside "done"
+      # @raise [Refusal]
+      def apply(command)
+        send(Live::Commands::HANDLERS.fetch(command.kind), command)
+      end
+
+      private
+
+      # @return [void]
+      def advance_snapshot(snapshot, now)
+        stamp = now.utc.iso8601
+        snapshot["at"] = stamp
+        snapshot["node"]["heartbeat_at"] = stamp
+        snapshot["plans"].each { |plan| advance_plan(plan) }
+        run = snapshot["run"]
+        run["up"] = snapshot["plans"].sum { it["up"] }
+        run["down"] = snapshot["plans"].sum { it["down"] }
+        run["agents_working"] = running(snapshot).size
+      end
+
+      # @return [void]
+      def advance_plan(plan)
+        plan["cars"].select { it["state"] == "running" && !it["held"] }.each do |car|
+          up = @random.rand(800..2400)
+          down = @random.rand(60..240)
+          car["up"] += up
+          car["down"] += down
+          plan["up"] += up
+          plan["down"] += down
+          car["elapsed"] += 1
+          car["remaining"] = [car["remaining"] - 1, 0].max if car["remaining"]
+          chatter(car) if (@ticks % 4).zero?
+        end
+        plan["elapsed"] += 1 if plan["cars"].any? { it["state"] == "running" }
+      end
+
+      # @return [void]
+      def chatter(car)
+        car["message"] = CHATTER[(@ticks / 4) % CHATTER.size]
+        car["history"] = [car["message"], *car["history"]].first(50)
+      end
+
+      # @return [Array<Hash>] cars still at work
+      def running(snapshot) = snapshot["plans"].flat_map { it["cars"] }.select { it["state"] == "running" }
+
+      # ---- questions --------------------------------------------------------
+
+      # @return [nil]
+      def answer(command)
+        plan, question = question!(command)
+        plan["questions"].delete(question)
+        unblock(plan) if plan["questions"].empty?
+        nil
+      end
+
+      # @return [nil]
+      def hold_blocked(command) = hold_question(command, true)
+
+      # @return [nil]
+      def release_hold(command) = hold_question(command, false)
+
+      # @return [nil]
+      def hold_question(command, held)
+        question!(command).last["held"] = held
+        nil
+      end
+
+      # @return [void]
+      def unblock(plan)
+        plan["status"] = UNBLOCKED.dup if %w[blocked product_blocked].include?(plan.dig("status", "key"))
+        plan["cars"].each { it["state"] = "running" if it["state"] == "stuck" }
+      end
+
+      # @return [Array(Hash, Hash)] the plan and its question
+      def question!(command)
+        plan = plan!(command)
+        number = command["question"][/\AB?(\d+)\z/i, 1] or raise Refusal, "#{command["question"]} is not a question number like B2"
+        question = plan["questions"].find { it["number"] == number.to_i } or
+          raise Refusal, "#{command.plan} has no open question B#{number}"
+        [plan, question]
+      end
+
+      # ---- agents -----------------------------------------------------------
+
+      # @return [String]
+      def resume(command)
+        plan = plan!(command)
+        interrupted = plan["interrupted"] or raise Refusal, "#{command.plan} has no interrupted agent to resume"
+        plan["interrupted"] = nil
+        "#{interrupted["agent"]} resumes on #{command.plan} at its next turn"
+      end
+
+      # Every agent on the plan stops and the interruption is forgotten; the
+      # engine also resets the worktree and sends the plan back one state,
+      # which a board with no folders behind it has nothing to show for.
+      #
+      # @return [String]
+      def discard(command)
+        plan = plan!(command)
+        plan["cars"].each { it.merge!(SIGNALS.fetch("stop")) }
+        plan["interrupted"] = nil
+        "discarded the work on #{command.plan}; its agents stopped"
+      end
+
+      # @return [nil]
+      def message(command)
+        plan = plan!(command)
+        cars = plan["cars"].select { command.agent.to_s.empty? || it["agent"] == command.agent }
+        raise Refusal, "no agent named, and none is working #{command.plan}" if cars.empty?
+
+        cars.each do |car|
+          car["history"] = ["human: #{command["text"]}", *car["history"]].first(50)
+          car["held"] = false
+        end
+        nil
+      end
+
+      # @return [nil]
+      def signal(command)
+        car!(command).merge!(SIGNALS.fetch(command.kind)).tap { it["held"] = command.kind == "hold" }
+        nil
+      end
+
+      # The demo has no session to compact; the car calms as a real one would
+      # once its context is shed.
+      #
+      # @return [nil]
+      def compact(command) = signal(command)
+
+      # @return [String]
+      def stop_all(_command)
+        cars = running(@me)
+        cars.each { it.merge!(SIGNALS.fetch("stop")) }
+        @me["run"]["status"] = "quitting"
+        "stopping #{cars.size} agent#{"s" unless cars.size == 1} on #{@me.dig("node", "user")}@#{@me.dig("node", "host")}"
+      end
+
+      # Queues the model for the next round and leaves the running one
+      # alone, as Live::Snapshot reports it: `next_model` until a round runs
+      # on it, and nil when it is the model already running.
+      #
+      # @return [String]
+      def set_model(command) # rubocop:disable Naming/AccessorMethodName -- named for the command kind, as in Live::Commands
+        car = car!(command)
+        model = model!(command["model"])
+        car["next_model"] = (model unless model == car["model"])
+        "#{command.agent} runs on #{model} from its next round"
+      end
+
+      # @return [String]
+      def switch_model(command)
+        car = car!(command)
+        raise Refusal, "#{command.car} is not running; use set_model for its next round" unless car["state"] == "running"
+
+        car["model"] = model!(command["model"])
+        # The switch is the model now, so nothing is queued behind it.
+        car["next_model"] = nil
+        "#{command.agent} compacted and carries on on #{car["model"]}"
+      end
+
+      # @return [String] the model's full id
+      def model!(name)
+        entry = @me["models"].find { [it["id"], it["label"]].include?(name) } or raise Refusal, "claude offers no model #{name}"
+        entry["id"]
+      end
+
+      # ---- plans ------------------------------------------------------------
+
+      # @return [nil]
+      def add_plan(command)
+        ordinal = Plans::Ordinal.parse(command["ordinal"])&.to_s or raise Refusal, "#{command["ordinal"]} is not a plan number"
+        entry = @me["backlog"].find { it["ordinal"] == ordinal } or raise Refusal, "there is no plan #{ordinal}"
+        @me["backlog"].delete(entry)
+        @me["plans"] << plan_from(entry)
+        nil
+      end
+
+      # @return [String]
+      def create_plans(command)
+        ordinals = [*@me["plans"], *@me["backlog"]].map { it["ordinal"].to_i }
+        ordinal = format("%03d.00", ordinals.max.to_i + 1)
+        title = command["idea"].lines.first.to_s.strip.delete_prefix("#").strip
+        @me["plans"] << plan_from({ "ordinal" => ordinal,
+                                    "title" => title,
+                                    "status" => { "key" => "new", "emoji" => "⚪️", "label" => "New" },
+                                    "lane" => "full" })
+        "created #{ordinal} #{slug(title)}"
+      end
+
+      # @return [Hash] a `Plan` at its status's station, with nobody on it yet
+      def plan_from(entry)
+        station = @me["stations"].find { it["key"] == entry.dig("status", "key") }&.fetch("key") || @me["stations"].first["key"]
+        entry.merge("slug" => slug(entry["title"]),
+          "station" => station,
+          "up" => 0,
+          "down" => 0,
+          "cost" => 0,
+          "started_at" => nil,
+          "elapsed" => 0,
+          "cars" => [],
+          "pr" => nil,
+          "questions" => [],
+          "interrupted" => nil,
+          "claimed_by" => @me.dig("node", "id"))
+      end
+
+      # @return [String]
+      def slug(title) = title.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-").delete_suffix("-")
+
+      # ---- lookups ----------------------------------------------------------
+
+      # @return [Hash]
+      def plan!(command)
+        @me["plans"].find { it["ordinal"] == command.plan } or raise Refusal, "there is no plan #{command.plan}"
+      end
+
+      # @return [Hash]
+      def car!(command)
+        plan!(command)["cars"].find { it["key"] == command.car } or raise Refusal, "#{command.car} is not running"
+      end
+    end
+  end
+end