@zerotal/devtools 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog — @zerotal/devtools
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `experimental`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Added
+
+- **Extensible panel — other packages can add their own tab.** The injected panel now exposes a global registry, `window.__zerotalDevtools`, that any package's browser code pushes a panel into: `window.__zerotalDevtools?.register({ id, title, badge?, render })` adds a tab alongside Queries/Logs/Request/Mail/Cache/Jobs, and `refresh(id)` pushes a live update (badge + re-render the open tab). Registration is order-independent (the registry is created by whichever runs first) and optional-peer friendly (guard with `?.`; a no-op when devtools isn't present). Panels render into the shared Shadow-DOM content area, so the devtools CSS classes/variables are available and contributed tabs match the panel without shipping styles. The `DevtoolsPanelPlugin` type is exported for TypeScript consumers. First consumer: `@zerotal/flow`'s time-travel Timeline. See [Extending the panel](/docs/devtools#extending-the-panel).
+
+### Changed
+
+- Moved service provider to `src/provider/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @zerotal/devtools
+
+> A live, in-page development panel that traces every request — SQL queries, N+1 warnings, logs, mail, cache, and jobs.
+
+`@zerotal/devtools` injects a floating debug panel into every HTML response during development. No browser extension required: it shows per-request traces and exposes a `TraceStore` you can read programmatically. `DevtoolsProvider` is a no-op when `APP_ENV=production` or `APP_ENV=prod`.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/devtools
+```
+
+## Setup
+
+### 1. Register the provider
+
+```typescript
+// bootstrap/providers.ts
+import { DatabaseProvider } from "@zerotal/orm";
+import { DevtoolsProvider } from "@zerotal/devtools";
+
+const providers = [
+  // …your other providers
+  DatabaseProvider,
+  DevtoolsProvider,
+];
+
+export default providers;
+```
+
+`DevtoolsProvider` automatically registers `DevtoolsInjectionMiddleware` — you do not need to add it to `.use([…])` manually.
+
+### 2. Start the client panel
+
+In your frontend entry (e.g. `resources/js/app.js`):
+
+```typescript
+import { DevTools } from "@zerotal/devtools/client";
+DevTools.start(); // optionally { endpoint: "/__zerotal/devtools" }
+```
+
+This connects to the SSE stream and mounts the floating panel. Press `Alt+D` (or `Cmd+D` on Mac) to toggle it.
+
+## Usage
+
+### Read traces programmatically
+
+```typescript
+import { traceStore } from "@zerotal/devtools";
+
+// All traces stored in memory (up to 100, most recent first)
+const traces = traceStore().all();
+
+// Find slow requests / N+1 offenders
+const slow = traces.filter((t) => t.durationMs > 500);
+const nplus = traces.filter((t) => t.warnings.length > 0);
+
+// Subscribe to new traces (fn receives null on 'clear')
+const unsub = traceStore().subscribe((trace) => {
+  if (trace === null) return;
+  console.log(`${trace.method} ${trace.path} → ${trace.statusCode} (${trace.durationMs}ms)`);
+});
+unsub();
+
+traceStore().clear();
+```
+
+Traces persist to `.zerotal/devtools.sqlite` and reload on restart. Configure in
+`config/devtools.ts`:
+
+```ts
+import { DevtoolsConfig } from "@zerotal/devtools";
+
+export default DevtoolsConfig({
+  capacity: 250,
+  dbPath: ".data/devtools.sqlite", // null keeps traces in memory only
+  pruneHours: 48,
+  redact: { allow: ["email"] }, // query bindings are masked by default
+});
+```
+
+`ZT_DEVTOOLS_DB` and `ZT_DEVTOOLS_PRUNE_HOURS` still apply when no config
+file is present.
+
+## Exports
+
+The package exposes two subpaths:
+
+### `@zerotal/devtools` (`.`)
+
+| Export                        | Kind             | Description                                                                                                      |
+| ----------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `DevtoolsProvider`            | provider         | Registers the injection middleware and internal `/__zerotal/devtools` routes (dev only).                         |
+| `DevtoolsInjectionMiddleware` | middleware       | Injects the panel into HTML responses. Type: `DevtoolsInjectionOptions`.                                         |
+| `TraceStore`, `traceStore`    | class / accessor | In-memory + SQLite-backed trace store (`all`, `push`, `clear`, `subscribe`, `dispose`).                          |
+| `DevtoolsConfig`              | config           | Typed `config/devtools.ts` factory. Type: `DevtoolsConfigShape`.                                                 |
+| `traceSink`, `traceChannels`  | sink / registry  | The `devtools.trace` surface other packages contribute through.                                                  |
+| `redactBindings`              | function         | Mask the bindings of a statement. Type: `RedactionOptions`.                                                      |
+| Trace types                   | types            | `RequestTrace`, `QuerySpan`, `NPlusOneWarning`, `MailEntry`, `CacheEntry`, `JobEntry`, `TraceChannelDescriptor`. |
+
+### `@zerotal/devtools/client` (`./client`)
+
+| Export     | Description                                                           |
+| ---------- | --------------------------------------------------------------------- |
+| `DevTools` | Browser-side panel; call `DevTools.start()` from your frontend entry. |
+
+## Documentation
+
+- [DevTools](../../docs/devtools.md)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zerotal/devtools",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "experimental",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@zerotal/orm": "1.0.0"
+  },
+  "description": "In-browser developer tools for Zerotal — request traces, an inspector panel, and an extensible tab registry.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/devtools"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/devtools#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/DevtoolsInjectionMiddleware.ts

@@ -0,0 +1,167 @@
+import { fileURLToPath } from "node:url";
+import type { NextFn, HttpContext } from "@zerotal/core";
+import { BaseMiddleware } from "@zerotal/core";
+import { traceStore } from "./TraceStore.ts";
+import { traceChannels } from "./tracing.ts";
+
+// ── Injected browser client bundle ────────────────────────────────────────────
+// The in-page devtools panel is bundled for the browser on first request and
+// cached for the process lifetime (dev only — the provider is a no-op in prod).
+let _clientJs: string | null = null;
+
+async function _buildClientJs(): Promise<string> {
+  if (_clientJs !== null) return _clientJs;
+  try {
+    const entry = fileURLToPath(new URL("./client-auto.ts", import.meta.url));
+    const result = await Bun.build({ entrypoints: [entry], target: "browser", minify: true });
+    const out = result.outputs[0];
+    _clientJs =
+      result.success && out ? await out.text() : "/* [Zerotal DevTools] client build failed */";
+  } catch (error) {
+    _clientJs = `/* [Zerotal DevTools] client build error: ${String(error)} */`;
+  }
+  return _clientJs;
+}
+
+/** The standalone dashboard bundle — the same panel, mounted full-window. */
+let _dashboardJs: string | null = null;
+
+async function _buildDashboardJs(): Promise<string> {
+  if (_dashboardJs !== null) return _dashboardJs;
+  try {
+    const entry = fileURLToPath(new URL("./dashboard-auto.ts", import.meta.url));
+    const result = await Bun.build({ entrypoints: [entry], target: "browser", minify: true });
+    const out = result.outputs[0];
+    _dashboardJs =
+      result.success && out ? await out.text() : "/* [Zerotal DevTools] dashboard build failed */";
+  } catch (error) {
+    _dashboardJs = `/* [Zerotal DevTools] dashboard build error: ${String(error)} */`;
+  }
+  return _dashboardJs;
+}
+
+export interface DevtoolsInjectionOptions {
+  // reserved for future use
+}
+
+// ── SSE subscribers ───────────────────────────────────────────────────────────
+
+const _sseClients = new Set<ReadableStreamDefaultController<Uint8Array>>();
+const _enc = new TextEncoder();
+
+function _ssePublish(data: unknown): void {
+  if (_sseClients.size === 0) return;
+  const chunk = _enc.encode(`data: ${JSON.stringify(data)}\n\n`);
+  for (const ctrl of _sseClients) {
+    try {
+      ctrl.enqueue(chunk);
+    } catch {
+      _sseClients.delete(ctrl);
+    }
+  }
+}
+
+/**
+ * Bridge the trace store to connected panels. Called by {@link DevtoolsProvider}
+ * on boot rather than at module scope — subscribing on import would tie the
+ * stream to whichever store existed at import time, before the provider has
+ * built the one the app's config asks for.
+ *
+ * @returns A disposer that unsubscribes and drops connected clients.
+ */
+export function startDevtoolsStream(): () => void {
+  const unsubscribe = traceStore().subscribe((trace) => {
+    if (trace === null) _ssePublish({ type: "clear" });
+    else _ssePublish({ type: "trace", data: trace });
+  });
+  return () => {
+    unsubscribe();
+    _sseClients.clear();
+  };
+}
+
+// ── Middleware — devtools API routes only ─────────────────────────────────────
+//
+// All request tracing is handled by tracing.ts subscribing to FrameworkEvents.
+// This middleware only serves the devtools panel endpoints.
+
+export class DevtoolsInjectionMiddleware extends BaseMiddleware<DevtoolsInjectionOptions> {
+  protected options: DevtoolsInjectionOptions = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const { pathname } = http.url;
+
+    if (pathname === "/__zerotal/devtools/api/traces") {
+      return Response.json(traceStore().all());
+    }
+
+    if (pathname === "/__zerotal/devtools/api/channels") {
+      return Response.json(traceChannels());
+    }
+
+    if (pathname === "/__zerotal/devtools/api/clear" && http.request.method === "POST") {
+      traceStore().clear();
+      return new Response(null, { status: 204 });
+    }
+
+    if (pathname === "/__zerotal/devtools/sse") {
+      let ctrl!: ReadableStreamDefaultController<Uint8Array>;
+      const stream = new ReadableStream<Uint8Array>({
+        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.
+          ctrl.enqueue(
+            _enc.encode(
+              `data: ${JSON.stringify({
+                type: "history",
+                data: traceStore().all(),
+                channels: traceChannels(),
+              })}\n\n`,
+            ),
+          );
+        },
+        cancel() {
+          _sseClients.delete(ctrl);
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+          "X-Accel-Buffering": "no",
+        },
+      });
+    }
+
+    if (pathname === "/__zerotal/devtools/client.js") {
+      return new Response(await _buildClientJs(), {
+        headers: {
+          "Content-Type": "text/javascript; charset=utf-8",
+          "Cache-Control": "no-cache",
+        },
+      });
+    }
+
+    if (pathname === "/__zerotal/devtools/dashboard.js") {
+      return new Response(await _buildDashboardJs(), {
+        headers: {
+          "Content-Type": "text/javascript; charset=utf-8",
+          "Cache-Control": "no-cache",
+        },
+      });
+    }
+
+    if (pathname === "/__zerotal/devtools" || pathname === "/__zerotal/devtools/") {
+      const html = await Bun.file(new URL("./panel.html", import.meta.url)).text();
+      return new Response(html, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+
+    return next();
+  }
+}

package/src/RequestTrace.ts

@@ -0,0 +1,148 @@
+export interface QuerySpan {
+  sql: string;
+  bindings: unknown[];
+  startMs: number;
+  durationMs: number;
+  rowCount: number;
+}
+
+export interface NPlusOneWarning {
+  sql: string;
+  count: number;
+}
+
+export interface RouteInfo {
+  pattern: string;
+  controller: string;
+  action: string;
+}
+
+export interface AuthInfo {
+  id: unknown;
+  name?: unknown;
+  email?: unknown;
+}
+
+export interface LogEntry {
+  level: "log" | "debug" | "info" | "warn" | "error";
+  args: string[];
+  offsetMs: number;
+}
+
+export interface MailEntry {
+  /** Mailable class name (e.g. "WelcomeMail") */
+  className: string;
+  to: string[];
+  subject: string;
+  /** Rendered HTML — used for the mail preview panel */
+  html: string;
+  durationMs: number;
+  queued: boolean;
+  offsetMs: number;
+}
+
+export interface CacheEntry {
+  op: "has" | "hit" | "miss" | "write" | "forget" | "flush";
+  key: string;
+  ttl?: number | undefined;
+  durationMs: number;
+  offsetMs: number;
+}
+
+export interface JobEntry {
+  className: string;
+  queue: string;
+  status: "dispatched" | "completed" | "failed";
+  durationMs: number;
+  error?: string;
+  offsetMs: number;
+}
+
+// ── Open channels ─────────────────────────────────────────────────────────────
+
+/**
+ * One entry on an open {@link TraceChannelDescriptor | channel}.
+ *
+ * The shape is deliberately a bare record: devtools does not know what a
+ * channel carries, only how its descriptor says to display it. `offsetMs` is
+ * stamped by devtools when the entry is recorded.
+ */
+export interface TraceChannelEntry extends Record<string, unknown> {
+  /** Milliseconds from the start of the request. Stamped on record. */
+  offsetMs: number;
+}
+
+/**
+ * How a package's channel is displayed in the panel.
+ *
+ * The descriptor crosses the wire to the browser, so it names *fields* rather
+ * than carrying formatter functions — a channel is declared once on the server
+ * and rendered generically, which is what lets a package add a tab without
+ * devtools shipping a renderer for it.
+ *
+ * @example
+ * trace.channel({
+ *   id: "auth",
+ *   label: "Auth",
+ *   badge: "event",
+ *   title: "detail",
+ *   meta: ["guard", "ip"],
+ *   warn: "failed",
+ * });
+ */
+export interface TraceChannelDescriptor {
+  /** Unique id — also the key under {@link RequestTrace.channels}. */
+  id: string;
+  /** Tab label in the panel. */
+  label: string;
+  /** Entry field rendered as the row's leading badge. */
+  badge?: string;
+  /** Entry field rendered as the row's main text. Defaults to the badge field. */
+  title?: string;
+  /** Entry fields rendered as dim metadata beneath the title. */
+  meta?: string[];
+  /** Entry field whose truthiness marks the row — and the tab's badge — as a warning. */
+  warn?: string;
+  /** Sort order among channel tabs. Lower sorts first. Defaults to 100. */
+  order?: number;
+}
+
+export interface RequestTrace {
+  id: string;
+  requestId: string;
+  method: string;
+  path: string;
+  statusCode: number;
+  startMs: number;
+  durationMs: number;
+  queries: QuerySpan[];
+  warnings: NPlusOneWarning[];
+  /** Heap memory used at the end of the request, in bytes */
+  memory: number;
+  /** URL query string parameters */
+  queryParams: Record<string, string>;
+  /** Filtered request headers (no auth/cookie values) */
+  headers: Record<string, 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[];
+  /** Emails sent (or queued) during this request */
+  mail: MailEntry[];
+  /** Cache operations performed during this request */
+  cache: CacheEntry[];
+  /** Jobs dispatched (or processed synchronously) during this request */
+  jobs: JobEntry[];
+  /**
+   * Entries recorded on open channels, keyed by channel id.
+   *
+   * The fields above are the five signals devtools renders with bespoke UI they
+   * have earned — a query needs its bindings and duration bar, mail needs its
+   * preview. Everything else a package wants to show lands here and is rendered
+   * from its {@link TraceChannelDescriptor}, so contributing a tab takes no
+   * change inside devtools.
+   */
+  channels: Record<string, TraceChannelEntry[]>;
+}