brakit 0.7.6 → 0.8.1

package/README.md

@@ -3,7 +3,7 @@
 <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>
+  <b>Open source · Local first · Zero config · 2 dependencies</b>
 </p>
 
 <h3 align="center">
@@ -22,6 +22,9 @@
   <a href="https://typescriptlang.org">
     <img src="https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg" alt="TypeScript" />
   </a>
+  <a href="https://www.npmjs.com/package/brakit">
+    <img src="https://img.shields.io/npm/v/brakit" alt="npm version" />
+  </a>
   <a href="CONTRIBUTING.md">
     <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen" alt="PRs welcome!" />
   </a>
@@ -30,7 +33,15 @@
 ---
 
 <p align="center">
-  <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard" />
+  <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard — issues surfaced automatically" />
+  <br />
+  <sub>Brakit catches N+1 queries, PII leaks, and slow endpoints as you develop</sub>
+</p>
+
+<p align="center">
+  <img width="700" src="docs/images/vscode.png" alt="Claude reading Brakit findings in VS Code" />
+  <br />
+  <sub>Claude reads findings via MCP and fixes your code</sub>
 </p>
 
 ## Quick Start
@@ -63,6 +74,7 @@ Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
 - **Full server tracing** — fetch calls, DB queries, console logs, errors — zero code changes
 - **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
 
 ---
 
@@ -93,7 +105,9 @@ Brakit watches every action your app takes — not raw HTTP noise, but what actu
 
 ## 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.
 
 ---
 
@@ -105,6 +119,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.
@@ -156,7 +171,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.
 
 ---
 
@@ -194,6 +209,8 @@ src/
   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
@@ -214,6 +231,7 @@ 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

@@ -149,7 +149,9 @@ interface RequestMetrics {
     fetchTimeMs: number;
 }
 
-type SecuritySeverity = "critical" | "warning" | "info";
+/** Shared severity levels used by both security findings and insights. */
+type Severity = "critical" | "warning" | "info";
+type SecuritySeverity = Severity;
 interface SecurityFinding {
     severity: SecuritySeverity;
     rule: string;
@@ -160,34 +162,25 @@ interface SecurityFinding {
     count: number;
 }
 
-interface BrakitAdapter {
-    name: string;
-    detect(): boolean;
-    patch(emit: (event: TelemetryEvent) => void): void;
-    unpatch?(): void;
-}
-
-interface SecurityContext {
-    requests: readonly TracedRequest[];
-    logs: readonly TracedLog[];
-}
-interface SecurityRule {
-    id: string;
-    severity: SecuritySeverity;
-    name: string;
-    hint: string;
-    check(ctx: SecurityContext): SecurityFinding[];
-}
-
-declare class SecurityScanner {
-    private rules;
-    register(rule: SecurityRule): void;
-    scan(ctx: SecurityContext): SecurityFinding[];
-    getRules(): readonly SecurityRule[];
+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 function createDefaultScanner(): SecurityScanner;
 
-type InsightSeverity = "critical" | "warning" | "info";
+type InsightSeverity = Severity;
 type InsightType = "n1" | "cross-endpoint" | "redundant-query" | "error" | "error-hotspot" | "duplicate" | "slow" | "query-heavy" | "select-star" | "high-rows" | "large-response" | "response-overfetch" | "security" | "regression";
 interface Insight {
     severity: InsightSeverity;
@@ -229,6 +222,71 @@ interface PreparedInsightContext extends InsightContext {
     endpointGroups: ReadonlyMap<string, EndpointGroup>;
 }
 
+type InsightState = "open" | "resolved";
+interface StatefulInsight {
+    key: string;
+    state: InsightState;
+    insight: Insight;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    resolvedAt: number | null;
+    /** Consecutive recompute cycles where the insight was not detected. */
+    consecutiveAbsences: number;
+}
+
+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;
+    patch(emit: (event: TelemetryEvent) => void): void;
+    unpatch?(): void;
+}
+
+interface SecurityContext {
+    requests: readonly TracedRequest[];
+    logs: readonly TracedLog[];
+}
+interface SecurityRule {
+    id: string;
+    severity: SecuritySeverity;
+    name: string;
+    hint: string;
+    check(ctx: SecurityContext): SecurityFinding[];
+}
+
+declare class SecurityScanner {
+    private rules;
+    register(rule: SecurityRule): void;
+    scan(ctx: SecurityContext): SecurityFinding[];
+    getRules(): readonly SecurityRule[];
+}
+declare function createDefaultScanner(): SecurityScanner;
+
 interface InsightRule {
     id: InsightType;
     check(ctx: PreparedInsightContext): Insight[];
@@ -282,30 +340,41 @@ declare class MetricsStore {
     private getOrCreateEndpoint;
 }
 
-type AnalysisListener = (insights: Insight[], findings: SecurityFinding[]) => void;
+interface AnalysisUpdate {
+    insights: Insight[];
+    findings: SecurityFinding[];
+    statefulFindings: readonly StatefulFinding[];
+    statefulInsights: readonly StatefulInsight[];
+}
+type AnalysisListener = (update: AnalysisUpdate) => void;
 declare class AnalysisEngine {
     private metricsStore;
+    private findingStore?;
     private debounceMs;
     private scanner;
+    private insightTracker;
     private cachedInsights;
     private cachedFindings;
+    private cachedStatefulInsights;
     private debounceTimer;
     private listeners;
     private boundRequestListener;
     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;
     offUpdate(fn: AnalysisListener): void;
     getInsights(): readonly Insight[];
     getFindings(): readonly SecurityFinding[];
+    getStatefulFindings(): readonly StatefulFinding[];
+    getStatefulInsights(): readonly StatefulInsight[];
     private scheduleRecompute;
     recompute(): void;
 }
 
 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 };