ace-hitl 0.8.0

data/lib/ace/hitl/cli/commands/list.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../../molecules/hitl_display_formatter"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class List < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "List HITL events"
+
+          option :status, type: :string, aliases: %w[-s], desc: "Filter by status"
+          option :kind, type: :string, aliases: %w[-k], desc: "Filter by kind"
+          option :tags, type: :string, aliases: %w[-T], desc: "Filter by tags (comma-separated)"
+          option :in, type: :string, aliases: %w[-i], desc: "Folder filter (next, all, archive)"
+          option :scope, type: :string, desc: "Scope (current, all)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(**options)
+            scope = validate_scope(options[:scope])
+            status = options[:status]
+            kind = options[:kind]
+            tags = parse_tags(options[:tags])
+            in_folder = options[:in] || "next"
+
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            events = manager.list(status: status, kind: kind, tags: tags, in_folder: in_folder, scope: scope)
+
+            puts Ace::Hitl::Molecules::HitlDisplayFormatter.format_list(
+              events,
+              total_count: manager.last_list_total,
+              global_folder_stats: manager.last_folder_counts
+            )
+          end
+
+          private
+
+          def parse_tags(raw)
+            return [] unless raw
+
+            raw.split(",").map(&:strip).reject(&:empty?)
+          end
+
+          def validate_scope(raw_scope)
+            return nil if raw_scope.nil?
+
+            scope = raw_scope.to_s.strip
+            allowed = Ace::Hitl::Molecules::WorktreeScopeResolver::VALID_SCOPES
+            return scope if allowed.include?(scope)
+
+            raise Ace::Support::Cli::Error.new("Invalid scope '#{raw_scope}'. Allowed: #{allowed.join(", ")}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/show.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Show < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Show HITL event details"
+
+          argument :ref, required: true, desc: "HITL reference (full ID or shortcut)"
+
+          option :path, type: :boolean, desc: "Print file path only"
+          option :content, type: :boolean, desc: "Print raw markdown content"
+          option :scope, type: :string, desc: "Scope (current, all)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            scope = validate_scope(options[:scope])
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            begin
+              resolved = manager.show(ref, scope: scope)
+            rescue Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError => e
+              candidates = e.matches.map(&:file_path).join(", ")
+              raise Ace::Support::Cli::Error.new(
+                "HITL event '#{ref}' is ambiguous across scope '#{scope || "all"}'. Candidates: #{candidates}"
+              )
+            end
+            raise Ace::Support::Cli::Error.new("HITL event '#{ref}' not found") unless resolved
+            event = resolved[:event]
+            resolved_location = format_resolved_location(resolved)
+
+            if options[:path]
+              puts event.file_path
+            elsif options[:content]
+              puts resolved_location if resolved_location
+              puts File.read(event.file_path)
+            else
+              puts "ID: #{event.id}"
+              puts "Title: #{event.title}"
+              puts "Status: #{event.status}"
+              puts "Kind: #{event.kind}"
+              puts "Tags: #{event.tags.join(", ")}"
+              puts "Questions: #{event.questions.join(" | ")}"
+              puts "Answer: #{event.answer || "(none)"}"
+              puts resolved_location if resolved_location
+              puts "Path: #{event.file_path}"
+            end
+          end
+
+          private
+
+          def validate_scope(raw_scope)
+            return nil if raw_scope.nil?
+
+            scope = raw_scope.to_s.strip
+            allowed = Ace::Hitl::Molecules::WorktreeScopeResolver::VALID_SCOPES
+            return scope if allowed.include?(scope)
+
+            raise Ace::Support::Cli::Error.new("Invalid scope '#{raw_scope}'. Allowed: #{allowed.join(", ")}")
+          end
+
+          def format_resolved_location(resolved)
+            return nil unless resolved[:resolved_outside_current]
+
+            worktree = resolved[:resolved_worktree_root] || "(unknown worktree)"
+            "Resolved Location: worktree=#{worktree} path=#{resolved[:event].file_path}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/update.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/support/items"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Update < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Update HITL event metadata and/or answer"
+
+          argument :ref, required: true, desc: "HITL reference (full ID or shortcut)"
+
+          option :set, type: :string, repeat: true, desc: "Set field: key=value"
+          option :add, type: :string, repeat: true, desc: "Add field: key=value"
+          option :remove, type: :string, repeat: true, desc: "Remove field: key=value"
+          option :"move-to", type: :string, aliases: %w[-m], desc: "Move to folder (archive, next)"
+          option :answer, type: :string, desc: "Write ## Answer body and mark answered"
+          option :resume, type: :boolean, desc: "Dispatch resume after answer using waiter/session metadata"
+          option :scope, type: :string, desc: "Scope (current, all)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            set_args = Array(options[:set])
+            add_args = Array(options[:add])
+            remove_args = Array(options[:remove])
+            move_to = options[:"move-to"]
+            answer = options[:answer]
+            resume = options[:resume] == true
+            scope = validate_scope(options[:scope])
+
+            if set_args.empty? && add_args.empty? && remove_args.empty? && move_to.nil? && answer.nil? && !resume
+              raise Ace::Support::Cli::Error.new("No update operations specified")
+            end
+
+            set_hash = parse_kv_pairs(set_args)
+            add_hash = parse_kv_pairs(add_args)
+            remove_hash = parse_kv_pairs(remove_args)
+
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            event = begin
+              manager.update(
+                ref,
+                set: set_hash,
+                add: add_hash,
+                remove: remove_hash,
+                move_to: move_to,
+                answer: answer,
+                scope: scope
+              )
+            rescue Ace::Hitl::Organisms::HitlManager::AmbiguousReferenceError => e
+              candidates = e.matches.map(&:file_path).join(", ")
+              raise Ace::Support::Cli::Error.new(
+                "HITL event '#{ref}' is ambiguous across scope '#{scope || "all"}'. Candidates: #{candidates}"
+              )
+            end
+
+            raise Ace::Support::Cli::Error.new("HITL event '#{ref}' not found") unless event
+
+            if move_to
+              folder_info = event.special_folder || "root"
+              puts "HITL event updated: #{event.id} #{event.title} -> #{folder_info}"
+            else
+              puts "HITL event updated: #{event.id} #{event.title}"
+            end
+
+            return unless resume
+
+            dispatch = manager.dispatch_resume(event.id, scope: scope)
+            case dispatch[:status]
+            when :waiter_active
+              puts "Resume dispatch skipped: active waiter lease detected."
+            when :dispatched
+              puts "Resume dispatched: mode=#{dispatch[:mode]} details=#{dispatch[:details]}"
+              puts "HITL event archived after successful dispatch."
+            when :no_answer
+              raise Ace::Support::Cli::Error.new("Cannot resume '#{event.id}' without an answer")
+            when :failed
+              raise Ace::Support::Cli::Error.new(dispatch[:error] || "Resume dispatch failed")
+            else
+              raise Ace::Support::Cli::Error.new("Resume dispatch failed: unexpected status #{dispatch[:status]}")
+            end
+          end
+
+          private
+
+          def parse_kv_pairs(args)
+            result = {}
+            args.each do |arg|
+              unless arg.include?("=")
+                raise Ace::Support::Cli::Error.new("Invalid format '#{arg}': expected key=value")
+              end
+
+              parsed = Ace::Support::Items::Atoms::FieldArgumentParser.parse([arg])
+              parsed.each do |key, value|
+                result[key] = if result.key?(key)
+                  Array(result[key]) + Array(value)
+                else
+                  value
+                end
+              end
+            rescue Ace::Support::Items::Atoms::FieldArgumentParser::ParseError => e
+              raise Ace::Support::Cli::Error.new("Invalid argument '#{arg}': #{e.message}")
+            end
+            result
+          end
+
+          def validate_scope(raw_scope)
+            return nil if raw_scope.nil?
+
+            scope = raw_scope.to_s.strip
+            allowed = Ace::Hitl::Molecules::WorktreeScopeResolver::VALID_SCOPES
+            return scope if allowed.include?(scope)
+
+            raise Ace::Support::Cli::Error.new("Invalid scope '#{raw_scope}'. Allowed: #{allowed.join(", ")}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/wait.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        class Wait < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Wait for a specific HITL event answer (polling default)"
+
+          argument :ref, required: true, desc: "HITL reference (full ID or shortcut)"
+
+          option :"poll-every", type: :integer, desc: "Polling interval in seconds (default: 600)"
+          option :timeout, type: :integer, desc: "Max wait time in seconds (default: 14400)"
+          option :scope, type: :string, desc: "Scope (current, all)"
+          option :"session-id", type: :string, desc: "Waiter session id (optional)"
+          option :provider, type: :string, desc: "Waiter provider (optional)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            scope = validate_scope(options[:scope])
+            poll_every = options[:"poll-every"] || 600
+            timeout = options[:timeout] || 14_400
+
+            waiter = {
+              session_id: options[:"session-id"] || ENV["ACE_AGENT_SESSION_ID"] || ENV["ACE_SESSION_ID"],
+              provider: options[:provider] || ENV["ACE_PROVIDER"]
+            }
+
+            manager = Ace::Hitl::Organisms::HitlManager.new
+            result = manager.wait_for_answer(
+              ref,
+              scope: scope,
+              poll_every: poll_every,
+              timeout: timeout,
+              waiter: waiter
+            )
+
+            case result[:status]
+            when :answered
+              event = result[:event]
+              puts "HITL event answered: #{event.id} #{event.title}"
+              puts "Answer: #{event.answer}"
+              resume = event.metadata["resume_instructions"]
+              puts "Resume: #{resume}" if resume
+            when :timeout
+              raise Ace::Support::Cli::Error.new("Timed out waiting for HITL event '#{ref}'")
+            else
+              raise Ace::Support::Cli::Error.new("HITL event '#{ref}' not found")
+            end
+          end
+
+          private
+
+          def validate_scope(raw_scope)
+            return nil if raw_scope.nil?
+
+            scope = raw_scope.to_s.strip
+            allowed = Ace::Hitl::Molecules::WorktreeScopeResolver::VALID_SCOPES
+            return scope if allowed.include?(scope)
+
+            raise Ace::Support::Cli::Error.new("Invalid scope '#{raw_scope}'. Allowed: #{allowed.join(", ")}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../hitl/version"
+require_relative "cli/commands/create"
+require_relative "cli/commands/show"
+require_relative "cli/commands/list"
+require_relative "cli/commands/update"
+require_relative "cli/commands/wait"
+
+module Ace
+  module Hitl
+    module HitlCLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-hitl"
+
+      REGISTERED_COMMANDS = [
+        ["create", "Create HITL event"],
+        ["show", "Show HITL event details"],
+        ["list", "List HITL events"],
+        ["update", "Update HITL event metadata or answer"],
+        ["wait", "Wait for an answer on a specific HITL event"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-hitl list --status pending",
+        "ace-hitl show abc123 --content",
+        "ace-hitl create \"Which auth strategy?\" --kind decision",
+        "ace-hitl update abc123 --answer \"Use JWT with refresh tokens\"",
+        "ace-hitl wait abc123 --poll-every 600 --timeout 14400"
+      ].freeze
+
+      register "create", CLI::Commands::Create
+      register "show", CLI::Commands::Show
+      register "list", CLI::Commands::List
+      register "update", CLI::Commands::Update
+      register "wait", CLI::Commands::Wait
+
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-hitl",
+        version: Ace::Hitl::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Hitl::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+
+      def self.start(args)
+        Ace::Support::Cli::Runner.new(self).call(args: args)
+      end
+    end
+  end
+end

data/lib/ace/hitl/models/hitl_event.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Models
+      HitlEvent = Struct.new(
+        :id,
+        :status,
+        :kind,
+        :title,
+        :tags,
+        :questions,
+        :answer,
+        :content,
+        :path,
+        :file_path,
+        :special_folder,
+        :created_at,
+        :metadata,
+        keyword_init: true
+      ) do
+        def shortcut
+          id[-3..]
+        end
+
+        def answered?
+          status.to_s == "answered" || metadata["answered"] == true
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_answer_editor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Molecules
+      class HitlAnswerEditor
+        ANSWER_HEADER = /^## Answer\s*$/
+
+        def self.apply(body, answer)
+          answer_text = answer.to_s.strip
+          replacement = "## Answer\n\n#{answer_text}\n"
+          source = body.to_s.rstrip
+
+          if source.match?(ANSWER_HEADER)
+            source.sub(/^## Answer[ \t]*(?:\n.*)?\z/m, replacement)
+          elsif source.empty?
+            replacement
+          else
+            "#{source}\n\n#{replacement}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/molecules/hitl_config_loader.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/config"
+require "ace/support/fs"
+
+module Ace
+  module Hitl
+    module Molecules
+      class HitlConfigLoader
+        DEFAULT_ROOT_DIR = ".ace-local/hitl"
+        DEFAULT_KIND = "clarification"
+
+        def self.load(gem_root: nil)
+          gem_root ||= File.expand_path("../../../..", __dir__)
+          resolver = Ace::Support::Config.create(
+            config_dir: ".ace",
+            defaults_dir: ".ace-defaults",
+            gem_path: gem_root
+          )
+          {"hitl" => resolver.resolve_namespace("hitl").data}
+        rescue StandardError => e
+          warn "ace-hitl: Could not load config: #{e.class} - #{e.message}" if Ace::Hitl.respond_to?(:debug?) && Ace::Hitl.debug?
+          load_defaults_fallback(gem_root: gem_root)
+        end
+
+        def self.root_dir(config = nil)
+          config ||= load
+          dir = config.dig("hitl", "root_dir") || DEFAULT_ROOT_DIR
+
+          if dir.start_with?("/")
+            dir
+          else
+            File.join(Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current, dir)
+          end
+        end
+
+        def self.load_defaults_fallback(gem_root:)
+          defaults_path = File.join(gem_root, ".ace-defaults", "hitl", "config.yml")
+          return {} unless File.exist?(defaults_path)
+
+          YAML.safe_load_file(defaults_path, permitted_classes: [Date, Time, Symbol], aliases: true) || {}
+        rescue StandardError
+          {}
+        end
+        private_class_method :load_defaults_fallback
+      end
+    end
+  end
+end