litclaude-ai 0.2.2

package/plugins/litclaude/skills/debugging/references/runtimes/node.md

@@ -0,0 +1,260 @@
+# Node.js / tsx / ts-node / Bun / Deno Debugging
+
+Covers Node 18+, tsx, ts-node, Bun, Deno. Launch recipes, inspector protocol usage, the `node inspect` CLI, and the **tsx source-map silent-failure** that costs people days.
+
+---
+
+## Environment detection (Phase 0)
+
+```bash
+node --version
+cat package.json | head -40
+
+# Which JS runtime launches the app? (order them; the first match wins)
+ls node_modules/.bin/tsx 2>/dev/null         && echo 'has tsx'
+ls node_modules/.bin/ts-node 2>/dev/null     && echo 'has ts-node'
+ls node_modules/.bin/vitest 2>/dev/null      && echo 'has vitest'
+which bun 2>/dev/null                        && bun --version
+which deno 2>/dev/null                       && deno --version
+
+# Source-map situation
+grep -E '"sourceMap"|"inlineSources"' tsconfig.json 2>/dev/null
+grep -l '//# sourceMappingURL' dist/*.js 2>/dev/null | head -3
+
+# Debug-relevant ports
+lsof -iTCP:9229 -sTCP:LISTEN -nP 2>/dev/null
+lsof -iTCP:9230 -sTCP:LISTEN -nP 2>/dev/null
+```
+
+---
+
+## 🚨 The tsx + `node inspect` CLI silent-failure (READ THIS)
+
+`tsx` transpiles each `.ts` file on the fly and emits an inline source map. V8 Inspector registers the module with its `.ts` path (so it shows up in the debugger's `scripts` list), **but the `node inspect` CLI REPL does not resolve source-map line numbers reliably**. Setting `sb('session.ts', 285)` will show a "pending" breakpoint that **never fires even after the module loads**.
+
+The breakpoint list will happily display it, so you think it's set. It isn't.
+
+### Three reliable workarounds
+
+| Workaround | When to use | Downside |
+|---|---|---|
+| **`debugger;` statement in source** | You can edit the source, CLI required | Requires source edit + revert |
+| **Chrome DevTools GUI** (`chrome://inspect`) | CLI not required, faster iteration | Not usable if user specifically asked for CLI |
+| **Debug the built `dist/` JS** | Source maps are working end-to-end | Requires `npm run build` on every source change |
+
+The `debugger;` statement is the most reliable. Journal the edit — revert at Phase 9.
+
+---
+
+## Launch recipes by runtime
+
+### Node (plain JS / compiled TS)
+
+```bash
+# Break on first line, wait for debugger to attach
+node --inspect-brk=9229 dist/index.js
+
+# Attach immediately, don't block startup — pair with debugger; statements
+node --inspect=9229 dist/index.js
+
+# Wait for debugger to attach, THEN run (new in Node 20.15+)
+node --inspect-wait=9229 dist/index.js
+
+# Source maps in stack traces (always a good idea in debug builds)
+node --enable-source-maps --inspect dist/index.js
+```
+
+### tsx
+
+```bash
+# The tsx runner is --import-compatible, so these work:
+node --inspect-brk=9229 --import tsx index.ts
+node --inspect=9229 --import tsx index.ts
+
+# If user prefers invoking tsx directly, this also works but is less explicit:
+NODE_OPTIONS='--inspect-brk=9229' npx tsx index.ts
+
+# ⚠️ tsx watch + inspector = inspector reloads per file change
+# Debug without watch:
+node --inspect=9229 --import tsx index.ts     # (no `watch`)
+```
+
+### ts-node (legacy but still encountered)
+
+```bash
+node --inspect-brk -r ts-node/register src/index.ts
+# ESM (ts-node's ESM loader is fragile — if possible, migrate to tsx):
+node --inspect --loader ts-node/esm src/index.ts
+```
+
+### Bun (WebKit Inspector Protocol, NOT V8)
+
+```bash
+bun --inspect src/index.ts                    # opens debug.bun.sh URL
+bun --inspect-brk src/index.ts                # break on start
+bun --inspect-wait src/index.ts               # wait for attach
+bun test --inspect-brk                        # debug test runner
+```
+
+**Critical**: Bun uses WebKit Inspector Protocol, not V8. `chrome://inspect` cannot connect directly. Use `debug.bun.sh` or the (currently buggy, per Bun docs) VS Code extension.
+
+### Deno (native V8, Chrome DevTools / VS Code compatible)
+
+```bash
+deno run --inspect-brk --allow-all src/main.ts
+deno test --inspect-brk --filter "auth"
+```
+
+Deno is the smoothest TS debugging experience — native V8 inspector, no source-map workarounds.
+
+### Vitest
+
+```bash
+# Single worker required — inspector can't attach to multiple workers
+vitest --inspect-brk --no-file-parallelism
+vitest --inspect-brk --browser --no-file-parallelism   # browser mode
+```
+
+Without `--no-file-parallelism`, breakpoints won't fire because the process Vitest spawns workers in isn't the one listening on the inspector port.
+
+---
+
+## Attaching with `node inspect` CLI
+
+```bash
+node inspect 127.0.0.1:9229         # attach to an existing --inspect process
+```
+
+Core commands at the `debug>` prompt:
+
+```
+cont, c                  resume until next break / debugger;
+next, n                  step over
+step, s                  step into
+out, o                   step out
+pause                    pause a running process
+bt                       backtrace
+scripts                  list all modules V8 has loaded (incl. tsx-transpiled .ts)
+sb(N)                    set breakpoint at line N of current file
+sb('file', N)            set breakpoint at line N of matching file (⚠️ unreliable with tsx)
+sb(func)                 set breakpoint at function reference
+cb(N), cb('file', N)     clear breakpoint
+breakpoints              list breakpoints (shows pending ones, doesn't tell you they'll never fire)
+watch('expr')            persistent watch expression
+watchers                 show watchers
+exec('expr')             evaluate expression in paused frame's scope
+repl                     drop into full REPL with frame's scope
+restart                  restart the debuggee
+kill                     kill the debuggee
+```
+
+**`exec('expr')` is the most powerful tool in this CLI** — it evaluates any JS in the paused frame and returns the value. Use it heavily.
+
+---
+
+## `exec()` patterns that resolve hypotheses fast
+
+At a breakpoint, these queries resolve most LLM / agent / async bugs in one line each:
+
+```js
+// Agent / LLM state
+exec('this.agent.state.messages.length')
+exec('this.agent.state.messages.map(m => m.role)')
+exec('JSON.stringify(this.agent.state.messages.at(-1)).substring(0, 500)')
+exec('this.agent.state.messages.at(-1).errorMessage')      // silent-error sentinel
+exec('this.agent.state.messages.at(-1).stopReason')
+exec('JSON.stringify(this.agent.state.usage)')             // undefined / all-zero = failed call
+exec('this.agent.state.model.baseUrl')                     // catch hardcoded vs env-var
+
+// Env / config at runtime
+exec('process.env.RELEVANT_VAR')
+exec('Object.keys(process.env).filter(k => k.startsWith("ANTHROPIC"))')
+exec('this.config')
+
+// Async / timing
+exec('Date.now() - this._turnStartedAt')
+exec('this._activePromises?.size')
+
+// HTTP request/response in-flight
+exec('JSON.stringify(req.body).length')
+exec('res.statusCode')
+exec('res.headersSent')
+
+// What's actually running
+exec('process.version')
+exec('process.cwd()')
+exec('process.argv')
+```
+
+---
+
+## Silent-failure patterns in Node
+
+These are the patterns that most commonly look like success but aren't. Always check when a response is "too fast" or "too empty":
+
+| Signal | What it means |
+|---|---|
+| HTTP 200 + `content: ""` | Silent error swallowed |
+| HTTP 200 + response in <1s for an LLM call | Too fast for a real Claude/GPT call; something short-circuited |
+| `usage: { totalTokens: 0 }` | LLM SDK returned a stub without making the call |
+| `stopReason: "error" + content: []` | SDK packaged an error into a "success" message |
+| Unhandled promise rejection with no log | Caller forgot to `await`, or `.catch(() => {})` |
+| `try { await x(); } catch {}` | Error eaten, no log |
+| `void somePromise()` | Explicit opt-out of error propagation; often a bug |
+| Callback-style API where callback never fires | Error happened before callback scheduled |
+| Handler returns `res.json(...)` twice | Second call is silent on some Express versions |
+
+When you find one, add a temporary `console.error('[DEBUG]', ...)` to make it loud — journal it, revert at Phase 9.
+
+---
+
+## tmux session layout (two sessions, one purpose each)
+
+```bash
+# Long-running inspected process
+tmux new-session -d -s debug-server -c "$PWD"
+tmux send-keys -t debug-server 'node --inspect=9229 --import tsx index.ts' Enter
+
+# Interactive debugger client (separate pane for readability)
+tmux new-session -d -s debug-client -c "$PWD"
+tmux send-keys -t debug-client 'node inspect 127.0.0.1:9229' Enter
+
+# Non-blocking pane inspection from the outside
+tmux capture-pane -p -t debug-server -S -50
+```
+
+Journal both session names. Kill both at Phase 9:
+
+```bash
+tmux kill-session -t debug-server
+tmux kill-session -t debug-client
+```
+
+---
+
+## When to abandon the CLI and switch to Chrome DevTools
+
+The user's preference for CLI is valid and should be respected. But you may recommend a switch in one short sentence if ANY of these hold:
+
+- You hit source-map resolution failures (`sb('file', line)` not firing) AND the fix is time-sensitive
+- You need to watch many values simultaneously (GUI watch panel is faster to scan)
+- You're stepping through async-heavy code where CLI step semantics get murky across microtask boundaries
+
+Phrase as a note, not a request: "I can push through with `debugger;` statements in CLI. If we hit three or more of these in a row, switching to `chrome://inspect` GUI would cut cycle time in half — your call."
+
+---
+
+## Phase 9 cleanup specifics
+
+```bash
+# Revert source-level debug statements
+git diff | grep -E '(debugger;|console\.log\(.*DEBUG|\[ARBITER-DEBUG|\[DEBUG)'
+# Revert any matching files:
+git checkout <file>
+
+# Kill inspector-attached processes
+pkill -f 'node --inspect' || true
+pkill -f 'bun --inspect' || true
+pkill -f 'deno.*--inspect' || true
+lsof -iTCP:9229 -sTCP:LISTEN -nP 2>/dev/null
+```

package/plugins/litclaude/skills/debugging/references/runtimes/python.md

@@ -0,0 +1,248 @@
+# Python Debugging
+
+Covers CPython 3.9+, pytest, asyncio, Django, FastAPI. Setup commands, attach mechanisms, state-query patterns, gotchas, silent-failure signatures.
+
+---
+
+## Environment detection (Phase 0)
+
+```bash
+# Which Python will actually run the code?
+which python; which python3
+python --version
+
+# Is there a project env manager in play?
+ls poetry.lock uv.lock Pipfile.lock requirements*.txt .python-version 2>/dev/null
+
+# Installed debuggers / profilers in this env?
+python -c 'import pdb, sys; print("pdb", "built-in"); print("python", sys.executable)'
+pip list 2>/dev/null | grep -iE '^(ipdb|pudb|debugpy|py-spy|memray|rich)\s'
+
+# asyncio debug mode available?
+python -c 'import asyncio; print(asyncio.__version__)'
+```
+
+**Wrapper gotchas** (these change how flags propagate):
+
+- `poetry run python ...` — args after `python` are fine; args before `poetry run` go to poetry, not python
+- `uv run python ...` — similar; prefer `uv run -- python -X dev` if flags collide
+- `pipenv run` — same story
+- `./manage.py <cmd>` (Django) — shebang resolution; make sure it points to the right venv
+- `pytest` — loads `conftest.py` at collection; breakpoints inside collection need `pytest --pdb-trace` not `--pdb`
+
+---
+
+## The four ways to attach
+
+| Method | When to use | Command |
+|---|---|---|
+| **`breakpoint()` inline** (Python 3.7+) | You can edit the source and restart. Most reliable. | Add `breakpoint()` to source. Run normally. It invokes `pdb` by default. |
+| **`python -m pdb <script>`** | No source edit desired. Breaks on entry. | `python -m pdb script.py arg1` |
+| **post-mortem `pdb.pm()`** | Exception already happened, you want to inspect state | In an exception-caught REPL: `import pdb; pdb.pm()` after the exception propagates |
+| **debugpy (remote / IDE)** | IDE attach, remote host, containerized process | `python -m debugpy --listen 5678 --wait-for-client script.py` then attach from VS Code / PyCharm |
+
+### Prefer `ipdb` or `pudb` over plain `pdb` when available
+
+- **ipdb** — drop-in replacement with tab completion, syntax highlighting. `pip install ipdb`, then `PYTHONBREAKPOINT=ipdb.set_trace` or use `import ipdb; ipdb.set_trace()`.
+- **pudb** — full-screen TUI debugger, much faster to navigate stack/locals. `pip install pudb`, then `PYTHONBREAKPOINT=pudb.set_trace`.
+
+### Control `breakpoint()` globally
+
+```bash
+# Use ipdb instead of pdb
+export PYTHONBREAKPOINT=ipdb.set_trace
+
+# Disable all breakpoint() calls (useful to ship without removing them)
+export PYTHONBREAKPOINT=0
+```
+
+**Journal this env var** — unset at Phase 9.
+
+---
+
+## pdb / ipdb essentials
+
+At a `(Pdb)` or `ipdb>` prompt:
+
+```
+l           list source around current line
+ll          list whole function
+s           step into
+n           step over (next)
+r           step out (return)
+c           continue
+b           list breakpoints
+b <line>    breakpoint at line
+b <func>    breakpoint at function
+cl <n>      clear breakpoint n
+w           where (backtrace)
+u / d       move up/down the stack
+a           args of current frame
+p <expr>    print expression
+pp <expr>   pretty-print
+!<stmt>     execute Python statement (e.g. !x = 5)
+interact    drop into a full Python REPL with current frame's locals
+q           quit (aborts the program)
+```
+
+**`interact` is underused** — it gives you a full IPython-esque REPL with all locals available. Faster than typing `p` for 20 things.
+
+---
+
+## pytest-specific debugging
+
+```bash
+# Enter pdb on first failure
+pytest --pdb
+
+# Enter pdb at the START of each test (not on failure)
+pytest --trace
+
+# Run only the failing test, with -s to show print output
+pytest --pdb -x -s path/to/test.py::test_name
+
+# Collect-time debugging (for problems in conftest.py / fixture setup)
+pytest --pdb-trace
+
+# Disable capture for this test (so breakpoint prompt is visible)
+pytest -s
+```
+
+**Common failure**: `breakpoint()` hangs inside a pytest test — that's because pytest captures stdout/stderr by default. Always add `-s` when debugging with breakpoints inside pytest.
+
+---
+
+## asyncio gotchas
+
+Async is where most Python debug sessions go sideways. Know these before attaching.
+
+### Breakpoints inside coroutines
+
+`breakpoint()` works inside an async function, but stepping into another coroutine from `pdb` is awkward. Two techniques:
+
+```python
+async def handler():
+    result = await some_async_fn()  # add breakpoint ABOVE, not inside, when possible
+    breakpoint()
+    return result
+```
+
+Inside the breakpoint, to inspect a coroutine without actually advancing time:
+```
+!import asyncio
+!loop = asyncio.get_event_loop()
+!task = asyncio.ensure_future(some_async_fn())
+# Now inspect task state, don't await it
+p task
+```
+
+### PYTHONASYNCIODEBUG
+
+Enable before running the process:
+
+```bash
+PYTHONASYNCIODEBUG=1 python script.py
+```
+
+Surfaces: coroutines that were never awaited, slow callbacks, unhandled task exceptions. **Always turn this on** if the bug is timing- or async-related.
+
+### `asyncio.gather` swallows the first exception
+
+By default, `asyncio.gather(t1, t2)` raises the first exception and cancels the rest. If you need all exceptions, use `gather(..., return_exceptions=True)`.
+
+### Unhandled task exceptions are silent
+
+```python
+async def main():
+    task = asyncio.create_task(broken_coroutine())
+    # If task raises and we never await it, the exception is eaten at gc time
+    await asyncio.sleep(10)
+```
+
+To catch these, set `loop.set_exception_handler(...)` or upgrade to Python 3.12+ which warns louder by default.
+
+---
+
+## debugpy — remote / IDE / container attach
+
+Listen and wait for attach:
+
+```bash
+python -m debugpy --listen 0.0.0.0:5678 --wait-for-client script.py
+```
+
+Attach from VS Code:
+```json
+// .vscode/launch.json
+{
+  "name": "attach",
+  "type": "python",
+  "request": "attach",
+  "connect": { "host": "localhost", "port": 5678 }
+}
+```
+
+Inside the code, programmatic attach point:
+```python
+import debugpy
+debugpy.listen(5678)
+debugpy.wait_for_client()  # blocks until attached
+debugpy.breakpoint()        # programmatic breakpoint
+```
+
+**Journal**: the port (5678) and the listener file — unset at Phase 9.
+
+---
+
+## Sampling profilers for "why is it slow / stuck"
+
+When the problem is performance or a hang (not a crash), don't attach pdb — it alters timing. Use a sampling profiler that attaches to the running process:
+
+```bash
+# py-spy — production-safe, zero code change, works on running process
+py-spy top --pid <pid>                       # live top-like view
+py-spy record -o profile.svg --pid <pid>     # flamegraph
+py-spy dump --pid <pid>                      # stack traces of all threads right now
+
+# memray — memory allocation tracking
+memray run script.py
+memray flamegraph output.bin
+memray stats output.bin
+```
+
+`py-spy dump` on a stuck process is often enough to find the hung call — no breakpoints needed.
+
+---
+
+## Silent-failure patterns in Python
+
+Add these to Phase 8's silent-failure check:
+
+| Pattern | Why it's silent |
+|---|---|
+| `except Exception: pass` or `except: pass` | Catches and discards every error including KeyboardInterrupt |
+| `logging.exception(...)` in a logger with no handlers | "Logs" but actually writes nowhere |
+| `asyncio.create_task(coro)` without storing the task | Task GC'd before completion, exception swallowed |
+| `return x.get("key")` where key is missing | Returns None silently, caller often doesn't check |
+| `subprocess.run(..., check=False)` with ignored returncode | Non-zero exit treated as success |
+| Django `transaction.atomic()` inside a broader `except` | Rolls back silently |
+| `contextlib.suppress(Exception)` | Explicit silencer; easy to leave wider than intended |
+| `queue.get(block=False)` with `except queue.Empty: pass` | Polling that silently drops the work |
+
+---
+
+## Phase 9 cleanup specifics
+
+```bash
+# Remove breakpoint() / ipdb / pudb lines from source
+git diff | grep -E '(breakpoint\(\)|import ipdb|import pudb|import pdb; pdb\.set_trace)'
+# If the above has output, revert those files:
+git checkout <file>
+
+# Unset the global breakpoint override
+unset PYTHONBREAKPOINT
+
+# Kill any leftover debugpy listeners
+pkill -f 'debugpy' || true
+lsof -iTCP:5678 -sTCP:LISTEN -nP 2>/dev/null    # confirm free
+```