doru 1.0.0

package/README.md

@@ -0,0 +1,248 @@
+# Doru Interceptoru
+
+Small Node.js network interception **library + CLI** with a web UI.
+
+- Intercepts `http/https` and `fetch` via `@mswjs/interceptors`
+- Writes **JSONL** (default) or **JSON** captures
+- Works with both CommonJS and ESM scripts
+
+> Requires Node **22+**
+
+## Install
+
+```bash
+npm i -g doru
+doru --ui <script>
+
+# or just
+npx doru --ui <script>
+
+# development
+bun i && bun run build
+```
+
+**Try it out:**
+
+```sh
+bun src/cli.ts --ui examples/basic.mjs
+bun src/cli.ts --ui examples/basic.cjs
+bun src/cli.ts --ui (which claude)
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- [Bun](https://bun.sh) (recommended) or npm
+
+### Setup
+
+```bash
+bun install
+```
+
+### Scripts
+
+| Command | Description |
+|---------|-------------|
+| `bun run build` | Build library, CLI, and UI |
+| `bun run dev` | Watch mode for library/CLI (tsup) |
+| `bun run dev:ui` | Vite dev server for UI (HMR) |
+| `bun run type-check` | TypeScript type checking |
+| `bun run storybook` | Component development UI |
+
+### UI Development
+
+The web UI uses React + Vite. For hot module reloading:
+
+```bash
+# 1. start doru
+ src/cli.ts --ui capture.jsonl
+
+# 2. start Vite dev server and open open http://localhost:5173
+bun run dev:ui
+```
+
+Vite proxies `/api` requests to the CLI server (port 3000).
+
+### CLI Development
+
+```bash
+# Watch mode - rebuilds on file changes
+bun run dev
+
+# Run CLI from source
+bun src/cli.ts [options]
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts          # Library entry
+├── cli.ts            # CLI entry
+├── core/             # Interceptor, config, storage
+├── cli/              # Argument parsing, server
+└── ui/react/         # React web UI
+```
+
+## Library
+
+Use doru programmatically in your Node.js application:
+
+```js
+import { createInterceptor } from "doru";
+
+const interceptor = createInterceptor({
+  outputFile: "./capture.jsonl",
+  format: "jsonl", // "jsonl" or "json"
+  filters: {
+    excludeHosts: ["localhost", "127.0.0.1"],
+    methods: ["GET", "POST"],
+  },
+});
+interceptor.start();
+
+// your app code - all http/https/fetch calls are captured
+await fetch("https://api.example.com/data");
+
+interceptor.stop();
+```
+
+### API
+
+#### `createInterceptor(config?)`
+
+Returns an interceptor instance with:
+
+- `start()` — Begin intercepting network requests
+- `stop()` — Stop intercepting and close output file
+- `updateConfig(config)` — Update configuration at runtime
+- `getConfig()` — Get current configuration
+
+### Configuration
+
+```ts
+interface InterceptorConfig {
+  enabled: boolean;              // default: true
+  outputFile: string;            // default: "./network-capture.jsonl"
+  format: "json" | "jsonl";      // default: "jsonl"
+  maxFileSize: number;           // default: 10MB
+  debug: boolean;                // default: false (or DORU_DEBUG env)
+
+  filters: {
+    includeHosts: string[];      // only capture these hosts
+    excludeHosts: string[];      // skip these hosts
+    includePaths: string[];      // regex patterns to include
+    excludePaths: string[];      // regex patterns to exclude
+    methods: string[];           // e.g. ["GET", "POST"]
+    statusCodes: {
+      min: number | null;        // minimum status code
+      max: number | null;        // maximum status code
+    };
+    minSize: number | null;      // minimum response size
+    maxSize: number | null;      // maximum response size
+  };
+
+  performance: {
+    bufferSize: number;          // default: 1024
+    flushInterval: number;       // default: 1000ms
+    compression: boolean;        // default: false
+  };
+}
+```
+
+## CLI
+
+### Run script with network interception
+
+```bash
+doru run [options] <script> [-- <script-args>]
+```
+
+Runs a Node.js script with network interception enabled:
+
+```bash
+doru run server.js
+doru run app.mjs -- --port 3000
+doru run -o api.jsonl fetch-data.js
+```
+
+### Live UI Mode
+
+```bash
+doru --ui <script> [-- <script-args>]
+```
+
+Runs a script with real-time web UI for monitoring:
+
+```bash
+doru --ui server.js
+doru --ui app.mjs -- --port 8080
+```
+
+### Explorer Mode
+
+```bash
+doru --ui <capture.json|jsonl>
+```
+
+Opens the web UI to explore an existing capture file:
+
+```bash
+doru --ui capture.jsonl
+doru --ui network-capture.json
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Output file (default: `./network-capture.jsonl`) |
+| `-f, --format <fmt>` | `json` or `jsonl` (default: `jsonl`) |
+| `-c, --config <file>` | Config file path (JSON) |
+| `--ui <path>` | Explorer (capture file) or Live UI (script) |
+| `--debug` | Enable debug logs |
+| `--max-file-size <size>` | e.g. `10MB`, `500KB` |
+| `--include-hosts <list>` | Comma-separated hosts to capture |
+| `--exclude-hosts <list>` | Comma-separated hosts to skip |
+| `--include-paths <list>` | Comma-separated path patterns |
+| `--exclude-paths <list>` | Comma-separated path patterns |
+| `--methods <list>` | Comma-separated methods (e.g. `GET,POST`) |
+| `--min-status <code>` | Minimum status code (100-599) |
+| `--max-status <code>` | Maximum status code (100-599) |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+### Examples
+
+```bash
+# Basic capture
+doru run server.js
+
+# Custom output file and format
+doru run -o api-calls.json -f json server.js
+
+# Filter specific hosts
+doru run --include-hosts api.example.com,cdn.example.com app.js
+
+# Exclude localhost traffic
+doru run --exclude-hosts localhost,127.0.0.1 app.js
+
+# Only capture POST/PUT requests
+doru run --methods POST,PUT app.js
+
+# Only capture error responses
+doru run --min-status 400 app.js
+
+# Pass arguments to script
+doru run server.js -- --port 3000 --env production
+
+# Live UI with script
+doru --ui server.js -- --port 3000
+
+# Explore existing capture
+doru --ui ./network-capture.jsonl
+```
+