harnex 0.2.0

data/lib/harnex/adapters/base.rb

@@ -0,0 +1,134 @@
+module Harnex
+  module Adapters
+    class Base
+      PROMPT_PREFIXES = [">", "\u203A", "\u276F"].freeze
+
+      # Adapter contract — subclasses MUST implement:
+      #   base_command          -> Array[String]  CLI args to spawn
+      #
+      # Subclasses MAY override:
+      #   input_state(text)     -> Hash           Parse screen for state
+      #   build_send_payload    -> Hash           Build injection payload
+      #   inject_exit(writer)   -> void           Send a stop/exit sequence
+      #   infer_repo_path(argv) -> String         Extract repo path from CLI args
+      #   wait_for_sendable     -> String         Wait for a send-ready snapshot
+
+      attr_reader :key
+
+      def initialize(key, extra_args = [])
+        @key = key
+        @extra_args = extra_args.dup
+      end
+
+      def build_command
+        base_command + @extra_args
+      end
+
+      def base_command
+        raise NotImplementedError, "#{self.class} must define #base_command"
+      end
+
+      def infer_repo_path(_argv)
+        Dir.pwd
+      end
+
+      def input_state(screen_text)
+        {
+          state: "unknown",
+          input_ready: nil
+        }
+      end
+
+      def send_wait_seconds(submit:, enter_only:)
+        0.0
+      end
+
+      def wait_for_sendable_state?(_state, submit:, enter_only:)
+        false
+      end
+
+      def wait_for_sendable(screen_snapshot_fn, submit:, enter_only:, force:)
+        snapshot = screen_snapshot_fn.call
+        return snapshot if force
+
+        wait_secs = send_wait_seconds(submit: submit, enter_only: enter_only).to_f
+        return snapshot unless wait_secs.positive?
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + wait_secs
+        state = input_state(snapshot)
+
+        while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline &&
+              wait_for_sendable_state?(state, submit: submit, enter_only: enter_only)
+          sleep 0.05
+          snapshot = screen_snapshot_fn.call
+          state = input_state(snapshot)
+        end
+
+        snapshot
+      end
+
+      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
+        state = input_state(screen_text)
+        if !force && blocked_state?(state, enter_only: enter_only)
+          raise ArgumentError, blocked_message(state, enter_only: enter_only)
+        end
+
+        payload = enter_only ? "" : text.to_s
+        payload << submit_bytes if submit || enter_only
+
+        {
+          text: payload,
+          newline: false,
+          input_state: state,
+          force: force
+        }
+      end
+
+      def inject_exit(writer, delay_ms: 0)
+        writer.write("/exit")
+        writer.flush
+        sleep(delay_ms / 1000.0) if delay_ms.positive?
+        writer.write(submit_bytes)
+        writer.flush
+      end
+
+      protected
+
+      def submit_bytes
+        "\r"
+      end
+
+      def blocked_state?(state, enter_only:)
+        state[:input_ready] == false && !allow_control_action?(state, enter_only: enter_only)
+      end
+
+      def allow_control_action?(_state, enter_only:)
+        enter_only ? false : false
+      end
+
+      def blocked_message(state, enter_only:)
+        suffix = enter_only ? " for Enter-only input" : ""
+        "session is not ready for #{key} prompt input#{suffix} (state: #{state[:state]})"
+      end
+
+      def prompt_line?(line)
+        stripped = line.to_s.strip
+        return false if stripped.empty?
+        return false if stripped.match?(/\A(?:[>\u203A\u276F]\s*)?\d+\./)
+
+        PROMPT_PREFIXES.any? { |prefix| stripped.start_with?(prefix) }
+      end
+
+      def recent_lines(screen_text, limit: 40)
+        normalized_screen_text(screen_text).lines.last(limit)
+      end
+
+      def normalized_screen_text(screen_text)
+        text = screen_text.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "")
+        text = text.gsub(/\e\][^\a]*?(?:\a|\e\\)/, "")
+        text = text.gsub(/\e(?:[@-Z\\-_]|\[[0-?]*[ -\/]*[@-~])/, "")
+        text.gsub(/\r\n?/, "\n")
+      end
+    end
+  end
+end

data/lib/harnex/adapters/claude.rb

@@ -0,0 +1,105 @@
+module Harnex
+  module Adapters
+    class Claude < Base
+      SUBMIT_DELAY_MS = 75
+      SUBMIT_DELAY_PER_KB_MS = 50
+
+      def initialize(extra_args = [])
+        super("claude", extra_args)
+      end
+
+      def base_command
+        [
+          "claude",
+          "--dangerously-skip-permissions"
+        ]
+      end
+
+      def input_state(screen_text)
+        lines = recent_lines(screen_text, limit: 20)
+        text = lines.join
+        compact = text.gsub(/\s+/, "")
+
+        if compact.include?("Quicksafetycheck:") && compact.include?("Yes,Itrustthisfolder")
+          {
+            state: "workspace-trust-prompt",
+            input_ready: false,
+            action: "press-enter-to-confirm"
+          }
+        elsif compact.include?("Entertoconfirm") && compact.include?("Esctocancel")
+          {
+            state: "confirmation",
+            input_ready: false
+          }
+        elsif compact.include?("--INSERT--") || compact.include?("bypasspermissionson")
+          {
+            state: "prompt",
+            input_ready: true
+          }
+        elsif compact.include?("NORMAL") || compact.include?("--NORMAL--")
+          {
+            state: "vim-normal",
+            input_ready: true
+          }
+        elsif lines.any? { |line| prompt_line?(line) }
+          {
+            state: "prompt",
+            input_ready: true
+          }
+        else
+          super
+        end
+      end
+
+      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
+        state = input_state(screen_text)
+        if !force && blocked_state?(state, enter_only: enter_only)
+          raise ArgumentError, blocked_message(state, enter_only: enter_only)
+        end
+
+        steps = []
+        unless enter_only
+          body = text.to_s
+          steps << { text: body, newline: false } unless body.empty?
+        end
+
+        if submit || enter_only
+          step = { text: submit_bytes, newline: false }
+          step[:delay_ms] = submit_delay_ms(text) if steps.any?
+          steps << step
+        end
+
+        {
+          steps: steps,
+          input_state: state,
+          force: force
+        }
+      end
+
+      def inject_exit(writer)
+        super(writer, delay_ms: SUBMIT_DELAY_MS)
+      end
+
+      protected
+
+      def submit_delay_ms(text)
+        extra = (text.to_s.bytesize / 1024.0 * SUBMIT_DELAY_PER_KB_MS).ceil
+        SUBMIT_DELAY_MS + extra
+      end
+
+      def allow_control_action?(state, enter_only:)
+        enter_only && state[:state] == "workspace-trust-prompt"
+      end
+
+      def blocked_message(state, enter_only:)
+        return super unless state[:state] == "workspace-trust-prompt"
+
+        if enter_only
+          "Claude is waiting on the workspace trust prompt"
+        else
+          "Claude is waiting on the workspace trust prompt; use `harnex send --submit-only` first or `--force` to bypass"
+        end
+      end
+    end
+  end
+end

data/lib/harnex/adapters/codex.rb

@@ -0,0 +1,112 @@
+module Harnex
+  module Adapters
+    class Codex < Base
+      SUBMIT_DELAY_MS = 75
+      SUBMIT_DELAY_PER_KB_MS = 50
+      SEND_WAIT_SECONDS = 2.0
+
+      def initialize(extra_args = [])
+        super("codex", extra_args)
+      end
+
+      def base_command
+        [
+          "codex",
+          "--dangerously-bypass-approvals-and-sandbox",
+          "--no-alt-screen"
+        ]
+      end
+
+      def infer_repo_path(argv)
+        index = 0
+        while index < argv.length
+          arg = argv[index]
+          case arg
+          when "-C", "--cd"
+            next_value = argv[index + 1]
+            return next_value if next_value
+            break
+          when /\A-C(.+)\z/
+            return Regexp.last_match(1)
+          end
+          index += 1
+        end
+
+        Dir.pwd
+      end
+
+      def input_state(screen_text)
+        lines = recent_lines(screen_text)
+        return super unless lines.any? { |line| line.include?("OpenAI Codex") || line.include?("gpt-") }
+
+        if lines.any? { |line| prompt_line?(line) }
+          {
+            state: "prompt",
+            input_ready: true
+          }
+        else
+          {
+            state: "session",
+            input_ready: nil
+          }
+        end
+      end
+
+      def send_wait_seconds(submit:, enter_only:)
+        return 0.0 unless submit
+        return 0.0 if enter_only
+
+        SEND_WAIT_SECONDS
+      end
+
+      def wait_for_sendable_state?(state, submit:, enter_only:)
+        return false unless submit
+        return false if enter_only
+
+        state[:input_ready] != true
+      end
+
+      def build_send_payload(text:, submit:, enter_only:, screen_text:, force: false)
+        state = input_state(screen_text)
+        if !force && submit && !enter_only && state[:input_ready] != true
+          raise ArgumentError, blocked_message(state, enter_only: enter_only)
+        end
+
+        steps = []
+        unless enter_only
+          body = text.to_s
+          steps << { text: body, newline: false } unless body.empty?
+        end
+
+        if submit || enter_only
+          step = { text: submit_bytes, newline: false }
+          step[:delay_ms] = submit_delay_ms(text) if steps.any?
+          steps << step
+        end
+
+        {
+          steps: steps,
+          input_state: state,
+          force: force
+        }
+      end
+
+      def inject_exit(writer)
+        super(writer, delay_ms: SUBMIT_DELAY_MS)
+      end
+
+      protected
+
+      def submit_delay_ms(text)
+        extra = (text.to_s.bytesize / 1024.0 * SUBMIT_DELAY_PER_KB_MS).ceil
+        SUBMIT_DELAY_MS + extra
+      end
+
+      def blocked_message(state, enter_only:)
+        return super if enter_only
+
+        "Codex is not at a prompt; wait and retry or use `harnex send --force` (state: #{state[:state]})"
+      end
+    end
+  end
+end

data/lib/harnex/adapters/generic.rb

@@ -0,0 +1,14 @@
+module Harnex
+  module Adapters
+    class Generic < Base
+      def initialize(cli_name, extra_args = [])
+        @cli_name = cli_name
+        super(cli_name, extra_args)
+      end
+
+      def base_command
+        [@cli_name]
+      end
+    end
+  end
+end

data/lib/harnex/adapters.rb

@@ -0,0 +1,32 @@
+require_relative "adapters/base"
+require_relative "adapters/generic"
+require_relative "adapters/codex"
+require_relative "adapters/claude"
+
+module Harnex
+  module Adapters
+    module_function
+
+    def known
+      registry.keys.sort
+    end
+
+    def supported?(key)
+      !key.to_s.strip.empty?
+    end
+
+    def build(key, extra_args = [])
+      adapter_class = registry[key.to_s]
+      return adapter_class.new(extra_args) if adapter_class
+
+      Generic.new(key.to_s, extra_args)
+    end
+
+    def registry
+      @registry ||= {
+        "claude" => Claude,
+        "codex" => Codex
+      }
+    end
+  end
+end

data/lib/harnex/cli.rb

@@ -0,0 +1,115 @@
+module Harnex
+  class CLI
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      case @argv.first
+      when nil
+        puts usage
+        0
+      when "run"
+        Runner.new(@argv.drop(1)).run
+      when "send"
+        Sender.new(@argv.drop(1)).run
+      when "wait"
+        Waiter.new(@argv.drop(1)).run
+      when "stop"
+        Stopper.new(@argv.drop(1)).run
+      when "status"
+        Status.new(@argv.drop(1)).run
+      when "logs"
+        Logs.new(@argv.drop(1)).run
+      when "pane"
+        Pane.new(@argv.drop(1)).run
+      when "recipes"
+        Recipes.new(@argv.drop(1)).run
+      when "guide"
+        Guide.new.run
+      when "skills"
+        Skills.new(@argv.drop(1)).run
+      when "help"
+        puts help(@argv[1])
+        0
+      when "-h", "--help"
+        puts usage
+        0
+      else
+        raise OptionParser::ParseError, "unknown command #{@argv.first.inspect}"
+      end
+    end
+
+    private
+
+    def help(topic)
+      case topic
+      when "run"
+        Runner.usage
+      when "send"
+        Sender.usage
+      when "wait"
+        Waiter.usage
+      when "stop"
+        Stopper.usage
+      when "status"
+        Status.usage
+      when "logs"
+        Logs.usage
+      when "pane"
+        Pane.usage
+      when "recipes"
+        Recipes.usage
+      when "guide"
+        Guide.usage
+      when "skills"
+        Skills.usage
+      else
+        usage
+      end
+    end
+
+    def usage
+      <<~TEXT
+        Usage:
+          harnex run <cli> [options] [--] [cli-args...]
+          harnex send --id ID [options] [text...]
+          harnex wait --id ID [options]
+          harnex stop --id ID [options]
+          harnex status [options]
+          harnex logs --id ID [options]
+          harnex pane --id ID [options]
+          harnex help [command]
+
+        Commands:
+          run     Start a wrapped interactive session and local API
+          send    Send text to an active session
+          wait    Block until a session exits or reaches a state
+          stop    Send the adapter stop sequence to a session
+          status  List live sessions
+          logs    Read session output transcripts
+          pane    Capture the current tmux pane for a live session
+          recipes List and read workflow recipes
+          guide   Show the getting started guide
+          skills  Install bundled skills into a repo or globally
+          help    Show command help
+
+        New to harnex? Start with: harnex guide
+
+        Notes:
+          CLIs with smart prompt detection: #{Adapters.known.join(', ')}
+          Any other CLI name is launched with generic wrapping.
+
+        Examples:
+          harnex run codex
+          harnex run aider --id blue-cat
+          harnex run codex -- --cd /path/to/repo
+          harnex status
+          harnex logs --id main --follow
+          harnex pane --id main --lines 40
+          harnex send --id main --message "Summarize current progress."
+          harnex skills install close
+      TEXT
+    end
+  end
+end

data/lib/harnex/commands/guide.rb

@@ -0,0 +1,23 @@
+module Harnex
+  class Guide
+    GUIDE_PATH = File.expand_path("../../../../GUIDE.md", __FILE__)
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex guide
+
+        Print the getting started guide.
+      TEXT
+    end
+
+    def run
+      unless File.exist?(GUIDE_PATH)
+        warn("harnex guide: GUIDE.md not found at #{GUIDE_PATH}")
+        return 1
+      end
+
+      puts File.read(GUIDE_PATH)
+      0
+    end
+  end
+end