proctolog 0.1.0

data/docs/manual/unopened.md

@@ -0,0 +1,80 @@
+# Before anything is opened
+
+Work still being shaped can be reviewed before any pull request is opened for
+it. Nothing reaches GitHub: no pull request, no picture, no push. Once the
+branches are opened, the review goes with them.
+
+## What the agent writes
+
+An unopened pull request is what `gh pr create` would be told, written down
+before anyone runs it: a branch, the branch it goes into, a title and a
+description. Each lives in a folder of your store named after its branch,
+which `proctolog unopened folder BRANCH` prints:
+
+```
+~/.local/share/proctolog/<owner>/<repo>/unopened/recovery/emails/
+  pull_request.md
+  reset-mail-before.png
+  reset-mail-after.png
+```
+
+```markdown
+---
+title: A reset mail says which account it is for
+base: recovery/fields
+---
+## Summary
+…
+```
+
+The description is written as any other the desk reads
+([how](pr-format.md)). Its pictures sit beside it, linked by their file names:
+`![reset-mail-after](reset-mail-after.png)`. Tell your agent to "write these
+for PRoctolog without opening PRs"; the `proctolog-pr-writing` skill knows the
+rest. A missing title is the branch's name, and a missing base is origin's
+default branch.
+
+`proctolog unopened` lists what the desk reads, each with its number. GitHub
+never writes a number with a leading zero, so the desk numbers these 01, 02
+and on, and a branch keeps its number. `proctolog check recovery/emails`, or
+`proctolog check 01`, checks one, pictures and all.
+
+## Reviewing them
+
+The open pull requests page lists them under "Not opened", each with "Review
+alone", and "Review the chain" for one that sits on another's branch. A burst
+file names one by its branch, in the lists it already has:
+
+```yaml
+name: Account recovery
+repository: sartoria-llc/sartoria
+tops: [recovery/emails]        # followed down by base, as any chain
+pull_requests: [recovery/copy] # stands alone
+```
+
+From there it is a pull request like any other: read, decided, tried, handed
+over. Its line says "not opened, on `recovery/emails`", and `G` says GitHub
+has nothing of it. A chain followed down from it can end on an open pull
+request's branch, and sits on it.
+
+What differs is where things are kept:
+
+- Its head and files are read from the branch on this Mac, each time a page
+  is shown: there is nothing to read again.
+- Ticking accepted decisions writes its file, not GitHub.
+- The desk keeps each text it reads in the folder's `.revisions/`, so a "good
+  to go" that the description moved past says how it changed.
+- The handover tells the agent where its file is. An agent rewrites the file
+  in place, which needs no word from you, so a whole round stays on this Mac.
+
+## Opening them
+
+When you're ready, tell the agent to open them. That is a GitHub write, and
+waits for your word: it pushes the branches, uploads the pictures and opens
+each pull request with its title, base and description.
+
+On its next reading the desk finds the open pull request on each branch and
+carries the review over to its new number: notes, choices, good-to-go marks,
+code comments, handovers and films. The route says "opened, was #01" until
+you dismiss it with `x`. From then on GitHub is the truth, and the folder is
+left alone.

data/docs/manual/updates.md

@@ -0,0 +1,55 @@
+# Versions and updates
+
+PRoctolog is a gem, `proctolog`, numbered the semantic way: `MAJOR.MINOR.PATCH`.
+
+- A **patch** (0.1.0 → 0.1.1) fixes something. Nothing you do changes.
+- A **minor** (0.1.1 → 0.2.0) adds something. Nothing you do changes either.
+- A **major** (0.2.0 → 1.0.0) asks something new of you: a command renamed or
+  gone, a file that moved, a format your agent writes differently.
+  [CHANGELOG.md](../../CHANGELOG.md) says what.
+
+While the number starts with 0, a minor may ask something of you too, and the
+changelog says so when it does.
+
+`proctolog version` says which one you run.
+
+## Being told
+
+Once a day while the desk serves, and once as it starts, it asks RubyGems which
+PRoctolog is the latest. That's the only thing it sends anywhere besides
+GitHub: a request for `rubygems.org/api/v1/versions/proctolog/latest.json`,
+with nothing of yours in it. It keeps the answer in
+`~/.cache/proctolog/latest_release.json`.
+
+When the latest is newer than yours, you're told three ways:
+
+- the next page you open says so in the toast at the foot, once in each
+  browser for each version, and `m` shows it again after;
+- `proctolog serve` says so as it starts;
+- `proctolog doctor` says so, on a `--` line.
+
+None of them waits on RubyGems: they read what the desk last kept, and say
+nothing before the first answer.
+
+## Updating
+
+```sh
+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.
+
+The old version stays installed. `gem cleanup proctolog` removes the ones
+you no longer run; with rv, `rv tool list` shows them and
+`rv tool uninstall proctolog` removes them all.
+
+A checkout is pulled only when that's all it takes: no changes of your own in
+it, on the branch origin calls its own, and only forward (`git pull
+--ff-only`). Anything else, `update` says what's in the way and leaves it to
+you. A plain `git pull` works too; run `bundle install` after it when the
+Gemfile.lock changed.

data/lib/proctolog/installation.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "shellwords"
+
+module Proctolog
+  # Where this PRoctolog lives, and what it puts on this Mac for zsh and the
+  # agents to find it: zsh's completion and the agent skills, as links into
+  # it, so they never fall behind it. It lives in one of three places:
+  #
+  # - a checkout, with its own bundle and a launcher in ~/.local/bin;
+  # - an rv tool, on a Ruby and gems of its own whatever Ruby the shell has,
+  #   with a launcher in ~/.local/bin that asks rvx for it;
+  # - a gem among the others, run by RubyGems' own launcher.
+  #
+  # Plain Ruby, as bin/install runs it before any bundle.
+  class Installation
+    # Something of the same name is someone else's, and stays.
+    Refused = Class.new(StandardError)
+
+    SKILL_FOLDERS = %w[.claude/skills .agents/skills].freeze
+
+    def self.here = new(File.expand_path("../..", __dir__))
+
+    attr_reader :root
+
+    def initialize(root, home: Dir.home, env: ENV)
+      @root, @home, @env = Pathname(root).realpath, Pathname(home), env
+    end
+
+    # A gem ships no Gemfile: a checkout runs in a bundle of its own.
+    def checkout? = root.join("Gemfile").exist?
+
+    # rv gives each tool a gem home of its own, named for it and its version,
+    # and runs it with GEM_HOME set there.
+    def rv_tool? = !checkout? && gem_home&.basename.to_s.start_with?("proctolog@") && root.to_s.start_with?("#{gem_home}/")
+
+    def gem_home = @env["GEM_HOME"]&.then { Pathname(it) }
+
+    # Brings a checkout up to its origin, as `proctolog update` does: only a
+    # clean one, on the branch origin calls its own, and only forward.
+    def pull
+      raise Refused, "#{root} has changes of its own: commit or stash them, then run `proctolog update` again." unless git("status", "--porcelain").empty?
+
+      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
+
+      git("pull", "--ff-only")
+    end
+
+    def launcher = @home.join(".local/bin/proctolog")
+
+    def completion = @home.join(".zsh/completions/_proctolog")
+
+    # What it did, a line each. Refuses before it writes anything.
+    def install
+      refuse_strangers
+      [*(script ? launch : shadowed), complete, *link_skills]
+    end
+
+    private
+
+    # What git printed, or Refused with what it said.
+    def git(*arguments)
+      output, status = Open3.capture2e("git", "-C", root.to_s, *arguments)
+      status.success? ? output.strip : raise(Refused, "git #{arguments.join(" ")} failed in #{root}:\n#{output}")
+    end
+
+    # origin's own branch, as this Mac last fetched it.
+    def origin_branch
+      git("symbolic-ref", "--short", "refs/remotes/origin/HEAD").delete_prefix("origin/")
+    rescue Refused
+      "main"
+    end
+
+    # The launcher's, where this PRoctolog needs one of its own on the PATH.
+    def script
+      if checkout? then "#!/bin/sh\nexec #{RbConfig.ruby.shellescape} #{root.join("bin/proctolog").to_s.shellescape} \"$@\"\n"
+      elsif rv_tool? then "#!/bin/sh\nexec rvx proctolog \"$@\"\n"
+      end
+    end
+
+    def refuse_strangers
+      if script && launcher.exist? && launcher.read != script
+        raise Refused, "#{launcher} runs another PRoctolog; leave it in place or remove it before installing."
+      end
+      # A copy an earlier install left is replaced by the link; anything else is someone else's.
+      if completion.exist? && !completion.symlink? && !completion.read.start_with?("#compdef proctolog")
+        raise Refused, "#{completion} is not PRoctolog's completion; leave it in place or remove it before installing."
+      end
+    end
+
+    def launch
+      return "#{launcher} runs this PRoctolog." if launcher.exist?
+
+      launcher.dirname.mkpath
+      launcher.write(script, perm: 0o755)
+      "Installed #{launcher}."
+    end
+
+    # A checkout's launcher, left from before the gem, may come first on the PATH.
+    def shadowed = launcher.exist? ? ["#{launcher} runs another PRoctolog: remove it, or it may answer for proctolog instead of this one."] : []
+
+    def complete
+      completion.dirname.mkpath
+      FileUtils.ln_sf(root.join("completions/_proctolog"), completion)
+      "Linked #{completion}."
+    end
+
+    # A skill folder of the same name that is no link is someone else's: it stays.
+    def link_skills
+      SKILL_FOLDERS.product(root.glob("skills/*/")).map do |folder, skill|
+        link = @home.join(folder, skill.basename)
+        next "#{link} is not a link to PRoctolog's skill; left as it is." if link.exist? && !link.symlink?
+
+        link.dirname.mkpath
+        FileUtils.rm_f(link)
+        link.make_symlink(skill.to_s.chomp("/"))
+        "Linked #{link}."
+      end
+    end
+  end
+end

data/lib/proctolog/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+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.0"
+end

data/public/asking.js

@@ -0,0 +1,50 @@
+// A question the owner asks at once, in a Claude Code session of its own,
+// rather than in the handover. The prompt quotes each decision as the desk
+// holds it, so the session needs nothing else to know what is meant, and
+// puts the question last, where the owner goes on typing.
+
+import { inventory } from "./review-drafts.js";
+
+const { checkout, pictures } = document.querySelector("[data-review-draft]")
+	.dataset;
+
+// The decision's words as a block quote, without its theme marker.
+const quoted = (text) =>
+	text
+		.replace(/\s*<!-- proctolog:theme [\w-]+ -->/g, "")
+		.trim()
+		.split("\n")
+		.map((line) => `> ${line}`.trimEnd())
+		.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 }) => {
+	const here = shots.filter((picture) => picture.file);
+	return [
+		`#${pr}, "${title}" (${url}), on ${branch} at ${head.slice(0, 7)}:`,
+		quoted(text),
+		here.length &&
+			`Its pictures, on this Mac:\n${here.map((picture) => `- ${picture.name}: ${pictures}/${picture.file}`).join("\n")}`,
+	]
+		.filter(Boolean)
+		.join("\n\n");
+};
+
+export const askingPrompt = (ids, question) => {
+	const decisions = ids.map((id) => inventory.find((each) => each.id === id));
+	const which =
+		decisions.length === 1
+			? "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.`,
+		...decisions.map(about),
+		`My question:\n${question.trim()}`,
+	].join("\n\n");
+};
+
+// Claude's own address for a new Code session in the checkout under review,
+// with the prompt typed in. Nothing is sent until the owner sends it there.
+export const sessionAddress = (prompt) =>
+	`claude://code/new?folder=${encodeURIComponent(checkout)}&q=${encodeURIComponent(prompt)}`;

data/public/code-review.js

@@ -0,0 +1,40 @@
+// What Diffle holds of this pull request, on the outline: the comments nobody
+// resolved and the files marked viewed. Diffle goes on in a tab of its own,
+// and closing it tells this one nothing, so the page asks the desk again
+// whenever the owner comes back to it. The desk reads Diffle's own file:
+// asking costs nothing of GitHub.
+
+const comments = document.querySelector("[data-outline] [data-code-tally]");
+const viewing = document.querySelector("[data-outline] [data-files-viewed]");
+const count = (line) => line.querySelector(".count");
+
+const say = ({ open, viewed, files }) => {
+	count(comments).textContent = open || "";
+	count(comments).dataset.waits = open > 0;
+	viewing.hidden = files == null;
+	count(viewing).textContent = `${viewed}/${files}`;
+};
+
+// Coming back to a tab is both shown and focused: one question answers both.
+let asking;
+const ask = () => {
+	asking ??= fetch(comments.dataset.codeTally, {
+		headers: { Accept: "application/json" },
+	})
+		.then((response) => (response.ok ? response.json() : undefined))
+		.then((tally) => tally && say(tally))
+		.catch(() => {})
+		.finally(() => {
+			asking = undefined;
+		});
+};
+
+if (comments) {
+	document.addEventListener("visibilitychange", () => {
+		if (!document.hidden) ask();
+	});
+	addEventListener("focus", ask);
+	addEventListener("pageshow", (event) => {
+		if (event.persisted) ask();
+	});
+}

data/public/cursor.js

@@ -0,0 +1,292 @@
+// The cursor of a pull request's page. The reading rests on one block at a
+// time, and notes.js and decisions.js move it; this script only shows where:
+// a mark in the gutter, the keys of that block beside it and at the head of
+// the docked list, and on the outline the section the block is in. Nothing
+// else on the page carries keys, so the page stays quiet until it is asked.
+
+import { thisBlock } from "./keys.js";
+import { prNumber } from "./pr-number.js";
+import { progress } from "./review-drafts.js";
+
+const main = document.querySelector("body.shell > .main");
+const sections = [...document.querySelectorAll("details.section")];
+// The outline lists the page's sections in the page's own order.
+const folds = [...document.querySelectorAll("[data-outline] [data-fold]")];
+
+const made = (tag, className, text = "") =>
+	Object.assign(document.createElement(tag), {
+		className,
+		textContent: text,
+	});
+
+// The keys of a block, as pairs like the bar's. A third member is what a
+// press of the pointer does, where the key alone would not reach it.
+const deciding = () => document.body.dataset.decisionMode === "true";
+const folded = (summary) => !summary.parentElement.open;
+const fold = (summary) => () => {
+	summary.parentElement.open = folded(summary);
+};
+const pictured = (decision) =>
+	decision.querySelectorAll('a[href*="#screenshot-"]').length;
+
+// Where f begins deciding, by its place among the blocking decisions: the first
+// still to review, which decisions.js marks, and the page marks in its turn
+// while the reading rests on their heading.
+const beginsAt = () => {
+	const all = [
+		...document.querySelectorAll(
+			'li[data-decision]:not([data-grade="non_blocking"])',
+		),
+	];
+	const first = all.findIndex((box) => box.hasAttribute("data-first"));
+	if (first >= 0) return `decide, from ${first + 1} of ${all.length}`;
+	return progress(pullRequest).left
+		? "blocking reviewed: what waits"
+		: "all reviewed: what now";
+};
+
+const keysOf = (block) => {
+	// What can be done with the whole pull request stands beside its title itself.
+	if (block.matches("h1")) return [];
+	if (block.matches("li[data-decision]")) {
+		if (!deciding())
+			return [
+				["Enter", "decide on this"],
+				["n", "note on this"],
+			];
+		const pictures = pictured(block);
+		return [
+			...(pictures ? [["s", `its pictures · ${pictures}`]] : []),
+			["u", "undo"],
+			[
+				"Esc",
+				document.body.dataset.returnsTo
+					? "back to the list"
+					: "back to reading",
+			],
+		];
+	}
+	// A decision's line where they end unfolds to its words, and opens it.
+	if (block.matches("[data-line-of]"))
+		return [
+			block.getAttribute("aria-expanded") === "true"
+				? ["←", "less"]
+				: ["→", "more"],
+			["Enter", "decide on this"],
+			["Esc", "the whole page"],
+		];
+	// A picture an answer rests on is looked at, and takes no note.
+	if (block.matches("figure.evidence")) return [["Space", "look closely"]];
+	if (block.matches("figure.picture"))
+		return [
+			["Space", "look closely"],
+			["n", "note on this"],
+		];
+	// The condition on its decisions goes where they are decided.
+	if (block.matches('.conditions > [data-about="decisions"]'))
+		return document.querySelector("li[data-decision]")
+			? [
+					["f", beginsAt()],
+					["Enter", "the same"],
+				]
+			: [];
+	if (block.matches("#decisions > summary"))
+		return [
+			["f", beginsAt()],
+			["Enter", folded(block) ? "open" : "close", fold(block)],
+		];
+	// The non-blocking decisions' heading: one gesture leaves those that wait
+	// for nothing as they are; decisions.js says how many it would.
+	if (block.matches("details[data-non-blocking] > summary"))
+		return [
+			...(Number(block.dataset.leaves)
+				? [["A", `leave ${block.dataset.leaves} as is`]]
+				: []),
+			["Enter", folded(block) ? "open" : "close", fold(block)],
+		];
+	if (block.matches("details.section > summary"))
+		return [
+			["Enter", folded(block) ? "open" : "close", fold(block)],
+			["]", "next section"],
+		];
+	if (block.matches("summary"))
+		return [["Enter", folded(block) ? "open" : "close", fold(block)]];
+	if (block.closest("[data-quotable]")) return [["n", "note on this"]];
+	return [];
+};
+
+// A press of the pointer on a block's key is the key itself, pressed where
+// the reading rests.
+const NAMED = {
+	Space: " ",
+	Esc: "Escape",
+	"→": "ArrowRight",
+	"←": "ArrowLeft",
+};
+const press = (key, on) =>
+	on.dispatchEvent(
+		new KeyboardEvent("keydown", {
+			key: NAMED[key] ?? key,
+			// keys.js reads a capital by Shift, as a keyboard sends it.
+			shiftKey: /^[A-Z]$/.test(key),
+			bubbles: true,
+			cancelable: true,
+		}),
+	);
+
+const mark = made("span", "mark", ">");
+mark.setAttribute("aria-hidden", "true");
+// A rule down the gutter as far as the block goes, so that where the reading
+// rests is seen whole, however many lines it takes.
+const reach = made("span", "reach");
+const beside = made("div", "beside");
+const cursor = made("div", "cursor");
+cursor.setAttribute("data-desk", "");
+cursor.hidden = true;
+cursor.append(mark, reach, beside);
+main.append(cursor);
+
+const hint = (block, [keys, does, pressed]) => {
+	const button = made("button", "");
+	button.type = "button";
+	button.append(
+		...keys.split(" ").map((key) => made("kbd", "", key)),
+		` ${does}`,
+	);
+	// The reading keeps its place while the pointer presses.
+	button.addEventListener("mousedown", (event) => event.preventDefault());
+	button.addEventListener("click", () => {
+		if (pressed) pressed();
+		else press(keys.split(" ")[0], block);
+		place();
+	});
+	return button;
+};
+
+// What can be done with the whole pull request shows while the title holds the
+// focus, and a press on a link takes none: the title keeps it, or the panel
+// would go before the press ends and the click land on the page behind.
+document
+	.querySelector(".pull-request .whole")
+	?.addEventListener("mousedown", (event) => event.preventDefault());
+
+const onOutline = (block) => {
+	const section = block?.closest("details.section");
+	folds.forEach((line, index) => {
+		if (section && sections[index] === section)
+			line.setAttribute("aria-current", "true");
+		else line.removeAttribute("aria-current");
+	});
+};
+
+// The block the reading last rested on. A press of the pointer on bare page
+// takes the focus from it; the reading goes back there, so that the cursor is
+// never lost and j and k go on from where they were. Not while the press may
+// be the start of a selection, nor while words are selected: taking the focus
+// then would undo the selection under the owner's hand.
+let rested;
+let pointerDown = false;
+const comeBack = () => {
+	if (document.activeElement !== document.body) return;
+	if (document.querySelector("dialog[open], :popover-open")) return;
+	if (pointerDown || !getSelection().isCollapsed) return;
+	if (rested?.isConnected && rested.getClientRects().length)
+		rested.focus({ preventScroll: true });
+};
+
+const place = () => {
+	const block = document.activeElement?.closest?.("[data-reading]");
+	const shown =
+		!!block && main.contains(block) && block.getClientRects().length > 0;
+	if (shown) rested = block;
+	cursor.hidden = !shown;
+	onOutline(shown ? block : null);
+	if (!shown) return thisBlock([]);
+
+	const keys = keysOf(block);
+	beside.replaceChildren(...keys.map((key) => hint(block, key)));
+	thisBlock(keys);
+
+	// The mark stands at the block's first line, whatever the block's own face.
+	const style = getComputedStyle(block);
+	const top =
+		block.getBoundingClientRect().top -
+		main.getBoundingClientRect().top +
+		Number.parseFloat(style.paddingTop) +
+		Number.parseFloat(style.borderTopWidth);
+	cursor.style.top = `${top}px`;
+	const line = Number.parseFloat(style.lineHeight);
+	cursor.style.setProperty(
+		"--line",
+		`${Number.isNaN(line) ? Number.parseFloat(style.fontSize) * 1.6 : line}px`,
+	);
+	cursor.style.setProperty(
+		"--height",
+		`${
+			block.getBoundingClientRect().height -
+			Number.parseFloat(style.paddingTop) -
+			Number.parseFloat(style.paddingBottom) -
+			Number.parseFloat(style.borderTopWidth) -
+			Number.parseFloat(style.borderBottomWidth)
+		}px`,
+	);
+};
+
+// The outline goes to a section at a press. From a decision that is being
+// decided, the page comes back first.
+folds.forEach((line, index) => {
+	line.addEventListener("click", () => {
+		const heading = sections[index]?.querySelector("summary");
+		if (!heading) return;
+		if (document.body.dataset.focus) press("Escape", document.activeElement);
+		heading.focus({ preventScroll: true });
+		heading.scrollIntoView({ block: "start" });
+	});
+});
+
+// How many decisions still wait, on the outline: a number that goes when none do.
+const pullRequest = prNumber(
+	document.querySelector("[data-review-draft]")?.dataset.pr,
+);
+const count = () => {
+	const said = document.querySelector(
+		'[data-outline] [data-waits-for="decisions"]',
+	);
+	if (!said) return;
+	const { left } = progress(pullRequest);
+	said.textContent = left || "";
+	said.dataset.waits = left > 0;
+};
+count();
+
+// The page moves under the cursor when a section folds, a picture arrives or
+// the list of keys docks: the mark follows its block.
+const soon = () => requestAnimationFrame(place);
+document.addEventListener("focusin", soon);
+document.addEventListener("focusout", () =>
+	setTimeout(() => {
+		comeBack();
+		place();
+	}),
+);
+document.addEventListener("pointerdown", () => {
+	pointerDown = true;
+});
+document.addEventListener("pointerup", () => {
+	pointerDown = false;
+	setTimeout(comeBack);
+});
+document.addEventListener("toggle", soon, true);
+document.addEventListener("keys-docked", soon);
+document.addEventListener("drafts-changed", () => {
+	count();
+	soon();
+});
+addEventListener("resize", soon);
+addEventListener("load", soon);
+new ResizeObserver(soon).observe(main);
+new MutationObserver(soon).observe(document.body, {
+	attributes: true,
+	attributeFilter: ["data-focus", "data-decision-mode"],
+});
+soon();