agentilda 2.0.1 → 2.0.4

data/lib/agentilda/unblocker.rb

@@ -1,221 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # Draining a plan's `blocked.md`, and saying what happened.
-  #
-  # `unblock` is the one command a human runs *because* they know something the
-  # tool cannot observe: an answer has arrived. So it owes them an account of
-  # what it did with it. Four things can happen to a plan named on the command
-  # line, and only one of them is the interesting one:
-  #
-  #   * the number names no folder,
-  #   * the folder is not blocked and there is nothing to drain,
-  #   * the folder is blocked, and some, none or all of its questions fold in,
-  #   * `blocked.md` is there but numbers nothing `## B<n>`, so no program can
-  #     read it at all.
-  #
-  # Each is reported differently, because each needs a different thing done
-  # next. This object works out which one happened; {CLI::Unblock} prints it.
-  class Unblocker
-    # One open question, as `blocked.md` writes it.
-    #
-    # @!attribute [r] number
-    #   @return [Integer] the `n` in `## B<n>`
-    # @!attribute [r] heading
-    #   @return [String] the heading text, hashes stripped
-    # @!attribute [r] answered
-    #   @return [Boolean] whether an `## A<n>` of the same number is waiting
-    Question = Data.define(:number, :heading, :answered) do
-      # @return [String]
-      def to_s = answered ? "#{heading}  ← answer waiting" : heading
-    end
-
-    # One token from the command line, once the tree has had a look at it.
-    #
-    # @!attribute [r] token
-    #   @return [String] what the user typed
-    # @!attribute [r] subject
-    #   @return [Agentilda::Subject, nil]
-    # @!attribute [r] problem
-    #   @return [Symbol, nil] :missing, :not_blocked, or nil when it is drainable
-    Target = Data.define(:token, :subject, :problem) do
-      # @return [Boolean]
-      def drainable? = problem.nil?
-    end
-
-    # What became of one plan.
-    #
-    # @!attribute [r] subject
-    #   @return [Agentilda::Subject] as the folder stands *now*
-    # @!attribute [r] ok
-    #   @return [Boolean] whether the agent ran without failing
-    # @!attribute [r] note
-    #   @return [String] one line about how it went
-    # @!attribute [r] before
-    #   @return [Array<Question>] open before the agent ran
-    # @!attribute [r] after
-    #   @return [Array<Question>] open now
-    Outcome = Data.define(:subject, :ok, :note, :before, :after) do
-      # @return [Agentilda::Ordinal]
-      def ordinal = subject.feature.ordinal
-
-      # @return [Array<Integer>] the questions this run actually disposed of
-      def folded = before.map(&:number) - after.map(&:number)
-
-      # @return [Boolean] `blocked.md` is gone, so the plan is out of the block
-      def cleared? = !subject.file?("blocked.md")
-
-      # @return [Boolean] a `blocked.md` no program can read
-      def unreadable? = subject.unreadable_block?
-
-      # @return [Array<Question>] still open, with an answer sitting unfolded
-      def waiting = after.select(&:answered)
-    end
-
-    # The questions a folder still names, in the order the file names them.
-    #
-    # @param subject [Agentilda::Subject]
-    # @return [Array<Question>]
-    def self.questions(subject)
-      answered = subject.block_answers
-
-      subject.read("blocked.md").to_s.lines.grep(OPEN_BLOCK).map do |line|
-        number = line[OPEN_BLOCK, 1].to_i
-        Question.new(number:, heading: line.strip.sub(/\A\#+[ \t]*/, ""), answered: answered.include?(number))
-      end
-    end
-
-    # @param tree [Agentilda::Tree]
-    # @param agent [Agentilda::Agent]
-    # @param executor [#call] receives (agent, subject, root:) and yields each
-    #   phrase describing what the agent is doing
-    # @param root [String] the repository the agent works in
-    # @param commit [Boolean] false plans the invocation and changes nothing
-    def initialize(tree:, agent:, executor:, root: nil, commit: false)
-      @tree = tree
-      @agent = agent
-      @executor = executor
-      @root = root || File.dirname(tree.dir)
-      @commit = commit
-    end
-
-    # @return [Agentilda::Tree]
-    attr_reader :tree
-
-    # @return [Agentilda::Agent]
-    attr_reader :agent
-
-    # @return [String]
-    attr_reader :root
-
-    # @return [Boolean]
-    def commit? = @commit
-
-    # Work out what each number on the command line refers to.
-    #
-    # Nothing is rejected here and nothing exits: a token that names no folder
-    # is as much a thing the user needs told about as a folder that drained, and
-    # stopping at the first bad one hides the rest of the report.
-    #
-    # The gate is `blocked.md` itself, not the folder's emoji. ⭕️ is *derived*
-    # from the file, so gating on the emoji made the tool circular: a
-    # `blocked.md` whose questions are not numbered `## B<n>` never earns the
-    # emoji, so `unblock` refused it, so the file could never drain and the
-    # folder could never leave 🟡.
-    #
-    # @param tokens [Array<String>] `NNN`, `NNN.MM`, or several comma separated
-    # @return [Array<Target>]
-    def resolve(tokens)
-      tokens.flat_map { |token| token.to_s.split(",") }.map(&:strip).reject(&:empty?).map do |token|
-        subject = tree.find(token)
-        next Target.new(token:, subject: nil, problem: :missing) if subject.nil?
-        next Target.new(token:, subject:, problem: :not_blocked) unless subject.file?("blocked.md")
-
-        Target.new(token:, subject:, problem: nil)
-      end
-    end
-
-    # Hand each folder to the agent, one at a time, and read the file back.
-    #
-    # What the agent claims it did is not evidence. The questions are counted
-    # off disk before and after, so "folded B3" means the heading is gone from
-    # `blocked.md`, not that an agent said so.
-    #
-    # @param subjects [Array<Agentilda::Subject>]
-    # @return [Array<Outcome>]
-    def call(subjects)
-      return [] if subjects.empty?
-
-      before = subjects.map { |subject| [subject.feature.ordinal.to_s, self.class.questions(subject)] }.to_h
-      results = UI.concurrently(subjects,
-        headline(subjects),
-        jobs:   1,
-        label:  method(:label),
-        fields: method(:log_fields),
-        file:   ->(_) { "blocked.md" },
-        root:) do |subject, progress|
-        # After ctrl-c the plans not yet started stay as they are, blocked.md
-        # untouched, so the next run picks them up from the beginning.
-        next [false, "not started: interrupted by ctrl-c"] if Control.interrupted?
-
-        invoke(subject, progress)
-      end
-
-      settle
-      subjects.zip(results).map { |subject, result| outcome(subject, result, before) }
-    end
-
-    private
-
-    # @param subject [Agentilda::Subject]
-    # @param progress [Agentilda::UI::Line] a dashboard row carries the
-    #   executor handle its kill and extend keys act on; a plain line does not
-    # @return [Array(Boolean, String)]
-    def invoke(subject, progress)
-      handle = progress.handle if progress.is_a?(Dashboard::Tracker)
-      @executor.call(agent, subject, root:, handle:, &progress)
-    rescue StandardError => e
-      [false, "#{e.class}: #{e.message.lines.first.to_s.strip}"]
-    end
-
-    # The same pass the run loop makes after every round, for the same reason:
-    # a drained folder is only *named* differently once something reads the
-    # file the agent just deleted.
-    #
-    # @return [void]
-    def settle
-      Resync::Dirs.new(tree:).call(commit: true) if commit?
-      tree.reload
-    end
-
-    # @param subject [Agentilda::Subject] as it was before the run
-    # @param result [Array, Exception]
-    # @param before [Hash{String => Array<Question>}]
-    # @return [Outcome]
-    def outcome(subject, result, before)
-      ok, note = result.is_a?(Exception) ? [false, result.message.lines.first.to_s.strip] : result
-      current = tree.find(subject.feature.ordinal) || subject
-
-      Outcome.new(subject: current,
-        ok: !!ok,
-        note: note.to_s,
-        before: before.fetch(subject.feature.ordinal.to_s, []),
-        after: self.class.questions(current))
-    end
-
-    # @param subjects [Array<Agentilda::Subject>]
-    # @return [String]
-    def headline(subjects)
-      "#{commit? ? "handing" : "would hand"} #{subjects.size} plan#{"s" unless subjects.size == 1} " \
-        "to #{agent.name} in #{root}"
-    end
-
-    # @param subject [Agentilda::Subject]
-    # @return [String]
-    def label(subject) = "#{subject.feature.ordinal} → #{agent.name}"
-
-    # @param subject [Agentilda::Subject]
-    # @return [Hash] the columns this plan's log lines carry
-    def log_fields(subject) = { plan: subject.feature.ordinal.to_s, status: subject.status.to_s, agent: agent.name }
-  end
-end

data/lib/agentilda/viewer.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # Hands Markdown files to a renderer outside this process: the system
-  # viewer via `open`, or mdfried in the terminal.
-  #
-  # Both paths shell out, so the class takes its two effects as lambdas and
-  # the specs assert on the commands instead of launching viewers on the box
-  # running the suite.
-  class Viewer
-    # What to run when mdfried is asked for but not installed. Homebrew is the
-    # one package manager the toolchain already assumes (see the Brewfile
-    # convention), so there is no fallback chain to get wrong.
-    INSTALL = "brew install mdfried >/dev/null"
-
-    # How to notice mdfried is missing without depending on `which`, which
-    # differs across shells; `command -v` is POSIX.
-    DETECT = "command -v mdfried >/dev/null"
-
-    # @param launch [#call] runs a command, returns truthy on success
-    # @param pipe [#call] runs a command, yielding its stdin as an IO
-    def initialize(launch: ->(*cmd) { system(*cmd) },
-      pipe: ->(cmd, &block) { IO.popen(cmd, "w", &block) })
-      @launch = launch
-      @pipe = pipe
-    end
-
-    # Opens each file in whatever the system has configured for Markdown.
-    #
-    # @param paths [Array<String>]
-    # @return [void]
-    def open(paths)
-      Array(paths).each { |path| @launch.call("open", path) }
-    end
-
-    # Streams each file's content into mdfried, installing it first when it
-    # is missing.
-    #
-    # @param paths [Array<String>]
-    # @return [void]
-    # @raise [Agentilda::Error] when mdfried is absent and brew cannot fix that
-    def mdfried(paths)
-      ensure_mdfried!
-      Array(paths).each do |path|
-        @pipe.call("mdfried") { |io| io.write(File.read(path)) }
-      end
-    end
-
-    private
-
-    # @return [void]
-    # @raise [Agentilda::Error]
-    def ensure_mdfried!
-      return if @launch.call(DETECT)
-
-      @launch.call(INSTALL) or
-        raise Error, "mdfried is not installed, and `brew install mdfried` failed"
-    end
-  end
-end

data/lib/agentilda/worktree.rb

@@ -1,207 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "shellwords"
-
-module Agentilda
-  # A git worktree per plan, so agents working on different plans cannot
-  # collide at all.
-  #
-  # A lock coordinates a shared tree; a worktree removes the sharing. That
-  # matters more than it sounds for an agent loop: two agents editing one
-  # checkout produce no git conflict — same branch, same files — so the last
-  # writer simply wins and the loser's work vanishes with nothing anywhere to
-  # say it happened.
-  #
-  # The branch carries the plan number (`<user>/NNN.MM-slug`), which is not
-  # decoration: it is the first thing `resync prs` reads when deciding which
-  # plan a pull request implements. Naming branches this way means the number
-  # carries itself from worktree creation through to a merged pull request with
-  # nobody having to remember it.
-  class Worktree
-    # `bin/setup-worktree`, which copies in the ignored-but-required files a new
-    # checkout does not get. Shelling out rather than reimplementing the rules
-    # here keeps one answer to "what does a worktree need", and keeps that answer
-    # usable from a shell on a machine that has never run `bundle install`.
-    SEEDER = File.expand_path("../../bin/setup-worktree", __dir__)
-
-    # One plan's isolated checkout.
-    #
-    # @!attribute [r] ordinal
-    #   @return [Agentilda::Ordinal]
-    # @!attribute [r] branch
-    #   @return [String]
-    # @!attribute [r] path
-    #   @return [String] absolute
-    # @!attribute [r] created
-    #   @return [Boolean] false when an existing worktree was reused
-    Checkout = Data.define(:ordinal, :branch, :path, :created) do
-      # @return [Boolean] whether the agent left anything behind
-      def dirty? = !`git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
-
-      # @return [String] the plans directory inside this checkout
-      def plans_dir = File.join(path, Agentilda::PLANS_DIR)
-
-      # @return [Boolean] whether this round made it, rather than reusing one
-      def created? = created
-    end
-
-    # @param root [String] the main repository
-    # @param dir [String, nil] where worktrees go; defaults to a sibling
-    # @param user [String] branch namespace
-    def initialize(root:, dir: nil, user: ENV["USER"] || "agent")
-      @root = File.expand_path(root)
-      @user = user
-      @dir = File.expand_path(dir || default_dir)
-    end
-
-    # @return [String] the main repository
-    attr_reader :root
-
-    # @return [String] where worktrees are kept
-    attr_reader :dir
-
-    # @return [Boolean] whether root is a git repository at all
-    def repository? = system("git", "-C", root, "rev-parse", "--git-dir", out: File::NULL, err: File::NULL)
-
-    # Get, or create, the isolated checkout for one plan.
-    #
-    # The checkout is seeded before it is handed back, on both paths. `git
-    # worktree add` brings every TRACKED file and nothing else, so an agent
-    # given a bare one cannot run the suite it was told to keep green: a Rails
-    # project dies on `MissingKeyError` because `config/credentials/*.key` is
-    # gitignored. The agent then reports a broken checkout as a broken plan,
-    # which is the worst failure this loop has, because the diagnosis points
-    # at the code rather than at the tree.
-    #
-    # A reused worktree is seeded too. {#seed} only ever adds a missing file,
-    # so running it again costs one fast subprocess and repairs the worktrees
-    # that were created before any of this existed.
-    #
-    # @param feature [Agentilda::Feature]
-    # @return [Agentilda::Worktree::Checkout]
-    # @raise [Agentilda::Error] when git refuses
-    def checkout_for(feature)
-      branch = branch_for(feature)
-      path = File.join(dir, "#{feature.ordinal}-#{feature.slug}")
-
-      if File.directory?(path)
-        seed(path)
-        return Checkout.new(ordinal: feature.ordinal, branch:, path:, created: false)
-      end
-
-      # git keeps a registration for a worktree whose directory was deleted by
-      # hand, marks it `prunable`, and then refuses to create a new one at that
-      # path. Anybody who has ever `rm -rf`d a worktree meets this, and the
-      # error says only "already exists" about a directory that does not.
-      forget_stale
-
-      FileUtils.mkdir_p(dir)
-      add(branch, path)
-      seed(path)
-      Checkout.new(ordinal: feature.ordinal, branch:, path:, created: true)
-    end
-
-    # Copy in the files git ignores and a new checkout therefore lacks: `.env`
-    # and friends, and credential keys.
-    #
-    # Never fatal. A repository with no ignored files is perfectly normal, and
-    # a plan is not worth abandoning over a seeding step, so this notes it and
-    # carries on.
-    #
-    # The note goes to the progress log, never the terminal: this runs while
-    # the ratatui dashboard owns the screen, and a line written to STDERR
-    # lands on top of an agent's row. The seeder's own output is silenced for
-    # the same reason. A suite that later dies on a missing key is explained
-    # by the log line.
-    #
-    # @param path [String] the worktree to seed
-    # @return [Boolean] whether the seeder ran and succeeded
-    def seed(path)
-      unless File.executable?(SEEDER)
-        UI.log("worktree: #{SEEDER} is missing, so #{path} has no .env or credential keys")
-        return false
-      end
-
-      return true if system(SEEDER, "--quiet", path, out: File::NULL, err: File::NULL)
-
-      UI.log("worktree: could not seed #{path}; its suite may fail on a missing key")
-      false
-    end
-
-    # @param feature [Agentilda::Feature]
-    # @return [String] e.g. "kig/002.00-tenancy-households"
-    def branch_for(feature) = "#{@user}/#{feature.ordinal}-#{feature.slug}"
-
-    # Every worktree this class manages, as git sees them.
-    #
-    # @return [Array<String>] absolute paths
-    def list
-      # Compare canonical paths. git reports resolved ones, and on macOS the
-      # temp and home trees run through symlinks (/var -> /private/var), so a
-      # raw string compare matches nothing and prune silently does nothing.
-      mine = canonical(dir)
-
-      `git -C #{root.shellescape} worktree list --porcelain 2>/dev/null`
-        .lines(chomp: true)
-        .filter_map { |l| l.delete_prefix("worktree ") if l.start_with?("worktree ") }
-        .select { |p| canonical(p).start_with?(mine) }
-    end
-
-    # @param path [String]
-    # @return [String] the symlink-resolved path, or the input when it is gone
-    def canonical(path)
-      File.realpath(path)
-    rescue Errno::ENOENT
-      path
-    end
-
-    # Remove worktrees the agents left untouched.
-    #
-    # An agent that ran and changed nothing has produced a checkout that is
-    # pure cost: it looks like work in progress and is not. Dirty ones are
-    # always kept — that is the output.
-    #
-    # @return [Array<String>] paths removed
-    def prune
-      list.select { |path| clean?(path) }.each { |path| remove(path) }
-    end
-
-    # @param path [String]
-    # @return [void]
-    def remove(path)
-      system("git", "-C", root, "worktree", "remove", "--force", path, out: File::NULL, err: File::NULL)
-    end
-
-    private
-
-    # Sibling of the repository, not inside it: a worktree under the repo shows
-    # up in its own `git status` and in every glob anybody writes.
-    #
-    # @return [String]
-    def default_dir = "#{@root}.worktrees"
-
-    # Drop registrations whose directory is gone.
-    #
-    # @return [void]
-    def forget_stale
-      system("git", "-C", root, "worktree", "prune", out: File::NULL, err: File::NULL)
-    end
-
-    # @param path [String]
-    # @return [Boolean]
-    def clean?(path) = `git -C #{path.shellescape} status --porcelain 2>/dev/null`.strip.empty?
-
-    # @param branch [String]
-    # @param path [String]
-    # @return [void]
-    def add(branch, path)
-      exists = system("git", "-C", root, "show-ref", "--verify", "--quiet", "refs/heads/#{branch}")
-      args = exists ? ["worktree", "add", path, branch] : ["worktree", "add", "-b", branch, path]
-
-      return if system("git", "-C", root, *args, out: File::NULL, err: File::NULL)
-
-      raise Error, "could not create a worktree for #{branch} at #{path}"
-    end
-  end
-end