ace-llm-providers-cli 0.27.0

data/README.md

@@ -0,0 +1,36 @@
+<div align="center">
+  <h1> ACE - LLM Providers CLI </h1>
+
+  CLI-backed provider adapters that extend ace-llm with local tool execution.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-llm-providers-cli"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-llm-providers-cli.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[ace-llm Usage Guide](../ace-llm/docs/usage.md) | [ace-llm Handbook](../ace-llm/docs/handbook.md)
+`ace-llm-providers-cli` extends [ace-llm](../ace-llm) with provider clients that execute through installed CLI tools (Claude, Codex, OpenCode, Gemini, pi, Codex OSS) while preserving the shared command interface. Provider defaults live in versioned YAML, and a health-check command verifies local readiness.
+
+## How It Works
+
+1. The gem registers CLI provider clients on require, making them available to [ace-llm](../ace-llm) automatically.
+2. Provider defaults are read from `.ace-defaults/llm/providers/*.yml` and can be overridden through the [ace-support-config](../ace-support-config) cascade.
+3. When [ace-llm](../ace-llm) routes a model call, the matching CLI adapter executes a subprocess command and returns a normalized response.
+
+## Use Cases
+
+**Use CLI-native providers through one surface** - run prompts against Claude, Codex, OpenCode, Gemini, pi, and Codex OSS via [ace-llm](../ace-llm) without changing calling conventions.
+
+**Keep provider configuration in versioned YAML** - tune model behavior and provider settings through [ace-support-config](../ace-support-config) instead of custom glue code.
+
+**Diagnose local provider readiness** - run `ace-llm-providers-cli-check` to verify that CLI tools are installed, authenticated, and reachable before starting work.
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+desc "Run tests using ace-test"
+task :test do
+  sh "ace-test"
+end
+
+desc "Run tests directly (CI mode)"
+Minitest::TestTask.create(:ci)
+
+task default: :test

data/exe/ace-llm-providers-cli-check

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Handle --help explicitly before loading dependencies
+if ARGV.include?("--help") || ARGV.include?("-h") || ARGV.include?("help")
+  puts <<~HELP
+    Usage: ace-llm-providers-cli-check
+
+    Checks availability and authentication status of CLI-based LLM tools.
+
+    Options:
+      -h, --help    Display this help message
+
+    This utility checks for the following CLI tools:
+      - Claude Code (claude)
+      - Codex (codex)
+      - OpenCode (opencode)
+      - Codex OSS (codex-oss)
+
+    Exit codes:
+      0 - At least one CLI tool is available
+      1 - No CLI tools are available
+  HELP
+  exit 0
+end
+
+require_relative "../lib/ace/llm/providers/cli/molecules/health_checker"
+
+checker = Ace::Llm::Providers::Cli::Molecules::HealthChecker.new
+results = checker.check_all
+
+puts "🔍 Checking CLI-based LLM providers for ace-llm-providers-cli\n\n"
+
+max_name_length = results.map { |r| r[:name].length }.max
+
+results.each do |result|
+  name_padded = result[:name].ljust(max_name_length)
+  status_icon = result[:available] ? "✅" : "❌"
+  auth_icon = result[:authenticated] ? "🔓" : "🔒"
+  config = result[:config]
+
+  puts "#{status_icon} #{name_padded} (#{result[:provider]})"
+
+  if result[:available]
+    puts "   Version: #{result[:version]}"
+    puts "   Auth: #{auth_icon} #{result[:auth_status]}"
+  else
+    puts "   Status: Not installed"
+    puts "   Install: #{config[:install_cmd]}"
+    puts "   URL: #{config[:install_url]}" if config[:install_url]
+  end
+
+  puts
+end
+
+# Summary
+available_count = results.count { |r| r[:available] }
+authenticated_count = results.count { |r| r[:authenticated] }
+
+puts "─" * 50
+puts "\n📊 Summary:"
+puts "   Available: #{available_count}/#{results.size} CLI tools installed"
+puts "   Authenticated: #{authenticated_count}/#{available_count} tools authenticated" if available_count > 0
+
+if available_count == 0
+  puts "\n💡 To use CLI providers, install at least one tool from above."
+  puts "   After installation, run this check again to verify authentication."
+elsif authenticated_count < available_count
+  puts "\n💡 Some tools need authentication. Run the auth commands shown above."
+else
+  puts "\n🎉 All installed CLI tools are ready to use with ace-llm!"
+  puts "   Example: ace-llm claude:opus \"Hello, Claude!\""
+  puts "   Or using alias: ace-llm cc \"Hello, Claude!\""
+end
+
+exit(available_count == 0 ? 1 : 0)

data/lib/ace/llm/providers/cli/atoms/args_normalizer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          class ArgsNormalizer
+            def normalize_cli_args(cli_args)
+              return [] if cli_args.nil?
+
+              args = begin
+                if cli_args.is_a?(String)
+                  Shellwords.split(cli_args)
+                else
+                  normalize_cli_arg_array(cli_args)
+                end
+              rescue ArgumentError => e
+                raise ArgumentError, "Malformed --cli-args '#{cli_args}': #{e.message}"
+              end
+
+              args = normalize_arg_tokens(args)
+
+              normalized = []
+              previous_flag = false
+              seen_sentinel = false
+
+              args.each do |arg|
+                if seen_sentinel
+                  normalized << arg
+                  next
+                end
+
+                if arg == "--"
+                  normalized << arg
+                  seen_sentinel = true
+                  next
+                end
+
+                if arg.start_with?("-")
+                  normalized << arg
+                  previous_flag = !arg.include?("=")
+                  next
+                end
+
+                normalized << if previous_flag
+                  arg
+                else
+                  "--#{arg}"
+                end
+
+                previous_flag = false
+              end
+
+              normalized
+            end
+
+            private
+
+            def normalize_cli_arg_array(cli_args)
+              Array(cli_args).flat_map do |arg|
+                next [] if arg.nil?
+                next [""] if arg == ""
+
+                Shellwords.split(arg.to_s)
+              end
+            end
+
+            def normalize_arg_tokens(args)
+              args.compact.map do |arg|
+                string_arg = arg.to_s
+                string_arg.empty? ? string_arg : string_arg.strip
+              end.reject { |arg| arg != "" && arg.empty? }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/auth_checker.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Llm
+    module Providers
+      module Cli
+        module Atoms
+          # Checks authentication status for CLI-based LLM providers
+          class AuthChecker
+            # Check authentication for a specific provider
+            # @param provider [String] Provider name (claude, codex, opencode, codexoss)
+            # @return [Hash] Result with :authenticated and :message
+            def self.check(provider)
+              case provider
+              when "claude" then check_claude
+              when "codex" then check_codex
+              when "opencode" then check_opencode
+              when "codexoss" then check_codexoss
+              else
+                {authenticated: false, message: "Unknown provider: #{provider}"}
+              end
+            end
+
+            def self.check_claude
+              stdout, _, status = Open3.capture3("claude", "--version")
+              if status.success? && (stdout.include?("Claude") || stdout.include?("claude"))
+                {authenticated: true, message: "Authenticated"}
+              else
+                {authenticated: false, message: "Run: claude setup-token"}
+              end
+            rescue Errno::ENOENT, Errno::EACCES
+              {authenticated: false, message: "Authentication check failed"}
+            end
+
+            def self.check_codex
+              _, _, status = Open3.capture3("codex", "--help")
+              if status.success?
+                {authenticated: true, message: "Authenticated"}
+              else
+                {authenticated: false, message: "Run: codex login"}
+              end
+            rescue Errno::ENOENT, Errno::EACCES
+              {authenticated: false, message: "Authentication check failed"}
+            end
+
+            def self.check_opencode
+              _, _, status = Open3.capture3("opencode", "--version")
+              if status.success?
+                {authenticated: true, message: "Authenticated"}
+              else
+                {authenticated: false, message: "Run: opencode auth"}
+              end
+            rescue Errno::ENOENT, Errno::EACCES
+              {authenticated: false, message: "Authentication check failed"}
+            end
+
+            def self.check_codexoss
+              stdout, _, status = Open3.capture3("codex-oss", "--version")
+              if status.success? && stdout.include?("codex")
+                {authenticated: true, message: "Configured"}
+              else
+                {authenticated: false, message: "Run: codex-oss init"}
+              end
+            rescue Errno::ENOENT, Errno::EACCES
+              {authenticated: false, message: "Configuration check failed"}
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/command_formatters.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          module CommandFormatters
+            # Pi CLI: `/ace-git-commit` → `/skill:ace-git-commit`
+            PI_FORMATTER = ->(name) { "/skill:#{name}" }
+
+            # Codex CLI: `/ace-git-commit` → `$ace-git-commit`
+            CODEX_FORMATTER = ->(name) { "$#{name}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/command_rewriter.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          # Provider-agnostic skill/command rewriter.
+          # Transforms commands based on a formatter proc.
+          #
+          # Rules:
+          # - Only matches `/name` preceded by start-of-line or whitespace
+          # - Skips matches inside backtick code blocks (inline or fenced)
+          # - Skips URL-like patterns
+          # - Matches longest names first (avoids partial matches)
+          class CommandRewriter
+            # Rewrite command references in a prompt string.
+            #
+            # @param prompt [String] The prompt text to rewrite
+            # @param skill_names [Array<String>] Known command names
+            # @param formatter [Proc] Transformation proc (e.g., ->(name) { "/skill:#{name}" })
+            # @return [String] Rewritten prompt
+            def self.call(prompt, skill_names:, formatter:)
+              return prompt if prompt.nil? || prompt.empty?
+              return prompt if skill_names.nil? || skill_names.empty?
+
+              sorted_names = skill_names.sort_by { |n| -n.length }
+              name_pattern = sorted_names.map { |n| Regexp.escape(n) }.join("|")
+              pattern = /(?<=\A|\s)\/(#{name_pattern})(?=\s|\z)/m
+
+              rewrite_outside_code_blocks(prompt, pattern, formatter)
+            end
+
+            def self.rewrite_outside_code_blocks(prompt, pattern, formatter)
+              lines = prompt.split("\n", -1)
+              in_fenced_block = false
+              result = []
+
+              lines.each do |line|
+                if line.match?(/\A\s*```/)
+                  in_fenced_block = !in_fenced_block
+                  result << line
+                  next
+                end
+
+                if in_fenced_block
+                  result << line
+                  next
+                end
+
+                result << rewrite_line(line, pattern, formatter)
+              end
+
+              result.join("\n")
+            end
+
+            def self.rewrite_line(line, pattern, formatter)
+              segments = line.split(/(`[^`]*`)/)
+
+              segments.each_with_index.map do |segment, i|
+                if i.odd?
+                  segment
+                else
+                  segment.gsub(pattern) { formatter.call(Regexp.last_match(1)) }
+                end
+              end.join
+            end
+
+            private_class_method :rewrite_outside_code_blocks, :rewrite_line
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/execution_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          # Resolves filesystem execution context for CLI-backed providers.
+          module ExecutionContext
+            module_function
+
+            def resolve_working_dir(working_dir: nil, subprocess_env: nil)
+              explicit = working_dir.to_s.strip
+              return File.expand_path(explicit) unless explicit.empty?
+
+              env = subprocess_env.respond_to?(:to_h) ? subprocess_env.to_h : {}
+              project_root = env["PROJECT_ROOT_PATH"] || env[:PROJECT_ROOT_PATH]
+              project_root = project_root.to_s.strip
+              return File.expand_path(project_root) unless project_root.empty?
+
+              Dir.pwd
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/provider_detector.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Llm
+    module Providers
+      module Cli
+        module Atoms
+          # Detects whether a CLI tool is installed and retrieves its version
+          class ProviderDetector
+            # Check if a CLI tool is available on the system
+            # @param cli_name [String] Name of the CLI tool
+            # @return [Boolean] true if the tool is found in PATH
+            def self.available?(cli_name)
+              system("which", cli_name, out: File::NULL, err: File::NULL)
+            end
+
+            # Get the version of a CLI tool
+            # @param check_cmd [Array<String>] Command to run for version check
+            # @return [String] Version string or "Unknown"
+            def self.version(check_cmd)
+              stdout, _, status = Open3.capture3(*check_cmd)
+              return "Unknown" unless status.success?
+
+              extract_version(stdout)
+            rescue Errno::ENOENT, Errno::EACCES
+              "Unknown"
+            end
+
+            # Extract version number from command output
+            # @param output [String] Raw command output
+            # @return [String] Extracted version or first line
+            def self.extract_version(output)
+              if output =~ /(\d+\.\d+\.\d+)/
+                $1
+              elsif output =~ /v(\d+\.\d+)/
+                $1
+              else
+                output.lines.first&.strip || "Unknown"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/session_finders/claude_session_finder.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          module SessionFinders
+            # Finds a Claude Code session by scanning JSONL session files.
+            #
+            # Claude stores sessions under ~/.claude/projects/<encoded-path>/*.jsonl
+            # Path encoding: replace `/` and `.` with `-`
+            # Session ID: `sessionId` field on conversation entries
+            # First user message: `type:"user"` with `message.content` string
+            class ClaudeSessionFinder
+              DEFAULT_BASE = File.expand_path("~/.claude/projects").freeze
+
+              # @param working_dir [String] project directory to match
+              # @param prompt [String] expected first user message
+              # @param base_path [String] override base path for testing
+              # @param max_candidates [Integer] max files to scan
+              # @return [Hash, nil] { session_id:, session_path: } or nil
+              def self.call(working_dir:, prompt:, base_path: DEFAULT_BASE, max_candidates: 5)
+                encoded = encode_path(working_dir)
+                project_dir = File.join(base_path, encoded)
+                return nil unless File.directory?(project_dir)
+
+                candidates = Dir.glob(File.join(project_dir, "*.jsonl"))
+                  .sort_by { |f| -File.mtime(f).to_f }
+                  .first(max_candidates)
+
+                candidates.each do |path|
+                  result = scan_file(path, prompt)
+                  return result if result
+                end
+
+                nil
+              rescue
+                nil
+              end
+
+              def self.encode_path(path)
+                path.gsub(%r{[/.]}, "-")
+              end
+
+              def self.scan_file(path, prompt)
+                session_id = nil
+                File.foreach(path) do |line|
+                  entry = JSON.parse(line)
+                  session_id ||= entry["sessionId"]
+
+                  next unless entry["type"] == "user"
+
+                  content = entry.dig("message", "content")
+                  content = content.first["text"] if content.is_a?(Array)
+
+                  # Substring match: Claude wraps user input with prefixes (e.g. "User: "),
+                  # so exact equality would miss valid sessions.
+                  if content.is_a?(String) && content.include?(prompt.strip)
+                    return {session_id: session_id, session_path: path}
+                  end
+                rescue JSON::ParserError
+                  next
+                end
+                nil
+              rescue
+                nil
+              end
+
+              private_class_method :encode_path, :scan_file
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/session_finders/codex_session_finder.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          module SessionFinders
+            # Finds a Codex session by scanning JSONL session files.
+            #
+            # Codex stores sessions under ~/.codex/sessions/YYYY/MM/DD/*.jsonl
+            # Session ID: `session_meta.payload.id`
+            # First user message: `payload.role:"user"` + `payload.content[0].text`
+            class CodexSessionFinder
+              DEFAULT_BASE = File.expand_path("~/.codex/sessions").freeze
+
+              # @param working_dir [String] project directory (unused for path encoding, kept for interface)
+              # @param prompt [String] expected first user message
+              # @param base_path [String] override base path for testing
+              # @param max_candidates [Integer] max files to scan
+              # @return [Hash, nil] { session_id:, session_path: } or nil
+              def self.call(working_dir:, prompt:, base_path: DEFAULT_BASE, max_candidates: 5)
+                candidates = recent_session_files(base_path)
+                  .first(max_candidates)
+
+                candidates.each do |path|
+                  result = scan_file(path, prompt)
+                  return result if result
+                end
+
+                nil
+              rescue
+                nil
+              end
+
+              def self.recent_session_files(base_path)
+                return [] unless File.directory?(base_path)
+
+                Dir.glob(File.join(base_path, "**", "*.jsonl"))
+                  .sort_by { |f| -File.mtime(f).to_f }
+              end
+
+              def self.scan_file(path, prompt)
+                session_id = nil
+                File.foreach(path) do |line|
+                  entry = JSON.parse(line)
+
+                  # Extract session ID from session_meta entry
+                  if entry.dig("session_meta", "payload", "id")
+                    session_id = entry.dig("session_meta", "payload", "id")
+                  end
+
+                  # Check for user message match
+                  payload = entry["payload"] || entry
+                  next unless payload["role"] == "user"
+
+                  content = payload["content"]
+                  text = if content.is_a?(Array)
+                    content.first&.dig("text")
+                  elsif content.is_a?(String)
+                    content
+                  end
+
+                  if text.is_a?(String) && text.strip == prompt.strip
+                    return {session_id: session_id, session_path: path}
+                  end
+                rescue JSON::ParserError
+                  next
+                end
+                nil
+              rescue
+                nil
+              end
+
+              private_class_method :recent_session_files, :scan_file
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/atoms/session_finders/gemini_session_finder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Atoms
+          module SessionFinders
+            # Finds a Gemini CLI session by scanning JSON chat files.
+            #
+            # Gemini stores sessions under ~/.gemini/tmp/<sha256>/chats/*.json
+            # Directory name: SHA256 of the absolute working directory path
+            # Session ID: `sessionId` field in the JSON file
+            # First user message: `messages[0].content[0].text`
+            class GeminiSessionFinder
+              DEFAULT_BASE = File.expand_path("~/.gemini/tmp").freeze
+
+              # @param working_dir [String] project directory to match
+              # @param prompt [String] expected first user message
+              # @param base_path [String] override base path for testing
+              # @param max_candidates [Integer] max files to scan
+              # @return [Hash, nil] { session_id:, session_path: } or nil
+              def self.call(working_dir:, prompt:, base_path: DEFAULT_BASE, max_candidates: 5)
+                dir_hash = Digest::SHA256.hexdigest(File.expand_path(working_dir))
+                chats_dir = File.join(base_path, dir_hash, "chats")
+                return nil unless File.directory?(chats_dir)
+
+                candidates = Dir.glob(File.join(chats_dir, "*.json"))
+                  .sort_by { |f| -File.mtime(f).to_f }
+                  .first(max_candidates)
+
+                candidates.each do |path|
+                  result = scan_file(path, prompt)
+                  return result if result
+                end
+
+                nil
+              rescue
+                nil
+              end
+
+              def self.scan_file(path, prompt)
+                data = JSON.parse(File.read(path))
+                session_id = data["sessionId"]
+
+                first_message = data.dig("messages", 0, "content", 0, "text")
+                if first_message.is_a?(String) && first_message.strip == prompt.strip
+                  return {session_id: session_id, session_path: path}
+                end
+
+                nil
+              rescue
+                nil
+              end
+
+              private_class_method :scan_file
+            end
+          end
+        end
+      end
+    end
+  end
+end