@litfamily/litmuse 0.0.0-stage → 0.1.0

package/plugin/skills/debugging/references/runtimes/rust.md

@@ -0,0 +1,234 @@
+# Rust Debugging
+
+Covers `cargo`, `tokio`, panics, and the fact that you usually don't actually need a debugger — Rust's type system, `dbg!`, and logging cover 80% of sessions faster than gdb would.
+
+---
+
+## Environment detection (Phase 0)
+
+```bash
+cargo --version
+rustc --version
+cat rust-toolchain.toml rust-toolchain 2>/dev/null
+cat Cargo.toml | head -30
+
+# Debuggers available
+which rust-gdb
+which rust-lldb
+which lldb
+
+# Async infrastructure
+grep -E '"(tokio|async-std|smol)"' Cargo.toml
+
+# Profile flags
+grep -E '^\[profile' Cargo.toml
+```
+
+**The default `cargo run` builds with `dev` profile** which includes debug symbols. `cargo run --release` strips them. For debugging, stay in dev unless the bug only manifests under optimization.
+
+---
+
+## The Rust debugging hierarchy (use in this order)
+
+Rust's ecosystem has a specific order that's faster than reaching for gdb first:
+
+1. **`dbg!(expr)` macro** — for a single value at a specific spot. Prints file:line + value, returns the value unchanged so you can inline it. Faster than a debugger for 60% of bugs.
+2. **`RUST_LOG=trace` with `tracing` / `env_logger`** — for flow and state across an operation. Zero code change in dev-time.
+3. **`RUST_BACKTRACE=1` / `=full`** — for crashes. Almost always sufficient; you rarely need a live debugger for a panic.
+4. **`rust-gdb` / `rust-lldb`** — when you need to pause execution and inspect memory, especially for unsafe code or FFI.
+5. **`tokio-console`** — for async deadlocks, stuck tasks, hot loops.
+6. **`cargo-expand`** — when a macro is doing something weird.
+
+Reach for the lightest tool that answers the hypothesis.
+
+---
+
+## `dbg!` — the underused macro
+
+```rust
+let x = 5;
+let y = dbg!(x * 2);   // prints: [src/main.rs:2] x * 2 = 10
+```
+
+Inside a complex expression:
+```rust
+let total = items.iter().filter(|i| i.active).map(|i| dbg!(i.cost)).sum::<u64>();
+```
+
+Multiple values at once:
+```rust
+dbg!(&user, &request, elapsed.as_millis());
+```
+
+`dbg!` writes to stderr, so it won't corrupt stdout-based pipelines. **Journal each `dbg!` you add**; revert at Phase 9.
+
+---
+
+## `RUST_LOG` for flow-level debugging
+
+If the codebase uses `tracing` or `env_logger`:
+
+```bash
+RUST_LOG=debug cargo run
+RUST_LOG=trace cargo run                          # very verbose
+RUST_LOG=my_crate=trace,hyper=info cargo run      # per-module level
+RUST_LOG=debug,tokio=off cargo run                # silence noisy crates
+```
+
+For `tracing`-based apps, instrument with spans:
+```rust
+#[tracing::instrument]
+fn handle_request(req: &Request) -> Response { ... }
+```
+
+This gives you structured per-call entry/exit logs with args and timing, zero additional code in the body.
+
+---
+
+## `RUST_BACKTRACE` for panics
+
+```bash
+RUST_BACKTRACE=1 cargo run       # backtrace on panic
+RUST_BACKTRACE=full cargo run    # include libstd/tokio frames
+```
+
+The panic itself usually tells you the file:line. The backtrace tells you how it got there. Between the two, most crash bugs are solved without a debugger.
+
+---
+
+## rust-gdb / rust-lldb
+
+### Launch
+
+```bash
+# Build with debug symbols (default dev profile)
+cargo build
+
+# Attach gdb wrapper (applies Rust type pretty-printers)
+rust-gdb ./target/debug/my_binary
+# Or lldb:
+rust-lldb ./target/debug/my_binary
+
+# With args
+rust-gdb --args ./target/debug/my_binary arg1 arg2
+
+# Attach to running process
+rust-gdb -p $(pgrep my_binary)
+```
+
+### Breakpoints
+
+Rust symbols are mangled. Use either:
+
+```
+(gdb) b main                                  # main function
+(gdb) b my_crate::module::function            # canonical path
+(gdb) b src/handler.rs:42                     # file:line
+(gdb) info functions my_function              # find mangled name
+```
+
+### State inspection
+
+```
+(gdb) p x                        # print value (uses Rust pretty-printer for Vec, Option, HashMap, etc.)
+(gdb) p *ptr                     # deref
+(gdb) info locals                # all locals in current frame
+(gdb) info args                  # function args
+(gdb) bt                         # backtrace
+(gdb) frame <n>                  # switch to stack frame n
+(gdb) watch my_var               # stop when my_var changes
+(gdb) rbreak regex               # breakpoint all functions matching regex
+```
+
+**Pair with pwndbg** for better layout on native bugs — see [tools/pwndbg.md](../tools/pwndbg.md). Pwndbg works with rust-gdb too.
+
+---
+
+## tokio-console — async task debugging
+
+For tokio-based async apps, this is essential when tasks are stuck or leaking.
+
+```bash
+# Add tokio-console instrumentation to the target binary
+# In Cargo.toml:
+#   [dependencies]
+#   console-subscriber = "0.2"
+
+# In main.rs:
+#   console_subscriber::init();
+
+# Build with tokio_unstable:
+RUSTFLAGS="--cfg tokio_unstable" cargo run
+
+# In another terminal:
+tokio-console                     # connects to default port 6669
+```
+
+Shows live tasks, their state, wake counts, poll durations, parent tasks. The single fastest way to find "why is my async thing stuck".
+
+---
+
+## cargo-expand — when a macro is suspect
+
+```bash
+cargo install cargo-expand
+cargo expand                      # expand all macros in the crate
+cargo expand my::module::path     # scope to one item
+```
+
+If you suspect a macro (especially `#[derive]`, `#[tokio::main]`, `#[async_trait]`) is generating code that doesn't match your mental model, this shows you exactly what the compiler sees.
+
+---
+
+## Release-build gotcha
+
+```bash
+cargo build --release                        # no debug symbols by default
+```
+
+If the bug only shows up in `--release`:
+
+```toml
+# Cargo.toml
+[profile.release]
+debug = true                                 # add symbols, keep optimizations
+```
+
+Now `rust-gdb ./target/release/my_binary` works on release builds. This is required when optimization-enabled codegen bugs (inlining, LLVM folding) are suspected.
+
+---
+
+## Silent-failure patterns in Rust
+
+| Pattern | Why it's silent |
+|---|---|
+| `.unwrap_or_default()` | Masks errors as the zero value |
+| `.unwrap_or(fallback)` | Same, with a specific fallback |
+| `let _ = fallible_operation()` | Explicitly discards the Result, no compiler warning |
+| `if let Ok(x) = ... { use(x); } // no else` | Silent on Err |
+| `.ok()` chaining | Converts Result to Option, throwing the error away |
+| Panic inside a tokio task not `.await`ed | Task dies silently; runtime usually logs but it's quiet if logs are off |
+| `eprintln!` that goes to a redirected-null stderr | Looks like nothing happened |
+| `Drop` impl that panics under specific condition | Double-panic aborts process silently if no logging configured |
+
+---
+
+## Phase 9 cleanup specifics
+
+```bash
+# Revert dbg! macro additions
+git diff | grep -E 'dbg!\('
+# For any file with dbg! additions:
+git checkout <file>
+
+# Unset env vars
+unset RUST_LOG RUST_BACKTRACE
+
+# Kill any rust-gdb/lldb sessions
+pkill -f 'rust-gdb' || true
+pkill -f 'rust-lldb' || true
+pkill -f '^lldb ' || true
+
+# tokio-console binds 6669 by default
+lsof -iTCP:6669 -sTCP:LISTEN -nP 2>/dev/null
+```

package/plugin/skills/debugging/references/tools/ghidra.md

@@ -0,0 +1,212 @@
+# Ghidra — Decompile Binaries Into Readable C
+
+**https://github.com/NationalSecurityAgency/ghidra**
+
+Ghidra is the NSA's open-source reverse-engineering suite. Its defining feature is a **decompiler** that turns machine code back into readable C. For any binary you don't have source for, this is the correct starting point — not `strings`, not hex-staring, not `objdump -d`.
+
+**Use Ghidra when**: third-party closed-source libs, malware analysis, vendored binaries whose behavior contradicts docs, CTF challenges, firmware, any time you need to read compiled code.
+
+---
+
+## Install
+
+```bash
+# macOS
+brew install --cask ghidra
+# OR download the release ZIP from the repo and ./ghidraRun
+
+# Linux
+# Download from https://github.com/NationalSecurityAgency/ghidra/releases
+# Requires JDK 21+
+./ghidraRun
+
+# Dependency
+java -version    # must be 21+
+```
+
+Ghidra is a Java Swing app. Looks dated, works well.
+
+---
+
+## First-time workflow (memorize this — it's not obvious)
+
+1. **Start Ghidra**: `ghidraRun`
+2. **Create a project**: File → New Project → Non-Shared → name it `debug-<binary-name>` (journal this path so you can rm it at Phase 9 if disposable).
+3. **Import the binary**: File → Import File → pick your target. Accept default format detection.
+4. **Double-click the imported binary** in the project listing. Ghidra asks to analyze it — say **yes**, accept defaults for the first pass. This takes anywhere from seconds (small binary) to tens of minutes (large binary).
+5. **Once analysis completes**, you're in the CodeBrowser view.
+
+Two panels you'll use 95% of the time:
+
+- **Listing** (middle) — the disassembly with Ghidra's inferred labels/types.
+- **Decompiler** (right) — the reconstructed C. The real value.
+
+---
+
+## Finding the right function fast
+
+Don't try to read the whole binary. Use these to narrow:
+
+### Symbol Tree (left panel)
+
+- `Functions` — all detected functions. Stripped binaries show `FUN_00401234` (address-named); unstripped show actual names.
+- `Imports` — dynamically-linked functions. Great for "does this binary call `system()`, `strcpy`, `curl_easy_perform`?"
+- `Exports` — if it's a library.
+
+Click to jump. The Decompiler updates instantly.
+
+### String search
+
+```
+Search → For Strings
+```
+
+Produces a list of all strings. Right-click a string → `References` → `Show References to Address`. Jumps to code that references it. **This is how you find which function handles the error message you saw at runtime.**
+
+### Memory search for bytes
+
+```
+Search → Memory
+```
+
+Search hex or text. Useful for known magic bytes, file-format signatures, constants.
+
+### Cross-references (XREF)
+
+Right-click any function / address → `References → Find References to`. Shows every place that calls it. Walk the call graph backward from interesting functions.
+
+---
+
+## Making the decompiler's output readable
+
+Ghidra's decompiler is good but needs hints. These three actions dramatically improve its output:
+
+### 1. Rename variables
+
+Click a variable in the Decompiler view → press `L` → type a better name. Ghidra propagates the rename across all uses.
+
+### 2. Set types
+
+A variable that looks like `undefined4` or `void *` is unhelpful. Click it → press `Ctrl+L` → set type (e.g. `int`, `char *`, `struct my_header *`).
+
+For pointers to structs from headers you have, use:
+```
+File → Parse C Source → paste header file → auto-creates struct types
+```
+
+Then assign the struct type to the pointer. Ghidra resolves field accesses immediately.
+
+### 3. Retype function signatures
+
+Click the function name in the Decompiler → press `F` (Edit Function Signature) → set return type + argument types. This propagates through callers.
+
+Do these three actions on the 3-5 most relevant functions and the decompiler output becomes near-source-readable.
+
+---
+
+## Patterns for specific bug types
+
+### Looking for integer overflow / buffer overflow
+
+```
+Listing: look for
+  - LEA → CMP patterns on sizes
+  - memcpy/strcpy/sprintf with non-constant sizes
+Decompiler: look for
+  - arithmetic on size_t without bounds check
+  - `+ user_input` in a length calculation
+```
+
+### Looking for a missing auth check
+
+Navigate from the handler entry (found via Strings or Imports) and check the control flow:
+
+```
+Decompiler: does the function return early / jump to error handler when some flag is not set?
+  If the check is absent, that's the bug.
+```
+
+### Looking for hardcoded URLs / keys / paths
+
+```
+Search → For Strings → filter `http:` / `https:` / `/etc/` / `bearer ` / `api_key`
+```
+
+### Looking for dispatch / plugin loading
+
+```
+Imports → dlopen, LoadLibrary, dlsym, GetProcAddress
+```
+
+The strings referenced near those calls are often plugin names.
+
+---
+
+## Scripting (headless Ghidra)
+
+When you need to automate analysis across many binaries, or repeat a workflow:
+
+```bash
+# Headless analyzer
+$GHIDRA_INSTALL_DIR/support/analyzeHeadless \
+  <project-dir> <project-name> \
+  -import <binary> \
+  -postScript <script.py or script.java>
+```
+
+Ghidra supports Python 3 scripts (via Jython-compatible API) and Java. Useful scripts:
+
+- Dump all function signatures to JSON
+- Find all calls to `system()` with constant arguments
+- Auto-rename FUN_xxx based on heuristics (string refs, call patterns)
+
+The community has a large collection: https://github.com/NationalSecurityAgency/ghidra/tree/master/Ghidra/Features/Base/ghidra_scripts
+
+---
+
+## Bookmarks + Notes
+
+Ghidra has built-in bookmarks and comments. Use them as your journal inside the project:
+
+- Right-click an address → `Set Bookmark` → tag as `Note`. Attach a description.
+- Right-click → `Comments → Set EOL Comment` (shows up inline in decompiler).
+
+Treat these as part of the journal. If you end up promoting this Ghidra project (keeping it after the debug session), the comments become durable documentation.
+
+---
+
+## Gotchas
+
+- **Large binaries need more Java heap.** Edit `support/launch.properties` and bump `VMARGS=-Xmx8G` (default is often 2G, too small).
+- **Save often.** Ghidra's autosave is not instant; a crash loses uncommitted analysis.
+- **Decompiler has timeouts.** For complex functions it may give up and print `/* WARNING: ... */`. Increase timeout in `Edit → Tool Options → Decompiler`.
+- **Archs beyond x86/ARM/MIPS** sometimes need Sleigh processor module tweaks. Rare but possible.
+- **Signed vs unsigned decompilation** is frequently wrong. Manually retype when integer behavior matters.
+
+---
+
+## When Ghidra is NOT the right tool
+
+- You have the source. Go read it.
+- Bug is in your own recently-compiled binary. Rebuild with `-g` and use gdb/pwndbg (see [pwndbg.md](pwndbg.md)).
+- You just need to know which libs a binary links. `ldd` / `otool -L` / `readelf -d` are faster.
+- You just need strings. `strings -n 8` is faster.
+
+Ghidra is the right tool when you need to **read the logic** of a binary you don't have source for.
+
+---
+
+## Phase 9 cleanup specifics
+
+```bash
+# If you created a scratch project just for this debug session, journal path and remove:
+# (the journal should have the exact path)
+# Example:
+ls ~/ghidra-projects/ 2>/dev/null
+# rm -rf ~/ghidra-projects/debug-<binary-name>
+
+# If you promoted the project (kept it), it's not cleanup — note it in the final summary to the user
+
+# Kill any running Ghidra headless processes
+pkill -f 'analyzeHeadless' || true
+```

package/plugin/skills/debugging/references/tools/playwright-cli.md

@@ -0,0 +1,194 @@
+# Playwright CLI — Browser QA That Actually Drives a Browser
+
+**https://playwright.dev/ · https://github.com/microsoft/playwright**
+
+For any browser-served web UI bug, this is the correct tool. Not curl. Not imagination. Not a headless HTTP library. A real browser with a real rendering engine, real JS execution, real cookies, real service workers, real viewport.
+
+**In Phase 8 Manual QA for browser products, using Playwright is not optional.** Curl cannot catch: CSS that breaks at specific viewport widths, hydration mismatches, client-side router bugs, cookie/session interactions, service-worker caching, JS-triggered navigations. All of those are common bug classes. Drive a browser.
+
+> Note: `microsoft/playwright-cli` is the legacy repo; the current tooling lives in `@playwright/test` (npm) and `playwright` (pip), which include the `playwright` CLI. Use those — the legacy `playwright-cli` package is deprecated.
+
+---
+
+## When to reach for Playwright
+
+| Bug symptom | Use Playwright? |
+|---|---|
+| Form submit produces wrong result | ✅ — Playwright drives the form exactly as a user does |
+| Page blank in prod, fine locally | ✅ — hydration/env differences need a real browser |
+| CSS looks wrong at a specific width | ✅ — use `--viewport-size` |
+| Click doesn't fire / wrong handler | ✅ — Playwright fires real DOM events |
+| Flash of unstyled content / loading glitch | ✅ — use trace viewer to see frames |
+| API returns wrong data | ❌ — use curl, this isn't a browser bug |
+| Backend returns wrong status code | ❌ — use curl |
+| Client hits a URL that returns 500 | ✅ but also ❌ — Playwright shows the call + response + failure effect on UI |
+
+---
+
+## Install (per-project)
+
+Playwright installs browser binaries separately from the npm package.
+
+```bash
+# In the project
+npm init playwright@latest             # interactive; picks TS/JS + browsers + config
+# Or if Playwright is already a dep:
+npx playwright install                 # downloads browsers
+npx playwright install chromium        # just chromium
+npx playwright install --with-deps     # also installs OS deps (Linux)
+```
+
+Python:
+```bash
+pip install playwright
+playwright install
+```
+
+---
+
+## The four things you'll actually use
+
+### 1. `codegen` — record a session, generate the script
+
+The fastest way to create a repro. Opens a real browser; your clicks / typing become a Playwright script you can paste into a test.
+
+```bash
+npx playwright codegen https://your-app.local
+npx playwright codegen --viewport-size=375,667 https://your-app.local    # iPhone SE size
+npx playwright codegen --device="iPhone 14" https://your-app.local
+```
+
+Click / type / navigate in the browser; watch the script build in the side panel. Copy the generated script into your journal as the repro for Phase 8.
+
+### 2. A one-shot Playwright script — reproduce + capture
+
+Usually the Phase 8 QA artifact. Save to `/tmp/debug-repro.spec.ts` (journal it):
+
+```ts
+// /tmp/debug-repro.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('refinement chat shows non-empty response when env var set', async ({ page }) => {
+  await page.goto('http://localhost:3000/chat');
+  await page.fill('textarea[name="message"]', 'Add a logging step');
+  await page.click('button[type=submit]');
+
+  // Wait for the response to appear (not just the spinner to disappear)
+  const response = page.locator('[data-testid="assistant-reply"]');
+  await expect(response).toBeVisible({ timeout: 30_000 });
+  await expect(response).not.toBeEmpty();
+
+  // Capture evidence
+  await page.screenshot({ path: '/tmp/debug-after-fix.png', fullPage: true });
+  console.log(await response.textContent());
+});
+```
+
+Run it with tracing enabled for rich post-mortem:
+
+```bash
+npx playwright test /tmp/debug-repro.spec.ts --trace on --headed
+```
+
+### 3. `PWDEBUG=1` — step through the script with Playwright Inspector
+
+```bash
+PWDEBUG=1 npx playwright test /tmp/debug-repro.spec.ts
+```
+
+Opens the Playwright Inspector alongside the browser. You can step through Playwright actions, see the DOM state at each step, and edit selectors on the fly.
+
+Use this when the script doesn't reproduce cleanly and you need to watch it run.
+
+### 4. `show-trace` — post-mortem on a failed run
+
+```bash
+npx playwright show-trace trace.zip
+# or from the test-results dir:
+npx playwright show-trace test-results/<test-name>/trace.zip
+```
+
+Scrubs through a recorded session: timeline, DOM snapshot at each action, network, console, source. When a test failed on CI but passed locally, this is the single best artifact.
+
+---
+
+## Headless vs headed during debugging
+
+Always add `--headed` when debugging. Headless browsers sometimes behave subtly differently (font rendering, viewport, media permissions). For QA evidence, run headed and screenshot.
+
+```bash
+npx playwright test --headed
+npx playwright test --headed --project=chromium     # pin the browser
+```
+
+---
+
+## Catching the silent-failure patterns Playwright is good at
+
+```ts
+// Toast that flashes and disappears
+page.on('console', msg => console.log('[browser console]', msg.type(), msg.text()));
+
+// Unhandled page errors (uncaught exceptions in the page JS)
+page.on('pageerror', err => console.error('[page error]', err));
+
+// Network failures — e.g., backend returned 500 but UI shows nothing
+page.on('response', async resp => {
+  if (!resp.ok()) {
+    console.warn(`[network ${resp.status()}] ${resp.url()} — ${await resp.text()}`);
+  }
+});
+
+// Request that never came back
+page.on('requestfailed', req => {
+  console.error('[request failed]', req.url(), req.failure()?.errorText);
+});
+```
+
+Add these listeners to the top of the debug script. They surface a lot of the "UI showed nothing" class of bug.
+
+---
+
+## Viewport and device emulation
+
+CSS bugs that only appear at specific sizes, or layout bugs on mobile:
+
+```ts
+// At test level
+test.use({ viewport: { width: 375, height: 667 } });
+
+// Per-page
+await page.setViewportSize({ width: 375, height: 667 });
+
+// Predefined devices
+import { devices } from '@playwright/test';
+test.use({ ...devices['iPhone 14'] });
+```
+
+---
+
+## Gotchas
+
+- **Wait for state, not for time.** `await page.waitForTimeout(2000)` is flaky. Use `await expect(locator).toBeVisible()` or `page.waitForResponse(urlPattern)`.
+- **Stale selectors re-resolve.** Playwright's locators re-find the element on each action, unlike Puppeteer's handles. Don't over-think it.
+- **Service workers persist across test runs in headed mode.** If you see cached behavior from a previous run, add `await context.clearCookies()` + clear storage before the test.
+- **Installing on CI requires `--with-deps`** on Linux images that lack the browser's shared-library deps.
+- **Parallel tests share a browser process by default**; if one test polls a debugger port, others may interfere. Use `workers: 1` for debugging.
+
+---
+
+## Phase 9 cleanup specifics
+
+```bash
+# Remove trace files from debug runs
+rm -rf playwright-report/ test-results/ trace.zip
+
+# Remove debug spec files from /tmp
+rm -f /tmp/debug-*.spec.ts
+
+# Remove screenshot captures
+rm -f /tmp/debug-*.png
+
+# If you installed browsers just for this session (rare):
+# Don't remove them — they're useful for future sessions. They live in ~/Library/Caches/ms-playwright (macOS) or ~/.cache/ms-playwright (Linux).
+```