@zerotal/devtools 1.6.3 → 1.7.0

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,53 @@ export interface TraceChannelDescriptor {
   warn?: string;
   /** Sort order among channel tabs. Lower sorts first. Defaults to 100. */
   order?: number;
+
+  // ── 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 +204,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();
+}

package/src/client/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @zerotal/devtools — browser client
+ *
+ * Usage (in your app.js / frontend entry):
+ *   import { DevTools } from '@zerotal/devtools/client';
+ *   DevTools.start();
+ *
+ * Connects to the SSE stream served by DevtoolsInjectionMiddleware and renders a
+ * live floating panel. No script injection by the server is required.
+ *
+ * This file is only the wiring. The panel was one 1,400-line closure holding its
+ * state, its transport, its styles, eight renderers, and every helper — which
+ * made adding a tab an edit to the middle of it and made none of its logic
+ * testable. It is now a directory: {@link Store} holds the state,
+ * `transport.ts` owns the wire, `ui/shell.ts` owns the frame, and each tab is a
+ * file that exports a {@link TabView}. Both mount modes still run one set of
+ * renderers, and both extension doors are unchanged.
+ */
+import { Store } from "./state.ts";
+import { collectClientMetrics, onceLoaded } from "./metrics.ts";
+import { connect } from "./transport.ts";
+import { mountShell } from "./ui/shell.ts";
+import { allTab } from "./tabs/all.ts";
+import { cacheTab } from "./tabs/cache.ts";
+import { exceptionsTab } from "./tabs/exceptions.ts";
+import { jobsTab } from "./tabs/jobs.ts";
+import { logsTab } from "./tabs/logs.ts";
+import { mailTab } from "./tabs/mail.ts";
+import { queriesTab } from "./tabs/queries.ts";
+import { requestTab } from "./tabs/request.ts";
+import { timelineTab } from "./tabs/timeline.ts";
+
+export interface DevtoolsClientOptions {
+  /** Base URL path for the devtools API. Default: '/__zerotal/devtools' */
+  endpoint?: string;
+  /**
+   * How the panel is mounted.
+   *
+   * `'floating'` (default) pins a collapsible bar to the bottom of the page.
+   * `'standalone'` fills the window and drops the collapse/close controls — the
+   * inspector dashboard. Both run the same renderers, so a tab added for one
+   * exists in the other.
+   */
+  mode?: "floating" | "standalone";
+  /** Element to mount into. Defaults to `document.body`. */
+  mount?: HTMLElement;
+}
+
+/**
+ * The built-in tabs, in strip order.
+ *
+ * The order is also the `1`–`9` keyboard order, so it is worth being deliberate
+ * about: queries first because it is where a request explains itself, all last
+ * because it is where you go to leave the request you are on.
+ */
+const BUILT_IN = [
+  queriesTab,
+  timelineTab,
+  logsTab,
+  requestTab,
+  exceptionsTab,
+  mailTab,
+  cacheTab,
+  jobsTab,
+  allTab,
+];
+
+export const DevTools = {
+  start(opts: DevtoolsClientOptions = {}): void {
+    if (typeof document === "undefined") return;
+    if (document.getElementById("__zerotal_dt__")) return;
+
+    const base = (opts.endpoint ?? "/__zerotal/devtools").replace(/\/$/, "");
+    const standalone = opts.mode === "standalone";
+
+    const store = new Store(standalone, base);
+    const transport = connect(base, store);
+
+    // What the browser measured for this page load, read once after it settles.
+    // The panel reports server duration as though it were the user's experience;
+    // it is not, and this is the only place that knows the difference.
+    onceLoaded(() => {
+      store.clientMetrics = collectClientMetrics();
+      store.changed();
+    });
+
+    mountShell({
+      base,
+      standalone,
+      mount: opts.mount ?? document.body,
+      store,
+      transport,
+      tabs: BUILT_IN,
+    });
+  },
+};
+
+// ── Public surface ────────────────────────────────────────────────────────────
+//
+// The panel is markup, and markup is awkward to assert on. What is exported here
+// is the part of it that is *logic*: a package contributing a channel can check
+// how its rows will filter, fold, and nest without a browser.
+//
+// Deliberately not everything the directory exports. `TabView`, the theme choice,
+// and the All tab's own mechanics are internal contracts this package reserves
+// the right to change — the tests that cover them import them by path, which is
+// what a same-package test should do rather than widening the API to be reachable.
+
+export type { DevtoolsPanelPlugin } from "./registry.ts";
+export type { Facets } from "./filter.ts";
+export type { PathTreeNode, TraceRow } from "./tree.ts";
+
+export {
+  matchesFilter,
+  matchesFacets,
+  traceMatches,
+  methodsPresent,
+  noFacets,
+  facetsActive,
+  SLOW_MS,
+} from "./filter.ts";
+export { buildPathTree, traceGroupKey, foldTraceRows } from "./tree.ts";