brakit 0.8.7 → 0.9.0

package/README.md

@@ -52,19 +52,31 @@
 
 ## Quick Start
 
+### Node.js
+
 ```bash
 npx brakit install
+npm run dev
 ```
 
-That's it. Brakit detects your framework, adds itself as a devDependency, and creates the instrumentation file. Start your app normally:
+### Python (FastAPI / Flask)
 
 ```bash
-npm run dev
+pip install brakit
+```
+
+```python
+import brakit  # must be before framework import
+from fastapi import FastAPI
+
+app = FastAPI()
 ```
 
 Dashboard at `http://localhost:<port>/__brakit`. Issues in the terminal.
 
-> **Requirements:** Node.js >= 18 and a project with `package.json`.
+> **Full setup guide:** [brakit.ai/docs/introduction](https://brakit.ai/docs/introduction)
+
+> **Requirements:** Node.js >= 18. Python SDK requires Python >= 3.9.
 
 ---
 

package/dist/api.d.ts

@@ -16,6 +16,7 @@ interface TracedRequest {
     durationMs: number;
     responseSize: number;
     isStatic: boolean;
+    isHealthCheck: boolean;
 }
 type RequestListener = (req: TracedRequest) => void;
 
@@ -35,7 +36,7 @@ interface BrakitConfig {
     customCommand?: string;
 }
 
-type RequestCategory = "auth-handshake" | "auth-check" | "middleware" | "server-action" | "api-call" | "data-fetch" | "page-load" | "navigation" | "polling" | "static" | "unknown";
+type RequestCategory = "auth-handshake" | "auth-check" | "health-check" | "middleware" | "server-action" | "api-call" | "data-fetch" | "page-load" | "navigation" | "polling" | "static" | "unknown";
 interface LabeledRequest extends TracedRequest {
     label: string;
     category: RequestCategory;
@@ -121,6 +122,10 @@ interface EndpointMetrics {
     sessions: SessionMetric[];
     dataPoints?: LiveRequestPoint[];
 }
+interface MetricsData {
+    version: 1;
+    endpoints: EndpointMetrics[];
+}
 interface LiveRequestPoint {
     timestamp: number;
     durationMs: number;
@@ -131,6 +136,7 @@ interface LiveRequestPoint {
 }
 interface LiveEndpointSummary {
     p95Ms: number;
+    medianMs: number;
     errorRate: number;
     avgQueryCount: number;
     totalRequests: number;
@@ -142,6 +148,8 @@ interface LiveEndpointData {
     endpoint: string;
     requests: LiveRequestPoint[];
     summary: LiveEndpointSummary;
+    sessions?: SessionMetric[];
+    baselineP95Ms: number | null;
 }
 interface RequestMetrics {
     queryCount: number;
@@ -158,6 +166,7 @@ interface SecurityFinding {
     title: string;
     desc: string;
     hint: string;
+    detail?: string;
     endpoint: string;
     count: number;
 }
@@ -382,74 +391,102 @@ interface CaptureInput {
     endTime?: number;
     config: Pick<BrakitConfig, "maxBodyCapture">;
 }
-
-interface Lifecycle {
-    start(): void;
-    stop(): void;
+declare class RequestStore {
+    private maxEntries;
+    private requests;
+    private listeners;
+    constructor(maxEntries?: number);
+    capture(input: CaptureInput): TracedRequest;
+    add(entry: TracedRequest): void;
+    getAll(): readonly TracedRequest[];
+    clear(): void;
+    onRequest(fn: RequestListener): void;
+    offRequest(fn: RequestListener): void;
 }
-interface TelemetryStoreInterface<T extends TelemetryEntry> {
+
+type TelemetryListener<T> = (entry: T) => void;
+/** Read-only view of a TelemetryStore — used by API handlers that only query data. */
+interface ReadonlyTelemetryStore {
+    getAll(): readonly TelemetryEntry[];
+    getByRequest(requestId: string): TelemetryEntry[];
+}
+declare class TelemetryStore<T extends TelemetryEntry> implements ReadonlyTelemetryStore {
+    private maxEntries;
+    private entries;
+    private listeners;
+    constructor(maxEntries?: number);
     add(data: Omit<T, "id">): T;
     getAll(): readonly T[];
     getByRequest(requestId: string): T[];
     clear(): void;
+    onEntry(fn: TelemetryListener<T>): void;
+    offEntry(fn: TelemetryListener<T>): void;
 }
-interface RequestStoreInterface {
-    capture(input: CaptureInput): TracedRequest;
-    add(entry: TracedRequest): void;
-    getAll(): readonly TracedRequest[];
-    clear(): void;
+
+interface MetricsPersistence {
+    load(): MetricsData;
+    loadAsync(): Promise<MetricsData>;
+    save(data: MetricsData): void;
+    saveSync(data: MetricsData): void;
+    remove(): void;
 }
-interface MetricsStoreInterface extends Lifecycle {
+
+declare class MetricsStore {
+    private persistence;
+    private data;
+    private endpointIndex;
+    private sessionId;
+    private sessionStart;
+    private flushTimer;
+    private dirty;
+    private accumulators;
+    private pendingPoints;
+    constructor(persistence: MetricsPersistence);
+    start(): void;
+    stop(): void;
     recordRequest(req: TracedRequest, metrics: RequestMetrics): void;
     getAll(): readonly EndpointMetrics[];
     getEndpoint(endpoint: string): EndpointMetrics | undefined;
+    /**
+     * Compute the adaptive performance baseline for an endpoint.
+     * Returns the median p95 across historical sessions, or null when
+     * there isn't enough data to establish a meaningful baseline.
+     */
+    /**
+     * Cached baselines — invalidated on flush (when sessions change) and
+     * on new request recordings (when pending points grow). Avoids recomputing
+     * on every getLiveEndpoints() API call.
+     */
+    private baselineCache;
+    getEndpointBaseline(endpoint: string): number | null;
+    private computeBaseline;
     getLiveEndpoints(): LiveEndpointData[];
     reset(): void;
-}
-interface IssueStoreInterface extends Lifecycle {
-    upsert(issue: Issue, source: IssueSource): StatefulIssue;
-    transition(issueId: string, state: IssueState): boolean;
-    reportFix(issueId: string, status: AiFixStatus, notes: string): boolean;
-    reconcile(currentIssueIds: Set<string>, activeEndpoints: Set<string>): void;
-    getAll(): readonly StatefulIssue[];
-    getByState(state: IssueState): readonly StatefulIssue[];
-    getByCategory(category: IssueCategory): readonly StatefulIssue[];
-    get(issueId: string): StatefulIssue | undefined;
-    clear(): void;
-}
-interface AnalysisEngineInterface extends Lifecycle {
-    recompute(): void;
-    getInsights(): readonly Insight[];
-    getFindings(): readonly SecurityFinding[];
+    flush(sync?: boolean): void;
+    private getOrCreateEndpoint;
 }
 
-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;
-    "issue-store": IssueStoreInterface;
-    "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;
+interface Services {
+    bus: EventBus;
+    requestStore: RequestStore;
+    queryStore: TelemetryStore<TracedQuery>;
+    fetchStore: TelemetryStore<TracedFetch>;
+    logStore: TelemetryStore<TracedLog>;
+    errorStore: TelemetryStore<TracedError>;
+    metricsStore: MetricsStore;
+    issueStore: IssueStore;
+    analysisEngine: AnalysisEngine;
 }
 
 declare class AnalysisEngine {
-    private registry;
+    private services;
     private debounceMs;
     private scanner;
     private cachedInsights;
     private cachedFindings;
     private debounceTimer;
     private subs;
-    constructor(registry: ServiceRegistry, debounceMs?: number);
+    constructor(services: Services, debounceMs?: number);
     start(): void;
     stop(): void;
     getInsights(): readonly Insight[];