procsi 0.2.6

package/dist/shared/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/shared/version.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAUzC"}

package/dist/shared/version.js

@@ -0,0 +1,21 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Get procsi version from package.json.
+ */
+export function getProcsiVersion() {
+    try {
+        // Find package.json relative to this file (dist/shared/version.js -> package.json)
+        const packageJsonPath = path.resolve(__dirname, "..", "..", "package.json");
+        const content = fs.readFileSync(packageJsonPath, "utf-8");
+        const pkg = JSON.parse(content);
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+//# sourceMappingURL=version.js.map

package/dist/shared/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/shared/version.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,mFAAmF;QACnF,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QAC5E,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAyB,CAAC;QACxD,OAAO,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "procsi",
+  "version": "0.2.6",
+  "description": "Terminal HTTP interception toolkit",
+  "type": "module",
+  "main": "dist/cli/index.js",
+  "bin": {
+    "procsi": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": "./dist/cli/index.js",
+    "./interceptors": {
+      "types": "./dist/interceptors.d.ts",
+      "default": "./dist/interceptors.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "agents": {
+    "skills": [
+      {
+        "name": "procsi",
+        "path": "./skills/procsi"
+      }
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run --dir src",
+    "test:int": "vitest run --dir tests/integration",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "keywords": [
+    "http",
+    "https",
+    "proxy",
+    "intercept",
+    "mitm",
+    "debugging",
+    "cli",
+    "tui",
+    "terminal"
+  ],
+  "author": "",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mtford90/procsi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mtford90/procsi/issues"
+  },
+  "homepage": "https://github.com/mtford90/procsi#readme",
+  "packageManager": "pnpm@10.13.1",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@ink-tools/ink-mouse": "^2.1.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "cli-highlight": "^2.1.11",
+    "commander": "^14.0.3",
+    "global-agent": "^3.0.0",
+    "ink": "^6.6.0",
+    "ink-use-stdout-dimensions": "^1.0.5",
+    "jiti": "^2.6.1",
+    "mockttp": "^4.2.1",
+    "react": "^19.2.4",
+    "undici": "^7.21.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.2.0",
+    "@types/react": "^19.2.10",
+    "@types/uuid": "^11.0.0",
+    "cli-testing-library": "^3.0.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "ink-testing-library": "^4.0.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
+}

package/skills/procsi/SKILL.md

@@ -0,0 +1,228 @@
+# /procsi
+
+Use procsi to inspect, filter, and intercept HTTP traffic. Activate when procsi MCP tools are available or when the user mentions HTTP traffic, API debugging, request interception, or mocking.
+
+## Installation & Setup
+
+If procsi is not installed or the daemon is not running, you can set it up:
+
+1. **Install**: `npm install -g procsi`
+2. **Shell setup** (one-time): Add `eval "$(procsi init)"` to the user's shell config (`~/.zshrc` or `~/.bashrc`), then source it or ask them to restart their shell
+3. **Start intercepting**: `eval "$(procsi vars)"` in the project directory (or `procsi on` if the shell wrapper is installed)
+4. **MCP config**: Add procsi to the MCP configuration:
+   ```json
+   {
+     "mcpServers": {
+       "procsi": {
+         "command": "procsi",
+         "args": ["mcp"]
+       }
+     }
+   }
+   ```
+
+After setup, call `procsi_get_status` to verify the daemon is running.
+
+## When to Use procsi
+
+- **Debugging failing API calls** -- filter by status code, inspect headers and response bodies
+- **Understanding traffic patterns** -- count requests, group by host/path/method
+- **Writing mocks/interceptors** -- capture real traffic as a template, write TypeScript interceptors
+- **Investigating auth issues** -- filter by `authorization` header, inspect tokens
+- **Performance analysis** -- check response times (`durationMs`), body sizes
+
+## Preflight
+
+Always call `procsi_get_status` first to confirm the daemon is running. If it is not running, try to start it by running `eval "$(procsi vars)"` in the project directory. If procsi is not installed, follow the Installation & Setup steps above.
+
+## MCP Tool Reference
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `procsi_get_status` | Check daemon is running, get proxy port and request count | -- |
+| `procsi_list_requests` | Browse/filter captured traffic (returns summaries) | `method`, `status_range`, `search`, `host`, `path`, `header_name`, `header_value`, `header_target`, `intercepted_by`, `since`, `before`, `limit`, `offset`, `format` |
+| `procsi_get_request` | Full request details -- headers, bodies, timing | `id` (single or comma-separated IDs), `format` |
+| `procsi_search_bodies` | Full-text search in request/response bodies | `query`, plus all filter params |
+| `procsi_query_json` | Extract JSON values with JSONPath (SQLite `json_extract`) | `json_path`, `value`, `target` (`request`/`response`/`both`), plus filters |
+| `procsi_count_requests` | Count matching requests | All filter params, `format` |
+| `procsi_clear_requests` | Delete all captured traffic (irreversible) | -- |
+| `procsi_list_sessions` | List active proxy sessions | -- |
+| `procsi_list_interceptors` | List loaded interceptors with status/errors | `format` |
+| `procsi_reload_interceptors` | Hot-reload interceptors from disk | `format` |
+
+### Output Formats
+
+All query tools accept `format`:
+- `"text"` (default) -- human-readable markdown summaries
+- `"json"` -- structured JSON for programmatic processing
+
+Use `"json"` when you need to process results (e.g. extract IDs, compare values). Use `"text"` when presenting to the user.
+
+## Common Filter Patterns
+
+```
+status_range: "5xx"            # Server errors
+status_range: "4xx"            # Client errors
+status_range: "401"            # Exact status code
+status_range: "500-503"        # Numeric range
+method: "POST,PUT"             # Mutation requests only
+host: ".api.example.com"       # Suffix match (note leading dot)
+host: "api.example.com"        # Exact match
+path: "/api/v2"                # Path prefix match
+search: "api/users"            # URL substring match
+header_name: "authorization"   # Requests with this header
+header_name: "content-type", header_value: "application/json"  # Exact header match
+header_target: "request"       # Only search request headers
+intercepted_by: "my-mock"      # Requests handled by a specific interceptor
+since: "2024-01-15T10:30:00Z"  # Time-bounded queries
+```
+
+Filters can be combined freely. All are optional.
+
+## Workflow Patterns
+
+### Pattern 1: Investigate a Bug
+
+1. `procsi_list_requests` with relevant filters (status code, host, path) to find the request
+2. `procsi_get_request` with the ID to inspect full headers, bodies, timing
+3. If searching for specific content in bodies, use `procsi_search_bodies`
+
+### Pattern 2: Write a Mock Interceptor
+
+1. `procsi_list_requests` to understand the traffic pattern you want to mock
+2. `procsi_get_request` to capture a real response as a template
+3. Write a `.ts` file to `.procsi/interceptors/` (see interceptor patterns below)
+4. `procsi_reload_interceptors` to activate
+5. `procsi_list_interceptors` to verify it loaded without errors
+
+### Pattern 3: Analyse API Usage
+
+1. `procsi_count_requests` with various filters to understand volume
+2. `procsi_query_json` to extract specific values from JSON bodies
+3. `procsi_list_requests` with `format: "json"` for structured analysis
+
+### Pattern 4: Debug Auth Issues
+
+1. `procsi_list_requests` with `header_name: "authorization", header_target: "request"` to find authed requests
+2. `procsi_list_requests` with `status_range: "401"` to find failures
+3. `procsi_get_request` to compare auth headers between successful and failed requests
+
+## Writing Interceptors
+
+Interceptor files are TypeScript files placed in `.procsi/interceptors/`. Each file exports a default `Interceptor` object.
+
+### Mock -- Return a Canned Response
+
+```typescript
+import type { Interceptor } from "procsi/interceptors";
+
+export default {
+  name: "mock-users",
+  match: (req) => req.path === "/api/users",
+  handler: async () => ({
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify([{ id: 1, name: "Alice" }]),
+  }),
+} satisfies Interceptor;
+```
+
+Do not call `ctx.forward()` -- the request never reaches upstream. This is recorded as `interceptionType: "mocked"`.
+
+### Modify -- Forward, Then Alter the Response
+
+```typescript
+import type { Interceptor } from "procsi/interceptors";
+
+export default {
+  name: "inject-header",
+  match: (req) => req.host.includes("example.com"),
+  handler: async (ctx) => {
+    const response = await ctx.forward();
+    return { ...response, headers: { ...response.headers, "x-debug": "procsi" } };
+  },
+} satisfies Interceptor;
+```
+
+Calls `ctx.forward()` but returns a modified response. Recorded as `interceptionType: "modified"`.
+
+### Observe -- Log Without Altering
+
+```typescript
+import type { Interceptor } from "procsi/interceptors";
+
+export default {
+  name: "log-api",
+  match: (req) => req.path.startsWith("/api/"),
+  handler: async (ctx) => {
+    ctx.log(`${ctx.request.method} ${ctx.request.url}`);
+    const response = await ctx.forward();
+    ctx.log(`  -> ${response.status}`);
+    return response;
+  },
+} satisfies Interceptor;
+```
+
+Calls `ctx.forward()` and returns the response unchanged. Useful for debugging.
+
+### InterceptorContext Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ctx.request` | `Readonly<InterceptorRequest>` | The incoming request (read-only) |
+| `ctx.forward()` | `() => Promise<InterceptorResponse>` | Forward to upstream server, returns response |
+| `ctx.log(msg)` | `(message: string) => void` | Write to `.procsi/procsi.log` (`console.log` is `/dev/null` in daemon) |
+| `ctx.procsi` | `ProcsiClient` | Full query API (see below) |
+
+### InterceptorRequest Shape
+
+| Property | Type |
+|----------|------|
+| `method` | `string` |
+| `url` | `string` |
+| `host` | `string` |
+| `path` | `string` |
+| `headers` | `Record<string, string>` |
+| `body` | `Buffer \| undefined` |
+
+### InterceptorResponse Shape
+
+| Property | Type |
+|----------|------|
+| `status` | `number` |
+| `headers` | `Record<string, string> \| undefined` |
+| `body` | `string \| Buffer \| undefined` |
+
+### ProcsiClient API (available as `ctx.procsi`)
+
+```typescript
+ctx.procsi.countRequests(filter?)          // Promise<number>
+ctx.procsi.listRequests({ filter, limit, offset })  // Promise<CapturedRequestSummary[]>
+ctx.procsi.getRequest(id)                  // Promise<CapturedRequest | null>
+ctx.procsi.searchBodies({ query, filter, limit })    // Promise<CapturedRequestSummary[]>
+ctx.procsi.queryJsonBodies({ jsonPath, filter })      // Promise<JsonQueryResult[]>
+```
+
+This allows interceptors to make decisions based on previously captured traffic.
+
+### Interceptor Rules
+
+- Any `.ts` file in `.procsi/interceptors/` is loaded as an interceptor
+- Files are loaded alphabetically; **first matching interceptor wins**
+- `match` is optional -- omit it to match all requests
+- `name` is optional but strongly recommended (used in `intercepted_by` filter)
+- Use `satisfies Interceptor` for full type checking and intellisense
+- Handler timeout: 30 seconds. Match timeout: 5 seconds.
+- Errors in handlers result in graceful pass-through -- never crashes the proxy
+- `ctx.log()` writes to `.procsi/procsi.log` (since `console.log` goes nowhere in the daemon)
+- Hot-reload on file changes, or run `procsi interceptors reload` / `procsi_reload_interceptors` / `procsi daemon restart`
+
+## Tips
+
+- After writing an interceptor, always `procsi_reload_interceptors` then `procsi_list_interceptors` to verify it loaded without errors
+- The `search` filter matches URL substrings -- useful for quick filtering when you do not know the exact host or path
+- `procsi_query_json` uses SQLite `json_extract` syntax (e.g. `$.user.name`, `$.items[0].id`)
+- Use `limit` and `offset` for pagination when there are many results (default limit: 50, max: 500)
+- `procsi_get_request` accepts comma-separated IDs for batch fetching (e.g. `id: "id1,id2,id3"`)
+- Host suffix matching requires a leading dot: `.example.com` matches `api.example.com` and `www.example.com`
+- Time filters use ISO 8601 format: `since: "2024-01-15T10:30:00Z"`