ace-herdr 0.1.0

data/lib/ace/herdr/molecules/herdr_executor.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "open3"
+require "json"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Executes herdr CLI commands via argv arrays (ADR-031) and classifies
+      # failures into typed executor errors from herdr's machine-readable
+      # JSON error codes. The single seam between ace-herdr and the herdr
+      # binary; tests substitute this class.
+      class HerdrExecutor
+        DEFAULT_BINARY = "herdr"
+
+        def initialize(binary: DEFAULT_BINARY)
+          @binary = binary
+        end
+
+        # Probe the agent living in a pane (raises AgentNotFoundError when none)
+        def agent_get(pane)
+          run!([@binary, "agent", "get", pane])
+        end
+
+        # Start an agent in a pane at an interactive shell prompt.
+        # Success means the agent was detected and is ready for input.
+        def agent_start(name:, kind:, pane:, timeout_ms:)
+          run!([@binary, "agent", "start", name, "--kind", kind,
+            "--pane", pane, "--timeout", timeout_ms.to_s])
+        end
+
+        # Submit a prompt to the agent in a pane (push delivery). herdr
+        # rejects blocked agents pre-send with agent_blocked.
+        def agent_prompt(pane:, text:)
+          run!([@binary, "agent", "prompt", pane, text])
+        end
+
+        # Wait until the agent reaches one of the requested states
+        def agent_wait(pane:, until_states:, timeout_ms:)
+          cmd = [@binary, "agent", "wait", pane]
+          until_states.each { |state| cmd += ["--until", state] }
+          cmd += ["--timeout", timeout_ms.to_s]
+          run!(cmd)
+        end
+
+        # Run a shell command line in a pane (text + Enter in one call)
+        def pane_run(pane, command)
+          run!([@binary, "pane", "run", pane, command])
+        end
+
+        def pane_rename(pane, label)
+          run!([@binary, "pane", "rename", pane, label])
+        end
+
+        def pane_close(pane)
+          run!([@binary, "pane", "close", pane])
+        end
+
+        def pane_current
+          run!([@binary, "pane", "current", "--current"])
+        end
+
+        # Inspect a pane's processes (positive proof of process exit for tidy)
+        def pane_process_info(pane)
+          run!([@binary, "pane", "process-info", "--pane", pane])
+        end
+
+        # Create a tab in a workspace with a label and optional cwd
+        def tab_create(workspace_id:, label:, cwd: nil, focus: nil)
+          cmd = [@binary, "tab", "create", "--workspace", workspace_id, "--label", label]
+          cmd += ["--cwd", cwd] if cwd
+          cmd += ["--focus"] if focus
+          run!(cmd)
+        end
+
+        # --- terminal-control surface (spec 8wq.t.k84) -----------------------
+
+        # List workspaces (tmux sessions analogue)
+        def workspace_list
+          run!([@binary, "workspace", "list"])
+        end
+
+        # List tabs, optionally scoped to a workspace (tmux windows analogue)
+        def tab_list(workspace_id: nil)
+          cmd = [@binary, "tab", "list"]
+          cmd += ["--workspace", workspace_id] if workspace_id
+          run!(cmd)
+        end
+
+        # List panes, optionally scoped to a workspace
+        def pane_list(workspace_id: nil)
+          cmd = [@binary, "pane", "list"]
+          cmd += ["--workspace", workspace_id] if workspace_id
+          run!(cmd)
+        end
+
+        # Send literal text to a pane without submitting
+        def pane_send_text(pane, text)
+          run!([@binary, "pane", "send-text", pane, text])
+        end
+
+        # Send named keys to a pane, in order
+        def pane_send_keys(pane, keys)
+          run!([@binary, "pane", "send-keys", pane, *keys])
+        end
+
+        # Send named keys to the agent in a pane, in order
+        def agent_send_keys(pane, keys)
+          run!([@binary, "agent", "send-keys", pane, *keys])
+        end
+
+        # Read pane terminal output as raw text (capture). The raw runner
+        # keeps stdout verbatim — no trimming of leading/trailing blank lines
+        def pane_read(pane, source: "recent", lines: nil)
+          cmd = [@binary, "pane", "read", pane, "--source", source]
+          cmd += ["--lines", lines.to_s] if lines
+          run_raw(cmd)
+        end
+
+        # Wait for pane output containing a literal pattern. herdr checks
+        # existing content immediately, then polls; timeout fails closed.
+        def pane_wait_output(pane, pattern:, source: "recent", lines: nil, timeout_ms: nil)
+          cmd = [@binary, "pane", "wait-output", pane, "--match", pattern, "--source", source]
+          cmd += ["--lines", lines.to_s] if lines
+          cmd += ["--timeout", timeout_ms.to_s] if timeout_ms
+          run!(cmd)
+        rescue AgentNotReadyError => e
+          raise WaitTimeoutError, e.message
+        end
+
+        # Create a workspace with a label and optional cwd/focus
+        def workspace_create(label:, cwd: nil, focus: nil)
+          cmd = [@binary, "workspace", "create", "--label", label]
+          cmd += ["--cwd", cwd] if cwd
+          cmd += ["--focus"] if focus
+          run!(cmd)
+        end
+
+        # Close a tab (used to drop the native initial tab of a created
+        # workspace once the preset's declared tabs exist)
+        def tab_close(tab_id)
+          run!([@binary, "tab", "close", tab_id])
+        end
+
+        # Split a pane (direction: right|down); herdr reports the new pane
+        def pane_split(pane:, direction:, cwd: nil, ratio: nil, focus: nil)
+          cmd = [@binary, "pane", "split", "--pane", pane, "--direction", direction]
+          cmd += ["--cwd", cwd] if cwd
+          cmd += ["--ratio", ratio.to_s] if ratio
+          cmd += ["--focus"] if focus
+          run!(cmd)
+        end
+
+        def available?
+          run([@binary, "--version"]).success?
+        rescue ExecutorUnavailableError
+          false
+        end
+
+        private
+
+        def run!(cmd)
+          result = run(cmd)
+          raise classify(result, cmd) unless result.success?
+
+          result
+        end
+
+        # Like run!, but stdout is preserved verbatim (no strip) — for
+        # commands whose output is content (pane read/capture)
+        def run_raw(cmd)
+          result = run_raw_stdout(cmd)
+          raise classify(result, cmd) unless result.success?
+
+          result
+        end
+
+        def run(cmd)
+          stdout, stderr, status = Open3.capture3(*cmd)
+          ExecutionResult.new(
+            stdout: stdout.strip, stderr: stderr.strip,
+            success: status.success?, exit_code: status.exitstatus || -1
+          )
+        rescue Errno::ENOENT
+          raise ExecutorUnavailableError, "herdr CLI not found on PATH: #{@binary}"
+        end
+
+        def run_raw_stdout(cmd)
+          stdout, stderr, status = Open3.capture3(*cmd)
+          ExecutionResult.new(
+            stdout: stdout, stderr: stderr.strip,
+            success: status.success?, exit_code: status.exitstatus || -1
+          )
+        rescue Errno::ENOENT
+          raise ExecutorUnavailableError, "herdr CLI not found on PATH: #{@binary}"
+        end
+
+        # Map a failed result to a typed error from herdr's error codes
+        # (JSON: {"error":{"code":...,"message":...}}). The native machine
+        # code is kept in the message so CLI failures carry it.
+        def classify(result, cmd)
+          code, message = error_code(result)
+          case code
+          when "agent_blocked" then AgentBlockedError.new(tag_code(code, message))
+          when "agent_prompt_stalled" then AgentNotReadyError.new(tag_code(code, message))
+          when "pane_not_found" then PaneNotFoundError.new(tag_code(code, message))
+          when "agent_not_found" then AgentNotFoundError.new(tag_code(code, message))
+          when "tab_not_found" then TabNotFoundError.new(tag_code(code, message))
+          when "workspace_not_found" then WorkspaceNotFoundError.new(tag_code(code, message))
+          when "timeout" then AgentNotReadyError.new(tag_code(code, message))
+          else
+            CommandError.new(
+              "herdr command failed (exit #{result.exit_code}): #{cmd.join(" ")} " \
+              "#{message || result.stderr}".strip
+            )
+          end
+        end
+
+        def tag_code(code, message)
+          "#{code}: #{message}"
+        end
+
+        def error_code(result)
+          [result.parsed_json, parse_json(result.stderr)].each do |json|
+            next unless json.is_a?(Hash)
+
+            error = json["error"]
+            return [error["code"], error["message"]] if error.is_a?(Hash) && error["code"]
+          end
+          [nil, nil]
+        end
+
+        def parse_json(text)
+          JSON.parse(text)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # Immutable result of a herdr command execution
+      class ExecutionResult
+        attr_reader :stdout, :stderr, :exit_code
+
+        def initialize(stdout:, stderr:, success:, exit_code:)
+          @stdout = stdout
+          @stderr = stderr
+          @success = success
+          @exit_code = exit_code
+        end
+
+        def success?
+          @success
+        end
+
+        # Parsed stdout JSON or nil
+        def parsed_json
+          JSON.parse(@stdout)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/molecules/pane_tidy_probe.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Ace
+  module Herdr
+    module Molecules
+      # Positive-evidence probe for tidy (spec 8wq.t.1w0): the only component
+      # that interprets native `agent get` and `pane process-info` responses.
+      # A pane qualifies for closing solely on explicit completion proof — an
+      # observed `done` agent state or a pane with no foreground process.
+      # Every unrecognized response, missing field, or probe failure is
+      # preserve-only (no proof != dead).
+      module PaneTidyProbe
+        module_function
+
+        # Probe the agent in a pane and, when no agent exists, the pane's
+        # processes. Returns:
+        #   :agent_done     - agent observed in state done (eligible)
+        #   :process_exited - pane alive, empty foreground process list (eligible)
+        #   :active         - live agent (idle/working/blocked) or live process
+        #   :unknown        - unreadable/absent evidence (preserve)
+        #   :unreadable     - probe failure (preserve)
+        #   :gone           - pane no longer exists (nothing to close)
+        def pane_evidence(executor, pane)
+          agent_evidence = agent_evidence(executor, pane)
+          return agent_evidence unless agent_evidence == :no_agent
+
+          process_evidence(executor, pane)
+        end
+
+        # Interpret `agent get`: result.agent.agent_status. A missing agent
+        # (:no_agent) defers to the process probe.
+        def agent_evidence(executor, pane)
+          status = dug_value(executor.agent_get(pane).parsed_json, "result", "agent", "agent_status")
+          case status
+          when "done" then :agent_done
+          when "idle", "working", "blocked" then :active
+          else :unknown
+          end
+        rescue AgentNotFoundError
+          :no_agent
+        rescue PaneNotFoundError
+          :gone
+        rescue ExecutorError
+          :unreadable
+        end
+
+        # Interpret `pane process-info`. herdr serializes
+        # `foreground_processes` with serde skip_serializing_if (v0.9.1
+        # schema/panes.rs), so within a well-formed process_info object an
+        # OMITTED key is the process-exit proof; an explicit null or any
+        # non-array value is malformed evidence and preserves. Anything
+        # alive appears as a non-empty array.
+        def process_evidence(executor, pane)
+          info = dug_value(executor.pane_process_info(pane).parsed_json, "result", "process_info")
+          return :unknown unless info.is_a?(Hash)
+
+          processes = info["foreground_processes"]
+          return :unknown if info.key?("foreground_processes") && !processes.is_a?(Array)
+
+          processes.to_a.empty? ? :process_exited : :active
+        rescue PaneNotFoundError
+          :gone
+        rescue ExecutorError
+          :unreadable
+        end
+
+        # Path walk that fails closed: nil unless every hop is a Hash
+        def dug_value(parsed, *path)
+          current = parsed
+          path.each do |key|
+            return nil unless current.is_a?(Hash)
+
+            current = current[key]
+          end
+          current
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/molecules/preset_loader.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/config"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Finds and loads herdr workspace/tab YAML presets across the ADR-022
+      # config cascade:
+      #   1. project .ace/herdr/ (highest priority)
+      #   2. user ~/.ace/herdr/
+      #   3. gem .ace-defaults/herdr/ (lowest priority)
+      class PresetLoader
+        PRESET_TYPES = %w[workspaces tabs].freeze
+
+        # @param gem_root [String] Gem root directory for defaults
+        # @param start_path [String, nil] Starting path for cascade traversal
+        def initialize(gem_root: Ace::Herdr.gem_root, start_path: nil)
+          @resolver = Ace::Support::Config.virtual_resolver(
+            config_dir: ".ace",
+            defaults_dir: ".ace-defaults",
+            start_path: start_path,
+            gem_path: gem_root
+          )
+        end
+
+        # Load a preset by type and name
+        #
+        # @param type [String] Preset type: "workspaces" or "tabs"
+        # @param name [String] Preset name (without .yml extension)
+        # @return [Hash, nil] Parsed YAML hash, or nil when unknown
+        def load(type, name)
+          absolute_path = @resolver.resolve_path("herdr/#{type}/#{name}.yml")
+          return nil unless absolute_path && File.exist?(absolute_path)
+
+          YAML.safe_load_file(absolute_path, permitted_classes: [Date], aliases: true) || {}
+        end
+
+        # List available preset names for a type, merged across the cascade
+        #
+        # @param type [String] Preset type: "workspaces" or "tabs"
+        # @return [Array<String>] Preset names (without .yml extension)
+        def list(type)
+          @resolver.glob("herdr/#{type}/*.yml").keys
+            .map { |relative_path| File.basename(relative_path, ".yml") }
+            .sort.uniq
+        end
+
+        # List all preset types and their presets
+        #
+        # @return [Hash<String, Array<String>>] Map of type => preset names
+        def list_all
+          PRESET_TYPES.each_with_object({}) do |type, result|
+            presets = list(type)
+            result[type] = presets unless presets.empty?
+          end
+        end
+
+        # Create a lookup proc for PresetResolver
+        #
+        # @param type [String] Preset type to look up
+        # @return [Proc] Proc that takes a name and returns a preset hash
+        def to_lookup(type)
+          ->(name) { load(type, name) }
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/molecules/preset_resolver.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "ace/support/config"
+
+module Ace
+  module Herdr
+    module Molecules
+      # Resolves `preset:` references in herdr workspace/tab presets
+      # (spec 8wq.t.k84): recursive lookup with deep merge (overlay wins),
+      # array concat so collections compose, cycle detection, and
+      # fail-closed missing references.
+      module PresetResolver
+        MAX_DEPTH = 10
+
+        # Raised when a preset references an unknown nested preset
+        class PresetNotFoundError < Ace::Herdr::Error; end
+
+        # Raised when preset references form a cycle
+        class CircularPresetError < Ace::Herdr::Error; end
+
+        module_function
+
+        # Resolve a workspace hash: the root may inherit another workspace
+        # preset; each tab entry may inherit a tab preset.
+        #
+        # @param hash [Hash] Workspace configuration hash
+        # @param workspace_lookup [Proc] name => workspace preset hash
+        # @param tab_lookup [Proc] name => tab preset hash
+        # @return [Hash] Fully resolved workspace hash
+        def resolve_workspace(hash, workspace_lookup:, tab_lookup:)
+          resolved = resolve_refs(hash, lookup: workspace_lookup)
+          tabs = resolved["tabs"]
+          if tabs.is_a?(Array)
+            resolved = resolved.merge(
+              "tabs" => tabs.map { |entry| resolve_tab(tab_entry(entry), tab_lookup: tab_lookup) }
+            )
+          end
+          resolved
+        end
+
+        # Resolve a tab hash: it may inherit another tab preset; pane string
+        # shorthand becomes a command entry.
+        #
+        # @param hash [Hash, String] Tab configuration hash (or label shorthand)
+        # @param tab_lookup [Proc] name => tab preset hash
+        # @return [Hash] Resolved tab hash
+        def resolve_tab(hash, tab_lookup:)
+          resolved = resolve_refs(tab_entry(hash), lookup: tab_lookup)
+          panes = resolved["panes"]
+          if panes.is_a?(Array)
+            resolved = resolved.merge("panes" => panes.map { |entry| pane_entry(entry) })
+          end
+          resolved
+        end
+
+        # Resolve one `preset:` reference chain onto `hash`
+        #
+        # @param hash [Hash] Hash that may contain a "preset" key
+        # @param lookup [Proc] name => preset hash (nil when unknown)
+        # @param depth [Integer] Recursion depth (cycle guard)
+        # @return [Hash] Resolved hash with the base deep-merged underneath
+        def resolve_refs(hash, lookup:, depth: 0)
+          raise CircularPresetError, "Preset resolution exceeded max depth (#{MAX_DEPTH})" if depth >= MAX_DEPTH
+          return hash unless hash.is_a?(Hash) && hash.key?("preset")
+
+          name = hash["preset"].to_s
+          base = lookup.call(name)
+          raise PresetNotFoundError, "Unknown preset '#{name}'" if base.nil?
+
+          base = resolve_refs(base, lookup: lookup, depth: depth + 1)
+          overlay = hash.reject { |key, _| key == "preset" }
+          Ace::Support::Config::Atoms::DeepMerger.merge(base, overlay, array_strategy: :concat)
+        end
+
+        # @api private
+        def tab_entry(entry)
+          entry.is_a?(Hash) ? entry : {"label" => entry.to_s}
+        end
+
+        # @api private
+        # Pane string shorthand declares a command to run in a new split
+        def pane_entry(entry)
+          entry.is_a?(Hash) ? entry : {"command" => entry.to_s}
+        end
+      end
+    end
+  end
+end