proctolog 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efc3995bd997f8129593d45bbe4de75341a7b27f43401cb329566ac552baffb5
-  data.tar.gz: 47456fcf6f060778f085e96a41d015e8d2b14c6d3e450178f8122b7bd6295bf6
+  metadata.gz: 7e70671fa7a287f7273aa19d34e110411abdaf6eaa53af119c538e6f9f558b83
+  data.tar.gz: 715e723cad15056e1c5e878e21f89895e10a8a970550a6eb84183e9ccfc2c84a
 SHA512:
-  metadata.gz: f0d7b8c993fe32e7a08c4212de1a30f287c10e0b1ce33a4d58a85c557f172f55a82196098ec6a8b5d894b2c003733809599e1db279a85a67ade37e680de2dae3
-  data.tar.gz: 3b38800d1b7bd1ef1aeb3dc364a87510ab3bf55837c8f3827b5ccc509c870aef742b5a78bbefbe3d2a6acb92cf131e7fde0b6d317e39686dbcef19dc2422dcf2
+  metadata.gz: ab6e65d6dffbb0cf8cfa2b1dd228879e3aae55f32f5118a77873c5e69fab28e840dfce9240cf44d88efc30e59a7cb4b8e271d800e987126e6c3514d60a718109
+  data.tar.gz: 38aa55282ff812f1eb8ff1fe22b6dbff1493f0debfe592c6b57f6e21a0cd6a2b7343ad86d45363202cfa3318070f9116a71039bffec371866a60c2cc8d1680f4

data/CHANGELOG.md

@@ -6,6 +6,40 @@ adds, what it changes and what it fixes. Versions are semantic
 something of you says what under **You do**. Unreleased is what main has that
 no gem has yet.
 
+## 0.3.0
+
+### Added
+
+- `proctolog setup` is the one command to remember: it takes you from
+  wherever you are to an open desk, a step at a time. It links PRoctolog's
+  command, completion and skills, then goes through doctor's checks in the
+  order you meet them, each saying why it matters, checked again when you
+  press Enter, and stamped done or left for later. Outside a checkout, it
+  asks for one. Its sharing step says what Tailscale and ngrok each give, and
+  where to get them. Of anyone else's, it installs nothing
+  ([docs/manual/setup.md](docs/manual/setup.md)). A bare `proctolog`, and
+  `serve` outside a checkout, point to it.
+- `proctolog update` says what's new since the version you had, from this
+  changelog: each change by its first sentence, under Added, Changed and
+  Fixed, and in full what you must do. It starts with the update after this
+  one, as the version you leave is the one that runs it.
+
+### Changed
+
+- `proctolog install` is another name for `setup`: it links as before, then
+  takes you through the rest. After an update it only links, and says what's
+  new.
+- `doctor` says how to install Chrome when it is missing.
+
+### Fixed
+
+- `proctolog update` said it pulled a checkout forward, and to restart the
+  desk, when origin had nothing newer. It says the checkout is the latest now,
+  and changes nothing.
+- On macOS 27 the desk took every port on this Mac for answering: Try it
+  showed the app up and never started it, `doctor` said port 4040 was taken,
+  and `proctolog share start` shared a desk that was not there.
+
 ## 0.2.0
 
 ### Added

data/README.md

@@ -12,16 +12,16 @@ it works.
 
 ## The short version
 
-Install it with [rv](https://rv.dev), then run it from a checkout of the repo
-whose PRs you review:
+With [rv](https://rv.dev), from a checkout of the repo whose PRs you review:
 
 ```sh
-rvx proctolog install
 cd path/to/your-repo
-proctolog doctor   # fix what it marks !!
-proctolog serve    # then open http://proctolog.localhost:4040
+rvx proctolog setup   # a step at a time, to http://proctolog.localhost:4040
 ```
 
+`setup` is the one command to remember: it links PRoctolog's own pieces, says
+what to do about the rest, and opens the desk. `install` is another name for it.
+
 Pick a PR, a stack, or a few ticked ones, and press `?` once you're in. When
 your agent opens PRs, tell it to "write these PRs for PRoctolog", so they come
 with decisions to review. Everything below is the long version.
@@ -41,11 +41,10 @@ brew install diffle imagemagick ffmpeg
 With rv, whatever Ruby your shell or your repo runs:
 
 ```sh
-rvx proctolog install
-proctolog doctor
+rvx proctolog setup
 ```
 
-rv gives PRoctolog a Ruby 4 and gems of its own, and `install` puts a
+rv gives PRoctolog a Ruby 4 and gems of its own, and `setup` puts a
 `proctolog` in `~/.local/bin` that runs it through `rvx`. The apps you review
 keep their own Ruby: what the desk starts for them never sees PRoctolog's.
 rv installs from gem.coop, which mirrors RubyGems.
@@ -54,20 +53,24 @@ With Ruby 4.0 already in your shell:
 
 ```sh
 gem install proctolog
-proctolog install
-proctolog doctor
+proctolog setup
 ```
 
-Either way `install` also links the zsh completion into `~/.zsh/completions`
-and the agent skills (below) into `~/.claude/skills` and `~/.agents/skills`. `doctor`
-says what's missing, a line each, with the fix: `!!` for what the desk can't do
+Either way `setup` first links the zsh completion into `~/.zsh/completions`
+and the agent skills (below) into `~/.claude/skills` and `~/.agents/skills`.
+Then it takes the rest a step at a time: gh, the checkout, a first burst, what
+turns features on, sharing the desk with your phone. Each step says why it
+matters, checks again once you've acted, and is stamped done or left for
+later; the last one opens the desk ([setting up](docs/manual/setup.md)). Run it
+again whenever: what's done is stamped and passed. `doctor` asks the same
+things all at once, a line each with the fix: `!!` for what the desk can't do
 without, `--` for what only turns a feature off.
 
 When a newer PRoctolog is out, the desk says so, and `proctolog update` takes
 it ([versions and updates](docs/manual/updates.md)).
 
 Working on PRoctolog itself? Run it from a checkout instead: clone it, then
-`bundle install && ruby bin/install`, which also puts a `proctolog` that runs
+`bundle install && bin/proctolog setup`, which also puts a `proctolog` that runs
 the checkout in `~/.local/bin`. Keep the checkout where it is, since
 everything links back to it. The desk tells a checkout of a newer release
 too, and `proctolog update` pulls it forward.
@@ -104,7 +107,7 @@ Your review is saved as you go, on your Mac under `~/.local/share/proctolog/`.
 
 PRoctolog finds decisions under a `## Decisions for the owner` heading, one
 checkbox line each. The `proctolog-pr-writing` skill teaches your agent the
-format, and `proctolog install` already put it where the agent looks. Tell it to
+format, and `proctolog setup` already put it where the agent looks. Tell it to
 "write these PRs for PRoctolog", or "rewrite this PR's description for
 PRoctolog" for one that's open. Check a description before publishing it:
 

data/app/controllers/proctolog/application_controller.rb

@@ -2,7 +2,7 @@
 
 module Proctolog
   class ApplicationController < ActionController::Base
-    rescue_from(Github::Unreachable) { render plain: "GitHub did not answer.\n\n#{it.message}", status: :service_unavailable }
+    rescue_from(Github::Unreachable) { render plain: "GitHub did not answer.\n\n#{it.message}\n\nIf gh is not set up on this Mac yet, proctolog setup takes you through it.", status: :service_unavailable }
     rescue_from(ActionController::InvalidAuthenticityToken) do
       redirect_back_or_to root_path, alert: "The desk did not know this page any more, so nothing was saved. Do it once more."
     end

data/app/models/proctolog/doctor.rb

@@ -11,6 +11,7 @@ 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
@@ -23,7 +24,16 @@ module Proctolog
       @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")
@@ -112,7 +122,7 @@ module Proctolog
       off("Nothing shares the desk beyond this Mac. #{unready.map { "#{it.unready}." }.join(" ")}")
     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")
+    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)
@@ -124,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/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/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/bin/proctolog

@@ -157,7 +157,7 @@ module Proctolog
     option :allow, type: :string, repeatable: true, desc: "An email that may sign in through ngrok, in place of your Git email"
     def start
       boot_desk!
-      abort "No desk answers on :#{port}. Start one with the share: proctolog serve --share#{port_option}" unless answers?
+      abort "No desk answers on :#{port}. Start one with the share: proctolog serve --share#{port_option}" unless Localhost.answers?(port, within: 1)
       puts Share.open(port, via: options[:via], allow: options[:allow])
       puts "Stop it with: proctolog share stop#{port_option}"
     rescue Share::Refused => e
@@ -188,13 +188,6 @@ module Proctolog
       def port = options[:port]
 
       def port_option = (" --port #{port}" unless port == 4040)
-
-      def answers?
-        Socket.tcp("localhost", port, connect_timeout: 1, &:close)
-        true
-      rescue SystemCallError
-        false
-      end
     end
   end
 
@@ -205,6 +198,14 @@ module Proctolog
 
     class_option :project, type: :string, aliases: "-C", desc: "The Git checkout whose bursts to open"
 
+    no_commands do
+      # Bare, proctolog shows its commands under the one to start with.
+      def help(command = nil, subcommand = false)
+        puts "New here? proctolog setup takes you to the desk, a step at a time.", "" unless command
+        super
+      end
+    end
+
     desc "burst SUBCOMMAND", "Start a burst of your own, or list the bursts there are"
     subcommand "burst", BurstCommands
 
@@ -233,7 +234,7 @@ module Proctolog
       abort "Port #{options[:port]} is taken. If that is the desk, it is open at #{Desk.address(options[:port])}; " \
             "for a second one: proctolog serve --port #{options[:port] + 1}"
     rescue Project::Missing => e
-      abort e.message
+      abort "#{e.message} New here? proctolog setup takes you to the desk, a step at a time."
     end
 
     desc "route [BURST]", "Print the order to take a burst in"
@@ -318,25 +319,20 @@ module Proctolog
     map %w[-v --version] => :version
     def version = puts("PRoctolog #{VERSION}")
 
-    desc "install", "Link zsh's completion and the agent skills to this PRoctolog"
+    desc "install", "Another name for setup: link this PRoctolog, then set it up a step at a time"
     long_desc <<~TEXT
-      Links zsh's completion into ~/.zsh/completions and the agent skills into ~/.claude/skills and
-      ~/.agents/skills, from wherever this PRoctolog lives: the gem, or the checkout, which also gets its
-      launcher in ~/.local/bin. Leaves anything of the same name that is not PRoctolog's as it is.
-      `update` runs it for the version it installs.
+      Does what `proctolog setup` does, whichever of the two you remember: links the proctolog command, zsh's
+      completion and the agent skills to this PRoctolog, then takes you through the rest a step at a time.
+      `proctolog help setup` says how.
     TEXT
-    def install
-      puts Installation.here.install
-    rescue Installation::Refused => e
-      abort e.message
-    end
+    def install = setup
 
     desc "update", "Install the latest PRoctolog, and link to it"
     long_desc <<~TEXT
       Asks RubyGems for the latest PRoctolog and, when it is newer than this one, installs it the way this one
       was: with `rv tool install` for one rvx runs, with `gem install` otherwise. A checkout is pulled
       forward instead, when it is clean and on origin's own branch, and its bundle installed. Then runs the
-      new one's `install`. A desk open now runs on as it was: restart it to run the new one.
+      new one's `setup`, which links it. A desk open now runs on as it was: restart it to run the new one.
     TEXT
     def update
       installation = Installation.here
@@ -367,7 +363,7 @@ module Proctolog
           system(environment, "rv", "tool", "install", "proctolog@#{latest}", "--gem-server", "#{Release.server}/", exception: true)
           puts taken(latest)
           # rvx runs the newest it holds, which is now this one; rv 0.7 runs no proctolog@VERSION.
-          exec(environment, "rvx", "--no-install", "proctolog", "install")
+          exec(environment.merge(Installation.updating_from(VERSION)), "rvx", "--no-install", "proctolog", "setup")
         end
       end
 
@@ -376,17 +372,20 @@ module Proctolog
         system(RbConfig.ruby, File.join(RbConfig::CONFIG["bindir"], "gem"), "install", "proctolog", "--version", latest.version, "--clear-sources", "--source", Release.server, exception: true)
         puts taken(latest)
         # RubyGems' launcher takes the version to run as its first word.
-        exec(RbConfig.ruby, File.join(Gem.bindir, "proctolog"), "_#{latest}_", "install")
+        exec(Installation.updating_from(VERSION), RbConfig.ruby, File.join(Gem.bindir, "proctolog"), "_#{latest}_", "setup")
       end
 
       # The checkout's own bundle, on this Ruby, as bin/proctolog runs it.
+      # Nothing to take when origin has nothing newer, as for a gem.
       def take_with_git(installation)
-        puts installation.pull
+        pull = installation.pull
+        return puts("PRoctolog #{VERSION} in #{installation.root} is the latest: origin has nothing newer.") unless pull.moved?
+
         Bundler.with_unbundled_env do
           system(RbConfig.ruby, Gem.bin_path("bundler", "bundle"), "install", "--quiet", chdir: installation.root.to_s, exception: true)
         end
         puts "Pulled #{installation.root} forward. Restart the desk to run it."
-        exec(RbConfig.ruby, installation.root.join("bin/install").to_s)
+        exec(Installation.updating_from(VERSION), RbConfig.ruby, installation.root.join("bin/install").to_s)
       end
 
       def taken(latest) = "Installed PRoctolog #{latest}. Restart the desk to run it: one open now still runs #{Release.running}."
@@ -402,13 +401,55 @@ module Proctolog
       Exits 0 when every need is met, 1 when one is not.
     TEXT
     def doctor
-      project = begin
-        Project.current = Project.discover(options[:project] || Dir.pwd)
+      project = discovered
+      boot_desk!
+      Doctor.new(project).tap { puts it }.then { exit(it.fine? ? 0 : 1) }
+    end
+
+    desc "setup", "Set PRoctolog up, a step at a time, from wherever you are to an open desk"
+    long_desc <<~TEXT
+      First links the proctolog command, zsh's completion and the agent skills to this PRoctolog: from the gem,
+      or the checkout, which also gets its launcher in ~/.local/bin. Anything of the same name that is not
+      PRoctolog's stays as it is. Then takes doctor's checks in the order you meet them: gh signed in, the
+      checkout you review and its GitHub repository, a first burst, what turns features on, sharing the desk
+      with your phone, and the desk itself. Each step says why it matters and what to do; Enter checks it again
+      once you have, and it is stamped DONE when it is met, or LATER when you leave it. Outside a checkout, its
+      step asks for the folder of one. Of anyone else's, nothing is installed for you. The last step opens the
+      desk with `proctolog serve`. `install` is another name for it, and `update` runs it for the version it
+      installs, which then only links and says what is new.
+
+      Outside a terminal it asks nothing: it prints each step as it stands, and exits 0 when the desk can
+      open, 1 when a step still waits on something the desk needs.
+    TEXT
+    def setup
+      installation = Installation.here
+      # An update hands over to the version it installed, to link it and say
+      # what is new: the owner asked for an update, not for a setup.
+      return puts(installation.install, "", installation.news) if installation.news
+
+      discovered
+      boot_desk!
+      setup = Setup.new(installation:, directory: options[:project] || Dir.pwd) { Doctor.new(discovered(it)) }
+      exit(setup.show ? 0 : 1) unless $stdin.tty?
+
+      case setup.walk
+      # The command that runs now, as a new terminal may not find proctolog yet.
+      in :serve then exec(RbConfig.ruby, $PROGRAM_NAME, "serve", *(["--project", Project.current.root.to_s] if Project.current))
+      in :finished then exit 0
+      in :stopped then exit 1
+      end
+    rescue Installation::Refused => e
+      abort e.message
+    end
+
+    no_commands do
+      # The checkout --project names, or the one this runs in, found again
+      # each time: one a setup step made is there the next time it checks.
+      def discovered(directory = options[:project] || Dir.pwd)
+        Project.current = Project.discover(directory)
       rescue Project::Missing
-        nil
+        Project.current = nil
       end
-      Desk.initialize! unless Desk.initialized?
-      Doctor.new(project).tap { puts it }.then { exit(it.fine? ? 0 : 1) }
     end
   end
 end

data/completions/_proctolog

@@ -58,8 +58,9 @@ _proctolog() {
     'check:Check a description as the desk reads it, of a pull request or a file'
     'themes:Print the themes a decision may name, with what each means'
     'doctor:Say what this Mac and this checkout lack, a line each with the fix'
+    'setup:Set PRoctolog up, a step at a time, from wherever you are to an open desk'
     'version:Print which PRoctolog this is'
-    'install:Link zsh'"'"'s completion and the agent skills to this PRoctolog'
+    'install:Another name for setup: link this PRoctolog, then set it up a step at a time'
     'update:Install the latest PRoctolog, and link to it'
     'tree:Print a tree of all available commands'
     'help:Describe the commands, or one of them'
@@ -157,7 +158,7 @@ _proctolog() {
           unopened=(${(f)"$(_proctolog_unopened "$root")"})
           _arguments $project '(-f --file)'{-f,--file}'[A local Markdown file to check before it is published]:file:_files' \
             "1:pull request:{_describe -t pull-requests 'open pull request' pull_requests; _describe -t unopened 'not opened yet' unopened}" ;;
-        themes|doctor|version|install|update) _arguments $project ;;
+        themes|doctor|setup|version|install|update) _arguments $project ;;
         help) _describe -t commands 'command' commands ;;
       esac
       ;;

data/docs/manual/pr-format.md

@@ -21,7 +21,7 @@ which only renders and keeps nothing.
 ## PR format
 
 The skill in `skills/proctolog-pr-writing/` teaches an agent this format, with a
-whole example in its `references/example-description.md`. `proctolog install`
+whole example in its `references/example-description.md`. `proctolog setup`
 links it into `~/.claude/skills/` and `~/.agents/skills/`. Keep the project's
 template (Summary, Changes, Verification) and add:
 

data/docs/manual/setup.md

@@ -0,0 +1,59 @@
+# Setting up, a step at a time
+
+`proctolog setup` is the one command to remember. Run it the first time, with
+`rvx proctolog setup` or after `gem install proctolog`, and again whenever
+you're unsure something is in place. It takes you from wherever you are to an
+open desk, one step at a time. `proctolog install` is another name for it, so
+whichever you remember works.
+
+1. **PRoctolog on this Mac**: setup links the `proctolog` command, zsh's
+   completion and the agent skills to this PRoctolog, then checks Ruby, the
+   command on your PATH, and whether a newer PRoctolog is out.
+2. **GitHub, through gh**: installed and signed in.
+3. **The checkout you review**: a Git checkout whose origin is on GitHub,
+   and which your `gh` can read. Outside one, type its folder here.
+4. **A first burst**: the pull requests you review together.
+5. **What turns features on**: Chrome, Diffle, ImageMagick, ffmpeg and the
+   checkout's `.proctolog/app.yml`.
+6. **Your phone, through a share**: Tailscale or ngrok, what each gives, and
+   where to get them ([sharing](sharing.md)).
+7. **The desk**: Enter opens it with `proctolog serve`.
+
+Each step says why it matters and shows doctor's lines for it, each with the
+fix. Do what it says in another terminal, then press Enter there: the step
+checks itself again. A step that is met is stamped `[ DONE ]` and the next
+one begins, so a second run passes over what you already have, stamping each
+step as it goes. The links in the first step are PRoctolog's own, made again
+each time; anything of the same name that is someone else's stays, and is
+said. Nothing else is installed for you: a step explains, links and checks.
+
+Some steps can wait. Type `l` and Enter to leave one for later, and it is
+stamped `[ LATER ]` with what does its work meanwhile:
+
+- A step whose lines are only `--` is a nicety: the desk opens without it.
+- The first step, when the command is linked but your PATH doesn't have it
+  yet: setup goes on as it is, and a new terminal finds `proctolog` once
+  `~/.zshrc` puts it there.
+- A first burst: **Review** on the desk's first page starts one, so the step
+  needn't hold you up.
+- The features step: each feature waits for its own program, and the rest of
+  the desk works.
+
+gh and the checkout can't wait, as the desk opens nothing without them;
+there, `l` only checks again. `q` stops anywhere, and `proctolog setup`
+starts again from the first step.
+
+If a desk already answers on port 4040, the last step says so instead of
+opening a second one.
+
+## After an update
+
+`proctolog update` runs the new version's `setup`, which then only links it
+and says what's new: you asked for an update, not to go through setup again.
+
+## For an agent
+
+Outside a terminal, in a pipe or an agent's shell, `setup` asks nothing. It
+links, prints every step as it stands, stamping the unfinished ones
+`[ TO DO ]`, and exits 0 when the desk can open, 1 when a step still waits on
+something the desk needs.

data/docs/manual/sharing.md

@@ -34,7 +34,7 @@ in. It goes through whichever of these this Mac has:
   and run `ngrok config add-authtoken TOKEN`. On the free plan, ngrok shows a
   warning page of its own before the desk, and carries 1 GB a month.
 
-Neither is installed for you. `proctolog doctor` and `proctolog share status`
+Neither is installed for you. `proctolog doctor`, `proctolog setup` and `proctolog share status`
 say what each one still needs.
 
 ### Turning it on

data/docs/manual/updates.md

@@ -39,10 +39,17 @@ proctolog update
 
 It asks RubyGems, installs the newer version the way yours was installed
 (`rv tool install` for a PRoctolog that `rvx` runs, `gem install` otherwise),
-and runs that version's `proctolog install`, so zsh's completion and the agent
-skills link to it. A checkout of PRoctolog is pulled forward instead, and its
-bundle installed. A desk that's open keeps running the old one: stop it and run
-`proctolog serve` again.
+and runs that version's `proctolog setup`, which after an update only links
+zsh's completion and the agent skills to it, and walks no steps. A checkout of PRoctolog is pulled forward instead, and its
+bundle installed. When there's nothing newer, it says so and changes nothing.
+A desk that's open keeps running the old one: stop it and run `proctolog
+serve` again.
+
+Then it says what's new since the version you had, from the changelog: each
+change by its first sentence, under Added, Changed and Fixed, and in full
+what you must do. Past a dozen changes it counts the rest, and it ends with
+where the whole changelog is. An update from 0.2.0 or earlier says none of
+this, as the version you leave is the one that runs the update.
 
 The old version stays installed. `gem cleanup proctolog` removes the ones
 you no longer run; with rv, `rv tool list` shows them and

data/lib/proctolog/changelog/news.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Proctolog
+  class Changelog
+    # What an update brings, as the console says it once the new version is
+    # in: each change by the first sentence of its line, under its heading,
+    # and what to do in full. Plain text, as a terminal reads no markdown.
+    class News
+      # Past this many changes, the rest are counted rather than shown.
+      SHOWN = 12
+
+      # As wide as the terminal it is said in, within reason.
+      def self.columns = (IO.console&.winsize&.last || 80).clamp(40, 100)
+
+      def initialize(since:, sections:, path:)
+        @since, @sections, @path = since, sections, path
+      end
+
+      def to_s(width: self.class.columns)
+        shown = changes.first(SHOWN)
+        more = changes.size - shown.size
+        told = @sections.flat_map { told(it, shown:, width:) }
+        ["What's new since PRoctolog #{@since}:", *told, "", more.positive? ? "#{more} more, and all of it: #{@path}" : "All of it: #{@path}"].join("\n")
+      end
+
+      private
+
+      # Every change, in the order written: its section, its heading and its line.
+      def changes = @sections.flat_map { |section| section.changes.flat_map { |heading, lines| lines.map { [section, heading, it] } } }
+
+      # A section's changes that are shown, and what it asks, which always is.
+      def told(section, shown:, width:)
+        headed = section.changes.flat_map do |heading, lines|
+          kept = lines.select { shown.include?([section, heading, it]) }
+          kept.any? ? ["  #{heading}", *kept.map { "    - #{headline(it, room: width - 6)}" }] : []
+        end
+        asked = section.you_do&.then { laid("You do#{plain(it)}", width:) } || []
+        (headed.any? || asked.any?) ? ["", section.name, *headed, *asked] : []
+      end
+
+      # The first sentence of a line. One longer than the room ends at its last
+      # clause that fits, when that keeps half the room, or else at a word.
+      def headline(line, room:)
+        sentence = plain(line).then { it[/\A.+?[.!?](?=\s|\z)/] || it }
+        return sentence if sentence.size <= room
+
+        cut = sentence[0, room]
+        clause = cut[/\A.*(?=[,;:]\s)/]
+        "#{(clause && clause.size >= room / 2) ? clause : cut[/\A.*(?=\s)/]}…"
+      end
+
+      # In lines no wider than the console, the first two spaces in, the rest four.
+      def laid(text, width:)
+        text.split.each_with_object([+"  "]) do |word, lines|
+          lines << +"    " if lines.last.size + word.size >= width && !lines.last.strip.empty?
+          lines.last << (lines.last.strip.empty? ? word : " #{word}")
+        end
+      end
+
+      # Without markdown's marks: **bold**, <links> and [text](links) keep
+      # their words. Backticks stay, as the console writes commands in them.
+      def plain(text) = text.gsub(/\*\*(.+?)\*\*/, '\1').gsub(/<(\S+?)>/, '\1').gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
+    end
+  end
+end

data/lib/proctolog/changelog.rb

@@ -1,23 +1,42 @@
 # frozen_string_literal: true
 
+require_relative "changelog/news"
+
 module Proctolog
-  # CHANGELOG.md as a release reads it: a section to each version, newest
-  # first, under ## Unreleased what main has that no gem has yet. Plain Ruby,
-  # as bin/release and the Release workflow read it before any bundle.
+  # CHANGELOG.md as a release and an update read it: a section to each
+  # version, newest first, under ## Unreleased what main has that no gem has
+  # yet. Plain Ruby, as bin/release, the Release workflow and bin/install
+  # read it before any bundle.
   class Changelog
     PATH = File.expand_path("../../CHANGELOG.md", __dir__)
 
-    # One ## section, its lines under ### Added, Changed and Fixed.
+    # One ## section, its lines under ### Added, Changed and Fixed, and what
+    # to do after **You do**.
     Section = Data.define(:name, :text) do
       def adds? = text.match?(/^### Added$/)
       def lines? = text.match?(/^- /)
       def notes = text.strip
+
+      def unreleased? = name == "Unreleased"
+      def version = (Gem::Version.new(name) if Gem::Version.correct?(name))
+
+      # Its lines by heading, in the order written, each on one line.
+      def changes
+        text.scan(/^### ([^\n]+)\n(.*?)(?=^### |^\*\*You do\*\*|\z)/m).to_h do |heading, lines|
+          [heading, lines.split(/^- /).drop(1).map { it.split.join(" ") }]
+        end
+      end
+
+      # What it asks, on one line, as it goes on after **You do**: ": nothing",
+      # or ", coming from a checkout: …".
+      def you_do = text[/^\*\*You do\*\*(.*)/m, 1]&.split&.join(" ")
     end
 
     # It writes ⌘ and ↩, so it is read as UTF-8 whatever the locale.
-    def self.read(path = PATH) = new(File.read(path, encoding: "UTF-8"))
+    def self.read(path = PATH) = new(File.read(path, encoding: "UTF-8"), path:)
 
-    def initialize(text)
+    def initialize(text, path: PATH)
+      @path = path
       @sections = text.split(/^## /).drop(1).map do
         name, body = it.split("\n", 2)
         Section.new(name: name.strip, text: body.to_s)
@@ -28,6 +47,15 @@ module Proctolog
 
     def unreleased = self["Unreleased"]
 
+    # What an update from this version brings: every section newer than it,
+    # Unreleased too in a checkout. Nil when it brings nothing written here.
+    def since(version)
+      return unless Gem::Version.correct?(version)
+
+      newer = @sections.select { it.unreleased? || it.version&.>(Gem::Version.new(version)) }
+      News.new(since: version, sections: newer, path: @path) if newer.any?
+    end
+
     # Adding something makes a minor (docs/manual/updates.md): the minor this
     # version owes when it adds something but is only a patch on the one
     # before it.
@@ -42,9 +70,6 @@ module Proctolog
     # too.
     def adds?(version) = [self[version], unreleased].compact.any?(&:adds?)
 
-    def released_before(version)
-      older = @sections.drop_while { it.name != version }.drop(1)
-      older.map(&:name).find { Gem::Version.correct?(it) }&.then { Gem::Version.new(it) }
-    end
+    def released_before(version) = @sections.drop_while { it.name != version }.drop(1).find(&:version)&.version
   end
 end

data/lib/proctolog/installation.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "open3"
 require "rbconfig"
 require "shellwords"
+require_relative "changelog"
 
 module Proctolog
   # Where this PRoctolog lives, and what it puts on this Mac for zsh and the
@@ -22,8 +23,20 @@ module Proctolog
 
     SKILL_FOLDERS = %w[.claude/skills .agents/skills].freeze
 
+    # What a pull did: the commit the checkout was at, and the one it is at.
+    Pull = Data.define(:from, :to) do
+      def moved? = from != to
+    end
+
+    # `proctolog update` hands the new version's install the version it
+    # leaves, in the environment, for that install to say what is new since.
+    UPDATED_FROM = "PROCTOLOG_UPDATED_FROM"
+
     def self.here = new(File.expand_path("../..", __dir__))
 
+    # The environment update starts the new version's install in.
+    def self.updating_from(version) = {UPDATED_FROM => version.to_s}
+
     attr_reader :root
 
     def initialize(root, home: Dir.home, env: ENV)
@@ -47,9 +60,15 @@ module Proctolog
       branch, main = git("branch", "--show-current"), origin_branch
       raise Refused, "#{root} is on #{branch}, not #{main}: switch to #{main}, or pull #{branch} yourself." unless branch == main
 
+      from = git("rev-parse", "HEAD")
       git("pull", "--ff-only")
+      Pull.new(from:, to: git("rev-parse", "HEAD"))
     end
 
+    # What is new in this PRoctolog since the one an update left, or nil when
+    # no update brought it here.
+    def news = @env[UPDATED_FROM]&.then { Changelog.read(root.join("CHANGELOG.md")).since(it) }
+
     def launcher = @home.join(".local/bin/proctolog")
 
     def completion = @home.join(".zsh/completions/_proctolog")

data/lib/proctolog/version.rb

@@ -3,5 +3,5 @@
 module Proctolog
   # Semantic: a patch fixes, a minor adds, a major asks something new of the
   # owner (a command gone, a file moved). docs/manual/updates.md says more.
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: proctolog
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Gill Abarbanel
@@ -193,6 +193,7 @@ files:
 - app/models/proctolog/handover/worklist.rb
 - app/models/proctolog/housekeeping.rb
 - app/models/proctolog/kit.rb
+- app/models/proctolog/localhost.rb
 - app/models/proctolog/marks.rb
 - app/models/proctolog/membership.rb
 - app/models/proctolog/mentions.rb
@@ -217,6 +218,7 @@ files:
 - app/models/proctolog/rules.rb
 - app/models/proctolog/scenario.rb
 - app/models/proctolog/server.rb
+- app/models/proctolog/setup.rb
 - app/models/proctolog/share.rb
 - app/models/proctolog/share/ngrok.rb
 - app/models/proctolog/share/settings.rb
@@ -306,10 +308,12 @@ files:
 - docs/manual/handover.md
 - docs/manual/pr-format.md
 - docs/manual/reading.md
+- docs/manual/setup.md
 - docs/manual/sharing.md
 - docs/manual/unopened.md
 - docs/manual/updates.md
 - lib/proctolog/changelog.rb
+- lib/proctolog/changelog/news.rb
 - lib/proctolog/installation.rb
 - lib/proctolog/version.rb
 - public/asking.js