@zerotal/devtools 1.6.3 → 1.7.2

package/src/editor.ts

@@ -0,0 +1,107 @@
+/**
+ * `file:line` → a URL your editor opens.
+ *
+ * A repo-wide search for any editor URL scheme used to return nothing: no stack
+ * frame, query, log line, or prop in any Zerotal surface was clickable to source.
+ * Going from "this query is slow" to the line that ran it is the most frequent
+ * move in a debugging session, and it was two manual searches — copy the path,
+ * find the file, find the line.
+ *
+ * The schemes are the editors' own and are stable; what is *not* stable is where
+ * the file lives relative to the person reading the panel, which is what
+ * {@link mapEditorPath} is for.
+ */
+
+/** A place in the source. The one shape every capture in the panel produces. */
+export interface SourceLocation {
+  /** Absolute path as the server saw it. */
+  file: string;
+  line: number;
+  column?: number;
+  /** The function the frame was in, when the runtime named one. */
+  function?: string;
+}
+
+/** Editors that register a URL scheme for opening a file at a line. */
+export type EditorName = "vscode" | "vscode-insiders" | "cursor" | "windsurf" | "zed" | "webstorm";
+
+/**
+ * How each editor spells "open this file here".
+ *
+ * Two families: the VS Code line takes a query string, JetBrains takes the same
+ * shape under a different host, and Zed puts the position in the path. Written
+ * out rather than templated because there are six of them and a template that
+ * covers all six is harder to read than the six.
+ */
+const SCHEMES: Record<EditorName, (file: string, line: number, column: number) => string> = {
+  vscode: (f, l, c) => `vscode://file/${f}:${l}:${c}`,
+  "vscode-insiders": (f, l, c) => `vscode-insiders://file/${f}:${l}:${c}`,
+  cursor: (f, l, c) => `cursor://file/${f}:${l}:${c}`,
+  windsurf: (f, l, c) => `windsurf://file/${f}:${l}:${c}`,
+  zed: (f, l, c) => `zed://file/${f}:${l}:${c}`,
+  webstorm: (f, l) => `webstorm://open?file=${encodeURIComponent(f)}&line=${l}`,
+};
+
+/** Every editor this understands, for a config error worth reading. */
+export const EDITORS = Object.keys(SCHEMES) as EditorName[];
+
+/**
+ * Rewrite a server path to where the reader's editor can find it.
+ *
+ * The process recording a trace is often not the machine reading it — a
+ * container reports `/app/src/Foo.ts` for a file that is `~/project/src/Foo.ts`
+ * on the laptop with the editor. Longest prefix wins, so a specific mapping can
+ * sit inside a general one.
+ *
+ * @param file - The path as captured.
+ * @param map - Prefix → replacement, from the app's `editorPathMap`.
+ */
+export function mapEditorPath(file: string, map: Record<string, string>): string {
+  let bestPrefix = "";
+  let bestReplacement = "";
+  for (const [prefix, replacement] of Object.entries(map)) {
+    if (file.startsWith(prefix) && prefix.length > bestPrefix.length) {
+      bestPrefix = prefix;
+      bestReplacement = replacement;
+    }
+  }
+  return bestPrefix ? bestReplacement + file.slice(bestPrefix.length) : file;
+}
+
+/**
+ * The URL that opens `location` in `editor`, or null when there is nothing to
+ * link to.
+ *
+ * Null rather than a broken link for the two cases that mean "do not link":
+ * `editor: null` in the config, and a location with no file. The panel renders
+ * the location as plain text then, which is still worth showing.
+ *
+ * @param location - Where to go.
+ * @param editor - The configured editor, or null to disable linking.
+ * @param map - Path rewrites for editing on a different machine.
+ */
+export function editorUrl(
+  location: SourceLocation | null | undefined,
+  editor: EditorName | null,
+  map: Record<string, string> = {},
+): string | null {
+  if (!editor || !location?.file) return null;
+  const scheme = SCHEMES[editor];
+  if (!scheme) return null;
+  // Backslashes are legal in a Windows path and illegal in a URL path segment;
+  // every one of these editors accepts the forward-slash form on Windows.
+  const file = mapEditorPath(location.file, map).replace(/\\/g, "/");
+  return scheme(file, Math.max(1, location.line || 1), Math.max(1, location.column ?? 1));
+}
+
+/**
+ * A location as the panel labels it: the last two path segments and the line.
+ *
+ * Not the whole path — an absolute path from a monorepo is sixty characters of
+ * which the last twenty are the part you read.
+ */
+export function shortLocation(location: SourceLocation): string {
+  const parts = location.file.replace(/\\/g, "/").split("/");
+  const tail = parts.slice(-2).join("/");
+  return `${tail}:${location.line}`;
+}

package/src/enabled.ts

@@ -0,0 +1,59 @@
+/**
+ * One place that answers "is the inspector on, and for whom".
+ *
+ * Separated from the provider and the middleware because both need the same
+ * answer, and two gates that can disagree is how a dev-only surface ends up
+ * serving request headers in production.
+ *
+ * The panel was all-or-nothing on {@link devSurfacesEnabled} until it grew things
+ * worth gating: request bodies, session keys, stack traces, the resolved config.
+ * That default is still right — a deployed process exposes nothing — but "off
+ * everywhere but my laptop" is not the only shape a team needs, and without a
+ * supported escape hatch the way you run this on a shared staging box is to lie
+ * about `APP_ENV`.
+ */
+import { config, devSurfacesEnabled } from "@zerotal/core";
+import { DevtoolsConfig, type DevtoolsConfigShape } from "./config.ts";
+
+/** The `devtools` config block, with defaults when config is not loaded. */
+export function devtoolsSettings(): DevtoolsConfigShape {
+  return DevtoolsConfig(config.safe<Partial<DevtoolsConfigShape>>("devtools", {}));
+}
+
+/**
+ * Whether the inspector should run at all.
+ *
+ * `enabled: null` (the default) defers to {@link devSurfacesEnabled} — the same
+ * gate as the stack-trace error page — so the panel is on under `zt dev` and off
+ * in a production deploy without anyone configuring it. An explicit `true` or
+ * `false` wins, which is what makes it testable and what lets an app run it on a
+ * staging box behind a gate.
+ */
+export function devtoolsEnabled(): boolean {
+  return devtoolsSettings().enabled ?? devSurfacesEnabled();
+}
+
+/**
+ * Whether this request may reach the inspector's endpoints.
+ *
+ * A dev process always may — a gate that can lock a developer out of their own
+ * machine gets switched off, and then nothing is gated. Anywhere else the app's
+ * `gate` decides, and the absence of one is a **refusal** rather than a default
+ * allow: an app that turned the inspector on outside development without saying
+ * who may read it has not made a decision this code should make for it.
+ *
+ * One function answers for every endpoint. The SSE stream, the trace JSON, the
+ * dashboard, and the panel bundle are the same secret.
+ */
+export async function devtoolsAuthorized(request: Request): Promise<boolean> {
+  if (devSurfacesEnabled()) return true;
+  const gate = devtoolsSettings().gate;
+  if (!gate) return false;
+  try {
+    return await gate(request);
+  } catch {
+    // A gate that throws has not said yes. Failing open here would turn a typo in
+    // someone's authorization check into an open trace inspector.
+    return false;
+  }
+}

package/src/index.ts

@@ -1,14 +1,29 @@
 // @zerotal/devtools — public API barrel
 
 export { DevtoolsProvider } from "./provider/DevtoolsProvider.ts";
-export type { DevtoolsPanelPlugin } from "./client.ts";
+export type { DevtoolsPanelPlugin } from "./client/registry.ts";
 export { DevtoolsInjectionMiddleware, startDevtoolsStream } from "./DevtoolsInjectionMiddleware.ts";
 export type { DevtoolsInjectionOptions } from "./DevtoolsInjectionMiddleware.ts";
 export { TraceStore, traceStore, _setTraceStore } from "./TraceStore.ts";
 export type { TraceStoreOptions } from "./TraceStore.ts";
 export { DevtoolsConfig } from "./config.ts";
-export type { DevtoolsConfigShape } from "./config.ts";
-export { redactBindings, attributeBindings } from "./redaction.ts";
+export type { DevtoolsConfigShape, DevtoolsGate } from "./config.ts";
+// Whether the inspector is running, for an app that wants to branch on it. The
+// gate check and the settings reader beside it are plumbing for the middleware
+// and the provider — an app never calls them, and exporting them only so a
+// same-package test can import them is how internals become unchangeable.
+export { devtoolsEnabled } from "./enabled.ts";
+// Types only: both appear on shapes an app can hold (`SourceLocation` on a
+// `QuerySpan`, `EditorName` in its config). The URL builders and the stack walker
+// behind them are the panel's own business.
+export type { EditorName, SourceLocation } from "./editor.ts";
+export {
+  redactBindings,
+  redactValue,
+  redactCacheKey,
+  isSensitiveName,
+  attributeBindings,
+} from "./redaction.ts";
 export type { RedactionOptions } from "./redaction.ts";
 export { traceSink, traceChannels } from "./tracing.ts";
 export type { TraceSink } from "./tracing.ts";
@@ -20,6 +35,7 @@ export type {
   CacheEntry,
   JobEntry,
   LogEntry,
+  ExceptionInfo,
   RouteInfo,
   AuthInfo,
   TraceChannelDescriptor,

package/src/map.ts

@@ -0,0 +1,213 @@
+/**
+ * The application as it is, rather than as it just behaved.
+ *
+ * Every tab up to here reads the trace stream: what one request did. This reads
+ * the framework's own registries — the routes it will match, the config it
+ * resolved, what is in the container, which providers put it there, and what
+ * listens to what. All of it existed already and all of it was CLI-only or
+ * invisible, so the questions it answers ("is that route even registered", "who
+ * bound `cache`", "does anything listen to `OrderPlaced`") were answered by
+ * reading source.
+ *
+ * Nothing here is instrumented. It is a read of state the app is already
+ * keeping, taken when the panel asks — which is also why it needs no store and
+ * no retention: there is only ever one current answer.
+ */
+import { Router, FrameworkEvents } from "@zerotal/core";
+import type { Application, Emitter } from "@zerotal/core";
+import { isSensitiveName } from "./redaction.ts";
+import { redactGraph } from "@zerotal/core/security";
+import type { RedactionOptions } from "./redaction.ts";
+
+/** One registered route, flattened for display. */
+export interface RouteRow {
+  method: string;
+  path: string;
+  name: string;
+  handler: string;
+  middleware: string;
+}
+
+/** One container binding. */
+export interface BindingRow {
+  token: string;
+  kind: string;
+  /** The provider that bound it, when boot recorded one. */
+  provider: string;
+}
+
+/** One provider, in boot order. */
+export interface ProviderRow {
+  name: string;
+  durationMs: number;
+  bindings: number;
+}
+
+/** One event and what reacts to it. */
+export interface EventRow {
+  event: string;
+  /** Application listener class names, or the handler count for a framework event. */
+  listeners: string;
+  source: "application" | "framework";
+}
+
+/** Everything the App section draws. */
+export interface FrameworkMap {
+  routes: RouteRow[];
+  config: Record<string, unknown>;
+  bindings: BindingRow[];
+  providers: ProviderRow[];
+  events: EventRow[];
+  /** Wall-clock boot time, so the provider list has a total to be read against. */
+  bootMs: number | null;
+}
+
+/** `[class PostController]` → `PostController`; a plain token passes through. */
+function tokenName(token: unknown): string {
+  if (typeof token === "string") return token;
+  if (typeof token === "function") return token.name || "‹anonymous›";
+  return String(token);
+}
+
+/**
+ * Every registered route, newest framework state, sorted for reading.
+ *
+ * Sorted by path then method rather than by registration order: registration
+ * order is an implementation detail of which file loaded first, and a list you
+ * scan for "is `/posts/:id` there" wants the paths together.
+ */
+export function routeRows(): RouteRow[] {
+  // `namedRoutes` is name → path; the panel wants the reverse.
+  const nameByPath = new Map<string, string>();
+  for (const [name, path] of Router.namedRoutes) nameByPath.set(path, name);
+
+  return [...Router.routes.values()]
+    .map((route) => ({
+      method: route.method,
+      path: route.path,
+      name: nameByPath.get(route.path) ?? "",
+      handler: `${route.controller?.name ?? "—"}@${route.action}`,
+      middleware: route.middleware
+        .map((m) => m.name)
+        .filter(Boolean)
+        .join(", "),
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+}
+
+/**
+ * The resolved config, with anything that looks like a secret masked.
+ *
+ * Exposing config is how a debugging tool leaks a database password, so this is
+ * the one surface here that is *not* a plain read. The same `isSensitiveName`
+ * rule the rest of the package uses decides, which means an app's `allow` and
+ * `deny` mean the same thing here as they do on the Queries tab — and it is a
+ * deny-by-default rule, so a key nobody anticipated is masked rather than shown.
+ */
+export function configTree(
+  all: Record<string, unknown>,
+  redaction: RedactionOptions,
+): Record<string, unknown> {
+  // Stricter here than anywhere else in the package, deliberately. The shared
+  // list masks `api_key` and `private_key` but not a bare `key` — reasonable for
+  // a query binding, where a column called `key` is usually a lookup key, and
+  // wrong for config, where `app.key` is the application's encryption key. Same
+  // reasoning for `dsn`: a connection string is credentials with a hostname
+  // attached. Config is the one place secrets are *supposed* to live, so it gets
+  // the benefit of the doubt in the other direction.
+  const strict: RedactionOptions = {
+    ...redaction,
+    deny: [...(redaction.deny ?? []), "key", "dsn"],
+  };
+  return redactGraph(all, {
+    sensitive: (key) => isSensitiveName(key, strict),
+    mask: "‹redacted›",
+    circular: "‹circular›",
+    tooDeep: "‹truncated›",
+    // Deeper than a trace entry: config is nested by design and a namespace
+    // truncated three levels in is a namespace you cannot read.
+    maxDepth: 10,
+    flatten: (value) => (typeof value === "function" ? "‹fn›" : undefined),
+  }) as Record<string, unknown>;
+}
+
+/**
+ * What is in the container, and who put it there.
+ *
+ * Provenance comes from the boot report rather than from the container, which
+ * does not track it — see `Application.providerReport`.
+ */
+export function bindingRows(app: Application): BindingRow[] {
+  const owner = new Map<string, string>();
+  for (const provider of app.providerReport) {
+    for (const token of provider.bindings) owner.set(token, provider.name);
+  }
+
+  return [...app.container.registry.entries()]
+    .map(([token, binding]) => {
+      const name = tokenName(token);
+      return {
+        token: name,
+        kind: (binding as { kind?: string }).kind ?? "unknown",
+        provider: owner.get(name) ?? "—",
+      };
+    })
+    .sort((a, b) => a.token.localeCompare(b.token));
+}
+
+/** Providers in boot order, with what each cost. */
+export function providerRows(app: Application): ProviderRow[] {
+  return app.providerReport.map((p) => ({
+    name: p.name,
+    durationMs: p.durationMs,
+    bindings: p.bindings.length,
+  }));
+}
+
+/**
+ * Application listeners and framework subscribers, in one list.
+ *
+ * Two different mechanisms — `Emitter.on()` for the app's own events,
+ * `FrameworkEvents.on()` for the framework bus — and a developer asking "what
+ * reacts to this" does not care which. The `source` column keeps them
+ * distinguishable without splitting the answer in two.
+ */
+export function eventRows(emitter: Emitter | undefined): EventRow[] {
+  const rows: EventRow[] = [];
+
+  for (const { event, listeners } of emitter?.registrations() ?? []) {
+    rows.push({ event, listeners: listeners.join(", "), source: "application" });
+  }
+  for (const { event, handlers } of FrameworkEvents.subscriptions()) {
+    rows.push({
+      event,
+      listeners: `${handlers} subscriber${handlers === 1 ? "" : "s"}`,
+      source: "framework",
+    });
+  }
+  return rows.sort((a, b) => a.event.localeCompare(b.event));
+}
+
+/**
+ * Read the whole map.
+ *
+ * Taken fresh on each request for it. The registries are small and static, and a
+ * cached map is a map that disagrees with the app the moment a provider
+ * registers a route late.
+ */
+export function buildFrameworkMap(app: Application, redaction: RedactionOptions): FrameworkMap {
+  const config = app.container.tryMake("config");
+  const emitter = app.container.tryMake("events") as Emitter | undefined;
+
+  return {
+    routes: routeRows(),
+    config: configTree(
+      (config as { all?: () => Record<string, unknown> } | undefined)?.all?.() ?? {},
+      redaction,
+    ),
+    bindings: bindingRows(app),
+    providers: providerRows(app),
+    events: eventRows(emitter),
+    bootMs: app.bootDurationMs ?? null,
+  };
+}

package/src/provider/DevtoolsProvider.ts

@@ -4,6 +4,8 @@ import {
   type AppEnvironment,
   type HttpContext,
 } from "@zerotal/core";
+import { devtoolsEnabled } from "../enabled.ts";
+import { startActivityCapture, _resetActivity } from "../activity.ts";
 import { DevReloadMiddleware, registerDevHtmlSnippet } from "@zerotal/core/dev";
 import {
   DevtoolsInjectionMiddleware,
@@ -19,6 +21,8 @@ import {
   traceSink,
   _resetChannels,
   _setRedaction,
+  _setCaptureSource,
+  _setHeaderAllowlist,
   type TraceSink,
 } from "../tracing.ts";
 
@@ -69,6 +73,7 @@ export class DevtoolsProvider extends ServiceProvider {
   /** Set once the provider has activated, so teardown only undoes what it did. */
   private _active = false;
   private _stopStream: (() => void) | null = null;
+  private _stopActivity: (() => void) | null = null;
 
   override async onBooting(): Promise<void> {
     // Fail closed: only activate for explicitly non-prod environments. An unset or
@@ -80,7 +85,12 @@ export class DevtoolsProvider extends ServiceProvider {
     //     runtime mode, so this was asking whether `"web"` is a development environment;
     //   - it is the only dev gate that did not honour `ZT_DEV`, which is what the dev
     //     orchestrator sets on the server it supervises — so `zt dev` did not help either.
-    if (!devSurfacesEnabled()) return;
+    // `devtoolsEnabled()` rather than `devSurfacesEnabled()` directly: the app's
+    // `enabled` setting wins when it is set, which is what lets the inspector run
+    // on a shared staging box behind a `gate`. `null` — the default — still
+    // defers to the dev-surface gate, so nothing changes for anyone who has not
+    // asked for it.
+    if (!devtoolsEnabled()) return;
     this._active = true;
 
     const config = this._config();
@@ -96,6 +106,8 @@ export class DevtoolsProvider extends ServiceProvider {
       }),
     );
     _setRedaction(config.redact);
+    _setCaptureSource(config.captureSource);
+    _setHeaderAllowlist(config.headers);
 
     // Expose the trace sink so feature packages can contribute per-request spans
     // and declare their own channels. Bound in onBooting so it is available when
@@ -113,12 +125,19 @@ export class DevtoolsProvider extends ServiceProvider {
     // injector — no `DevTools.start()` needed in the app's own bundle. Also
     // register the injector so this works under a plain `serve` (not only
     // `serve --dev-worker`, where Application.enableDevWs() already adds it).
-    this.app.useOnce(DevReloadMiddleware);
-    registerDevHtmlSnippet("zerotal-devtools", (ctx: HttpContext) =>
-      ctx.url.pathname.startsWith("/__zerotal")
-        ? "" // don't inject the panel into the devtools' own pages
-        : `<script type="module" src="/__zerotal/devtools/client.js"></script>`,
-    );
+    //
+    // Only on a development machine. Auto-injection is a convenience for the
+    // person running the app; on a gated environment the snippet would go into
+    // every visitor's HTML and then 403 in their console, so there the way in is
+    // the dashboard at `/__zerotal/devtools`, which the gate answers for.
+    if (devSurfacesEnabled()) {
+      this.app.useOnce(DevReloadMiddleware);
+      registerDevHtmlSnippet("zerotal-devtools", (ctx: HttpContext) =>
+        ctx.url.pathname.startsWith("/__zerotal")
+          ? "" // don't inject the panel into the devtools' own pages
+          : `<script type="module" src="/__zerotal/devtools/client.js"></script>`,
+      );
+    }
   }
 
   override async onBooted(): Promise<void> {
@@ -128,6 +147,9 @@ export class DevtoolsProvider extends ServiceProvider {
     // devtools no longer imports @zerotal/orm — it only consumes FrameworkEvents.
     startDevtoolsTracing();
     startConsoleCapture();
+    // Console commands and scheduled tasks, which have no request to hang off
+    // and so appeared nowhere at all.
+    this._stopActivity = startActivityCapture();
     this._stopStream = startDevtoolsStream();
 
     process.stdout.write(
@@ -141,9 +163,12 @@ export class DevtoolsProvider extends ServiceProvider {
     if (!this._active) return;
     stopDevtoolsTracing();
     stopConsoleCapture();
+    this._stopActivity?.();
+    this._stopActivity = null;
     this._stopStream?.();
     this._stopStream = null;
     _resetChannels();
+    _resetActivity();
     // Flushes any pending batch and closes the database — without this a suite
     // that boots several apps leaves a handle and an hourly timer per app.
     _setTraceStore(null);