proctolog 0.1.1 → 0.3.0

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

@@ -0,0 +1,77 @@
+# The desk's address, and sharing it
+
+## On this Mac
+
+The desk is at <http://proctolog.localhost:4040>. Arc, Chrome and the other
+Chromium browsers send any name under `localhost` to this Mac without asking
+anyone, so there is nothing to set up; after the first visit, typing `procto`
+in the address bar finds it. `http://localhost:4040` still works too. Safari asks macOS, which
+doesn't know these names, so use `localhost` there.
+
+A bare `proctolog`, with no port, would need the desk on port 80, which macOS
+gives a user only on every network at once, Wi-Fi included. The desk listens
+on this Mac alone, so it stays on its port.
+
+## From your phone, or a computer elsewhere
+
+Sharing the desk lets you reach it from your other devices while this Mac
+keeps it: a review on your phone, say, while an agent works on. Only you get
+in. It goes through whichever of these this Mac has:
+
+- **Tailscale.** The desk is at this Mac's name on your tailnet,
+  `https://your-mac.your-tailnet.ts.net`. Only the devices signed in to your
+  tailnet reach it, so your phone needs the Tailscale app, signed in to the
+  same tailnet as this Mac. One account can be in more than one tailnet, one
+  of its own and others it was invited to, so check the tailnet's name, not
+  only the account: `proctolog share status` and the sharing page say it.
+  Nothing goes on the internet, and nothing limits how much you open. Install it from <https://tailscale.com/download/mac>; the desk asks
+  for HTTPS certificates to be on for your tailnet, which they are unless you
+  turned them off, at <https://login.tailscale.com/admin/dns>.
+- **ngrok.** The desk is on the internet, at the address ngrok gives your
+  account, behind ngrok's sign-in with Google, which lets in only your Git
+  email unless you name others. Install it (`brew install ngrok`), then copy
+  your authtoken from <https://dashboard.ngrok.com/get-started/your-authtoken>
+  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`, `proctolog setup` and `proctolog share status`
+say what each one still needs.
+
+### Turning it on
+
+On any page with the pane at the left, its foot says whether the desk is
+shared; **share it** opens the page that shares it, through either way,
+and stops it again. From a terminal:
+
+```sh
+proctolog share                # the way you named last, or the first one ready
+proctolog share --via ngrok --allow you@gmail.com
+proctolog share status         # shared or not, and what each way needs
+proctolog share stop
+proctolog serve --share        # open the desk, shared
+```
+
+An agent can run them too, on a Mac you left working, and send you the
+address it prints. A share stays open until it is stopped, whether the desk
+is running or not, and a share already open is only printed again. A trial
+desk, on marks of its own, is never shared.
+
+### What passes through it
+
+Everything a page shows comes from this Mac, so everything you open travels
+through the share. That counts for ngrok's 1 GB: a pull request's pictures
+are on GitHub, but GitHub gives them only to someone signed in, so the desk
+fetches each one once, with your `gh`, keeps it, and serves it itself. Its
+films are the same. Keeping them saves asking GitHub again, not the trip to
+your phone.
+
+### What stays on this Mac
+
+- **The app under review.** A scenario's button and the Try it rail open the
+  app at `localhost`, which on a phone is the phone. They work on this Mac
+  only for now.
+- **Grouse's overlay.** The desk shows it to a request from this Mac, and one
+  through the share isn't one.
+
+The desk is drawn for a keyboard. On a phone it reads, and its buttons and
+links work, but the keys have no touch of their own yet.

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "changelog/news"
+
+module Proctolog
+  # 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, 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"), path:)
+
+    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)
+      end
+    end
+
+    def [](name) = @sections.find { it.name == name }
+
+    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.
+    def minor_owed(version)
+      owed = released_before(version)&.then { Gem::Version.new("#{it.bump}.0") }
+      owed if owed && adds?(version) && Gem::Version.new(version) < owed
+    end
+
+    private
+
+    # Under its own heading, or still under Unreleased, since main has that
+    # too.
+    def adds?(version) = [self[version], unreleased].compact.any?(&:adds?)
+
+    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.1.1"
+  VERSION = "0.3.0"
 end

data/public/asking.js

@@ -18,11 +18,25 @@ const quoted = (text) =>
 		.join("\n");
 
 // Where a decision stands, its words, and the pictures it rests on that
-// the desk holds on this Mac.
-const about = ({ pr, title, url, branch, head, text, pictures: shots }) => {
+// the desk holds on this Mac. One nobody has opened yet has no address on
+// GitHub: its branch and the file its description is kept in stand there.
+const about = ({
+	pr,
+	title,
+	url,
+	branch,
+	base,
+	file,
+	head,
+	text,
+	pictures: shots,
+}) => {
 	const here = shots.filter((picture) => picture.file);
+	const where = file
+		? `not opened, on ${branch} at ${head.slice(0, 7)}, into ${base}, described in ${file}`
+		: `(${url}), on ${branch} at ${head.slice(0, 7)}`;
 	return [
-		`#${pr}, "${title}" (${url}), on ${branch} at ${head.slice(0, 7)}:`,
+		`#${pr}, "${title}" ${where}:`,
 		quoted(text),
 		here.length &&
 			`Its pictures, on this Mac:\n${here.map((picture) => `- ${picture.name}: ${pictures}/${picture.file}`).join("\n")}`,
@@ -31,6 +45,19 @@ const about = ({ pr, title, url, branch, head, text, pictures: shots }) => {
 		.join("\n\n");
 };
 
+// How to read the pull requests asked about: GitHub has the opened ones,
+// git and the store the rest.
+const reading = (decisions) =>
+	[
+		decisions.some((each) => !each.file) &&
+			"Read a pull request with `gh pr view` and `gh pr diff`.",
+		decisions.some((each) => each.file) &&
+			"A pull request not opened yet is not on GitHub: read its code with `git log` and `git diff` from its base to its branch, and its description in the file named here.",
+		"If one has moved on since the head named here, say so.",
+	]
+		.filter(Boolean)
+		.join(" ");
+
 export const askingPrompt = (ids, question) => {
 	const decisions = ids.map((id) => inventory.find((each) => each.id === id));
 	const which =
@@ -38,7 +65,7 @@ export const askingPrompt = (ids, question) => {
 			? "one of their decisions"
 			: `${decisions.length} of their decisions`;
 	return [
-		`I am reviewing pull requests in PRoctolog and have a question on ${which} before I choose. Answer it plainly, with evidence. Change nothing while you do: no edits, no commits, no checkout, nothing on GitHub. Read a pull request with \`gh pr view\` and \`gh pr diff\`; if one has moved on since the head named here, say so.`,
+		`I am reviewing pull requests in PRoctolog and have a question on ${which} before I choose. Answer it plainly, with evidence. Change nothing while you do: no edits, no commits, no checkout, nothing on GitHub. ${reading(decisions)}`,
 		...decisions.map(about),
 		`My question:\n${question.trim()}`,
 	].join("\n\n");

data/public/decisions.js

@@ -9,7 +9,7 @@ import {
 	prepareScreenshots,
 	toggleScreenshots,
 } from "./decision-screenshots.js";
-import { helping, keyOf, mode } from "./keys.js";
+import { helping, keyOf, mode, overThePage } from "./keys.js";
 import { withMentions } from "./mentions.js";
 import { prNumber } from "./pr-number.js";
 import {
@@ -1092,9 +1092,9 @@ document.addEventListener("click", (event) => {
 });
 
 document.addEventListener("focusin", (event) => {
-	// A panel over the page, a picture looked at closely, takes the focus
-	// without leaving the decision: its Esc comes back to it.
-	if (event.target.closest("dialog")) return;
+	// A picture looked at closely, or a note written in Grouse's overlay, takes
+	// the focus without leaving the decision: its Esc comes back to it.
+	if (overThePage(event.target)) return;
 	const box = event.target.closest("[data-decision]");
 	if (inline) {
 		// Deciding begins only when it is asked for (f, Enter, a click, a choice's

data/public/desk.js

@@ -27,14 +27,18 @@ const follow = (key) => {
 	if (link) location.assign(link.href + location.hash);
 };
 
-// Opens the next pull request with decisions still to review: the one the
-// cursor rests on when it has some, else the first after it, going round to
-// the top of the route. With none left anywhere, the cursor's row says so.
+// Opens the next pull request that asks for the owner, with blocking
+// decisions to review or something back from the agent (Standing#asks_for_owner?):
+// the one the cursor rests on when it asks, else the first after it, going
+// round to the top of the route. With none left anywhere, the cursor's row
+// says so.
 const openUnreviewed = () => {
 	const ahead = [...stops.slice(at), ...stops.slice(0, at)];
-	// The non-blocking wait for one gesture on their pull request's page.
-	const next = ahead.find((stop) => Number(stop.dataset.blockingLeft) > 0);
-	if (!next) return said("Every decision of this burst is reviewed.");
+	const next = ahead.find((stop) => stop.dataset.asks === "true");
+	if (!next)
+		return said(
+			"Nothing asks for you: every blocking decision is reviewed, and nothing is back from the agent.",
+		);
 	restOn(stops.indexOf(next));
 	location.assign(next.querySelector("a").href);
 };

data/public/keys.js

@@ -201,6 +201,12 @@ export const thisBlock = (hints = []) => {
 export const helping = () =>
 	!!document.querySelector("dialog[open], :popover-open");
 
+// Whether the focus went over the page rather than along it: into a picture
+// looked at closely, or into Grouse's overlay to write a note on the desk.
+// Either leaves the page where it was, a decision being decided included.
+export const overThePage = (target) =>
+	!!target.closest?.("dialog, grouse-widget");
+
 // `hints` are pairs of keys and what they do: [["j k", "move"], ["a", "leave as is"]].
 let shown;
 export const mode = (name, hints = []) => {