codebase_index 0.1.0

data/lib/codebase_index/console/sql_validator.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# @see CodebaseIndex
+module CodebaseIndex
+  class Error < StandardError; end unless defined?(CodebaseIndex::Error)
+
+  module Console
+    class SqlValidationError < CodebaseIndex::Error; end
+
+    # Validates SQL strings for read-only safety.
+    #
+    # Allows only SELECT and WITH...SELECT statements. Rejects DML (INSERT,
+    # UPDATE, DELETE), DDL (CREATE, DROP, ALTER, TRUNCATE), and administrative
+    # commands (GRANT, REVOKE). Also rejects multiple statements (semicolons).
+    #
+    # Uses pattern-based validation, not full SQL parsing.
+    #
+    # @example
+    #   validator = SqlValidator.new
+    #   validator.validate!('SELECT * FROM users')         # => true
+    #   validator.validate!('DELETE FROM users')            # => raises SqlValidationError
+    #   validator.valid?('SELECT 1')                       # => true
+    #
+    class SqlValidator
+      # Forbidden statement prefixes (case-insensitive).
+      FORBIDDEN_KEYWORDS = %w[
+        INSERT UPDATE DELETE DROP ALTER TRUNCATE CREATE GRANT REVOKE
+      ].freeze
+
+      # Keywords that are forbidden anywhere in the SQL (not just at start).
+      BODY_FORBIDDEN_KEYWORDS = %w[UNION INTO COPY].freeze
+
+      # Dangerous functions that can be used for DoS or file access.
+      DANGEROUS_FUNCTIONS = %w[
+        pg_sleep lo_import lo_export pg_read_file pg_write_file
+        load_file sleep benchmark
+      ].freeze
+
+      # Allowed statement prefixes (case-insensitive).
+      ALLOWED_PREFIXES = /\A\s*(SELECT|WITH|EXPLAIN)\b/i
+
+      # @return [true]
+      # @raise [SqlValidationError] if the SQL is not a safe read-only statement
+      def validate!(sql) # rubocop:disable Naming/PredicateMethod
+        raise SqlValidationError, 'SQL is empty' if sql.nil? || sql.strip.empty?
+
+        normalized = sql.strip
+
+        # Reject multiple statements (semicolons not inside string literals)
+        if contains_multiple_statements?(normalized)
+          raise SqlValidationError, 'Rejected: multiple statements are not allowed'
+        end
+
+        # Check for forbidden keywords at statement start
+        check_forbidden_keywords!(normalized)
+
+        # Check for writable CTEs (before body keywords to give better error messages)
+        check_writable_ctes!(normalized)
+
+        # Check for forbidden keywords anywhere in the SQL body
+        check_body_forbidden_keywords!(normalized)
+
+        # Check for dangerous functions
+        check_dangerous_functions!(normalized)
+
+        # After stripping comments, check again for forbidden keywords that might have been hidden
+        check_forbidden_keywords_in_body!(normalized)
+
+        # Must start with an allowed prefix
+        unless normalized.match?(ALLOWED_PREFIXES)
+          raise SqlValidationError, 'Rejected: SQL must start with SELECT, WITH, or EXPLAIN'
+        end
+
+        true
+      end
+
+      # Check if SQL is valid without raising.
+      #
+      # @param sql [String] SQL string to validate
+      # @return [Boolean]
+      def valid?(sql)
+        validate!(sql)
+        true
+      rescue SqlValidationError
+        false
+      end
+
+      private
+
+      # Check if the SQL contains multiple statements separated by semicolons.
+      # Strips SQL comments and string literals before checking.
+      #
+      # @param sql [String]
+      # @return [Boolean]
+      def contains_multiple_statements?(sql)
+        # Strip SQL comments before checking
+        stripped = sql.gsub(/--[^\n]*/, '') # line comments
+        stripped = stripped.gsub(%r{/\*.*?\*/}m, '') # block comments
+        # Strip single-quoted strings to avoid false positives
+        stripped = stripped.gsub(/'[^']*'/, '')
+        stripped.include?(';')
+      end
+
+      # Check if the SQL starts with a forbidden keyword.
+      #
+      # @param sql [String]
+      # @raise [SqlValidationError] if a forbidden keyword is found
+      def check_forbidden_keywords!(sql)
+        FORBIDDEN_KEYWORDS.each do |keyword|
+          if sql.match?(/\A\s*#{keyword}\b/i)
+            raise SqlValidationError, "Rejected: #{keyword} statements are not allowed"
+          end
+        end
+      end
+
+      # Check if the SQL contains forbidden keywords anywhere in the body.
+      #
+      # @param sql [String]
+      # @raise [SqlValidationError] if a forbidden keyword is found
+      def check_body_forbidden_keywords!(sql)
+        BODY_FORBIDDEN_KEYWORDS.each do |keyword|
+          raise SqlValidationError, "Rejected: #{keyword} is not allowed" if sql.match?(/\b#{keyword}\b/i)
+        end
+      end
+
+      # Check if the SQL contains writable CTEs (WITH...DELETE/UPDATE/INSERT).
+      #
+      # @param sql [String]
+      # @raise [SqlValidationError] if a writable CTE is found
+      def check_writable_ctes!(sql)
+        return unless sql.match?(/WITH\s+\w+\s+AS\s*\(\s*(DELETE|UPDATE|INSERT)\b/i)
+
+        raise SqlValidationError, 'Rejected: writable CTEs are not allowed'
+      end
+
+      # Check if the SQL calls dangerous functions.
+      #
+      # @param sql [String]
+      # @raise [SqlValidationError] if a dangerous function is found
+      def check_dangerous_functions!(sql)
+        DANGEROUS_FUNCTIONS.each do |func|
+          if sql.match?(/\b#{func}\s*\(/i)
+            raise SqlValidationError, "Rejected: dangerous function #{func} is not allowed"
+          end
+        end
+      end
+
+      # Check if the SQL contains forbidden keywords anywhere in the body after stripping comments.
+      # This catches comment-hidden injections like "SELECT 1 --;\nDELETE FROM users".
+      #
+      # @param sql [String]
+      # @raise [SqlValidationError] if a forbidden keyword is found
+      def check_forbidden_keywords_in_body!(sql)
+        # Strip comments to reveal hidden statements
+        stripped = sql.gsub(/--[^\n]*/, '') # line comments
+        stripped = stripped.gsub(%r{/\*.*?\*/}m, '') # block comments
+
+        # Check if any forbidden keyword appears anywhere (not just at start)
+        FORBIDDEN_KEYWORDS.each do |keyword|
+          # Look for keyword as a whole word anywhere in the stripped SQL
+          next unless stripped.match?(/\b#{keyword}\b/i)
+
+          # Make sure it's not at the very start (already checked)
+          unless stripped.match?(/\A\s*#{keyword}\b/i)
+            raise SqlValidationError,
+                  "Rejected: #{keyword} statements are not allowed (found in SQL body)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/codebase_index/console/tools/tier1.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Console
+    module Tools
+      # Tier 1: MVP read-only tools for querying live Rails data.
+      #
+      # Each method builds a bridge request hash from validated parameters.
+      # The bridge executes the query against the Rails database.
+      #
+      module Tier1
+        module_function
+
+        # Count records matching scope conditions.
+        #
+        # @param model [String] Model name
+        # @param scope [Hash, nil] Filter conditions
+        # @return [Hash] Bridge request
+        def console_count(model:, scope: nil)
+          { tool: 'count', params: { model: model, scope: scope }.compact }
+        end
+
+        # Random sample of records.
+        #
+        # @param model [String] Model name
+        # @param scope [Hash, nil] Filter conditions
+        # @param limit [Integer] Max records (default: 5, max: 25)
+        # @param columns [Array<String>, nil] Columns to include
+        # @return [Hash] Bridge request
+        def console_sample(model:, scope: nil, limit: 5, columns: nil)
+          limit = [limit, 25].min
+          { tool: 'sample', params: { model: model, scope: scope, limit: limit, columns: columns }.compact }
+        end
+
+        # Find a single record by primary key or unique column.
+        #
+        # @param model [String] Model name
+        # @param id [Integer, nil] Primary key value
+        # @param by [Hash, nil] Unique column lookup (e.g., { email: "x@y.com" })
+        # @param columns [Array<String>, nil] Columns to include
+        # @return [Hash] Bridge request
+        def console_find(model:, id: nil, by: nil, columns: nil)
+          { tool: 'find', params: { model: model, id: id, by: by, columns: columns }.compact }
+        end
+
+        # Extract column values.
+        #
+        # @param model [String] Model name
+        # @param columns [Array<String>] Column names to pluck
+        # @param scope [Hash, nil] Filter conditions
+        # @param limit [Integer] Max records (default: 100, max: 1000)
+        # @param distinct [Boolean] Return unique values only
+        # @return [Hash] Bridge request
+        def console_pluck(model:, columns:, scope: nil, limit: 100, distinct: false)
+          limit = [limit, 1000].min
+          { tool: 'pluck', params: { model: model, columns: columns, scope: scope,
+                                     limit: limit, distinct: distinct }.compact }
+        end
+
+        # Run aggregate function on a column.
+        #
+        # @param model [String] Model name
+        # @param function [String] One of: sum, avg, minimum, maximum
+        # @param column [String] Column to aggregate
+        # @param scope [Hash, nil] Filter conditions
+        # @return [Hash] Bridge request
+        def console_aggregate(model:, function:, column:, scope: nil)
+          { tool: 'aggregate', params: { model: model, function: function, column: column, scope: scope }.compact }
+        end
+
+        # Count associated records.
+        #
+        # @param model [String] Model name
+        # @param id [Integer] Record primary key
+        # @param association [String] Association name
+        # @param scope [Hash, nil] Filter on the association
+        # @return [Hash] Bridge request
+        def console_association_count(model:, id:, association:, scope: nil)
+          { tool: 'association_count',
+            params: { model: model, id: id, association: association, scope: scope }.compact }
+        end
+
+        # Get database schema for a model.
+        #
+        # @param model [String] Model name
+        # @param include_indexes [Boolean] Include index information
+        # @return [Hash] Bridge request
+        def console_schema(model:, include_indexes: false)
+          { tool: 'schema', params: { model: model, include_indexes: include_indexes } }
+        end
+
+        # Recently created/updated records.
+        #
+        # @param model [String] Model name
+        # @param order_by [String] Column to sort by (default: created_at)
+        # @param direction [String] Sort direction (default: desc)
+        # @param limit [Integer] Max records (default: 10, max: 50)
+        # @param scope [Hash, nil] Filter conditions
+        # @param columns [Array<String>, nil] Columns to include
+        # @return [Hash] Bridge request
+        # rubocop:disable Metrics/ParameterLists
+        def console_recent(model:, order_by: 'created_at', direction: 'desc', limit: 10, scope: nil, columns: nil)
+          limit = [limit, 50].min
+          { tool: 'recent', params: { model: model, order_by: order_by, direction: direction,
+                                      limit: limit, scope: scope, columns: columns }.compact }
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # System health check.
+        #
+        # @return [Hash] Bridge request
+        def console_status
+          { tool: 'status', params: {} }
+        end
+      end
+    end
+  end
+end

data/lib/codebase_index/console/tools/tier2.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Console
+    module Tools
+      # Tier 2: Domain-aware tools for querying live Rails data.
+      #
+      # These tools build on Tier 1 primitives to provide higher-level
+      # domain operations: model diagnostics, data snapshots, validation,
+      # settings management, policy checks, and decorator invocation.
+      #
+      # Each method builds a bridge request hash from validated parameters.
+      # The bridge executes the operation against the Rails environment.
+      #
+      module Tier2
+        module_function
+
+        # Diagnose a model by composing multiple queries: count, recent records, and aggregates.
+        #
+        # @param model [String] Model name
+        # @param scope [Hash, nil] Filter conditions
+        # @param sample_size [Integer] Number of sample records (default: 5, max: 25)
+        # @return [Hash] Bridge request
+        def console_diagnose_model(model:, scope: nil, sample_size: 5)
+          sample_size = [sample_size, 25].min
+          { tool: 'diagnose_model', params: { model: model, scope: scope, sample_size: sample_size }.compact }
+        end
+
+        # Snapshot a record with its associations for debugging.
+        #
+        # @param model [String] Model name
+        # @param id [Integer] Record primary key
+        # @param associations [Array<String>, nil] Association names to include
+        # @param depth [Integer] Association traversal depth (default: 1, max: 3)
+        # @return [Hash] Bridge request
+        def console_data_snapshot(model:, id:, associations: nil, depth: 1)
+          depth = [depth, 3].min
+          { tool: 'data_snapshot',
+            params: { model: model, id: id, associations: associations, depth: depth }.compact }
+        end
+
+        # Run validations on an existing record, optionally with changed attributes.
+        #
+        # @param model [String] Model name
+        # @param id [Integer] Record primary key
+        # @param attributes [Hash, nil] Attributes to set before validating
+        # @return [Hash] Bridge request
+        def console_validate_record(model:, id:, attributes: nil)
+          { tool: 'validate_record', params: { model: model, id: id, attributes: attributes }.compact }
+        end
+
+        # Check a configuration setting value.
+        #
+        # @param key [String] Setting key
+        # @param namespace [String, nil] Setting namespace
+        # @return [Hash] Bridge request
+        def console_check_setting(key:, namespace: nil)
+          { tool: 'check_setting', params: { key: key, namespace: namespace }.compact }
+        end
+
+        # Update a configuration setting (requires human confirmation).
+        #
+        # @param key [String] Setting key
+        # @param value [Object] New value
+        # @param namespace [String, nil] Setting namespace
+        # @return [Hash] Bridge request with requires_confirmation flag
+        def console_update_setting(key:, value:, namespace: nil)
+          { tool: 'update_setting',
+            params: { key: key, value: value, namespace: namespace }.compact,
+            requires_confirmation: true }
+        end
+
+        # Check authorization policy for a record and user.
+        #
+        # @param model [String] Model name
+        # @param id [Integer] Record primary key
+        # @param user_id [Integer] User to check authorization for
+        # @param action [String] Policy action (e.g., "update", "destroy")
+        # @return [Hash] Bridge request
+        def console_check_policy(model:, id:, user_id:, action:)
+          { tool: 'check_policy',
+            params: { model: model, id: id, user_id: user_id, action: action } }
+        end
+
+        # Validate attributes against a model without persisting.
+        #
+        # @param model [String] Model name
+        # @param attributes [Hash] Attributes to validate
+        # @param context [String, nil] Validation context (e.g., "create", "update")
+        # @return [Hash] Bridge request
+        def console_validate_with(model:, attributes:, context: nil)
+          { tool: 'validate_with', params: { model: model, attributes: attributes, context: context }.compact }
+        end
+
+        # Check feature eligibility for a record.
+        #
+        # @param model [String] Model name
+        # @param id [Integer] Record primary key
+        # @param feature [String] Feature name to check
+        # @return [Hash] Bridge request
+        def console_check_eligibility(model:, id:, feature:)
+          { tool: 'check_eligibility', params: { model: model, id: id, feature: feature } }
+        end
+
+        # Invoke a decorator on a record and return computed attributes.
+        #
+        # @param model [String] Model name
+        # @param id [Integer] Record primary key
+        # @param methods [Array<String>, nil] Specific decorator methods to call
+        # @return [Hash] Bridge request
+        def console_decorate(model:, id:, methods: nil)
+          { tool: 'decorate', params: { model: model, id: id, methods: methods }.compact }
+        end
+      end
+    end
+  end
+end

data/lib/codebase_index/console/tools/tier3.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Console
+    module Tools
+      # Tier 3: Analytics tools for monitoring live Rails application state.
+      #
+      # Provides request performance metrics, job queue monitoring,
+      # cache statistics, and ActionCable channel status. Job-related
+      # tools delegate to backend-specific adapters (Sidekiq, Solid Queue, GoodJob).
+      #
+      # Each method builds a bridge request hash from validated parameters.
+      # The bridge executes the query against the Rails environment.
+      #
+      module Tier3
+        module_function
+
+        # List slowest endpoints by response time.
+        #
+        # @param limit [Integer] Max endpoints to return (default: 10, max: 100)
+        # @param period [String] Time period (default: "1h")
+        # @return [Hash] Bridge request
+        def console_slow_endpoints(limit: 10, period: '1h')
+          limit = [limit, 100].min
+          { tool: 'slow_endpoints', params: { limit: limit, period: period } }
+        end
+
+        # Get error rates by controller or overall.
+        #
+        # @param period [String] Time period (default: "1h")
+        # @param controller [String, nil] Filter by controller name
+        # @return [Hash] Bridge request
+        def console_error_rates(period: '1h', controller: nil)
+          { tool: 'error_rates', params: { period: period, controller: controller }.compact }
+        end
+
+        # Get request throughput over time.
+        #
+        # @param period [String] Time period (default: "1h")
+        # @param interval [String] Aggregation interval (default: "5m")
+        # @return [Hash] Bridge request
+        def console_throughput(period: '1h', interval: '5m')
+          { tool: 'throughput', params: { period: period, interval: interval } }
+        end
+
+        # Get job queue statistics.
+        #
+        # @param queue [String, nil] Filter by queue name
+        # @return [Hash] Bridge request
+        def console_job_queues(queue: nil)
+          { tool: 'job_queues', params: { queue: queue }.compact }
+        end
+
+        # List recent job failures.
+        #
+        # @param limit [Integer] Max failures to return (default: 10, max: 100)
+        # @param queue [String, nil] Filter by queue name
+        # @return [Hash] Bridge request
+        def console_job_failures(limit: 10, queue: nil)
+          limit = [limit, 100].min
+          { tool: 'job_failures', params: { limit: limit, queue: queue }.compact }
+        end
+
+        # Find a job by ID, optionally retry it (requires confirmation).
+        #
+        # @param job_id [String] Job identifier
+        # @param retry_job [Boolean, nil] Whether to retry the job
+        # @return [Hash] Bridge request, with requires_confirmation if retry requested
+        def console_job_find(job_id:, retry_job: nil)
+          result = { tool: 'job_find', params: { job_id: job_id, retry: retry_job }.compact }
+          result[:requires_confirmation] = true if retry_job
+          result
+        end
+
+        # List scheduled/upcoming jobs.
+        #
+        # @param limit [Integer] Max jobs to return (default: 20, max: 100)
+        # @return [Hash] Bridge request
+        def console_job_schedule(limit: 20)
+          limit = [limit, 100].min
+          { tool: 'job_schedule', params: { limit: limit } }
+        end
+
+        # Get Redis server information.
+        #
+        # @param section [String, nil] Redis INFO section filter (e.g., "memory", "stats")
+        # @return [Hash] Bridge request
+        def console_redis_info(section: nil)
+          { tool: 'redis_info', params: { section: section }.compact }
+        end
+
+        # Get cache store statistics.
+        #
+        # @param namespace [String, nil] Cache namespace filter
+        # @return [Hash] Bridge request
+        def console_cache_stats(namespace: nil)
+          { tool: 'cache_stats', params: { namespace: namespace }.compact }
+        end
+
+        # Get ActionCable channel status.
+        #
+        # @param channel [String, nil] Filter by channel name
+        # @return [Hash] Bridge request
+        def console_channel_status(channel: nil)
+          { tool: 'channel_status', params: { channel: channel }.compact }
+        end
+      end
+    end
+  end
+end

data/lib/codebase_index/console/tools/tier4.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Console
+    module Tools
+      # Tier 4: Guarded tools requiring confirmation or SQL validation.
+      #
+      # - `console_eval` — Arbitrary Ruby execution with confirmation + timeout
+      # - `console_sql` — Read-only SQL (validated by SqlValidator)
+      # - `console_query` — Enhanced query builder with joins/grouping
+      #
+      # Each method builds a bridge request hash. The bridge executes against
+      # the live Rails environment.
+      #
+      module Tier4
+        MAX_EVAL_TIMEOUT = 30
+        MIN_EVAL_TIMEOUT = 1
+        DEFAULT_EVAL_TIMEOUT = 10
+        MAX_SQL_LIMIT = 10_000
+        MAX_QUERY_LIMIT = 10_000
+
+        module_function
+
+        # Arbitrary Ruby evaluation with timeout.
+        #
+        # @param code [String] Ruby code to execute
+        # @param timeout [Integer] Execution timeout in seconds (default 10, max 30)
+        # @return [Hash] Bridge request
+        def console_eval(code:, timeout: DEFAULT_EVAL_TIMEOUT)
+          timeout = timeout.clamp(MIN_EVAL_TIMEOUT, MAX_EVAL_TIMEOUT)
+          { tool: 'eval', params: { code: code, timeout: timeout } }
+        end
+
+        # Read-only SQL execution with validation.
+        #
+        # @param sql [String] SQL query (must be SELECT or WITH...SELECT)
+        # @param validator [SqlValidator] SQL validator instance
+        # @param limit [Integer, nil] Optional row limit (max 10000)
+        # @return [Hash] Bridge request
+        # @raise [SqlValidationError] if SQL is not read-only
+        def console_sql(sql:, validator:, limit: nil)
+          validator.validate!(sql)
+          limit = [limit, MAX_SQL_LIMIT].min if limit
+          { tool: 'sql', params: { sql: sql, limit: limit }.compact }
+        end
+
+        # Enhanced query builder with joins and grouping.
+        #
+        # @param model [String] Model name
+        # @param select [Array<String>] Columns to select
+        # @param joins [Array<String>, nil] Associations to join
+        # @param group_by [Array<String>, nil] Columns to group by
+        # @param having [String, nil] HAVING clause
+        # @param order [Hash, nil] Order specification (e.g., { id: :desc })
+        # @param scope [Hash, nil] Filter conditions
+        # @param limit [Integer, nil] Row limit (max 10000)
+        # @return [Hash] Bridge request
+        # rubocop:disable Metrics/ParameterLists
+        def console_query(model:, select:, joins: nil, group_by: nil, having: nil, order: nil, scope: nil, limit: nil)
+          limit = [limit, MAX_QUERY_LIMIT].min if limit
+          {
+            tool: 'query',
+            params: {
+              model: model,
+              select: select,
+              joins: joins,
+              group_by: group_by,
+              having: having,
+              order: order,
+              scope: scope,
+              limit: limit
+            }.compact
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+      end
+    end
+  end
+end