brakit 0.8.0 → 0.8.2

package/README.md

@@ -1,9 +1,9 @@
 <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>
+  <b>AI writes your code. Brakit watches what it does.</b> <br />
+  Every request, query, and security issue, caught before you ship. <br />
+  <b>Open source · Local first · Zero config · AI-native via MCP</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,7 +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
+- **AI-native via MCP** — Claude Code and Cursor can query findings, inspect endpoints, and verify fixes directly
 
 ---
 
@@ -177,7 +188,7 @@ npm run typecheck   # Type-check without emitting
 npm test            # Run tests with vitest
 ```
 
-Only 2 production dependencies: `citty` (CLI) and `picocolors` (terminal colors). Everything else is Node.js built-ins.
+Minimal production dependencies. Everything else is Node.js built-ins.
 
 ### Architecture
 

package/dist/api.d.ts

@@ -1,3 +1,5 @@
+import { IncomingHttpHeaders } from 'node:http';
+
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | (string & {});
 type FlatHeaders = Record<string, string>;
 interface TracedRequest {
@@ -117,10 +119,6 @@ interface EndpointMetrics {
     sessions: SessionMetric[];
     dataPoints?: LiveRequestPoint[];
 }
-interface MetricsData {
-    version: 1;
-    endpoints: EndpointMetrics[];
-}
 interface LiveRequestPoint {
     timestamp: number;
     durationMs: number;
@@ -149,7 +147,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;
@@ -178,20 +178,81 @@ interface FindingsData {
     findings: StatefulFinding[];
 }
 
+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;
+    type: InsightType;
+    title: string;
+    desc: string;
+    hint: string;
+    detail?: string;
+    nav?: string;
+}
+interface InsightContext {
+    requests: readonly TracedRequest[];
+    queries: readonly TracedQuery[];
+    errors: readonly TracedError[];
+    flows: readonly RequestFlow[];
+    fetches: readonly TracedFetch[];
+    previousMetrics?: readonly EndpointMetrics[];
+    securityFindings?: readonly SecurityFinding[];
+}
+interface EndpointGroup {
+    total: number;
+    errors: number;
+    totalDuration: number;
+    queryCount: number;
+    totalSize: number;
+    totalQueryTimeMs: number;
+    totalFetchTimeMs: number;
+    queryShapeDurations: Map<string, {
+        totalMs: number;
+        count: number;
+        label: string;
+    }>;
+}
+interface PreparedInsightContext extends InsightContext {
+    nonStatic: readonly TracedRequest[];
+    queriesByReq: ReadonlyMap<string, TracedQuery[]>;
+    fetchesByReq: ReadonlyMap<string, TracedFetch[]>;
+    reqById: ReadonlyMap<string, TracedRequest>;
+    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 writer;
     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;
+    /**
+     * Reconcile passive findings against the current analysis results.
+     *
+     * Passive findings are detected by continuous scanning (not user-triggered).
+     * When a previously-seen finding is absent from the current results, it means
+     * the issue has been fixed — transition it to "resolved" automatically.
+     * Active findings (from MCP verify-fix) are not auto-resolved because they
+     * require explicit verification.
+     */
     reconcilePassive(currentFindings: readonly SecurityFinding[]): void;
     getAll(): readonly StatefulFinding[];
     getByState(state: FindingState): readonly StatefulFinding[];
@@ -200,8 +261,7 @@ declare class FindingStore {
     private load;
     private flush;
     private flushSync;
-    private writeAsync;
-    private ensureDir;
+    private serialize;
 }
 
 interface BrakitAdapter {
@@ -231,48 +291,6 @@ declare class SecurityScanner {
 }
 declare function createDefaultScanner(): SecurityScanner;
 
-type InsightSeverity = "critical" | "warning" | "info";
-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;
-    type: InsightType;
-    title: string;
-    desc: string;
-    hint: string;
-    detail?: string;
-    nav?: string;
-}
-interface InsightContext {
-    requests: readonly TracedRequest[];
-    queries: readonly TracedQuery[];
-    errors: readonly TracedError[];
-    flows: readonly RequestFlow[];
-    fetches: readonly TracedFetch[];
-    previousMetrics?: readonly EndpointMetrics[];
-    securityFindings?: readonly SecurityFinding[];
-}
-interface EndpointGroup {
-    total: number;
-    errors: number;
-    totalDuration: number;
-    queryCount: number;
-    totalSize: number;
-    totalQueryTimeMs: number;
-    totalFetchTimeMs: number;
-    queryShapeDurations: Map<string, {
-        totalMs: number;
-        count: number;
-        label: string;
-    }>;
-}
-interface PreparedInsightContext extends InsightContext {
-    nonStatic: readonly TracedRequest[];
-    queriesByReq: ReadonlyMap<string, TracedQuery[]>;
-    fetchesByReq: ReadonlyMap<string, TracedFetch[]>;
-    reqById: ReadonlyMap<string, TracedRequest>;
-    endpointGroups: ReadonlyMap<string, EndpointGroup>;
-}
-
 interface InsightRule {
     id: InsightType;
     check(ctx: PreparedInsightContext): Insight[];
@@ -298,55 +316,120 @@ declare class AdapterRegistry {
     getActive(): readonly BrakitAdapter[];
 }
 
-interface MetricsPersistence {
-    load(): MetricsData;
-    save(data: MetricsData): void;
-    saveSync(data: MetricsData): void;
-    remove(): void;
+interface AnalysisUpdate {
+    insights: Insight[];
+    findings: SecurityFinding[];
+    statefulFindings: readonly StatefulFinding[];
+    statefulInsights: readonly StatefulInsight[];
+}
+interface ChannelMap {
+    "telemetry:fetch": Omit<TracedFetch, "id">;
+    "telemetry:query": Omit<TracedQuery, "id">;
+    "telemetry:log": Omit<TracedLog, "id">;
+    "telemetry:error": Omit<TracedError, "id">;
+    "request:completed": TracedRequest;
+    "analysis:updated": AnalysisUpdate;
+    "store:cleared": void;
+}
+type Listener<T> = (data: T) => void;
+declare class EventBus {
+    private listeners;
+    emit<K extends keyof ChannelMap>(channel: K, data: ChannelMap[K]): void;
+    on<K extends keyof ChannelMap>(channel: K, fn: Listener<ChannelMap[K]>): () => void;
+    off<K extends keyof ChannelMap>(channel: K, fn: Listener<ChannelMap[K]>): void;
 }
 
-declare class MetricsStore {
-    private persistence;
-    private data;
-    private endpointIndex;
-    private sessionId;
-    private sessionStart;
-    private flushTimer;
-    private accumulators;
-    private pendingPoints;
-    constructor(persistence: MetricsPersistence);
-    start(): void;
-    stop(): void;
+interface CaptureInput {
+    requestId: string;
+    method: string;
+    url: string;
+    requestHeaders: IncomingHttpHeaders;
+    requestBody: Buffer | null;
+    statusCode: number;
+    responseHeaders: IncomingHttpHeaders;
+    responseBody: Buffer | null;
+    responseContentType: string;
+    startTime: number;
+    endTime?: number;
+    config: Pick<BrakitConfig, "maxBodyCapture">;
+}
+
+interface TelemetryStoreInterface<T extends TelemetryEntry> {
+    add(data: Omit<T, "id">): T;
+    getAll(): readonly T[];
+    getByRequest(requestId: string): T[];
+    clear(): void;
+}
+interface RequestStoreInterface {
+    capture(input: CaptureInput): TracedRequest;
+    getAll(): readonly TracedRequest[];
+    clear(): void;
+}
+interface MetricsStoreInterface {
     recordRequest(req: TracedRequest, metrics: RequestMetrics): void;
     getAll(): readonly EndpointMetrics[];
     getEndpoint(endpoint: string): EndpointMetrics | undefined;
     getLiveEndpoints(): LiveEndpointData[];
     reset(): void;
-    flush(sync?: boolean): void;
-    private getOrCreateEndpoint;
+    start(): void;
+    stop(): void;
+}
+interface FindingStoreInterface {
+    upsert(finding: SecurityFinding, source: FindingSource): StatefulFinding;
+    transition(findingId: string, state: FindingState): boolean;
+    reconcilePassive(findings: readonly SecurityFinding[]): void;
+    getAll(): readonly StatefulFinding[];
+    getByState(state: FindingState): readonly StatefulFinding[];
+    get(findingId: string): StatefulFinding | undefined;
+    clear(): void;
+    start(): void;
+    stop(): void;
+}
+interface AnalysisEngineInterface {
+    start(): void;
+    stop(): void;
+    recompute(): void;
+    getInsights(): readonly Insight[];
+    getFindings(): readonly SecurityFinding[];
+    getStatefulInsights(): readonly StatefulInsight[];
+    getStatefulFindings(): readonly StatefulFinding[];
+}
+
+interface ServiceMap {
+    "event-bus": EventBus;
+    "request-store": RequestStoreInterface;
+    "query-store": TelemetryStoreInterface<TracedQuery>;
+    "fetch-store": TelemetryStoreInterface<TracedFetch>;
+    "log-store": TelemetryStoreInterface<TracedLog>;
+    "error-store": TelemetryStoreInterface<TracedError>;
+    "metrics-store": MetricsStoreInterface;
+    "finding-store": FindingStoreInterface;
+    "analysis-engine": AnalysisEngineInterface;
+}
+declare class ServiceRegistry {
+    private services;
+    register<K extends keyof ServiceMap>(name: K, service: ServiceMap[K]): void;
+    get<K extends keyof ServiceMap>(name: K): ServiceMap[K];
+    has<K extends keyof ServiceMap>(name: K): boolean;
 }
 
-type AnalysisListener = (insights: Insight[], findings: SecurityFinding[]) => void;
 declare class AnalysisEngine {
-    private metricsStore;
-    private findingStore?;
+    private registry;
     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, findingStore?: FindingStore | undefined, debounceMs?: number);
+    private subs;
+    constructor(registry: ServiceRegistry, 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;
 }