npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

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 DELETED Viewed

@@ -1,177 +0,0 @@
----
-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 DELETED Viewed

@@ -1,337 +0,0 @@
----
-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
-```