@zerotal/devtools 1.0.0

package/src/provider/DevtoolsProvider.ts

@@ -0,0 +1,153 @@
+import {
+  ServiceProvider,
+  isDevSurfaceAllowed,
+  type AppEnvironment,
+  type HttpContext,
+} from "@zerotal/core";
+import { DevReloadMiddleware, registerDevHtmlSnippet } from "@zerotal/core/dev";
+import {
+  DevtoolsInjectionMiddleware,
+  startDevtoolsStream,
+} from "../DevtoolsInjectionMiddleware.ts";
+import { DevtoolsConfig, type DevtoolsConfigShape } from "../config.ts";
+import { TraceStore, _setTraceStore } from "../TraceStore.ts";
+import {
+  startDevtoolsTracing,
+  stopDevtoolsTracing,
+  startConsoleCapture,
+  stopConsoleCapture,
+  traceSink,
+  _resetChannels,
+  _setRedaction,
+  type TraceSink,
+} from "../tracing.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    "devtools.trace": TraceSink;
+  }
+}
+
+const PURPLE = "\x1b[35m";
+const CYAN = "\x1b[36m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+/**
+ * Activates Zerotal DevTools for web environments.
+ * No-op in production.
+ *
+ * Register in `bootstrap/app.ts`:
+ *
+ * ```typescript
+ * import { DevtoolsProvider } from '@zerotal/devtools';
+ *
+ * Application.create()
+ *   .register([DatabaseProvider, DevtoolsProvider])
+ * ```
+ *
+ * In development the floating panel is **auto-injected** into HTML responses —
+ * no `DevTools.start()` in your app bundle. (You can still import it manually
+ * from `@zerotal/devtools/client` if you prefer to control startup.)
+ *
+ * Routes served automatically:
+ *   GET  /__zerotal/devtools              standalone inspector dashboard
+ *   GET  /__zerotal/devtools/client.js    injected in-page panel bundle
+ *   GET  /__zerotal/devtools/sse          SSE stream (EventSource)
+ *   GET  /__zerotal/devtools/api/traces   recent request traces (JSON)
+ *   GET  /__zerotal/devtools/api/channels declared trace channels (JSON)
+ *   POST /__zerotal/devtools/api/clear    clear trace history
+ */
+export class DevtoolsProvider extends ServiceProvider {
+  // Deliberately empty: `devtools.trace` is only bound when the dev surface is
+  // allowed (fail-closed outside development), and every token in `provides` is
+  // a boot-doctor guarantee that must hold in every environment. Satellites
+  // detect the sink with `tryMake`, so its absence is a supported state.
+  static override provides = [] as const;
+  static override environments: AppEnvironment[] = ["web"];
+
+  /** Set once the provider has activated, so teardown only undoes what it did. */
+  private _active = false;
+  private _stopStream: (() => void) | null = null;
+
+  override async onBooting(): Promise<void> {
+    const env = Bun.env["APP_ENV"] ?? "";
+    // Fail closed: only activate for explicitly non-prod envs. An unset or
+    // `staging` APP_ENV must NOT expose the unauthenticated trace inspector.
+    if (!isDevSurfaceAllowed(env)) return;
+    this._active = true;
+
+    const config = this._config();
+
+    // The store is built here rather than at import time: opening a database
+    // from module scope would create `.zerotal/devtools.sqlite` in the working
+    // directory of every process that imports this package, production included.
+    _setTraceStore(
+      new TraceStore({
+        capacity: config.capacity,
+        dbPath: config.dbPath,
+        pruneHours: config.pruneHours,
+      }),
+    );
+    _setRedaction(config.redact);
+
+    // 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
+    // providers' onBooted run.
+    //
+    // `value`, not `singleton`: an unresolved singleton is invisible to the
+    // synchronous `tryMake` every satellite bridge uses to detect devtools, so
+    // registering it as a factory meant those bridges silently found nothing and
+    // no package's spans ever reached the panel in a real app.
+    this.app.container.value("devtools.trace", traceSink);
+
+    this.app.useOnce(DevtoolsInjectionMiddleware as never);
+
+    // Auto-inject the in-page panel into HTML responses via the core dev
+    // 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 as never);
+    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> {
+    if (!this._active) return;
+
+    // N+1 detection is owned by the ORM provider now (env-gated there), so
+    // devtools no longer imports @zerotal/orm — it only consumes FrameworkEvents.
+    startDevtoolsTracing();
+    startConsoleCapture();
+    this._stopStream = startDevtoolsStream();
+
+    process.stdout.write(
+      `  ${PURPLE}[Zerotal Inspector]${RESET} DevTools active\n` +
+        `  ${DIM}Panel${RESET}     → auto-injected into dev pages\n` +
+        `  ${DIM}Dashboard${RESET} → ${CYAN}/__zerotal/devtools${RESET}\n`,
+    );
+  }
+
+  async onStopping(): Promise<void> {
+    if (!this._active) return;
+    stopDevtoolsTracing();
+    stopConsoleCapture();
+    this._stopStream?.();
+    this._stopStream = null;
+    _resetChannels();
+    // 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);
+    this._active = false;
+  }
+
+  /** The app's `devtools` config, falling back to defaults when none is present. */
+  private _config(): DevtoolsConfigShape {
+    const config = this.app.container.tryMake("config");
+    const raw = config?.get<Partial<DevtoolsConfigShape>>("devtools");
+    return DevtoolsConfig(raw ?? {});
+  }
+}

package/src/redaction.ts

@@ -0,0 +1,208 @@
+/**
+ * Query-binding redaction.
+ *
+ * A trace does not stay on screen: it is streamed to the browser and written to
+ * `.zerotal/devtools.sqlite`, where it sits for a day. Bindings are the request's
+ * actual values — the password on a registration, a reset token, a session
+ * payload, every customer email a listing selects by. An ephemeral dev panel and
+ * a plaintext file with a day's worth of credentials in it are different risks,
+ * so the values are masked by default and you opt individual columns back in.
+ *
+ * Matching is on the column each binding belongs to, recovered by pairing the
+ * SQL's placeholders with the identifiers around them. When a binding cannot be
+ * attributed to a column — a raw expression, a dialect this does not parse — it
+ * is masked, because guessing wrong in the other direction is what writes a
+ * password to disk.
+ */
+
+export interface RedactionOptions {
+  /**
+   * Turn masking off entirely. Only reasonable when you are debugging the values
+   * themselves and nothing sensitive is in the database.
+   */
+  enabled?: boolean;
+  /**
+   * Column names whose values are safe to show in full. Matched
+   * case-insensitively against the column each binding belongs to.
+   */
+  allow?: string[];
+  /**
+   * Extra column names to mask, added to the built-in list.
+   */
+  deny?: string[];
+}
+
+/**
+ * Column names masked without being asked. Substring matches, so `password`
+ * covers `password_hash` and `user_password`.
+ */
+const SENSITIVE = [
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "api_key",
+  "apikey",
+  "authorization",
+  "auth",
+  "credential",
+  "private_key",
+  "session",
+  "remember_token",
+  "otp",
+  "two_factor",
+  "totp",
+  "recovery_code",
+  "signature",
+  "cvv",
+  "card_number",
+  "iban",
+  "ssn",
+  "id_number",
+];
+
+/** Columns always shown: structural values that make a trace readable at all. */
+const STRUCTURAL = ["id", "created_at", "updated_at", "deleted_at"];
+
+/** What a masked binding is replaced with. */
+const MASK = "‹redacted›";
+
+/**
+ * Mask the bindings of `sql` that belong to a sensitive column.
+ *
+ * @param sql - The statement the bindings belong to, used to attribute each one to a column.
+ * @param bindings - The values, positionally matched to the statement's placeholders.
+ * @param options - Redaction settings from the app's `devtools` config.
+ * @returns A new array; the input is not modified.
+ */
+export function redactBindings(
+  sql: string,
+  bindings: unknown[],
+  options: RedactionOptions = {},
+): unknown[] {
+  if (options.enabled === false) return bindings;
+  if (!Array.isArray(bindings) || bindings.length === 0) return bindings;
+
+  const allow = new Set((options.allow ?? []).map((c) => c.toLowerCase()));
+  const deny = [...SENSITIVE, ...(options.deny ?? []).map((c) => c.toLowerCase())];
+  const columns = attributeBindings(sql, bindings.length);
+
+  return bindings.map((value, i) => {
+    if (value === null || value === undefined) return value;
+    const column = columns[i];
+    // An unattributable binding is masked: a value we cannot name is a value we
+    // cannot clear.
+    if (!column) return MASK;
+    if (allow.has(column)) return value;
+    if (STRUCTURAL.includes(column)) return value;
+    return deny.some((s) => column.includes(s)) ? MASK : value;
+  });
+}
+
+/**
+ * Pair each `?` placeholder in `sql` with the column it sets or compares.
+ *
+ * Handles the three shapes the query builder emits: `INSERT … (cols) VALUES (?, …)`,
+ * `SET col = ?`, and `WHERE col <op> ?` (including `IN (?, ?)`, where every
+ * placeholder belongs to the same column). Returns `undefined` at any position it
+ * cannot attribute.
+ */
+export function attributeBindings(sql: string, count: number): Array<string | undefined> {
+  const out: Array<string | undefined> = new Array(count).fill(undefined);
+  if (count === 0) return out;
+
+  const insertColumns = _insertColumns(sql);
+  let index = 0;
+
+  // Walk the statement placeholder by placeholder, tracking the nearest
+  // identifier to the left of each one.
+  const tokens = sql.match(/"[^"]+"|`[^`]+`|\[[^\]]+\]|[A-Za-z_][\w.]*|\?|[(),=<>!]+/g) ?? [];
+  let lastIdentifier: string | undefined;
+  let inValues = false;
+  let valuesPosition = 0;
+
+  for (const raw of tokens) {
+    if (raw === "?") {
+      if (index >= count) break;
+      if (inValues && insertColumns) {
+        out[index] = insertColumns[valuesPosition];
+        valuesPosition++;
+      } else {
+        out[index] = lastIdentifier;
+      }
+      index++;
+      continue;
+    }
+    const token = raw.toLowerCase();
+    if (token === "values") {
+      inValues = true;
+      valuesPosition = 0;
+      continue;
+    }
+    if (/^[a-z_][\w.]*$/.test(token)) {
+      // An operator sits between a column and its placeholders and must leave the
+      // column attached — `WHERE id IN (?, ?)` belongs to `id` for both. Any other
+      // keyword ends that column's scope, so `AND`/`WHERE` cannot carry a stale
+      // column onto the next placeholder.
+      if (_OPERATORS.has(token)) continue;
+      if (_KEYWORDS.has(token)) {
+        lastIdentifier = undefined;
+        continue;
+      }
+      lastIdentifier = _bareColumn(token);
+    }
+  }
+
+  return out;
+}
+
+/** Keywords that sit between a column and its placeholders, leaving it in scope. */
+const _OPERATORS = new Set(["in", "like", "ilike", "between", "is", "not", "any", "all"]);
+
+const _KEYWORDS = new Set([
+  "select",
+  "from",
+  "where",
+  "and",
+  "or",
+  "insert",
+  "into",
+  "update",
+  "set",
+  "delete",
+  "values",
+  "limit",
+  "offset",
+  "order",
+  "group",
+  "by",
+  "having",
+  "join",
+  "left",
+  "right",
+  "inner",
+  "outer",
+  "on",
+  "as",
+
+  "null",
+  "returning",
+  "conflict",
+  "do",
+  "nothing",
+  "duplicate",
+  "key",
+]);
+
+/** `schema.table.column` / quoted identifiers → `column`. */
+function _bareColumn(identifier: string): string {
+  const parts = identifier.replace(/["`[\]]/g, "").split(".");
+  return (parts[parts.length - 1] ?? identifier).toLowerCase();
+}
+
+/** The column list of an `INSERT INTO t (a, b, c) VALUES …`, if this is one. */
+function _insertColumns(sql: string): string[] | null {
+  const match = /insert\s+(?:or\s+\w+\s+)?into\s+[^(]+\(([^)]*)\)\s*values/i.exec(sql);
+  if (!match?.[1]) return null;
+  return match[1].split(",").map((c) => _bareColumn(c.trim()));
+}