phlex-reactive 0.9.2 → 0.9.4

data/lib/phlex/reactive/inspector/report.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Phlex
+  module Reactive
+    module Inspector
+      # Renders the Inspector's read-only inventory for the `phlex_reactive:actions`
+      # and `phlex_reactive:find` rake tasks (issue #168). Plain text by default,
+      # JSON when asked — the SAME no-ANSI posture as Doctor (clean CI/log
+      # capture). Reports NAMES/paths/schemas only, never tokens/secrets/state.
+      module Report
+        module_function
+
+        # A plain-text table of every component × action, or a JSON array when
+        # `format` is :json. One row per action: component, action, params,
+        # file:line, authorization heuristic.
+        def actions(components, format: :text)
+          return actions_json(components) if format == :json
+
+          actions_text(components)
+        end
+
+        # The find result: a ranked list header, then the TOP match in detail —
+        # each action's params, source location, authorization heuristic, and the
+        # full method-definition source. Empty message when nothing matched.
+        def find(matches, query)
+          return %(no component matched "#{query}") if matches.empty?
+
+          lines = [%(#{matches.size} match#{"es" unless matches.size == 1} for "#{query}":)]
+          matches.each { lines << "  #{it.name}" }
+          lines << ""
+          lines.concat(detail_lines(matches.first))
+          lines.join("\n")
+        end
+
+        # -- plain text -------------------------------------------------------
+
+        def actions_text(components)
+          return "no reactive components found" if components.empty?
+
+          rows = components.flat_map { component_rows(it) }
+          render_table(%w[COMPONENT ACTION PARAMS FILE:LINE AUTH], rows)
+        end
+
+        def component_rows(info)
+          return [[info.name, "(no actions)", "", location_str(info.path), ""]] if info.actions.empty?
+
+          info.actions.map do
+            [info.name, it.name.to_s, params_str(it.params),
+             location_str(it.source_location), auth_str(it)]
+          end
+        end
+
+        # A minimal fixed-column table: each column padded to its widest cell.
+        # No ANSI, no external dependency.
+        def render_table(headers, rows)
+          all = [headers] + rows
+          # Two nested blocks (column index + row) need distinct named params —
+          # `it` would collide, so name both.
+          widths = headers.each_index.map { |col| all.map { |row| row[col].to_s.length }.max } # rubocop:disable Style/ItBlockParameter
+          all.map { format_row(it, widths) }.join("\n")
+        end
+
+        def format_row(row, widths)
+          row.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ").rstrip
+        end
+
+        # -- find detail ------------------------------------------------------
+
+        def detail_lines(info)
+          lines = ["#{info.name}  (#{location_str(info.path)})"]
+          lines << "  record: #{info.record_key}" if info.record_key
+          lines << "  state:  #{info.state_keys.join(", ")}" if info.state_keys.any?
+          lines << ""
+          info.actions.each { lines.concat(action_detail(it)) }
+          lines
+        end
+
+        def action_detail(action)
+          header = "  action :#{action.name}"
+          header += "  params: #{params_str(action.params)}" unless action.params.empty?
+          header += "  (#{location_str(action.source_location)})  auth: #{auth_str(action)}"
+          body = action.definition ? indent(action.definition) : "    (method not defined)"
+          [header, body, ""]
+        end
+
+        def indent(text)
+          text.each_line.map { "    #{it}" }.join.rstrip
+        end
+
+        # -- json -------------------------------------------------------------
+
+        def actions_json(components)
+          JSON.pretty_generate(components.map { component_hash(it) })
+        end
+
+        def component_hash(info)
+          {
+            component: info.name,
+            path: location_str(info.path),
+            record_key: info.record_key,
+            state_keys: info.state_keys,
+            actions: info.actions.map { action_hash(it) }
+          }
+        end
+
+        def action_hash(action)
+          {
+            name: action.name,
+            params: action.params,
+            source_location: location_str(action.source_location),
+            authorization_call_detected: action.authorization_call_detected?
+          }
+        end
+
+        # -- shared formatters ------------------------------------------------
+
+        def params_str(params)
+          params.empty? ? "" : params.inspect
+        end
+
+        # "file.rb:42", relative to Rails.root when possible. nil location (a
+        # declared-but-missing method, or an unlocatable const) prints "?".
+        def location_str(location)
+          return "?" unless location
+
+          file, line = location
+          file = file.delete_prefix("#{::Rails.root}/") if defined?(::Rails) && ::Rails.root
+          line ? "#{file}:#{line}" : file
+        end
+
+        # The authorization heuristic as a short label — advisory only.
+        def auth_str(action)
+          action.authorization_call_detected? ? "authorized*" : "unverified"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/inspector.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Phlex
+  module Reactive
+    # The ONE read-only introspection layer (issue #168), consumed by the rake
+    # tasks (`phlex_reactive:actions` / `find`), the MCP tools, and Doctor. It
+    # discovers every constant-backed reactive component from the loaded
+    # Streamable registry and, per declared action, its param schema, source
+    # location, full method-definition source (extracted with Prism), and a
+    # heuristic authorization status.
+    #
+    # It reports NAMES, PATHS, and declared SCHEMAS only — never tokens, secrets,
+    # or runtime state (the instrumentation privacy contract extended to
+    # tooling). Like Doctor, it is READ-ONLY: it never mounts a component,
+    # mutates state, or touches the default-deny boundary.
+    #
+    #   Phlex::Reactive::Inspector.components   # => [ComponentInfo]
+    #   Phlex::Reactive::Inspector.find(query)  # => ranked [ComponentInfo]
+    module Inspector
+      # One declared action's introspection.
+      #
+      #   * source_location — klass.instance_method(name).source_location, or nil
+      #                       when the action is declared but the method is
+      #                       missing (the endpoint would 500 on public_send).
+      #   * definition      — the full `def ... end` source, extracted with Prism.
+      #                       nil when the method is missing or its file is
+      #                       unreadable/unparseable (degrade, never raise).
+      #   * authorization_call_detected? — a HEURISTIC: true when the Prism scan
+      #                       of the definition finds a call to any configured
+      #                       authorization method or mark_authorized!. A helper
+      #                       may authorize indirectly, so this is advisory ONLY.
+      ActionInfo = Data.define(:name, :params, :source_location, :definition) do
+        # Was any authorization method (or mark_authorized!) called directly in
+        # the method body? Heuristic — a Prism scan of `definition`. False when
+        # the definition is unavailable.
+        def authorization_call_detected?
+          return false unless definition
+
+          Inspector.authorization_call?(definition)
+        end
+      end
+
+      # One reactive component's introspection.
+      #
+      #   * path        — Object.const_source_location(name) => [file, line].
+      #   * record_key  — the declared reactive_record key, or nil.
+      #   * state_keys  — the declared reactive_state keys.
+      #   * actions     — [ActionInfo], one per declared action.
+      ComponentInfo = Data.define(:klass, :name, :path, :record_key, :state_keys, :actions)
+
+      # The authorization method names the heuristic looks for. Reads
+      # Phlex::Reactive.authorization_methods when configured (issue #168 phase 2);
+      # otherwise the common set (Pundit/CanCanCan/ActionPolicy-style). The manual
+      # escape hatch `mark_authorized!` always counts.
+      DEFAULT_AUTHORIZATION_METHODS = %i[authorize! authorize allowed_to?].freeze
+      MANUAL_AUTHORIZATION_MARK = :mark_authorized!
+
+      class << self
+        # Every constant-backed reactive component, as [ComponentInfo]. Call
+        # Rails.application.eager_load! first (the caller / rake task does) so
+        # every app component is in the Streamable registry.
+        def components
+          reactive_component_classes.map { component_info(it) }
+        end
+
+        # Ranked fuzzy matches for `query` (issue #168). Scored on BOTH the
+        # demodulized and the full namespaced name, best of the two:
+        # exact > prefix > substring > subsequence, case-insensitive. Returns []
+        # on no match. No dependency — a ~1-screen scorer.
+        def find(query)
+          q = query.to_s.downcase
+          return [] if q.empty?
+
+          reactive_component_classes
+            .filter_map { score_component(it, q) }
+            .sort_by { |score, name, _klass| [-score, name] }
+            .map { |_score, _name, klass| component_info(klass) }
+        end
+
+        # True when a component class is a real, CONSTANT-RESOLVABLE reactive
+        # component — its own name round-trips through safe_constantize (exactly
+        # how ActionsController#resolve_component rebuilds it from the token). This
+        # also excludes anonymous classes (name nil) and fixtures that fake
+        # `def self.name` without a matching constant. Moved here from Doctor
+        # (issue #168); Doctor delegates.
+        def constant_backed_component?(klass)
+          reactive_component?(klass) && klass.name && klass.name.safe_constantize.equal?(klass)
+        rescue StandardError
+          false
+        end
+
+        def reactive_component?(klass)
+          klass.respond_to?(:reactive_actions) && klass.include?(Phlex::Reactive::Component)
+        rescue StandardError
+          false
+        end
+
+        # Does the method-definition source `definition` call an authorization
+        # method or mark_authorized! anywhere? A Prism scan for a call node whose
+        # method name is in the configured set. Heuristic; degrades to false on
+        # an unparseable snippet.
+        def authorization_call?(definition)
+          result = Prism.parse(definition)
+          return false unless result.success?
+
+          names = authorization_method_names
+          call_names(result.value).any? { names.include?(it) }
+        rescue StandardError
+          false
+        end
+
+        # The configured authorization method names plus the manual mark, as a
+        # Set of symbols. Reads Phlex::Reactive.authorization_methods when it
+        # exists (phase 2), else the default set. Guarded: a misconfigured
+        # authorization_methods (nil, or a single symbol) is coerced through
+        # Array() rather than raising `.map` on nil — which the caller's rescue
+        # would swallow, silently disabling the heuristic instead of surfacing it.
+        def authorization_method_names
+          configured =
+            if Phlex::Reactive.respond_to?(:authorization_methods)
+              Phlex::Reactive.authorization_methods || DEFAULT_AUTHORIZATION_METHODS
+            else
+              DEFAULT_AUTHORIZATION_METHODS
+            end
+          (Array(configured).map(&:to_sym) + [MANUAL_AUTHORIZATION_MARK]).to_set
+        end
+
+        private
+
+        def reactive_component_classes
+          Phlex::Reactive::Streamable.registered_classes.select { constant_backed_component?(it) }
+        end
+
+        def component_info(klass)
+          ComponentInfo.new(
+            klass:,
+            name: klass.name,
+            path: Object.const_source_location(klass.name),
+            record_key: (klass.reactive_record_key if klass.respond_to?(:reactive_record_key)),
+            state_keys: state_keys_for(klass),
+            actions: action_infos(klass)
+          )
+        rescue StandardError
+          ComponentInfo.new(klass:, name: klass.name, path: nil, record_key: nil, state_keys: [], actions: [])
+        end
+
+        def state_keys_for(klass)
+          klass.respond_to?(:reactive_state_keys) ? klass.reactive_state_keys : []
+        end
+
+        def action_infos(klass)
+          klass.reactive_actions.values.map { action_info(klass, it) }
+        end
+
+        def action_info(klass, action)
+          location = method_location(klass, action.name)
+          ActionInfo.new(
+            name: action.name,
+            params: action.params,
+            source_location: location,
+            definition: (extract_definition(location) if location)
+          )
+        end
+
+        # The method's [file, line], or nil when the declared method is missing
+        # (an undeclared/typo'd action — the endpoint would 500 on public_send).
+        def method_location(klass, name)
+          return nil unless klass.method_defined?(name) || klass.private_method_defined?(name)
+
+          klass.instance_method(name).source_location
+        rescue StandardError
+          nil
+        end
+
+        # The full `def ... end` source at [file, line], via Prism. Finds the def
+        # node whose location spans `line` and returns its slice. nil when the
+        # file is unreadable/unparseable or no def node covers the line — never
+        # raises.
+        def extract_definition(location)
+          file, line = location
+          return nil unless file && line && File.readable?(file)
+
+          result = Prism.parse_file(file)
+          return nil unless result.success?
+
+          node = def_node_at(result.value, line)
+          node&.slice
+        rescue StandardError
+          nil
+        end
+
+        # Depth-first search for the DefNode whose source line == `line`.
+        def def_node_at(node, line)
+          return node if def_node_on_line?(node, line)
+
+          node.compact_child_nodes.each do
+            found = def_node_at(it, line)
+            return found if found
+          end
+          nil
+        end
+
+        def def_node_on_line?(node, line)
+          node.is_a?(Prism::DefNode) && node.location.start_line == line
+        end
+
+        # Every method name called anywhere under `node` (a Prism CallNode's
+        # name), depth-first. Used by the authorization heuristic.
+        def call_names(node, acc = [])
+          acc << node.name if node.is_a?(Prism::CallNode)
+          node.compact_child_nodes.each { call_names(it, acc) }
+          acc
+        end
+
+        # -- fuzzy scoring ----------------------------------------------------
+
+        # The best match score of the demodulized and full names, or nil if
+        # neither matches. Higher is better; ties broken by name in .find.
+        def score_component(klass, query)
+          full = klass.name.downcase
+          demodulized = klass.name.split("::").last.downcase
+          score = [match_score(demodulized, query), match_score(full, query)].compact.max
+          return nil unless score
+
+          [score, klass.name, klass]
+        end
+
+        # exact 4 > prefix 3 > substring 2 > subsequence 1 > no match nil.
+        def match_score(candidate, query)
+          return 4 if candidate == query
+          return 3 if candidate.start_with?(query)
+          return 2 if candidate.include?(query)
+          return 1 if subsequence?(candidate, query)
+
+          nil
+        end
+
+        # Are the characters of `query` present in `candidate` in order (gaps
+        # allowed)? The loosest fuzzy tier.
+        def subsequence?(candidate, query)
+          i = 0
+          candidate.each_char do
+            i += 1 if it == query[i]
+            return true if i == query.length
+          end
+          query.empty?
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/log_subscriber.rb

@@ -54,6 +54,16 @@ module Phlex
         end
       end
 
+      # The defer endpoint / render leg (issue #165). Like #action, an
+      # :invalid_token event carries no TRUSTED component name — omit it.
+      def defer(event)
+        return unless logger.debug?
+
+        payload = event.payload
+        subject = [payload[:component], payload[:outcome]].compact.join(" ")
+        debug { "[reactive] defer #{subject} (#{round(event.duration)}ms)" }
+      end
+
       private
 
       def round(duration_ms)

data/lib/phlex/reactive/mcp/base_tool.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Phlex
+  module Reactive
+    module MCP
+      # The base class every phlex-reactive MCP tool subclasses (issue #168),
+      # mirroring pgbus's BaseTool. It sets the read-only annotation contract ONCE
+      # and overrides annotations_value so subclasses inherit it — MCP::Tool.inherited
+      # resets @annotations_value to nil per subclass, so without this each tool
+      # would advertise no annotations.
+      #
+      # Every tool is READ-ONLY and NON-DESTRUCTIVE: it reads the loaded registry
+      # (via Inspector / Doctor) and reports NAMES, PATHS, and declared SCHEMAS
+      # only — never a token, secret, or runtime state (the instrumentation
+      # privacy contract extended to tooling). There is deliberately NO
+      # arbitrary-query tool.
+      class BaseTool < ::MCP::Tool
+        annotations(
+          read_only_hint: true,
+          destructive_hint: false,
+          idempotent_hint: true,
+          open_world_hint: false
+        )
+
+        class << self
+          # Inherit the base annotations into every subclass (MCP::Tool.inherited
+          # nils @annotations_value, so fall through to the superclass's).
+          def annotations_value
+            super || (superclass.respond_to?(:annotations_value) ? superclass.annotations_value : nil)
+          end
+
+          # A single text-content response carrying JSON.generate(value). The one
+          # place tool output is serialized — pretty-printed for a human reading
+          # the transcript, still valid JSON for the client.
+          def json_response(value)
+            ::MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(value) }])
+          end
+
+          # An error response (the tool ran but has nothing to return — e.g. a
+          # find with no match handled by the tool, or a bad filter).
+          def error_response(message)
+            ::MCP::Tool::Response.new([{ type: "text", text: message }], error: true)
+          end
+
+          # Populate the Streamable registry the Inspector/Doctor read — the
+          # tools call this before introspecting so every app component is
+          # loaded. Guarded for a non-Rails / not-yet-booted context.
+          def eager_load_app!
+            ::Rails.application.eager_load! if defined?(::Rails) && ::Rails.application
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp/runner.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      # Drives the read-only MCP server over stdio (issue #168). Invoked by the
+      # `phlex_reactive:mcp` rake task after MCP.load!.
+      #
+      # KNOWN CONSTRAINT (same as pgbus): stdio MCP requires a CLEAN stdout — the
+      # JSON-RPC frames are the ONLY thing that may be written there. An
+      # initializer that `puts` (or any library that writes to $stdout) breaks the
+      # transport. Log to $stderr or Rails.logger, never $stdout.
+      module Runner
+        module_function
+
+        def run
+          server = Server.build
+          transport = ::MCP::Server::Transports::StdioTransport.new(server)
+          transport.open
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp/server.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      # Builds the read-only MCP::Server (issue #168). The tool array is FIXED and
+      # FROZEN — there is deliberately no arbitrary-query or mutation tool; every
+      # tool reads the loaded registry and reports names/paths/schemas only.
+      module Server
+        TOOLS = [
+          Tools::DoctorTool,
+          Tools::ComponentsTool,
+          Tools::ActionsTool,
+          Tools::FindTool,
+          Tools::ConfigTool
+        ].freeze
+
+        INSTRUCTIONS = <<~TEXT
+          Read-only diagnostic tools for a phlex-reactive install. Use them to
+          answer "what reactive components/actions exist, where are they defined,
+          is each authorized, and is the install wired correctly?" without grepping.
+
+          - phlex_reactive_doctor: validate the install (route, Stimulus, verifier, …).
+          - phlex_reactive_components: the component inventory (names, paths, keys).
+          - phlex_reactive_actions: per-action detail (params, source, authorization).
+          - phlex_reactive_find: fuzzy search + method-definition source.
+          - phlex_reactive_config: a redacted config summary (never secrets/tokens).
+
+          For reference documentation (not live-app introspection) see the hosted
+          docs MCP at https://phlex-reactive.zoolutions.llc/llms.txt.
+        TEXT
+
+        module_function
+
+        def build
+          ::MCP::Server.new(
+            name: "phlex-reactive",
+            title: "phlex-reactive diagnostics",
+            version: Phlex::Reactive::VERSION,
+            instructions: INSTRUCTIONS,
+            tools: TOOLS.dup
+          )
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp/tools/actions_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      module Tools
+        # phlex_reactive_actions — the full action inventory: per action, the
+        # declared param schema, source location, and the authorization heuristic.
+        # Optional `component:` filter narrows to one component.
+        class ActionsTool < BaseTool
+          tool_name "phlex_reactive_actions"
+          title "phlex-reactive actions"
+          description <<~DESC
+            The full reactive action inventory: for every component, each declared
+            action with its param schema, source file:line, and a heuristic
+            authorization status (whether an authorization method or
+            mark_authorized! call was detected in the body — advisory only, since a
+            helper may authorize indirectly). Pass `component:` to scope to one
+            component (exact name). Read-only — schemas and paths, never runtime
+            values.
+          DESC
+
+          input_schema(
+            properties: {
+              component: {
+                type: "string",
+                description: "Exact component class name to scope to (e.g. \"CounterComponent\"). Omit for all."
+              }
+            },
+            required: []
+          )
+
+          def self.call(component: nil, server_context: nil) # rubocop:disable Lint/UnusedMethodArgument
+            eager_load_app!
+            infos = Phlex::Reactive::Inspector.components
+            infos = infos.select { it.name == component } if component
+            json_response(components: infos.map { Phlex::Reactive::Inspector::Report.component_hash(it) })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp/tools/components_tool.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      module Tools
+        # phlex_reactive_components — a summary of every constant-backed reactive
+        # component: name, source path, action count, record/state keys. The
+        # bird's-eye inventory; phlex_reactive_actions has the per-action detail.
+        class ComponentsTool < BaseTool
+          tool_name "phlex_reactive_components"
+          title "phlex-reactive components"
+          description <<~DESC
+            List every reactive component in the app with its name, source
+            file:line, action count, and record/state keys. Use phlex_reactive_actions
+            for the full per-action detail, or phlex_reactive_find to search.
+            Read-only — names, paths, and declared keys only.
+          DESC
+
+          input_schema(properties: {}, required: [])
+
+          def self.call(server_context: nil) # rubocop:disable Lint/UnusedMethodArgument
+            eager_load_app!
+            components = Phlex::Reactive::Inspector.components.map do
+              {
+                name: it.name,
+                path: Phlex::Reactive::Inspector::Report.location_str(it.path),
+                action_count: it.actions.length,
+                record_key: it.record_key,
+                state_keys: it.state_keys
+              }
+            end
+            json_response(components: components)
+          end
+        end
+      end
+    end
+  end
+end