better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/software-development/software-development-inspecting-hermes-desktop-dom.md

@@ -0,0 +1,177 @@
+---
+title: "Inspecting Hermes Desktop Dom — Read the live Hermes desktop DOM/CSS over CDP"
+sidebar_label: "Inspecting Hermes Desktop Dom"
+description: "Read the live Hermes desktop DOM/CSS over CDP"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Inspecting Hermes Desktop Dom
+
+Read the live Hermes desktop DOM/CSS over CDP.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/software-development\inspecting-hermes-desktop-dom` |
+| Version | `1.0.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `desktop`, `electron`, `cdp`, `dom`, `ui-verification`, `self-inspection` |
+| Related skills | [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`dogfood`](/docs/user-guide/skills/bundled/software-development/software-development-dogfood) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Inspecting the live Hermes desktop DOM
+
+## Overview
+
+When you are developing `apps/desktop` and the user is running that same app
+(`hgui` / `npm run dev`), you can read the **live rendered DOM** of the window
+they are looking at — computed styles, geometry, which CSS rule actually won,
+console output — instead of inferring it from `.tsx` and being wrong.
+
+Dev-server runs open a Chrome DevTools Protocol port on `127.0.0.1:9222`
+automatically. The renderer is a Chromium page, so everything DevTools can read,
+a script can read.
+
+**This does not replace looking at it.** CDP answers *factual* questions ("what
+is the computed padding", "did this element render", "which selector matches").
+It cannot tell you whether the result looks good. Colour balance, spacing feel,
+and "is this ugly" still need the user's eyes or a screenshot. Answer facts with
+CDP; hand aesthetics to the user.
+
+## When to Use
+
+- Verifying a UI change actually took effect in the running app
+- "Why is this element still X?" — find the winning rule before editing anything
+- Locating a stable selector for a component you're about to change
+- Checking a design token's computed value on a real node
+- Reading renderer console errors the user mentions but can't copy out
+
+**Don't use for:** perf profiling or heap work (`node-inspect-debugger`,
+`debugging-hermes-desktop`), or anything where the real question is "does this
+look right".
+
+## The port
+
+Open on `127.0.0.1:9222` for any dev-server run. Closed in exactly two cases
+(`apps/desktop/electron/dev-cdp.ts`):
+
+- **packaged builds** — always, and no environment value overrides it;
+- **no `HERMES_DESKTOP_DEV_SERVER`** — an unpackaged `electron .` against
+  `dist/` is how the packaged app gets smoke tested, so it behaves like one.
+
+`HERMES_DESKTOP_CDP_PORT` moves the port (`=9333`) or disables it (`=off`).
+
+Check before doing anything else:
+
+```bash
+curl -s --max-time 3 http://127.0.0.1:${HERMES_DESKTOP_CDP_PORT:-9222}/json/version
+```
+
+Empty → no port. Do not guess another port silently.
+
+**Never relaunch the user's app to get a port.** That destroys their session and
+their state. Launch your own isolated instance instead (below).
+
+## Reading the DOM
+
+`apps/desktop/scripts/eval.mjs` is the one-liner:
+
+```bash
+cd apps/desktop
+node scripts/eval.mjs "document.querySelectorAll('[data-slot]').length"
+```
+
+For multi-step work use the shared client — it has target discovery and
+promise-aware eval:
+
+```js
+import { CDP, SELECTORS } from './scripts/perf/lib/cdp.mjs'
+
+const cdp = await CDP.connect({ port: 9222, match: '5174' })
+const out = await cdp.eval(`JSON.stringify({
+  radius: getComputedStyle(document.documentElement).getPropertyValue('--radius-scalar').trim(),
+  composer: !!document.querySelector('[data-slot="composer-rich-input"]')
+})`)
+cdp.close()
+```
+
+`SELECTORS` in `scripts/perf/lib/cdp.mjs` holds the stable `data-slot` hooks
+(composer, thread viewport, assistant message, turn pair, profile rail). Prefer
+them over inventing a `querySelector` — they are updated as a unit when
+components move.
+
+## The question this is best at: which rule won?
+
+Editing every call site because a style "isn't applying" is the classic waste.
+Read the real node first:
+
+```js
+const el = document.querySelector('[data-slot="aui_assistant-message-root"] a')
+JSON.stringify({
+  ownClasses: el.className,
+  weight: getComputedStyle(el).fontWeight,
+  parents: (() => {
+    const out = []
+    let n = el
+    while ((n = n.parentElement) && out.length < 6) out.push(n.className)
+    return out
+  })()
+})
+```
+
+If the node carries no class of its own, the value is **inherited** — sweeping
+call sites will not fix it, and you need the ancestor rule. A plugin stylesheet
+(e.g. `@tailwindcss/typography`'s `prose a { font-weight: 500 }`) routinely beats
+a utility class; override on the shared class, not at each usage.
+
+## Your own isolated instance
+
+When there is no port, or you must not disturb the user's window:
+
+```bash
+cd apps/desktop
+HERMES_HOME=/tmp/cdp-probe-home \
+HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 \
+HERMES_DESKTOP_CDP_PORT=9333 \
+  npx electron . --user-data-dir=/tmp/cdp-probe-userdata
+```
+
+The separate `--user-data-dir` dodges Electron's single-instance lock, so it
+cannot collide with a running `hgui`; the separate `HERMES_HOME` keeps it away
+from real sessions. Pick a port other than 9222 for the same reason. Run it in
+the background and kill it when done.
+
+`npm run perf:serve` does the same with a temp `HERMES_HOME` baked in, if you
+also want the perf harness.
+
+## Pitfalls
+
+- **Never kill the user's dev server or app to "free" anything.** A mid-serve
+  kill nukes Chromium's socket pool, and the resulting `ERR_NETWORK_CHANGED`
+  gets blamed on whatever you just changed.
+- **A throwaway `HERMES_HOME` has no backend.** The app logs `ECONNREFUSED` for
+  `hermes:api` and may exit on its own. The renderer still mounts and the DOM is
+  readable — read promptly, and don't mistake a self-exited probe for a broken
+  port. Chromium logs `DevTools listening on ws://127.0.0.1:<port>/…` when it
+  binds; that line is the proof the port opened.
+- **Poll, don't probe once.** A just-launched app needs a second or two before
+  the port answers.
+- **Never dump the whole DOM.** The desktop renders hundreds of nodes and
+  `outerHTML` will bury your context. Project down to a small JSON object inside
+  the evaluated expression.
+- **Pass `match` to `CDP.connect`.** Without it you may attach to the pet
+  overlay, quick-entry window, or a devtools target instead of the main window.
+- **`cdp.eval` returns the value; raw `Runtime.evaluate` double-nests it**
+  (`.result.result.value`). Use the wrapper.
+- **`import.meta.env.DEV` is `true` under `vite dev`** in this repo. The note in
+  `apps/desktop/scripts/profile-typing-lag.md` claiming otherwise is stale.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md

@@ -0,0 +1,337 @@
+---
+title: "Node Inspect Debugger — Debug Node.js via --inspect + Chrome DevTools Protocol CLI"
+sidebar_label: "Node Inspect Debugger"
+description: "Debug Node.js via --inspect + Chrome DevTools Protocol CLI"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Node Inspect Debugger
+
+Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/software-development\node-inspect-debugger` |
+| Version | `1.0.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
+| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Node.js Inspect Debugger
+
+## Overview
+
+When `console.log` isn't enough, drive Node's built-in V8 inspector programmatically from the terminal. You get real breakpoints, step in/over/out, call-stack walking, local/closure scope dumps, and arbitrary expression evaluation in the paused frame.
+
+Two tools, pick one:
+
+- **`node inspect`** — built-in, zero install, CLI REPL. Best for quick poking.
+- **`ndb` / CDP via `chrome-remote-interface`** — scriptable from Node/Python; best when you want to automate many breakpoints, collect state across runs, or debug non-interactively from an agent loop.
+
+**Prefer `node inspect` first.** It's always available and the REPL is fast.
+
+## When to Use
+
+- A Node test fails and you need to see intermediate state
+- ui-tui crashes or behaves wrong and you want to inspect React/Ink state pre-render
+- tui_gateway child processes (`_SlashWorker`, PTY bridge workers) misbehave
+- You need to inspect a value in a closure that `console.log` can't reach without patching
+- Perf: attach to a running process to capture a CPU profile or heap snapshot
+
+**Don't use for:** things `console.log` solves in under a minute. Breakpoint-driven debugging is heavier; use it when the payoff is real.
+
+## Quick Reference: `node inspect` REPL
+
+Launch paused on first line:
+
+```bash
+node inspect path/to/script.js
+# or with tsx
+node --inspect-brk $(which tsx) path/to/script.ts
+```
+
+The `debug>` prompt accepts:
+
+| Command | Action |
+|---|---|
+| `c` or `cont` | continue |
+| `n` or `next` | step over |
+| `s` or `step` | step into |
+| `o` or `out` | step out |
+| `pause` | pause running code |
+| `sb('file.js', 42)` | set breakpoint at file.js line 42 |
+| `sb(42)` | set breakpoint at line 42 of current file |
+| `sb('functionName')` | break when function is called |
+| `cb('file.js', 42)` | clear breakpoint |
+| `breakpoints` | list all breakpoints |
+| `bt` | backtrace (call stack) |
+| `list(5)` | show 5 lines of source around current position |
+| `watch('expr')` | evaluate expr on every pause |
+| `watchers` | show watched expressions |
+| `repl` | drop into REPL in current scope (Ctrl+C to exit REPL) |
+| `exec expr` | evaluate expression once |
+| `restart` | restart script |
+| `kill` | kill the script |
+| `.exit` | quit debugger |
+
+**In the `repl` sub-mode:** type any JS expression, including access to locals/closure variables. `Ctrl+C` exits back to `debug>`.
+
+## Attaching to a Running Process
+
+When the process is already running (e.g. a long-lived dev server or the TUI gateway):
+
+```bash
+# 1. Send SIGUSR1 to enable the inspector on an existing process
+kill -SIGUSR1 <pid>
+# Node prints: Debugger listening on ws://127.0.0.1:9229/<uuid>
+
+# 2. Attach the debugger CLI
+node inspect -p <pid>
+# or by URL
+node inspect ws://127.0.0.1:9229/<uuid>
+```
+
+To start a process with the inspector from the beginning:
+
+```bash
+node --inspect script.js           # listen on 127.0.0.1:9229, keep running
+node --inspect-brk script.js       # listen AND pause on first line
+node --inspect=0.0.0.0:9230 script.js   # custom host:port
+```
+
+For TypeScript via tsx:
+
+```bash
+node --inspect-brk --import tsx script.ts
+# or older tsx
+node --inspect-brk -r tsx/cjs script.ts
+```
+
+## Programmatic CDP (scripting from terminal)
+
+When you want to automate — set many breakpoints, capture scope state, script a repro — use `chrome-remote-interface`:
+
+```bash
+npm i -g chrome-remote-interface        # or project-local
+# Start your target:
+node --inspect-brk=9229 target.js &
+```
+
+Driver script (save as `/tmp/cdp-debug.js`):
+
+```javascript
+const CDP = require('chrome-remote-interface');
+
+(async () => {
+  const client = await CDP({ port: 9229 });
+  const { Debugger, Runtime } = client;
+
+  Debugger.paused(async ({ callFrames, reason }) => {
+    const top = callFrames[0];
+    console.log(`PAUSED: ${reason} @ ${top.url}:${top.location.lineNumber + 1}`);
+
+    // Walk scopes for locals
+    for (const scope of top.scopeChain) {
+      if (scope.type === 'local' || scope.type === 'closure') {
+        const { result } = await Runtime.getProperties({
+          objectId: scope.object.objectId,
+          ownProperties: true,
+        });
+        for (const p of result) {
+          console.log(`  ${scope.type}.${p.name} =`, p.value?.value ?? p.value?.description);
+        }
+      }
+    }
+
+    // Evaluate an expression in the paused frame
+    const { result } = await Debugger.evaluateOnCallFrame({
+      callFrameId: top.callFrameId,
+      expression: 'typeof state !== "undefined" ? JSON.stringify(state) : "n/a"',
+    });
+    console.log('state =', result.value ?? result.description);
+
+    await Debugger.resume();
+  });
+
+  await Runtime.enable();
+  await Debugger.enable();
+
+  // Set a breakpoint by URL regex + line
+  await Debugger.setBreakpointByUrl({
+    urlRegex: '.*app\\.tsx$',
+    lineNumber: 119,       // 0-indexed
+    columnNumber: 0,
+  });
+
+  await Runtime.runIfWaitingForDebugger();
+})();
+```
+
+Run it:
+
+```bash
+node /tmp/cdp-debug.js
+```
+
+Hermes-specific note: `chrome-remote-interface` is NOT in `ui-tui/package.json`. Install it to a throwaway location if you don't want to dirty the project:
+
+```bash
+mkdir -p /tmp/cdp-tools && cd /tmp/cdp-tools && npm i chrome-remote-interface
+NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.js
+```
+
+## Debugging Hermes ui-tui
+
+The TUI is built Ink + tsx. Two common scenarios:
+
+### Debugging a single Ink component under dev
+
+`ui-tui/package.json` has `npm run dev` (tsx --watch). Add `--inspect-brk` by running tsx directly:
+
+```bash
+cd <hermes-agent-repo>/ui-tui
+npm run build    # produce dist/ once so transpile isn't needed on first load
+node --inspect-brk dist/entry.js
+# In another terminal:
+node inspect -p <node pid>
+```
+
+Then inside `debug>`:
+
+```
+sb('dist/app.js', 220)     # or wherever the suspect render is
+cont
+```
+
+When it pauses, `repl` → inspect `props`, state refs, `useInput` handler values, etc.
+
+### Debugging a running `hermes --tui`
+
+The TUI spawns Node from the Python CLI. Easiest path:
+
+```bash
+# 1. Launch TUI
+hermes --tui &
+TUI_PID=$(pgrep -f 'ui-tui/dist/entry' | head -1)
+
+# 2. Enable inspector on that Node PID
+kill -SIGUSR1 "$TUI_PID"
+
+# 3. Find the WS URL
+curl -s http://127.0.0.1:9229/json/list | jq -r '.[0].webSocketDebuggerUrl'
+
+# 4. Attach
+node inspect ws://127.0.0.1:9229/<uuid>
+```
+
+Interacting with the TUI (typing in its window) continues to advance execution; your debugger can pause it on a breakpoint at any `sb(...)`.
+
+### Debugging `_SlashWorker` / PTY child processes
+
+Those are Python, not Node — use the `python-debugpy` skill for them. Only Node portions (Ink UI, tui_gateway client, tsx-run tests under `ui-tui/`) use this skill.
+
+## Running Vitest Tests Under the Debugger
+
+```bash
+cd <hermes-agent-repo>/ui-tui
+# Run a single test file paused on entry
+node --inspect-brk ./node_modules/vitest/vitest.mjs run --no-file-parallelism src/app/foo.test.tsx
+```
+
+In another terminal: `node inspect -p <pid>`, then `sb('src/app/foo.tsx', 42)`, `cont`.
+
+Use `--no-file-parallelism` (vitest) or `--runInBand` (jest) so only one worker exists — debugging a pool is painful.
+
+## Heap Snapshots & CPU Profiles (Non-interactive)
+
+From the CDP driver above, swap Debugger for `HeapProfiler` / `Profiler`:
+
+```javascript
+// CPU profile for 5 seconds
+await client.Profiler.enable();
+await client.Profiler.start();
+await new Promise(r => setTimeout(r, 5000));
+const { profile } = await client.Profiler.stop();
+require('fs').writeFileSync('/tmp/cpu.cpuprofile', JSON.stringify(profile));
+// Open /tmp/cpu.cpuprofile in Chrome DevTools → Performance tab
+```
+
+```javascript
+// Heap snapshot
+await client.HeapProfiler.enable();
+const chunks = [];
+client.HeapProfiler.addHeapSnapshotChunk(({ chunk }) => chunks.push(chunk));
+await client.HeapProfiler.takeHeapSnapshot({ reportProgress: false });
+require('fs').writeFileSync('/tmp/heap.heapsnapshot', chunks.join(''));
+```
+
+## Common Pitfalls
+
+1. **Wrong line numbers in TS source.** Breakpoints hit the emitted JS, not the `.ts`. Either (a) break in the built `dist/*.js`, or (b) enable sourcemaps (`node --enable-source-maps`) and use `sb('src/app.tsx', N)` — but only with CDP clients that follow sourcemaps. `node inspect` CLI does not.
+
+2. **`--inspect` vs `--inspect-brk`.** `--inspect` starts the inspector but doesn't pause; your script races past your first breakpoint if you attach too late. Use `--inspect-brk` when you need to set breakpoints before any code runs.
+
+3. **Port collisions.** Default is `9229`. If multiple Node processes are inspecting, pass `--inspect=0` (random port) and read the actual URL from `/json/list`:
+   ```bash
+   curl -s http://127.0.0.1:9229/json/list   # lists all inspectable targets on the host
+   ```
+
+4. **Child processes.** `--inspect` on a parent does NOT inspect its children. Use `NODE_OPTIONS='--inspect-brk' node parent.js` to propagate to every child; be aware they all need unique ports (Node auto-increments when `NODE_OPTIONS='--inspect'` is inherited).
+
+5. **Background kills.** If you `Ctrl+C` out of `node inspect` while the target is paused, the target stays paused. Either `cont` first, or `kill` the target explicitly.
+
+6. **Running `node inspect` through an agent terminal.** It's a PTY-friendly REPL. In Hermes, launch it with `terminal(pty=true)` or `background=true` + `process(action='submit', data='...')`. Non-PTY foreground mode will work for one-shot commands but not for interactive stepping.
+
+7. **Security.** `--inspect=0.0.0.0:9229` exposes arbitrary code execution. Always bind to `127.0.0.1` (the default) unless you have an isolated network.
+
+## Verification Checklist
+
+After setting up a debug session, verify:
+
+- [ ] `curl -s http://127.0.0.1:9229/json/list` returns exactly the target you expect
+- [ ] First breakpoint actually hits (if it doesn't, you likely missed `--inspect-brk` or attached after execution completed)
+- [ ] Source listing at pause shows the right file (mismatch = sourcemap issue, see pitfall 1)
+- [ ] `exec process.pid` in `repl` returns the PID you meant to attach to
+
+## One-Shot Recipes
+
+**"Why is this variable undefined at line X?"**
+```bash
+node --inspect-brk script.js &
+node inspect -p $!
+# debug>
+sb('script.js', X)
+cont
+# paused. Now:
+repl
+> myVariable
+> Object.keys(this)
+```
+
+**"What's the call path into this function?"**
+```
+debug> sb('suspectFn')
+debug> cont
+# paused on entry
+debug> bt
+```
+
+**"This async chain hangs — where?"**
+```
+# Start with --inspect (no -brk), let it run to the hang, then:
+debug> pause
+debug> bt
+# Now you see the stuck frame
+```