proctolog 0.1.0

data/bin/proctolog

@@ -0,0 +1,330 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/proctolog/installation"
+
+# A checkout runs in its own bundle, whatever the calling project's. A gem
+# runs on what RubyGems installed with it, which its launcher has loaded.
+if Proctolog::Installation.here.checkout? && ENV["PROCTOLOG_BUNDLED"] != "1"
+  require "bundler"
+  require "rbconfig"
+
+  Bundler.with_unbundled_env do
+    exec({"BUNDLE_FROZEN" => "true", "BUNDLE_GEMFILE" => File.expand_path("../Gemfile", __dir__), "PROCTOLOG_BUNDLED" => "1"}, RbConfig.ruby, Gem.bin_path("bundler", "bundle"), "exec", RbConfig.ruby, __FILE__, *ARGV)
+  end
+end
+
+require_relative "../config/application"
+require_relative "../app/models/proctolog/project"
+require "rbconfig"
+require "thor"
+
+module Proctolog
+  # Opens the checkout --project names, or the one the command runs in.
+  module Booting
+    private
+
+    # A command prints what it was asked for and nothing else, and asks
+    # 1Password for no keys. The desk's log, with what Grouse says at boot it
+    # is missing, and the keys are for `serve`, which says so in the block.
+    def boot!
+      Project.current = Project.discover(options[:project] || Dir.pwd)
+      Desk.config.log_level = :error
+      Desk.config.x.reads_keys = false
+      yield Desk.config if block_given?
+      Desk.initialize! unless Desk.initialized?
+    end
+
+    # A pull request as the owner names one: an open one by its number, and
+    # one nobody has opened yet by its branch, or by its number, 01. Nil for
+    # an open one; the unopened one otherwise, or a sentence that says why not.
+    def unopened_by(named)
+      if named.match?(/\A[1-9]\d*\z/) then nil
+      elsif PullRequest.unopened?(named) then Unopened.find(named) || abort("No pull request waits unopened as #{named}: `proctolog unopened` lists those that do.")
+      else Unopened.on(named) || abort("Nothing is written for #{named}. Write its pull_request.md in #{Unopened.folder_of(named)}.")
+      end
+    end
+  end
+
+  class BurstCommands < Thor
+    include Booting
+
+    def self.exit_on_failure? = true
+
+    class_option :project, type: :string, aliases: "-C", desc: "The Git checkout whose bursts to open"
+
+    desc "new NAME", "Start a burst of your own, kept outside the repository"
+    long_desc <<~TEXT
+      Writes NAME.yml among your own bursts, beside your marks under ~/.local/share/proctolog, where every
+      checkout of this repository on this Mac finds it and Git never does. NAME is lowercase words joined by
+      hyphens; it is what `route` and the desk's addresses use. Name its pull requests with --pr, --top and
+      --stack, each as many times as needed: an open pull request by its number, one nobody has opened yet by
+      its branch, so that the burst still holds it once it is opened.
+    TEXT
+    option :pr, type: :string, repeatable: true, desc: "A pull request that stands alone, by its number, or its branch while not opened"
+    option :top, type: :string, repeatable: true, desc: "The top of a chain, followed down by base branches"
+    option :stack, type: :numeric, repeatable: true, desc: "A stack GitHub holds, by its number"
+    option :title, type: :string, desc: "Its name on the desk (from NAME when left out)"
+    map "new" => :start
+    def start(slug)
+      boot!
+      file = Burst.start(slug, name: options[:title], stacks: options.fetch(:stack, []), tops: listed(options.fetch(:top, [])), pull_requests: listed(options.fetch(:pr, [])))
+      puts "Wrote #{Project.current.from_root(file)}. Open it with: proctolog route #{slug}"
+    rescue Project::Missing, Failure => e
+      abort e.message
+    end
+
+    # Thor gives every group its own `tree`; the top level's already shows this one's.
+    desc "tree", "Print a tree of all available commands", hide: true
+    def tree = super
+
+    no_commands do
+      # As a burst file lists them: by number, or by branch while not opened.
+      def listed(named) = named.map { it.match?(/\A[1-9]\d*\z/) ? Integer(it) : (PullRequest.unopened?(it) ? unopened_by(it).branch : it) }
+    end
+
+    desc "list", "List the bursts this checkout opens, and where each is kept"
+    def list
+      boot!
+      Burst.all.each { puts format("%-24s %-5s %s", it.slug, it.own? ? "yours" : "repo", Project.current.from_root(it.file)) }
+    rescue Project::Missing, Failure => e
+      abort e.message
+    end
+  end
+
+  class UnopenedCommands < Thor
+    include Booting
+
+    def self.exit_on_failure? = true
+
+    class_option :project, type: :string, aliases: "-C", desc: "The Git checkout whose pull requests to read"
+    default_command :list
+
+    desc "list", "List the pull requests nobody has opened yet: number, branch, base and title"
+    def list
+      boot!
+      waiting = Unopened.all
+      puts "Nothing waits unopened. One is written as #{Unopened.folder}/BRANCH/#{Unopened::FILE}." if waiting.empty?
+      waiting.each { puts format("#%-4s %-32s into %-24s %s", it.number, it.branch, it.base, it.title) }
+    rescue Project::Missing, Failure => e
+      abort e.message
+    end
+
+    desc "folder BRANCH", "Print the folder a pull request nobody has opened yet is written in"
+    long_desc <<~TEXT
+      Prints where the pull request of BRANCH is written while nobody has opened it, whether anything is there
+      yet or not. Write pull_request.md in it: a title and a base as front matter, then the description, with
+      its pictures beside it, linked by their file names. The desk reads it from there under a number with a
+      leading zero, 01, and once the branch is opened on GitHub, the pull request is GitHub's.
+    TEXT
+    def folder(branch)
+      boot!
+      puts Unopened.folder_of(branch)
+    rescue Project::Missing => e
+      abort e.message
+    end
+
+    desc "tree", "Print a tree of all available commands", hide: true
+    def tree = super
+  end
+
+  class CLI < Thor
+    include Booting
+
+    def self.exit_on_failure? = true
+
+    class_option :project, type: :string, aliases: "-C", desc: "The Git checkout whose bursts to open"
+
+    desc "burst SUBCOMMAND", "Start a burst of your own, or list the bursts there are"
+    subcommand "burst", BurstCommands
+
+    desc "unopened SUBCOMMAND", "List the pull requests nobody has opened yet, or say where one is written"
+    subcommand "unopened", UnopenedCommands
+
+    desc "serve", "Open the desk on http://localhost:4040"
+    option :port, type: :numeric, default: 4040, aliases: "-p", desc: "The port to listen on"
+    def serve
+      boot! do |config|
+        config.log_level = :warn
+        config.x.reads_keys = true
+      end
+      require "rackup"
+      Release.newer&.then { puts it.news }
+      Housekeeping.start
+      Rackup::Handler.get("puma").run(Desk, Host: "localhost", Port: options[:port])
+    rescue Errno::EADDRINUSE
+      abort "Port #{options[:port]} is taken. If that is the desk, it is open at http://localhost:#{options[:port]}; " \
+            "for a second one: proctolog serve --port #{options[:port] + 1}"
+    rescue Project::Missing => e
+      abort e.message
+    end
+
+    desc "route [BURST]", "Print the order to take a burst in"
+    def route(burst = nil)
+      boot!
+      burst ||= Burst.latest&.slug
+      Burst.find(burst).route.each do |stop|
+        puts format("%-6s #%-5s %s", stop.stacked? ? "#{stop.layer}/#{stop.of}" : "alone", stop.number, stop.title)
+      end
+    rescue Project::Missing => e
+      abort e.message
+    rescue Burst::Missing, Github::Unreachable, Failure => e
+      abort e.message
+    end
+
+    desc "handover [BURST]", "Hand what the owner decided so far to the agent that runs it"
+    long_desc <<~TEXT
+      Takes a pass as `e` on the desk does, with no page open: the owner's open notes, their choices on the
+      decisions, the code comments nobody resolved and their replies to answers that came back. Writes it as a
+      handover folder where the desk keeps them, and says where its brief is: read it, carry it out, and answer
+      in the one file it names. The desk takes that answer in, for the owner to confirm.
+
+      The owner may be halfway through: what they have not reviewed yet stays out, and the brief asks that it
+      be left as it is. What an earlier pass handed over and nobody answered is held back, so that two agents
+      never do the same work; --again takes it into this pass too. --part narrows the pass to one part of the
+      burst. With nothing to hand over, it writes nothing.
+    TEXT
+    option :part, type: :string, desc: "One part of the burst: its stack's or top's number, or alone"
+    option :again, type: :boolean, default: false, desc: "Take again what an earlier pass handed over and nobody answered"
+    def handover(burst = nil)
+      boot!
+      burst = Burst.find(burst || Burst.latest&.slug || abort("#{Project.current.root} has no burst. Start one: proctolog burst new NAME"))
+      route = burst.route
+      focus = Focus.on(route, options[:part])
+      abort "#{burst.name} has no part #{options[:part]}. Its parts: #{route.parts.map(&:to_param).join(", ")}" if options[:part] && focus.whole?
+      worklist = Rounds.new(burst, route:, focus:).worklist(batch_id: SecureRandom.uuid, again: options[:again])
+      handover = burst.handover(route, focus:, worklist:)
+      puts Handover::Taken.new(burst:, worklist:, brief: (handover.write if worklist.items.any?), answer: handover.answer_file)
+    rescue Project::Missing, Burst::Missing, Github::Unreachable, Failure => e
+      abort e.message
+    end
+
+    desc "check [PULL_REQUEST]", "Check a pull request's description as the desk reads it, or a file's with --file"
+    long_desc <<~TEXT
+      Reads a description with the desk's own parser and says, line by line, what would keep the desk from
+      reading it well (a fault) and what it only advises (a warning). PULL_REQUEST checks an open pull
+      request's description as GitHub holds it now, by its number, or one nobody has opened yet by its branch
+      or its number (01), with its pictures; --file checks a local Markdown file before it is published.
+      GitHub renders each, and keeps nothing of it.
+
+      Exits 0 with no faults, 1 with faults, and 2 when GitHub could not be asked.
+    TEXT
+    option :file, type: :string, aliases: "-f", desc: "A local Markdown file to check before it is published"
+    def check(named = nil)
+      boot!
+      github = Github.new(Project.current.github_repository || abort("#{Project.current.root} has no GitHub repository as its origin."))
+      named || options[:file] || abort("Name a pull request by its number or its branch, or a file with --file.")
+      markdown, rendering = if options[:file]
+        File.read(options[:file]).then { [it, github.rendered(it)] }
+      elsif (waiting = unopened_by(named))
+        [waiting.description.to_s, waiting.rendering]
+      else
+        github.described(Integer(named))
+      end
+      Check.new(markdown, rendering:).tap { puts it }.then { exit(it.passed? ? 0 : 1) }
+    rescue Github::Unreachable => e
+      warn e.message
+      exit 2
+    rescue Project::Missing, Failure, SystemCallError, ArgumentError => e
+      abort e.message
+    end
+
+    desc "themes", "Print the themes a decision may name, with what each means"
+    def themes
+      boot!
+      Theme.all.each { puts format("%-10s %s", it.name, it.meaning) }
+    rescue Project::Missing, Failure => e
+      abort e.message
+    end
+
+    desc "version", "Print which PRoctolog this is"
+    map %w[-v --version] => :version
+    def version = puts("PRoctolog #{VERSION}")
+
+    desc "install", "Link zsh's completion and the agent skills to this PRoctolog"
+    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.
+    TEXT
+    def install
+      puts Installation.here.install
+    rescue Installation::Refused => e
+      abort e.message
+    end
+
+    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.
+    TEXT
+    def update
+      installation = Installation.here
+      return take_with_git(installation) if installation.checkout?
+
+      Desk.initialize! unless Desk.initialized?
+      latest = Release.ask || abort("RubyGems named no PRoctolog: it did not answer, or holds none yet. Try again later.")
+      return puts("PRoctolog #{Release.running} is the latest.") unless latest > Release.running
+
+      installation.rv_tool? ? take_with_rv(latest) : take_with_gem(latest)
+    rescue Installation::Refused, RuntimeError => e
+      abort e.message
+    end
+
+    no_commands do
+      # rv runs as the shell would, not on the Ruby and gems it gave this one.
+      def take_with_rv(latest)
+        Outside.run do |environment|
+          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")
+        end
+      end
+
+      # With this Ruby's own gem command, into the gems this one is among.
+      def take_with_gem(latest)
+        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")
+      end
+
+      # The checkout's own bundle, on this Ruby, as bin/proctolog runs it.
+      def take_with_git(installation)
+        puts installation.pull
+        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)
+      end
+
+      def taken(latest) = "Installed PRoctolog #{latest}. Restart the desk to run it: one open now still runs #{Release.running}."
+    end
+
+    desc "doctor", "Say what this Mac and this checkout lack, a line each with the fix"
+    long_desc <<~TEXT
+      Checks what the desk needs (gh signed in, the launcher on the PATH, a GitHub checkout gh can read, a burst
+      file) and what it would like (the PR-writing skill, Chrome, Diffle, ImageMagick, ffmpeg, an app.yml whose
+      programs are there, a free port 4040). Lines start ok, !! for a need that is missing, or -- for a nicety
+      that is off.
+
+      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)
+      rescue Project::Missing
+        nil
+      end
+      Desk.initialize! unless Desk.initialized?
+      Doctor.new(project).tap { puts it }.then { exit(it.fine? ? 0 : 1) }
+    end
+  end
+end
+
+Proctolog::CLI.start

data/completions/_proctolog

@@ -0,0 +1,143 @@
+#compdef proctolog
+
+# Completes proctolog: its commands, options and a checkout's burst names,
+# your own ones first, then the repository's from bursts/ and from reviews/,
+# where burst files were kept before; for check and burst new, the open pull
+# requests of the desk's last reading, with their titles, and the branches
+# whose pull requests nobody has opened yet; for unopened folder, every
+# branch of the checkout.
+
+# "owner/name" of the checkout's GitHub origin.
+_proctolog_repository() {
+  local remote
+  remote=$(git -C "$1" remote get-url origin 2>/dev/null)
+  print -r -- ${${remote#*github.com[:/]}%.git}
+}
+
+# The open pull requests the desk last read for this checkout, as
+# "number:title", read from the reading it keeps; none when it keeps none.
+_proctolog_pull_requests() {
+  local repository reading
+  repository=$(_proctolog_repository "$1")
+  reading=${PROCTOLOG_CACHE:-$HOME/.cache/proctolog}/$repository/readings/${repository/\//-}.json
+  [[ -r $reading ]] || return
+  ruby -rjson -e 'JSON.parse(File.read(ARGV[0])).fetch("nodes").each { |node| puts "#{node["number"]}:#{node["title"].tr(":", " ")}" }' "$reading" 2>/dev/null
+}
+
+# The pull requests nobody has opened yet, as "branch:title", read from
+# their folders in the store; the title is the front matter's.
+_proctolog_unopened() {
+  local folder
+  folder=${PROCTOLOG_DATA:-$HOME/.local/share/proctolog}/$(_proctolog_repository "$1")/unopened
+  [[ -d $folder ]] || return
+  ruby -ryaml -e 'Dir.glob("**/pull_request.md", base: ARGV[0]).sort.each { |file| title = File.read(File.join(ARGV[0], file))[/\A---\n(.*?)^---/m, 1]&.then { YAML.safe_load(it)&.fetch("title", nil) rescue nil }; puts "#{File.dirname(file)}:#{title.to_s.tr(":", " ")}" }' "$folder" 2>/dev/null
+}
+
+# The checkout's own branches.
+_proctolog_branches() {
+  git -C "$1" for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null
+}
+
+# A burst's parts, as `handover --part` takes them: its stacks and tops by
+# number, and alone; read from the first of the burst's files it is given.
+_proctolog_parts() {
+  [[ -r $1 ]] || return
+  ruby -ryaml -e 'burst = YAML.safe_load_file(ARGV[0]) || {}; puts [*burst["stacks"], *burst["tops"], "alone"]' "$1" 2>/dev/null
+}
+
+_proctolog() {
+  local root own named
+  local -a commands burst_commands unopened_commands bursts pull_requests unopened branches parts project files
+  commands=(
+    'serve:Open the desk on http://localhost:4040'
+    'route:Print the order to take a burst in'
+    'handover:Hand what the owner decided so far to the agent that runs it'
+    'burst:Start a burst of your own, or list the bursts there are'
+    'unopened:List the pull requests nobody has opened yet, or say where one is written'
+    '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'
+    'version:Print which PRoctolog this is'
+    'install:Link zsh'"'"'s completion and the agent skills to this PRoctolog'
+    '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'
+  )
+  burst_commands=(
+    'new:Start a burst of your own, kept outside the repository'
+    'list:List the bursts this checkout opens, and where each is kept'
+    'help:Describe the burst commands, or one of them'
+  )
+  unopened_commands=(
+    'list:List the pull requests nobody has opened yet'
+    'folder:Print the folder a pull request nobody has opened yet is written in'
+    'help:Describe the unopened commands, or one of them'
+  )
+  project=('(-C --project)'{-C,--project}'[Git checkout]:directory:_directories')
+  root=$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null)
+  own=${PROCTOLOG_DATA:-$HOME/.local/share/proctolog}/$(_proctolog_repository "$root")/bursts
+  bursts=($own/*.yml(N:t:r) $root/.proctolog/{bursts,reviews}/*.yml(N:t:r))
+  bursts=(${(u)bursts})
+
+  _arguments -C '1: :->command' '*:: :->argument'
+
+  case $state in
+    command) _describe -t commands 'command' commands ;;
+    argument)
+      case $words[1] in
+        serve) _arguments '(-p --port)'{-p,--port}'[The port to listen on]:port:' $project ;;
+        route) _arguments $project "1:burst:(${bursts})" ;;
+        handover)
+          named=${${words[2,-1]:#-*}[1]}
+          [[ -n $named ]] || named=${${(f)"$(ls -t $own/*.yml(N) $root/.proctolog/{bursts,reviews}/*.yml(N) 2>/dev/null)"}[1]:t:r}
+          files=($own/$named.yml(N) $root/.proctolog/{bursts,reviews}/$named.yml(N))
+          parts=(${(f)"$(_proctolog_parts "$files[1]")"})
+          _arguments $project \
+            "--part[One part of the burst, by its stack or top, or alone]:part:(${parts})" \
+            '--again[Take again what an earlier pass handed over and nobody answered]' \
+            "1:burst:(${bursts})" ;;
+        burst)
+          if (( CURRENT == 2 )); then
+            _describe -t commands 'burst command' burst_commands
+          else
+            case $words[2] in
+              new)
+                pull_requests=(${(f)"$(_proctolog_pull_requests "$root")"})
+                unopened=(${(f)"$(_proctolog_unopened "$root")"})
+                _arguments $project \
+                  '*--pr[A pull request that stands alone]:pull request:{_describe -t pull-requests "open pull request" pull_requests; _describe -t unopened "not opened yet" unopened}' \
+                  '*--top[The top of a chain, followed down by base branches]:pull request:{_describe -t pull-requests "open pull request" pull_requests; _describe -t unopened "not opened yet" unopened}' \
+                  '*--stack[A stack GitHub holds, by its number]:stack number:' \
+                  '--title[Its name on the desk]:title:' \
+                  '2:burst name (lowercase words joined by hyphens):' ;;
+              list) _arguments $project ;;
+              help) _describe -t commands 'burst command' burst_commands ;;
+            esac
+          fi
+          ;;
+        unopened)
+          if (( CURRENT == 2 )); then
+            _describe -t commands 'unopened command' unopened_commands
+          else
+            case $words[2] in
+              list) _arguments $project ;;
+              folder)
+                branches=(${(f)"$(_proctolog_branches "$root")"})
+                _arguments $project "2:branch:(${branches})" ;;
+              help) _describe -t commands 'unopened command' unopened_commands ;;
+            esac
+          fi
+          ;;
+        check)
+          pull_requests=(${(f)"$(_proctolog_pull_requests "$root")"})
+          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 ;;
+        help) _describe -t commands 'command' commands ;;
+      esac
+      ;;
+  esac
+}
+
+_proctolog "$@"

data/config/application.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# The PRoctolog desk: a local page over a burst's pull requests.
+# From a checkout it has its own bundle; installed as a gem, the gems RubyGems
+# installed with it. Either way it reads only the selected project's files.
+
+require "bundler/setup" if File.exist?(File.expand_path("../Gemfile", __dir__))
+require_relative "../lib/proctolog/version"
+require_relative "../lib/proctolog/installation"
+require "ipaddr"
+require "tmpdir"
+require "action_controller/railtie"
+# Grouse, the overlay the owner writes notes on the desk with, keeps them in a
+# database, records their voice notes and screenshots, and reads them later.
+require "active_record/railtie"
+require "active_storage/engine"
+require "active_job/railtie"
+begin
+  require "grouse-rails"
+rescue LoadError
+  # Not bundled: the Gemfile's :grouse group is optional, as the gem is private.
+end
+
+# The agent shell has no LANG, and descriptions hold dashes and arrows.
+Encoding.default_external = Encoding.default_internal = Encoding::UTF_8
+
+module Proctolog
+  class Desk < Rails::Application
+    # What is the owner's beyond any one repository: the secret below, and
+    # beside it a folder per repository (Project).
+    def self.data = Pathname(ENV.fetch("PROCTOLOG_DATA") { File.expand_path("~/.local/share/proctolog") })
+
+    # What the desk read and can read again: GitHub's answers, pictures, and
+    # which PRoctolog is the latest (Release).
+    def self.cache = Pathname(ENV.fetch("PROCTOLOG_CACHE") { File.expand_path("~/.cache/proctolog") })
+
+    # Grouse's notes on the desk itself, with the files they keep
+    # (config/database.yml, config/storage.yml): one store for every checkout
+    # the desk reviews, as the notes are about the desk. A test process keeps
+    # one of its own and drops it when it ends.
+    def self.grouse? = defined?(Grouse::Engine).present?
+
+    def self.grouse_notes
+      (Rails.env.test? ? scratch : data).join("grouse_notes").tap(&:mkpath)
+    end
+
+    # A value made once and kept in the data folder, outside the installed app
+    # and Git, for this user alone.
+    def self.kept(name)
+      file = data.join(name)
+      file.exist? ? file.read.strip : yield.tap { file.dirname.mkpath && file.write(it, perm: 0o600) }
+    end
+
+    def self.scratch = @scratch ||= Pathname(Dir.mktmpdir("proctolog")).tap { |made| at_exit { made.rmtree } }
+
+    config.root = File.expand_path("..", __dir__)
+    config.load_defaults 8.1
+    config.eager_load = false
+    config.enable_reloading = true
+    config.consider_all_requests_local = true
+    # Kept outside the installed app so an update does not sign out an open desk.
+    config.secret_key_base = kept("secret_key_base") { SecureRandom.hex(64) }
+    # Whatever the environment: a page of another site that points a name of
+    # its own at this Mac is turned away.
+    config.hosts = ["localhost", IPAddr.new("127.0.0.0/8"), IPAddr.new("::1")]
+    config.logger = ActiveSupport::Logger.new($stdout)
+    # Grouse says at boot what is not set up yet, which its tests need not hear.
+    config.log_level = Rails.env.test? ? :error : :warn
+    config.cache_store = :memory_store
+    # A desk at work keeps what it read of GitHub for its next start. Its tests
+    # read a made-up GitHub and must leave no trace of it beside the real one.
+    config.x.keeps_readings = !Rails.env.test?
+    config.public_file_server.enabled = true
+    config.public_file_server.headers = {"cache-control" => "no-cache"}
+
+    # Jobs run in the desk's own process: the pictures and pull requests it
+    # reads ahead of the pages that show them, and Grouse's write-up of a note
+    # a moment after it is sent. Its tests queue them and run none they do
+    # not ask for.
+    config.active_job.queue_adapter = Rails.env.test? ? :test : :async
+    # Whether Grouse is given the owner's keys from 1Password (config/keys.yml):
+    # when the desk serves, and for Rails' own commands such as grouse:doctor.
+    # A `proctolog` command that only prints asks 1Password for nothing.
+    config.x.reads_keys = Rails.env.development?
+    config.active_storage.service = :local
+    config.active_storage.variant_processor = :disabled
+    # The migrations are the record; the desk brings its database up to them
+    # whenever it boots (config/initializers/grouse_notes.rb).
+    config.active_record.dump_schema_after_migration = false
+    # A note says which templates drew what the owner pointed at. Only where
+    # the desk runs for its owner: its tests read pages without them.
+    config.action_view.annotate_rendered_view_with_filenames = Rails.env.development?
+  end
+end

data/config/database.yml

@@ -0,0 +1,16 @@
+# The desk's one database: Grouse's notes on the desk itself, their review
+# sessions and the files Active Storage keeps for them (config/application.rb).
+default: &default
+  adapter: sqlite3
+  database: <%= Proctolog::Desk.grouse_notes.join("notes.sqlite3") %>
+  # The desk's own, wherever it is started: `serve` runs in the checkout under
+  # review, whose db/migrate is that app's.
+  migrations_paths: <%= Rails.root.join("db/migrate") %>
+  max_connections: 5
+  timeout: 5000
+
+development:
+  <<: *default
+
+test:
+  <<: *default

data/config/environment.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# What bin/rails loads before a task that needs the desk booted.
+require_relative "application"
+
+Rails.application.initialize!