woods 1.2.0 → 1.3.0

data/lib/woods/console/server.rb

@@ -12,13 +12,21 @@ require_relative 'sql_validator'
 require_relative 'audit_logger'
 require_relative 'confirmation'
 require_relative 'console_response_renderer'
+require_relative 'credential_scanner'
+require_relative 'eval_guard'
+require_relative 'table_gate'
+require_relative 'redactor'
+require_relative 'response_context'
+require_relative 'dispatch_pipeline'
+require_relative 'tool_specs'
 
 module Woods
   module Console
     # Console MCP Server — queries live Rails application state.
     #
     # Communicates with a bridge process running inside the Rails environment
-    # via JSON-lines over stdio. Exposes Tier 1-4 tools (read-only, domain, analytics, guarded) through MCP.
+    # via JSON-lines over stdio. Exposes 31 tools across 4 tiers
+    # (9 read-only / 9 domain-aware / 10 analytics / 3 guarded) through MCP.
     #
     # @example
     #   server = Woods::Console::Server.build(config: config)
@@ -26,25 +34,126 @@ module Woods
     #   transport.open
     #
     module Server # rubocop:disable Metrics/ModuleLength
-      TIER1_TOOLS = %w[count sample find pluck aggregate association_count schema recent status].freeze
-      TIER2_TOOLS = %w[diagnose_model data_snapshot validate_record check_setting update_setting
-                       check_policy validate_with check_eligibility decorate].freeze
-      TIER3_TOOLS = %w[slow_endpoints error_rates throughput job_queues job_failures job_find
-                       job_schedule redis_info cache_stats channel_status].freeze
-      TIER4_TOOLS = %w[eval sql query].freeze
-
       class << self # rubocop:disable Metrics/ClassLength
+        # Rebuild the boot-time credential index from fresh Rails credentials
+        # and hot-swap it into the active scanner without restarting the process.
+        #
+        # Host rotation jobs should call this immediately after `rails credentials:edit`
+        # changes are deployed. The swap is atomic on MRI (GVL) — in-flight scans see
+        # either the old or the new index, never a partial one.
+        #
+        # Returns nil when:
+        # - `console_credential_defense_enabled` is false
+        # - No server has been built yet in this process (`build` / `build_embedded`
+        #   have not been called)
+        #
+        # Existing callers of `build` / `build_embedded` are unaffected — this is an
+        # additive class method with no required arguments beyond `rails_app`.
+        #
+        # @param rails_app [#credentials] The Rails application to re-read.
+        #   Defaults to `Rails.application` when `Rails` is defined, otherwise
+        #   the caller must supply it explicitly.
+        # @return [CredentialIndex, nil] The newly built index, or nil when
+        #   the rebuild was skipped.
+        def rebuild_credential_index(rails_app: nil)
+          return nil unless credential_defense_enabled?
+          return nil unless @active_scanner
+
+          target_app = rails_app || default_rails_app
+          return nil unless target_app
+
+          new_index = CredentialIndex.build(rails_app: target_app)
+          @active_scanner.replace_index!(new_index)
+          new_index
+        end
+
+        # True when Woods is configured and credential defense is on.
+        def credential_defense_enabled?
+          config = Woods.configuration if Woods.respond_to?(:configuration)
+          config&.console_credential_defense_enabled ? true : false
+        end
+
+        # True when the caller has opted into the unsafe `console_eval`
+        # scaffolding via `WOODS_CONSOLE_UNSAFE_EVAL=true` or an explicit
+        # `config.console_unsafe_eval_enabled = true`. Explicit config wins
+        # over the env var in both directions.
+        #
+        # NOTE: returning true here does NOT enable eval execution. The
+        # execution path is deliberately unimplemented (backlog
+        # unsafe-eval-opt-in). This predicate only governs the boot-time
+        # banner and the production-environment refusal below.
+        #
+        # @return [Boolean]
+        def unsafe_eval_enabled?
+          config = Woods.configuration if Woods.respond_to?(:configuration)
+          explicit = config&.console_unsafe_eval_enabled
+          return explicit if [true, false].include?(explicit)
+
+          ENV['WOODS_CONSOLE_UNSAFE_EVAL'] == 'true'
+        end
+
+        # Enforce the `console_eval` opt-in safety contract at boot.
+        #
+        # When `WOODS_CONSOLE_UNSAFE_EVAL` is on:
+        # - refuse outright in `Rails.env.production?` (non-negotiable),
+        # - otherwise emit a LOUD stderr banner so operators know the flag
+        #   is live even though eval remains unimplemented.
+        #
+        # Safe when Rails is not loaded (specs, non-Rails hosts).
+        #
+        # @return [void]
+        # @raise [Woods::ConfigurationError] when the flag is on in production.
+        def enforce_unsafe_eval_contract!
+          return unless unsafe_eval_enabled?
+
+          if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.respond_to?(:production?) &&
+             Rails.env.production?
+            raise Woods::ConfigurationError,
+                  'WOODS_CONSOLE_UNSAFE_EVAL is set but Rails.env.production? is true. ' \
+                  'console_eval cannot be opted into in production. Unset the flag or ' \
+                  'restart in a non-production environment.'
+          end
+
+          warn unsafe_eval_banner
+        end
+
+        # Resolves `Rails.application` when available, else nil.
+        def default_rails_app
+          return nil unless defined?(Rails) && Rails.respond_to?(:application)
+
+          Rails.application
+        end
+
         # Build a configured MCP::Server with console tools using the bridge protocol.
         #
+        # ⚠ Layer 1 limitation in bridge mode:
+        # The server side of the bridge has no access to the remote app's
+        # `ActiveRecord::Base.descendants`, so model_tables and model_reflections
+        # are empty. `TableGate#check_sql!` still fires against the raw SQL
+        # argument of `console_sql`, but `check_model!`, `check_joins!`, and
+        # `check_association!` are effectively no-ops for tools that receive a
+        # model name rather than SQL (find, sample, count, etc.). A bridge-mode
+        # deployment therefore relies on Layer 2 (credential scanning) + Layer 3
+        # (column/EAV redaction) + Layer 4 (SqlValidator + SafeContext rollback)
+        # for non-SQL tool calls. If you need full Layer 1 coverage, use
+        # `build_embedded` (the stdio entry point `exe/woods-console` does this).
+        #
+        # See docs/CONSOLE_MCP_SETUP.md "Bridge vs. embedded defense coverage"
+        # for the full matrix.
+        #
         # @param config [Hash] Configuration hash (from YAML or env)
         # @return [MCP::Server] Configured server ready for transport
         def build(config:)
           connection_config = config['console'] || config
           conn_mgr = ConnectionManager.new(config: connection_config)
           redacted_columns = Array(config['redacted_columns'] || connection_config['redacted_columns'])
-          safe_ctx = redacted_columns.any? ? SafeContext.new(connection: nil, redacted_columns: redacted_columns) : nil
+          redacted_key_values = Array(
+            config['redacted_key_values'] || connection_config['redacted_key_values']
+          )
+          safe_ctx = build_safe_context(redacted_columns, redacted_key_values)
+          ctx = build_response_context(safe_ctx: safe_ctx, model_tables: {}, model_reflections: {})
 
-          build_server(conn_mgr, safe_ctx)
+          build_server(conn_mgr, ctx)
         end
 
         # Build a configured MCP::Server using embedded ActiveRecord execution.
@@ -55,557 +164,379 @@ module Woods
         # @param model_validator [ModelValidator] Validates model/column names
         # @param safe_context [SafeContext] Wraps queries in rolled-back transactions
         # @param redacted_columns [Array<String>] Column names to redact from output
+        # @param redacted_key_values [Array<Hash>] EAV redaction patterns. Each pattern:
+        #   {key_column:, value_column:, sensitive_keys: []}. See SafeContext for semantics.
         # @param connection [Object, nil] Database connection for adapter detection
         # @param read_tools_enabled [Boolean] Enable sql/query tools in embedded mode (default: false)
+        # @param unsafe_eval_confirmation [Confirmation, nil] Approval callback for
+        #   `console_eval`. Required when the opt-in is on; the server refuses to
+        #   boot without it. Ignored when the opt-in is off.
+        # @param unsafe_eval_audit_log_path [String, Pathname, nil] JSONL audit log
+        #   path for `console_eval`. Required when the opt-in is on.
         # @return [MCP::Server] Configured server ready for transport
-        def build_embedded(model_validator:, safe_context:, redacted_columns: [], connection: nil,
-                           read_tools_enabled: false)
+        def build_embedded(model_validator:, safe_context:, redacted_columns: [], # rubocop:disable Metrics/ParameterLists
+                           redacted_key_values: [], connection: nil,
+                           read_tools_enabled: false, model_tables: {},
+                           model_reflections: {},
+                           unsafe_eval_confirmation: nil,
+                           unsafe_eval_audit_log_path: nil)
           require_relative 'embedded_executor'
+          enforce_unsafe_eval_contract!
+
+          safe_ctx = build_safe_context(redacted_columns, redacted_key_values)
+          ctx = build_response_context(safe_ctx: safe_ctx, model_tables: model_tables,
+                                       model_reflections: model_reflections)
 
+          eval_wiring = build_unsafe_eval_wiring(
+            confirmation: unsafe_eval_confirmation,
+            audit_log_path: unsafe_eval_audit_log_path
+          )
+
+          # Wire the same TableGate into the executor so sql/query are blocked
+          # PRE-execution against console_blocked_tables (previously TableGate
+          # was only consulted on the render path, leaving the defense inert
+          # for the sql and query tools).
+          table_gate = ctx&.table_gate
           executor = EmbeddedExecutor.new(
             model_validator: model_validator, safe_context: safe_context,
-            connection: connection, read_tools_enabled: read_tools_enabled
+            connection: connection, read_tools_enabled: read_tools_enabled,
+            table_gate: table_gate,
+            eval_guard: eval_wiring[:eval_guard],
+            confirmation: eval_wiring[:confirmation],
+            audit_logger: eval_wiring[:audit_logger],
+            unsafe_eval_enabled: eval_wiring[:unsafe_eval_enabled]
           )
-          redact_ctx = if redacted_columns.any?
-                         SafeContext.new(connection: nil,
-                                         redacted_columns: redacted_columns)
-                       end
 
-          build_server(executor, redact_ctx)
+          build_server(executor, ctx)
+        end
+
+        # Resolve the three-collaborator eval wiring for the current config.
+        #
+        # When `unsafe_eval_enabled?` is false (default), returns nil for all
+        # three collaborators — the executor keeps its hard refusal and
+        # EvalGuard is never reached.
+        #
+        # When it's true, BOTH a {Confirmation} and an audit-log path MUST be
+        # provided (via kwargs or config); otherwise we raise so a
+        # misconfigured host fails at boot instead of silently running Ruby
+        # without approval or audit. See backlog B-053.
+        #
+        # @param confirmation [Confirmation, nil] Explicit kwarg wins over
+        #   `config.console_unsafe_eval_confirmation`.
+        # @param audit_log_path [String, Pathname, nil] Explicit kwarg wins
+        #   over `config.console_unsafe_eval_audit_log_path`.
+        # @return [Hash] { eval_guard:, confirmation:, audit_logger:, unsafe_eval_enabled: }
+        # @raise [Woods::ConfigurationError] when opt-in is on but either
+        #   collaborator is missing.
+        def build_unsafe_eval_wiring(confirmation:, audit_log_path:)
+          return empty_unsafe_eval_wiring unless unsafe_eval_enabled?
+
+          config = Woods.configuration if Woods.respond_to?(:configuration)
+          confirmation ||= config&.console_unsafe_eval_confirmation
+          audit_log_path ||= config&.console_unsafe_eval_audit_log_path
+          require_unsafe_eval_collaborators!(confirmation, audit_log_path)
+
+          {
+            eval_guard: EvalGuard.new,
+            confirmation: confirmation,
+            audit_logger: AuditLogger.new(path: audit_log_path.to_s),
+            unsafe_eval_enabled: true
+          }
+        end
+
+        def empty_unsafe_eval_wiring
+          { eval_guard: nil, confirmation: nil, audit_logger: nil, unsafe_eval_enabled: false }
+        end
+
+        def require_unsafe_eval_collaborators!(confirmation, audit_log_path)
+          if confirmation.nil?
+            raise Woods::ConfigurationError,
+                  'WOODS_CONSOLE_UNSAFE_EVAL is set but no Confirmation was provided. ' \
+                  'Pass `unsafe_eval_confirmation:` to Server.build_embedded / RackMiddleware ' \
+                  'or set `config.console_unsafe_eval_confirmation`. Fail-closed by design — ' \
+                  'see backlog B-053 / docs/CONSOLE_MCP_SETUP.md.'
+          end
+          return unless audit_log_path.nil? || audit_log_path.to_s.strip.empty?
+
+          raise Woods::ConfigurationError,
+                'WOODS_CONSOLE_UNSAFE_EVAL is set but no audit-log path was provided. ' \
+                'Pass `unsafe_eval_audit_log_path:` to Server.build_embedded / RackMiddleware ' \
+                'or set `config.console_unsafe_eval_audit_log_path`. Every console_eval run ' \
+                'must be audited.'
+        end
+
+        # Register all tool specs for a given tier on the server.
+        #
+        # @param server [MCP::Server] The MCP server instance
+        # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Request executor
+        # @param ctx [ResponseContext, nil] Optional context bundling response-safety layers
+        # @param tier [Integer] Tier number (1-4)
+        # @param renderer [ConsoleResponseRenderer, nil] Optional response renderer
+        # @return [void]
+        def register_tier_tools(server, conn_mgr, ctx, tier:, renderer: nil)
+          TOOL_SPECS.select { |spec| spec.tier == tier }.each do |spec|
+            register(spec, server, conn_mgr, ctx, renderer: renderer)
+          end
         end
 
         # Register Tier 1 read-only tools on the server.
         #
         # @param server [MCP::Server] The MCP server instance
         # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Request executor
-        # @param safe_ctx [SafeContext, nil] Optional context for column redaction
+        # @param ctx [ResponseContext, nil] Optional context for column redaction
         # @return [void]
-        def register_tier1_tools(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          TIER1_TOOLS.each { |tool| send(:"define_#{tool}", server, conn_mgr, safe_ctx, renderer: renderer) }
+        def register_tier1_tools(server, conn_mgr, ctx = nil, renderer: nil)
+          register_tier_tools(server, conn_mgr, ctx, tier: 1, renderer: renderer)
         end
 
         # Register Tier 2 domain-aware tools on the server.
         #
         # @param server [MCP::Server] The MCP server instance
         # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Request executor
-        # @param safe_ctx [SafeContext, nil] Optional context for column redaction
+        # @param ctx [ResponseContext, nil] Optional context for column redaction
         # @return [void]
-        def register_tier2_tools(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          TIER2_TOOLS.each { |tool| send(:"define_#{tool}", server, conn_mgr, safe_ctx, renderer: renderer) }
+        def register_tier2_tools(server, conn_mgr, ctx = nil, renderer: nil)
+          register_tier_tools(server, conn_mgr, ctx, tier: 2, renderer: renderer)
         end
 
         # Register Tier 3 analytics tools on the server.
         #
         # @param server [MCP::Server] The MCP server instance
         # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Request executor
-        # @param safe_ctx [SafeContext, nil] Optional context for column redaction
+        # @param ctx [ResponseContext, nil] Optional context for column redaction
         # @return [void]
-        def register_tier3_tools(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          TIER3_TOOLS.each { |tool| send(:"define_#{tool}", server, conn_mgr, safe_ctx, renderer: renderer) }
+        def register_tier3_tools(server, conn_mgr, ctx = nil, renderer: nil)
+          register_tier_tools(server, conn_mgr, ctx, tier: 3, renderer: renderer)
         end
 
         # Register Tier 4 guarded tools on the server.
         #
         # @param server [MCP::Server] The MCP server instance
         # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Request executor
-        # @param safe_ctx [SafeContext, nil] Optional context for column redaction
+        # @param ctx [ResponseContext, nil] Optional context for column redaction
         # @return [void]
-        def register_tier4_tools(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          TIER4_TOOLS.each { |tool| send(:"define_#{tool}", server, conn_mgr, safe_ctx, renderer: renderer) }
+        def register_tier4_tools(server, conn_mgr, ctx = nil, renderer: nil)
+          register_tier_tools(server, conn_mgr, ctx, tier: 4, renderer: renderer)
         end
 
         private
 
-        # Shared server construction used by both build() and build_embedded().
+        # Register a single ToolSpec on the MCP server.
         #
-        # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Any object with send_request(Hash) -> Hash
-        # @param safe_ctx [SafeContext, nil] Optional context for column redaction
-        # @return [MCP::Server]
-        def build_server(conn_mgr, safe_ctx)
-          server = ::MCP::Server.new(
-            name: 'woods-console',
-            version: defined?(Woods::VERSION) ? Woods::VERSION : '0.1.0'
+        # Hands every tool a dedicated {DispatchPipeline} that owns the full
+        # args → gate → bridge → redact → scan → respond flow. The
+        # `define_tool` block stays a one-liner that delegates to the pipeline.
+        #
+        # @param spec [ToolSpec] The tool specification
+        # @param server [MCP::Server] The MCP server instance
+        # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Request executor
+        # @param ctx [ResponseContext, nil] Response context (table gate, scanner, safe_ctx)
+        # @param renderer [ConsoleResponseRenderer, nil] Optional response renderer
+        # @return [void]
+        def register(spec, server, conn_mgr, ctx, renderer: nil)
+          pipeline = DispatchPipeline.new(
+            tool_name: spec.name,
+            handler: spec.handler,
+            integer_keys: integer_property_keys(spec.properties),
+            conn_mgr: conn_mgr,
+            ctx: ctx || NullResponseContext.instance,
+            renderer: renderer,
+            logger: structured_logger
           )
 
-          renderer = build_console_renderer
-
-          register_tier1_tools(server, conn_mgr, safe_ctx, renderer: renderer)
-          register_tier2_tools(server, conn_mgr, safe_ctx, renderer: renderer)
-          register_tier3_tools(server, conn_mgr, safe_ctx, renderer: renderer)
-          register_tier4_tools(server, conn_mgr, safe_ctx, renderer: renderer)
-          server
-        end
-
-        def respond(text)
-          ::MCP::Tool::Response.new([{ type: 'text', text: text }])
-        end
-
-        def send_to_bridge(conn_mgr, request, safe_ctx = nil, renderer: nil)
-          response = conn_mgr.send_request(request)
-          if response['ok']
-            result = response['result']
-            result = apply_redaction(result, safe_ctx) if safe_ctx
-            text = renderer ? renderer.render_default(result) : JSON.pretty_generate(result)
-            respond(text)
-          else
-            error_text = "#{response['error_type']}: #{response['error']}"
-            ::MCP::Tool::Response.new(
-              [{ type: 'text', text: error_text }],
-              error: error_text
-            )
-          end
-        rescue ConnectionError => e
-          ::MCP::Tool::Response.new([{ type: 'text', text: "Connection error: #{e.message}" }], error: e.message)
-        end
-
-        # Apply SafeContext column redaction to a result value.
-        #
-        # Handles Hash (single record) and Array<Hash> (multiple records).
-        # Non-Hash values are returned unchanged.
-        #
-        # @param result [Object] The result from the bridge
-        # @param safe_ctx [SafeContext] The context with redacted_columns configured
-        # @return [Object] Redacted result
-        def apply_redaction(result, safe_ctx)
-          case result
-          when Array
-            result.map { |item| item.is_a?(Hash) ? safe_ctx.redact(item) : item }
-          when Hash
-            safe_ctx.redact(result)
-          else
-            result
-          end
-        end
-
-        def build_console_renderer
-          format = if Woods.respond_to?(:configuration)
-                     Woods.configuration&.context_format || :markdown
-                   else
-                     :markdown
-                   end
-          format == :json ? JsonConsoleRenderer.new : ConsoleResponseRenderer.new
-        end
-
-        def define_count(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_count', 'Count records matching scope conditions',
-                              properties: { model: str_prop('Model name'), scope: obj_prop('Filter conditions') },
-                              required: ['model'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_count(model: args[:model], scope: args[:scope])
-          end
-        end
-
-        def define_sample(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_sample', 'Random sample of records',
-                              properties: {
-                                model: str_prop('Model name'), limit: int_prop('Max records (default 5, max 25)'),
-                                columns: arr_prop('Columns to include'), scope: obj_prop('Filter conditions')
-                              }, required: ['model'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_sample(
-              model: args[:model], scope: args[:scope], limit: args[:limit] || 5, columns: args[:columns]
-            )
-          end
-        end
-
-        def define_find(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_find',
-                              'Find a single record by primary key or unique column',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Primary key value'),
-                                by: obj_prop('Unique column lookup'),
-                                columns: arr_prop('Columns to include')
-                              }, required: ['model'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_find(model: args[:model], id: args[:id], by: args[:by], columns: args[:columns])
-          end
-        end
-
-        def define_pluck(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_pluck', 'Extract column values from records',
-                              properties: {
-                                model: str_prop('Model name'), columns: arr_prop('Column names to pluck'),
-                                scope: obj_prop('Filter conditions'),
-                                limit: int_prop('Max records (default 100, max 1000)'),
-                                distinct: bool_prop('Return unique values only')
-                              }, required: %w[model columns], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_pluck(
-              model: args[:model], columns: args[:columns], scope: args[:scope],
-              limit: args[:limit] || 100, distinct: args[:distinct] || false
-            )
-          end
-        end
-
-        def define_aggregate(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_aggregate',
-                              'Run aggregate function (sum/avg/min/max) on a column',
-                              properties: {
-                                model: str_prop('Model name'),
-                                function: str_prop('Aggregate function: sum, avg, minimum, maximum'),
-                                column: str_prop('Column to aggregate'), scope: obj_prop('Filter conditions')
-                              }, required: %w[model function column], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_aggregate(
-              model: args[:model], function: args[:function], column: args[:column], scope: args[:scope]
-            )
-          end
-        end
-
-        def define_association_count(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_association_count',
-                              'Count associated records for a specific record',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Record primary key'),
-                                association: str_prop('Association name'),
-                                scope: obj_prop('Filter on association')
-                              }, required: %w[model id association], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_association_count(
-              model: args[:model], id: args[:id], association: args[:association], scope: args[:scope]
-            )
+          server.define_tool(name: spec.name, description: spec.description,
+                             input_schema: spec_schema(spec)) do |server_context:, **args|
+            pipeline.call(args)
           end
         end
 
-        def define_schema(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_schema', 'Get database schema for a model',
-                              properties: {
-                                model: str_prop('Model name'),
-                                include_indexes: bool_prop('Include index information')
-                              }, required: ['model'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_schema(model: args[:model], include_indexes: args[:include_indexes] || false)
-          end
-        end
-
-        def define_recent(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_recent', 'Recently created/updated records',
-                              properties: {
-                                model: str_prop('Model name'),
-                                order_by: str_prop('Column to sort by (default: created_at)'),
-                                direction: str_prop('Sort direction: asc or desc (default: desc)'),
-                                limit: int_prop('Max records (default 10, max 50)'),
-                                scope: obj_prop('Filter conditions'), columns: arr_prop('Columns to include')
-                              }, required: ['model'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier1.console_recent(
-              model: args[:model], order_by: args[:order_by] || 'created_at',
-              direction: args[:direction] || 'desc', limit: args[:limit] || 10,
-              scope: args[:scope], columns: args[:columns]
-            )
-          end
-        end
-
-        def define_status(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_status',
-                              'System health check - list models and connection status',
-                              properties: {}, safe_ctx: safe_ctx, renderer: renderer) do |_args|
-            Tools::Tier1.console_status
-          end
-        end
-
-        # ── Tier 2 tool definitions ──────────────────────────────────────────
-
-        def define_diagnose_model(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_diagnose_model',
-                              'Diagnose a model: count, recent records, aggregates',
-                              properties: {
-                                model: str_prop('Model name'), scope: obj_prop('Filter conditions'),
-                                sample_size: int_prop('Sample records (default 5, max 25)')
-                              }, required: ['model'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_diagnose_model(
-              model: args[:model], scope: args[:scope], sample_size: args[:sample_size] || 5
-            )
-          end
-        end
-
-        def define_data_snapshot(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_data_snapshot',
-                              'Snapshot a record with associations for debugging',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Record primary key'),
-                                associations: arr_prop('Association names to include'),
-                                depth: int_prop('Association depth (default 1, max 3)')
-                              }, required: %w[model id], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_data_snapshot(
-              model: args[:model], id: args[:id],
-              associations: args[:associations], depth: args[:depth] || 1
-            )
-          end
-        end
-
-        def define_validate_record(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_validate_record',
-                              'Run validations on an existing record',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Record primary key'),
-                                attributes: obj_prop('Attributes to set before validating')
-                              }, required: %w[model id], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_validate_record(
-              model: args[:model], id: args[:id], attributes: args[:attributes]
-            )
-          end
-        end
-
-        def define_check_setting(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_check_setting',
-                              'Check a configuration setting value',
-                              properties: {
-                                key: str_prop('Setting key'), namespace: str_prop('Setting namespace')
-                              }, required: ['key'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_check_setting(key: args[:key], namespace: args[:namespace])
-          end
-        end
-
-        def define_update_setting(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_update_setting',
-                              'Update a configuration setting (requires confirmation)',
-                              properties: {
-                                key: str_prop('Setting key'), value: str_prop('New value'),
-                                namespace: str_prop('Setting namespace')
-                              }, required: %w[key value], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_update_setting(
-              key: args[:key], value: args[:value], namespace: args[:namespace]
-            )
-          end
-        end
-
-        def define_check_policy(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_check_policy',
-                              'Check authorization policy for a record and user',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Record primary key'),
-                                user_id: int_prop('User to check'), action: str_prop('Policy action')
-                              }, required: %w[model id user_id action],
-                              safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_check_policy(
-              model: args[:model], id: args[:id], user_id: args[:user_id], action: args[:action]
-            )
-          end
-        end
-
-        def define_validate_with(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_validate_with',
-                              'Validate attributes against a model without persisting',
-                              properties: {
-                                model: str_prop('Model name'), attributes: obj_prop('Attributes to validate'),
-                                context: str_prop('Validation context')
-                              }, required: %w[model attributes], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_validate_with(
-              model: args[:model], attributes: args[:attributes], context: args[:context]
-            )
-          end
-        end
-
-        def define_check_eligibility(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_check_eligibility',
-                              'Check feature eligibility for a record',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Record primary key'),
-                                feature: str_prop('Feature name')
-                              }, required: %w[model id feature], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_check_eligibility(
-              model: args[:model], id: args[:id], feature: args[:feature]
-            )
-          end
-        end
-
-        def define_decorate(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_decorate',
-                              'Invoke a decorator on a record and return computed attributes',
-                              properties: {
-                                model: str_prop('Model name'), id: int_prop('Record primary key'),
-                                methods: arr_prop('Decorator methods to call')
-                              }, required: %w[model id], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier2.console_decorate(model: args[:model], id: args[:id], methods: args[:methods])
-          end
-        end
-
-        # ── Tier 3 tool definitions ──────────────────────────────────────────
-
-        def define_slow_endpoints(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_slow_endpoints',
-                              'List slowest endpoints by response time',
-                              properties: {
-                                limit: int_prop('Max endpoints (default 10, max 100)'),
-                                period: str_prop('Time period (default: 1h)')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_slow_endpoints(limit: args[:limit] || 10, period: args[:period] || '1h')
-          end
+        # Build the JSON Schema object for a ToolSpec.
+        #
+        # @param spec [ToolSpec]
+        # @return [Hash]
+        def spec_schema(spec)
+          schema = { properties: spec.properties }
+          schema[:required] = spec.required if spec.required&.any?
+          schema
         end
 
-        def define_error_rates(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_error_rates',
-                              'Get error rates by controller or overall',
-                              properties: {
-                                period: str_prop('Time period (default: 1h)'),
-                                controller: str_prop('Filter by controller')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_error_rates(period: args[:period] || '1h', controller: args[:controller])
-          end
+        # Pre-compute property keys declared as integer in a schema.
+        #
+        # @param properties [Hash] Tool schema properties
+        # @return [Array<Symbol>]
+        def integer_property_keys(properties)
+          properties.select { |_k, v| v[:type] == 'integer' }.keys.map(&:to_sym)
         end
 
-        def define_throughput(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_throughput',
-                              'Get request throughput over time',
-                              properties: {
-                                period: str_prop('Time period (default: 1h)'),
-                                interval: str_prop('Aggregation interval (default: 5m)')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_throughput(
-              period: args[:period] || '1h', interval: args[:interval] || '5m'
-            )
-          end
+        # Build a SafeContext (Layer 3) from redaction settings, or nil when nothing is configured.
+        #
+        # @param redacted_columns [Array<String>]
+        # @param redacted_key_values [Array<Hash>]
+        # @return [SafeContext, nil]
+        def build_safe_context(redacted_columns, redacted_key_values)
+          return nil unless redacted_columns.any? || redacted_key_values.any?
+
+          SafeContext.new(
+            connection: nil,
+            redacted_columns: redacted_columns,
+            redacted_key_values: redacted_key_values
+          )
         end
 
-        def define_job_queues(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_job_queues',
-                              'Get job queue statistics',
-                              properties: {
-                                queue: str_prop('Filter by queue name')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_job_queues(queue: args[:queue])
-          end
-        end
+        # Bundle the three response-safety layers into a ResponseContext the
+        # server can thread through every tool. Returns nil when every layer is
+        # absent so callers can skip wiring.
+        #
+        # @param safe_ctx [SafeContext, nil] Layer 3 (column + EAV redaction)
+        # @param model_tables [Hash{String=>String}] Model => table registry for Layer 1
+        # @param model_reflections [Hash{String=>Hash{String=>String}}] Model => { association => table }
+        # @return [ResponseContext, nil]
+        def build_response_context(safe_ctx:, model_tables:, model_reflections: {})
+          config = Woods.configuration if Woods.respond_to?(:configuration)
+          blocked = Array(config&.console_blocked_tables)
+          table_gate = if blocked.any?
+                         TableGate.new(blocked_tables: blocked, model_tables: model_tables,
+                                       model_reflections: model_reflections)
+                       end
 
-        def define_job_failures(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_job_failures',
-                              'List recent job failures',
-                              properties: {
-                                limit: int_prop('Max failures (default 10, max 100)'),
-                                queue: str_prop('Filter by queue name')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_job_failures(limit: args[:limit] || 10, queue: args[:queue])
-          end
-        end
+          secret_index = build_credential_index(config)
+          disabled_patterns = Array(config&.console_disabled_scanner_patterns)
+          scanner = if disabled_patterns.include?(:all)
+                      nil
+                    else
+                      CredentialScanner.new(
+                        disabled_patterns: disabled_patterns,
+                        secret_index: secret_index
+                      )
+                    end
+          @active_scanner = scanner
+
+          ResponseContext.build(safe_ctx: safe_ctx, table_gate: table_gate, credential_scanner: scanner)
+        end
+
+        # Build the boot-time credential index from Rails.application's encrypted
+        # credentials. Returns nil when credential defense is disabled or when no
+        # Rails application is reachable (specs, non-Rails hosts) — the scanner
+        # then falls back to its pattern-only behavior.
+        #
+        # When `console_credential_rotation_warning` is enabled (default: true),
+        # also emits a structured log warning if any credentials file on disk was
+        # modified after this process started — a strong signal that credentials
+        # were rotated without restarting the MCP process. Disable with:
+        #
+        #   config.console_credential_rotation_warning = false
+        #
+        # @param config [Woods::Configuration, nil]
+        # @return [CredentialIndex, nil]
+        def build_credential_index(config)
+          return nil unless config&.console_credential_defense_enabled
+          return nil unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
 
-        def define_job_find(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_job_find',
-                              'Find a job by ID, optionally retry it (requires confirmation)',
-                              properties: {
-                                job_id: str_prop('Job identifier'),
-                                retry: bool_prop('Retry the job (requires confirmation)')
-                              }, required: ['job_id'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_job_find(job_id: args[:job_id], retry_job: args[:retry])
-          end
+          index = CredentialIndex.build(rails_app: Rails.application)
+          maybe_warn_rotation(config, Rails.application)
+          index
         end
 
-        def define_job_schedule(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_job_schedule',
-                              'List scheduled/upcoming jobs',
-                              properties: {
-                                limit: int_prop('Max jobs (default 20, max 100)')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_job_schedule(limit: args[:limit] || 20)
-          end
+        # Emit a boot-time rotation warning when the credentials file mtime is
+        # newer than the process start time, indicating a rotation that was not
+        # followed by a restart. Only fires when Rails.root is available and
+        # `console_credential_rotation_warning` is not false.
+        #
+        # @param config [Woods::Configuration, nil]
+        # @param rails_app [#root] The Rails application (used to locate credential files).
+        # @return [void]
+        def maybe_warn_rotation(config, rails_app)
+          return if config&.console_credential_rotation_warning == false
+          return unless rails_app.respond_to?(:root) && rails_app.root
+
+          root = rails_app.root
+          candidates = [
+            root.join('config/credentials.yml.enc').to_s,
+            root.join("config/credentials/#{ENV.fetch('RAILS_ENV', 'production')}.yml.enc").to_s
+          ]
+
+          CredentialIndex.warn_if_credentials_rotated(
+            credentials_files: candidates,
+            process_start: CredentialIndex::PROCESS_START,
+            logger: structured_logger
+          )
+        rescue StandardError => e
+          handle_observability_failure(e)
         end
 
-        def define_redis_info(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_redis_info',
-                              'Get Redis server information',
-                              properties: {
-                                section: str_prop('INFO section (e.g., memory, stats)')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_redis_info(section: args[:section])
-          end
-        end
+        # Shared server construction used by both build() and build_embedded().
+        #
+        # @param conn_mgr [ConnectionManager, EmbeddedExecutor] Any object with send_request(Hash) -> Hash
+        # @param ctx [ResponseContext, nil] Optional context bundling response-safety layers
+        # @return [MCP::Server]
+        def build_server(conn_mgr, ctx)
+          server = ::MCP::Server.new(
+            name: 'woods-console',
+            version: defined?(Woods::VERSION) ? Woods::VERSION : '0.1.0'
+          )
 
-        def define_cache_stats(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_cache_stats',
-                              'Get cache store statistics',
-                              properties: {
-                                namespace: str_prop('Cache namespace filter')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_cache_stats(namespace: args[:namespace])
-          end
-        end
+          renderer = build_console_renderer
 
-        def define_channel_status(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_channel_status',
-                              'Get ActionCable channel status',
-                              properties: {
-                                channel: str_prop('Filter by channel name')
-                              }, safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier3.console_channel_status(channel: args[:channel])
-          end
+          register_tier1_tools(server, conn_mgr, ctx, renderer: renderer)
+          register_tier2_tools(server, conn_mgr, ctx, renderer: renderer)
+          register_tier3_tools(server, conn_mgr, ctx, renderer: renderer)
+          register_tier4_tools(server, conn_mgr, ctx, renderer: renderer)
+          server
         end
 
-        # ── Tier 4 tool definitions ──────────────────────────────────────────
+        # Loud multi-line banner surfaced to stderr when the opt-in flag is
+        # recognised outside of production. Operators should see this every
+        # boot so an accidentally-persistent env var cannot go unnoticed.
+        #
+        # @return [String]
+        def unsafe_eval_banner
+          <<~BANNER
 
-        def define_eval(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          define_console_tool(server, conn_mgr, 'console_eval',
-                              'Execute arbitrary Ruby code (requires confirmation)',
-                              properties: {
-                                code: str_prop('Ruby code to execute'),
-                                timeout: int_prop('Timeout in seconds (default 10, max 30)')
-                              }, required: ['code'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier4.console_eval(code: args[:code], timeout: args[:timeout] || 10)
-          end
+            ================================================================================
+             WOODS_CONSOLE_UNSAFE_EVAL IS SET
+             console_eval is LIVE on this process. Every run goes through EvalGuard +
+             Confirmation + SafeContext rollback + a wall-clock timeout and is recorded
+             to the audit log. The flag refuses to boot in Rails.env.production?.
+             If you did not mean to set this, unset the env var.
+            ================================================================================
+          BANNER
         end
 
-        def define_sql(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          validator = SqlValidator.new
-          define_console_tool(server, conn_mgr, 'console_sql',
-                              'Execute read-only SQL (SELECT/WITH...SELECT only)',
-                              properties: {
-                                sql: str_prop('SQL query (SELECT or WITH...SELECT only)'),
-                                limit: int_prop('Max rows returned (default unlimited, max 10000)')
-                              }, required: ['sql'], safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier4.console_sql(sql: args[:sql], validator: validator, limit: args[:limit])
+        def structured_logger
+          @structured_logger ||= begin
+            require 'woods/observability/structured_logger'
+            Woods::Observability::StructuredLogger.new
           end
         end
 
-        def define_query(server, conn_mgr, safe_ctx = nil, renderer: nil)
-          props = {
-            model: str_prop('Model name'), select: arr_prop('Columns to select'),
-            joins: arr_prop('Associations to join'), group_by: arr_prop('Columns to group by'),
-            having: str_prop('HAVING clause'), order: obj_prop('Order specification'),
-            scope: obj_prop('Filter conditions'), limit: int_prop('Max rows (max 10000)')
-          }
-          define_console_tool(server, conn_mgr, 'console_query',
-                              'Enhanced query builder with joins and grouping',
-                              properties: props, required: %w[model select],
-                              safe_ctx: safe_ctx, renderer: renderer) do |args|
-            Tools::Tier4.console_query(
-              model: args[:model], select: args[:select], joins: args[:joins],
-              group_by: args[:group_by], having: args[:having],
-              order: args[:order], scope: args[:scope], limit: args[:limit]
-            )
-          end
-        end
+        # Swallow observability failures so they never break a tool response,
+        # but emit a single warn so operators can see if the structured
+        # logging pipeline is broken. Subsequent failures stay silent to
+        # avoid flooding stderr.
+        def handle_observability_failure(error)
+          return if @observability_failure_reported
 
-        # Shared tool definition helper that wires block -> bridge -> response.
-        # rubocop:disable Metrics/ParameterLists
-        def define_console_tool(server, conn_mgr, name, description, properties:, required: nil,
-                                safe_ctx: nil, renderer: nil, &tool_block)
-          bridge_method = method(:send_to_bridge)
-          coerce_method = method(:coerce_integer_args!)
-          integer_keys = integer_property_keys(properties)
-          schema = { properties: properties }
-          schema[:required] = required if required&.any?
-          server.define_tool(name: name, description: description, input_schema: schema) do |server_context:, **args|
-            coerce_method.call(args, integer_keys)
-            request = tool_block.call(args)
-            bridge_method.call(conn_mgr, request.transform_keys(&:to_s), safe_ctx, renderer: renderer)
-          end
+          @observability_failure_reported = true
+          warn '[woods-console] structured logger failed ' \
+               "(#{error.class}: #{error.message}); further failures will be silent."
+        rescue StandardError
+          nil
         end
-        # rubocop:enable Metrics/ParameterLists
 
-        # Pre-compute property keys declared as integer in a schema.
-        #
-        # @param properties [Hash] Tool schema properties
-        # @return [Array<Symbol>]
-        def integer_property_keys(properties)
-          properties.select { |_k, v| v[:type] == 'integer' }.keys.map(&:to_sym)
+        # Legacy delegate to {Redactor.apply} — kept so the server's class-level
+        # spec can drive redaction without constructing a ResponseContext.
+        def apply_redaction(result, ctx)
+          Redactor.apply(result, ctx)
         end
 
-        # Coerce string values to integers for known integer keys.
-        #
-        # @param args [Hash] Tool arguments (mutated in place)
-        # @param keys [Array<Symbol>] Keys that should be integers
-        # @return [void]
-        def coerce_integer_args!(args, keys)
-          keys.each { |k| args[k] = args[k].to_i if args[k].is_a?(String) }
+        def build_console_renderer
+          format = if Woods.respond_to?(:configuration)
+                     Woods.configuration&.context_format || :markdown
+                   else
+                     :markdown
+                   end
+          format == :json ? JsonConsoleRenderer.new : ConsoleResponseRenderer.new
         end
-
-        # Schema property helpers for concise tool definitions.
-        def str_prop(desc)  = { type: 'string', description: desc }
-        def int_prop(desc)  = { type: 'integer', description: desc }
-        def obj_prop(desc)  = { type: 'object', description: desc }
-        def bool_prop(desc) = { type: 'boolean', description: desc }
-        def arr_prop(desc)  = { type: 'array', items: { type: 'string' }, description: desc }
       end
     end
   end