openlanes 3.0.0 → 3.1.0

data/lib/openlanes/web/events.rb

@@ -6,32 +6,77 @@ module OpenLanes
   module Web
     # One page's event stream (contract.md, `GET /api/events`): a `board`
     # event whenever any node's snapshot `seq` changes, a `reply` event for
-    # each reply the engine writes, and a `: ping` comment so proxies and the
+    # each reply the engine writes, a `copilot` event for each turn of the
+    # conversation with the copilot (W17), and a `: ping` comment so proxies and the
     # browser keep the connection open.
     #
-    # Polled rather than blocked on: a blocking read would hold the thread's
-    # connection for the length of the wait, and the board has to be looked
-    # at every tick anyway.
+    # Pushed rather than polled: the stream holds a subscription of its own
+    # to {Live::Keys#news} and sleeps on it until a writer nudges ({Live::News}),
+    # then reads Redis exactly as it did when it looked every quarter second.
+    # The nudge carries no data, so the cursors below are untouched by it.
+    # It subscribes before its first read, so a write that lands between
+    # the two is read twice rather than missed. With no nudge it still looks
+    # once per ping, which is how it notices what nobody announces: a node
+    # whose snapshot expired, an app whose runner was killed. One
+    # subscription per stream, closed when the stream ends.
     #
     # A reply carries its stream id as the event's `id:`, so a browser that
     # reconnects sends `Last-Event-ID` and gets what it missed. The stream
     # opens with a `cursor` event carrying the id it starts from, so a
     # browser that drops before the first reply still has one to send;
     # without it, replies written during that gap were skipped.
+    #
+    # A `chat` event (plan 006) carries no `id:` either, and like the
+    # copilot's the stream opens with a `chat_cursor` when it carries a
+    # page's chat, so the page reads `GET /api/chat` only once relaying has
+    # begun. Nor is there a cursor id to carry: the chat between
+    # machines keeps no history (D2), so there is nothing to catch up on.
+    # The stream is how {Live::Chat} knows the page is still open; when it
+    # closes, the page has {Live::Chat::GRACE} to reconnect before it counts
+    # as having left (D6).
+    #
+    # A copilot turn carries no `id:`, so it never moves that cursor. The
+    # conversation has a boundary of its own instead: the stream samples the
+    # newest turn, says so in a `copilot_cursor` event, and from then on
+    # sends every turn after it. The page reads `GET /api/copilot` when that
+    # event arrives, never before it, so the read covers everything up to
+    # the boundary and the stream everything after. A turn written between a
+    # read the page started on its own and the stream opening fell in the
+    # gap between the two and was never shown.
+    #
+    # The apps running on this machine (plan 012) open the stream as one
+    # `apps` event, sent only when there is one, so a project with no app
+    # gets the stream it always had; the page starts each stream with no
+    # apps. After that each process whose status changed comes as an `app`
+    # event. A process whose plan's entry vanished (its runner
+    # stopped or died) is sent once more as `stopped`, so the page never
+    # keeps a tab for an app that is gone.
     class Events
+      # How often a stream without a subscription looks again: the polling
+      # interval every stream used before nudges.
+      POLL = 0.25
+
+      # Block on the subscription for the next nudge, or, with none, poll.
+      WAIT = ->(news, seconds) { news ? news.next_message(seconds) : sleep([seconds, POLL].min) }
+
       # @param context [OpenLanes::Web::Context]
       # @param store [OpenLanes::Live::Store, OpenLanes::Live::MemoryStore]
       # @param last_id [String, nil] the `Last-Event-ID` the browser sent
+      # @param page [String, nil] the page's own id, `?page=` on the stream, for its chat
       # @param clock [Proc] seconds, monotonic
-      # @param sleeper [Proc] waits the given seconds between ticks
-      def initialize(context:, store:, last_id: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
-        sleeper: ->(seconds) { sleep seconds })
+      # @param waiter [Proc] given the subscription and at most how many
+      #   seconds to wait, returns once a nudge arrives or the time is up
+      def initialize(context:, store:, last_id: nil, page: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+        waiter: WAIT)
         @context = context
         @store = store
         @keys = context.keys
+        @copilot = Live.copilot(store:, keys: @keys)
         @last_id = last_id.to_s.match?(/\A\d+-\d+\z/) ? last_id : nil
+        @chat = context.chat
+        @page = page.to_s.match?(Live::Chat::PAGE) ? page : nil
         @clock = clock
-        @sleeper = sleeper
+        @waiter = waiter
       end
 
       # Write events to +out+ until the browser leaves, the server stops, or
@@ -40,21 +85,35 @@ module OpenLanes
       # @param out [#<<, #closed?]
       # @return [void]
       def run(out)
+        @chat&.attach(@page) if @page
+        news = subscribe
         started = @clock.call
         pinged = started
         cursor = @last_id || newest_reply
         out << self.class.frame("cursor", { id: cursor }, id: cursor)
+        said = @copilot.newest
+        out << self.class.frame("copilot_cursor", { id: said }) unless out.closed?
+        # The page is attached, so every chat event from here on is queued for
+        # it: a `GET /api/chat` the page starts on this misses nothing.
+        out << self.class.frame("chat_cursor", {}) if @chat && @page && !out.closed?
+        apps = open_apps(out)
         seqs = nil
         until over?(out, started)
           seqs = board(out, seqs)
+          apps = app_news(out, apps)
           cursor = replies(out, cursor)
+          said = copilot(out, said)
+          chat(out)
           pinged = ping(out) if @clock.call - pinged >= @context.ping_every
-          @sleeper.call(@context.tick)
+          wait(news, started, pinged)
         end
       rescue Live::Unavailable => e
         # Ending the stream is the right answer: the page reconnects with
         # backoff and shows itself as reconnecting meanwhile.
         out << ": #{e.message.tr("\n", " ")}\n\n"
+      ensure
+        news&.close
+        @chat&.detach(@page) if @page
       end
 
       # @param event [String]
@@ -65,11 +124,45 @@ module OpenLanes
 
       private
 
+      # The stream's subscription to nudges, or nil to poll. A Redis user
+      # whose ACL withholds SUBSCRIBE got a working polled board before
+      # nudges existed, and ending the stream instead would leave its page
+      # reconnecting forever. A Redis that is gone fails the first read
+      # just after, and ends the stream there.
+      #
+      # @return [OpenLanes::Live::Subscriber, OpenLanes::Live::MemorySubscriber, nil]
+      def subscribe
+        Live::News.subscribe(store: @store, keys: @keys)
+      rescue Live::Unavailable => e
+        UI.log("events: no nudges, polling every #{POLL}s: #{e.message}", level: :warn)
+        nil
+      end
+
       # @return [Boolean]
       def over?(out, started)
         out.closed? || @context.stopping.true? || (@context.lifetime && @clock.call - started >= @context.lifetime)
       end
 
+      # Sleep until a nudge, the next ping, or the end of the stream's
+      # lifetime, whichever comes first. One nudge, one look: a nudge that
+      # arrives while the stream is reading stays queued and wakes the next
+      # wait at once, so nothing written during a look is missed. Queued
+      # nudges are not drained first because the drain costs more than it
+      # saves: redis-client cannot poll without waiting, so emptying the
+      # queue costs {Live::Subscriber::SHORTEST} on every wake, ten times
+      # what an extra look costs, and a tick nudges once or twice at most.
+      #
+      # @param news [OpenLanes::Live::Subscriber, OpenLanes::Live::MemorySubscriber]
+      # @param started [Float]
+      # @param pinged [Float]
+      # @return [void]
+      def wait(news, started, pinged)
+        now = @clock.call
+        limits = [@context.ping_every - (now - pinged)]
+        limits << (@context.lifetime - (now - started)) if @context.lifetime
+        @waiter.call(news, [limits.min, 0].max)
+      end
+
       # @return [Array] the seqs now, after sending the board if they changed
       def board(out, seqs)
         board = Live.board(store: @store, keys: @keys)
@@ -78,6 +171,25 @@ module OpenLanes
         now
       end
 
+      # @return [Hash{Array(String, String) => Hash}] what was sent, by plan and process
+      def open_apps(out)
+        now = live_apps
+        out << self.class.frame("apps", { apps: now.values }) unless now.empty? || out.closed?
+        now
+      end
+
+      # @param sent [Hash{Array(String, String) => Hash}]
+      # @return [Hash{Array(String, String) => Hash}]
+      def app_news(out, sent)
+        now = live_apps
+        now.each { |key, app| out << self.class.frame("app", app) unless sent[key] == app }
+        sent.except(*now.keys).each_value { out << self.class.frame("app", it.merge("state" => "stopped")) }
+        now
+      end
+
+      # @return [Hash{Array(String, String) => Hash}]
+      def live_apps = Apps::Listing.read(store: @store, keys: @keys).to_h { [[it["plan"], it["process"]], it] }
+
       # @return [String] the last reply id sent
       def replies(out, cursor)
         Live.replies(store: @store, keys: @keys, after: cursor).each do |id, reply|
@@ -87,6 +199,22 @@ module OpenLanes
         cursor
       end
 
+      # @return [String] the last copilot turn's stream id sent
+      def copilot(out, said)
+        @copilot.since(said).each do |id, turn|
+          out << self.class.frame("copilot", turn)
+          said = id
+        end
+        said
+      end
+
+      # @return [void]
+      def chat(out)
+        return unless @chat && @page
+
+        @chat.drain(@page).each { out << self.class.frame("chat", it) }
+      end
+
       # @return [Float] when it pinged
       def ping(out)
         out << ": ping\n\n"

data/lib/openlanes/web/launcher.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "socket"
 require "tmpdir"
 
 module OpenLanes
@@ -26,19 +27,35 @@ module OpenLanes
       # Seconds {#stop} gives the server after TERM before KILL.
       STOP_WITHIN = 5.0
 
+      # Ports {#start} tries, from the one asked for, before giving up.
+      PORTS_TRIED = 10
+
       # @param root [String] the checkout the run works in
       # @param plans_dir [String]
       # @param port [Integer]
       # @param redis_url [String]
-      # @param log [String] where the server's output goes
+      # @param log [String] where the server's raw STDOUT and STDERR go: a
+      #   crash before its logger is up, and Puma's own complaints
+      # @param logging [OpenLanes::Log::Settings, nil] where the server logs
+      #   its requests; the engine's own, so both processes write one file
       # @param ready_within [Float]
       # @param probe [Proc, nil] answers whether the server is up; `/healthz` by default
-      def initialize(root:, plans_dir:, port:, redis_url:, log: default_log(root), ready_within: READY_WITHIN, probe: nil)
+      # @param listen [OpenLanes::Web::Listen] the addresses the server listens on
+      # @param credentials [OpenLanes::Web::AdminAuth::Credentials, nil] its
+      #   login for requests from off this machine, handed over in {#env}
+      # @param spawner [#spawn] what starts the server process
+      def initialize(root:, plans_dir:, port:, redis_url:, log: default_log(root), logging: Log.settings,
+        ready_within: READY_WITHIN, probe: nil, listen: Listen.parse(nil), credentials: nil,
+        spawner: Spawner::System)
         @root = root
+        @spawner = spawner
         @plans_dir = plans_dir
         @port = Integer(port)
         @redis_url = redis_url
+        @listen = listen
+        @credentials = credentials
         @log = log
+        @logging = logging
         @ready_within = ready_within
         @probe = probe || method(:healthy?)
       end
@@ -49,22 +66,46 @@ module OpenLanes
       # @return [Integer, nil]
       attr_reader :pid
 
+      # @return [Integer] the port asked for, or the free one {#start} moved to
+      attr_reader :port
+
+      # Loopback, where the login is never asked. Every server it launches
+      # answers there: on loopback by default, and on a wildcard under -I.
+      #
       # @return [String]
       def url = "http://#{HOST}:#{@port}"
 
-      # @return [Array<String>] what is spawned; the Redis URL is in {#env}, never here
+      # @return [Array<String>] what is spawned; the Redis URL and the
+      #   credentials are in {#env}, never here
       def argv
-        [EXE, "web", "--port", @port.to_s, "--no-open", "--dir", @plans_dir]
+        ips = @listen.public? ? ["--ips", @listen.ips.join(",")] : []
+        [EXE, "web", "--port", @port.to_s, "--no-open", "--dir", @plans_dir, *ips]
       end
 
+      # The Redis URL, the login, and where to log. A server left to find its
+      # own log would resolve `log/development.log` from its own root and
+      # defaults, and a `--log` typed on `run` would move the engine's lines
+      # but not the server's.
+      #
       # @return [Hash{String => String}] added to the server's environment
-      def env = { REDIS_URL_ENV => @redis_url }
+      def env
+        login = @credentials ? { AdminAuth::ENV_NAME => "#{@credentials.user}:#{@credentials.password}" } : {}
+        { REDIS_URL_ENV => @redis_url, **login, **(@logging ? @logging.env : {}) }
+      end
 
-      # Spawn the server and wait for it to answer.
+      # Spawn the server on the first free port from the one asked for, and
+      # wait for it to answer. A taken port is skipped before spawning, never
+      # probed: a leftover `openlanes web` for another project answers
+      # `/healthz` there, and the run once declared that server its own and
+      # opened the browser on someone else's board.
       #
       # @return [self]
       def start
-        @pid = Process.spawn(env, *argv, chdir: @root, pgroup: true, in: File::NULL, %i[out err] => [@log, "a"])
+        free = free_port
+        return taken unless free
+
+        @port = free
+        @pid = @spawner.spawn(env, *argv, chdir: @root, pgroup: true, in: File::NULL, %i[out err] => [@log, "a"])
         @ready = wait_until_ready
         self
       end
@@ -88,6 +129,27 @@ module OpenLanes
 
       private
 
+      # @return [Integer, nil]
+      def free_port = (@port...(@port + PORTS_TRIED)).find { free?(it) }
+
+      # @param port [Integer]
+      # @return [Boolean] whether nothing listens there
+      def free?(port)
+        TCPServer.new(HOST, port).close
+        true
+      rescue SystemCallError
+        false
+      end
+
+      # Every port tried is taken: said in the log {#start}'s caller points at.
+      #
+      # @return [self]
+      def taken
+        File.write(@log, "Ports #{@port}-#{@port + PORTS_TRIED - 1} are all taken. Pass --port to use another.\n", mode: "a")
+        @ready = false
+        self
+      end
+
       # @return [Boolean]
       def wait_until_ready
         deadline = monotonic + @ready_within
@@ -137,7 +199,7 @@ module OpenLanes
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       # @return [String]
-      def default_log(root) = File.join(Dir.tmpdir, "openlanes-web-#{File.basename(root)}.log")
+      def default_log(root) = Engine::ProgressLog.default_path(root, kind: "web")
     end
   end
 end

data/lib/openlanes/web/listen.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "socket"
+
+module OpenLanes
+  module Web
+    # The addresses one server listens on, and what follows from them: the
+    # Host headers it answers, the URLs it prints, the one a browser opens.
+    #
+    # Loopback, {HOST}, unless told otherwise (W3). The page can stop agents
+    # and answer their questions, and has no login, so listening beyond this
+    # machine is something a person asks for by name, and is warned about.
+    #
+    #   listen = Listen.parse("0.0.0.0")
+    #   listen.public?             # => true
+    #   listen.urls(11_000)        # => ["http://192.168.1.20:11000", ...]
+    #   listen.browse_url(11_000)  # => "http://127.0.0.1:11000"
+    Listen = Data.define(:ips) do
+      # @return [Boolean] whether anything off this machine can reach it
+      def public? = ips.any? { !IPAddr.new(it).loopback? }
+
+      # @return [Array<String>] the addresses past loopback, as given
+      def public_ips = ips.reject { IPAddr.new(it).loopback? }
+
+      # Where this machine's browser opens the page: loopback, which every
+      # wildcard listener also answers on, else the first address given.
+      #
+      # @param port [Integer]
+      # @return [String]
+      def browse_url(port)
+        ip = ips.find { Listen.wildcard?(it) || IPAddr.new(it).loopback? } || ips.first
+        Listen.url(if Listen.wildcard?(ip)
+                     IPAddr.new(ip).ipv6? ? "::1" : HOST
+                   else
+                     ip
+                   end,
+          port)
+      end
+
+      # Every URL the page answers on, a wildcard spelled out as this
+      # machine's own addresses, since `http://0.0.0.0` opens nothing.
+      #
+      # @param port [Integer]
+      # @param addresses [Array<String>] this machine's interface addresses
+      # @return [Array<String>]
+      def urls(port, addresses: Listen.addresses) = reached(addresses).map { Listen.url(it, port) }
+
+      # The Host headers answered beside loopback, which {App} always
+      # permits: each address listened on, a wildcard's interfaces, and this
+      # machine's name. Anything else is refused, so a page on another site
+      # still cannot reach the server through DNS rebinding.
+      #
+      # @param addresses [Array<String>]
+      # @param hostname [String]
+      # @return [Array<String, IPAddr>]
+      def permitted_hosts(addresses: Listen.addresses, hostname: Socket.gethostname)
+        return [] unless public?
+
+        names = [hostname, hostname.split(".").first].uniq
+        names + reached(addresses).map { IPAddr.new(it) }
+      end
+
+      private
+
+      # @param addresses [Array<String>]
+      # @return [Array<String>] the addresses listened on, each wildcard
+      #   replaced by the interface addresses it answers on
+      def reached(addresses) = ips.flat_map { Listen.wildcard?(it) ? Listen.covered(it, addresses) : [it] }.uniq
+    end
+
+    class Listen
+      # Raised for an address that is not one.
+      class Invalid < OpenLanes::Error; end
+
+      # What `-I` stands for.
+      EVERYWHERE = "0.0.0.0"
+
+      class << self
+        # An address a wildcard given beside it already covers is dropped:
+        # Linux refuses to bind `127.0.0.1` on a port `0.0.0.0` holds, even
+        # with SO_REUSEADDR, and the EADDRINUSE read as "port taken".
+        #
+        # @param text [String, nil] comma-separated addresses; blank for {HOST}
+        # @return [Listen]
+        # @raise [Invalid] naming the address that is not one
+        def parse(text)
+          ips = text.to_s.split(",").map(&:strip).reject(&:empty?)
+          ips = [HOST] if ips.empty?
+          ips.each do |ip|
+            IPAddr.new(ip)
+          rescue IPAddr::Error
+            raise Invalid, "#{ip.inspect} is not an IP address"
+          end
+          ips = ips.uniq
+          wildcards = ips.select { wildcard?(it) }
+          new(ips: ips.reject { |ip| wildcards.any? { it != ip && covered(it, [ip]).any? } })
+        end
+
+        # @param ip [String]
+        # @return [Boolean] whether it means every interface
+        def wildcard?(ip) = IPAddr.new(ip).to_i.zero?
+
+        # @param ip [String]
+        # @param port [Integer]
+        # @return [String]
+        def url(ip, port) = "http://#{IPAddr.new(ip).ipv6? ? "[#{ip}]" : ip}:#{port}"
+
+        # The interface addresses a wildcard answers on. `0.0.0.0` is IPv4
+        # only; `::` is both, because Ruby's TCPServer leaves IPV6_V6ONLY
+        # off, so Linux and macOS hand it IPv4 clients too. Treating `::` as
+        # IPv6 alone refused an IPv4 LAN client's Host header with a 403.
+        #
+        # @param wildcard [String] `0.0.0.0` or `::`
+        # @param addresses [Array<String>]
+        # @return [Array<String>]
+        def covered(wildcard, addresses)
+          return addresses if IPAddr.new(wildcard).ipv6?
+
+          addresses.select { IPAddr.new(it).ipv4? }
+        end
+
+        # This machine's interface addresses, loopback first, link-local
+        # IPv6 left out: it needs a zone to be dialed, which no URL carries.
+        #
+        # @return [Array<String>]
+        def addresses
+          Socket.ip_address_list.reject(&:ipv6_linklocal?).map(&:ip_address).sort_by { IPAddr.new(it).loopback? ? 0 : 1 }
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/web/plan_files.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "securerandom"
+
+module OpenLanes
+  module Web
+    # The plan files the page may read, and the two it may write (plan 017).
+    #
+    # A name is looked up in {READABLE} and never joined onto a path as typed,
+    # which is what makes `../` meaningless here rather than merely refused.
+    # This knows nothing of HTTP or of cars: {App} maps each refusal to a
+    # status and checks the board before it calls {#write}.
+    class PlanFiles
+      # What the drawer lists and the preview reads, in the order listed.
+      READABLE = %w[spec.md plan.md contract.md blocked.md research.md design.md].freeze
+
+      # What the popup may save. `blocked.md` is appended by the `answer`
+      # command, and the build documents belong to the agents that own them.
+      EDITABLE = %w[spec.md plan.md].freeze
+
+      # Not a readable name, not a plan, or not a file in that plan.
+      class NotFound < OpenLanes::Error; end
+
+      # A readable name the page may not write.
+      class ReadOnly < OpenLanes::Error; end
+
+      # The file changed since the page read it.
+      class Stale < OpenLanes::Error; end
+
+      # The body's frontmatter block is not the one on disk. Frontmatter
+      # routes agents (`lane`, `frontend`, `depth`), so a crafted save must
+      # not reach it even when the page would never send one.
+      class FrontmatterChanged < OpenLanes::Error; end
+
+      # One file as read.
+      #
+      # @!attribute body [String] the raw bytes
+      # @!attribute etag [String] a strong, quoted ETag of those bytes
+      Document = Data.define(:body, :etag)
+
+      class << self
+        # @param body [String]
+        # @return [String] `"<sha256 hex>"`, quotes included, as HTTP sends it
+        def etag(body) = %("#{Digest::SHA256.hexdigest(body.b)}")
+      end
+
+      # @param plans_dir [String] the `.plans` directory
+      def initialize(plans_dir:)
+        @plans_dir = plans_dir
+      end
+
+      # @param ordinal [String] a plan number, as typed in the URL
+      # @return [Array<String>] readable names that exist, in {READABLE} order
+      # @raise [NotFound] when the ordinal is not a plan
+      def list(ordinal)
+        _, folder = folder_for(ordinal)
+        READABLE.select { File.file?(File.join(folder, it)) }
+      end
+
+      # @param ordinal [String]
+      # @param name [String]
+      # @return [Document]
+      # @raise [NotFound]
+      def read(ordinal, name)
+        body = File.binread(path_for(ordinal, name)).force_encoding(Encoding::UTF_8)
+        Document.new(body:, etag: self.class.etag(body))
+      end
+
+      # Replace a whole file, guarded three ways: an editable name, the
+      # ETag the page read, and the frontmatter block unchanged.
+      #
+      # @param ordinal [String]
+      # @param name [String]
+      # @param body [String] the whole new file
+      # @param if_match [String] the ETag the page read
+      # @return [String] the new ETag
+      # @raise [NotFound, ReadOnly, Stale, FrontmatterChanged]
+      def write(ordinal, name, body:, if_match:)
+        path = path_for(ordinal, name)
+        raise ReadOnly, "#{name} is read only" unless EDITABLE.include?(name)
+
+        current = read(ordinal, name)
+        raise Stale, "#{name} changed since it was read; reload it" unless current.etag == if_match.to_s.strip
+        raise FrontmatterChanged, "the frontmatter of #{name} is locked" unless frontmatter(current.body) == frontmatter(body)
+
+        replace(path, body)
+        self.class.etag(body)
+      end
+
+      private
+
+      # The raw frontmatter block, or nil when the file has none. Compared as
+      # bytes, not as parsed YAML, so a reordered key or a changed comment is
+      # a change too.
+      #
+      # @param content [String]
+      # @return [String, nil]
+      def frontmatter(content) = Frontmatter::PATTERN.match(content.b)&.then { it[1] }
+
+      # @param path [String]
+      # @param body [String]
+      # @return [void]
+      def replace(path, body)
+        temp = File.join(File.dirname(path), ".#{File.basename(path)}.#{SecureRandom.hex(6)}.tmp")
+        File.binwrite(temp, body)
+        File.rename(temp, path)
+      ensure
+        FileUtils.rm_f(temp) if temp && File.exist?(temp)
+      end
+
+      # @param ordinal [String]
+      # @param name [String]
+      # @return [String]
+      # @raise [NotFound]
+      def path_for(ordinal, name)
+        known = READABLE.find { it == name } or raise NotFound, "not a plan file: #{name}"
+        number, folder = folder_for(ordinal)
+        path = File.join(folder, known)
+        raise NotFound, "#{number} has no #{known}" unless File.file?(path)
+
+        path
+      end
+
+      # @param ordinal [String]
+      # @return [Array(Plans::Ordinal, String)] the plan number and its folder
+      # @raise [NotFound]
+      def folder_for(ordinal)
+        number = Plans::Ordinal.parse(ordinal.to_s) or raise NotFound, "not a plan number"
+        subject = Plans.tree(@plans_dir).find(number) or raise NotFound, "there is no plan #{number}"
+        [number, subject.feature.path]
+      end
+    end
+  end
+end