proctolog 0.1.1 → 0.3.0

data/app/models/proctolog/share.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "uri"
+require "yaml"
+
+module Proctolog
+  # The desk reached from away from this Mac, by its owner alone: from their
+  # phone, or a computer elsewhere, through whichever of Tailscale or ngrok
+  # this Mac has. Tailscale lets in the devices of the owner's own tailnet
+  # and puts nothing on the internet; ngrok puts the desk there behind its
+  # sign-in with Google, for the addresses the owner allows.
+  #
+  # A share is of the desk on one port, kept as a file in the cache by that
+  # port. It stays open until it is closed, across the desk's restarts, and
+  # while its file says so the desk answers to the share's name as to its own.
+  # `who` is whom it lets in, as it was opened.
+  class Share < Data.define(:port, :way, :address, :who, :process)
+    Refused = Class.new(StandardError)
+
+    def initialize(port:, way:, address:, who: way.who, process: nil) = super
+
+    class << self
+      # The ways this Mac could share the desk, Tailscale first: it puts
+      # nothing on the internet.
+      def ways(path: ENV.fetch("PATH", "")) = [Tailscale.new(path:), Ngrok.new(path:)]
+
+      # The share of the desk on port, while its way still carries it. One
+      # whose way let it go (ngrok ended with the Mac's restart, say) is
+      # forgotten.
+      def at(port, ways: self.ways)
+        kept(port, ways:)&.then do |share|
+          next share if share.way.carrying?(share)
+
+          file(port).delete
+          nil
+        end
+      end
+
+      # As its file says, without asking its way: for every page of a burst,
+      # which says whether the desk is shared.
+      def kept(port, ways: self.ways)
+        record = recorded(port) or return
+        way = ways.find { it.to_param == record["way"] } or return
+
+        new(port:, way:, address: record["address"], who: record.fetch("who") { way.who }, process: record["process"])
+      end
+
+      # Shares the desk on port through the way named, which is remembered,
+      # or the one last named while it is ready, or the first one ready.
+      # `allow` names whom ngrok lets in from now on. A share already open is
+      # only answered. A trial desk, on marks of its own, is never shared: it
+      # tries a change on this Mac, and its settings are the owner's.
+      def open(port, via: nil, allow: nil, ways: self.ways)
+        raise Refused, "A trial desk is not shared: it is for trying a change on this Mac." if Desk.trial?
+
+        Settings.current.with(allow:).save if allow
+        at(port, ways:) || chosen(via, ways).open(port).tap do
+          it.keep
+          Settings.current.with(via:).save if via
+        end
+      end
+
+      # Whether a request came through the desk's share: by the name it was
+      # asked for. Read from the file alone, as every request from away asks.
+      def carries?(request, port: Desk.port) = recorded(port)&.then { URI(it["address"]).host.casecmp?(request.host) } || false
+
+      def folder = Desk.cache.join("shares")
+
+      def file(port) = folder.join("#{port}.yml")
+
+      private
+
+      def recorded(port) = file(port).then { YAML.safe_load_file(it) if it.file? }
+
+      def chosen(via, ways)
+        if via
+          way = ways.find { it.to_param == via } or raise Refused, "The desk is shared through #{ways.map(&:to_param).to_sentence(last_word_connector: " or ", two_words_connector: " or ")}, not #{via}."
+          way.ready? ? way : raise(Refused, "#{way.unready}.")
+        else
+          remembered = Settings.current.via
+          ways.find { it.to_param == remembered && it.ready? } || ways.find(&:ready?) || raise(Refused, unshareable(ways))
+        end
+      end
+
+      def unshareable(ways) = "Neither #{ways.map(&:name).join(" nor ")} can share the desk yet. #{ways.map { "#{it.unready}." }.join(" ")}"
+    end
+
+    def keep = file.tap { it.dirname.mkpath }.write({"way" => way.to_param, "address" => address, "who" => who, "process" => process}.compact.to_yaml)
+
+    def close
+      way.close(self)
+      file.delete if file.exist?
+    end
+
+    def host = URI(address).host
+
+    def file = self.class.file(port)
+
+    def to_s = "The desk is shared at #{address} through #{way.name}: #{who}."
+  end
+end

data/app/models/proctolog/standing.rb

@@ -19,24 +19,43 @@ module Proctolog
     # under it. `scenarios` are the names of this pull request's scenarios, and
     # `named` the preconditions the burst file names for it. `progress` is how
     # far the owner's choices on its decisions are; without one, only the boxes
-    # ticked on GitHub count as reviewed.
-    def initialize(stop:, marks:, progress: nil, under: nil, above: [], scenarios: [], named: [])
-      @stop, @marks, @under, @above, @scenarios, @named = stop, marks, under, above, scenarios, named
+    # ticked on GitHub count as reviewed. `returned` is what came back from an
+    # agent on it.
+    def initialize(stop:, marks:, progress: nil, returned: Rounds::Returned.new, under: nil, above: [], scenarios: [], named: [])
+      @stop, @marks, @returned, @under, @above, @scenarios, @named = stop, marks, returned, under, above, scenarios, named
       @progress = progress || Choices::Progress.of(decisions.index_with(&:ticked))
     end
 
     # Whose move it is: :waiting on something outside, the :agent's, the
-    # :owner's, or nobody's because it is :settled.
+    # :owner's, or nobody's because it is :settled. What came back from the
+    # agent makes it the owner's, whatever else is still with the agent.
     def turn
       if marks.waiting_on then :waiting
+      elsif back_to_owner? then :owner
       elsif for_the_agent.any? then :agent
-      elsif good_to_go? && !changed? && for_the_owner.empty? then :settled
+      elsif good_to_go? && !changed? then :settled
       else :owner
       end
     end
 
     def settled? = turn == :settled
 
+    # What came back from the agent for the owner, in a few words each: the
+    # notes it addressed, its answers to confirm and its questions.
+    def for_the_owner
+      addressed = notes(:addressed).size
+      [*("#{count(addressed, "note")} addressed, to confirm" if addressed.positive?),
+        *("#{@returned.to_confirm} returned, to confirm" if @returned.to_confirm.positive?),
+        *("#{count(@returned.questions, "question")} for you" if @returned.questions.positive?)]
+    end
+
+    def back_to_owner? = for_the_owner.any?
+
+    # Whether it waits for the owner: a blocking decision left, or something
+    # back from the agent. The non-blocking wait for one gesture, and hold
+    # nothing up.
+    def asks_for_owner? = back_to_owner? || progress.blocking_left.positive?
+
     def good_to_go? = marks.good_to_go.present?
 
     # What moved since "good to go" was given: the code, the description, both
@@ -91,8 +110,6 @@ module Proctolog
         *("#{count(stop.open_threads, "review thread")} unresolved" if stop.open_threads.positive?)]
     end
 
-    def for_the_owner = notes(:addressed).any? ? ["#{count(notes(:addressed).size, "note")} addressed, to confirm"] : []
-
     def notes(state) = marks.notes.select { it.state == state.to_s }
 
     def count(number, noun) = "#{number} #{noun.pluralize(number)}"

data/app/views/proctolog/bursts/_line.html.erb

@@ -1,6 +1,6 @@
 <%# locals: (burst:, stop:, standing:) %>
-<%# One pull request of the route, in a line: its number, its title, and at the right whose it is when it is not the owner's, and how far its decisions are. The line the cursor is on opens out: its title in full, what else there is to know of it, and its keys beside it. %>
-<%= tag.li id: "pr-#{stop.number}", data: {stop: "", blocking_left: standing.progress.blocking_left, turn: standing.turn} do %>
+<%# One pull request of the route, in a line: its number, its title, and at the right whether something came back from the agent, or else whose it is when it is not the owner's, and its decisions as beads. The line the cursor is on opens out: its title in full, what else there is to know of it, and its keys beside it. %>
+<%= tag.li id: "pr-#{stop.number}", data: {stop: "", asks: standing.asks_for_owner?, turn: standing.turn} do %>
   <p class="what">
     <%= link_to "##{stop.number}", burst_pull_request_path(burst, stop.number), class: "number" %>
     <%= link_to stop.title, burst_pull_request_path(burst, stop.number), class: "title" %>

data/app/views/proctolog/bursts/_side.html.erb

@@ -1,7 +1,7 @@
 <%# locals: (burst:, at: nil) %>
-<%# The pane at the left of every page of a burst: the plaque the desk is named for, where the desk's pages are, and the route with how far each pull request's decisions are, so the owner always sees where they stand. `at` is the pull request the page is on. Focused on a part, it lists that part, with the key back to the whole burst, and counts what is left in the part against the burst; a pull request opened from outside the part stands apart under it. A page that keeps choices rewrites the counts as they change. data-desk keeps it out of a page's reading order. %>
+<%# The pane at the left of every page of a burst: the plaque the desk is named for, where the desk's pages are, and the route with how far each pull request's decisions are and what came back from the agent, so the owner always sees where they stand. `at` is the pull request the page is on. Focused on a part, it lists that part, with the key back to the whole burst, and counts what is left in the part against the burst; a pull request opened from outside the part stands apart under it. A page that keeps choices rewrites the counts as they change. data-desk keeps it out of a page's reading order. %>
 <% route = burst.route %>
-<% progress = burst.progress(route) %>
+<% standings = burst.standings(route) %>
 <aside class="side" aria-label="The burst" data-desk>
   <div class="head">
     <%= link_to image_tag("/plaque.png", alt: "", class: "plaque"), burst_path(burst), tabindex: -1, aria: {hidden: true} %>
@@ -19,7 +19,7 @@
     <p class="focus">Only <%= focus.part.in_words %> · <%= link_to url_for(part: nil), data: {key: "P"} do %><kbd>P</kbd> the whole burst<% end %></p>
   <% end %>
   <%= tag.p class: "overall", data: {side_overall: "", part_prs: (focus.map(&:number).join(" ") unless focus.whole?)} do %>
-    <%= side_gauge(progress.each_value.sum(Proctolog::Choices::NONE), part: (focus.sum(Proctolog::Choices::NONE) { progress.fetch(it.number) } unless focus.whole?)) %>
+    <%= side_gauge(standings.each_value.sum(Proctolog::Choices::NONE, &:progress), part: (focus.sum(Proctolog::Choices::NONE) { standings.fetch(it).progress } unless focus.whole?)) %>
   <% end %>
   <%# Only how many notices there are: they are read at the head of the route. %>
   <% if (notices = burst.notices).any? %>
@@ -30,14 +30,14 @@
     <h2><%= part_heading(part, route) %></h2>
     <ol class="stops">
       <% route.stops_of(part).each do |stop| %>
-        <%= render "proctolog/bursts/side_stop", burst:, stop:, progress: progress.fetch(stop.number), at: %>
+        <%= render "proctolog/bursts/side_stop", burst:, stop:, standing: standings.fetch(stop), at: %>
       <% end %>
     </ol>
   <% end %>
   <% if (outside = route.at(at)) && !focus.include?(outside) %>
     <h2>Outside this part</h2>
     <ol class="stops">
-      <%= render "proctolog/bursts/side_stop", burst:, stop: outside, progress: progress.fetch(outside.number), at: %>
+      <%= render "proctolog/bursts/side_stop", burst:, stop: outside, standing: standings.fetch(outside), at: %>
     </ol>
   <% end %>
 
@@ -45,5 +45,6 @@
   <%= tag.div class: "read", data: {freshness: burst_freshness_path(burst), read_at: burst.read_at.iso8601} do %>
     <p>GitHub read <%= tag.time read_at_in_words(burst.read_at), datetime: burst.read_at.iso8601 %> · <%= link_to "read again", burst_freshness_path(burst, again: 1, back: request.fullpath), class: "again", data: {key: "r"} %></p>
     <p class="moved" data-moved hidden></p>
+    <%= render "proctolog/shares/line" %>
   <% end %>
 </aside>

data/app/views/proctolog/bursts/_side_stop.html.erb

@@ -1,10 +1,10 @@
-<%# locals: (burst:, stop:, progress:, at:) %>
-<%# One pull request of the pane: its mark, its number, its title and how far its decisions are, marked when the page is about it. Held under the pointer, side.js says the same in words, with its title in full and the way to it on GitHub. %>
+<%# locals: (burst:, stop:, standing:, at:) %>
+<%# One pull request of the pane: ↩ when the agent's answers came back on it, its number, its title and its decisions as beads, marked when the page is about it. Held under the pointer, side.js says the same in words, with its title in full and the way to it on GitHub. %>
 <%= tag.li data: {side_pr: stop.number, github: stop.url}, aria: {current: ("page" if stop.number == at)} do %>
   <%= link_to burst_pull_request_path(burst, stop.number) do %>
-    <span class="mark" data-side-mark><%= side_mark(progress) %></span>
+    <%= side_mark(standing.for_the_owner) %>
     <span class="number"><%= stop.number %></span>
     <span class="title"><%= stop.title %></span>
-    <span class="fraction" data-side-fraction><%= side_fraction(progress) %></span>
+    <span class="decisions" data-side-decisions><%= decision_beads(standing.progress) %></span>
   <% end %>
 <% end %>

data/app/views/proctolog/notes/_card.html.erb

@@ -1,5 +1,5 @@
 <%# locals: (note:, burst:, stop:, where: nil, back: nil, attributes: {}) %>
-<%# One note as a card: what it is, what was said, where it is pinned (`where`), the agent's reply, and the ways to move it along. A press of those comes back to `back` when the page that showed the card gave one. %>
+<%# One note as a card: what it is, what was said, where it is pinned (`where`), the agent's reply, and the ways to move it along. A press of those comes back to `back` when the page that showed the card gave one. A note answered in a handover is confirmed or answered back under Returned work, which moves it (Rounds#move_notes), so it can only be withdrawn here. %>
 <%= tag.li(**{class: "card", data: {kind: note.kind, state: note.state}}.deep_merge(attributes)) do %>
   <p class="meta"><span class="kind"><%= note.kind %></span> <span class="state"><%= note.state %></span></p>
   <p class="text"><%= with_mentions(note.text, burst:) %></p>
@@ -12,8 +12,12 @@
   <% end %>
   <div class="moves">
     <% path = burst_pull_request_note_path(burst, stop.number, note.id) %>
-    <%= button_to "Confirm", path, method: :patch, params: {state: "confirmed", return: back}.compact, class: "quiet" if note.addressed? %>
-    <%= button_to "Reopen", path, method: :patch, params: {state: "open", return: back}.compact, class: "quiet" unless note.open? %>
+    <% if note.answered_in_a_handover? %>
+      <% if note.addressed? %><p class="judged">Confirm it, or answer back, under Returned work.</p><% end %>
+    <% else %>
+      <%= button_to "Confirm", path, method: :patch, params: {state: "confirmed", return: back}.compact, class: "quiet" if note.addressed? %>
+      <%= button_to "Reopen", path, method: :patch, params: {state: "open", return: back}.compact, class: "quiet" unless note.open? %>
+    <% end %>
     <%= button_to "Withdraw", path, method: :patch, params: {state: "withdrawn", return: back}.compact, class: "quiet" unless note.withdrawn? %>
   </div>
 <% end %>

data/app/views/proctolog/open_pull_requests/_side.html.erb

@@ -1,5 +1,5 @@
 <%# locals: (bursts:, read_at:) %>
-<%# The pane at the left where no burst is open: the plaque, where the desk's pages are, and the bursts to open, the newest first, each with how far its decisions are. Those put away stay off it, as on the page. %>
+<%# The pane at the left where no burst is open: the plaque, where the desk's pages are, and the bursts to open, the newest first, each with how many of its decisions wait. Those put away stay off it, as on the page. %>
 <aside class="side" aria-label="The desk" data-desk>
   <div class="head">
     <%= link_to image_tag("/plaque.png", alt: "", class: "plaque"), open_pull_requests_path, tabindex: -1, aria: {hidden: true} %>
@@ -15,10 +15,10 @@
         <% progress = burst.progress(burst.route).each_value.sum(Proctolog::Choices::NONE) %>
         <li>
           <%= link_to burst_path(burst) do %>
-            <span class="mark"><%= side_mark(progress) %></span>
+            <span class="mark"></span>
             <span class="number"></span>
             <span class="title"><%= burst.name %></span>
-            <span class="fraction"><%= side_fraction(progress) %></span>
+            <span class="decisions"><%= decisions_left(progress) %></span>
           <% end %>
         </li>
       <% end %>
@@ -26,5 +26,6 @@
   <% end %>
   <div class="read">
     <p>GitHub read <%= tag.time read_at_in_words(read_at), datetime: read_at.iso8601 %> · <%= link_to "read again", open_pull_requests_path(fresh: 1), class: "again" %></p>
+    <%= render "proctolog/shares/line" %>
   </div>
 </aside>

data/app/views/proctolog/open_pull_requests/_start.html.erb

@@ -0,0 +1,8 @@
+<%# locals: (pick:, repository:, first_time:) %>
+<%# At the head of the page, what to do here: for someone who has not reviewed here yet, or when nothing below has decisions to ask. %>
+<% if (start = pick.start(first_time:)) %>
+  <section class="start" aria-labelledby="start">
+    <h2 id="start">Start here</h2>
+    <%= render "proctolog/open_pull_requests/start/#{start}", pick:, repository: %>
+  </section>
+<% end %>

data/app/views/proctolog/open_pull_requests/index.html.erb

@@ -15,6 +15,8 @@
 </header>
 
 <main class="route pick">
+  <%= render "start", pick: @pick, repository: @repository, first_time: [*@bursts, *@put_away].none?(&:own?) %>
+
   <% if @bursts.any? || @put_away.any? %>
     <h2>Your bursts</h2>
     <ol class="lines">
@@ -36,10 +38,6 @@
     <% end %>
   <% end %>
 
-  <% if @pick.empty? %>
-    <p class="lede">Nothing is open in <%= @repository %>.</p>
-  <% end %>
-
   <% @pick.stacks.each do |stack| %>
     <h2>Stack #<%= stack.number %>, <%= stack.pull_requests.size %> from the bottom up</h2>
     <%= button_to "Review the stack", review_stack_path(stack.number), class: "quiet" %>
@@ -59,7 +57,8 @@
 
   <% if (loose = @pick.loose).any? %>
     <h2><%= @pick.stacks.any? ? "In no stack" : "Pull requests" %></h2>
-    <%= form_with url: bursts_path, method: :post do |form| %>
+    <%# Its "Review alone" buttons post elsewhere, so the form carries the session's token, not one good for bursts_path alone. %>
+    <%= form_with url: bursts_path, method: :post, authenticity_token: form_authenticity_token do |form| %>
       <ol class="lines">
         <% loose.each do |pull_request| %>
           <li>

data/app/views/proctolog/open_pull_requests/start/_first_time.html.erb

@@ -0,0 +1,3 @@
+<%# locals: (pick:, repository:) %>
+<p><%= pluralize(pick.written.size, "pull request") %> below <%= (pick.written.size == 1) ? "is" : "are" %> written for PRoctolog: their facts count the decisions they ask you. Press <b>Review alone</b> on one, <b>Review the stack</b> for a whole stack, or tick a few to review them together.</p>
+<p>Inside, <kbd>?</kbd> shows the keys.</p>

data/app/views/proctolog/open_pull_requests/start/_nothing_open.html.erb

@@ -0,0 +1,3 @@
+<%# locals: (pick:, repository:) %>
+<p>Nothing is open in <%= repository %>, and no branch here waits to be opened.</p>
+<p>The desk reviews pull requests whose descriptions list decisions for you. Ask your agent to “write these PRs for PRoctolog”: it opens them on GitHub, or leaves them on branches here for you to review first. Then <%= link_to "read GitHub again", open_pull_requests_path(fresh: 1) %>.</p>

data/app/views/proctolog/open_pull_requests/start/_nothing_written.html.erb

@@ -0,0 +1,3 @@
+<%# locals: (pick:, repository:) %>
+<p>None of these is written for PRoctolog yet, so the desk has no decisions to ask you. Any of them still opens, to read with its pictures and code.</p>
+<p>For decisions, ask your agent to “rewrite these PRs for PRoctolog”. <code>proctolog check <%= pick.loose.first&.number || pick.stacks.first&.top&.number %></code> says what a description still lacks.</p>

data/app/views/proctolog/shares/_line.html.erb

@@ -0,0 +1,5 @@
+<%# At the foot of the pane at the left: whether the desk is shared, as its file says, and the page to share it or stop. %>
+<% share = Proctolog::Share.kept(Proctolog::Desk.port) %>
+<p class="share">
+  <%= share ? "Shared through #{share.way.name}" : "Only on this Mac" %> · <%= link_to (share ? "see it" : "share it"), share_path(back: request.fullpath), class: "again" %>
+</p>

data/app/views/proctolog/shares/show.html.erb

@@ -0,0 +1,48 @@
+<% content_for :title, "Sharing the desk" %>
+<% content_for :head do %>
+  <link rel="stylesheet" href="/share.css">
+<% end %>
+
+<header class="burst">
+  <h1>Sharing the desk</h1>
+  <p class="lede">
+    Review from your phone, or a computer elsewhere, while this Mac keeps the desk. Only you get in.
+    <%= link_to "Back", @back %>
+  </p>
+</header>
+
+<main class="route share">
+  <% if @share %>
+    <p class="now">Shared at <%= link_to @share.address, @share.address %> through <%= @share.way.name %>: <%= @share.who %>.</p>
+    <p class="hint">It stays shared until you stop it, the desk running or not.<% if Proctolog::Share.carries?(request) %> This page came through it: stopping it closes this page too.<% end %></p>
+    <%= button_to "Stop sharing", share_path, method: :delete, params: {back: @back}, class: "quiet" %>
+  <% else %>
+    <p class="now">Only on this Mac, at <%= link_to Proctolog::Desk.address, Proctolog::Desk.address %>.</p>
+
+    <h2>Share it through</h2>
+    <div class="ways">
+      <% @ways.each do |way| %>
+        <section class="way" aria-label="<%= way.name %>">
+          <h3><%= way.name %></h3>
+          <% if way.ready? %>
+            <%= form_with url: share_path, method: :post do |form| %>
+              <%= form.hidden_field :via, value: way.to_param %>
+              <%= form.hidden_field :back, value: @back %>
+              <%= render "proctolog/shares/ways/#{way.to_param}", way:, form: %>
+              <%= form.button "Share through #{way.name}", class: "quiet" %>
+            <% end %>
+          <% else %>
+            <p class="facts"><%= linked_sentence(way.unready) %>.</p>
+          <% end %>
+        </section>
+      <% end %>
+    </div>
+  <% end %>
+
+  <h2>From a terminal</h2>
+  <p class="hint">
+    <code>proctolog share</code> shares it the way you named last, or the first one ready, and prints the address;
+    <code>proctolog share stop</code> stops it, and <code>proctolog share status</code> says what each way needs.
+    An agent can run them too, on a Mac you left working.
+  </p>
+</main>

data/app/views/proctolog/shares/ways/_ngrok.html.erb

@@ -0,0 +1,6 @@
+<%# locals: (way:, form:) %>
+<p class="facts">At your ngrok account's address, on the internet, behind ngrok's sign-in with Google and a warning page of its own. Its free plan carries 1 GB a month, and every picture and film you open passes through it.</p>
+<p class="allow">
+  <%= form.label :allow, "Who may sign in" %>
+  <%= form.text_field :allow, value: way.allowed.join(", "), spellcheck: false, autocomplete: "off" %>
+</p>

data/app/views/proctolog/shares/ways/_tailscale.html.erb

@@ -0,0 +1,2 @@
+<%# locals: (way:, form:) %>
+<p class="facts">At this Mac's name on your tailnet, and nowhere on the internet. Your phone needs the Tailscale app, signed in to <%= way.tailnet ? "the tailnet #{way.tailnet}" : "the same tailnet" %>: one account can be in more than one.</p>