brakit 0.8.1 → 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">
@@ -74,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
 
 ---
 
@@ -188,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;
@@ -239,15 +237,22 @@ declare class FindingStore {
     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[];
@@ -256,8 +261,7 @@ declare class FindingStore {
     private load;
     private flush;
     private flushSync;
-    private writeAsync;
-    private ensureDir;
+    private serialize;
 }
 
 interface BrakitAdapter {
@@ -312,44 +316,105 @@ 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 AnalysisUpdate {
-    insights: Insight[];
-    findings: SecurityFinding[];
-    statefulFindings: readonly StatefulFinding[];
-    statefulInsights: readonly StatefulInsight[];
+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 = (update: AnalysisUpdate) => void;
+
 declare class AnalysisEngine {
-    private metricsStore;
-    private findingStore?;
+    private registry;
     private debounceMs;
     private scanner;
     private insightTracker;
@@ -357,16 +422,10 @@ declare class AnalysisEngine {
     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[];