brakit 0.7.4 → 0.7.6

package/README.md

@@ -1,17 +1,38 @@
-# Brakit
-
-**See what your app is actually doing.**
-
-Every request, query, and security issue — before you ship.
-
-Open source · Local only · Zero config · 2 dependencies
-
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg)](https://typescriptlang.org)
+<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 only · Zero config · 2 dependencies</b>
+</p>
+
+<h3 align="center">
+  <a href="docs/design/architecture.md">Architecture</a> &bull;
+  <a href="https://brakit.ai">Website</a> &bull;
+  <a href="CONTRIBUTING.md">Contributing</a>
+</h3>
+
+<h4 align="center">
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" />
+  </a>
+  <a href="https://nodejs.org">
+    <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node >= 18" />
+  </a>
+  <a href="https://typescriptlang.org">
+    <img src="https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg" alt="TypeScript" />
+  </a>
+  <a href="CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen" alt="PRs welcome!" />
+  </a>
+</h4>
 
 ---
 
+<p align="center">
+  <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard" />
+</p>
+
 ## Quick Start
 
 ```bash
@@ -28,18 +49,19 @@ Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
 
 > **Requirements:** Node.js >= 18 and a project with `package.json`.
 
-[Documentation](https://brakit.ai/docs) · [Website](https://brakit.ai)
-
 ---
 
 ## What You Get
 
-- **8 security rules** scanned against live traffic — leaked secrets, PII in responses, missing auth, N+1 queries flagged automatically
+- **Live dashboard** at `/__brakit` — performance overview, request history, scatter charts, real-time via SSE
+- **8 security rules** scanned against live traffic — leaked secrets, PII in responses, missing auth flags
+- **Time breakdown** — every endpoint shows where time goes: DB, Fetch, or App code
+- **N+1 query detection** — same query pattern repeated 5+ times in a single request
+- **Regression detection** — p95 latency or query count increased vs. previous session
 - **Action-level visibility** — see "Sign Up" and "Load Dashboard", not 47 raw HTTP requests
 - **Duplicate detection** — same API called twice? Flagged with redundancy percentage
-- **N+1 query detection** — same query pattern repeated 5+ times in a single request? That's an N+1
 - **Full server tracing** — fetch calls, DB queries, console logs, errors — zero code changes
-- **Live dashboard** at `/__brakit` — 9 tabs updating in real-time
+- **Response overfetch** — large JSON responses with many fields your client doesn't use
 - **Performance tracking** — health grades and p95 trends across dev sessions
 
 ---
@@ -56,16 +78,16 @@ Brakit watches every action your app takes — not raw HTTP noise, but what actu
 
 8 high-confidence rules that scan your live traffic and flag real issues — not theoretical ones:
 
-|              | Rule             | What it catches                                                                 |
-| ------------ | ---------------- | ------------------------------------------------------------------------------- |
-| **Critical** | Exposed Secret   | Response contains `password`, `api_key`, `client_secret` fields with real values |
-| **Critical** | Token in URL     | Auth tokens in query parameters instead of headers                              |
-| **Critical** | Stack Trace Leak | Internal stack traces sent to the client                                        |
-| **Critical** | Error Info Leak  | DB connection strings, SQL queries, or secret values in error responses          |
-| Warning      | PII in Response  | API echoes back emails, returns full user records with internal IDs              |
-| Warning      | Insecure Cookie  | Missing `HttpOnly` or `SameSite` flags                                          |
-| Warning      | Sensitive Logs   | Passwords, secrets, or token values in console output                           |
-| Warning      | CORS + Credentials | `credentials: true` with wildcard origin                                      |
+|              | Rule               | What it catches                                                                  |
+| ------------ | ------------------ | -------------------------------------------------------------------------------- |
+| **Critical** | Exposed Secret     | Response contains `password`, `api_key`, `client_secret` fields with real values |
+| **Critical** | Token in URL       | Auth tokens in query parameters instead of headers                               |
+| **Critical** | Stack Trace Leak   | Internal stack traces sent to the client                                         |
+| **Critical** | Error Info Leak    | DB connection strings, SQL queries, or secret values in error responses          |
+| Warning      | PII in Response    | API echoes back emails, returns full user records with internal IDs              |
+| Warning      | Insecure Cookie    | Missing `HttpOnly` or `SameSite` flags                                           |
+| Warning      | Sensitive Logs     | Passwords, secrets, or token values in console output                            |
+| Warning      | CORS + Credentials | `credentials: true` with wildcard origin                                         |
 
 ---
 
@@ -93,27 +115,27 @@ Instrumentation hooks capture fetch calls, DB queries, console output, and error
 
 Brakit never runs in production. 7 independent layers ensure it:
 
-| # | Layer | How it blocks |
-|---|---|---|
-| 1 | `shouldActivate()` | Checks `NODE_ENV` + 15 cloud/CI env vars |
-| 2 | `instrumentation.ts` guard | Its own `NODE_ENV !== 'production'` check |
-| 3 | devDependency | Pruned in production builds |
-| 4 | `try/catch` on import | Missing module = silent no-op |
-| 5 | Localhost-only dashboard | Non-local IPs get 404 on `/__brakit` |
-| 6 | `safeWrap` + circuit breaker | 10 errors = brakit self-disables |
-| 7 | `BRAKIT_DISABLE=true` | Manual kill switch |
+| #   | Layer                        | How it blocks                             |
+| --- | ---------------------------- | ----------------------------------------- |
+| 1   | `shouldActivate()`           | Checks `NODE_ENV` + 15 cloud/CI env vars  |
+| 2   | `instrumentation.ts` guard   | Its own `NODE_ENV !== 'production'` check |
+| 3   | devDependency                | Pruned in production builds               |
+| 4   | `try/catch` on import        | Missing module = silent no-op             |
+| 5   | Localhost-only dashboard     | Non-local IPs get 404 on `/__brakit`      |
+| 6   | `safeWrap` + circuit breaker | 10 errors = brakit self-disables          |
+| 7   | `BRAKIT_DISABLE=true`        | Manual kill switch                        |
 
 ### Supported Frameworks
 
-| Framework   | Status                     |
-| ----------- | -------------------------- |
-| Next.js     | Full support (auto-detect) |
-| Remix       | Auto-detect                |
-| Nuxt        | Auto-detect                |
-| Vite        | Auto-detect                |
-| Astro       | Auto-detect                |
-| Express     | Auto-detect                |
-| Fastify     | Auto-detect                |
+| Framework | Status                     |
+| --------- | -------------------------- |
+| Next.js   | Full support (auto-detect) |
+| Remix     | Auto-detect                |
+| Nuxt      | Auto-detect                |
+| Vite      | Auto-detect                |
+| Astro     | Auto-detect                |
+| Express   | Auto-detect                |
+| Fastify   | Auto-detect                |
 
 ### Supported Databases
 
@@ -157,34 +179,40 @@ Only 2 production dependencies: `citty` (CLI) and `picocolors` (terminal colors)
 
 ```
 src/
-  runtime/        In-process entry point, server hooks, capture, safety
-  analysis/       Security scanning, N+1 detection, insights engine
+  runtime/        In-process entry point, interceptor, capture, safety
+  analysis/       Insights engine and security scanner
+    insights/     InsightRule implementations (one file per rule)
     rules/        SecurityRule implementations (one file per rule)
   cli/            CLI commands (install, uninstall)
+  constants/      Shared thresholds, route paths, limits
   dashboard/
     api/          REST handlers — requests, flows, telemetry, metrics
     client/       Browser JS generated as template strings
       views/      Tab renderers (overview, flows, graph, etc.)
     styles/       CSS modules
   detect/         Framework auto-detection
-  instrument/     Runtime hooks and database adapters
+  instrument/     Database adapters and instrumentation hooks
     adapters/     BrakitAdapter implementations (one file per library)
     hooks/        Core hooks (fetch, console, errors, context)
+  output/         Terminal insight listener
   store/          In-memory telemetry stores + persistent metrics
   types/          TypeScript definitions by domain
+  utils/          Shared utilities (collections, format, math, endpoint)
 ```
 
 ---
 
 ## Contributing
 
-Brakit is early and moving fast. The most common contributions — adding a new
-database adapter or a new security rule — each require exactly one file and one
-interface. See [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step guides.
+Brakit is early and moving fast. The most common contributions — adding a
+database adapter, a security rule, or an insight rule — each require exactly
+one file and one interface. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+step-by-step guides.
 
 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
 - **Dashboard** — Request diff, timeline view, HAR export
 

package/dist/api.d.ts

@@ -101,6 +101,54 @@ type TelemetryEvent = {
     data: Omit<TracedQuery, "id">;
 };
 
+interface SessionMetric {
+    sessionId: string;
+    startedAt: number;
+    avgDurationMs: number;
+    p95DurationMs: number;
+    requestCount: number;
+    errorCount: number;
+    avgQueryCount: number;
+    avgQueryTimeMs: number;
+    avgFetchTimeMs: number;
+}
+interface EndpointMetrics {
+    endpoint: string;
+    sessions: SessionMetric[];
+    dataPoints?: LiveRequestPoint[];
+}
+interface MetricsData {
+    version: 1;
+    endpoints: EndpointMetrics[];
+}
+interface LiveRequestPoint {
+    timestamp: number;
+    durationMs: number;
+    statusCode: number;
+    queryCount: number;
+    queryTimeMs: number;
+    fetchTimeMs: number;
+}
+interface LiveEndpointSummary {
+    p95Ms: number;
+    errorRate: number;
+    avgQueryCount: number;
+    totalRequests: number;
+    avgQueryTimeMs: number;
+    avgFetchTimeMs: number;
+    avgAppTimeMs: number;
+}
+interface LiveEndpointData {
+    endpoint: string;
+    requests: LiveRequestPoint[];
+    summary: LiveEndpointSummary;
+}
+interface RequestMetrics {
+    queryCount: number;
+    queryTimeMs: number;
+    fetchTimeMs: number;
+}
+
 type SecuritySeverity = "critical" | "warning" | "info";
 interface SecurityFinding {
     severity: SecuritySeverity;
@@ -140,7 +188,7 @@ 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";
+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;
@@ -155,8 +203,44 @@ interface InsightContext {
     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[];
+}
+
+declare class InsightRunner {
+    private rules;
+    register(rule: InsightRule): void;
+    run(ctx: InsightContext): Insight[];
+}
+
+declare function createDefaultInsightRunner(): InsightRunner;
 declare function computeInsights(ctx: InsightContext): Insight[];
 
 declare function detectProject(rootDir: string): Promise<DetectedProject>;
@@ -170,8 +254,37 @@ declare class AdapterRegistry {
     getActive(): readonly BrakitAdapter[];
 }
 
+interface MetricsPersistence {
+    load(): MetricsData;
+    save(data: MetricsData): void;
+    saveSync(data: MetricsData): void;
+    remove(): 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;
+    recordRequest(req: TracedRequest, metrics: RequestMetrics): void;
+    getAll(): readonly EndpointMetrics[];
+    getEndpoint(endpoint: string): EndpointMetrics | undefined;
+    getLiveEndpoints(): LiveEndpointData[];
+    reset(): void;
+    flush(sync?: boolean): void;
+    private getOrCreateEndpoint;
+}
+
 type AnalysisListener = (insights: Insight[], findings: SecurityFinding[]) => void;
 declare class AnalysisEngine {
+    private metricsStore;
     private debounceMs;
     private scanner;
     private cachedInsights;
@@ -182,7 +295,7 @@ declare class AnalysisEngine {
     private boundQueryListener;
     private boundErrorListener;
     private boundLogListener;
-    constructor(debounceMs?: number);
+    constructor(metricsStore: MetricsStore, debounceMs?: number);
     start(): void;
     stop(): void;
     onUpdate(fn: AnalysisListener): void;
@@ -195,4 +308,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 NormalizedOp, type RequestCategory, type RequestListener, type SecurityContext, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type TracedRequest, VERSION, computeInsights, createDefaultScanner, detectProject };
+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 };