brakit 0.7.6 → 0.8.0

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">
@@ -63,6 +63,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 +94,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 +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.
@@ -156,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.
 
 ---
 
@@ -194,6 +198,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 +220,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

@@ -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 };

package/dist/api.js

@@ -1,6 +1,53 @@
-// src/detect/project.ts
-import { readFile as readFile2 } from "fs/promises";
-import { join } from "path";
+// src/store/finding-store.ts
+import {
+  readFileSync as readFileSync2,
+  writeFileSync as writeFileSync2,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  renameSync
+} from "fs";
+import { writeFile as writeFile2, mkdir, rename } from "fs/promises";
+import { resolve as resolve2 } from "path";
+
+// src/constants/routes.ts
+var DASHBOARD_PREFIX = "/__brakit";
+
+// src/constants/limits.ts
+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/constants/metrics.ts
+var METRICS_DIR = ".brakit";
+var FINDINGS_FILE = ".brakit/findings.json";
+var FINDINGS_FLUSH_INTERVAL_MS = 1e4;
 
 // src/utils/fs.ts
 import { access } from "fs/promises";
@@ -14,8 +61,191 @@ async function fileExists(path) {
     return false;
   }
 }
+function ensureGitignore(dir, entry) {
+  try {
+    const gitignorePath = resolve(dir, "../.gitignore");
+    if (existsSync(gitignorePath)) {
+      const content = readFileSync(gitignorePath, "utf-8");
+      if (content.split("\n").some((l) => l.trim() === entry)) return;
+      writeFileSync(gitignorePath, content.trimEnd() + "\n" + entry + "\n");
+    } else {
+      writeFileSync(gitignorePath, entry + "\n");
+    }
+  } catch {
+  }
+}
+
+// src/store/finding-id.ts
+import { createHash } from "crypto";
+function computeFindingId(finding) {
+  const key = `${finding.rule}:${finding.endpoint}:${finding.desc}`;
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+
+// src/store/finding-store.ts
+var FindingStore = class {
+  constructor(rootDir) {
+    this.rootDir = rootDir;
+    this.metricsDir = resolve2(rootDir, METRICS_DIR);
+    this.findingsPath = resolve2(rootDir, FINDINGS_FILE);
+    this.tmpPath = this.findingsPath + ".tmp";
+    this.load();
+  }
+  findings = /* @__PURE__ */ new Map();
+  flushTimer = null;
+  dirty = false;
+  writing = false;
+  findingsPath;
+  tmpPath;
+  metricsDir;
+  start() {
+    this.flushTimer = setInterval(
+      () => this.flush(),
+      FINDINGS_FLUSH_INTERVAL_MS
+    );
+    this.flushTimer.unref();
+  }
+  stop() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.flushSync();
+  }
+  upsert(finding, source) {
+    const id = computeFindingId(finding);
+    const existing = this.findings.get(id);
+    const now = Date.now();
+    if (existing) {
+      existing.lastSeenAt = now;
+      existing.occurrences++;
+      existing.finding = finding;
+      if (existing.state === "resolved") {
+        existing.state = "open";
+        existing.resolvedAt = null;
+      }
+      this.dirty = true;
+      return existing;
+    }
+    const stateful = {
+      findingId: id,
+      state: "open",
+      source,
+      finding,
+      firstSeenAt: now,
+      lastSeenAt: now,
+      resolvedAt: null,
+      occurrences: 1
+    };
+    this.findings.set(id, stateful);
+    this.dirty = true;
+    return stateful;
+  }
+  transition(findingId, state) {
+    const finding = this.findings.get(findingId);
+    if (!finding) return false;
+    finding.state = state;
+    if (state === "resolved") {
+      finding.resolvedAt = Date.now();
+    }
+    this.dirty = true;
+    return true;
+  }
+  reconcilePassive(currentFindings) {
+    const currentIds = new Set(currentFindings.map(computeFindingId));
+    for (const [id, stateful] of this.findings) {
+      if (stateful.source === "passive" && stateful.state === "open" && !currentIds.has(id)) {
+        stateful.state = "resolved";
+        stateful.resolvedAt = Date.now();
+        this.dirty = true;
+      }
+    }
+  }
+  getAll() {
+    return [...this.findings.values()];
+  }
+  getByState(state) {
+    return [...this.findings.values()].filter((f) => f.state === state);
+  }
+  get(findingId) {
+    return this.findings.get(findingId);
+  }
+  clear() {
+    this.findings.clear();
+    this.dirty = true;
+  }
+  load() {
+    try {
+      if (existsSync2(this.findingsPath)) {
+        const raw = readFileSync2(this.findingsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.version === 1 && Array.isArray(parsed.findings)) {
+          for (const f of parsed.findings) {
+            this.findings.set(f.findingId, f);
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  flush() {
+    if (!this.dirty) return;
+    this.writeAsync();
+  }
+  flushSync() {
+    if (!this.dirty) return;
+    try {
+      this.ensureDir();
+      const data = {
+        version: 1,
+        findings: [...this.findings.values()]
+      };
+      writeFileSync2(this.tmpPath, JSON.stringify(data));
+      renameSync(this.tmpPath, this.findingsPath);
+      this.dirty = false;
+    } catch (err) {
+      process.stderr.write(
+        `[brakit] failed to save findings: ${err.message}
+`
+      );
+    }
+  }
+  async writeAsync() {
+    if (this.writing) return;
+    this.writing = true;
+    try {
+      if (!existsSync2(this.metricsDir)) {
+        await mkdir(this.metricsDir, { recursive: true });
+        ensureGitignore(this.metricsDir, METRICS_DIR);
+      }
+      const data = {
+        version: 1,
+        findings: [...this.findings.values()]
+      };
+      await writeFile2(this.tmpPath, JSON.stringify(data));
+      await rename(this.tmpPath, this.findingsPath);
+      this.dirty = false;
+    } catch (err) {
+      process.stderr.write(
+        `[brakit] failed to save findings: ${err.message}
+`
+      );
+    } finally {
+      this.writing = false;
+      if (this.dirty) this.writeAsync();
+    }
+  }
+  ensureDir() {
+    if (!existsSync2(this.metricsDir)) {
+      mkdirSync2(this.metricsDir, { recursive: true });
+      ensureGitignore(this.metricsDir, METRICS_DIR);
+    }
+  }
+};
 
 // src/detect/project.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join } from "path";
 var FRAMEWORKS = [
   { name: "nextjs", dep: "next", devCmd: "next dev", bin: "next", defaultPort: 3e3, devArgs: ["dev", "--port"] },
   { name: "remix", dep: "@remix-run/dev", devCmd: "remix dev", bin: "remix", defaultPort: 3e3, devArgs: ["dev"] },
@@ -409,34 +639,6 @@ 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;
@@ -623,13 +825,6 @@ function createDefaultScanner() {
   return scanner;
 }
 
-// src/constants/routes.ts
-var DASHBOARD_PREFIX = "/__brakit";
-
-// src/constants/limits.ts
-var MAX_REQUEST_ENTRIES = 1e3;
-var MAX_TELEMETRY_ENTRIES = 1e3;
-
 // src/utils/static-patterns.ts
 var STATIC_PATTERNS = [
   /^\/_next\//,
@@ -778,15 +973,15 @@ function getEndpointKey(method, path) {
 
 // src/store/metrics/persistence.ts
 import {
-  readFileSync as readFileSync2,
-  writeFileSync as writeFileSync2,
-  mkdirSync as mkdirSync2,
-  existsSync as existsSync2,
+  readFileSync as readFileSync3,
+  writeFileSync as writeFileSync3,
+  mkdirSync as mkdirSync3,
+  existsSync as existsSync3,
   unlinkSync,
-  renameSync
+  renameSync as renameSync2
 } from "fs";
-import { writeFile as writeFile2, mkdir, rename } from "fs/promises";
-import { resolve as resolve2 } from "path";
+import { writeFile as writeFile3, mkdir as mkdir2, rename as rename2 } from "fs/promises";
+import { resolve as resolve3 } from "path";
 
 // src/analysis/group.ts
 import { randomUUID as randomUUID3 } from "crypto";
@@ -1797,8 +1992,9 @@ function computeInsights(ctx) {
 
 // src/analysis/engine.ts
 var AnalysisEngine = class {
-  constructor(metricsStore, debounceMs = 300) {
+  constructor(metricsStore, findingStore, debounceMs = 300) {
     this.metricsStore = metricsStore;
+    this.findingStore = findingStore;
     this.debounceMs = debounceMs;
     this.scanner = createDefaultScanner();
     this.boundRequestListener = () => this.scheduleRecompute();
@@ -1859,6 +2055,12 @@ var AnalysisEngine = class {
     const fetches = defaultFetchStore.getAll();
     const flows = groupRequestsIntoFlows(requests);
     this.cachedFindings = this.scanner.scan({ requests, logs });
+    if (this.findingStore) {
+      for (const finding of this.cachedFindings) {
+        this.findingStore.upsert(finding, "passive");
+      }
+      this.findingStore.reconcilePassive(this.cachedFindings);
+    }
     this.cachedInsights = computeInsights({
       requests,
       queries,
@@ -1878,10 +2080,11 @@ var AnalysisEngine = class {
 };
 
 // src/index.ts
-var VERSION = "0.7.6";
+var VERSION = "0.8.0";
 export {
   AdapterRegistry,
   AnalysisEngine,
+  FindingStore,
   InsightRunner,
   SecurityScanner,
   VERSION,