agentilda 1.0.3 → 2.0.1

data/lib/agentilda/feature.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "agentilda/ordinal"
+require "agentilda/status"
+
 module Agentilda
   # Lowercase in the middle of a title, capitalised at the front.
   SMALL_WORDS = %w[a an and as at but by for from in into nor of on or per the to via vs with].freeze
@@ -44,21 +47,22 @@ module Agentilda
     }.join(" ")
   end
 
-  # The one place a plan folder's name is spelled out: `NNN.MM-<emoji>--<slug>`.
+  # The one place a plan folder's name is spelled out: `NNN.MM-<emoji> → <slug>`.
   #
-  # The double dash after the emoji is deliberate: an emoji renders two cells
-  # wide and visually swallows a single dash beside it, so `🔎-refactor` reads
+  # The spaced arrow after the emoji is deliberate: an emoji renders two cells
+  # wide and visually swallows a bare dash beside it, so `🔎-refactor` reads
   # as if the emoji and the slug were touching. Everything that mints or
   # renames a folder goes through here; {Feature.parse} accepts the older
-  # single-dash spelling too, and `resync dirs` normalises it on contact.
+  # `--` and single-dash spellings too, and `resync dirs` migrates them on
+  # contact.
   #
   # @param ordinal [Agentilda::Ordinal, String]
   # @param status [Agentilda::Status]
   # @param slug [String]
   # @return [String]
-  def self.plan_dirname(ordinal, status, slug) = "#{ordinal}-#{status.emoji}--#{slug}"
+  def self.plan_dirname(ordinal, status, slug) = "#{ordinal}-#{status.emoji} → #{slug}"
 
-  # One `NNN.MM-<emoji>--<slug>` folder, decoded.
+  # One `NNN.MM-<emoji> → <slug>` folder, decoded.
   #
   # @!attribute [r] ordinal
   #   @return [Agentilda::Ordinal]
@@ -82,13 +86,14 @@ module Agentilda
       ordinal = Ordinal.from_dirname(dirname) or return nil
 
       rest = dirname.sub(/\A[\d.]+[-_]/, "")
-      head, tail = rest.split(/[-_]/, 2)
+      head, tail = rest.split(/\s*→\s*|[-_]/, 2)
 
       # A leading segment with no ASCII word character is the status emoji.
       # The slug strips any further separators: the canonical spelling puts
-      # two dashes after the emoji, and folders from before that rule put one.
+      # a spaced arrow after the emoji, and folders from before that rule put
+      # two dashes, or one.
       status = (Agentilda.status_for_emoji(head) if tail && !head.to_s.empty? && !head.match?(/[A-Za-z0-9]/))
-      slug = status ? tail.sub(/\A[-_]+/, "") : rest
+      slug = status ? tail.sub(/\A[-_\s]+/, "") : rest
 
       new(ordinal:, status: status || STATUS_BY_KEY.fetch(:new), slug:, dirname:, path:)
     end
@@ -124,130 +129,4 @@ module Agentilda
     # @return [Integer, nil]
     def <=>(other) = other.is_a?(self.class) ? [ordinal, dirname] <=> [other.ordinal, other.dirname] : nil
   end
-
-  # A plan folder as the state machine sees it: which files exist, what they
-  # say, and which pull requests they record.
-  #
-  # It exists because the invariants ask the same questions repeatedly and
-  # {Feature} is a frozen `Data` with nowhere to memoize the answers.
-  class Subject
-    # @param feature [Agentilda::Feature]
-    def initialize(feature)
-      @feature = feature
-      @reads = {}
-    end
-
-    # @return [Agentilda::Feature]
-    attr_reader :feature
-
-    # @return [Agentilda::Status] the status the folder name claims
-    def status = feature.status
-
-    # @param name [String] a bare filename
-    # @return [Boolean]
-    def file?(name) = File.file?(File.join(feature.path, name))
-
-    # @param name [String]
-    # @return [String, nil] contents, or nil when absent
-    def read(name)
-      @reads.fetch(name) do
-        @reads[name] = file?(name) ? File.read(File.join(feature.path, name), encoding: "UTF-8") : nil
-      end
-    end
-
-    # @return [Array<Agentilda::PullRequest>]
-    def pull_requests = @pull_requests ||= PullRequests.new(dir: feature.path).all
-
-    # The specification's own Goal section, verbatim and at most two
-    # paragraphs. Anything that paraphrases the spec is a second copy that
-    # drifts; quoting it is not — which is why the pull request body and the
-    # index both read it from here rather than each writing their own.
-    #
-    # @return [Array<String>] paragraphs, empty when there is no Goal to read
-    def goal
-      body = read("spec.md").to_s
-      section = body[/^\#{"#"}{2,3}\s*Goals?\b[^\n]*\n+(.*?)(?=\n\#{"#"}{1,3}\s|\z)/mi, 1]
-
-      paragraphs(section) || paragraphs(body.sub(/\A\s*\#{"#"}[^\n]*\n/, "")) || []
-    end
-
-    # Specifications written before the template existed have no Goal section,
-    # and they are exactly the ones an index most needs to describe. So the
-    # opening prose stands in — skipping headings, quotes, lists and tables,
-    # which describe the document rather than the work.
-    #
-    # @param text [String, nil]
-    # @return [Array<String>, nil] nil when there is no prose to be had
-    def paragraphs(text)
-      found = text.to_s.strip.split(/\n{2,}/)
-        .map(&:strip)
-        .reject { |p| p.empty? || p.match?(/\A[\#>|\-*\d`_=]/) }
-        .first(2)
-
-      found.empty? ? nil : found
-    end
-
-    # The questions `blocked.md` still names, by number.
-    #
-    # Empty means one of two very different things, and a caller that treats
-    # them alike is how a folder with thirty kilobytes of open questions gets
-    # reported as "nothing left open": either there is no `blocked.md` at all,
-    # or there is one whose questions are not written as `## B<n>` and are
-    # therefore invisible to every part of this tool. Ask {#file?} which.
-    #
-    # @return [Array<Integer>]
-    def open_blocks = Agentilda.block_numbers(read("blocked.md"), OPEN_BLOCK)
-
-    # The answers waiting in `blocked.md`, by number. `## A1` settles `## B1`.
-    #
-    # Waiting, not folded. An `## A<n>` heading is not the same as a settled
-    # question: one may say in its own body that it is a draft pending a
-    # conversation. `lando-broker` makes that call; this only counts headings.
-    #
-    # @return [Array<Integer>]
-    def block_answers = Agentilda.block_numbers(read("blocked.md"), ANSWER_BLOCK)
-
-    # A `blocked.md` this tool cannot read: the file is there, and not one
-    # question in it is written as `## B<n>`. Nothing can drain it and nothing
-    # currently says so, which is the whole reason this exists.
-    #
-    # @return [Boolean]
-    def unreadable_block? = file?("blocked.md") && open_blocks.empty?
-
-    # @return [String, nil] why the folder's name is not justified
-    def violation = status.violation(self)
-
-    # @return [Boolean] whether the name matches the contents
-    def consistent? = violation.nil?
-
-    # @return [Agentilda::StateMachine] positioned at the current state
-    def machine = StateMachine.new(self)
-
-    # @return [Array<Symbol>] states reachable right now, guards applied
-    def allowed = machine.allowed
-
-    # @return [Agentilda::Status, nil] the state these contents justify
-    def best_fit = machine.best_fit
-
-    # Move the folder into +status+ — the side effect a transition *is*.
-    #
-    # The {Feature} is a frozen `Data` holding the old name, so it is replaced
-    # rather than mutated, and the memoized reads go with it.
-    #
-    # @param status [Agentilda::Status]
-    # @return [Agentilda::Feature] the feature under its new name
-    # @raise [Agentilda::Error] when the target name is already taken
-    def rename_to(status)
-      return @feature if status.key == @feature.status.key
-
-      target = File.join(File.dirname(@feature.path), @feature.dirname_as(status))
-      unless Agentilda.move_directory(@feature.path, target)
-        raise Error, "cannot rename #{@feature.dirname} — #{File.basename(target)} already exists"
-      end
-
-      @reads = {}
-      @pull_requests = nil
-      @feature = Feature.parse(target) or raise Error, "#{File.basename(target)} is not a plan folder"
-    end
-  end
 end

data/lib/agentilda/frontmatter.rb

@@ -12,12 +12,14 @@ module Agentilda
   # `create` reported a missing `title:` on a file whose title was right there.
   # One parser, one list of permitted classes, so that cannot happen twice.
   module Frontmatter
+    # rubocop: disable Lint/OrAssignmentToConstant
     # Frontmatter, then body.
-    PATTERN = /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
+    PATTERN ||= /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
 
     # Dates and timestamps are ordinary frontmatter, so they load. Nothing else
     # does: the point of `safe_load` is that a seed file cannot name a class.
-    PERMITTED_CLASSES = [Date, Time].freeze
+    PERMITTED_CLASSES ||= [Date, Time].freeze
+    # rubocop: enable Lint/OrAssignmentToConstant
 
     class << self
       # @param content [String] a whole markdown file

data/lib/agentilda/github.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "tty/command"
 
 module Agentilda
   # The `gh` CLI, wrapped thinly.
@@ -25,8 +26,15 @@ module Agentilda
     # @return [Array<Hash>] `{number:, title:, url:, branch:, files:}`
     def pulls(state: "all")
       out = UI.spinning("Fetching pull requests from GitHub") {
-        @command.run("gh", "pr", "list", "--state", state, "--limit", @limit.to_s,
-          "--json", FIELDS.join(",")).out
+        @command.run("gh",
+          "pr",
+          "list",
+          "--state",
+          state,
+          "--limit",
+          @limit.to_s,
+          "--json",
+          FIELDS.join(",")).out
       }
 
       # `gh` can exit 0 having printed NOTHING — most often when it cannot reach
@@ -39,12 +47,12 @@ module Agentilda
       JSON.parse(out).map do |pr|
         {
           number: pr["number"],
-          title: pr["title"].to_s,
-          url: pr["url"],
+          title:  pr["title"].to_s,
+          url:    pr["url"],
           branch: pr["headRefName"].to_s,
-          files: Array(pr["files"]).map { |f| f["path"] }.compact,
-          state: self.class.state_label(pr),
-          open: pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN"
+          files:  Array(pr["files"]).map { |f| f["path"] }.compact,
+          state:  self.class.state_label(pr),
+          open:   pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN"
         }
       end
     rescue TTY::Command::ExitError, JSON::ParserError => e
@@ -107,10 +115,10 @@ module Agentilda
       pr = JSON.parse(out)
       {
         number: pr["number"],
-        title: pr["title"].to_s,
-        url: pr["url"].to_s,
-        state: self.class.state_label(pr),
-        body: pr["body"].to_s
+        title:  pr["title"].to_s,
+        url:    pr["url"].to_s,
+        state:  self.class.state_label(pr),
+        body:   pr["body"].to_s
       }
     rescue TTY::Command::ExitError, JSON::ParserError => e
       raise Error, "could not read pull request #{ref}: #{e.message.lines.first.to_s.strip}"

data/lib/agentilda/index.rb

@@ -23,16 +23,16 @@ module Agentilda
 
     # Documents that get a proper name rather than their filename.
     ARTIFACT_NAMES = {
-      "spec.md" => "Spec",
-      "plan.md" => "Plan",
+      "spec.md"          => "Spec",
+      "plan.md"          => "Plan",
       "pull-requests.md" => "Pull Requests",
-      "linear.md" => "Linear",
-      "blocked.md" => "Blocked",
-      "delayed.md" => "Deferred",
-      "rewrite.md" => "Rewrite",
-      "deployed.md" => "Deployed",
-      "rollback.md" => "Rollback",
-      "discarded.md" => "Discarded"
+      "linear.md"        => "Linear",
+      "blocked.md"       => "Blocked",
+      "delayed.md"       => "Deferred",
+      "rewrite.md"       => "Rewrite",
+      "deployed.md"      => "Deployed",
+      "rollback.md"      => "Rollback",
+      "discarded.md"     => "Discarded"
     }.freeze
 
     # @param tree [Agentilda::Tree]
@@ -189,9 +189,9 @@ module Agentilda
     # @return [String]
     def footer
       counts = tree.subjects.each_with_object(Hash.new(0)) { |s, h| h[s.status] += 1 }
-        .map { |status, n| "#{status.emoji} #{n}" }.join("   ")
+                   .map { |status, n| "#{status.emoji} #{n}" }.join("   ")
 
-      "\n---\n\n#{tree.subjects.size} #{(tree.subjects.size == 1) ? "plan" : "plans"}   #{counts}\n"
+      "\n---\n\n#{tree.subjects.size} #{tree.subjects.size == 1 ? "plan" : "plans"}   #{counts}\n"
     end
 
     # @param href [String]

data/lib/agentilda/keyboard.rb

@@ -17,31 +17,42 @@ module Agentilda
   class Keyboard
     # Key → what it does, rendered by {#help} and dispatched by {#handle}.
     BINDINGS = [
-      ["h  ?", "this help"],
+      ["h", "this help"],
+      ["?", "about agentilda"],
+      ["s", "select the next running agent; arrows move the selection"],
+      ["k", "mark the selected agent to be killed (STOP, 15s, then kill -9)"],
+      ["x", "extend the selected agent's clock by 10 minutes, per press"],
+      ["ENTER", "apply the pending changes in the dialog"],
+      ["ESC", "discard the dialog, then clear the selection"],
       ["w", "ask every running agent to wrap up as fast as possible"],
       ["n", "ask agents to write out what they have and stop; the loop continues"],
       ["q", "write out, stop everything, and quit after a #{Control::GRACE}s grace"],
-      ["ctrl-c", "interrupt the run, as ever"]
+      ["ctrl-c", "agents leave a resume note and stop, then quit; press again to abort now"]
     ].freeze
 
+    # @param input [IO]
+    # @param sink [Agentilda::Console, nil] where the table keys go; nil
+    #   when there is no screen, in which case they do nothing
     # @return [Agentilda::Keyboard, nil] a running listener, or nil when
     #   STDIN is not a terminal
-    def self.listen(input: $stdin)
+    def self.listen(input: $stdin, sink: nil)
       return nil unless input.tty?
 
-      new(input:).start
+      new(input:, sink:).start
     end
 
     # @param input [IO]
-    def initialize(input: $stdin)
+    # @param sink [Agentilda::Console, nil]
+    def initialize(input: $stdin, sink: nil)
       @input = input
+      @sink = sink
     end
 
     # @return [self]
     def start
       @thread = Thread.new do
         Thread.current.report_on_exception = false
-        loop { handle(@input.getch) }
+        loop { handle(read_key) }
       rescue IOError, Errno::EIO
         # STDIN went away; a keyboard with no keys just stops listening.
       end
@@ -52,17 +63,41 @@ module Agentilda
     def stop
       @thread&.kill
       @thread = nil
+      restore
+    end
+
+    # `getch` puts the terminal in raw mode for the length of one read and
+    # restores it afterwards — but the listener spends almost all its life
+    # blocked inside that read, and {#stop} kills it there, which leaves
+    # the mode behind. Raw mode has output post-processing off, so a "\n"
+    # written after it drops a line without returning the cursor to column
+    # zero: the run report then starts wherever the previous line ended and
+    # staircases down the screen. Nothing else puts the mode back, so this
+    # does.
+    #
+    # @return [void]
+    def restore
+      @input.cooked! if @input.tty?
+    rescue IOError, SystemCallError
+      # No terminal left to put back; there is nothing to restore it to.
     end
 
     # @param key [String, nil]
     # @return [void]
     def handle(key)
       case key
-      when "h", "?" then UI.popup("Keys", help)
+      when "h" then @sink ? @sink.toggle_help : UI.popup("Keys", help)
+      when "?" then @sink ? @sink.toggle_about : UI.popup("About", about)
+      when "s", "\e[B" then @sink&.select_next
+      when "\e[A" then @sink&.select_prev
+      when "k" then @sink&.toggle_kill
+      when "x" then @sink&.extend
+      when "\r", "\n" then @sink&.apply
+      when "\e" then @sink&.escape
       when "w" then acted("w — agents asked to wrap up") { Control.wrap_up! }
       when "n" then acted("n — agents asked to write out and stop") { Control.stop! }
       when "q" then acted("q — quitting; #{Control::GRACE}s grace to write out") { Control.quit! }
-      when "\u0003" then Thread.main.raise(Interrupt)
+      when "\u0003" then interrupt
       end
     end
 
@@ -72,8 +107,36 @@ module Agentilda
       BINDINGS.map { |key, does| "#{key.ljust(width)}   #{does}" }.join("\n")
     end
 
+    # @return [String] the version and a reminder of how to leave
+    def about = "Agentilda Version #{Agentilda::VERSION}\n\nThanks for using this! Press 'q' to exit and stop all agents."
+
     private
 
+    # ESC alone and ESC-[-A are the same first byte. Wait a few
+    # milliseconds for the rest before deciding it was a bare ESC.
+    #
+    # @return [String]
+    def read_key
+      key = @input.getch
+      return key unless key == "\e"
+
+      if IO.select([@input], nil, nil, 0.05)
+        rest = @input.read_nonblock(2, exception: false)
+        return "\e#{rest}" if rest.is_a?(String)
+      end
+      key
+    end
+
+    # Raw mode swallows the signal, so the key stands in for it: the first
+    # press lets agents write down where they got to, the second aborts.
+    #
+    # @return [void]
+    def interrupt
+      return Thread.main.raise(Interrupt) if Control.interrupted?
+
+      acted("ctrl-c — agents leaving resume notes; #{Control::GRACE}s grace, ctrl-c again to abort") { Control.interrupt! }
+    end
+
     # A keypress with no acknowledgement looks like a keypress that did
     # nothing, so each one says what it just asked for.
     #
@@ -82,6 +145,11 @@ module Agentilda
     def acted(note)
       yield
       UI.log(note)
+      # Under the dashboard, RatatuiRuby.run owns the alternate screen and
+      # repaints it continuously, so this raw `$stderr` write either never
+      # appears or is immediately overwritten — `UI.log` above is the only
+      # guaranteed record of w/n/q there. The line still matters without a
+      # screen (a dry run, a pipe), where this is all the feedback there is.
       UI.line(note)
     end
   end

data/lib/agentilda/launcher.rb

@@ -0,0 +1,69 @@
+module Agentilda
+  class Launcher
+    # The one flag every command takes, so no command declares it. Removed
+    # from the arguments before dry-cli sees them, which would otherwise
+    # reject it as an argument the command never asked for.
+    NO_COLOR_FLAGS = %w[--no-color -C].freeze
+
+    attr_accessor :argv,
+      :stdin,
+      :stdout,
+      :stderr,
+      :kernel
+
+    def initialize(argv,
+      stdin = $stdin,
+      stdout = $stdout,
+      stderr = $stderr,
+      kernel = Kernel)
+      self.argv   = argv
+      self.stdin  = stdin
+      self.stdout = stdout
+      self.stderr = stderr
+      self.kernel = kernel
+
+      # Bare `agentilda` prints its help. It used to print the plan table, which
+      # meant the one command that reads a tree was also the one you got by accident.
+      @argv = argv.empty? ? %w(-h) : argv
+
+      # `run --push-pr` takes an OPTIONAL part letter: bare means "continue this
+      # plan"s sequence", `--push-pr C` means "use C". dry-cli has no optional-value
+      # option, so the bare form is filled in here rather than made to look like a
+      # mistake.
+      #
+      # Scoped to `run`, and to the long spelling when it is not. This rewrote every
+      # `-p` in every command for a while, which quietly turned
+      # `linear import TAX -p "Some Project"` into `-p auto "Some Project"` — the
+      # option took "auto" and the project name became a stray argument. A global
+      # rewrite of a one-letter flag will collide with the next command that wants
+      # it; this one collided within the week.
+      return unless argv.first == "run"
+
+      @argv = argv.each_with_object([]) do |token, out|
+        out << token
+        next unless ["--push-pr", "-p"].include?(token)
+
+        following = argv[argv.index(token) + 1]
+        out << "auto" unless following&.match?(/\A[A-Z]\z/)
+      end
+    end
+
+    # `--no-color` becomes NO_COLOR rather than a setting of its own: the help
+    # screens, the runtime UI and every child process already honour it, so
+    # one variable switches all three off together.
+    #
+    # @return [void] never returns; exits with the command's status
+    def execute!
+      ENV["NO_COLOR"] = "1" if NO_COLOR_FLAGS.intersect?(argv)
+      code = 0
+      Dry::CLI.new(::Agentilda::CLI).call(arguments: argv - NO_COLOR_FLAGS)
+    rescue SystemExit => e
+      code = e.status
+    rescue StandardError => e
+      stderr.puts UI.paint("Error: #{e.message}", :red)
+      code = 1
+    ensure
+      kernel.exit(code)
+    end
+  end
+end