vanara 0.1.0 → 0.2.0

package/catalog/agents/code-reviewer/scripts/review-guard.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Runnable check: flags maintainability violations from a diff-stat-like JSON so a
+// reviewer (human or agent) can mechanically catch oversized functions and files
+// before the manual pass. Mirrors the --selftest convention of check-envelope.mjs.
+//
+// Input shape (a "diff stat"):
+//   {
+//     "files": [
+//       { "path": "a.js", "lines": 120,
+//         "functions": [ { "name": "doThing", "lines": 40 } ] }
+//     ]
+//   }
+//
+// Usage:
+//   node review-guard.mjs '<json>'              # check a literal JSON string
+//   echo '<json>' | node review-guard.mjs      # check from stdin
+//   node review-guard.mjs --selftest           # run built-in test cases
+
+const MAX_FUNC_LINES = 50;   // functions should stay under 50 lines
+const MAX_FILE_LINES = 800;  // files should stay under 800 lines
+
+export function reviewGuard(stat) {
+  const violations = [];
+  const files = (stat && Array.isArray(stat.files)) ? stat.files : [];
+  for (const f of files) {
+    const path = f.path ?? '<unknown>';
+    if (typeof f.lines === 'number' && f.lines > MAX_FILE_LINES) {
+      violations.push({
+        severity: 'MEDIUM',
+        where: path,
+        msg: `file is ${f.lines} lines (> ${MAX_FILE_LINES}); split into smaller modules`,
+      });
+    }
+    const fns = Array.isArray(f.functions) ? f.functions : [];
+    for (const fn of fns) {
+      if (typeof fn.lines === 'number' && fn.lines > MAX_FUNC_LINES) {
+        violations.push({
+          severity: 'MEDIUM',
+          where: `${path}:${fn.name ?? '<anon>'}`,
+          msg: `function is ${fn.lines} lines (> ${MAX_FUNC_LINES}); extract focused helpers`,
+        });
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+
+function check(label, json) {
+  let stat;
+  try { stat = typeof json === 'string' ? JSON.parse(json) : json; }
+  catch { console.error(`✗ ${label}: invalid JSON`); return false; }
+  const { ok, violations } = reviewGuard(stat);
+  if (ok) console.log(`✓ ${label}: no oversized functions or files`);
+  else {
+    console.error(`✗ ${label}: ${violations.length} violation(s)`);
+    violations.forEach((v) => console.error(`    [${v.severity}] ${v.where} — ${v.msg}`));
+  }
+  return ok;
+}
+
+function selftest() {
+  const cases = {
+    clean: {
+      files: [
+        { path: 'ok.js', lines: 120, functions: [{ name: 'small', lines: 20 }] },
+      ],
+    },
+    bad_big_function: {
+      files: [
+        { path: 'svc.js', lines: 200, functions: [{ name: 'processOrder', lines: 59 }] },
+      ],
+    },
+    bad_big_file: {
+      files: [
+        { path: 'huge.js', lines: 1200, functions: [{ name: 'fine', lines: 10 }] },
+      ],
+    },
+    bad_both: {
+      files: [
+        { path: 'monster.js', lines: 900, functions: [{ name: 'god', lines: 300 }] },
+      ],
+    },
+  };
+  let allExpected = true;
+  for (const [name, payload] of Object.entries(cases)) {
+    const { ok } = reviewGuard(payload);
+    const shouldPass = name === 'clean';
+    const correct = ok === shouldPass;
+    allExpected &&= correct;
+    console.log(`${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'clean' : 'violations'} (expected ${shouldPass ? 'clean' : 'violations'})`);
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(check('diff-stat', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(check('stdin', buf) ? 0 : 1));
+}

package/catalog/agents/debugger/AGENT.md

@@ -0,0 +1,112 @@
+---
+name: debugger
+description: Hypothesis-driven debugging specialist. Use PROACTIVELY when a test fails, an exception or stack trace appears, a build breaks, or behavior is unexpected. Reproduces the failure, bisects to the root cause, fixes the smallest surface, and adds a regression test — never patches symptoms.
+tools: Read, Grep, Glob, Bash, Edit
+model: claude-sonnet-4-6
+type: agent
+version: 2.0.0
+updated: 2026-06-29
+---
+# Debugger
+
+You are a disciplined debugging specialist. You find **root causes, not band-aids**. Debugging is not
+guesswork — it is the scientific method applied to code: observe, hypothesize, predict, test, repeat. You
+change code only *after* a hypothesis is confirmed, and you change as little as possible.
+
+The single most important rule: **make the bug reproducible before you try to fix it.** A bug you cannot
+reproduce is a bug you cannot prove you fixed. If you change code while the failure is intermittent, a
+"fix" that coincides with the bug not appearing is indistinguishable from luck.
+
+## The method
+
+Work this loop in order. Do not skip ahead — most bad fixes come from jumping to step 5 from step 1.
+
+1. **Reproduce.** Capture the exact input, environment, and steps that trigger the failure. Reduce it to
+   the smallest deterministic repro (see `examples/repro-template.md`). Save the full error text verbatim.
+2. **Read the error.** The message and stack trace usually name the file and line. Read it *top to bottom*
+   for the exception type and message; read the frames *top of user code first* for where your code is
+   involved. Details in `references/observability.md`.
+3. **Localize / bisect.** Narrow *where* the bad state originates. Binary-search the input, the code path,
+   or the commit history (`git bisect`). Halve the search space each step — see `references/bisection.md`.
+4. **Hypothesize.** State the single most likely cause in one falsifiable sentence: "X is null here because
+   Y returns undefined when the cache misses." A hypothesis you can't test is not a hypothesis.
+5. **Test the hypothesis.** Confirm with a targeted probe — a log line, a breakpoint, an assertion, a unit
+   test — *before* editing the fix. Change one variable at a time so the signal stays clean.
+6. **Fix at the cause.** Edit the smallest surface that addresses the confirmed cause, not the symptom.
+7. **Verify & prevent regression.** Re-run the repro: it must now pass. Add a regression test that fails
+   on the old code and passes on the new. Then run the surrounding suite to confirm no new breakage.
+
+## Symptom vs root cause
+
+The symptom is *where it crashed*; the cause is *why the bad state arose*. A `NullPointerException` on
+line 200 is the symptom — the cause may be a function 50 lines earlier that returned `null` instead of
+throwing. Patching line 200 with a null check hides the real defect and lets corrupt state spread. Always
+trace the bad value back to its **origin**.
+
+```text
+Symptom fix:  if (user != null) { ... }     // silences the crash, bug still there
+Root fix:     // findUser() now throws NotFound instead of returning null on a cache miss
+```
+
+## Reading a stack trace
+
+A stack trace is a map. Read the exception type and message first, then find the **topmost frame in your
+own code** (skip framework/library frames) — that is almost always where to start looking.
+
+```text
+TypeError: Cannot read properties of undefined (reading 'id')   <- WHAT failed
+    at formatOrder (src/orders/format.js:42:18)                 <- TOP user frame: START HERE
+    at Array.map (<anonymous>)                                  <- library frame, skip
+    at renderOrders (src/orders/list.js:88:24)                  <- caller: how we got here
+    at handleRequest (src/server.js:130:9)                      <- entry point
+```
+
+Line 42 of `format.js` is where the bad value was *used*; lines 88 and 130 tell you the *path* that
+produced it. Walk down the trace to find which caller passed the undefined value.
+
+## Common pitfalls (failure modes)
+
+- **Fixing the symptom, not the cause.** A null check that silences a crash leaves the real defect alive.
+- **Changing many things at once.** If you edit five things and the bug disappears, you don't know which
+  one mattered — and you may have introduced two new bugs. Change one variable per iteration.
+- **No reproduction.** "It seems fixed" after a non-deterministic failure is not evidence. Get a repro first.
+- **Ignoring the error message.** The message and stack trace usually *say* what's wrong. Read them fully
+  before theorizing.
+- **Debugging by coincidence.** Adding random `sleep`/retries/try-catch until it "works" hides race
+  conditions and resource bugs instead of fixing them.
+- **Trusting assumptions over observation.** "That can't be null" — prove it with a log, don't assume it.
+- **Skipping the regression test.** Without one, the same bug returns the next time someone refactors.
+
+## When NOT to use / boundaries
+
+- **Not a feature builder.** This agent diagnoses and fixes defects; for new functionality use a
+  planning/TDD workflow instead.
+- **Not a performance profiler.** Slowness without incorrectness is a profiling task, not a bug hunt
+  (though the bisection method still applies to perf regressions).
+- **Not a security auditor.** If the "bug" is a vulnerability, hand off to the `security-auditor` agent.
+- **Don't guess-edit when you can't reproduce.** If reproduction is impossible, say so and list exactly
+  what you'd need (logs, env, input) rather than editing hopefully.
+- **Don't disable tests or loosen assertions to make red go green** — that destroys the signal that
+  caught the bug.
+
+## Output format
+
+Report in this structure:
+
+- **Reproduction** — the minimal steps/input that trigger the failure.
+- **Root cause** — the confirmed cause with `file:line`, distinguished from the symptom.
+- **Fix** — the minimal diff at the cause.
+- **Regression test** — a test that fails before, passes after.
+- **Verification** — what you re-ran to confirm green.
+
+## Files in this package
+
+- `references/debugging-method.md` — the scientific, hypothesis-driven loop in depth
+- `references/bisection.md` — `git bisect` + binary-search isolation techniques
+- `references/observability.md` — logs/metrics/traces, reading stack traces & core dumps
+- `examples/repro-template.md` — minimal reproduction checklist
+- `examples/postmortem-template.md` — blameless postmortem write-up template
+- `scripts/parse-stacktrace.mjs` — extracts the top user-code frame from a JS/Python stack trace
+
+Pairs with the `code-reviewer` agent (review the fix before merge), the `tdd-guide` agent (turn the repro
+into a failing test first), and the `error-handling-patterns` skill (so the cause can't silently recur).

package/catalog/agents/debugger/examples/postmortem-template.md

@@ -0,0 +1,59 @@
+# Blameless Postmortem Template
+
+Write this after a significant bug or incident is resolved. The goal is **systems, not scapegoats** — ask
+how the process let the defect through, not who typed it.
+
+## Summary
+
+- **Title:** _short description of the failure_
+- **Date / duration:** _when it started, when it was resolved_
+- **Severity / impact:** _who/what was affected, how badly (users, data, revenue)_
+- **Status:** Resolved / Mitigated / Monitoring
+
+## Timeline (UTC)
+
+| Time | Event |
+|---|---|
+| 14:01 | Deploy of `abc123` |
+| 14:05 | Error rate alarm fires |
+| 14:12 | On-call acknowledges, begins investigation |
+| 14:30 | Root cause identified (see below) |
+| 14:38 | Fix deployed, error rate normal |
+
+## Root cause
+
+State the **confirmed** cause, distinguished from the symptom, with `file:line` and the commit that
+introduced it. Explain *why the bad state arose*, not just where it crashed.
+
+> e.g. `applyDiscount` mutated the shared `cart` array (`src/cart.js:48`), so a retried request applied
+> the discount twice. The symptom was a wrong total at checkout; the cause was shared mutable state.
+
+## Detection
+
+- How was it found? (alarm / customer report / log)
+- How long until detection? Could a metric or test have caught it sooner?
+
+## Resolution & recovery
+
+- What fixed it (the minimal change at the cause)?
+- Any cleanup needed (data backfill, cache invalidation)?
+
+## The five whys
+
+1. Why did the total double? → discount applied twice.
+2. Why twice? → request was retried and the cart was mutated.
+3. Why was it mutated? → `applyDiscount` edited the array in place.
+4. Why in place? → no immutability convention in cart code.
+5. Why no convention? → no lint rule / review check for shared mutation.
+
+## Action items
+
+| Action | Owner | Type | Status |
+|---|---|---|---|
+| Add regression test for double-retry discount | | prevent | |
+| Make cart operations immutable | | fix-class | |
+| Add alarm on total-mismatch metric | | detect | |
+
+## What went well / what was lucky
+
+_Separate good process from good fortune — luck isn't repeatable._

package/catalog/agents/debugger/examples/repro-template.md

@@ -0,0 +1,50 @@
+# Minimal Reproduction Checklist
+
+A bug isn't ready to fix until you can trigger it on demand. Fill this out *before* editing any code.
+
+## 1. The failure (verbatim)
+
+- **Error message / stack trace:** _paste the full text, unedited_
+- **Where it surfaced:** `file:line` of the top user-code frame
+- **Expected vs actual behavior:** _one line each_
+
+## 2. The trigger
+
+- **Exact input / steps:**
+  1. _step_
+  2. _step_
+  3. _failure observed_
+- **Frequency:** [ ] every time  [ ] intermittent (___ % of runs)  [ ] only under load/concurrency
+- **First seen:** _commit / version / date_ — and the last known-good version, if any
+
+## 3. The environment
+
+| Factor | Value |
+|---|---|
+| OS / runtime version | |
+| Dependency versions | |
+| Config / env vars | |
+| Data / fixtures | |
+
+## 4. Reduce to the minimum
+
+Strip everything that *doesn't* affect the outcome until you have the smallest case that still fails:
+
+- [ ] Removed unrelated code paths
+- [ ] Replaced external calls with fixed stubs/fixtures
+- [ ] Hard-coded the triggering input
+- [ ] Confirmed it **still fails** after reduction
+- [ ] Confirmed it is **deterministic** (or documented the flake rate + suspected race)
+
+## 5. The repro artifact
+
+A runnable snippet or single failing test is the goal — paste it here:
+
+```text
+# minimal failing command or test
+$ npm test -- checkout.spec.js -t "applies discount once"
+  ✗ applies discount once  (expected 90, got 81)
+```
+
+> If you cannot produce a deterministic repro after a bounded effort, **stop**. Record what you tried and
+> exactly what additional evidence (logs, prod input, env access) you need — do not guess-edit.

package/catalog/agents/debugger/references/bisection.md

@@ -0,0 +1,63 @@
+# Bisection — Binary Search for Bugs
+
+When reasoning stalls, *search*. Halving the problem space repeatedly finds the culprit in log₂(N) steps
+instead of N. Bisection applies to three spaces: **history** (which commit), **code** (which statement),
+and **input** (which data).
+
+## 1. History: `git bisect`
+
+When a bug appeared "sometime in the last 200 commits," let git binary-search them. Mark a known-bad and
+known-good revision; git checks out the midpoint and you tell it good or bad until it names the culprit.
+
+```bash
+git bisect start
+git bisect bad                 # current HEAD is broken
+git bisect good v1.4.0         # this old tag worked
+# git checks out the midpoint; test it, then:
+git bisect good                # ...or: git bisect bad
+# repeat until git prints "<sha> is the first bad commit"
+git bisect reset               # return to where you started
+```
+
+Automate it when you have a script that exits 0 (good) / non-zero (bad):
+
+```bash
+git bisect start HEAD v1.4.0
+git bisect run npm test -- --testPathPattern=checkout
+```
+
+`git bisect run` will drive the entire search unattended and print the first bad commit. Keep the test
+fast and deterministic, or the search inherits its flakiness.
+
+## 2. Code: bisect the execution path
+
+Within a single bad function, find *where* the state goes wrong by checking the midpoint. Print or assert
+the suspect value halfway through; if it's already wrong, the bug is in the first half — otherwise the
+second. Repeat on the bad half.
+
+```text
+function process(x) {
+  step A          // assert(valid) here -> OK?  search lower half
+  step B
+  step C          // <-- midpoint probe: value already corrupt? bug is A/B
+  step D
+  step E          // assert(valid) here -> still OK?  bug is D/E
+}
+```
+
+A "wolf-fence" probe (a single well-placed log of the suspect value) beats scattering ten prints.
+
+## 3. Input: bisect the data
+
+A 100k-row file that crashes the parser? Don't read 100k rows. Feed the first half — still crashes? The
+offending row is in that half. Halve again. ~17 iterations isolate one row out of 100k. The same works
+for narrowing a failing config to one key, or a failing request to one field.
+
+## Pitfalls
+
+- **Non-deterministic test → useless bisect.** Flaky good/bad answers send the search to the wrong commit.
+  Stabilize the repro first.
+- **Skipping untestable midpoints.** If a midpoint commit won't build, use `git bisect skip` — don't guess.
+- **Forgetting `git bisect reset`** leaves you on a detached checkout.
+- **Too-coarse halving.** Bisect to the *commit*, then bisect *within* it to the statement; don't stop at
+  "this 400-line commit did it."

package/catalog/agents/debugger/references/debugging-method.md

@@ -0,0 +1,57 @@
+# The Debugging Method — Hypothesis-Driven
+
+Debugging is the scientific method applied to a misbehaving system. You don't "stare at code until you
+see it"; you run controlled experiments that each rule something in or out.
+
+## The loop
+
+```text
+   observe ──> hypothesize ──> predict ──> experiment ──> compare
+      ^                                                      │
+      └──────────────────── refine ─────────────────────────┘
+```
+
+1. **Observe.** Collect the facts: the exact error, the input, the environment, what changed recently.
+   Resist theorizing before you have the message in front of you.
+2. **Hypothesize.** Propose one *falsifiable* cause: "The total is wrong because `applyDiscount` mutates
+   the shared `cart` array." A good hypothesis predicts something you can check.
+3. **Predict.** If the hypothesis is true, what must also be true? "Then logging `cart` before and after
+   should show it changed."
+4. **Experiment.** Run the smallest test that distinguishes the hypothesis from its alternatives. Change
+   **one variable at a time**.
+5. **Compare.** Did the prediction hold? If yes, you've localized the cause. If no, the hypothesis is
+   wrong — discard it (don't patch it) and form a new one from what you learned.
+
+## Why "one variable at a time" is non-negotiable
+
+If you change input, code, and config simultaneously and the bug vanishes, the experiment has no signal:
+you cannot attribute the change. Worse, multi-change "fixes" routinely introduce new defects that hide
+behind the apparent success. Keep a clean control: a known-failing case you re-run after each change.
+
+## Rubber-duck and assumption auditing
+
+Explain the failing path aloud, line by line, to an imaginary listener. The bug is usually hidden in a
+step you *assumed* was correct and therefore never checked. Make a list of your assumptions and verify the
+cheapest ones first:
+
+- "This value is never null." → log it.
+- "This branch always runs." → add a counter.
+- "These two configs match." → diff them.
+
+## Confirmation before fixing
+
+The most common mistake is editing the fix before confirming the hypothesis. Confirm first with a probe
+(log, assertion, debugger, unit test). Only then edit — and only the smallest surface at the **origin** of
+the bad state, not the place where it finally crashed.
+
+## Binary search of everything
+
+When you can't reason your way to the cause, *search* for it. Halve the space repeatedly: comment out half
+the code, feed half the input, check the midpoint commit. See `bisection.md`. Each halving turns an
+N-step problem into log₂(N) steps — a 1,000-line search becomes ~10 checks.
+
+## Knowing when to stop
+
+Stop and escalate (or write down what you need) when: you cannot reproduce after a bounded effort; the
+cause is in a third-party dependency you can't change; or two equally-likely hypotheses both survive
+testing and you need more instrumentation. Guessing past this point produces band-aids.

package/catalog/agents/debugger/references/observability.md

@@ -0,0 +1,61 @@
+# Observability — Reading the Evidence
+
+You can't fix what you can't see. Observability is the practice of making a system's internal state
+inspectable from the outside, through three complementary signals plus the artifacts a crash leaves behind.
+
+## The three pillars
+
+| Signal | Answers | Use for |
+|---|---|---|
+| **Logs** | "What happened, exactly here?" | discrete events, error context, the bad value |
+| **Metrics** | "How much / how often, over time?" | rates, latencies, error %, spotting *when* a regression started |
+| **Traces** | "What was the path across services?" | distributed call graphs, finding the slow/failing hop |
+
+Logs give detail, metrics give trends, traces give causality across boundaries. A bug hunt usually starts
+at a metric spike ("errors jumped at 14:05"), zooms to a trace ("the payment service hop failed"), then
+lands on a log line with the exact exception.
+
+## Reading a stack trace
+
+1. **Exception type + message first** — `TypeError: Cannot read 'id' of undefined` tells you *what*.
+2. **Top user-code frame** — skip framework/stdlib frames; the first frame in *your* files is where to
+   start. (Note: Python prints oldest call first / failure **last**; JS prints failure **first**.)
+3. **Walk the callers** — each lower frame shows how execution reached the failure, i.e. who passed the
+   bad value.
+
+```text
+JavaScript (most-recent first):          Python (most-recent LAST):
+  TypeError: ... 'id' of undefined         Traceback (most recent call last):
+    at formatOrder (format.js:42)            File "list.py", line 88, in render
+    at renderOrders (list.js:88)               File "format.py", line 42, in format_order
+                                             KeyError: 'id'      <- read this line first
+```
+
+Use `scripts/parse-stacktrace.mjs` to extract the top user frame mechanically from either format.
+
+## Logging that actually helps
+
+- Log the **value and the context**, not "got here": `log('discount', {cartId, before, after})`.
+- Use **structured** logs (JSON) so you can filter/aggregate, not grep prose.
+- Use **levels** deliberately: `error` for failures, `warn` for recovered anomalies, `debug` for probes
+  you'll remove. Never leave `console.log` debug spew in committed code.
+- Include a **correlation/request id** so you can stitch one request's logs together.
+
+## Core dumps & post-mortem artifacts
+
+When a process dies hard, it may leave a snapshot of memory at the moment of death:
+
+- **Native (C/C++/Go):** a core file — open with `gdb ./bin core` and `bt` for the backtrace, inspect
+  locals with `frame`/`print`.
+- **Node:** run with `--abort-on-uncaught-exception` or use `--heapsnapshot-signal` / `--cpu-prof` for
+  memory and CPU forensics.
+- **JVM:** an `hs_err_pid.log` plus a heap dump (`jmap`) you open in a memory analyzer.
+
+These let you debug a failure you can observe but not re-trigger live.
+
+## Pitfalls
+
+- **Logging after the failure.** Put probes *before* the suspect operation so you capture the bad input.
+- **Too much log noise.** Drowning the signal is as bad as none; log the decisive values, not everything.
+- **No timestamps / no ids.** Unordered, uncorrelated logs can't reconstruct a sequence.
+- **Sensitive data in logs.** Never log secrets, tokens, or PII — redact at the boundary.

package/catalog/agents/debugger/scripts/parse-stacktrace.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Extract the top *user-code* frame (file:line) from a JS or Python stack trace.
+// Framework / stdlib / node_modules frames are skipped so you land on YOUR code —
+// the place a bug hunt should start (see references/observability.md).
+//
+// Usage:
+//   node parse-stacktrace.mjs "<trace text>"     # parse a literal string
+//   cat trace.txt | node parse-stacktrace.mjs    # parse from stdin
+//   node parse-stacktrace.mjs --selftest         # run built-in tests (exit 0/1)
+
+// Frames we consider "not user code" and skip when looking for the origin.
+const NOISE = [
+  /node_modules[\\/]/,
+  /\bnode:internal\//,
+  /\b<anonymous>\b/,
+  /[\\/](site-packages|dist-packages)[\\/]/,
+  /[\\/]lib[\\/]python\d/i,
+  /\bin <module>\b.*\b(site-packages|python\d)/i,
+];
+
+const isNoise = (line) => NOISE.some((re) => re.test(line));
+
+// JS:     "    at formatOrder (src/orders/format.js:42:18)"  or  "    at /a/b.js:10:5"
+// Python: '  File "src/format.py", line 42, in format_order'
+function parseFrame(line) {
+  const js = line.match(/^\s*at\s+(?:(.*?)\s+\()?(.+?):(\d+)(?::\d+)?\)?\s*$/);
+  if (js) {
+    return { func: js[1] || '<top>', file: js[2], line: Number(js[3]) };
+  }
+  const py = line.match(/^\s*File\s+"(.+?)",\s+line\s+(\d+)(?:,\s+in\s+(.*))?\s*$/);
+  if (py) {
+    return { func: (py[3] || '<module>').trim(), file: py[1], line: Number(py[2]) };
+  }
+  return null;
+}
+
+// Returns the top user frame. JS traces list the failure FIRST (scan top-down);
+// Python lists it LAST (scan bottom-up). We detect Python by its "File ..." frames.
+export function topUserFrame(trace) {
+  const lines = trace.split(/\r?\n/);
+  const isPython = lines.some((l) => /^\s*File\s+".+?",\s+line\s+\d+/.test(l));
+  const ordered = isPython ? [...lines].reverse() : lines;
+
+  let firstFrame = null;
+  for (const line of ordered) {
+    const frame = parseFrame(line);
+    if (!frame) continue;
+    if (!firstFrame) firstFrame = frame;   // fallback if everything is "noise"
+    if (!isNoise(line)) return frame;      // first non-noise frame = user code
+  }
+  return firstFrame; // all frames were noise: return the outermost we saw
+}
+
+function selftest() {
+  const jsTrace = [
+    "TypeError: Cannot read properties of undefined (reading 'id')",
+    '    at formatOrder (src/orders/format.js:42:18)',
+    '    at Array.map (<anonymous>)',
+    '    at renderOrders (src/orders/list.js:88:24)',
+    '    at handleRequest (node_modules/express/lib/router.js:12:3)',
+  ].join('\n');
+
+  const pyTrace = [
+    'Traceback (most recent call last):',
+    '  File "/usr/lib/python3.11/runpy.py", line 196, in _run_module',
+    '  File "src/orders/list.py", line 88, in render',
+    '  File "src/orders/format.py", line 42, in format_order',
+    "KeyError: 'id'",
+  ].join('\n');
+
+  // A trace where the only frames are in node_modules -> fall back to outermost.
+  const noiseOnly = [
+    'Error: boom',
+    '    at foo (node_modules/x/index.js:1:1)',
+  ].join('\n');
+
+  const cases = [
+    ['js top user frame', jsTrace, { file: 'src/orders/format.js', line: 42, func: 'formatOrder' }],
+    ['python top user frame', pyTrace, { file: 'src/orders/format.py', line: 42, func: 'format_order' }],
+    ['noise-only fallback', noiseOnly, { file: 'node_modules/x/index.js', line: 1, func: 'foo' }],
+  ];
+
+  let ok = true;
+  for (const [name, trace, want] of cases) {
+    const got = topUserFrame(trace) || {};
+    const pass = got.file === want.file && got.line === want.line && got.func === want.func;
+    ok &&= pass;
+    console.log(`${pass ? '✓' : '✗'} ${name}: ${got.func} @ ${got.file}:${got.line}` +
+      (pass ? '' : ` (expected ${want.func} @ ${want.file}:${want.line})`));
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+function report(trace) {
+  const frame = topUserFrame(trace);
+  if (!frame) { console.error('No stack frame found in input.'); return false; }
+  console.log(`Top user-code frame: ${frame.func} @ ${frame.file}:${frame.line}`);
+  console.log('Start your investigation here.');
+  return true;
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(report(arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(report(buf) ? 0 : 1));
+}