woods 2.0.0.beta2 → 2.0.0.beta4

data/lib/woods/hooks/context_cli.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'timeout'
+
+module Woods
+  module Hooks
+    # The plugin's independent process-group deadline also includes bundle/Ruby
+    # startup. This inner deadline keeps ordinary direct calls short as well.
+    class ContextCLI
+      MAX_INPUT_BYTES = 1_048_576
+      HELP = 'Usage: woods-hook-context SessionStart|PostToolUse < claude-event.json; ' \
+             'opt in with WOODS_HOOK_CONTEXT_ENABLED=1. Prefer the bounded plugin hook entry point.'
+
+      def self.run(kind, input: $stdin, output: $stdout)
+        return output.puts(HELP) || 0 if kind == '--help'
+
+        return 0 if ENV['WOODS_HOOKS_DISABLED'] == '1' || ENV['WOODS_HOOK_CONTEXT_ENABLED'] != '1'
+        return 0 unless %w[SessionStart PostToolUse].include?(kind)
+
+        Timeout.timeout(0.65) do
+          require 'woods'
+          require 'woods/hooks/context_hint'
+          require 'woods/hooks/context_state'
+          emit(kind, input, output)
+        end
+        0
+      rescue Timeout::Error, JSON::ParserError, ArgumentError, KeyError, TypeError, SystemCallError, IOError
+        # Missing/degraded/slow inputs are optional context, not permission to
+        # run extraction, read application data, or acknowledge queued edits.
+        0
+      end
+
+      def self.emit(kind, input, output)
+        bytes = input.read(MAX_INPUT_BYTES + 1)
+        return if bytes.bytesize > MAX_INPUT_BYTES
+
+        event = JSON.parse(bytes)
+        return unless event.is_a?(Hash) && event['hook_event_name'] == kind
+
+        root = ENV['WOODS_HOOK_CONTEXT_ROOT'] || event.fetch('cwd')
+        directory = File.expand_path(ENV.fetch('WOODS_OUTPUT', 'tmp/woods'), root)
+        result = ContextHint.new(event: event, output_dir: directory, root: root).call
+        return unless result
+
+        ContextState.new(directory).emit(result) do
+          output.write(ContextOutput.new(kind).encode(result.fetch(:context)))
+          output.flush
+        end
+      end
+      private_class_method :emit
+    end
+  end
+end

data/lib/woods/hooks/context_event.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'woods/input_rules'
+
+module Woods
+  module Hooks
+    # Claude context events are deliberately separate from refresh queue records.
+    class ContextEvent
+      MAX_FILE_BYTES = 1_048_576
+      attr_reader :root, :path, :kind, :session
+
+      def initialize(input, root: nil)
+        validate_root!(input)
+
+        @logical_root = File.expand_path(input['cwd'])
+        @root = File.realpath(root || @logical_root)
+        @kind = input['hook_event_name']
+        @session = input['session_id'] if valid_string?(input['session_id'], 256)
+        return if kind == 'SessionStart'
+
+        raise ArgumentError unless kind == 'PostToolUse' && %w[Edit Write MultiEdit].include?(input['tool_name'])
+
+        @path = relative_path(input.fetch('tool_input').fetch('file_path'))
+      end
+
+      def eligible?
+        return true if kind == 'SessionStart'
+
+        require 'woods/extractor' unless defined?(Woods::Extractor::EXTRACTORS)
+        InputRules.new.action(path) != :ignore
+      end
+
+      def fingerprint
+        return 'orientation' if kind == 'SessionStart'
+
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(File.join(root, path), flags) do |file|
+          return nil unless file.stat.file? && file.stat.size <= MAX_FILE_BYTES
+
+          bytes = file.read(MAX_FILE_BYTES + 1)
+          return nil if bytes.bytesize > MAX_FILE_BYTES
+
+          Digest::SHA256.hexdigest(bytes)
+        end
+      rescue Errno::ENOENT
+        'missing'
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      private
+
+      def validate_root!(input)
+        raise ArgumentError unless input.is_a?(Hash) && valid_string?(input['cwd']) && input['cwd'].start_with?('/')
+      end
+
+      def valid_string?(value, limit = 4096)
+        value.is_a?(String) && !value.empty? && value.bytesize <= limit &&
+          value.valid_encoding? && !value.include?("\0")
+      end
+
+      def relative_path(value)
+        raise ArgumentError unless valid_string?(value)
+
+        prefix = [@logical_root, root].find { |base| value.start_with?("#{base}/") }
+        relative = prefix ? value.delete_prefix("#{prefix}/") : value
+        validate_parts!(relative)
+        validate_containment!(relative)
+        relative
+      end
+
+      def validate_parts!(relative)
+        parts = relative.split('/', -1)
+        raise ArgumentError if relative.start_with?('/') || parts.size > 64
+        raise ArgumentError if parts.any? { |part| ['', '.', '..'].include?(part) }
+      end
+
+      def validate_containment!(relative)
+        candidate = File.join(root, relative)
+        candidate = File.dirname(candidate) until File.exist?(candidate) || File.symlink?(candidate)
+        resolved = File.realpath(candidate)
+        raise ArgumentError unless resolved == root || resolved.start_with?("#{root}/")
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_hint.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'woods/mcp/index_reader'
+require_relative 'context_event'
+require_relative 'context_output'
+require_relative 'context_impact'
+
+module Woods
+  module Hooks
+    # A bounded snapshot hint. The outer hook process owns the end-to-end deadline.
+    class ContextHint
+      MAX_ARTIFACT_BYTES = 16 * 1024 * 1024
+
+      def initialize(event:, output_dir:, root: nil)
+        @event = ContextEvent.new(event, root: root)
+        @output = File.expand_path(output_dir, @event.root)
+        @renderer = ContextOutput.new(@event.kind)
+      rescue ArgumentError, KeyError, TypeError, SystemCallError
+        @event = nil
+      end
+
+      def call
+        return nil unless @event&.eligible?
+
+        @reader = MCP::IndexReader.new(@output)
+        @reader.with_pinned_generation do
+          @generation = @reader.generation_identity
+          raise ArgumentError if @reader.payload_dir.to_s == @output
+
+          check_artifacts!
+          freshness = source_freshness
+          text = if @event.kind == 'SessionStart'
+                   orientation(freshness)
+                 else
+                   ContextImpact.new(@reader, @renderer).call(@event.path, @generation.first, freshness)
+                 end
+          result(text)
+        end
+      rescue ArgumentError, KeyError, TypeError, NoMethodError, JSON::ParserError, SystemCallError, IOError
+        { context: ContextOutput::UNAVAILABLE, identity: nil, session: nil }
+      end
+
+      private
+
+      def check_artifacts!
+        %w[manifest.json dependency_graph.json source_inputs.json].each do |name|
+          file = @reader.payload_dir.join(name)
+          next if name == 'source_inputs.json' && !file.exist?
+
+          raise ArgumentError unless file.file? && file.size <= MAX_ARTIFACT_BYTES
+        end
+      end
+
+      def source_freshness
+        SourceInputs::Status.new(output_dir: @output, root: @event.root, payload_dir: @reader.payload_dir,
+                                 generation: @reader.loaded_generation).call.fetch('state')
+      end
+
+      def orientation(freshness)
+        @renderer.context("Woods index generation #{@generation.first}; source freshness: #{freshness}. " \
+                          'Use woods_status, search and typed lookup; dependents explain:true suggests checks.')
+      end
+
+      def result(text)
+        fingerprint = @event.fingerprint
+        identity = if fingerprint && @event.session
+                     Digest::SHA256.hexdigest(JSON.generate([@event.root, @event.path, @generation, fingerprint, text]))
+                   end
+        { context: text, identity: identity, session: @event.session, root: @event.root }
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_impact.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Woods
+  module Hooks
+    # Resolve one unambiguous edited identity, then reuse the bounded graph walk.
+    class ContextImpact
+      MAX_NODES = 50_000
+
+      def initialize(reader, renderer)
+        @reader = reader
+        @renderer = renderer
+      end
+
+      def call(path, generation, freshness)
+        graph = @reader.raw_graph_data
+        roots = roots_for(graph, path)
+        header = "Woods candidates from generation #{generation} (pre-refresh snapshot; " \
+                 "source freshness: #{freshness}). Changed path: #{JSON.generate(path)}."
+        return unresolved(header, roots) unless roots.size == 1
+
+        root = roots.first
+        traversal = @reader.traverse_dependents(root.fetch('identifier'), depth: 2, explain: true, max_nodes: 10,
+                                                                          max_edges: 100)
+        @renderer.context(header, rows_for(traversal), partial: !!traversal[:partial])
+      end
+
+      private
+
+      def rows_for(traversal)
+        rows = traversal.fetch(:explanation).fetch(:witnesses).filter_map do |_identifier, witness|
+          next if witness[:impact] == 'root'
+
+          edge = traversal[:explanation][:edges].fetch(witness.fetch(:edge_id))
+          evidence_row(edge, witness)
+        end
+        rows << 'No candidate found within this bounded snapshot; verify manually with dependents.' if rows.empty?
+        rows
+      end
+
+      def roots_for(graph, path)
+        records = records_for(graph)
+        matching = records.select { |node| node['file_path'] == path }
+        identities = matching.map { |node| node.slice('identifier', 'type') }.uniq
+        return identities if identities.size != 1
+
+        # A recorded edge target does not identify which same-named type it means.
+        records.select { |node| node['identifier'] == identities.first['identifier'] }
+               .map { |node| node.slice('identifier', 'type') }.uniq
+      end
+
+      def unresolved(header, roots)
+        reason = roots.empty? ? 'unresolved changed path' : 'ambiguous changed identity'
+        rows = roots.first(10).map { |root| "#{root['identifier']} (#{root['type']})" }
+        @renderer.context("#{header} #{reason}; verify with search and typed lookup.", rows, partial: true)
+      end
+
+      def evidence_row(edge, witness)
+        source = edge.fetch(:source)
+        target = edge.fetch(:target)
+        target_type = target[:type] || "ambiguous/unknown #{Array(target[:candidate_types]).join(',')}"
+        test_hint = source[:type] == 'test_mapping' ? '; test suggestion' : ''
+        uncertain = witness[:typed_path_complete] ? '' : '; typed path incomplete'
+        "#{witness[:impact]} candidate: #{source[:identifier]} (#{source[:type]}) " \
+          "--via=#{edge[:via] || 'unknown'}--> #{target[:identifier]} (#{target_type})#{test_hint}#{uncertain}"
+      end
+
+      def records_for(graph)
+        nodes = graph.fetch('nodes')
+        variants = graph.fetch('variants', [])
+        raise ArgumentError unless nodes.is_a?(Hash) && variants.is_a?(Array)
+        raise ArgumentError if nodes.size + variants.size > MAX_NODES
+
+        nodes.map { |identifier, node| node.merge('identifier' => identifier) } + variants
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_output.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Woods
+  module Hooks
+    # Bounds the complete client JSON envelope, preserving whole evidence rows.
+    class ContextOutput
+      MAX_BYTES = 2048
+      UNAVAILABLE = 'Woods context unavailable or incomplete; inspect woods_status ' \
+                    'and verify with search/lookup/dependents.'
+
+      def initialize(kind)
+        @kind = kind
+      end
+
+      def context(header, rows = [], partial: false)
+        selected = []
+        rows.each do |row|
+          if envelope(([header] + selected + [row, footer(true)]).join("\n")).bytesize > MAX_BYTES
+            partial = true
+            break
+          end
+          selected << row
+        end
+        text = ([header] + selected + [footer(partial)]).join("\n")
+        envelope(text).bytesize <= MAX_BYTES ? text : UNAVAILABLE
+      end
+
+      def encode(context)
+        result = envelope(context)
+        result.bytesize <= MAX_BYTES ? result : envelope(UNAVAILABLE)
+      end
+
+      private
+
+      def footer(partial)
+        "truncated: #{partial ? 'yes' : 'no'}; depth<=2, nodes<=10, edges<=100. " \
+          'Verify with dependents explain:true; candidates and test suggestions are not proof.'
+      end
+
+      def envelope(context)
+        JSON.generate(hookSpecificOutput: { hookEventName: @kind, additionalContext: context })
+      end
+    end
+  end
+end

data/lib/woods/hooks/context_state.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'securerandom'
+
+module Woods
+  module Hooks
+    # Separate, bounded emitted-hint history; never touches refresh queue/leases.
+    class ContextState
+      MAX_BYTES = 131_072
+      MAX_SESSIONS = 32
+      MAX_HINTS = 32
+
+      def initialize(output_dir)
+        @file = File.join(output_dir, 'hook-context-state.json')
+      end
+
+      def emit(result)
+        return yield unless suppressible?(result)
+
+        key = Digest::SHA256.hexdigest(JSON.generate([result[:root], result[:session]]))
+        open_regular("#{@file}.lock", File::RDWR | File::CREAT) do |lock|
+          return unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+          state = read_state
+          history = state.delete(key) || []
+          return if history.include?(result[:identity])
+
+          yield
+          state[key] = (history + [result[:identity]]).last(MAX_HINTS)
+          state.shift while state.size > MAX_SESSIONS
+          write_state(state)
+        end
+      rescue SystemCallError, IOError
+        # State contention/unavailability may skip an optional hint, never refresh.
+        nil
+      end
+
+      private
+
+      def suppressible?(result)
+        result[:identity] && result[:session]
+      end
+
+      def open_regular(path, flags)
+        flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+        File.open(path, flags | File::NONBLOCK, 0o600) do |file|
+          raise IOError unless file.stat.file?
+
+          yield file
+        end
+      end
+
+      def read_state
+        open_regular(@file, File::RDONLY) do |file|
+          return {} if file.stat.size > MAX_BYTES
+
+          state = JSON.parse(file.read(MAX_BYTES + 1))
+          return {} unless valid_state?(state)
+
+          state
+        end
+      rescue Errno::ENOENT, JSON::ParserError
+        {}
+      end
+
+      def valid_state?(state)
+        state.is_a?(Hash) && state.size <= MAX_SESSIONS && state.all? do |key, history|
+          digest?(key) && valid_history?(history)
+        end
+      end
+
+      def valid_history?(history)
+        history.is_a?(Array) && history.size <= MAX_HINTS && history.all? { |id| digest?(id) }
+      end
+
+      def digest?(value)
+        value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+      end
+
+      def write_state(state)
+        temporary = "#{@file}.tmp-#{SecureRandom.hex(12)}"
+        owned = nil
+        open_regular(temporary, File::WRONLY | File::CREAT | File::EXCL) do |file|
+          owned = file.stat
+          file.write(JSON.generate(state))
+        end
+        File.rename(temporary, @file)
+      ensure
+        remove_owned_temporary(temporary, owned) if owned
+      end
+
+      def remove_owned_temporary(path, owned)
+        current = File.lstat(path)
+        File.unlink(path) if current.dev == owned.dev && current.ino == owned.ino
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/woods/hooks/refresh.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+require 'woods/input_rules'
+require 'woods/rake_helpers'
+
+module Woods
+  module Hooks
+    # The JSON argument is portable across host/container command boundaries.
+    # Exit 75 explicitly defers work; only successful consumption acknowledges it.
+    class Refresh
+      MAX_BYTES = 128 * 1024
+      MAX_EVENTS = 1000
+      OPERATIONS = %w[add update delete move].freeze
+
+      def initialize(encoded)
+        raise ArgumentError, 'hook batch too large' if encoded.to_s.bytesize > MAX_BYTES * 2
+
+        @batch = JSON.parse(Base64.strict_decode64(encoded.to_s))
+        validate!
+      end
+
+      def call
+        output = File.expand_path(@batch.fetch('output'), RakeHelpers.woods_task_root)
+        if RakeHelpers.woods_daemon_coverage(output) == :running
+          warn 'Woods hook deferred: watch daemon is active; this batch has not been acknowledged.'
+          exit 75
+        end
+
+        Rake::Task[:environment].invoke
+        require 'woods/extractor'
+        actions, paths = extraction_work
+        return if paths.empty?
+
+        extractor = Extractor.new(output_dir: output)
+        RakeHelpers.woods_with_extraction_lock(output) do
+          actions.include?(:full) ? extractor.extract_all : extractor.extract_changed(paths)
+          extractor.raise_on_publication_failure!
+        end
+      end
+
+      private
+
+      def extraction_work
+        rules = InputRules.new
+        events = @batch.fetch('events')
+        actions = events.map { |event| rules.action(event.fetch('path'), operation: event.fetch('operation')) }
+        paths = events.zip(actions).filter_map { |event, action| event.fetch('path') unless action == :ignore }.uniq
+        [actions, paths]
+      end
+
+      def validate!
+        raise ArgumentError, 'unsupported hook batch' unless @batch.is_a?(Hash) && @batch['version'] == 1
+        raise ArgumentError, 'invalid hook output' unless valid_string?(@batch['output'])
+
+        events = @batch['events']
+        raise ArgumentError, 'invalid hook events' unless valid_events?(events)
+      end
+
+      def valid_events?(events)
+        events.is_a?(Array) && events.size.between?(1, MAX_EVENTS) && events.all? { |event| valid_event?(event) }
+      end
+
+      def valid_event?(event)
+        return false unless event.is_a?(Hash) && OPERATIONS.include?(event['operation'])
+
+        path = event['path']
+        valid_string?(path) && !path.start_with?('/') && path.split('/', -1).none? do |part|
+          ['', '.', '..'].include?(part)
+        end
+      end
+
+      def valid_string?(value)
+        value.is_a?(String) && !value.empty? && !value.include?("\0") && value.bytesize <= MAX_BYTES
+      end
+    end
+  end
+end

data/lib/woods/hooks/rule_projection.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require 'woods/input_rules'
+
+module Woods
+  module Hooks
+    # Generated Bash predicate: the plugin also runs on hosts with no Ruby/bundle.
+    # This is a projection of authoritative rules, never a second path inventory.
+    class RuleProjection
+      def render
+        lines = [
+          '# Generated by script/generate-hook-rules; do not edit.',
+          'woods_input_action() {',
+          '  local path="$1" operation="${2:-update}"'
+        ]
+        restart_conditions.each { |condition| lines << "  if #{condition}; then printf full; return; fi" }
+        rules.each do |rule|
+          lines << "  if #{condition_for(rule)}; then"
+          lines << '    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac'
+          lines << '    return'
+          lines << '  fi'
+        end
+        lines.push('  printf ignore', '}', '').join("\n")
+      end
+
+      private
+
+      def rules
+        PathDispatcher.runtime_rules +
+          PathDispatcher.file_rules + PathDispatcher.whole_app_rules
+      end
+
+      def restart_conditions
+        policy = ReloadPolicy
+        conditions = policy::RESTART_PATHS.map { |path| "[[ \"$path\" == #{quote(path)} ]]" }
+        conditions += policy::RESTART_DIRECTORIES.map { |dir| "[[ \"$path\" == #{quote("#{dir}/")}* ]]" }
+        conditions + policy::RESTART_PATH_PATTERNS.map do |pattern|
+          regex = pattern.source.gsub('\\A', '^').gsub('\\z', '$')
+          "[[ \"$path\" =~ #{regex} ]]"
+        end
+      end
+
+      def condition_for(rule)
+        alternatives = rule.exact_paths.to_a.map { |path| "[[ \"$path\" == #{quote(path)} ]]" }
+        filters = rule.exclude.to_a.map { |part| "[[ \"$path\" != *#{quote(part)}* ]]" }
+        filters += if rule.basenames
+                     [either(rule.basenames.map { |name| "[[ \"${path##*/}\" == #{quote(name)} ]]" })]
+                   else
+                     directory_filters(rule)
+                   end
+        alternatives << "{ #{filters.join(' && ')}; }"
+        either(alternatives)
+      end
+
+      def directory_filters(rule)
+        filters = []
+        filters << either(rule.extensions.map { |ext| "[[ \"$path\" == *#{quote(ext)} ]]" }) if rule.extensions
+        filters << "[[ \"$path\" == *#{quote(rule.require_segment)}* ]]" if rule.require_segment
+        filters << either(rule.dirs.to_a.map { |dir| directory_condition(dir, rule.recursive) })
+      end
+
+      def directory_condition(dir, recursive)
+        variable = recursive == false ? '${path%/*}' : '$path'
+        suffix = recursive == false ? quote(dir) : "#{quote("#{dir}/")}*"
+        "[[ \"#{variable}\" == #{suffix} ]]"
+      end
+
+      def either(conditions)
+        conditions.empty? ? 'false' : "{ #{conditions.join(' || ')}; }"
+      end
+
+      def quote(value)
+        Shellwords.escape(value)
+      end
+    end
+  end
+end

data/lib/woods/input_rules.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'woods/reload_policy'
+require 'woods/path_dispatcher'
+
+module Woods
+  # Shared fresh-process action contract. Loading this class does not boot Rails.
+  # Extractor constants are needed only when deriving the dispatcher projection.
+  class InputRules
+    def action(path, operation: 'update')
+      return :full if ReloadPolicy.new.classify(path) == :restart
+      return :ignore unless PathDispatcher.new.relevant?(path)
+
+      # A removed runtime class may no longer be discoverable in a fresh boot.
+      # Full extraction also handles the old side of a rename conservatively.
+      %w[delete move].include?(operation) ? :full : :incremental
+    end
+  end
+end

data/lib/woods/mcp/bearer_auth.rb

@@ -35,19 +35,12 @@ module Woods
       # @param enabled [#call, nil] Optional request-time predicate. When it
       #   returns falsy the request passes through unguarded. Nil (the
       #   default) means always guard.
-      def initialize(app, token:, path: nil, enabled: nil)
-        @app = app
-        @path = path
-        @enabled = enabled
-        @warned_unusable_token = false
+      # Rails 6.0 forwards middleware options as a positional hash on Ruby 3.
+      # Delegate to explicit keywords to preserve required/unknown option checks.
+      def initialize(app, options = {}, **keywords)
+        raise TypeError, 'middleware options must be a Hash' unless options.is_a?(Hash)
 
-        if token.respond_to?(:call)
-          @token_source = token
-        else
-          validate_static_token!(token)
-          static_token = token.to_s
-          @token_source = -> { static_token }
-        end
+        initialize_options(app, **options, **keywords)
       end
 
       # Rack entry point. Out-of-scope requests (non-matching `path:` prefix
@@ -61,7 +54,8 @@ module Woods
 
         expected = resolve_token
         header = env['HTTP_AUTHORIZATION'].to_s
-        presented = header.start_with?('Bearer ') ? header.sub(/\ABearer /, '') : nil
+        # Only the ASCII scheme changes case; do not normalize or trim the token.
+        presented = header.match?(/\A[Bb][Ee][Aa][Rr][Ee][Rr] /) ? header[7..] : nil
 
         if expected && presented && Rack::Utils.secure_compare(expected, presented)
           @app.call(env)
@@ -72,6 +66,21 @@ module Woods
 
       private
 
+      def initialize_options(app, token:, path: nil, enabled: nil)
+        @app = app
+        @path = path
+        @enabled = enabled
+        @warned_unusable_token = false
+
+        if token.respond_to?(:call)
+          @token_source = token
+        else
+          validate_static_token!(token)
+          static_token = token.to_s
+          @token_source = -> { static_token }
+        end
+      end
+
       # @param env [Hash] Rack environment
       # @return [Boolean] whether this request falls under the guard
       def guard?(env)