proctolog 0.1.1 → 0.3.0

data/app/models/proctolog/doctor.rb

@@ -11,19 +11,29 @@ module Proctolog
     MARKS = {fine: "ok", missing: "!!", off: "--"}.freeze
 
     Finding = Data.define(:state, :line) do
+      def fine? = state == :fine
       def missing? = state == :missing
       def to_s = "#{MARKS.fetch(state)}  #{line}"
     end
 
     NEEDS = %i[ruby gh launcher checkout repository bursts].freeze
-    NICETIES = %i[release skills chrome diffle imagemagick ffmpeg app port].freeze
+    NICETIES = %i[release skills chrome diffle imagemagick ffmpeg app share port].freeze
 
     # project is nil when the directory is no Git checkout.
     def initialize(project, home: Dir.home, path: ENV.fetch("PATH", ""))
       @project, @home, @path = project, Pathname(home), path.split(File::PATH_SEPARATOR)
     end
 
-    def findings = @findings ||= (NEEDS + NICETIES).filter_map { send(it) }
+    def findings = (NEEDS + NICETIES).filter_map { self[it] }
+
+    # One check's finding, by its name, asked once: setup asks a step's
+    # checks alone. Nil for one not asked here, as the repository is not
+    # without gh.
+    def [](check)
+      raise ArgumentError, "Doctor checks no #{check}" unless (NEEDS + NICETIES).include?(check)
+
+      (@checked ||= {}).fetch(check) { @checked[check] = send(check) }
+    end
 
     def fine? = findings.none?(&:missing?)
 
@@ -72,7 +82,7 @@ module Proctolog
     def skills
       folders = %w[.claude/skills .agents/skills].select { |folder| SKILLS.keys.all? { @home.join(folder, it).exist? } }
       missing = SKILLS.reject { |skill, _| %w[.claude/skills .agents/skills].any? { @home.join(it, skill).exist? } }.values
-      if missing.any? then off("The #{missing.to_sentence} #{"skill".pluralize(missing.size)} #{missing.one? ? "is" : "are"} not linked: proctolog install")
+      if missing.any? then off("The #{missing.to_sentence} #{"skill".pluralize(missing.size)} #{missing.one? ? "is" : "are"} not linked: proctolog setup")
       else fine("The #{SKILLS.values.to_sentence} skills, in ~/#{folders.join(" and ~/")}")
       end
     end
@@ -82,7 +92,7 @@ module Proctolog
 
     def chrome
       require "ferrum"
-      Ferrum::Browser::Options::Chrome.options.detect_path ? fine("Chrome, for browser tests and scenarios") : off("No Chrome: browser tests skip and scenarios cannot open")
+      Ferrum::Browser::Options::Chrome.options.detect_path ? fine("Chrome, for browser tests and scenarios") : off("No Chrome, so browser tests skip and scenarios cannot open: brew install --cask google-chrome")
     end
 
     def diffle = command?("diffle") ? fine("Diffle, for d on a pull request") : off("No Diffle, so d opens no code: brew install diffle")
@@ -104,7 +114,15 @@ module Proctolog
       fine("app.yml names #{app.parts.to_sentence}")
     end
 
-    def port = answers?(4040) ? off("Port 4040 answers already: a desk may be open there, or serve --port 4041") : fine("Port 4040 is free")
+    # Tailscale or ngrok, either of which shares the desk with the owner's phone.
+    def share
+      ready, unready = Share.ways(path: @path.join(File::PATH_SEPARATOR)).partition(&:ready?)
+      return fine("Sharing through #{ready.map(&:name).to_sentence}: proctolog share") if ready.any?
+
+      off("Nothing shares the desk beyond this Mac. #{unready.map { "#{it.unready}." }.join(" ")}")
+    end
+
+    def port = Localhost.answers?(4040, within: 1) ? off("Port 4040 answers already: a desk may be open there, or serve --port 4041") : fine("Port 4040 is free")
 
     def fine(line) = Finding.new(:fine, line)
     def missing(line) = Finding.new(:missing, line)
@@ -116,12 +134,5 @@ module Proctolog
     def runnable?(program) = program.include?("/") ? @project.root.join(program).executable? : command?(program)
 
     def succeeds?(*command) = Open3.capture2e({"PATH" => @path.join(File::PATH_SEPARATOR)}, *command).last.success?
-
-    def answers?(port)
-      Socket.tcp("localhost", port, connect_timeout: 1, &:close)
-      true
-    rescue SystemCallError
-      false
-    end
   end
 end

data/app/models/proctolog/github.rb

@@ -240,7 +240,7 @@ module Proctolog
     # when the owner presses the button that shows this command first. An
     # alternate marks store remains a trial, even when a data directory moves.
     def rewrite(number, text)
-      (ENV.key?("PROCTOLOG_MARKS") || ENV.key?("PROCTOLOG_READ_ONLY")) and raise Unreachable, "A trial or read-only desk does not write to GitHub."
+      (Desk.trial? || ENV.key?("PROCTOLOG_READ_ONLY")) and raise Unreachable, "A trial or read-only desk does not write to GitHub."
 
       Tempfile.create(["description", ".md"]) do |file|
         file.write(text)

data/app/models/proctolog/localhost.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Proctolog
+  # This Mac, as a program on it is reached: by a port something answers on.
+  module Localhost
+    # TCPSocket, not Socket.tcp: on macOS 27, Socket.tcp with a connect
+    # timeout takes a port nothing listens on for one that answers.
+    def self.answers?(port, within: 0.5)
+      TCPSocket.new("localhost", port, connect_timeout: within).close
+      true
+    rescue SystemCallError, IO::TimeoutError
+      false
+    end
+  end
+end

data/app/models/proctolog/marks.rb

@@ -20,7 +20,7 @@ module Proctolog
     def self.root = Pathname(ENV.fetch("PROCTOLOG_MARKS") { Project.current.marks })
 
     # A desk with marks of its own is a trial, whose marks are not the owner's.
-    def self.trial? = ENV.key?("PROCTOLOG_MARKS")
+    def self.trial? = Desk.trial?
 
     def self.directory_of(burst) = root.join(burst.slug)
 

data/app/models/proctolog/note.rb

@@ -82,6 +82,10 @@ module Proctolog
     # Still needs someone: the agent while it is open, the owner once addressed.
     def live? = open? || addressed?
 
+    # Answered by an agent in a handover: the owner judges the answer under
+    # Returned work, which moves the note (Rounds#move_notes).
+    def answered_in_a_handover? = reply&.key?("response")
+
     # The decision of a description that this note answers otherwise: a change
     # asked for on words of a box. A question or a remark leaves the box open.
     def answers_in(description) = (description.decision_quoted_by(place) if change? && (place in Quote[section: Description::DECISIONS]))

data/app/models/proctolog/owner.rb

@@ -11,6 +11,9 @@ module Proctolog
 
     def self.git_name = Open3.capture2("git", "config", "--get", "user.name").first.strip
 
+    # The address ngrok lets in when the owner named none (Share::Settings).
+    def self.git_email = Open3.capture2("git", "config", "--get", "user.email").first.strip
+
     def first_name = name.split.first
   end
 end

data/app/models/proctolog/pick.rb

@@ -32,6 +32,18 @@ module Proctolog
 
     def empty? = @pull_requests.empty? && unopened.empty?
 
+    # Those of every kind with decisions for the reviewer, open or not.
+    def written = [*@pull_requests, *unopened].select { written?(it) }
+
+    # What the page first tells someone who has not reviewed here yet, or
+    # who would otherwise find nothing to do: nil once neither is true.
+    def start(first_time:)
+      if empty? then :nothing_open
+      elsif written.none? then :nothing_written
+      elsif first_time then :first_time
+      end
+    end
+
     # Whether a pull request nobody has opened yet sits on another pull
     # request's branch, so that it tops a chain.
     def chained?(pull_request) = [*@pull_requests, *unopened].any? { it.head == pull_request.base }

data/app/models/proctolog/rounds.rb

@@ -46,6 +46,18 @@ module Proctolog
       def newness = [order, Rounds.moment(response[:createdAt])]
     end
 
+    # What came back from an agent on one pull request besides its notes,
+    # which say so themselves once addressed (move_notes): the answers the
+    # owner is to confirm and the questions they are to answer.
+    Returned = Data.define(:to_confirm, :questions) do
+      def initialize(to_confirm: 0, questions: 0) = super
+    end
+
+    # Where a note an agent answered stands in its marks, by where its
+    # request stands: addressed while the answer waits on the owner,
+    # confirmed once they confirmed it, open again once they replied.
+    NOTE_STATES = {owner: "addressed", question: "addressed", closed: "confirmed", agent: "open", out: "open"}.freeze
+
     # A time as a page or an agent wrote it; one that cannot be read is
     # taken for the oldest.
     def self.moment(text)
@@ -93,6 +105,31 @@ module Proctolog
       end
     end
 
+    # What came back to the owner, by pull request.
+    def returned
+      everything.reject { it.dig(:source, :noteId) }.group_by { it[:pr] }.transform_values do |requests|
+        states = requests.group_by { state_of(it) }.tap { it.default = [] }
+        Returned.new(to_confirm: states[:owner].size, questions: states[:question].size)
+      end
+    end
+
+    # Moves each note an agent answered in a handover to where its answer
+    # stands (NOTE_STATES), with the answer as its reply, so the marks say
+    # what Returned work says: to the pages, and to an agent reading them.
+    # A note the owner withdrew stays withdrawn.
+    def move_notes
+      everything.each do |item|
+        id = item.dig(:source, :noteId) or next
+        latest = latest(item) or next
+        to = NOTE_STATES[state_of(item)] or next
+        marks = @burst.marks(item[:pr] || "sitting")
+        note = marks.note(id)
+        next if note.nil? || note.withdrawn? || [note.state, note.reply&.dig("response")] == [to, latest.key]
+
+        marks.move(id, to:, reply: {"text" => latest.result[:summary], "commit" => latest.result[:head]&.first(8), "response" => latest.key}.compact)
+      end
+    end
+
     # What an agent took and has not answered, with the handover it went in.
     def with_agent
       current.select { in_focus?(it[:pr]) && state_of(it) == :out }.map do |item|

data/app/models/proctolog/server.rb

@@ -35,7 +35,7 @@ module Proctolog
     end
 
     # Every port the app listens on answers.
-    def up? = app.listens(port).all? { listening?(it) }
+    def up? = app.listens(port).all? { Localhost.answers?(it) }
 
     def state
       return :up if up?
@@ -179,12 +179,6 @@ module Proctolog
 
     def logs = Project.current.cache.join("servers")
 
-    def listening?(port)
-      Socket.tcp("localhost", port, connect_timeout: 0.5) { true }
-    rescue SystemCallError
-      false
-    end
-
     def git(*) = Open3.capture2e("git", "-C", checkout.to_s, *)
 
     def tip(name)

data/app/models/proctolog/setup.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # From nothing to an open desk, a step at a time: PRoctolog's own links,
+  # then doctor's checks in the order a newcomer meets them, each step saying
+  # why it matters. It explains, links to what to install and checks again
+  # once the owner says a step is done; of anyone else's, it installs
+  # nothing. `proctolog setup` walks it, and `install` is another name for it.
+  #
+  # A step is done when every one of its checks is fine. A nicety that is
+  # off never holds it up: the owner may leave it for later. A need that is
+  # missing does, unless the step says what does its work until then, as the
+  # desk's first page starts a burst.
+  class Setup
+    # first names what the setup does itself before checking the step; asks,
+    # what the owner may type in place of Enter: the step's folder.
+    Step = Data.define(:title, :why, :checks, :advice, :until_then, :first, :asks) do
+      def initialize(title:, why:, checks:, advice: [], until_then: nil, first: nil, asks: nil) = super
+
+      def findings(doctor) = checks.filter_map { doctor[it] }
+
+      # Whether the owner may go on without it: nothing it needs is missing,
+      # or something does that work meanwhile.
+      def leavable?(findings) = until_then.present? || findings.none?(&:missing?)
+
+      def question(findings) = [asks, "Enter checks again", ("l leaves it for later" if leavable?(findings)), "q stops"].compact.join(", ")
+    end
+
+    class << self
+      def steps = @steps ||= []
+
+      private
+
+      def step(title, **) = steps << Step.new(title:, **)
+    end
+
+    step "PRoctolog on this Mac", checks: %i[ruby launcher skills release], first: :link,
+      why: "From wherever this PRoctolog lives, setup links the proctolog command, zsh's completion, and the skills your agents write pull requests and carry out your review with.",
+      until_then: "This setup goes on as it is; a new terminal finds proctolog once your PATH has it."
+
+    step "GitHub, through gh", checks: %i[gh],
+      why: "The desk reads pull requests, their stacks and their checks with your own gh, and writes to GitHub only when you say so."
+
+    step "The checkout you review", checks: %i[checkout repository], asks: "type its folder",
+      why: "The desk opens the pull requests of one checkout, from its GitHub origin, which your gh must be able to read."
+
+    step "A first burst", checks: %i[bursts],
+      why: "A burst is a body of pull requests you review together, a part at a time; the desk keeps your marks by it.",
+      until_then: "Review on the desk's first page starts one."
+
+    step "What turns features on", checks: %i[chrome diffle imagemagick ffmpeg app],
+      why: "Each of these turns one feature on. The desk opens without any of them.",
+      until_then: "Each feature waits for its own."
+
+    step "Your phone, through a share", checks: %i[share],
+      why: "Shared, the desk is yours from your phone or a computer elsewhere, while this Mac keeps it and an agent works on.",
+      advice: [
+        "Tailscale keeps the desk off the internet: only the devices signed in to your tailnet reach it, your phone among them once it has the Tailscale app. Install it from https://tailscale.com/download/mac.",
+        "ngrok puts the desk on the internet, behind its sign-in with Google, for your email alone; its free plan carries 1 GB a month. Install it from https://ngrok.com/download, then copy your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken and run ngrok config add-authtoken TOKEN.",
+        "Either one is enough. Once the desk is open, proctolog share shares it."
+      ]
+
+    INDENT = " " * 8
+    WIDTH = 78
+
+    # The folder setup takes the checkout from: where it started, or the one
+    # the owner typed at its step.
+    attr_reader :directory
+
+    # installation links PRoctolog's own files. doctor gives a fresh Doctor
+    # for a folder each time it is called, so that a step checked again sees
+    # what the owner just did.
+    def initialize(installation:, directory: Dir.pwd, input: $stdin, output: $stdout, &doctor)
+      @installation, @directory, @input, @output, @doctor = installation, Pathname(directory), input, output, doctor
+    end
+
+    def steps = self.class.steps
+
+    # Asks at each step that is not done yet, and checks it again on Enter.
+    # :serve when the owner asked for the desk to open now, :finished when
+    # it is left for later or one answers already, :stopped when they
+    # stopped on the way.
+    def walk
+      say "PRoctolog, a step at a time: each says why it matters, and is stamped DONE", "once it is met. Of anyone else's, nothing is installed for you: a step says", "what to do, and Enter checks it again once you have."
+      steps.each.with_index(1) { |step, number| taken(step, number) or return :stopped }
+      desk
+    end
+
+    # Every step as it stands, asking nothing: for an agent, or a pipe.
+    # True when the desk can open: no step waits on a need.
+    def show
+      shown = steps.each.with_index(1).map { |step, number| shown(step, number) }
+      the_desk
+      lines [doctor[:port]]
+      say(*wrapped("Run proctolog setup in a terminal to take it a step at a time, or proctolog serve to open the desk."))
+      shown.all?
+    end
+
+    private
+
+    def doctor = @doctor.call(directory)
+
+    def taken(step, number)
+      begun(step, number)
+      advised = false
+      loop do
+        findings = step.findings(doctor)
+        lines findings
+        return stamp("DONE") if findings.all?(&:fine?)
+
+        advise(step) unless advised
+        advised = true
+        answer = ask(step.question(findings))
+        case answer&.downcase
+        in "q" | nil then return stopped(number)
+        in "l" then (return stamp("LATER", step.until_then) if step.leavable?(findings))
+        in "" then next
+        else @directory = Pathname(File.expand_path(answer, directory)) if step.asks
+        end
+      end
+    end
+
+    def shown(step, number)
+      begun(step, number)
+      findings = step.findings(doctor)
+      lines findings
+      return stamp("DONE") if findings.all?(&:fine?)
+
+      advise(step)
+      stamp("TO DO", step.until_then)
+      step.leavable?(findings)
+    end
+
+    def begun(step, number)
+      heading(step.title, number, why: step.why)
+      send(step.first) if step.first
+    end
+
+    # PRoctolog's own links, made fresh before its first step is checked.
+    # One in the way that is someone else's stays, and is said.
+    def link
+      @installation.install.each { say "#{INDENT}#{it.gsub(Dir.home, "~")}" }
+    rescue Installation::Refused => e
+      say(*wrapped("!!  #{e.message}"))
+    end
+
+    # The last step: the desk itself, opened by the owner's Enter.
+    def desk
+      the_desk
+      port = doctor[:port]
+      lines [port]
+      return :finished unless port.fine?
+
+      (ask("Enter opens the desk, q leaves it for proctolog serve") == "") ? :serve : :finished
+    end
+
+    def the_desk = heading("The desk", steps.size + 1, why: "It opens on this Mac at #{Desk.address(4040)}; after the first visit, typing procto in the address bar finds it.")
+
+    def stopped(number)
+      say "", "Stopped at step #{number}. proctolog setup starts again from the first, and stamps each step that is done."
+      false
+    end
+
+    def heading(title, number, why: nil)
+      say "", format("%-8s%s", "#{number} of #{steps.size + 1}", title)
+      say(*wrapped(why)) if why
+    end
+
+    def lines(findings) = findings.each { say "#{INDENT}#{it}" }
+
+    def advise(step) = step.advice.each { say(*wrapped(it)) }
+
+    def stamp(word, after = nil)
+      say "#{INDENT}[ #{word} ]#{" #{after}" if after}"
+      true
+    end
+
+    def ask(question)
+      @output.print "#{INDENT}#{question.upcase_first} > "
+      @output.flush
+      @input.gets&.strip
+    end
+
+    # A long line broken at spaces under the step's title; a word too long
+    # for the line, an address, stays whole.
+    def wrapped(text) = text.scan(/\S.{0,#{WIDTH - INDENT.size - 1}}(?=\s|\z)|\S+/).map { INDENT + it }
+
+    def say(*lines) = @output.puts(*lines)
+  end
+end

data/app/models/proctolog/share/ngrok.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "yaml"
+
+module Proctolog
+  class Share
+    # ngrok: the desk on the internet, at the address ngrok gives the account
+    # (on the free plan, one that stays the same), behind ngrok's sign-in with
+    # Google, which lets in only the addresses the owner allows: their Git
+    # email unless they named others. ngrok runs in the background on its own
+    # until the share is closed, the desk running or not, and keeps its log
+    # beside the share's file. It opens no inspector on this Mac, which would
+    # take 4040 or the port after it, a desk's.
+    class Ngrok
+      DOWNLOAD = "https://ngrok.com/download"
+      AUTHTOKEN = "https://dashboard.ngrok.com/get-started/your-authtoken"
+      WAIT = 20
+
+      def initialize(path: ENV.fetch("PATH", ""))
+        @program = path.split(File::PATH_SEPARATOR).map { File.join(it, "ngrok") }.find { File.executable?(it) }
+      end
+
+      def name = "ngrok"
+
+      def to_param = "ngrok"
+
+      def who = "only #{allowed.to_sentence(two_words_connector: " or ", last_word_connector: ", or ")}, signed in with Google, gets in"
+
+      def allowed = Settings.current.allowed
+
+      # What to do before it can share the desk; nil when nothing.
+      def unready
+        if !@program then "ngrok is not installed: brew install ngrok, or #{DOWNLOAD}"
+        elsif !authtoken? then "ngrok has no authtoken: copy yours from #{AUTHTOKEN}, then run ngrok config add-authtoken TOKEN"
+        elsif allowed.empty? then "ngrok would let nobody in: name yourself with proctolog share --via ngrok --allow EMAIL"
+        end
+      end
+
+      def ready? = unready.nil?
+
+      def open(port)
+        Share.folder.mkpath
+        log = Share.folder.join("#{port}.ngrok.log").tap { it.delete if it.exist? }
+        process = Process.spawn(Outside.environment, @program, "http", "http://localhost:#{port}", "--config", [config, quiet].join(","),
+          "--oauth", "google", *allowed.flat_map { ["--oauth-allow-email", it] }, "--log", log.to_s, "--log-format", "json",
+          in: File::NULL, out: File::NULL, err: File::NULL, pgroup: true)
+        Process.detach(process)
+        Share.new(port:, way: self, address: started(log, process), process:)
+      end
+
+      def close(share) = (stop(share.process) if carrying?(share))
+
+      # Its process is still this share's ngrok, not another program given
+      # the same number since.
+      def carrying?(share)
+        share.process.present? && Open3.capture3("ps", "-o", "command=", "-p", share.process.to_s).first.include?("ngrok http http://localhost:#{share.port} ")
+      end
+
+      private
+
+      # What ngrok logged until its address, or its reason for giving none.
+      def started(log, process)
+        deadline = WAIT.seconds.from_now
+        while Time.current < deadline
+          lines = log.exist? ? log.each_line.filter_map { logged(it) } : []
+          if (tunnel = lines.find { it["msg"] == "started tunnel" }) then return tunnel.fetch("url")
+          elsif (failure = lines.find { it["lvl"] == "crit" }) then raise Refused, said(failure.fetch("err", ""))
+          elsif !alive?(process) then raise Refused, "ngrok stopped before it gave the desk an address: #{log}."
+          end
+          sleep 0.1
+        end
+        stop(process)
+        raise Refused, "ngrok gave the desk no address within #{WAIT} seconds: #{log}."
+      end
+
+      # A line of ngrok's log; nil for one it had not finished writing.
+      def logged(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # ngrok's first sentence, and its error's code, which its docs explain.
+      def said(error) = "ngrok said: #{error.lines.first.to_s.strip.chomp(".")}#{" (#{error[/ERR_NGROK_\d+/]})" if error[/ERR_NGROK_\d+/]}."
+
+      def alive?(process)
+        Process.kill(0, process)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+
+      # The whole group: ngrok, and whatever it started.
+      def stop(process)
+        Process.kill("TERM", -process)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      def authtoken? = ENV["NGROK_AUTHTOKEN"].present? || own_settings.then { it["authtoken"] || it.dig("agent", "authtoken") }.present?
+
+      # ngrok's own configuration, where `ngrok config add-authtoken` wrote.
+      def config
+        @config ||= Open3.capture2e(Outside.environment, @program, "config", "check").first[/configuration file at (.+\.yml)/, 1] ||
+          File.expand_path("~/Library/Application Support/ngrok/ngrok.yml")
+      end
+
+      def own_settings = File.file?(config) ? (YAML.safe_load_file(config) || {}) : {}
+
+      # Read over ngrok's own, in the same version: no inspector.
+      def quiet
+        Share.folder.join("ngrok.yml").tap do |file|
+          file.write((own_settings["version"].to_s == "3") ? {"version" => 3, "agent" => {"web_addr" => false}}.to_yaml : {"version" => "2", "web_addr" => false}.to_yaml)
+        end.to_s
+      end
+    end
+  end
+end

data/app/models/proctolog/share/settings.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Proctolog
+  class Share
+    # What the owner chose about sharing, for every checkout on this Mac: the
+    # way they last named, and the addresses ngrok lets in. Kept in share.yml
+    # beside the desk's secret.
+    class Settings < Data.define(:via, :allow)
+      def self.file = Desk.data.join("share.yml")
+
+      def self.current = new(**(file.file? ? (YAML.safe_load_file(file) || {}) : {}).symbolize_keys.slice(:via, :allow))
+
+      def initialize(via: nil, allow: []) = super(via:, allow: Array(allow).map { it.to_s.strip.downcase }.compact_blank.uniq)
+
+      def save = self.class.file.tap { it.dirname.mkpath }.write({"via" => via, "allow" => allow}.compact_blank.to_yaml)
+
+      # Those named, or the owner as Git knows them, as Google spells an address.
+      def allowed = allow.presence || [Owner.git_email.downcase].compact_blank
+    end
+  end
+end

data/app/models/proctolog/share/tailscale.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "uri"
+
+module Proctolog
+  class Share
+    # Tailscale's serve: the desk at this Mac's own name on the owner's
+    # tailnet, https://mac.tailnet.ts.net, which only the devices signed in to
+    # that tailnet reach. Nothing goes on the internet, and Tailscale is the
+    # sign-in. Tailscale keeps serving it, the desk running or not, until the
+    # share is closed.
+    class Tailscale
+      DOWNLOAD = "https://tailscale.com/download/mac"
+      CERTIFICATES = "https://login.tailscale.com/admin/dns"
+      # The app's own program, for a Mac that never put tailscale on its PATH.
+      APP = "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+      # The first share of a tailnet can wait on its owner turning Serve on, in a browser.
+      WAIT = 20
+
+      def initialize(path: ENV.fetch("PATH", ""), app: APP)
+        @program = path.split(File::PATH_SEPARATOR).map { File.join(it, "tailscale") }.find { File.executable?(it) } ||
+          (app if File.executable?(app))
+      end
+
+      def name = "Tailscale"
+
+      def to_param = "tailscale"
+
+      # By the tailnet's name: one account can be in several, and a phone
+      # signed in to another one never sees this Mac.
+      def who = "only devices signed in to your tailnet#{", #{tailnet}," if tailnet} reach it"
+
+      def tailnet = status.dig("CurrentTailnet", "Name")
+
+      # What to do before it can share the desk; nil when nothing.
+      def unready
+        return "Tailscale is not installed: #{DOWNLOAD}" unless @program
+
+        case status["BackendState"]
+        when "Running" then ("Tailscale gives your tailnet no HTTPS certificates: turn them on at #{CERTIFICATES}" if status["CertDomains"].blank?)
+        when "NeedsLogin", "NeedsMachineAuth" then "Tailscale is signed out: sign in from its icon in the menu bar"
+        else "Tailscale is off: turn it on from its icon in the menu bar"
+        end
+      end
+
+      def ready? = unready.nil?
+
+      # On 443, the tailnet name itself, unless Tailscale serves something
+      # else there; then on the desk's own port.
+      def open(port)
+        https = served.fetch("TCP", {}).key?("443") ? port : 443
+        run("serve", "--bg", "--yes", "--https=#{https}", "http://localhost:#{port}")
+        Share.new(port:, way: self, address: "https://#{status.dig("Self", "DNSName").to_s.chomp(".")}#{":#{https}" unless https == 443}")
+      end
+
+      def close(share) = run("serve", "--https=#{URI(share.address).port}", "off")
+
+      def carrying?(share)
+        address = URI(share.address)
+        served.dig("Web", "#{address.host}:#{address.port}", "Handlers", "/", "Proxy") == "http://localhost:#{share.port}"
+      end
+
+      private
+
+      def status = @status ||= asked("status", "--json")
+
+      def served = asked("serve", "status", "--json")
+
+      # Tailscale's answer as JSON; empty when it gave none, as a stopped one does.
+      def asked(*arguments)
+        output, = Open3.capture3(Outside.environment, @program, *arguments)
+        JSON.parse(output)
+      rescue JSON::ParserError, SystemCallError
+        {}
+      end
+
+      def run(*arguments)
+        Open3.popen3(Outside.environment, @program, *arguments) do |input, output, errors, waiter|
+          input.close
+          said = [output, errors].map { |stream| Thread.new { stream.read } }
+          finished = waiter.join(WAIT)
+          Process.kill("TERM", waiter.pid) unless finished
+          words = said.map(&:value).join
+          raise Refused, refusal(words) unless finished&.value&.success?
+
+          words
+        end
+      end
+
+      # Serve asks a tailnet's owner once to turn it on, at an address it
+      # prints, and waits.
+      def refusal(words)
+        if (address = words[%r{https://login\.tailscale\.com/\S+}])
+          "Tailscale waits for Serve to be turned on for your tailnet: #{address}, then share again."
+        else
+          "Tailscale said: #{words.lines.grep_v(/\AWarning:|TPM/).join(" ").squish.chomp(".").presence || "nothing, and served nothing"}."
+        end
+      end
+    end
+  end
+end