brakit 0.7.5 → 0.7.6

package/README.md

@@ -1,17 +1,38 @@
-# Brakit
-
-**See what your app is actually doing.**
-
-Every request, query, and security issue — before you ship.
-
-Open source · Local only · Zero config · 2 dependencies
-
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg)](https://typescriptlang.org)
+<h1 align="center"><img src="docs/images/icon.png" height="24" alt="" />&nbsp;&nbsp;Brakit</h1>
+
+<p align="center">
+  <b>See what your app is actually doing.</b> <br />
+  Every request, query, and security issue — before you ship. <br />
+  <b>Open source · Local only · Zero config · 2 dependencies</b>
+</p>
+
+<h3 align="center">
+  <a href="docs/design/architecture.md">Architecture</a> &bull;
+  <a href="https://brakit.ai">Website</a> &bull;
+  <a href="CONTRIBUTING.md">Contributing</a>
+</h3>
+
+<h4 align="center">
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" />
+  </a>
+  <a href="https://nodejs.org">
+    <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node >= 18" />
+  </a>
+  <a href="https://typescriptlang.org">
+    <img src="https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg" alt="TypeScript" />
+  </a>
+  <a href="CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen" alt="PRs welcome!" />
+  </a>
+</h4>
 
 ---
 
+<p align="center">
+  <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard" />
+</p>
+
 ## Quick Start
 
 ```bash
@@ -28,18 +49,19 @@ Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
 
 > **Requirements:** Node.js >= 18 and a project with `package.json`.
 
-[Documentation](https://brakit.ai/docs) · [Website](https://brakit.ai)
-
 ---
 
 ## What You Get
 
-- **8 security rules** scanned against live traffic — leaked secrets, PII in responses, missing auth, N+1 queries flagged automatically
+- **Live dashboard** at `/__brakit` — performance overview, request history, scatter charts, real-time via SSE
+- **8 security rules** scanned against live traffic — leaked secrets, PII in responses, missing auth flags
+- **Time breakdown** — every endpoint shows where time goes: DB, Fetch, or App code
+- **N+1 query detection** — same query pattern repeated 5+ times in a single request
+- **Regression detection** — p95 latency or query count increased vs. previous session
 - **Action-level visibility** — see "Sign Up" and "Load Dashboard", not 47 raw HTTP requests
 - **Duplicate detection** — same API called twice? Flagged with redundancy percentage
-- **N+1 query detection** — same query pattern repeated 5+ times in a single request? That's an N+1
 - **Full server tracing** — fetch calls, DB queries, console logs, errors — zero code changes
-- **Live dashboard** at `/__brakit` — 9 tabs updating in real-time
+- **Response overfetch** — large JSON responses with many fields your client doesn't use
 - **Performance tracking** — health grades and p95 trends across dev sessions
 
 ---
@@ -56,16 +78,16 @@ Brakit watches every action your app takes — not raw HTTP noise, but what actu
 
 8 high-confidence rules that scan your live traffic and flag real issues — not theoretical ones:
 
-|              | Rule             | What it catches                                                                 |
-| ------------ | ---------------- | ------------------------------------------------------------------------------- |
-| **Critical** | Exposed Secret   | Response contains `password`, `api_key`, `client_secret` fields with real values |
-| **Critical** | Token in URL     | Auth tokens in query parameters instead of headers                              |
-| **Critical** | Stack Trace Leak | Internal stack traces sent to the client                                        |
-| **Critical** | Error Info Leak  | DB connection strings, SQL queries, or secret values in error responses          |
-| Warning      | PII in Response  | API echoes back emails, returns full user records with internal IDs              |
-| Warning      | Insecure Cookie  | Missing `HttpOnly` or `SameSite` flags                                          |
-| Warning      | Sensitive Logs   | Passwords, secrets, or token values in console output                           |
-| Warning      | CORS + Credentials | `credentials: true` with wildcard origin                                      |
+|              | Rule               | What it catches                                                                  |
+| ------------ | ------------------ | -------------------------------------------------------------------------------- |
+| **Critical** | Exposed Secret     | Response contains `password`, `api_key`, `client_secret` fields with real values |
+| **Critical** | Token in URL       | Auth tokens in query parameters instead of headers                               |
+| **Critical** | Stack Trace Leak   | Internal stack traces sent to the client                                         |
+| **Critical** | Error Info Leak    | DB connection strings, SQL queries, or secret values in error responses          |
+| Warning      | PII in Response    | API echoes back emails, returns full user records with internal IDs              |
+| Warning      | Insecure Cookie    | Missing `HttpOnly` or `SameSite` flags                                           |
+| Warning      | Sensitive Logs     | Passwords, secrets, or token values in console output                            |
+| Warning      | CORS + Credentials | `credentials: true` with wildcard origin                                         |
 
 ---
 
@@ -93,27 +115,27 @@ Instrumentation hooks capture fetch calls, DB queries, console output, and error
 
 Brakit never runs in production. 7 independent layers ensure it:
 
-| # | Layer | How it blocks |
-|---|---|---|
-| 1 | `shouldActivate()` | Checks `NODE_ENV` + 15 cloud/CI env vars |
-| 2 | `instrumentation.ts` guard | Its own `NODE_ENV !== 'production'` check |
-| 3 | devDependency | Pruned in production builds |
-| 4 | `try/catch` on import | Missing module = silent no-op |
-| 5 | Localhost-only dashboard | Non-local IPs get 404 on `/__brakit` |
-| 6 | `safeWrap` + circuit breaker | 10 errors = brakit self-disables |
-| 7 | `BRAKIT_DISABLE=true` | Manual kill switch |
+| #   | Layer                        | How it blocks                             |
+| --- | ---------------------------- | ----------------------------------------- |
+| 1   | `shouldActivate()`           | Checks `NODE_ENV` + 15 cloud/CI env vars  |
+| 2   | `instrumentation.ts` guard   | Its own `NODE_ENV !== 'production'` check |
+| 3   | devDependency                | Pruned in production builds               |
+| 4   | `try/catch` on import        | Missing module = silent no-op             |
+| 5   | Localhost-only dashboard     | Non-local IPs get 404 on `/__brakit`      |
+| 6   | `safeWrap` + circuit breaker | 10 errors = brakit self-disables          |
+| 7   | `BRAKIT_DISABLE=true`        | Manual kill switch                        |
 
 ### Supported Frameworks
 
-| Framework   | Status                     |
-| ----------- | -------------------------- |
-| Next.js     | Full support (auto-detect) |
-| Remix       | Auto-detect                |
-| Nuxt        | Auto-detect                |
-| Vite        | Auto-detect                |
-| Astro       | Auto-detect                |
-| Express     | Auto-detect                |
-| Fastify     | Auto-detect                |
+| Framework | Status                     |
+| --------- | -------------------------- |
+| Next.js   | Full support (auto-detect) |
+| Remix     | Auto-detect                |
+| Nuxt      | Auto-detect                |
+| Vite      | Auto-detect                |
+| Astro     | Auto-detect                |
+| Express   | Auto-detect                |
+| Fastify   | Auto-detect                |
 
 ### Supported Databases
 
@@ -157,34 +179,40 @@ Only 2 production dependencies: `citty` (CLI) and `picocolors` (terminal colors)
 
 ```
 src/
-  runtime/        In-process entry point, server hooks, capture, safety
-  analysis/       Security scanning, N+1 detection, insights engine
+  runtime/        In-process entry point, interceptor, capture, safety
+  analysis/       Insights engine and security scanner
+    insights/     InsightRule implementations (one file per rule)
     rules/        SecurityRule implementations (one file per rule)
   cli/            CLI commands (install, uninstall)
+  constants/      Shared thresholds, route paths, limits
   dashboard/
     api/          REST handlers — requests, flows, telemetry, metrics
     client/       Browser JS generated as template strings
       views/      Tab renderers (overview, flows, graph, etc.)
     styles/       CSS modules
   detect/         Framework auto-detection
-  instrument/     Runtime hooks and database adapters
+  instrument/     Database adapters and instrumentation hooks
     adapters/     BrakitAdapter implementations (one file per library)
     hooks/        Core hooks (fetch, console, errors, context)
+  output/         Terminal insight listener
   store/          In-memory telemetry stores + persistent metrics
   types/          TypeScript definitions by domain
+  utils/          Shared utilities (collections, format, math, endpoint)
 ```
 
 ---
 
 ## Contributing
 
-Brakit is early and moving fast. The most common contributions — adding a new
-database adapter or a new security rule — each require exactly one file and one
-interface. See [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step guides.
+Brakit is early and moving fast. The most common contributions — adding a
+database adapter, a security rule, or an insight rule — each require exactly
+one file and one interface. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+step-by-step guides.
 
 Some areas where help would be great:
 
 - **Database adapters** — Drizzle, Mongoose, SQLite, MongoDB
+- **Insight rules** — New performance patterns, custom thresholds
 - **Security rules** — More patterns, configurable severity
 - **Dashboard** — Request diff, timeline view, HAR export
 

package/dist/api.js

@@ -409,6 +409,58 @@ var corsCredentialsRule = {
   }
 };
 
+// src/constants/thresholds.ts
+var FLOW_GAP_MS = 5e3;
+var SLOW_REQUEST_THRESHOLD_MS = 2e3;
+var MIN_POLLING_SEQUENCE = 3;
+var ENDPOINT_TRUNCATE_LENGTH = 12;
+var N1_QUERY_THRESHOLD = 5;
+var ERROR_RATE_THRESHOLD_PCT = 20;
+var SLOW_ENDPOINT_THRESHOLD_MS = 1e3;
+var MIN_REQUESTS_FOR_INSIGHT = 2;
+var HIGH_QUERY_COUNT_PER_REQ = 5;
+var CROSS_ENDPOINT_MIN_ENDPOINTS = 3;
+var CROSS_ENDPOINT_PCT = 50;
+var CROSS_ENDPOINT_MIN_OCCURRENCES = 5;
+var REDUNDANT_QUERY_MIN_COUNT = 2;
+var LARGE_RESPONSE_BYTES = 51200;
+var HIGH_ROW_COUNT = 100;
+var OVERFETCH_MIN_REQUESTS = 2;
+var OVERFETCH_MIN_FIELDS = 8;
+var OVERFETCH_MIN_INTERNAL_IDS = 2;
+var OVERFETCH_NULL_RATIO = 0.3;
+var REGRESSION_PCT_THRESHOLD = 50;
+var REGRESSION_MIN_INCREASE_MS = 200;
+var REGRESSION_MIN_REQUESTS = 5;
+var QUERY_COUNT_REGRESSION_RATIO = 1.5;
+var OVERFETCH_MANY_FIELDS = 12;
+var OVERFETCH_UNWRAP_MIN_SIZE = 3;
+var MAX_DUPLICATE_INSIGHTS = 3;
+
+// src/utils/response.ts
+function unwrapResponse(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
+  const obj = parsed;
+  const keys = Object.keys(obj);
+  if (keys.length > 3) return parsed;
+  let best = null;
+  let bestSize = 0;
+  for (const key of keys) {
+    const val = obj[key];
+    if (Array.isArray(val) && val.length > bestSize) {
+      best = val;
+      bestSize = val.length;
+    } else if (val && typeof val === "object" && !Array.isArray(val)) {
+      const size = Object.keys(val).length;
+      if (size > bestSize) {
+        best = val;
+        bestSize = size;
+      }
+    }
+  }
+  return best && bestSize >= OVERFETCH_UNWRAP_MIN_SIZE ? best : parsed;
+}
+
 // src/analysis/rules/response-pii-leak.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
 var FULL_RECORD_MIN_FIELDS = 5;
@@ -453,28 +505,6 @@ function hasInternalIds(obj) {
   }
   return false;
 }
-function unwrapResponse(parsed) {
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
-  const obj = parsed;
-  const keys = Object.keys(obj);
-  if (keys.length > 3) return parsed;
-  let best = null;
-  let bestSize = 0;
-  for (const key of keys) {
-    const val = obj[key];
-    if (Array.isArray(val) && val.length > bestSize) {
-      best = val;
-      bestSize = val.length;
-    } else if (val && typeof val === "object" && !Array.isArray(val)) {
-      const size = Object.keys(val).length;
-      if (size > bestSize) {
-        best = val;
-        bestSize = size;
-      }
-    }
-  }
-  return best && bestSize >= 3 ? best : parsed;
-}
 function detectPII(method, reqBody, resBody) {
   const target = unwrapResponse(resBody);
   if (WRITE_METHODS.has(method) && reqBody && typeof reqBody === "object") {
@@ -600,34 +630,6 @@ var DASHBOARD_PREFIX = "/__brakit";
 var MAX_REQUEST_ENTRIES = 1e3;
 var MAX_TELEMETRY_ENTRIES = 1e3;
 
-// src/constants/thresholds.ts
-var FLOW_GAP_MS = 5e3;
-var SLOW_REQUEST_THRESHOLD_MS = 2e3;
-var MIN_POLLING_SEQUENCE = 3;
-var ENDPOINT_TRUNCATE_LENGTH = 12;
-var N1_QUERY_THRESHOLD = 5;
-var ERROR_RATE_THRESHOLD_PCT = 20;
-var SLOW_ENDPOINT_THRESHOLD_MS = 1e3;
-var MIN_REQUESTS_FOR_INSIGHT = 2;
-var HIGH_QUERY_COUNT_PER_REQ = 5;
-var CROSS_ENDPOINT_MIN_ENDPOINTS = 3;
-var CROSS_ENDPOINT_PCT = 50;
-var CROSS_ENDPOINT_MIN_OCCURRENCES = 5;
-var REDUNDANT_QUERY_MIN_COUNT = 2;
-var LARGE_RESPONSE_BYTES = 51200;
-var HIGH_ROW_COUNT = 100;
-var OVERFETCH_MIN_REQUESTS = 2;
-var OVERFETCH_MIN_FIELDS = 8;
-var OVERFETCH_MIN_INTERNAL_IDS = 2;
-var OVERFETCH_NULL_RATIO = 0.3;
-var REGRESSION_PCT_THRESHOLD = 50;
-var REGRESSION_MIN_INCREASE_MS = 200;
-var REGRESSION_MIN_REQUESTS = 5;
-var QUERY_COUNT_REGRESSION_RATIO = 1.5;
-var OVERFETCH_MANY_FIELDS = 12;
-var OVERFETCH_UNWRAP_MIN_SIZE = 3;
-var MAX_DUPLICATE_INSIGHTS = 3;
-
 // src/utils/static-patterns.ts
 var STATIC_PATTERNS = [
   /^\/_next\//,
@@ -1642,30 +1644,6 @@ var highRowsRule = {
   }
 };
 
-// src/utils/response.ts
-function unwrapResponse2(parsed) {
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
-  const obj = parsed;
-  const keys = Object.keys(obj);
-  if (keys.length > 3) return parsed;
-  let best = null;
-  let bestSize = 0;
-  for (const key of keys) {
-    const val = obj[key];
-    if (Array.isArray(val) && val.length > bestSize) {
-      best = val;
-      bestSize = val.length;
-    } else if (val && typeof val === "object" && !Array.isArray(val)) {
-      const size = Object.keys(val).length;
-      if (size > bestSize) {
-        best = val;
-        bestSize = size;
-      }
-    }
-  }
-  return best && bestSize >= OVERFETCH_UNWRAP_MIN_SIZE ? best : parsed;
-}
-
 // src/analysis/insights/rules/response-overfetch.ts
 var responseOverfetchRule = {
   id: "response-overfetch",
@@ -1682,7 +1660,7 @@ var responseOverfetchRule = {
       } catch {
         continue;
       }
-      const target = unwrapResponse2(parsed);
+      const target = unwrapResponse(parsed);
       const inspectObj = Array.isArray(target) && target.length > 0 ? target[0] : target;
       if (!inspectObj || typeof inspectObj !== "object" || Array.isArray(inspectObj)) continue;
       const fields = Object.keys(inspectObj);
@@ -1900,7 +1878,7 @@ var AnalysisEngine = class {
 };
 
 // src/index.ts
-var VERSION = "0.7.5";
+var VERSION = "0.7.6";
 export {
   AdapterRegistry,
   AnalysisEngine,

package/dist/bin/brakit.js

@@ -386,6 +386,33 @@ var corsCredentialsRule = {
   }
 };
 
+// src/constants/thresholds.ts
+var OVERFETCH_UNWRAP_MIN_SIZE = 3;
+
+// src/utils/response.ts
+function unwrapResponse(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
+  const obj = parsed;
+  const keys = Object.keys(obj);
+  if (keys.length > 3) return parsed;
+  let best = null;
+  let bestSize = 0;
+  for (const key of keys) {
+    const val = obj[key];
+    if (Array.isArray(val) && val.length > bestSize) {
+      best = val;
+      bestSize = val.length;
+    } else if (val && typeof val === "object" && !Array.isArray(val)) {
+      const size = Object.keys(val).length;
+      if (size > bestSize) {
+        best = val;
+        bestSize = size;
+      }
+    }
+  }
+  return best && bestSize >= OVERFETCH_UNWRAP_MIN_SIZE ? best : parsed;
+}
+
 // src/analysis/rules/response-pii-leak.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
 var FULL_RECORD_MIN_FIELDS = 5;
@@ -430,28 +457,6 @@ function hasInternalIds(obj) {
   }
   return false;
 }
-function unwrapResponse(parsed) {
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
-  const obj = parsed;
-  const keys = Object.keys(obj);
-  if (keys.length > 3) return parsed;
-  let best = null;
-  let bestSize = 0;
-  for (const key of keys) {
-    const val = obj[key];
-    if (Array.isArray(val) && val.length > bestSize) {
-      best = val;
-      bestSize = val.length;
-    } else if (val && typeof val === "object" && !Array.isArray(val)) {
-      const size = Object.keys(val).length;
-      if (size > bestSize) {
-        best = val;
-        bestSize = size;
-      }
-    }
-  }
-  return best && bestSize >= 3 ? best : parsed;
-}
 function detectPII(method, reqBody, resBody) {
   const target = unwrapResponse(resBody);
   if (WRITE_METHODS.has(method) && reqBody && typeof reqBody === "object") {
@@ -695,7 +700,7 @@ import { resolve as resolve2 } from "path";
 import { randomUUID as randomUUID3 } from "crypto";
 
 // src/index.ts
-var VERSION = "0.7.5";
+var VERSION = "0.7.6";
 
 // src/cli/commands/install.ts
 var IMPORT_LINE = `import "brakit";`;

package/dist/runtime/index.js

@@ -3076,6 +3076,36 @@ var init_cors_credentials = __esm({
   }
 });
 
+// src/utils/response.ts
+function unwrapResponse(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
+  const obj = parsed;
+  const keys = Object.keys(obj);
+  if (keys.length > 3) return parsed;
+  let best = null;
+  let bestSize = 0;
+  for (const key of keys) {
+    const val = obj[key];
+    if (Array.isArray(val) && val.length > bestSize) {
+      best = val;
+      bestSize = val.length;
+    } else if (val && typeof val === "object" && !Array.isArray(val)) {
+      const size = Object.keys(val).length;
+      if (size > bestSize) {
+        best = val;
+        bestSize = size;
+      }
+    }
+  }
+  return best && bestSize >= OVERFETCH_UNWRAP_MIN_SIZE ? best : parsed;
+}
+var init_response = __esm({
+  "src/utils/response.ts"() {
+    "use strict";
+    init_thresholds();
+  }
+});
+
 // src/analysis/rules/response-pii-leak.ts
 function tryParseJson2(body) {
   if (!body) return null;
@@ -3117,28 +3147,6 @@ function hasInternalIds(obj) {
   }
   return false;
 }
-function unwrapResponse(parsed) {
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
-  const obj = parsed;
-  const keys = Object.keys(obj);
-  if (keys.length > 3) return parsed;
-  let best = null;
-  let bestSize = 0;
-  for (const key of keys) {
-    const val = obj[key];
-    if (Array.isArray(val) && val.length > bestSize) {
-      best = val;
-      bestSize = val.length;
-    } else if (val && typeof val === "object" && !Array.isArray(val)) {
-      const size = Object.keys(val).length;
-      if (size > bestSize) {
-        best = val;
-        bestSize = size;
-      }
-    }
-  }
-  return best && bestSize >= 3 ? best : parsed;
-}
 function detectPII(method, reqBody, resBody) {
   const target = unwrapResponse(resBody);
   if (WRITE_METHODS.has(method) && reqBody && typeof reqBody === "object") {
@@ -3186,6 +3194,7 @@ var init_response_pii_leak = __esm({
   "src/analysis/rules/response-pii-leak.ts"() {
     "use strict";
     init_patterns();
+    init_response();
     WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
     FULL_RECORD_MIN_FIELDS = 5;
     LIST_PII_MIN_ITEMS = 2;
@@ -3879,36 +3888,6 @@ var init_high_rows = __esm({
   }
 });
 
-// src/utils/response.ts
-function unwrapResponse2(parsed) {
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return parsed;
-  const obj = parsed;
-  const keys = Object.keys(obj);
-  if (keys.length > 3) return parsed;
-  let best = null;
-  let bestSize = 0;
-  for (const key of keys) {
-    const val = obj[key];
-    if (Array.isArray(val) && val.length > bestSize) {
-      best = val;
-      bestSize = val.length;
-    } else if (val && typeof val === "object" && !Array.isArray(val)) {
-      const size = Object.keys(val).length;
-      if (size > bestSize) {
-        best = val;
-        bestSize = size;
-      }
-    }
-  }
-  return best && bestSize >= OVERFETCH_UNWRAP_MIN_SIZE ? best : parsed;
-}
-var init_response = __esm({
-  "src/utils/response.ts"() {
-    "use strict";
-    init_thresholds();
-  }
-});
-
 // src/analysis/insights/rules/response-overfetch.ts
 var responseOverfetchRule;
 var init_response_overfetch = __esm({
@@ -3933,7 +3912,7 @@ var init_response_overfetch = __esm({
           } catch {
             continue;
           }
-          const target = unwrapResponse2(parsed);
+          const target = unwrapResponse(parsed);
           const inspectObj = Array.isArray(target) && target.length > 0 ? target[0] : target;
           if (!inspectObj || typeof inspectObj !== "object" || Array.isArray(inspectObj)) continue;
           const fields = Object.keys(inspectObj);
@@ -4226,7 +4205,7 @@ var init_src = __esm({
     init_engine();
     init_insights3();
     init_insights2();
-    VERSION = "0.7.5";
+    VERSION = "0.7.6";
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brakit",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "See what your API is really doing. Security scanning, N+1 detection, duplicate calls, DB queries — one command, zero config.",
   "type": "module",
   "bin": {