brakit 0.7.5 → 0.8.0

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 first · 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,19 +49,21 @@ 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
+- **AI-native via MCP** — Claude, Cursor, and other AI tools can query findings, inspect endpoints, and verify fixes directly
 
 ---
 
@@ -56,22 +79,24 @@ 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                                         |
 
 ---
 
 ## Who Is This For
 
-Developers using AI tools (Cursor, Copilot, Claude Code) to generate API code they don't fully review. Developers who debug with `console.log` and wish they could just see every action their API is executing. Anyone building Node.js APIs who wants to catch security and performance issues before production.
+- **AI-assisted developers** — Using Cursor, Copilot, or Claude Code to generate API code you don't fully review? Brakit catches the issues they introduce.
+- **Console.log debuggers** — Wish you could just see every action your API executes without adding log statements everywhere? That's literally what brakit does.
+- **Anyone shipping Node.js APIs** — If you want to catch security and performance issues before they reach production, brakit surfaces them as you develop.
 
 ---
 
@@ -83,6 +108,7 @@ import 'brakit'  →  hooks into http.Server  →  captures everything
                           +-- Dashboard UI    (/__brakit)
                           +-- Live SSE stream (real-time updates)
                           +-- Terminal output  (insights as you develop)
+                          +-- MCP server      (AI assistant integration)
 ```
 
 `import 'brakit'` runs inside your process. It patches `http.Server.prototype.emit` to intercept all requests — capturing request/response pairs, grouping them into actions, and streaming everything to the dashboard at `/__brakit` on your existing port. No proxy, no second process, no different port.
@@ -93,27 +119,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
 
@@ -134,7 +160,7 @@ Brakit never runs in production. 7 independent layers ensure it:
 npx brakit uninstall
 ```
 
-Removes the instrumentation file and devDependency. Your app is unchanged.
+Removes the instrumentation file, MCP configuration, `.brakit` data directory, `.gitignore` entry, and devDependency. Your app is unchanged.
 
 ---
 
@@ -157,35 +183,44 @@ 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)
+  mcp/            MCP server for AI tool integration (Claude, Cursor)
+    tools/        Tool implementations (one file per tool)
+  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
+- **MCP tools** — New AI-facing tools for the MCP server
 - **Dashboard** — Request diff, timeline view, HAR export
 
 Please open an issue first for larger changes so we can discuss the approach.

package/dist/api.d.ts

@@ -160,6 +160,50 @@ interface SecurityFinding {
     count: number;
 }
 
+type FindingState = "open" | "fixing" | "resolved";
+type FindingSource = "passive";
+interface StatefulFinding {
+    /** Stable ID derived from rule + endpoint + description hash */
+    findingId: string;
+    state: FindingState;
+    source: FindingSource;
+    finding: SecurityFinding;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    resolvedAt: number | null;
+    occurrences: number;
+}
+interface FindingsData {
+    version: 1;
+    findings: StatefulFinding[];
+}
+
+declare class FindingStore {
+    private rootDir;
+    private findings;
+    private flushTimer;
+    private dirty;
+    private writing;
+    private readonly findingsPath;
+    private readonly tmpPath;
+    private readonly metricsDir;
+    constructor(rootDir: string);
+    start(): void;
+    stop(): void;
+    upsert(finding: SecurityFinding, source: FindingSource): StatefulFinding;
+    transition(findingId: string, state: FindingState): boolean;
+    reconcilePassive(currentFindings: readonly SecurityFinding[]): void;
+    getAll(): readonly StatefulFinding[];
+    getByState(state: FindingState): readonly StatefulFinding[];
+    get(findingId: string): StatefulFinding | undefined;
+    clear(): void;
+    private load;
+    private flush;
+    private flushSync;
+    private writeAsync;
+    private ensureDir;
+}
+
 interface BrakitAdapter {
     name: string;
     detect(): boolean;
@@ -285,6 +329,7 @@ declare class MetricsStore {
 type AnalysisListener = (insights: Insight[], findings: SecurityFinding[]) => void;
 declare class AnalysisEngine {
     private metricsStore;
+    private findingStore?;
     private debounceMs;
     private scanner;
     private cachedInsights;
@@ -295,7 +340,7 @@ declare class AnalysisEngine {
     private boundQueryListener;
     private boundErrorListener;
     private boundLogListener;
-    constructor(metricsStore: MetricsStore, debounceMs?: number);
+    constructor(metricsStore: MetricsStore, findingStore?: FindingStore | undefined, debounceMs?: number);
     start(): void;
     stop(): void;
     onUpdate(fn: AnalysisListener): void;
@@ -308,4 +353,4 @@ declare class AnalysisEngine {
 
 declare const VERSION: string;
 
-export { AdapterRegistry, AnalysisEngine, type BrakitAdapter, type BrakitConfig, type DetectedProject, type FlatHeaders, type Framework, type HttpMethod, type Insight, type InsightContext, type InsightRule, InsightRunner, type NormalizedOp, type RequestCategory, type RequestListener, type SecurityContext, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type TracedRequest, VERSION, computeInsights, createDefaultInsightRunner, createDefaultScanner, detectProject };
+export { AdapterRegistry, AnalysisEngine, type BrakitAdapter, type BrakitConfig, type DetectedProject, type FindingSource, type FindingState, FindingStore, type FindingsData, type FlatHeaders, type Framework, type HttpMethod, type Insight, type InsightContext, type InsightRule, InsightRunner, type NormalizedOp, type RequestCategory, type RequestListener, type SecurityContext, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type StatefulFinding, type TracedRequest, VERSION, computeInsights, createDefaultInsightRunner, createDefaultScanner, detectProject };