@warlock.js/devtools 5.25.0

package/esm/types.d.mts

@@ -0,0 +1,213 @@
+//#region ../devtools/src/types.d.ts
+/**
+ * The records the devtools collector keeps and the dashboard API returns.
+ *
+ * Every timestamp is epoch milliseconds (fractional allowed); every duration
+ * is milliseconds. Nothing here is persisted — the collector is an in-memory
+ * ring buffer that is lost on restart.
+ */
+/** Options accepted by `devtoolsConnector()`. */
+type DevtoolsOptions = {
+  /**
+   * URL prefix the dashboard and its API are served under.
+   *
+   * @default "/__warlock"
+   */
+  path?: string;
+  /**
+   * How many requests the ring buffer keeps; the oldest is evicted first.
+   *
+   * @default 200
+   */
+  maxRequests?: number;
+  /**
+   * How many times one query shape may run inside a single request before it
+   * is reported as an N+1.
+   *
+   * @default 5
+   */
+  nPlusOneThreshold?: number;
+};
+/** `DevtoolsOptions` with every default applied. */
+type ResolvedDevtoolsOptions = Required<DevtoolsOptions>;
+/** A source file position, as shown next to an N+1 warning. */
+type DevtoolsCallerLocation = {
+  /** Absolute path, forward slashes. */file: string;
+  line: number;
+  column: number;
+};
+/** One timed phase of a request (router middleware, loader, render, …). */
+type DevtoolsPhase = {
+  name: string;
+  startedAt: number;
+  durationMs: number;
+  attrs?: Record<string, unknown>;
+};
+/** One database query, Postgres or Mongo. */
+type DevtoolsQuery = {
+  /** Unique within the collector. */id: string;
+  connection: string;
+  driver: "postgres" | "mongodb";
+  sql?: string; /** Redacted through the logger's redaction rules before storage. */
+  bindings?: unknown[];
+  collection?: string;
+  command?: string;
+  pipeline?: unknown;
+  startedAt: number;
+  durationMs: number;
+  rowCount?: number; /** The error message when the query failed. */
+  error?: string;
+  /**
+   * The query with its values stripped — SQL text without bindings, or the
+   * Mongo command with every leaf value replaced by `?`. Two queries with the
+   * same shape are "the same query" for N+1 detection.
+   */
+  shape: string; /** The first application frame that issued the query, when resolvable. */
+  caller?: DevtoolsCallerLocation;
+};
+/** One cache operation. */
+type DevtoolsCacheOperation = {
+  type: "hit" | "miss" | "set" | "removed" | "invalidated" | "flushed";
+  driver: string;
+  key?: string;
+  tags?: string[];
+  keys?: string[];
+  at: number;
+  durationMs?: number;
+};
+/** One log entry. */
+type DevtoolsLogEntry = {
+  level: "debug" | "info" | "warn" | "error" | "success";
+  module: string;
+  action: string;
+  message: string;
+  at: number; /** Redacted through the logger's redaction rules before storage. */
+  context?: unknown;
+};
+/** A mail captured in development (see core's `mailEvents.onCaptured`). */
+type DevtoolsMail = {
+  id: string;
+  requestId?: string;
+  capturedAt: number;
+  from?: string;
+  to: string[];
+  cc: string[];
+  bcc: string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  headers: Record<string, string>;
+  attachments: DevtoolsMailAttachment[];
+};
+/** Attachment metadata only — the bytes are never stored. */
+type DevtoolsMailAttachment = {
+  filename: string;
+  contentType?: string;
+  size?: number;
+};
+/** A problem devtools noticed about a request. */
+type DevtoolsWarning = {
+  type: "n+1";
+  message: string;
+  shape: string;
+  count: number;
+  caller?: DevtoolsCallerLocation;
+};
+/** Everything recorded for one HTTP request. */
+type DevtoolsRequest = {
+  /** The framework's `request.id`. */id: string;
+  method: string;
+  path: string; /** Matched route pattern, e.g. `/posts/:slug`. */
+  route?: string;
+  status?: number;
+  startedAt: number; /** Undefined while the request is still in flight. */
+  durationMs?: number;
+  error?: string;
+  phases: DevtoolsPhase[];
+  queries: DevtoolsQuery[];
+  cache: DevtoolsCacheOperation[];
+  logs: DevtoolsLogEntry[]; /** Ids of mails captured during this request (see `DevtoolsMail`). */
+  mails: string[];
+  warnings: DevtoolsWarning[];
+};
+/** The row the request list shows; `GET <path>/api/requests` returns these. */
+type DevtoolsRequestSummary = {
+  id: string;
+  method: string;
+  path: string;
+  route?: string;
+  status?: number;
+  startedAt: number;
+  durationMs?: number;
+  queryCount: number;
+  warningCount: number;
+};
+/** The row the mailbox list shows; `GET <path>/api/mails` returns these. */
+type DevtoolsMailSummary = {
+  id: string;
+  requestId?: string;
+  capturedAt: number;
+  to: string[];
+  subject: string;
+};
+/**
+ * Work that happened outside any request (boot, a scheduler tick, a queue
+ * job): kept separately so it never pollutes a request's timeline.
+ */
+type DevtoolsBackground = {
+  queries: DevtoolsQuery[];
+  cache: DevtoolsCacheOperation[];
+  logs: DevtoolsLogEntry[];
+};
+/** Server-sent events on `GET <path>/api/stream`. */
+type DevtoolsStreamEvent = {
+  type: "request";
+  data: DevtoolsRequestSummary;
+} | {
+  type: "mail";
+  data: DevtoolsMailSummary;
+} | {
+  type: "log";
+  data: DevtoolsLogEntry;
+};
+/** Unsubscribes a listener or detaches a source. */
+type DevtoolsDisposer = () => void;
+/**
+ * The in-memory store every source writes to and the dashboard API reads
+ * from. `requestId` is the framework's `request.id`; `undefined` means the
+ * work happened outside a request and goes to the background bucket.
+ */
+type DevtoolsCollector = {
+  startRequest(request: {
+    id: string;
+    method: string;
+    path: string;
+    route?: string;
+    startedAt: number;
+  }): void; /** Settles the request, runs N+1 detection and emits a `request` stream event. */
+  endRequest(id: string, result: {
+    status?: number;
+    durationMs: number;
+    error?: string;
+    route?: string;
+  }): void;
+  addPhase(requestId: string, phase: DevtoolsPhase): void; /** Computes `id` and `shape` itself. */
+  addQuery(requestId: string | undefined, query: Omit<DevtoolsQuery, "id" | "shape">): DevtoolsQuery;
+  addCacheOperation(requestId: string | undefined, operation: DevtoolsCacheOperation): void;
+  addLog(requestId: string | undefined, entry: DevtoolsLogEntry): void;
+  addMail(mail: DevtoolsMail): void;
+  listRequests(): DevtoolsRequestSummary[];
+  getRequest(id: string): DevtoolsRequest | undefined;
+  listMails(): DevtoolsMailSummary[];
+  getMail(id: string): DevtoolsMail | undefined;
+  listLogs(filter?: {
+    level?: DevtoolsLogEntry["level"];
+    module?: string;
+  }): DevtoolsLogEntry[];
+  getBackground(): DevtoolsBackground;
+  subscribe(listener: (event: DevtoolsStreamEvent) => void): DevtoolsDisposer;
+  clear(): void;
+};
+//#endregion
+export { DevtoolsBackground, DevtoolsCacheOperation, DevtoolsCallerLocation, DevtoolsCollector, DevtoolsDisposer, DevtoolsLogEntry, DevtoolsMail, DevtoolsMailAttachment, DevtoolsMailSummary, DevtoolsOptions, DevtoolsPhase, DevtoolsQuery, DevtoolsRequest, DevtoolsRequestSummary, DevtoolsStreamEvent, DevtoolsWarning, ResolvedDevtoolsOptions };
+//# sourceMappingURL=types.d.mts.map

package/esm/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../devtools/src/types.ts"],"mappings":"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"}

package/esm/ui-root.mjs

@@ -0,0 +1,40 @@
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+//#region ../devtools/src/ui-root.ts
+let cachedUiRoot;
+/** Whether `dir` is this package's root: it has `ui/index.html` beside a `package.json` named `@warlock.js/devtools`. */
+function isPackageRoot(dir) {
+	const indexHtml = path.join(dir, "ui", "index.html");
+	const packageJson = path.join(dir, "package.json");
+	if (!existsSync(indexHtml) || !existsSync(packageJson)) return false;
+	try {
+		return JSON.parse(readFileSync(packageJson, "utf8")).name === "@warlock.js/devtools";
+	} catch {
+		return false;
+	}
+}
+/**
+* Locate this package's `ui/` directory by walking up from the current
+* module's directory. Works from `src/` in development and from the built
+* `esm/`/`cjs/` output, since both sit beside `ui/` and `package.json` at
+* the package root.
+*/
+function resolveUiRoot() {
+	if (cachedUiRoot) return cachedUiRoot;
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	while (true) {
+		if (isPackageRoot(dir)) {
+			cachedUiRoot = path.join(dir, "ui");
+			return cachedUiRoot;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) throw new Error("Could not locate the devtools UI directory: no ancestor of this module has a ui/index.html beside a package.json named @warlock.js/devtools.");
+		dir = parent;
+	}
+}
+
+//#endregion
+export { resolveUiRoot };
+//# sourceMappingURL=ui-root.mjs.map

package/esm/ui-root.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-root.mjs","names":[],"sources":["../../../../../../devtools/src/ui-root.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nlet cachedUiRoot: string | undefined;\n\n/** Whether `dir` is this package's root: it has `ui/index.html` beside a `package.json` named `@warlock.js/devtools`. */\nfunction isPackageRoot(dir: string): boolean {\n  const indexHtml = path.join(dir, \"ui\", \"index.html\");\n  const packageJson = path.join(dir, \"package.json\");\n\n  if (!existsSync(indexHtml) || !existsSync(packageJson)) {\n    return false;\n  }\n\n  try {\n    const parsed = JSON.parse(readFileSync(packageJson, \"utf8\")) as { name?: string };\n    return parsed.name === \"@warlock.js/devtools\";\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Locate this package's `ui/` directory by walking up from the current\n * module's directory. Works from `src/` in development and from the built\n * `esm/`/`cjs/` output, since both sit beside `ui/` and `package.json` at\n * the package root.\n */\nexport function resolveUiRoot(): string {\n  if (cachedUiRoot) {\n    return cachedUiRoot;\n  }\n\n  let dir = path.dirname(fileURLToPath(import.meta.url));\n\n  while (true) {\n    if (isPackageRoot(dir)) {\n      cachedUiRoot = path.join(dir, \"ui\");\n      return cachedUiRoot;\n    }\n\n    const parent = path.dirname(dir);\n    if (parent === dir) {\n      throw new Error(\n        \"Could not locate the devtools UI directory: no ancestor of \" +\n          \"this module has a ui/index.html beside a package.json named \" +\n          \"@warlock.js/devtools.\",\n      );\n    }\n\n    dir = parent;\n  }\n}\n"],"mappings":";;;;;AAIA,IAAI;;AAGJ,SAAS,cAAc,KAAsB;CAC3C,MAAM,YAAY,KAAK,KAAK,KAAK,MAAM,YAAY;CACnD,MAAM,cAAc,KAAK,KAAK,KAAK,cAAc;CAEjD,IAAI,CAAC,WAAW,SAAS,KAAK,CAAC,WAAW,WAAW,GACnD,OAAO;CAGT,IAAI;EAEF,OADe,KAAK,MAAM,aAAa,aAAa,MAAM,CAC9C,CAAC,CAAC,SAAS;CACzB,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,gBAAwB;CACtC,IAAI,cACF,OAAO;CAGT,IAAI,MAAM,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC;CAErD,OAAO,MAAM;EACX,IAAI,cAAc,GAAG,GAAG;GACtB,eAAe,KAAK,KAAK,KAAK,IAAI;GAClC,OAAO;EACT;EAEA,MAAM,SAAS,KAAK,QAAQ,GAAG;EAC/B,IAAI,WAAW,KACb,MAAM,IAAI,MACR,8IAGF;EAGF,MAAM;CACR;AACF"}

package/llms-full.txt

@@ -0,0 +1,78 @@
+# Warlock Devtools — full skills
+
+> Package: `@warlock.js/devtools`
+
+> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/devtools/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
+
+## devtools-overview  `@warlock.js/devtools/devtools-overview/SKILL.md`
+
+---
+name: devtools-overview
+description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations and the route map. Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
+---
+
+# `@warlock.js/devtools` — overview
+
+A dashboard for **development only**, served by your own app at `/__warlock`.
+It shows what each request did: its timing waterfall, the queries it ran, the
+cache operations, the logs, and any mail it sent.
+
+## Install: one command, no config
+
+```bash
+warlock add devtools   # adds @warlock.js/devtools as a DEV dependency
+warlock dev            # open http://localhost:<port>/__warlock
+```
+
+There's nothing to register. `warlock dev` loads devtools automatically when
+the package is installed.
+
+**Do not** add `devtoolsConnector()` to `warlock.config.ts`. Devtools is a
+dev dependency, so a production install doesn't have it, and a config import
+of it would fail to resolve there.
+
+## Why it can't leak into production
+
+1. **It isn't installed there.** Production installs omit dev dependencies.
+2. **It refuses to run outside development.** If it's present anyway, it logs
+   one warning (`@warlock.js/devtools only runs in development; it is not mounted`)
+   and mounts nothing.
+3. **It only answers loopback clients.** Every dashboard and API route answers
+   404 unless the connection comes from `127.0.0.1` / `::1`. It checks the
+   socket address, not `X-Forwarded-For`, so a forwarded-for header can't
+   unlock it.
+
+## What each panel shows
+
+| Panel | What you see | Where it comes from |
+|---|---|---|
+| **Requests** | Each request with its status, duration and query count. Click one for a waterfall: router middleware, `page.middleware`, loaders, `page.cache` hit/miss, `render.shell`, `defer.settle`, with queries and cache ops placed on the same time axis. | core `registerTracingHooks()` |
+| **Queries** | SQL + bindings or the Mongo command, duration, rows, and an **Explain** button (Postgres `SELECT` only; runs `EXPLAIN (FORMAT JSON)`, never `ANALYZE`) | cascade `dataSourceRegistry.on("query")` |
+| **N+1** | `⚠ N+1: 12× "select … where post_id = $1" — src/app/posts/services/list-posts.service.ts:18`, shown on the request and printed in the terminal | same query shape ≥ 5 times in one request |
+| **Mail** | Every mail sent in development: headers, HTML (sandboxed) and text, attachment names | core `mailEvents.onCaptured()` |
+| **Logs** | Log entries per request, filterable by level and module | a logger channel |
+| **Cache** | hit / miss / set / removed / `invalidated` (tags, keys removed) | cache `cache.on(...)` |
+| **Routes** | Every HTTP route with its method, path, name and middleware | core router |
+
+Work outside a request (boot, scheduler ticks, queue jobs) goes to a separate
+background list, so it never clutters a request's timeline.
+
+## Options
+
+`warlock dev` uses the defaults: path `/__warlock`, the last 200 requests
+kept, and an N+1 threshold of 5. Everything lives in memory and is gone on
+restart.
+
+## Secrets
+
+Query bindings and log context go through the logger's redaction rules
+before they're stored. The data is still real request data, which is exactly
+why the dashboard is development-only and loopback-only.
+
+## Related
+
+- Building your own tooling on the same hooks: core `registerTracingHooks()`,
+  cascade `dataSourceRegistry.on("query")`, core `mailEvents.onCaptured()` and
+  the cache `invalidated` event are public APIs that also work without devtools.
+
+

package/llms.txt

@@ -0,0 +1,9 @@
+# Warlock Devtools
+
+> Package: `@warlock.js/devtools`
+
+> Development-only dashboard for Warlock.js apps at /__warlock: request timeline, queries with EXPLAIN, N+1 detection, dev mailbox, logs, cache operations and the route map. Refuses to run outside development.
+
+## Skills
+
+- [devtools-overview](@warlock.js/devtools/devtools-overview/SKILL.md): Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations and the route map. Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@warlock.js/devtools",
+  "description": "Development-only dashboard for Warlock.js apps at /__warlock: request timeline, queries with EXPLAIN, N+1 detection, dev mailbox, logs, cache operations and the route map. Refuses to run outside development.",
+  "warlock": {
+    "environment": "server"
+  },
+  "peerDependencies": {
+    "@warlock.js/cache": "5.25.0",
+    "@warlock.js/cascade": "5.25.0",
+    "@warlock.js/core": "5.25.0",
+    "@warlock.js/logger": "5.25.0"
+  },
+  "peerDependenciesMeta": {
+    "@warlock.js/cache": {
+      "optional": true
+    },
+    "@warlock.js/cascade": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/devtools"
+  },
+  "keywords": [
+    "warlock.js",
+    "devtools",
+    "debugging",
+    "profiler",
+    "n+1",
+    "timeline",
+    "mailbox"
+  ],
+  "author": "hassanzohdy",
+  "license": "MIT",
+  "version": "5.25.0",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./esm/index.d.mts",
+        "default": "./cjs/index.cjs"
+      }
+    }
+  }
+}

package/skills/devtools-overview/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: devtools-overview
+description: 'Development-only dashboard for Warlock.js apps at `/__warlock`: request timeline (router + page middleware, loaders, render, deferred values), every SQL/Mongo query with EXPLAIN, N+1 warnings naming the file and line, a dev mailbox, logs, cache operations and the route map. Use for: "why is this page slow", "which queries does this request run", "find N+1 queries", "see the email my app just sent in dev", "open the dashboard". Install with `warlock add devtools`; never registered in warlock.config.ts. Not this package: production monitoring/APM or OpenTelemetry export — use `http.tracing` hooks in @warlock.js/core; slow-query logging in production — subscribe to cascade `dataSourceRegistry.on("query")` yourself.'
+---
+
+# `@warlock.js/devtools` — overview
+
+A dashboard for **development only**, served by your own app at `/__warlock`.
+It shows what each request did: its timing waterfall, the queries it ran, the
+cache operations, the logs, and any mail it sent.
+
+## Install: one command, no config
+
+```bash
+warlock add devtools   # adds @warlock.js/devtools as a DEV dependency
+warlock dev            # open http://localhost:<port>/__warlock
+```
+
+There's nothing to register. `warlock dev` loads devtools automatically when
+the package is installed.
+
+**Do not** add `devtoolsConnector()` to `warlock.config.ts`. Devtools is a
+dev dependency, so a production install doesn't have it, and a config import
+of it would fail to resolve there.
+
+## Why it can't leak into production
+
+1. **It isn't installed there.** Production installs omit dev dependencies.
+2. **It refuses to run outside development.** If it's present anyway, it logs
+   one warning (`@warlock.js/devtools only runs in development; it is not mounted`)
+   and mounts nothing.
+3. **It only answers loopback clients.** Every dashboard and API route answers
+   404 unless the connection comes from `127.0.0.1` / `::1`. It checks the
+   socket address, not `X-Forwarded-For`, so a forwarded-for header can't
+   unlock it.
+
+## What each panel shows
+
+| Panel | What you see | Where it comes from |
+|---|---|---|
+| **Requests** | Each request with its status, duration and query count. Click one for a waterfall: router middleware, `page.middleware`, loaders, `page.cache` hit/miss, `render.shell`, `defer.settle`, with queries and cache ops placed on the same time axis. | core `registerTracingHooks()` |
+| **Queries** | SQL + bindings or the Mongo command, duration, rows, and an **Explain** button (Postgres `SELECT` only; runs `EXPLAIN (FORMAT JSON)`, never `ANALYZE`) | cascade `dataSourceRegistry.on("query")` |
+| **N+1** | `⚠ N+1: 12× "select … where post_id = $1" — src/app/posts/services/list-posts.service.ts:18`, shown on the request and printed in the terminal | same query shape ≥ 5 times in one request |
+| **Mail** | Every mail sent in development: headers, HTML (sandboxed) and text, attachment names | core `mailEvents.onCaptured()` |
+| **Logs** | Log entries per request, filterable by level and module | a logger channel |
+| **Cache** | hit / miss / set / removed / `invalidated` (tags, keys removed) | cache `cache.on(...)` |
+| **Routes** | Every HTTP route with its method, path, name and middleware | core router |
+
+Work outside a request (boot, scheduler ticks, queue jobs) goes to a separate
+background list, so it never clutters a request's timeline.
+
+## Options
+
+`warlock dev` uses the defaults: path `/__warlock`, the last 200 requests
+kept, and an N+1 threshold of 5. Everything lives in memory and is gone on
+restart.
+
+## Secrets
+
+Query bindings and log context go through the logger's redaction rules
+before they're stored. The data is still real request data, which is exactly
+why the dashboard is development-only and loopback-only.
+
+## Related
+
+- Building your own tooling on the same hooks: core `registerTracingHooks()`,
+  cascade `dataSourceRegistry.on("query")`, core `mailEvents.onCaptured()` and
+  the cache `invalidated` event are public APIs that also work without devtools.