@zerotal/devtools 1.6.3 → 1.7.2

package/src/DevtoolsInjectionMiddleware.ts

@@ -1,8 +1,11 @@
 import { fileURLToPath } from "node:url";
 import type { NextFn, HttpContext } from "@zerotal/core";
-import { BaseMiddleware } from "@zerotal/core";
+import { BaseMiddleware, tryCurrentApp } from "@zerotal/core";
 import { traceStore } from "./TraceStore.ts";
 import { traceChannels } from "./tracing.ts";
+import { devtoolsAuthorized, devtoolsSettings } from "./enabled.ts";
+import { buildFrameworkMap } from "./map.ts";
+import { activityFeed } from "./activity.ts";
 
 // ── Injected browser client bundle ────────────────────────────────────────────
 // The in-page devtools panel is bundled for the browser on first request and
@@ -44,6 +47,9 @@ export interface DevtoolsInjectionOptions {
   // reserved for future use
 }
 
+/** Everything the inspector serves lives under here, and is gated as one thing. */
+const DEVTOOLS_PREFIX = "/__zerotal/devtools";
+
 // ── SSE subscribers ───────────────────────────────────────────────────────────
 
 const _sseClients = new Set<ReadableStreamDefaultController<Uint8Array>>();
@@ -130,10 +136,34 @@ export class DevtoolsInjectionMiddleware extends BaseMiddleware<DevtoolsInjectio
   async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
     const { pathname } = http.url;
 
+    // Everything under the prefix is one secret. The stream, the trace JSON, the
+    // dashboard, and the panel bundle all expose the same request data, so they
+    // are gated together and before anything is read — checking per endpoint is
+    // how one of them ends up ungated.
+    if (pathname.startsWith(DEVTOOLS_PREFIX)) {
+      if (!(await devtoolsAuthorized(http.request))) {
+        // 404, not 403: outside development the honest answer to an
+        // unauthenticated stranger is that there is nothing here.
+        return new Response("Not Found", { status: 404 });
+      }
+    }
+
     if (pathname === "/__zerotal/devtools/api/traces") {
       return Response.json(traceStore().all());
     }
 
+    // The framework map: read fresh, never cached. The registries are small and
+    // static, and a cached map is one that disagrees with the app the moment a
+    // provider registers a route late.
+    if (pathname === "/__zerotal/devtools/api/map") {
+      const app = tryCurrentApp();
+      if (!app) return Response.json({ error: "No application in scope" }, { status: 503 });
+      return Response.json({
+        ...buildFrameworkMap(app, devtoolsSettings().redact),
+        activity: activityFeed(),
+      });
+    }
+
     if (pathname === "/__zerotal/devtools/api/channels") {
       return Response.json(traceChannels());
     }
@@ -149,15 +179,22 @@ export class DevtoolsInjectionMiddleware extends BaseMiddleware<DevtoolsInjectio
         start(c) {
           ctrl = c;
           _sseClients.add(ctrl);
-          // The opening frame carries the channel descriptors alongside the
-          // history, so a panel can render a package's tab on first paint
-          // instead of waiting for that package's next entry.
+          // The opening frame carries everything the panel needs at first paint
+          // rather than making it ask three more times: the channel descriptors,
+          // so a package's tab is there before that package's next entry; the
+          // store's capacity, so the list trims to the depth the app asked for;
+          // and the editor settings, so a `file:line` is a link on the first
+          // trace rather than the second.
+          const settings = devtoolsSettings();
           ctrl.enqueue(
             _enc.encode(
               `data: ${JSON.stringify({
                 type: "history",
                 data: traceStore().all(),
                 channels: traceChannels(),
+                capacity: traceStore().capacity,
+                editor: settings.editor,
+                editorPathMap: settings.editorPathMap,
               })}\n\n`,
             ),
           );

package/src/RequestTrace.ts

@@ -1,9 +1,19 @@
+import type { SourceLocation } from "./editor.ts";
+
 export interface QuerySpan {
   sql: string;
   bindings: unknown[];
   startMs: number;
   durationMs: number;
   rowCount: number;
+  /**
+   * The application line that ran this query, when one could be found.
+   *
+   * Absent for a query with no application frame above it — a seeder, a
+   * framework-internal read — which is a truthful answer and better than
+   * pointing at a file nobody wrote.
+   */
+  source?: SourceLocation;
 }
 
 export interface NPlusOneWarning {
@@ -27,6 +37,32 @@ export interface LogEntry {
   level: "log" | "debug" | "info" | "warn" | "error";
   args: string[];
   offsetMs: number;
+  /** The application line that logged this, when one could be found. */
+  source?: SourceLocation;
+}
+
+/**
+ * The error that propagated out of the request pipeline, when one did.
+ *
+ * A failed request finalises like any other, so its status code was always on
+ * the trace — but the message that caused it was not, and a red `500` with no
+ * text next to it is the one thing a request inspector must not do.
+ */
+export interface ExceptionInfo {
+  /** The error's message as it left the pipeline. */
+  message: string;
+  /** The status the rendered error response used. */
+  status: number;
+  /** The error's class name, when the failure was an `Error`. */
+  type?: string;
+  /**
+   * The stack, innermost first, with framework frames kept.
+   *
+   * Unlike a query's call site this is deliberately *not* filtered to
+   * application code: you read a stack trace to find out how you got somewhere,
+   * and a trace with the middle removed does not tell you that.
+   */
+  frames?: SourceLocation[];
 }
 
 export interface MailEntry {
@@ -105,6 +141,63 @@ export interface TraceChannelDescriptor {
   warn?: string;
   /** Sort order among channel tabs. Lower sorts first. Defaults to 100. */
   order?: number;
+  /**
+   * Record the entries on the trace but give them no tab of their own.
+   *
+   * For a package that renders this data somewhere better than a generic row
+   * list — its own plugin panel, say — while still wanting it on the persisted
+   * trace. Flow declares its actions this way: the numbers belong on the trace,
+   * but they read as one line on a time-travel frame rather than as a tab
+   * repeating what the trace header already says.
+   */
+  hidden?: boolean;
+
+  // ── Presentation hints ──────────────────────────────────────────────────────
+  //
+  // A flat list of badge-title-meta rows is the right shape for an audit feed and
+  // the wrong one for a prop map or a route table. These pick a different
+  // presentation without breaking the property that makes channels worth having:
+  // everything here is still *data*, so devtools ships no code per package.
+
+  /**
+   * How rows are presented. Defaults to `"rows"` — badge, title, and a meta line.
+   *
+   * - `"rows"` — one block per entry.
+   * - `"tree"` — {@link treeField} holds a map of dotted paths; shared prefixes
+   *   become branches.
+   * - `"table"` — one row per entry, {@link meta} as columns. For many entries
+   *   with the same shape.
+   * - `"kv"` — every field of every entry as a key/value table. For a handful of
+   *   entries with many fields.
+   * - `"grouped"` — entries collected under the value of {@link groupBy}.
+   */
+  render?: "rows" | "tree" | "table" | "kv" | "grouped";
+  /**
+   * For `"tree"`: the entry field holding the tree, as a map of dotted path →
+   * a record of that node's attributes. Dotted keys become branches.
+   */
+  treeField?: string;
+  /** For `"tree"`: the node field rendered as each leaf's leading badge. */
+  treeBadge?: string;
+  /** For `"grouped"`: the entry field rows are grouped by. */
+  groupBy?: string;
+  /**
+   * Fields rendered as a bare chip when truthy — `shared`, `deferred`, `failed`.
+   * Applies to a row's own fields and, under `"tree"`, to each node's.
+   *
+   * A flag is named by its *field*, so a `true` reads as the word rather than as
+   * `deepMerge: true`, which is how a row ends up saying nothing at a glance.
+   */
+  flags?: string[];
+  /**
+   * The entry field whose value groups whole *traces* together on the All tab.
+   *
+   * One request can cause several — a visit and the deferred-prop loads it
+   * triggers — and listing them as unrelated siblings is how the thing you are
+   * debugging scrolls away. Traces sharing a value here collapse into one
+   * expandable entry. Read from the channel's first entry on each trace.
+   */
+  traceGroup?: string;
 }
 
 export interface RequestTrace {
@@ -121,14 +214,26 @@ export interface RequestTrace {
   memory: number;
   /** URL query string parameters */
   queryParams: Record<string, string>;
-  /** Filtered request headers (no auth/cookie values) */
+  /** Filtered request headers (never auth/cookie values) */
   headers: Record<string, string>;
+  /** Filtered response headers — the other half of the exchange */
+  responseHeaders: Record<string, string>;
+  /**
+   * Session key names, never values.
+   *
+   * "Is the CSRF token there, did the flash survive the redirect, is the user id
+   * set" are all answered by the keys — and the values are the request's real
+   * state, on a trace that is written to disk for a day.
+   */
+  session: string[];
   /** Matched route pattern, controller, and action */
   route: RouteInfo | null;
   /** Authenticated user at the end of the request, or null for guests */
   auth: AuthInfo | null;
   /** Console log/debug/info/warn/error messages emitted during the request */
   logs: LogEntry[];
+  /** The error that ended the request, or null when it completed normally */
+  exception: ExceptionInfo | null;
   /** Emails sent (or queued) during this request */
   mail: MailEntry[];
   /** Cache operations performed during this request */

package/src/TraceStore.ts

@@ -138,6 +138,18 @@ export class TraceStore {
     return this._db !== null;
   }
 
+  /**
+   * How many traces this store keeps.
+   *
+   * Read by the SSE stream so the panel can trim its own list to the same depth.
+   * The client used to cap at a hardcoded 100, so an app that configured a larger
+   * capacity got the full history in the opening frame and then silently lost
+   * everything past 100 as soon as the next request arrived.
+   */
+  get capacity(): number {
+    return this._capacity;
+  }
+
   // ── Persistence ───────────────────────────────────────────────────────
 
   /** Open the database and load history, once, on first use. */

package/src/activity.ts

@@ -0,0 +1,116 @@
+/**
+ * What the application did when nobody was making a request.
+ *
+ * A scheduled task that fails at 03:00 leaves no trace in the tool whose job is
+ * to show you what your app did — because every surface in the panel until now
+ * hangs off an `HttpContext`, and a console command and a cron tick have none.
+ * `CommandRan`, `TaskRan`, `TaskFailed` and `TaskSkipped` were all on the bus and
+ * all went nowhere.
+ *
+ * A small ring of its own rather than a channel, for the reason channels exist:
+ * a channel entry belongs to a request. These belong to the process.
+ */
+import { FrameworkEvents } from "@zerotal/core";
+import type { CommandRan } from "@zerotal/core";
+
+/** One thing the app did outside a request. */
+export interface ActivityEntry {
+  kind: "command" | "task";
+  name: string;
+  /** `ok`, `failed`, or why a task was skipped. */
+  outcome: string;
+  durationMs: number;
+  /** Unix milliseconds, so the panel can show when rather than only what. */
+  at: number;
+  failed: boolean;
+  detail?: string;
+}
+
+/**
+ * How many entries to keep.
+ *
+ * A long-lived dev server running a per-minute schedule produces 1,440 of these
+ * a day; the useful window is the last few dozen. Unbounded here would be a
+ * memory leak with a friendly name.
+ */
+const MAX_ENTRIES = 200;
+
+let _entries: ActivityEntry[] = [];
+
+/** Newest first, as the panel draws them. */
+export function activityFeed(): ActivityEntry[] {
+  return [..._entries].reverse();
+}
+
+/** @internal — drop everything (provider teardown, tests). */
+export function _resetActivity(): void {
+  _entries = [];
+}
+
+function push(entry: ActivityEntry): void {
+  _entries.push(entry);
+  if (_entries.length > MAX_ENTRIES) _entries.shift();
+}
+
+/**
+ * Subscribe to the non-HTTP lifecycle events.
+ *
+ * The scheduler's events are subscribed **by kind string** rather than by class:
+ * `@zerotal/scheduler` is an optional package, and importing its event classes
+ * to name them would make devtools depend on it. The bus supports either door
+ * and a string subscription costs nothing when nothing ever emits.
+ *
+ * @returns A disposer that removes every subscription.
+ */
+export function startActivityCapture(): () => void {
+  const unsubs = [
+    FrameworkEvents.on<CommandRan>("CommandRan", (e) => {
+      push({
+        kind: "command",
+        name: e.name,
+        outcome: e.ok ? "ok" : `exit ${e.exitCode}`,
+        durationMs: e.durationMs,
+        at: Date.now(),
+        failed: !e.ok,
+        ...(e.error ? { detail: e.error } : {}),
+      });
+    }),
+    FrameworkEvents.on<{ name: string; durationMs: number; ok: boolean }>("TaskRan", (e) => {
+      push({
+        kind: "task",
+        name: e.name,
+        outcome: e.ok ? "ok" : "failed",
+        durationMs: e.durationMs,
+        at: Date.now(),
+        failed: !e.ok,
+      });
+    }),
+    FrameworkEvents.on<{ name: string; durationMs: number; error: string }>("TaskFailed", (e) => {
+      push({
+        kind: "task",
+        name: e.name,
+        outcome: "failed",
+        durationMs: e.durationMs,
+        at: Date.now(),
+        failed: true,
+        detail: e.error,
+      });
+    }),
+    FrameworkEvents.on<{ name: string; reason: string }>("TaskSkipped", (e) => {
+      push({
+        kind: "task",
+        name: e.name,
+        // Why it skipped is the whole content of the event: "skipped" alone
+        // sends you looking for a bug in a task that was told not to run.
+        outcome: `skipped · ${e.reason}`,
+        durationMs: 0,
+        at: Date.now(),
+        failed: false,
+      });
+    }),
+  ];
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/callsite.ts

@@ -0,0 +1,146 @@
+/**
+ * Where in *your* code this happened.
+ *
+ * A `QuerySpan` was `{ sql, bindings, startMs, durationMs, rowCount }` and a
+ * `LogEntry` was `{ level, args, offsetMs }`. Neither knew which line produced
+ * it, so "which of my forty queries is the slow one" was answerable and "where do
+ * I go to fix it" was not.
+ *
+ * The whole trick is throwing away frames. A stack captured where devtools
+ * buffers an event begins inside devtools, passes through the emitting package,
+ * and only then reaches the application — so the first frame that is *not*
+ * framework code is the answer, and every frame above it is noise.
+ *
+ * **Cost.** Measured under Bun at roughly two microseconds per capture, flat
+ * across stack depths from 5 to 80 — the engine builds the trace lazily, so
+ * depth barely registers. A request running forty queries pays about 0.08ms.
+ * That is why {@link DevtoolsConfigShape.captureSource} defaults to on: it was
+ * expected to be the expensive part of this and it is not.
+ */
+import type { SourceLocation } from "./editor.ts";
+
+/**
+ * Path fragments that mean "not the application".
+ *
+ * Matched against the normalised path, so the separator is always `/`. The
+ * framework's own packages are here twice over — as a workspace checkout
+ * (`packages/orm/src`) and as an installed dependency (`node_modules`) — because
+ * a contributor debugging the framework and an app developer using it see
+ * different paths for the same file.
+ */
+const FRAMEWORK_FRAGMENTS = [
+  "node_modules/",
+  "/packages/core/",
+  "/packages/orm/",
+  "/packages/devtools/",
+  "/packages/cache/",
+  "/packages/queue/",
+  "/packages/auth/",
+  "/packages/session/",
+  "/packages/notifications/",
+  "/packages/inertia/",
+  "/packages/flow/",
+  "bun:",
+  "node:",
+];
+
+/** Frames the runtime adds that name no file at all. */
+const NATIVE = ["[native code]", "<anonymous>", "unknown"];
+
+/**
+ * One line of a stack, as the runtimes spell it.
+ *
+ * Two shapes: `at fn (file:line:col)` and a bare `at file:line:col`. The `async`
+ * prefix rides along on continuation frames and is stripped from the name rather
+ * than being allowed to become part of it.
+ */
+const FRAME = /^\s*at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?\s*$/;
+
+/** How far down a stack to look before giving up. */
+const MAX_FRAMES = 40;
+
+function isFrameworkFrame(file: string): boolean {
+  const normalised = file.replace(/\\/g, "/");
+  if (NATIVE.some((n) => normalised.includes(n))) return true;
+  return FRAMEWORK_FRAGMENTS.some((f) => normalised.includes(f));
+}
+
+/** Parse one stack line into a location, or null when it is not one. */
+export function parseFrame(line: string): SourceLocation | null {
+  const match = FRAME.exec(line);
+  if (!match) return null;
+  const [, rawName, file, lineNo, column] = match;
+  if (!file || !lineNo) return null;
+  const name = rawName?.replace(/^async\s+/, "").trim();
+  return {
+    file,
+    line: Number(lineNo),
+    column: Number(column ?? 1),
+    ...(name ? { function: name } : {}),
+  };
+}
+
+/**
+ * Every frame of a stack, framework noise included.
+ *
+ * Used for an exception, where the full trace is the point — you are reading it
+ * to find out how you got somewhere, and a trace with the framework removed does
+ * not tell you that.
+ *
+ * @param stack - An `Error.stack` string.
+ * @param limit - How many frames to keep.
+ */
+export function parseStack(stack: string | undefined, limit = MAX_FRAMES): SourceLocation[] {
+  if (!stack) return [];
+  const out: SourceLocation[] = [];
+  for (const line of stack.split("\n")) {
+    const frame = parseFrame(line);
+    if (frame) out.push(frame);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * The first application frame in a stack.
+ *
+ * Null when every frame is framework — a query run from a seeder, a log line
+ * from inside a package — which is a truthful answer and better than pointing at
+ * a file the reader did not write.
+ *
+ * Pure, and separate from {@link captureCallSite}, because this is the part with
+ * a decision in it: which frames count as yours. Taking the stack as an argument
+ * is also the only way to test it from inside this package, whose own files the
+ * filter is supposed to reject.
+ *
+ * @param stack - An `Error.stack` string.
+ * @param skip - Frames to drop before looking, for a caller that knows its own
+ *   wrappers are on the stack.
+ */
+export function firstAppFrame(stack: string | undefined, skip = 0): SourceLocation | null {
+  if (!stack) return null;
+
+  // The first line is the "Error" header on V8 and absent on JSC; `parseFrame`
+  // returns null for it either way, so this does not need to know which runtime
+  // it is on.
+  let seen = 0;
+  const lines = stack.split("\n");
+  for (let i = 0; i < lines.length && i < MAX_FRAMES; i++) {
+    const frame = parseFrame(lines[i]!);
+    if (!frame) continue;
+    if (seen++ < skip) continue;
+    if (isFrameworkFrame(frame.file)) continue;
+    return frame;
+  }
+  return null;
+}
+
+/**
+ * Where in the application this was called from.
+ *
+ * @param skip - Frames to drop before looking. The console patch passes 1,
+ *   because it stands between the caller and the stack.
+ */
+export function captureCallSite(skip = 0): SourceLocation | null {
+  return firstAppFrame(new Error().stack, skip);
+}

package/src/client/filter.ts

@@ -0,0 +1,108 @@
+/**
+ * Which traces the All tab shows.
+ *
+ * Two independent narrowings that compose with AND: free text, and facets. Text
+ * answers "the request I am thinking of"; facets answer "the kind of request I am
+ * hunting" — and a list you can only search by name is one you cannot ask "show
+ * me the failures" of.
+ *
+ * All of it is pure, and none of it touches the DOM: this is the part of the
+ * panel that is logic rather than markup, and it is worth testing without a
+ * browser.
+ */
+import type { RequestTrace } from "../RequestTrace.ts";
+
+/**
+ * A request slower than this reads as slow.
+ *
+ * The same boundary the duration colour already uses, so the `slow` facet
+ * selects exactly the rows that were already amber or red — a filter that
+ * disagreed with the colouring next to it would be worse than no filter.
+ */
+export const SLOW_MS = 300;
+
+/** The non-text narrowings, each empty or false meaning "do not narrow by this". */
+export interface Facets {
+  /** Uppercase method names. Empty means every method. */
+  methods: string[];
+  /** Status classes as their leading digit — `"2"`, `"4"`, … Empty means every status. */
+  statusClasses: string[];
+  /** Only requests that threw. */
+  errors: boolean;
+  /** Only requests slower than {@link SLOW_MS}. */
+  slow: boolean;
+  /** Only requests with an N+1 warning. */
+  nPlusOne: boolean;
+}
+
+/** No narrowing at all — what a fresh panel starts with. */
+export function noFacets(): Facets {
+  return { methods: [], statusClasses: [], errors: false, slow: false, nPlusOne: false };
+}
+
+/** Whether any facet is actually narrowing, for the "clear" affordance. */
+export function facetsActive(f: Facets): boolean {
+  return f.methods.length > 0 || f.statusClasses.length > 0 || f.errors || f.slow || f.nPlusOne;
+}
+
+/**
+ * Match a trace against the All tab's filter box.
+ *
+ * Every space-separated term has to match, so `posts 500` narrows twice rather
+ * than widening — a filter that ORs its terms gets less useful the more you type.
+ * The haystack covers what you would search a request list by: method, path,
+ * status, and the route it matched.
+ */
+export function matchesFilter(trace: RequestTrace, query: string): boolean {
+  const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return true;
+  const haystack = [
+    trace.method,
+    trace.path,
+    String(trace.statusCode),
+    trace.route?.pattern ?? "",
+    trace.route?.controller ?? "",
+    trace.route?.action ?? "",
+  ]
+    .join(" ")
+    .toLowerCase();
+  return terms.every((term) => haystack.includes(term));
+}
+
+/**
+ * Match a trace against the facet chips.
+ *
+ * Within one facet the values are alternatives — picking `GET` and `POST` shows
+ * both. Across facets they compound, the same way the text terms do: `POST` plus
+ * `5xx` means failing writes, not writes-or-failures.
+ */
+export function matchesFacets(trace: RequestTrace, f: Facets): boolean {
+  if (f.methods.length && !f.methods.includes(trace.method.toUpperCase())) return false;
+  if (f.statusClasses.length) {
+    const cls = String(trace.statusCode || 0).charAt(0);
+    if (!f.statusClasses.includes(cls)) return false;
+  }
+  // A 4xx or 5xx counts as an error even when nothing threw: a rendered 404 is a
+  // failed request to anyone reading this list, and the trace only carries an
+  // `exception` when an error escaped the pipeline.
+  if (f.errors && !trace.exception && trace.statusCode < 400) return false;
+  if (f.slow && trace.durationMs <= SLOW_MS) return false;
+  if (f.nPlusOne && !trace.warnings.length) return false;
+  return true;
+}
+
+/** Both narrowings at once — what the All tab actually asks. */
+export function traceMatches(trace: RequestTrace, query: string, f: Facets): boolean {
+  return matchesFacets(trace, f) && matchesFilter(trace, query);
+}
+
+/**
+ * The method chips worth offering, from the traces actually recorded.
+ *
+ * Listing every HTTP verb would put five dead chips on screen for an app that
+ * only ever GETs. Sorted for a stable strip — chips that reorder as traffic
+ * arrives are chips you have to re-find every time you look.
+ */
+export function methodsPresent(traces: RequestTrace[]): string[] {
+  return [...new Set(traces.map((t) => t.method.toUpperCase()))].sort();
+}