phlex-reactive 0.9.2 → 0.9.4

data/lib/generators/phlex/reactive/claude/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Installs the phlex-reactive debugging toolkit for Claude Code:
+    copies the `phlex-reactive-debugging` skill into .claude/skills/ (the
+    debugging runbook — doctor → inventory → find → browser scan → MCP) and adds
+    the read-only diagnostic MCP server to .mcp.json (only when absent; it never
+    rewrites an existing .mcp.json — it prints the snippet instead).
+
+    The MCP server needs the optional `mcp` gem (`gem "mcp"`); the skill and rake
+    tasks work without it.
+
+Example:
+    bin/rails generate phlex:reactive:claude
+
+    Creates .claude/skills/phlex-reactive-debugging/ and, when absent, .mcp.json
+    with the phlex-reactive server entry.

data/lib/generators/phlex/reactive/claude/claude_generator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "json"
+
+module Phlex
+  module Reactive
+    module Generators
+      # `rails g phlex:reactive:claude`
+      #
+      # Installs the phlex-reactive debugging toolkit for Claude Code inside a
+      # host app (issue #168):
+      #   * copies the shipped `phlex-reactive-debugging` skill into
+      #     .claude/skills/ (the debugging runbook: doctor → inventory → find →
+      #     browser scan → MCP)
+      #   * adds the read-only MCP server to .claude/../.mcp.json — but ONLY when
+      #     the file is absent (never rewrite an existing .mcp.json); otherwise it
+      #     prints the snippet to add by hand.
+      #
+      # The skill ships INSIDE the gem (under lib/, so the gemspec packages it),
+      # not as a template, so it always matches the installed gem version.
+      class ClaudeGenerator < ::Rails::Generators::Base
+        SKILL_NAME = "phlex-reactive-debugging"
+
+        # The shipped skills live inside the gem under lib/phlex/reactive/claude/
+        # skills/ (packaged by the gemspec). source_root points there so
+        # `directory` copies the skill tree by its relative name.
+        source_root File.expand_path("../../../../phlex/reactive/claude/skills", __dir__)
+
+        # The MCP server entry a host app adds to .mcp.json. Introspection needs
+        # the booted app, so the command is the rake task (not a standalone exe).
+        MCP_ENTRY = {
+          "mcpServers" => {
+            "phlex-reactive" => {
+              "command" => "bin/rails",
+              "args" => ["phlex_reactive:mcp"]
+            }
+          }
+        }.freeze
+
+        # The shipped skill directory inside the gem (packaged under lib/).
+        def self.skill_source_dir
+          File.expand_path("../../../../phlex/reactive/claude/skills/#{SKILL_NAME}", __dir__)
+        end
+
+        # Copy the shipped skill into the host app's .claude/skills/.
+        def install_skill
+          source = self.class.skill_source_dir
+          dest = File.join(".claude", "skills", SKILL_NAME)
+          directory(source, dest)
+        end
+
+        # Create .mcp.json with the server entry when it's absent; otherwise print
+        # the snippet (NEVER rewrite an existing .mcp.json — it may hold other
+        # servers the app configured).
+        def configure_mcp
+          path = ".mcp.json"
+          if File.exist?(File.join(destination_root, path))
+            say_status :skip, "#{path} exists — add the phlex-reactive server yourself:", :yellow
+            say(pretty_entry)
+          else
+            create_file path, "#{pretty_entry}\n"
+          end
+        end
+
+        def show_post_install
+          say_status :info, "phlex-reactive debugging toolkit installed for Claude Code.", :green
+          say <<~MSG
+
+            The `#{SKILL_NAME}` skill teaches the debugging workflow (doctor →
+            inventory → find → browser report() → MCP). The MCP server needs the
+            optional `mcp` gem — add `gem "mcp"` to your Gemfile to enable it.
+
+            Try it:  bin/rails phlex_reactive:doctor
+          MSG
+        end
+
+        private
+
+        def pretty_entry
+          JSON.pretty_generate(MCP_ENTRY)
+        end
+      end
+    end
+  end
+end

data/lib/generators/phlex/reactive/install/install_generator.rb

@@ -61,6 +61,9 @@ module Phlex
             Scaffold one with:  rails g phlex:reactive:component Counter
 
             Then verify the whole install:  bin/rails phlex_reactive:doctor
+
+            Debugging with Claude Code? Install the toolkit (skill + MCP server):
+              rails g phlex:reactive:claude
           MSG
         end
 

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -15,6 +15,16 @@
 # Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]
 # Phlex::Reactive.authorization_errors = [ActionPolicy::Unauthorized]
 
+# verify_authorized (ON by default): an action that completes WITHOUT any
+# authorization call raises Phlex::Reactive::AuthorizationNotVerified inside the
+# transaction — the mutation rolls back (fail-closed). Satisfy it by calling one
+# of authorization_methods, calling `mark_authorized!` after a bespoke check, or
+# declaring `skip_verify_authorized` on a genuinely public component/action.
+# Set the method names to match your authorization library:
+# Phlex::Reactive.authorization_methods = %i[authorize! authorize allowed_to?]
+# Turn the guard off entirely (not recommended — you lose the fail-closed net):
+# Phlex::Reactive.verify_authorized = false
+
 # Diagnostic endpoint error bodies + dropped-param logging (statuses never
 # change). Defaults to Rails.env.local? — on in development AND test, off in production.
 # Phlex::Reactive.verbose_errors = true
@@ -41,6 +51,52 @@
 #   <meta name="phlex-reactive-action-path" content="<%%= Phlex::Reactive.action_path %>">
 # Phlex::Reactive.action_path = "/_r/actions"
 
+# --- Deferred reply segments (reply.defer + reactive_lazy, issue #165) ------
+# PROFILE FIRST: an app-side N+1 looks exactly like framework lag — make the
+# synchronous path cheap before deferring a segment.
+#
+# How the deferred render reaches the actor (default :auto — a durable pgbus
+# one-shot stream + ActiveJob when both are available, else a parallel fetch to
+# the defer endpoint; :fetch forces the fetch lane, :stream requests push and
+# degrades to fetch with a warning when the capability is absent):
+# Phlex::Reactive.defer_transport = :auto
+#
+# Defer tokens are purpose-scoped and short-lived — the TTL only needs to cover
+# the reply→fetch gap (default 120 seconds):
+# Phlex::Reactive.defer_token_ttl = 120
+#
+# reply.defer tokens are ACTOR-BOUND: signed under the requesting session so a
+# leaked token can't be redeemed in another session. The default binding is the
+# session id; override to bind to your own actor identity (a user id, an API
+# token digest). Apps with no session middleware mint UNBOUND tokens — their
+# bound is then the TTL plus any authorization your component enforces AT RENDER
+# TIME. Note the defer endpoint runs NO action and calls NO authorize! itself
+# (it's a read); protection comes from the component raising a registered
+# authorization error from from_identity/render, or returning false from
+# render?, when it's rebuilt at the defer endpoint.
+# Phlex::Reactive.singleton_class.class_eval do
+#   def defer_binding_for(request) = Current.user&.id&.to_s
+# end
+#
+# The push lane's render job queue (default "default"). Point it at a FAST
+# queue in production — a deferred segment is a UX-latency render; letting it
+# starve behind heavy jobs defeats the point:
+# Phlex::Reactive.defer_job_queue = "latency"
+#
+# PUSH LANE QUEUE LIFECYCLE: each deferred segment on the push lane mints a
+# durable one-shot pgbus stream. Its queue is reclaimed by pgbus's age-based
+# orphan-stream sweep (pgbus >= 0.9.10) — make sure the pgbus Dispatcher runs
+# with streams_orphan_threshold set. We never drop it from the job (an eager
+# drop would destroy an unconsumed message and reopen the broadcast-before-
+# subscribe race). On pgbus <= 0.9.9, or if you don't run the reaper, force the
+# (universal, cleanup-free) fetch lane:
+# Phlex::Reactive.defer_transport = :fetch
+#
+# Change the defer endpoint path (default "/reactive/defer"). If you change it,
+# expose it to the client with:
+#   <meta name="phlex-reactive-defer-path" content="<%%= Phlex::Reactive.defer_path %>">
+# Phlex::Reactive.defer_path = "/_r/defer"
+
 # Client request timeout (default 30s). There is NO server-side setting — a hung
 # request aborts client-side after this window (reactive:error kind "timeout"),
 # so the per-component queue never wedges. Override in your layout head:

data/lib/phlex/reactive/authorization.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The runtime machinery behind verify_authorized (issue #168): a time-window
+    # tracking cell, an interceptor that marks it when a configured authorization
+    # method returns, and the enforcement decision the endpoint calls after an
+    # action runs.
+    #
+    # The design mirrors Phlex::Reactive.with_connection_id: a fiber-local cell
+    # (Thread.current, which is fiber-local in Ruby, so Falcon's fiber-per-request
+    # model is safe) saved and restored around the action. Because tracking is a
+    # WINDOW — anything marking during the action counts — authorization performed
+    # in a HELPER the action calls is detected too, not just a top-level call.
+    module Authorization
+      # The fiber-local key holding the tracking cell during an action. A truthy
+      # value means "some authorization method has been called (and returned)
+      # during this window".
+      CELL = :phlex_reactive_authorized
+
+      # Streamable defines a CLASS method `prepend(target:, model:)` (the Turbo
+      # Stream verb), which shadows Ruby's Module#prepend on a component class.
+      # Bind the real Module#prepend so instrument! can prepend the interceptor
+      # module without dispatching to the stream helper (and its keyword arity).
+      MODULE_PREPEND = ::Module.instance_method(:prepend)
+      private_constant :MODULE_PREPEND
+
+      class << self
+        # Open a fresh tracking window, run the block, and restore the previous
+        # cell — exactly the with_connection_id save/restore shape, so nesting is
+        # correct and a raise still restores. The inner window starts UNMARKED
+        # regardless of an outer mark (a fresh action authorizes for itself).
+        def with_tracking
+          previous = Thread.current[CELL]
+          Thread.current[CELL] = false
+          yield
+        ensure
+          Thread.current[CELL] = previous
+        end
+
+        # Mark the current window authorized. Called by the interceptor (on a
+        # non-raising authorization-method return) and by Component#mark_authorized!
+        # for a bespoke check. A no-op semantically outside a window (the cell is
+        # simply overwritten and restored by the nearest with_tracking).
+        def mark!
+          Thread.current[CELL] = true
+        end
+
+        # Has anything marked the current window?
+        def marked?
+          Thread.current[CELL] == true
+        end
+
+        # The enforcement decision, called by the endpoint AFTER the action runs,
+        # INSIDE the transaction (so a raise rolls the mutation back). A no-op
+        # unless verify_authorized is on, the action isn't skipped, and nothing
+        # marked the window. Otherwise raises AuthorizationNotVerified naming the
+        # component#action and the three remedies.
+        def verify!(component_class, action_def)
+          return unless Phlex::Reactive.verify_authorized
+          return if skipped?(component_class, action_def.name)
+          return if marked?
+
+          raise Phlex::Reactive::AuthorizationNotVerified, violation_message(component_class, action_def)
+        end
+
+        # Wrap each configured authorization method the class defines (public OR
+        # private, own OR inherited) with a prepended module that calls super and
+        # then mark! on a NON-RAISING return — so a denial (which raises) never
+        # marks and still propagates to the endpoint's authorization_errors → 403.
+        #
+        # Idempotent per class OBJECT (memoized on an ivar the class carries), so
+        # a Zeitwerk reload's fresh class re-instruments naturally and a repeated
+        # call in one process is a no-op. Re-reads authorization_methods each first
+        # call, so an initializer that widened the list is honored.
+        def instrument!(component_class)
+          return if component_class.instance_variable_get(:@reactive_authorization_instrumented)
+
+          names = Phlex::Reactive.authorization_methods.select do
+            component_class.method_defined?(it) || component_class.private_method_defined?(it)
+          end
+          MODULE_PREPEND.bind_call(component_class, interceptor_for(names)) if names.any?
+          component_class.instance_variable_set(:@reactive_authorization_instrumented, true)
+        end
+
+        private
+
+        def skipped?(component_class, action_name)
+          component_class.respond_to?(:skip_verify_authorized?) &&
+            component_class.skip_verify_authorized?(action_name)
+        end
+
+        # Build the prepend module: one wrapper per authorization method name,
+        # each `super(...)` then mark! (only reached when super didn't raise).
+        def interceptor_for(names)
+          Module.new do
+            names.each do
+              define_method(it) do |*args, **kwargs, &block|
+                result = super(*args, **kwargs, &block)
+                Phlex::Reactive::Authorization.mark!
+                result
+              end
+            end
+          end
+        end
+
+        def violation_message(component_class, action_def)
+          where = [component_class&.name, action_def&.name].compact.join("#")
+          methods = Phlex::Reactive.authorization_methods.map { ":#{it}" }.join(", ")
+          "#{where} completed without any authorization call — verify_authorized is on. " \
+            "Either call one of your authorization methods (#{methods}), call mark_authorized! " \
+            "for a bespoke check, or declare `skip_verify_authorized` (whole component) / " \
+            "`skip_verify_authorized :#{action_def&.name}` (this action) if it is intentionally public."
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/claude/skills/phlex-reactive-debugging/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: phlex-reactive-debugging
+description: "Debug phlex-reactive in a Rails app: a reactive component that doesn't update, a 400/403/404 from POST /reactive/actions, an AuthorizationNotVerified error, or an audit of which reactive actions authorize. Use when a reactive click does nothing, a Turbo Stream never arrives, or you need to inventory the reactive components/actions in the app."
+---
+
+# Debugging phlex-reactive
+
+phlex-reactive turns every reactive component into a browser-reachable RPC:
+`POST /reactive/actions` with a signed identity token → verify → rebuild the
+component → run the declared action → render an auto-targeted Turbo Stream. When
+something "just doesn't work," the failure is almost always at one of those
+seams. This skill is the runbook.
+
+Work top-down: **validate the install → inventory the server → find the specific
+component → scan the live page → introspect the running app.** Stop as soon as a
+step names the problem.
+
+## 1. Validate the install (`doctor`)
+
+```bash
+bin/rails phlex_reactive:doctor
+```
+
+Prints ✓/✗/? for the whole install: does `POST /reactive/actions` route to the
+gem (a host catch-all route shadows it otherwise), is the generic `reactive`
+Stimulus controller registered, does the identity verifier round-trip, does every
+declared `action :name` have a public method, does every component resolve a
+stable `#id`, and an **advisory** authorization heuristic. A ✗ prints the fix.
+Run this FIRST — most "nothing happens" reports are a red ✗ here.
+
+## 2. Inventory the server (`actions` / `find`)
+
+```bash
+bin/rails phlex_reactive:actions            # every component × action: params, file:line, auth
+bin/rails phlex_reactive:actions FORMAT=json
+bin/rails "phlex_reactive:find[counter]"    # fuzzy-find one; prints each action's method source
+```
+
+Answers "what reactive actions exist, where are they defined, and is each
+authorized?" without grepping. The `auth` column is a heuristic (`authorized*` =
+an authorization call was detected in the body; `unverified` = none — a helper
+may still authorize indirectly).
+
+## 3. Scan the live page (browser inspector)
+
+In the browser console on the affected page:
+
+```js
+(await import("phlex/reactive/inspect")).report()
+```
+
+`report()` prints a `console.table` of every reactive root on the page — its
+`id`, decoded token payload (**component class**, gid, state keys), status
+(error/busy/dirty), the bound **triggers** (action + event + params +
+debounce/confirm), client-only ops, computes, and the named fields a dispatch
+would send. `scan()` returns the same data.
+
+**The server↔client mapping is by name.** The `component` and each trigger's
+`action` in `report()` are exactly the identifiers `phlex_reactive:actions`
+lists. So: does the button on the page carry the action you expect? Does its
+`component` match the class you think renders here? A mismatch (or a root with an
+`(opaque token)`) localizes the bug.
+
+## 4. Introspect the running app (MCP server)
+
+For live-app introspection from inside your editor, run the read-only MCP server
+(needs the optional `mcp` gem — `gem "mcp"`):
+
+```json
+// .mcp.json
+{ "mcpServers": { "phlex-reactive": { "command": "bin/rails", "args": ["phlex_reactive:mcp"] } } }
+```
+
+It exposes five read-only tools — `phlex_reactive_doctor`,
+`phlex_reactive_components`, `phlex_reactive_actions` (optional `component:`
+filter), `phlex_reactive_find`, `phlex_reactive_config` — the same data as the
+rake tasks, queryable in conversation. Constraint: stdio MCP needs a clean
+stdout, so an initializer that `puts` breaks it.
+
+`rails g phlex:reactive:claude` installs this skill and writes the `.mcp.json`
+entry for you.
+
+## Failure table
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| **400** (bad request) | Tampered / stale token — a token from before a deploy, a `secret_key_base` mismatch, or a `reply.with(...)` stream that skipped the token refresh | Reload the page for a fresh token; confirm `secret_key_base`; ensure custom streams refresh the token |
+| **403** (forbidden) | The action isn't declared (`action :name`), OR your authorizer raised and is registered in `Phlex::Reactive.authorization_errors` | Declare the action; or the 403 is correct — the user isn't allowed |
+| **`AuthorizationNotVerified`** (500) | `verify_authorized` is ON and the action completed without calling an authorization method or `mark_authorized!` | Call your authorization method inside the action, call `mark_authorized!` after a bespoke check, or declare `skip_verify_authorized` if it's genuinely public |
+| **404** (not found) | The record was deleted while a page still showed it (record-backed component) | Expected for a stale page; handle by removing the row or reloading |
+| **Nothing happens on click** | The `reactive` controller isn't registered, or a host catch-all route shadows `POST /reactive/actions` | `bin/rails phlex_reactive:doctor` names both — fix the ✗ |
+| **`importmap` 404 for the client** | The engine's pin was overridden | Re-add `pin "phlex/reactive/reactive_controller"`; doctor flags it |
+| **Component renders but never updates** | The root's `id` and `data-controller="reactive"` landed on DIFFERENT elements | Spread `**reactive_root` (binds id + controller + token to the same element) instead of `**reactive_attrs` on a child |
+
+## Reference vs live introspection
+
+- **Reference docs** (how a feature works, the API): the hosted docs MCP at
+  <https://phlex-reactive.zoolutions.llc/llms.txt> — search/read the published
+  guide.
+- **Live-app introspection** (what's in THIS app right now): the local
+  `phlex_reactive:mcp` server + the rake tasks + the browser `report()`.
+
+For transport-level problems (a broadcast never arrives over pgbus / Action
+Cable), reach for pgbus's own tooling (`pgbus doctor`, its MCP) — phlex-reactive
+is transport-agnostic and doesn't diagnose the wire.

data/lib/phlex/reactive/component/dsl.rb

@@ -58,6 +58,41 @@ module Phlex
             Registry.resolve_list(self, :state_keys, :reactive_state_keys)
           end
 
+          # Lazy initial mount (issue #165): the FIRST (page-embedded) render
+          # emits the placeholder shell + a defer token on the root; the client
+          # fetches the real content on connect. Reactive machinery renders
+          # (replies, broadcasts, the defer endpoint/job) stay REAL. Inherited
+          # by subclasses. See Component::Lazy.
+          #
+          # `tag:` sets the shell element (default :div). Set it to the real
+          # root's element for content that can't legally hold a <div> — a
+          # `reactive_lazy tag: :tr` component rooting at <tr> inside <tbody>
+          # ships a <tr> shell, not a <div> the HTML parser would hoist away.
+          def reactive_lazy(tag: :div)
+            Registry.write_scalar(self, :lazy, { tag: tag.to_sym })
+          end
+
+          # The RAW resolved lazy declaration ({ tag: } or nil) — the reader the
+          # Registry walks up the ancestry. It MUST return the stored value, not
+          # a boolean: resolve_scalar inherits whatever the superclass reader
+          # returns, so a boolean false would be inherited as the value and read
+          # back as "declared" (`!false.nil?` == true) — a subclass of any
+          # component would spuriously render the lazy shell.
+          def reactive_lazy_declaration
+            Registry.resolve_scalar(self, :lazy, :reactive_lazy_declaration)
+          end
+
+          def reactive_lazy?
+            !reactive_lazy_declaration.nil?
+          end
+
+          # The shell element tag for a lazy component (:div default), resolved
+          # through the registry so a subclass inherits the parent's choice.
+          def reactive_lazy_tag
+            value = reactive_lazy_declaration
+            value.is_a?(::Hash) ? value.fetch(:tag, :div) : :div
+          end
+
           # Declare a client-invokable action with an optional param schema.
           #   action :increment
           #   action :rename, params: { title: :string }
@@ -100,6 +135,41 @@ module Phlex
             reactive_actions.key?(name.to_sym)
           end
 
+          # Opt out of the default-ON verify_authorized guard (issue #168).
+          # Bare skips the WHOLE component (a public counter, a client-only
+          # filter); with names skips just those actions:
+          #
+          #   skip_verify_authorized                 # every action
+          #   skip_verify_authorized :filter, :page  # only these
+          #
+          # Registry #6 — resolves through the superclass at read time like the
+          # other five, so a child inherits a parent's skips (and a child's bare
+          # skip covers everything). Marks nothing else; a non-skipped action
+          # still needs a real authorization call or mark_authorized!.
+          def skip_verify_authorized(*names)
+            if names.empty?
+              Registry.write_scalar(self, :skip_all, true)
+            else
+              Registry.append(self, :skip_actions, names.map(&:to_sym))
+            end
+          end
+
+          def reactive_skip_all_authorization?
+            Registry.resolve_scalar(self, :skip_all, :reactive_skip_all_authorization?) == true
+          end
+
+          def reactive_skip_authorization_actions
+            Registry.resolve_list(self, :skip_actions, :reactive_skip_authorization_actions)
+          end
+
+          # Is verify_authorized skipped for `action_name`? True under a bare
+          # component skip OR when the action is in the named list — resolved
+          # through Registry so inheritance matches every other declaration.
+          def skip_verify_authorized?(action_name)
+            reactive_skip_all_authorization? ||
+              reactive_skip_authorization_actions.include?(action_name.to_sym)
+          end
+
           # Declare an add/remove-row collection (issue #35) — the list contract
           # in one place, so actions append/prepend/remove a row WITHOUT
           # re-deriving the container id, count, and empty-state in every action: