ask-ruby-harness 0.1.0

data/lib/ask/ruby/harness/tools/read_log.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Ask
+  module Ruby
+    module Harness
+      module Tools
+        class ReadLog < Ask::Ruby::Harness::Tool
+          description "Read application log files with filtering. Supports standard " \
+                       "log rotation. Reads from the end of the file (most recent first)."
+
+          param :lines,  type: :integer, desc: "Number of recent lines (default 50, max 500)", required: false
+          param :level,  type: :string, desc: "Filter by level: ERROR, WARN, INFO, DEBUG", required: false
+          param :search, type: :string, desc: "Search term (plain text, case-insensitive)", required: false
+          param :file,   type: :string, desc: "Log file name (default: log/<env>.log)", required: false
+
+          MAX_LINES = 500
+          LEVEL_PATTERNS = {
+            "ERROR" => /\bERROR\b/i,
+            "WARN"  => /\bWARN\b/i,
+            "INFO"  => /\bINFO\b/i,
+            "DEBUG" => /\bDEBUG\b/i
+          }.freeze
+
+          def execute(lines: 50, level: nil, search: nil, file: nil)
+            max_lines = [lines.to_i, MAX_LINES].min
+            log_path = resolve_log_path(file)
+
+            unless log_path.exist?
+              return Ask::Result.failure(
+                "Log file not found: #{log_path}. The application may not have written any logs yet."
+              )
+            end
+
+            raw_lines = read_all_log_files(log_path)
+            return { lines: [], total_lines: 0, path: log_path.to_s } if raw_lines.empty?
+
+            filtered = apply_filters(raw_lines, level: level, search: search)
+            recent = filtered.last(max_lines).map(&:chomp)
+
+            {
+              lines: recent,
+              total_lines: raw_lines.size,
+              matched_lines: filtered.size,
+              path: log_path.to_s,
+              filters_applied: { level: level, search: search }.compact
+            }
+          end
+
+          private
+
+          def resolve_log_path(custom_path)
+            return app_root.join(custom_path) if custom_path
+            app_root.join("log", "#{Ask::Ruby::Harness.env}.log")
+          end
+
+          # Read from rotated archives too: log/production.log, .1, .2.gz, etc.
+          def read_all_log_files(log_path)
+            all_content = +""
+            rotated_files(log_path).each do |path|
+              content = read_file_content(path)
+              all_content.prepend(content) if content
+            end
+            all_content.lines
+          end
+
+          def rotated_files(log_path)
+            dir = log_path.dirname
+            base = log_path.basename.to_s
+            # Primary file, then rotated files in reverse order (oldest first, then primary last)
+            pattern = File.join(dir, "#{base}.*")
+            rotations = Dir[pattern].sort_by { |f| extract_rotation_number(f) }
+            # Primary file is read last (most recent)
+            rotations + [log_path.to_s]
+          end
+
+          def extract_rotation_number(path)
+            File.basename(path).sub(/.*\.(\d+)(\.gz)?$/, '\1').to_i
+          rescue
+            0
+          end
+
+          def read_file_content(path)
+            if path.to_s.end_with?(".gz")
+              Zlib::GzipReader.open(path.to_s) { |gz| gz.read }
+            else
+              File.read(path.to_s)
+            end
+          rescue => e
+            warn "[ReadLog] Could not read #{path}: #{e.message}"
+            nil
+          end
+
+          def apply_filters(lines, level: nil, search: nil)
+            filtered = lines
+            filtered = filtered.select { |l| LEVEL_PATTERNS.fetch(level) { // }.match?(l) } if level
+            filtered = filtered.select { |l| l.downcase.include?(search.downcase) } if search
+            filtered
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/ruby/harness/tools/read_model.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module Ask
+  module Ruby
+    module Harness
+      module Tools
+        class ReadModel < Ask::Ruby::Harness::Tool
+          description "Inspect an ActiveRecord model — columns, associations, validations, " \
+                       "scopes, and indexes. Returns structured data the agent can act on."
+
+          param :name,   type: :string, desc: "Model class name (e.g. 'User', 'Blog::Post')", required: true
+          param :detail, type: :string, desc: "Which details: 'all' (default), 'columns', 'associations', 'validations', 'scopes'", required: false
+
+          def execute(name:, detail: "all")
+            klass = safe_constantize(name)
+            return Ask::Result.failure("Model '#{name}' not found or is not an ActiveRecord model.") unless klass
+
+            result = { name: klass.name, table_name: klass.table_name }
+
+            result[:primary_key] = klass.primary_key if klass.respond_to?(:primary_key)
+
+            if %w[all columns].include?(detail)
+              result[:columns] = klass.columns.map { |c|
+                entry = { name: c.name, type: c.type, null: c.null, default: c.default }
+                entry[:primary_key] = true if c.name == klass.primary_key
+                entry
+              }
+            end
+
+            if %w[all associations].include?(detail)
+              result[:associations] = klass.reflect_on_all_associations.group_by(&:macro).transform_values { |refs|
+                refs.map { |a|
+                  entry = { name: a.name, class_name: a.class_name }
+                  entry[:through] = a.options[:through] if a.options[:through]
+                  entry[:source] = a.options[:source] if a.options[:source]
+                  entry[:foreign_key] = a.foreign_key if a.respond_to?(:foreign_key)
+                  entry
+                }
+              }
+            end
+
+            if %w[all scopes].include?(detail) && klass.respond_to?(:all)
+              result[:scopes] = klass.methods(false)
+                .reject { |m| m.to_s.end_with?("=", "!", "?") || %i[new allocate inspect to_s].include?(m) }
+                .map(&:to_s).sort
+            end
+
+            if %w[all validations].include?(detail)
+              result[:validators] = klass.validators.map { |v|
+                {
+                  attribute: v.attributes.first&.to_s,
+                  kind: v.kind,
+                  options: v.options.reject { |k, _| k == :if }
+                }
+              }.reject { |v| v[:attribute].nil? }
+            end
+
+            result
+          end
+
+          private
+
+          def safe_constantize(name)
+            klass = name.safe_constantize
+            return nil unless klass
+            return nil unless klass < ActiveRecord::Base
+            klass
+          rescue
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/ruby/harness/tools/run_command.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ask
+  module Ruby
+    module Harness
+      module Tools
+        class RunCommand < Ask::Ruby::Harness::Tool
+          description "Run a shell command in the project root directory."
+          param :command, type: :string, desc: "Shell command to run", required: true
+
+          def execute(command:)
+            check_result = check_command_allowed(command)
+            return check_result if check_result
+
+            output = `cd #{app_root} && #{command} 2>&1`
+            Ask::Result.ok(
+              data: { output: output, exit_status: $?.exitstatus },
+              metadata: { exit_status: $?.exitstatus }
+            )
+          end
+
+          private
+
+          def check_command_allowed(command)
+            config = Ask::Ruby::Harness.configuration
+
+            # Use per-environment rules if configured, fall back to global
+            denied = config.effective_denied_commands
+            allowed = config.effective_allowed_commands
+
+            # 1. Check denied commands first (takes precedence)
+            if denied
+              denied.each do |pattern|
+                if command.match?(pattern)
+                  return Ask::Result.error(
+                    message: "Command blocked by deny rule: #{pattern.inspect}"
+                  )
+                end
+              end
+            end
+
+            # 2. Check allowed commands (if configured)
+            if allowed
+              matches = allowed.any? { |pattern| command.match?(pattern) }
+              unless matches
+                allowed_desc = allowed.map(&:inspect).join(", ")
+                return Ask::Result.error(
+                  message: "Command blocked: does not match any allowed pattern (#{allowed_desc})"
+                )
+              end
+            end
+
+            # 3. No restrictions configured — allow
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/ruby/harness/tools/run_tests.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Ask
+  module Ruby
+    module Harness
+      module Tools
+        class RunTests < Ask::Ruby::Harness::Tool
+          description "Run the project's test suite and return structured results — summary counts " \
+                       "plus per-test file/line/message for failures, never raw terminal output. " \
+                       "Detects the runner (bin/rails test, rspec, or rake test). Minitest gets a " \
+                       "JSON reporter via the bundled minitest plugin; rspec uses its built-in JSON " \
+                       "formatter. Rerun only the previous run's failures with failed_only."
+
+          param :file, type: :string, desc: "Test file path(s) relative to the project root (comma-separated for multiple)", required: false
+          param :name, type: :string, desc: "Test name pattern: minitest --name (string or /regex/), rspec -e", required: false
+          param :failed_only, type: :boolean, desc: "Rerun only the tests that failed in the previous run", required: false
+          param :timeout, type: :integer, desc: "Max seconds to wait before killing the run (default 300)", required: false
+
+          DEFAULT_TIMEOUT = 300
+          ARTIFACT_DIR = %w[tmp test .ask].freeze
+
+          def execute(file: nil, name: nil, failed_only: false, timeout: DEFAULT_TIMEOUT)
+            files = split_files(file)
+            runner = detect_runner
+
+            failed_tests = failed_only ? load_failed_tests : nil
+            if failed_only && failed_tests.empty?
+              return Ask::Result.failure("No failed tests from the previous run to rerun.")
+            end
+
+            artifact_dir = app_root.join(*ARTIFACT_DIR).tap(&:mkpath)
+            log_path = artifact_dir.join("last-test.log")
+            json_path = artifact_dir.join("last-test.json")
+            status_path = artifact_dir.join("last-failures.json")
+
+            command, env = build_command(runner, files, name, failed_tests, json_path)
+            outcome = run(command, env, log_path, timeout)
+
+            results = parse_results(runner, json_path)
+            unless results
+              # A killed run can't produce results — report it structurally
+              # instead of failing, so the agent still gets the artifact path.
+              return Ask::Result.ok(data: timed_out_report(runner, command, env, outcome, status_path, log_path)) if outcome[:timed_out]
+
+              return Ask::Result.failure(
+                "Test run finished without machine-readable results (#{runner}); " \
+                "full output at #{rel(log_path)}"
+              )
+            end
+
+            report = build_report(runner, command, env, outcome, results, status_path, log_path)
+            Ask::Result.ok(data: report)
+          end
+
+          private
+
+          def split_files(file)
+            return [] if file.nil? || file.to_s.strip.empty?
+            file.split(",").map(&:strip).reject(&:empty?)
+          end
+
+          # Rails app → bin/rails test; rspec in the bundle with a spec/ dir →
+          # rspec; anything else → minitest via rake test.
+          def detect_runner
+            return :rails if app_root.join("bin", "rails").exist?
+            lockfile = app_root.join("Gemfile.lock")
+            rspec = lockfile.exist? && lockfile.read.include?("rspec")
+            return :rspec if rspec && app_root.join("spec").directory?
+            :minitest
+          end
+
+          def build_command(runner, files, name, failed_tests, json_path)
+            case runner
+            when :rspec
+              args = ["bundle", "exec", "rspec"]
+              args.concat(files)
+              args.concat(failed_tests.map { |t| "#{t[:file]}:#{t[:line]}" }) if failed_tests
+              args.concat(["-e", name]) if name
+              args.concat(["--format", "json", "--out", json_path.to_s])
+              [args, {}]
+            when :rails
+              # Rails' `rails test` passes CLI args straight to minitest.
+              args = ["bin/rails", "test"]
+              args.concat(files)
+              args.concat(["-n", name]) if name
+              args.concat(["-n", name_pattern(failed_tests)]) if failed_tests
+              [args, injection_env(json_path)]
+            else
+              # Plain Ruby project: rake test. Rake::TestTask reads TESTOPTS
+              # (passed to ruby's ARGV, where rake_test_loader keeps only
+              # `-`-prefixed args — so options must use the attached
+              # --name=... form) and TEST (single file); the JSON reporter
+              # arrives via RUBYOPT like everywhere else.
+              args = ["bundle", "exec", "rake", "test"]
+              env = injection_env(json_path)
+              env["TEST"] = files.first if files.size == 1
+              testopts = []
+              testopts << "--name=#{name}" if name
+              testopts << "--name=#{name_pattern(failed_tests)}" if failed_tests
+              env["TESTOPTS"] = testopts.join(" ") unless testopts.empty?
+              [args, env]
+            end
+          end
+
+          # minitest 6 dropped both plugin auto-discovery and the -r option.
+          # Activate the project's bundle first, then require the plugin by
+          # absolute path — it pushes its extension, and init_plugins
+          # registers the JSON reporter later.
+          def injection_env(json_path)
+            {
+              "ASK_TEST_JSON_PATH" => json_path.to_s,
+              "RUBYOPT" => "-rbundler/setup -r#{minitest_plugin_path}"
+            }
+          end
+
+          def minitest_plugin_path
+            spec = Gem.loaded_specs["ask-ruby-harness"]
+            spec ||= Gem::Specification.find_by_name("ask-ruby-harness")
+            File.join(spec.full_gem_path, "lib", "minitest", "ask_ruby_harness_plugin.rb")
+          end
+
+          # Minitest --name accepts a regexp; alternation runs exactly the
+          # failed tests.
+          def name_pattern(failed_tests)
+            escaped = failed_tests.map { |t| Regexp.escape(t[:test_name]) }
+            "/#{escaped.join('|')}/"
+          end
+
+          def run(command, env, log_path, timeout)
+            # The harness server may run with a deliberately small pool
+            # (e.g. RAILS_MAX_THREADS=1 in its MCP config). Test runs are a
+            # separate concern — let them use the app's normal pool sizes and
+            # their own bundle. All BUNDLE*/BUNDLER_* vars are stripped so
+            # the child's `bundle exec` resolves the project's own Gemfile
+            # from cwd (inherited BUNDLE_GEMFILE and BUNDLER_ORIG_* sentinels
+            # would otherwise hijack it).
+            child_env = env.merge("RAILS_MAX_THREADS" => nil)
+            ENV.each_key { |k| child_env[k] = nil if k.start_with?("BUNDLE") }
+            pid = Process.spawn(child_env, *command, chdir: app_root.to_s,
+                                out: [log_path.to_s, "w"], err: [:child, :out])
+            status = nil
+            timed_out = false
+            begin
+              Timeout.timeout(timeout) { status = Process.wait2(pid).last }
+            rescue Timeout::Error
+              timed_out = true
+              begin
+                Process.kill("TERM", pid)
+                sleep 0.2
+                Process.kill("KILL", pid)
+              rescue Errno::ESRCH, Errno::EPERM
+                # Process already gone — nothing to kill.
+              end
+              status = Process.wait2(pid).last rescue nil
+            end
+            { exit_status: status&.exitstatus, timed_out: timed_out }
+          end
+
+          def build_report(runner, command, env, outcome, results, status_path, log_path)
+            summary = results[:summary]
+            failed_tests = results[:failed_tests]
+            persist_failed_tests(runner, failed_tests, status_path)
+
+            {
+              framework: runner.to_s,
+              command: command.join(" "),
+              exit_status: outcome[:exit_status],
+              timed_out: outcome[:timed_out],
+              summary: summary,
+              failed_tests: failed_tests,
+              artifact: rel(log_path),
+              next: summary[:failures] + summary[:errors] > 0 ? "run_tests(failed_only: true)" : nil
+            }
+          end
+
+          def timed_out_report(runner, command, env, outcome, status_path, log_path)
+            persist_failed_tests(runner, [], status_path)
+            {
+              framework: runner.to_s,
+              command: command.join(" "),
+              exit_status: outcome[:exit_status],
+              timed_out: true,
+              summary: nil,
+              failed_tests: nil,
+              artifact: rel(log_path),
+              next: nil
+            }
+          end
+
+          def parse_results(runner, json_path)
+            return nil unless json_path.exist?
+            payload = JSON.parse(json_path.read)
+            runner == :rspec ? parse_rspec(payload) : parse_minitest(payload)
+          rescue JSON::ParserError
+            nil
+          end
+
+          def parse_minitest(payload)
+            tests = payload["tests"] || []
+            summary = {
+              run: payload.fetch("run", tests.size),
+              failures: payload.fetch("failures", 0),
+              errors: payload.fetch("errors", 0),
+              skips: payload.fetch("skips", 0)
+            }
+            failed_tests = tests.filter_map do |t|
+              next unless %w[failed error].include?(t["status"])
+              { file: t["file"], test_name: t["name"], line: t["line"], message: t["message"] }
+            end
+            { summary: summary, failed_tests: failed_tests }
+          end
+
+          def parse_rspec(payload)
+            examples = payload["examples"] || []
+            summary_payload = payload["summary"] || {}
+            failed_examples = examples.select { |e| e["status"] == "failed" }
+            pending = examples.count { |e| e["status"] == "pending" }
+            summary = {
+              run: summary_payload.fetch("example_count", examples.size),
+              failures: summary_payload.fetch("failure_count", failed_examples.size),
+              errors: 0,
+              skips: summary_payload.fetch("pending_count", pending)
+            }
+            failed_tests = failed_examples.map do |e|
+              exception = e["exception"] || {}
+              {
+                file: e["file_path"],
+                test_name: e["full_description"],
+                line: e["line_number"],
+                message: exception["message"]
+              }
+            end
+            { summary: summary, failed_tests: failed_tests }
+          end
+
+          def persist_failed_tests(runner, failed_tests, status_path)
+            status_path.write(JSON.pretty_generate(framework: runner.to_s, failed_tests: failed_tests))
+          end
+
+          def load_failed_tests
+            path = app_root.join(*ARTIFACT_DIR, "last-failures.json")
+            return [] unless path.exist?
+            JSON.parse(path.read).fetch("failed_tests", []).map { |t| symbolize_keys(t) }
+          rescue JSON::ParserError
+            []
+          end
+
+          def symbolize_keys(hash)
+            hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+          end
+
+          def rel(path)
+            path.relative_path_from(app_root).to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/ruby/harness/tools/schema_graph.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Ask
+  module Ruby
+    module Harness
+      module Tools
+        class SchemaGraph < Ask::Ruby::Harness::Tool
+          description "Return the full application schema graph — all models, tables, columns with types, " \
+                       "associations (belongs_to, has_many, has_one, HABTM, through), validations, indexes, " \
+                       "and polymorphic relationships. One call gives the agent a complete mental model " \
+                       "of the application's data layer."
+
+          param :detail, type: :string, desc: "Detail level: 'all' (default), 'models', 'associations', 'tables'", required: false
+
+          TABLE_EXCLUSIONS = %w[schema_migrations ar_internal_metadata].freeze
+
+          def execute(detail: "all")
+            models = discover_ar_models
+
+            result = {
+              summary: {
+                model_count: models.size,
+                table_count: models.map { |m| m.table_name }.uniq.size,
+                association_count: models.sum { |m| m.reflect_on_all_associations.size }
+              },
+              models: %w[all models].include?(detail) ? build_model_details(models, detail) : nil,
+              associations: %w[all associations].include?(detail) ? build_association_graph(models) : nil,
+              tables: %w[all tables].include?(detail) ? build_table_details(detail) : nil
+            }
+
+            result
+          end
+
+          private
+
+          def discover_ar_models
+            # Eager-load the host app's models when it's a full framework app
+            # (Rails); in a plain Ruby project the models are loaded by
+            # whatever loaded them.
+            if defined?(::Rails::Application) && ::Rails.application
+              ::Rails.application.eager_load! rescue nil
+            end
+            ActiveRecord::Base.descendants.reject do |klass|
+              klass.abstract_class? ||
+              klass.name.nil? ||
+              TABLE_EXCLUSIONS.include?(klass.table_name) ||
+              klass.name.start_with?("ActiveRecord::", "ActiveStorage::", "ActionText::")
+            end.sort_by(&:name)
+          rescue StandardError
+            []
+          end
+
+          def build_model_details(models, detail)
+            models.filter_map do |klass|
+              name = klass.name rescue nil
+              next nil unless name
+
+              entry = {
+                name: name,
+                table_name: klass.table_name,
+                primary_key: safe_primary_key(klass)
+              }
+
+              if klass.respond_to?(:columns)
+                entry[:columns] = safe_columns(klass)
+              end
+
+              if klass.respond_to?(:reflect_on_all_associations)
+                entry[:associations] = klass.reflect_on_all_associations.group_by(&:macro).transform_values { |refs|
+                  refs.map { |a|
+                    assoc = { name: a.name, class_name: a.class_name }
+                    assoc[:through] = a.options[:through] if a.options[:through]
+                    assoc[:source] = a.options[:source] if a.options[:source]
+                    assoc[:foreign_key] = a.foreign_key
+                    assoc[:polymorphic] = true if a.polymorphic?
+                    assoc[:as] = a.options[:as] if a.options[:as]
+                    assoc[:dependent] = a.options[:dependent] if a.options[:dependent]
+                    assoc
+                  }
+                }
+              end
+
+              if klass.respond_to?(:validators)
+                entry[:validators] = klass.validators.map { |v|
+                  {
+                    attribute: v.attributes.first&.to_s,
+                    kind: v.kind,
+                    options: v.options.reject { |k, _| k == :if }
+                  }
+                }.reject { |v| v[:attribute].nil? }
+              end
+
+              entry
+            end
+          end
+
+          def build_association_graph(models)
+            edges = []
+
+            models.each do |klass|
+              klass.reflect_on_all_associations.each do |a|
+                next if a.macro == :has_many && a.options[:through]  # Skip through associations (derived)
+
+                target_model = find_model_for_association(models, a)
+                next unless target_model
+
+                edges << {
+                  from: klass.name,
+                  to: target_model.name,
+                  type: a.macro,
+                  via: a.name,
+                  foreign_key: a.foreign_key,
+                  polymorphic: a.polymorphic? || false
+                }
+              end
+            end
+
+            edges
+          end
+
+          def find_model_for_association(models, association)
+            class_name = association.class_name
+            # Try exact match first, then match by class name suffix (handles namespace issues)
+            models.find { |m| m.name == class_name } ||
+              models.find { |m| m.name.end_with?("::#{class_name}") } ||
+              models.find { |m| class_name.end_with?("::#{m.name}") }
+          end
+
+          def build_table_details(detail)
+            models = discover_ar_models
+            tables = {}
+
+            models.each do |klass|
+              table = klass.table_name
+              next if TABLE_EXCLUSIONS.include?(table)
+
+              tables[table] = {
+                model: klass.name,
+                columns: safe_columns(klass),
+                indexes: fetch_indexes_for(table)
+              }
+            end
+
+            tables
+          end
+
+          def safe_primary_key(klass)
+            klass.primary_key
+          rescue StandardError
+            nil
+          end
+
+          def safe_columns(klass)
+            klass.columns.map { |c|
+              col = { name: c.name, type: c.type, null: c.null }
+              col[:default] = c.default unless c.default.nil?
+              col[:primary_key] = true if c.name == klass.primary_key
+              col
+            }
+          rescue StandardError
+            []
+          end
+
+          def fetch_indexes_for(table_name)
+            ActiveRecord::Base.connection.indexes(table_name).map do |idx|
+              {
+                name: idx.name,
+                columns: idx.columns,
+                unique: idx.unique
+              }
+            end
+          rescue StandardError
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/ruby/harness/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ask
+  module Ruby
+    module Harness
+      VERSION = "0.1.0"
+    end
+  end
+end