@nifrajs/devtools 2.3.0 → 2.4.0

package/dist/index.d.ts

@@ -58,6 +58,17 @@ export interface DevToolsClientOptions {
  * When configuring `tracing()` yourself, register it before this plugin so DevTools attaches to
  * that request owner.
  */
+/** Query for a DevTools state snapshot: an optional `path` prefix and a most-recent-`limit`. */
+export interface DevToolsQuery {
+    readonly path?: string | undefined;
+    readonly limit?: number | undefined;
+}
+/**
+ * Filter a DevTools event buffer for a snapshot query - by `path` prefix and/or the most recent
+ * `limit`. Pure, so the `/state` endpoint and its tests (and the `nifra_inspect` MCP tool that reads
+ * that endpoint) share ONE definition of what a query returns.
+ */
+export declare function filterDevToolsEvents(events: readonly DevToolsEvent[], query?: DevToolsQuery): DevToolsEvent[];
 export declare function devtools(options?: DevToolsOptions | undefined): import("@nifrajs/core/server").NifraPlugin<import("@nifrajs/core/server").AnyServer, import("@nifrajs/core/server").AnyServer>;
 /**
  * Returns a self-contained JavaScript string that creates a floating DevTools

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,wDAAwD;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC1C,gGAAgG;IAChG,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACvD,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IACnF;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C;AAED,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAQD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,kIAmK7D;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAuGhF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,wDAAwD;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC1C,gGAAgG;IAChG,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACvD,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IACnF;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C;AAED,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAQD;;;;;GAKG;AACH,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,KAAK,GAAE,aAAkB,GACxB,aAAa,EAAE,CASjB;AAED,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,kIA2L7D;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAuGhF"}

package/dist/index.js

@@ -20,15 +20,26 @@ import { tracing, } from "@nifrajs/otel";
 // ---------------------------------------------------------------------------
 const encoder = new TextEncoder();
 /**
- * DevTools plugin. Its observation adapter projects the single request span into a
- * `DevToolsEvent`; its middleware only owns the secured SSE transport.
- * When configuring `tracing()` yourself, register it before this plugin so DevTools attaches to
- * that request owner.
+ * Filter a DevTools event buffer for a snapshot query - by `path` prefix and/or the most recent
+ * `limit`. Pure, so the `/state` endpoint and its tests (and the `nifra_inspect` MCP tool that reads
+ * that endpoint) share ONE definition of what a query returns.
  */
+export function filterDevToolsEvents(events, query = {}) {
+    const { path, limit } = query;
+    const matched = path !== undefined ? events.filter((event) => event.path.startsWith(path)) : [...events];
+    // `slice(Math.max(0, n - limit))`, not `slice(-limit)`: the latter returns the WHOLE array for
+    // limit 0 (`-0 === 0`) and mishandles a limit larger than the buffer. This clamps both.
+    return limit !== undefined && limit >= 0
+        ? matched.slice(Math.max(0, matched.length - limit))
+        : matched;
+}
 export function devtools(options) {
     const maxEvents = options?.maxEvents ?? 200;
     const maxConnections = Math.max(1, options?.maxConnections ?? 5);
     const endpoint = options?.path ?? "/_nifra/devtools";
+    // A one-shot JSON snapshot of the ring buffer, alongside the live SSE stream. The SSE path is for a
+    // human watching the overlay; this is for an agent that made a request and wants to READ what happened.
+    const statePath = `${endpoint}/state`;
     const enabled = options?.enabled ?? process.env.NODE_ENV === "development";
     const allowRemote = options?.allowRemote ?? false;
     const allowedOrigins = new Set(options?.allowedOrigins ?? []);
@@ -115,64 +126,81 @@ export function devtools(options) {
         return app.use(tracing({ adapters: [adapter] })).use({
             name: "devtools-stream",
             async onRequest(request) {
-                // Handle the SSE endpoint
                 const url = new URL(request.url);
-                if (url.pathname === endpoint) {
-                    const loopback = url.hostname === "localhost" ||
-                        url.hostname === "127.0.0.1" ||
-                        url.hostname === "[::1]" ||
-                        url.hostname.endsWith(".localhost");
-                    if (!allowRemote && !loopback) {
-                        return new Response("Nifra DevTools is restricted to loopback hosts", { status: 403 });
-                    }
-                    const origin = request.headers.get("origin");
-                    if (origin !== null && origin !== url.origin && !allowedOrigins.has(origin)) {
-                        return new Response("Origin not allowed", { status: 403 });
-                    }
-                    if (options?.authorize !== undefined && !(await options.authorize(request))) {
-                        return new Response("Unauthorized", { status: 401 });
-                    }
-                    if (controllers.size >= maxConnections) {
-                        return new Response("Too many DevTools connections", {
-                            status: 503,
-                            headers: { "retry-after": "5" },
-                        });
-                    }
-                    let activeController;
-                    const stream = new ReadableStream({
-                        start(controller) {
-                            activeController = controller;
-                            controllers.add(controller);
-                            startPing();
-                            // Send buffered events as initial payload
-                            for (const evt of buffer) {
-                                try {
-                                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(evt)}\n\n`));
-                                }
-                                catch {
-                                    break;
-                                }
-                            }
-                        },
-                        cancel() {
-                            if (activeController !== undefined)
-                                dropController(activeController);
-                        },
+                if (url.pathname !== endpoint && url.pathname !== statePath)
+                    return undefined;
+                // One access-control gate for BOTH the live stream and the one-shot snapshot: a read of the
+                // buffer exposes the same request data as watching it live, so it is guarded identically -
+                // loopback-only unless `allowRemote`, origin-checked, and an optional `authorize` hook.
+                const loopback = url.hostname === "localhost" ||
+                    url.hostname === "127.0.0.1" ||
+                    url.hostname === "[::1]" ||
+                    url.hostname.endsWith(".localhost");
+                if (!allowRemote && !loopback) {
+                    return new Response("Nifra DevTools is restricted to loopback hosts", { status: 403 });
+                }
+                const origin = request.headers.get("origin");
+                if (origin !== null && origin !== url.origin && !allowedOrigins.has(origin)) {
+                    return new Response("Origin not allowed", { status: 403 });
+                }
+                if (options?.authorize !== undefined && !(await options.authorize(request))) {
+                    return new Response("Unauthorized", { status: 401 });
+                }
+                // The snapshot: recent request traces as JSON, filtered by ?path= / ?limit=. This is the agent's
+                // read of "what did my requests actually do" - the one thing the live SSE stream can't answer.
+                if (url.pathname === statePath) {
+                    const limitRaw = url.searchParams.get("limit");
+                    const limit = limitRaw !== null && Number.isFinite(Number(limitRaw)) ? Number(limitRaw) : undefined;
+                    const events = filterDevToolsEvents(buffer, {
+                        path: url.searchParams.get("path") ?? undefined,
+                        limit,
                     });
-                    // Clean up dead controllers on cancel
-                    const response = new Response(stream, {
+                    return Response.json({ events }, {
                         headers: {
-                            "content-type": "text/event-stream",
                             "cache-control": "no-store",
-                            connection: "keep-alive",
-                            "content-security-policy": "default-src 'none'",
                             "x-content-type-options": "nosniff",
                             "x-nifra-devtools": "true",
                         },
                     });
-                    return response;
                 }
-                return undefined;
+                // The live SSE stream.
+                if (controllers.size >= maxConnections) {
+                    return new Response("Too many DevTools connections", {
+                        status: 503,
+                        headers: { "retry-after": "5" },
+                    });
+                }
+                let activeController;
+                const stream = new ReadableStream({
+                    start(controller) {
+                        activeController = controller;
+                        controllers.add(controller);
+                        startPing();
+                        // Send buffered events as the initial payload.
+                        for (const evt of buffer) {
+                            try {
+                                controller.enqueue(encoder.encode(`data: ${JSON.stringify(evt)}\n\n`));
+                            }
+                            catch {
+                                break;
+                            }
+                        }
+                    },
+                    cancel() {
+                        if (activeController !== undefined)
+                            dropController(activeController);
+                    },
+                });
+                return new Response(stream, {
+                    headers: {
+                        "content-type": "text/event-stream",
+                        "cache-control": "no-store",
+                        connection: "keep-alive",
+                        "content-security-policy": "default-src 'none'",
+                        "x-content-type-options": "nosniff",
+                        "x-nifra-devtools": "true",
+                    },
+                });
             },
             beforeHandle(context) {
                 ;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/devtools",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Interactive DevTools overlay for nifra dev - loader traces, ISR status, route metadata.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,10 +31,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/otel": "2.3.0"
+    "@nifrajs/otel": "2.4.0"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.3.0"
+    "@nifrajs/core": "^2.4.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/index.ts

@@ -80,10 +80,38 @@ const encoder = new TextEncoder()
  * When configuring `tracing()` yourself, register it before this plugin so DevTools attaches to
  * that request owner.
  */
+/** Query for a DevTools state snapshot: an optional `path` prefix and a most-recent-`limit`. */
+export interface DevToolsQuery {
+  readonly path?: string | undefined
+  readonly limit?: number | undefined
+}
+
+/**
+ * Filter a DevTools event buffer for a snapshot query - by `path` prefix and/or the most recent
+ * `limit`. Pure, so the `/state` endpoint and its tests (and the `nifra_inspect` MCP tool that reads
+ * that endpoint) share ONE definition of what a query returns.
+ */
+export function filterDevToolsEvents(
+  events: readonly DevToolsEvent[],
+  query: DevToolsQuery = {},
+): DevToolsEvent[] {
+  const { path, limit } = query
+  const matched =
+    path !== undefined ? events.filter((event) => event.path.startsWith(path)) : [...events]
+  // `slice(Math.max(0, n - limit))`, not `slice(-limit)`: the latter returns the WHOLE array for
+  // limit 0 (`-0 === 0`) and mishandles a limit larger than the buffer. This clamps both.
+  return limit !== undefined && limit >= 0
+    ? matched.slice(Math.max(0, matched.length - limit))
+    : matched
+}
+
 export function devtools(options?: DevToolsOptions | undefined) {
   const maxEvents = options?.maxEvents ?? 200
   const maxConnections = Math.max(1, options?.maxConnections ?? 5)
   const endpoint = options?.path ?? "/_nifra/devtools"
+  // A one-shot JSON snapshot of the ring buffer, alongside the live SSE stream. The SSE path is for a
+  // human watching the overlay; this is for an agent that made a request and wants to READ what happened.
+  const statePath = `${endpoint}/state`
   const enabled = options?.enabled ?? process.env.NODE_ENV === "development"
   const allowRemote = options?.allowRemote ?? false
   const allowedOrigins = new Set(options?.allowedOrigins ?? [])
@@ -172,67 +200,88 @@ export function devtools(options?: DevToolsOptions | undefined) {
       name: "devtools-stream",
 
       async onRequest(request: Request): Promise<Response | undefined> {
-        // Handle the SSE endpoint
         const url = new URL(request.url)
-        if (url.pathname === endpoint) {
-          const loopback =
-            url.hostname === "localhost" ||
-            url.hostname === "127.0.0.1" ||
-            url.hostname === "[::1]" ||
-            url.hostname.endsWith(".localhost")
-          if (!allowRemote && !loopback) {
-            return new Response("Nifra DevTools is restricted to loopback hosts", { status: 403 })
-          }
-          const origin = request.headers.get("origin")
-          if (origin !== null && origin !== url.origin && !allowedOrigins.has(origin)) {
-            return new Response("Origin not allowed", { status: 403 })
-          }
-          if (options?.authorize !== undefined && !(await options.authorize(request))) {
-            return new Response("Unauthorized", { status: 401 })
-          }
-          if (controllers.size >= maxConnections) {
-            return new Response("Too many DevTools connections", {
-              status: 503,
-              headers: { "retry-after": "5" },
-            })
-          }
-
-          let activeController: ReadableStreamDefaultController | undefined
-          const stream = new ReadableStream({
-            start(controller) {
-              activeController = controller
-              controllers.add(controller)
-              startPing()
-              // Send buffered events as initial payload
-              for (const evt of buffer) {
-                try {
-                  controller.enqueue(encoder.encode(`data: ${JSON.stringify(evt)}\n\n`))
-                } catch {
-                  break
-                }
-              }
-            },
-            cancel() {
-              if (activeController !== undefined) dropController(activeController)
-            },
-          })
+        if (url.pathname !== endpoint && url.pathname !== statePath) return undefined
+
+        // One access-control gate for BOTH the live stream and the one-shot snapshot: a read of the
+        // buffer exposes the same request data as watching it live, so it is guarded identically -
+        // loopback-only unless `allowRemote`, origin-checked, and an optional `authorize` hook.
+        const loopback =
+          url.hostname === "localhost" ||
+          url.hostname === "127.0.0.1" ||
+          url.hostname === "[::1]" ||
+          url.hostname.endsWith(".localhost")
+        if (!allowRemote && !loopback) {
+          return new Response("Nifra DevTools is restricted to loopback hosts", { status: 403 })
+        }
+        const origin = request.headers.get("origin")
+        if (origin !== null && origin !== url.origin && !allowedOrigins.has(origin)) {
+          return new Response("Origin not allowed", { status: 403 })
+        }
+        if (options?.authorize !== undefined && !(await options.authorize(request))) {
+          return new Response("Unauthorized", { status: 401 })
+        }
 
-          // Clean up dead controllers on cancel
-          const response = new Response(stream, {
-            headers: {
-              "content-type": "text/event-stream",
-              "cache-control": "no-store",
-              connection: "keep-alive",
-              "content-security-policy": "default-src 'none'",
-              "x-content-type-options": "nosniff",
-              "x-nifra-devtools": "true",
-            },
+        // The snapshot: recent request traces as JSON, filtered by ?path= / ?limit=. This is the agent's
+        // read of "what did my requests actually do" - the one thing the live SSE stream can't answer.
+        if (url.pathname === statePath) {
+          const limitRaw = url.searchParams.get("limit")
+          const limit =
+            limitRaw !== null && Number.isFinite(Number(limitRaw)) ? Number(limitRaw) : undefined
+          const events = filterDevToolsEvents(buffer, {
+            path: url.searchParams.get("path") ?? undefined,
+            limit,
           })
+          return Response.json(
+            { events },
+            {
+              headers: {
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                "x-nifra-devtools": "true",
+              },
+            },
+          )
+        }
 
-          return response
+        // The live SSE stream.
+        if (controllers.size >= maxConnections) {
+          return new Response("Too many DevTools connections", {
+            status: 503,
+            headers: { "retry-after": "5" },
+          })
         }
 
-        return undefined
+        let activeController: ReadableStreamDefaultController | undefined
+        const stream = new ReadableStream({
+          start(controller) {
+            activeController = controller
+            controllers.add(controller)
+            startPing()
+            // Send buffered events as the initial payload.
+            for (const evt of buffer) {
+              try {
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(evt)}\n\n`))
+              } catch {
+                break
+              }
+            }
+          },
+          cancel() {
+            if (activeController !== undefined) dropController(activeController)
+          },
+        })
+
+        return new Response(stream, {
+          headers: {
+            "content-type": "text/event-stream",
+            "cache-control": "no-store",
+            connection: "keep-alive",
+            "content-security-policy": "default-src 'none'",
+            "x-content-type-options": "nosniff",
+            "x-nifra-devtools": "true",
+          },
+        })
       },
 
       beforeHandle(context) {