zoolutions/phlex-reactive/phlex-reactive-debugging

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)

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)

bin/rails phlex_reactive:actions            # every component × action: params, file:line, auth
bin/rails phlex_reactive:actions FORMAT=json
bin/rails phlex_reactive:actions UNVERIFIED=1   # only the unverified rows (the review queue)
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; skipped / skipped (class) = the author opted out with skip_verify_authorized (for that action / for the whole class); unverified = neither — a helper may still authorize indirectly.

3. Scan the live page (browser inspector)

In the browser console on the affected page:

(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"):

// .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

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.