@saptools/cf-inspector 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dongtran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+<div align="center">
+
+# 🔍 `@saptools/cf-inspector`
+
+**Set breakpoints, capture variable snapshots, and evaluate expressions on a remote Node.js process — over the Chrome DevTools Protocol, no IDE required.**
+
+Built so an AI agent (or a CI job) can drive a debugger from a single shell command. Pairs with [`@saptools/cf-debugger`](https://www.npmjs.com/package/@saptools/cf-debugger) when the target lives behind a Cloud Foundry SSH tunnel.
+
+[![npm version](https://img.shields.io/npm/v/@saptools/cf-inspector.svg?style=flat&color=CB3837&logo=npm)](https://www.npmjs.com/package/@saptools/cf-inspector)
+[![license](https://img.shields.io/npm/l/@saptools/cf-inspector.svg?style=flat&color=blue)](./LICENSE)
+[![node](https://img.shields.io/node/v/@saptools/cf-inspector.svg?style=flat&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
+
+[Install](#-install) • [Quick Start](#-quick-start) • [CLI](#-cli) • [API](#-programmatic-usage) • [How it works](#-how-it-works)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🎯 **One-shot snapshot** — `cf-inspector snapshot --bp src/handler.ts:42` sets the breakpoint, waits for it to hit, captures the scope, auto-resumes, prints JSON, exits
+- ✅ **Conditional breakpoints** — `--condition 'req.userId === "abc"'` only pauses when the predicate is truthy
+- 🎭 **Multi-breakpoint** — repeat `--bp` to race several locations; first hit wins
+- 📡 **Non-pausing logpoints** — `cf-inspector log --at file:line --expr 'JSON.stringify({…})'` streams JSON Lines as the line executes, **without ever pausing the inspectee** (safe for production traffic)
+- 🧠 **Agent-friendly** — JSON-by-default I/O, deterministic shape, sensitive-name redaction (`password`, `token`, `secret`, `cookie`, …) baked in
+- 🧭 **Path mapping** — local `src/handler.ts:42` is matched against the remote URL via a `urlRegex`, with optional `--remote-root` literal or regex (same DSL as `cds-debug`)
+- 🔁 **Composes with `cf-debugger`** — pass `--app/--region/--org/--space` and the tunnel is opened automatically; pass `--port` to attach to anything CDP-speaking
+- 🪶 **Tiny dependency footprint** — `commander` + `ws` only, no heavy CDP framework
+- 🧩 **Typed API** — every CLI command has a programmatic equivalent with full TypeScript definitions
+
+---
+
+## 📦 Install
+
+```bash
+npm install -g @saptools/cf-inspector
+# or
+pnpm add @saptools/cf-inspector
+```
+
+> [!NOTE]
+> Requires **Node.js ≥ 20**.
+> For Cloud Foundry targets, also install [`@saptools/cf-debugger`](https://www.npmjs.com/package/@saptools/cf-debugger) (added automatically as a peer-style runtime dep).
+
+---
+
+## 🚀 Quick Start
+
+### Local Node process
+
+```bash
+# Terminal 1 — run any Node app with the inspector enabled
+node --inspect=9229 my-app.js
+
+# Terminal 2 — capture a snapshot when handler.ts:42 hits
+cf-inspector snapshot \
+  --port 9229 \
+  --bp src/handler.ts:42 \
+  --capture 'this.user, req.body' \
+  --timeout 30
+```
+
+### Cloud Foundry app (auto-tunnel)
+
+```bash
+export SAP_EMAIL=...
+export SAP_PASSWORD=...
+
+cf-inspector snapshot \
+  --region eu10 --org my-org --space dev --app my-srv \
+  --bp src/handler.ts:42 \
+  --remote-root 'regex:^/(home/vcap/app|srv-.*)$'
+```
+
+The first form connects directly to `localhost:9229`. The second internally calls `@saptools/cf-debugger` to open the SSH tunnel, runs the snapshot through it, and tears the tunnel down on exit.
+
+---
+
+## 🧰 CLI
+
+### 📸 `cf-inspector snapshot`
+
+Set one or more breakpoints, wait for any of them to hit, capture the scope, auto-resume, exit.
+
+```bash
+# Simple snapshot
+cf-inspector snapshot \
+  --port 9229 \
+  --bp src/handler.ts:42 \
+  --capture 'this.user, req.body' \
+  --timeout 30
+
+# Conditional snapshot — only pauses for the user we care about
+cf-inspector snapshot --port 9229 \
+  --bp src/handler.ts:42 \
+  --condition 'req.userId === "abc"' \
+  --capture 'req.body'
+
+# Multi-breakpoint — first hit wins (useful when you don't know which path is taken)
+cf-inspector snapshot --port 9229 \
+  --bp src/auth.ts:120 \
+  --bp src/auth.ts:155 \
+  --bp src/auth.ts:180 \
+  --capture 'req.url, this.user'
+```
+
+| Flag | Description |
+| --- | --- |
+| `--port <number>` | Local port the inspector or tunnel listens on. **Required** unless `--app/--region/--org/--space` are all set |
+| `--bp <file:line>` | **Required.** Source location to break at. Pass multiple times to race several locations — the first one to hit wins |
+| `--condition <expr>` | Only pause when this JS expression evaluates truthy in the paused frame. Errors in the condition are silently treated as `false` by V8 |
+| `--capture <expr,…>` | Comma-separated expressions to evaluate in the paused frame; results merged into the snapshot |
+| `--timeout <seconds>` | How long to wait for the breakpoint to hit (default: `30`) |
+| `--remote-root <value>` | Optional path-mapping anchor: literal path or `regex:<pattern>` / `/pattern/flags` |
+| `--no-json` | Print a human-readable summary instead of JSON |
+| `--keep-paused` | Skip the auto-resume after capture (useful for diagnostics) |
+
+For Cloud Foundry targets, replace `--port` with `--region/--org/--space/--app` (and optionally `--cf-timeout <seconds>` for the tunnel).
+
+### 📡 `cf-inspector log`
+
+Set a non-pausing logpoint and stream the evaluated expression each time the line executes. Safe for production traffic — the inspectee **never pauses**.
+
+```bash
+# Stream user IDs hitting handler.ts:42 for 30 seconds
+cf-inspector log \
+  --port 9229 \
+  --at src/handler.ts:42 \
+  --expr 'JSON.stringify({ user: req.user, body: req.body })' \
+  --duration 30
+```
+
+Output is **JSON Lines** on stdout (one event per line) plus a summary trailer on stderr:
+
+```jsonc
+{"ts":"2026-04-29T...","at":"src/handler.ts:42","value":"{\"user\":\"alice\",\"body\":{}}"}
+{"ts":"2026-04-29T...","at":"src/handler.ts:42","value":"{\"user\":\"bob\",\"body\":{}}"}
+// stderr:
+{"stopped":"duration","emitted":2}
+```
+
+When the user expression throws, the event is emitted with `error` instead of `value` so the stream never silently gaps:
+
+```jsonc
+{"ts":"…","at":"src/handler.ts:42","error":"Cannot read properties of undefined (reading 'user')"}
+```
+
+| Flag | Description |
+| --- | --- |
+| `--port <number>` | Local port the inspector or tunnel listens on. **Required** unless `--app/--region/--org/--space` are all set |
+| `--at <file:line>` | **Required.** Source location to log at |
+| `--expr <expression>` | **Required.** JS expression to evaluate at each hit (wrapped in try/catch on the inspectee side) |
+| `--duration <seconds>` | Stop streaming after N seconds (default: run until SIGINT) |
+| `--remote-root <value>` | Optional path-mapping anchor (same DSL as `snapshot`) |
+| `--no-json` | Print human-readable lines instead of JSON Lines |
+
+### 🧮 `cf-inspector eval`
+
+Evaluate one expression and print the result. If a breakpoint is currently paused, it runs in the top frame; otherwise it runs against `Runtime.evaluate` in the global scope.
+
+```bash
+cf-inspector eval --port 9229 --expr 'process.uptime()'
+```
+
+### 📜 `cf-inspector list-scripts`
+
+Print every script the V8 instance knows about (useful for debugging path-mapping issues).
+
+```bash
+cf-inspector list-scripts --port 9229
+```
+
+### 🔗 `cf-inspector attach`
+
+Connect, fetch the runtime version, print it, disconnect. Useful as a smoke-test that the tunnel is healthy.
+
+```bash
+cf-inspector attach --port 9229
+```
+
+---
+
+## 🧑‍💻 Programmatic Usage
+
+```ts
+import {
+  connectInspector,
+  setBreakpoint,
+  waitForPause,
+  captureSnapshot,
+  evaluateOnFrame,
+  resume,
+} from "@saptools/cf-inspector";
+
+const session = await connectInspector({ port: 9229 });
+const bp = await setBreakpoint(session, {
+  file: "src/handler.ts",
+  line: 42,
+});
+const pause = await waitForPause(session, { timeoutMs: 30_000 });
+const snapshot = await captureSnapshot(session, pause);
+const customValue = await evaluateOnFrame(session, pause.callFrames[0]!.callFrameId, "this.user");
+await resume(session);
+await session.dispose();
+
+console.log({ bp, snapshot, customValue });
+```
+
+<details>
+<summary><b>📚 Full export list</b></summary>
+
+| Export | Description |
+| --- | --- |
+| `connectInspector(options)` | Open a CDP WebSocket session against a port |
+| `setBreakpoint(session, location)` | Set a breakpoint by file/line + optional remote root |
+| `removeBreakpoint(session, id)` | Remove a breakpoint by id |
+| `waitForPause(session, options)` | Resolve when the next `Debugger.paused` event fires |
+| `captureSnapshot(session, pause)` | Build a structured snapshot of the paused scope |
+| `evaluateOnFrame(session, frameId, expression)` | Evaluate in a paused frame |
+| `evaluateGlobal(session, expression)` | Evaluate against the global Runtime |
+| `listScripts(session)` | Return the scripts the V8 instance knows about |
+| `resume(session)` | Resume execution |
+| `streamLogpoint(session, options)` | Stream a non-pausing logpoint until duration / signal / transport-close |
+| `buildLogpointCondition(sentinel, expression)` | Build the CDP `condition` string for a logpoint (low-level helper) |
+| `parseRemoteRoot(value)` | Parse a literal/regex remote-root setting |
+| `buildBreakpointUrlRegex(input)` | Build a CDP `urlRegex` for a file path |
+| `CfInspectorError` | Rich error class with typed `code` |
+
+</details>
+
+<details>
+<summary><b>🧪 Error codes</b></summary>
+
+| Code | When |
+| --- | --- |
+| `INVALID_BREAKPOINT` | `--bp` is not in `file:line` form, or line is not a positive integer |
+| `INVALID_REMOTE_ROOT` | `--remote-root` regex did not compile |
+| `INSPECTOR_DISCOVERY_FAILED` | `/json/list` did not return a usable WebSocket URL |
+| `INSPECTOR_CONNECTION_FAILED` | WebSocket handshake failed |
+| `CDP_REQUEST_FAILED` | A CDP method returned an error result |
+| `BREAKPOINT_NOT_HIT` | The breakpoint did not hit before the timeout elapsed |
+| `EVALUATION_FAILED` | `Runtime.evaluate` / `Debugger.evaluateOnCallFrame` returned a remote exception |
+| `MISSING_TARGET` | Neither `--port` nor a CF target was provided |
+
+</details>
+
+---
+
+## 🔭 How it works
+
+```
+┌──────────────────────┐   1. GET http://127.0.0.1:<port>/json/list
+│ cf-inspector         │   2. Open ws:// debugger URL
+│  snapshot --bp X:Y   │ ─►3. Debugger.enable + Runtime.enable
+└──────────────────────┘   4. Debugger.setBreakpointByUrl({ urlRegex, lineNumber: Y - 1 })
+            │              5. Wait for `Debugger.paused`
+            ▼              6. Debugger.evaluateOnCallFrame(...)  for each --capture expression
+   JSON snapshot           7. Runtime.getProperties(scopeChain[i].object.objectId)
+                           8. Debugger.resume   (unless --keep-paused)
+```
+
+Path mapping uses CDP's first-class `urlRegex`:
+
+| `--remote-root` | Resulting urlRegex (line `42` of `src/handler.ts`) |
+| --- | --- |
+| _omitted_ | `(?:^|/)src/handler\.(?:ts\|js)$` |
+| `/home/vcap/app` (literal) | `^file:///home/vcap/app/src/handler\.(?:ts\|js)$` |
+| `regex:^/srv-.*$` | `^file:///srv-[^/]+/src/handler\.(?:ts\|js)$` |
+| `/^/srv-.*$/` | same as above |
+
+`.ts ↔ .js` is folded into the regex automatically because Node's V8 inspector normally serves both the source-mapped TypeScript URL and the runtime JavaScript URL — matching either is correct.
+
+---
+
+## ⚙️ Composing with `cf-debugger`
+
+If `--port` is omitted but `--region/--org/--space/--app` are given, the CLI internally calls `startDebugger(...)` from `@saptools/cf-debugger`, attaches over the SSH tunnel, and disposes the tunnel on exit. You get the same one-shot UX whether the target is local or in CF.
+
+```bash
+cf-inspector snapshot \
+  --region eu10 --org my-org --space dev --app my-srv \
+  --bp src/handler.ts:42 \
+  --capture 'req.url, this.user'
+```
+
+---
+
+## 🛠️ Development
+
+From the monorepo root:
+
+```bash
+pnpm install
+pnpm --filter @saptools/cf-inspector build
+pnpm --filter @saptools/cf-inspector typecheck
+pnpm --filter @saptools/cf-inspector lint
+pnpm --filter @saptools/cf-inspector test:unit
+pnpm --filter @saptools/cf-inspector test:e2e
+```
+
+The e2e suite is fully self-contained: it spawns a small Node fixture under `--inspect=0`, drives the CLI against it, and asserts the JSON output. No CF / live network required.
+
+---
+
+## 🌐 Related
+
+- 🐛 [`@saptools/cf-debugger`](https://www.npmjs.com/package/@saptools/cf-debugger) — opens the SSH inspector tunnel
+- ☁️ [`@saptools/cf-sync`](https://www.npmjs.com/package/@saptools/cf-sync) — snapshot CF topology + DB bindings into JSON
+- 🗂️ [saptools monorepo](https://github.com/dongitran/saptools) — the full toolbox
+
+---
+
+## 👨‍💻 Author
+
+**dongtran** ✨
+
+## 📄 License
+
+MIT
+
+---
+
+Made with ❤️ to make your work life easier!

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+declare function main(argv: readonly string[]): Promise<void>;
+
+export { main };