← Commit history

pup-bridge-debug: relay-vs-direct-API verb subset gotcha (verb works from CLI but not from the bridge loopback)

John Lauer ·f06f794f08 ·3mo ago ·parent 9575add
1 file changed +16
dev-skills/pup-bridge-debug/SKILL.md+16
@@ -135,6 +135,22 @@ the user cannot tell a working click from a broken one. Give IMMEDIATE on-screen AD's `desktop_caption` (`{text, duration, id, position}` — reuse the same `id` so the "doing it…" caption is REPLACED by the result caption rather than stacking). +## §AD verb works from the CLI but NOT from pup (direct-API verb subset, found v1.9.10)++**Symptom:** an AD verb (e.g. `desktop_caption`) works perfectly when tested via `adom-desktop <verb>`+from the container, but pup's `chrome.adCommand('<verb>', …)` silently does nothing. **Cause: the two+paths hit DIFFERENT surfaces.** The container CLI goes through the **relay** (full verb set). pup's+loopback `chrome.adCommand` hits AD's **direct API** (`~/.adom/direct-api-port`, e.g. `:62521`),+which exposes only a SUBSET of built-in desktop verbs. A verb missing there answers+`"'X' is not a built-in desktop verb"` — and `adCommand` resolves `null` on failure, so an+error-swallowing caller sees nothing at all. Confirmed live: `desktop_caption` = relay-only;+`desktop_set_window_identity` / `desktop_taskbar` / `desktop_flash_window` = available on both.+**Rules:** (1) NEVER test a bridge's AD call with the container CLI and call it verified — replicate+the loopback (`curl.exe` POST to `http://127.0.0.1:<direct-api-port>/command` on the box). (2) LOG+`adCommand` results in new call sites — it returns `null`/error-objects, it never throws. (3) If the+verb is relay-only, either file the AD ask to add it to the direct API, or do it pup-side (e.g. the+in-page `wikiToast` DOM pill replaced `desktop_caption` for wiki-toggle feedback).+ ## ⚠ THE TESTING LESSON (this is how the bug above survived to the user)  **Test the ACTUAL entry point the user hits, not a convenient proxy for it.** The wiki toggle was