@mandujs/core 0.53.2 → 0.54.0

package/src/kitchen/api/errors-grouping.ts

@@ -0,0 +1,126 @@
+/**
+ * Plan 18 P1-4 — Error grouping for the Kitchen Errors panel.
+ *
+ * The Kitchen error ring buffer (`kitchen-handler.ts:storedErrors`) is a
+ * flat list. When the same hydration failure or unhandled rejection
+ * fires repeatedly on every render, the buffer fills with near-identical
+ * rows and the operator has to scroll through them to spot the count.
+ *
+ * `groupErrors()` collapses runs of "the same error" into one row with
+ * count / first-seen / last-seen / affected-sources / a representative
+ * sample. The group key is intentionally conservative so that
+ * superficially different errors stay separate:
+ *
+ *   key = sha1(`${type}|${source}|${normalize(message)}`)
+ *
+ * `normalize` collapses obvious noise (numbers, UUIDs, file:line refs)
+ * but leaves stack-shape and message word order intact. This is a
+ * smaller hammer than full stack-trace fingerprinting — that lives
+ * elsewhere if we ever need it.
+ */
+
+import crypto from "node:crypto";
+
+export interface KitchenErrorLike {
+  id?: string;
+  type?: string;
+  severity?: string;
+  message: string;
+  stack?: string;
+  url?: string;
+  source?: string;
+  line?: number;
+  column?: number;
+  timestamp?: number;
+}
+
+export interface GroupedError {
+  /** Stable hash of (type, source, normalized message). */
+  key: string;
+  /** How many raw errors collapsed into this group. */
+  count: number;
+  /** Representative event — the most recent occurrence. */
+  sample: KitchenErrorLike;
+  /** Severity of the sample. Same across the group in practice. */
+  severity: string | undefined;
+  /** Earliest timestamp seen for this signature. */
+  firstSeen: number;
+  /** Latest timestamp seen for this signature. */
+  lastSeen: number;
+  /** Distinct source / file refs across the group, capped for transport. */
+  affectedSources: string[];
+}
+
+const NUM_RE = /\d{1,}/g;
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+const HEX_RE = /\b0x[0-9a-f]+\b/gi;
+
+/**
+ * Replace noise that varies run-to-run but doesn't change which bug is
+ * being reported. Kept intentionally narrow so user-visible message
+ * structure stays recognizable for the operator.
+ */
+export function normalizeMessage(message: string): string {
+  return message
+    .replace(UUID_RE, "<UUID>")
+    .replace(HEX_RE, "<HEX>")
+    .replace(NUM_RE, "<N>")
+    .trim()
+    .toLowerCase();
+}
+
+export function errorKey(err: KitchenErrorLike): string {
+  const parts = [
+    err.type ?? "runtime",
+    err.source ?? "unknown",
+    normalizeMessage(err.message ?? ""),
+  ].join("|");
+  return crypto.createHash("sha1").update(parts).digest("hex").slice(0, 16);
+}
+
+export interface GroupOptions {
+  /** Cap `affectedSources` length in the response. Default 5. */
+  maxSourcesPerGroup?: number;
+}
+
+/**
+ * Collapse a flat error list into `GroupedError[]`, newest-group first.
+ * Stable: a single error becomes a group of size 1.
+ */
+export function groupErrors(errors: readonly KitchenErrorLike[], options: GroupOptions = {}): GroupedError[] {
+  const maxSources = options.maxSourcesPerGroup ?? 5;
+  const byKey = new Map<string, GroupedError>();
+
+  for (const err of errors) {
+    const key = errorKey(err);
+    const ts = err.timestamp ?? 0;
+    const existing = byKey.get(key);
+    if (!existing) {
+      const sources = err.source ? [err.source] : [];
+      byKey.set(key, {
+        key,
+        count: 1,
+        sample: err,
+        severity: err.severity,
+        firstSeen: ts,
+        lastSeen: ts,
+        affectedSources: sources,
+      });
+      continue;
+    }
+    existing.count += 1;
+    if (ts < existing.firstSeen || existing.firstSeen === 0) existing.firstSeen = ts;
+    if (ts > existing.lastSeen) {
+      existing.lastSeen = ts;
+      existing.sample = err; // newest wins so the operator sees the freshest message
+    }
+    if (err.source && !existing.affectedSources.includes(err.source)) {
+      if (existing.affectedSources.length < maxSources) {
+        existing.affectedSources.push(err.source);
+      }
+    }
+  }
+
+  // Newest groups first — the operator wants the most recent regression up top.
+  return Array.from(byKey.values()).sort((a, b) => b.lastSeen - a.lastSeen);
+}

package/src/kitchen/kitchen-handler.ts

@@ -11,26 +11,30 @@ import { getGlobalCache, getCacheStoreStats } from "../runtime/cache";
 import { ActivitySSEBroadcaster } from "./stream/activity-sse";
 import { GuardAPI } from "./api/guard-api";
 import { handleRoutesRequest } from "./api/routes-api";
-import { FileAPI } from "./api/file-api";
-import { GuardDecisionManager } from "./api/guard-decisions";
-import { ContractPlaygroundAPI } from "./api/contract-api";
-import { handleAgentContextRequest } from "./api/agent-devtools-api";
-import { renderKitchenHTML } from "./kitchen-ui";
-import { eventBus } from "../observability/event-bus";
-import fs from "fs/promises";
-import path from "path";
-
-export const KITCHEN_PREFIX = "/__kitchen";
-
-function reverseCopy<T>(items: readonly T[]): T[] {
-  const reversed: T[] = [];
-  for (let index = items.length - 1; index >= 0; index -= 1) {
-    reversed.push(items[index] as T);
-  }
-  return reversed;
-}
-
-export interface KitchenOptions {
+import { FileAPI } from "./api/file-api";
+import { GuardDecisionManager } from "./api/guard-decisions";
+import { ContractPlaygroundAPI } from "./api/contract-api";
+import { handleAgentContextRequest } from "./api/agent-devtools-api";
+import { groupErrors } from "./api/errors-grouping";
+import type { BundleManifest } from "../bundler/types";
+import type { DiagnoseReport } from "../diagnose/types";
+import { runExtendedDiagnose } from "../diagnose/run";
+import { renderKitchenHTML } from "./kitchen-ui";
+import { eventBus } from "../observability/event-bus";
+import fs from "fs/promises";
+import path from "path";
+
+export const KITCHEN_PREFIX = "/__kitchen";
+
+function reverseCopy<T>(items: readonly T[]): T[] {
+  const reversed: T[] = [];
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    reversed.push(items[index] as T);
+  }
+  return reversed;
+}
+
+export interface KitchenOptions {
   rootDir: string;
   manifest: RoutesManifest;
   guardConfig: GuardConfig | null;
@@ -83,9 +87,9 @@ export function recordRequest(entry: RequestEntry): void {
   if (recentRequests.length > MAX_REQUESTS) recentRequests.shift();
 }
 
-export function getRecentRequests(): RequestEntry[] {
-  return reverseCopy(recentRequests);
-}
+export function getRecentRequests(): RequestEntry[] {
+  return reverseCopy(recentRequests);
+}
 
 /** Parse a window string like "5m", "30s", "1h" into milliseconds. */
 function parseWindow(input: string): number {
@@ -102,6 +106,64 @@ function parseWindow(input: string): number {
   }
 }
 
+// ========== Agent Context Pack — signal collectors (plan 18 P0-2) ==========
+
+/**
+ * Read the bundle manifest from `.mandu/manifest.json`. Returns `null`
+ * when the file is missing or malformed — the builder treats `null` as
+ * "not collected" rather than "empty", so missing-vs-empty stays
+ * distinguishable for the build-broken classifier.
+ */
+async function readBundleManifest(rootDir: string): Promise<BundleManifest | null> {
+  const manifestPath = path.join(rootDir, ".mandu", "manifest.json");
+  try {
+    const raw = await fs.readFile(manifestPath, "utf-8");
+    return JSON.parse(raw) as BundleManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the extended diagnose suite. Returns `null` on failure so the
+ * supervisor degrades gracefully — no diagnose summary, but the rest
+ * of the context pack still works.
+ */
+async function runDiagnoseSignal(rootDir: string): Promise<DiagnoseReport | null> {
+  try {
+    return await runExtendedDiagnose(rootDir);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect changed file paths via `git diff --name-only <base>`. Base
+ * defaults to `HEAD` (uncommitted changes only), overridable with the
+ * `MANDU_DIFF_BASE` environment variable. Returns `undefined` (not
+ * `[]`) when git is unavailable so the builder can omit the summary
+ * block entirely.
+ */
+async function collectChangedFiles(rootDir: string): Promise<string[] | undefined> {
+  const base = process.env.MANDU_DIFF_BASE ?? "HEAD";
+  try {
+    const proc = Bun.spawnSync({
+      cmd: ["git", "diff", "--name-only", base],
+      cwd: rootDir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (proc.exitCode !== 0) return undefined;
+    const text = new TextDecoder().decode(proc.stdout);
+    return text
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  } catch {
+    return undefined;
+  }
+}
+
 // ========== Per-Agent Stats ==========
 
 export interface AgentStats {
@@ -229,11 +291,11 @@ export class KitchenHandler {
     this.contractAPI.updateManifest(manifest);
   }
 
-  /** Update guard config when mandu.config.ts changes */
-  updateGuardConfig(config: GuardConfig | null): void {
-    this.options.guardConfig = config;
-    this.guardAPI.updateConfig(config);
-  }
+  /** Update guard config when mandu.config.ts changes */
+  updateGuardConfig(config: GuardConfig | null): void {
+    this.options.guardConfig = config;
+    this.guardAPI.updateConfig(config);
+  }
 
   /** Get the SSE broadcaster for external event injection */
   get broadcaster(): ActivitySSEBroadcaster {
@@ -332,11 +394,11 @@ export class KitchenHandler {
     // Requests API — recent HTTP events from eventBus (fallback: ring buffer)
     if (sub === "/api/requests" && req.method === "GET") {
       const url = new URL(req.url);
-      const limit = Math.min(parseInt(url.searchParams.get("limit") || "100", 10) || 100, 500);
-      const busEvents = eventBus.getRecent(limit, { type: "http" });
-      if (busEvents.length > 0) {
-        return Response.json({ requests: reverseCopy(busEvents) });
-      }
+      const limit = Math.min(parseInt(url.searchParams.get("limit") || "100", 10) || 100, 500);
+      const busEvents = eventBus.getRecent(limit, { type: "http" });
+      if (busEvents.length > 0) {
+        return Response.json({ requests: reverseCopy(busEvents) });
+      }
       return Response.json({ requests: getRecentRequests().slice(0, limit) });
     }
 
@@ -353,36 +415,90 @@ export class KitchenHandler {
     // Activity API — recent MCP events from eventBus (fallback: activity.jsonl)
     if (sub === "/api/activity" && req.method === "GET") {
       const url = new URL(req.url);
-      const limit = Math.min(parseInt(url.searchParams.get("limit") || "100", 10) || 100, 500);
-      const busEvents = eventBus.getRecent(limit, { type: "mcp" });
-      if (busEvents.length > 0) {
-        return Response.json({ events: reverseCopy(busEvents) });
-      }
+      const limit = Math.min(parseInt(url.searchParams.get("limit") || "100", 10) || 100, 500);
+      const busEvents = eventBus.getRecent(limit, { type: "mcp" });
+      if (busEvents.length > 0) {
+        return Response.json({ events: reverseCopy(busEvents) });
+      }
       const events = await this.readRecentActivity();
       return Response.json({ events });
     }
 
     // Agent Stats API — per-agent (sessionId) aggregation of MCP events
-    if (sub === "/api/agent-stats" && req.method === "GET") {
-      return Response.json(computeAgentStats());
-    }
-
-    // Agent DevTools API — read-only context pack for supervised coding sessions
-    if (sub === "/api/agent-context" && req.method === "GET") {
-      return handleAgentContextRequest({
-        rootDir: this.options.rootDir,
-        manifest: this.manifest,
-        guardEnabled: !!this.options.guardConfig,
-        errors: getKitchenErrors(),
-        requests: getRecentRequests().slice(0, 100),
-        httpEvents: eventBus.getRecent(100, { type: "http" }),
-        mcpEvents: eventBus.getRecent(100, { type: "mcp" }),
-        guardEvents: eventBus.getRecent(100, { type: "guard" }),
-        agentStats: computeAgentStats(),
-      });
-    }
-
-    // Cache API — cache store stats
+    if (sub === "/api/agent-stats" && req.method === "GET") {
+      return Response.json(computeAgentStats());
+    }
+
+    // Generic events API (plan 18 P1-3).
+    // Exposes the full eventBus surface — `build` / `cache` / `ws` / `ate`
+    // / `error` categories live on the bus but were previously invisible
+    // because /api/activity and /api/requests filter to mcp/http only.
+    // Query params:
+    //   ?type=build|cache|ws|ate|http|mcp|guard|error  (optional — omit for all)
+    //   ?severity=info|warn|error                       (optional)
+    //   ?limit=N                                        (default 100, max 500)
+    //   ?stats=1                                        (return per-type counts instead of events)
+    if (sub === "/api/events" && req.method === "GET") {
+      const url = new URL(req.url);
+      const limit = Math.min(parseInt(url.searchParams.get("limit") || "100", 10) || 100, 500);
+
+      if (url.searchParams.get("stats") === "1") {
+        return Response.json({ stats: eventBus.getStats() });
+      }
+
+      const typeParam = url.searchParams.get("type");
+      const sevParam = url.searchParams.get("severity");
+      const allowedTypes = new Set(["http", "mcp", "guard", "build", "error", "cache", "ws", "ate"]);
+      const allowedSev = new Set(["info", "warn", "error"]);
+      const filter: { type?: "http" | "mcp" | "guard" | "build" | "error" | "cache" | "ws" | "ate"; severity?: "info" | "warn" | "error" } = {};
+      if (typeParam && allowedTypes.has(typeParam)) filter.type = typeParam as typeof filter.type;
+      if (sevParam && allowedSev.has(sevParam)) filter.severity = sevParam as typeof filter.severity;
+
+      const events = eventBus.getRecent(limit, filter);
+      return Response.json({ events: reverseCopy(events) });
+    }
+
+    // Agent DevTools API — read-only context pack for supervised coding sessions.
+    //
+    // Plan 18 P0-2 — collect three additional signals (bundle manifest,
+    // diagnose report, changed files) so the supervisor can distinguish
+    // build-broken / boot-breaking categories from runtime errors.
+    // Each collector is fail-safe: failure to read disk or run a
+    // sub-process yields `null` / `[]` rather than throwing. Query
+    // params allow callers to skip expensive signals:
+    //   ?bundle=0    → skip reading .mandu/manifest.json
+    //   ?diagnose=0  → skip runExtendedDiagnose (a11y_hints is the
+    //                  most expensive check; opt out when latency matters)
+    //   ?diff=0      → skip `git diff --name-only`
+    if (sub === "/api/agent-context" && req.method === "GET") {
+      const urlObj = new URL(req.url);
+      const wantBundle = urlObj.searchParams.get("bundle") !== "0";
+      const wantDiagnose = urlObj.searchParams.get("diagnose") !== "0";
+      const wantDiff = urlObj.searchParams.get("diff") !== "0";
+
+      const [bundleManifest, diagnoseReport, changedFiles] = await Promise.all([
+        wantBundle ? readBundleManifest(this.options.rootDir) : Promise.resolve(null),
+        wantDiagnose ? runDiagnoseSignal(this.options.rootDir) : Promise.resolve(null),
+        wantDiff ? collectChangedFiles(this.options.rootDir) : Promise.resolve(undefined),
+      ]);
+
+      return handleAgentContextRequest({
+        rootDir: this.options.rootDir,
+        manifest: this.manifest,
+        guardEnabled: !!this.options.guardConfig,
+        errors: getKitchenErrors(),
+        requests: getRecentRequests().slice(0, 100),
+        httpEvents: eventBus.getRecent(100, { type: "http" }),
+        mcpEvents: eventBus.getRecent(100, { type: "mcp" }),
+        guardEvents: eventBus.getRecent(100, { type: "guard" }),
+        agentStats: computeAgentStats(),
+        bundleManifest,
+        diagnoseReport,
+        changedFiles,
+      });
+    }
+
+    // Cache API — cache store stats
     if ((sub === "/api/cache" || sub === "/api/cache-stats") && req.method === "GET") {
       const store = getGlobalCache();
       return Response.json({
@@ -459,6 +575,19 @@ export class KitchenHandler {
       return Response.json({ errors: storedErrors, count: storedErrors.length });
     }
 
+    // Plan 18 P1-4 — Errors panel grouped view. Collapses identical
+    // signatures into one row with count/firstSeen/lastSeen/affected
+    // sources. The operator no longer scrolls past five copies of the
+    // same hydration error to find the new one underneath.
+    if (sub === "/api/errors/grouped" && req.method === "GET") {
+      const groups = groupErrors(storedErrors);
+      return Response.json({
+        groups,
+        groupCount: groups.length,
+        totalCount: storedErrors.length,
+      });
+    }
+
     if (sub === "/api/errors" && req.method === "DELETE") {
       const count = storedErrors.length;
       clearKitchenErrors();
@@ -513,11 +642,11 @@ export class KitchenHandler {
   private async readRecentActivity(): Promise<unknown[]> {
     const logPath = path.join(this.options.rootDir, ".mandu", "activity.jsonl");
     try {
-      const content = await fs.readFile(logPath, "utf-8");
-      const lines = content.trim().split("\n").filter(Boolean);
-      return reverseCopy(lines.slice(-50)).map((line) => {
-        try { return JSON.parse(line); } catch { return null; }
-      }).filter(Boolean);
+      const content = await fs.readFile(logPath, "utf-8");
+      const lines = content.trim().split("\n").filter(Boolean);
+      return reverseCopy(lines.slice(-50)).map((line) => {
+        try { return JSON.parse(line); } catch { return null; }
+      }).filter(Boolean);
     } catch { return []; }
   }
 }