@piwitests/instrumentation-nitro 0.21.0

package/README.md

@@ -0,0 +1,93 @@
+# @piwitests/instrumentation-nitro
+
+Nitro / Nuxt server plugin for [Piwi Dashboard](https://piwitests.github.io) — captures Warning and Error log entries per HTTP request and delivers them to the Piwi Dashboard reporter via the `X-Piwi-Logs` response header.
+
+During a Playwright test run, the reporter reads this header from every response and stores the entries alongside the network request. The entries are then available in the Piwi Dashboard test-case view and are included in the AI diagnosis context.
+
+**Active outside production by default.** Capture is controlled by the `PIWI_TEST_LOGS_DISABLED` environment variable:
+
+- unset — capture is on, except when `NODE_ENV === 'production'`
+- `PIWI_TEST_LOGS_DISABLED=true` — capture is off everywhere
+- `PIWI_TEST_LOGS_DISABLED=false` — capture is on even in production builds (useful for a production-mode test deployment)
+
+## Installation
+
+```bash
+npm install @piwitests/instrumentation-nitro
+```
+
+## Usage
+
+Create a file in your project's server plugins directory:
+
+```typescript
+// Nuxt: server/plugins/piwi-test-logs.ts
+// Standalone Nitro: plugins/piwi-test-logs.ts
+export { default } from '@piwitests/instrumentation-nitro'
+```
+
+That's all. Nitro auto-loads every file in that directory on startup (`server/plugins/` in a Nuxt app, `plugins/` under the Nitro `srcDir` in a standalone Nitro app).
+
+A runnable end-to-end demo lives in [`examples/playwright-fixtures`](../../examples/playwright-fixtures) — a standalone Nitro app instrumented with this package, with a Playwright spec showing the captured logs in the dashboard.
+
+## What gets captured
+
+| Source                               | What is captured                               |
+|--------------------------------------|------------------------------------------------|
+| `consola.warn()` / `consola.error()` | Warning and Error entries logged via consola   |
+| Unhandled H3/Nitro errors            | Errors thrown in route handlers and middleware |
+
+> Only calls made through **consola** are captured — bare `console.warn()` / `console.error()` output is not. Nuxt server code typically logs via consola already; in a standalone Nitro app, `import { consola } from 'consola'` in your handlers.
+
+Each captured entry contains:
+
+| Field       | Description                                                                          |
+|-------------|--------------------------------------------------------------------------------------|
+| `timestamp` | Unix timestamp in milliseconds                                                       |
+| `level`     | `"Warning"` or `"Error"`                                                             |
+| `category`  | Logger tag/category (e.g. `"database"`)                                              |
+| `message`   | Log message (truncated at 500 characters)                                            |
+| `stack`     | Shrunk stack trace when an `Error` was logged (max 5 frames, internal frames dropped) |
+
+Up to 50 entries per request are included. The header is always emitted (with an empty array when no entries were captured) so the Piwi reporter can confirm the plugin is active.
+
+## How it works
+
+```
+Playwright test
+  └─ page.goto('/api/orders')
+       └─ Nitro route handler runs
+            ├─ consola.warn('Stock low')     ← captured via consola reporter
+            └─ HTTP response
+                 └─ X-Piwi-Logs: <gzip+base64 JSON>
+                      └─ Piwi reporter reads header
+                           └─ stored as serverLogs on the network request
+                                └─ visible in test-case detail + AI diagnosis
+```
+
+The plugin wraps Nitro's root H3 handler and uses three mechanisms:
+
+1. **`event.context._piwiLogs`** — a plain per-request array attached to the H3 event as the wrapped handler starts; everything captured for the request accumulates here.
+2. **`AsyncLocalStorage.run()`** — scopes that buffer around the entire downstream chain (hooks, middleware, route handlers), so the process-global `consola` reporter always appends to the correct request's buffer.
+3. **A patched `res.end`** — the header is written just before the response goes out, which covers **every** response, including H3 error responses that bypass Nitro's `beforeResponse` hook. Right before writing, unhandled errors are drained from `event.context.nitro.errors`, so thrown errors appear even when nothing logged via consola.
+
+## Peer dependencies
+
+| Package     | Version   |
+|-------------|-----------|
+| `nitropack` | `>=2.0.0` |
+| `h3`        | `>=1.0.0` |
+| `consola`   | `>=3.0.0` |
+
+These are already installed in any Nuxt project — no extra installs needed.
+
+## Building from source
+
+```bash
+cd integrations/nitro
+npm run build   # emits dist/index.js + dist/index.d.ts
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import type { NitroAppPlugin } from 'nitropack';
+export interface PiwiTestLogEntry {
+    timestamp: number;
+    level: string;
+    category: string;
+    message: string;
+    stack?: string;
+}
+/**
+ * A server-side span for the in-flight request. Rides back to the Piwi reporter
+ * in the `X-Piwi-Trace` response header (gzip+base64 JSON array) and is shown in
+ * the dashboard next to the network request that produced it. The plugin always
+ * emits a root request span; application code can contribute child spans with
+ * `recordServerSpan` (e.g. a DB query, a downstream call).
+ */
+export interface PiwiServerSpan {
+    /** Unique span id (hex). */
+    id: string;
+    /** Parent span id — child spans nest under the request's root span. */
+    parentId?: string;
+    /** Operation name, e.g. the route or a DB query label. */
+    name: string;
+    /** Coarse kind hint for display/color, e.g. 'server', 'db', 'client', 'internal'. */
+    kind?: string;
+    /** Start time, Unix epoch milliseconds. */
+    startMs: number;
+    /** Duration in milliseconds. */
+    durMs: number;
+    /** Outcome. */
+    status?: 'ok' | 'error';
+    /** Shared W3C trace id for the request (set on the root span). */
+    traceId?: string;
+    /** Small free-form attribute bag. */
+    attrs?: Record<string, string | number | boolean>;
+}
+/**
+ * Record a server-side span for the in-flight request. Shows up in the Piwi
+ * Dashboard test-case view (and AI diagnosis) under the request's root span.
+ * No-op outside a request scope or once the per-request span cap is reached.
+ */
+export declare function recordServerSpan(span: PiwiServerSpan): void;
+declare const piwiTestLogs: NitroAppPlugin;
+export default piwiTestLogs;

package/dist/index.js

@@ -0,0 +1,151 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+import { consola } from 'consola';
+const MAX_ENTRIES = 50;
+const MAX_MSG_LENGTH = 500;
+const MAX_STACK_FRAMES = 5;
+const MAX_SPANS = 100;
+/** Parse and shrink a JS/TS stack trace: skip internal/node_modules frames, keep max 5. */
+function shrinkStack(stack) {
+    if (!stack)
+        return undefined;
+    const lines = stack.split('\n');
+    const frames = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('at '))
+            continue; // skip error message line
+        if (trimmed.includes('node:internal') || trimmed.includes('node_modules'))
+            continue;
+        if (frames.length >= MAX_STACK_FRAMES)
+            break;
+        frames.push(trimmed.slice(3).trim());
+    }
+    return frames.length > 0 ? frames.join('\n') : undefined;
+}
+/** Extract stack from an unknown error value, shrunk, or undefined. */
+function extractStack(err) {
+    if (err instanceof Error && err.stack)
+        return shrinkStack(err.stack);
+    return undefined;
+}
+/** Pull the 32-hex trace-id out of a W3C `traceparent` header, if valid. */
+function parseTraceparent(tp) {
+    const value = Array.isArray(tp) ? tp[0] : tp;
+    if (!value)
+        return undefined;
+    const parts = value.split('-');
+    if (parts.length >= 3 && parts[1] && /^[0-9a-f]{32}$/i.test(parts[1]))
+        return parts[1];
+    return undefined;
+}
+// Links consola calls and recorded spans to the request being handled. The store
+// is scoped with als.run() around the whole downstream handler chain —
+// enterWith() from a request hook is not reliable here (the binding dies with
+// the hook's own async scope, so only the first request after boot would capture).
+const als = new AsyncLocalStorage();
+/**
+ * Record a server-side span for the in-flight request. Shows up in the Piwi
+ * Dashboard test-case view (and AI diagnosis) under the request's root span.
+ * No-op outside a request scope or once the per-request span cap is reached.
+ */
+export function recordServerSpan(span) {
+    const store = als.getStore();
+    if (!store || store.spans.length >= MAX_SPANS)
+        return;
+    store.spans.push(span);
+}
+// The consola reporter is process-global — register it only once.
+let reporterAdded = false;
+const TEST_LOGS_DISABLED = process.env.PIWI_TEST_LOGS_DISABLED === 'true' ||
+    (process.env.NODE_ENV === 'production' && process.env.PIWI_TEST_LOGS_DISABLED !== 'false');
+const piwiTestLogs = (nitroApp) => {
+    if (TEST_LOGS_DISABLED)
+        return;
+    if (!reporterAdded) {
+        reporterAdded = true;
+        consola.addReporter({
+            log(logObj) {
+                if (logObj.level > 1)
+                    return; // Warning (1) and Error/Fatal (0) only
+                const store = als.getStore();
+                if (!store)
+                    return;
+                const msg = logObj.args.map(String).join(' ');
+                const stack = logObj.args.map(extractStack).find(Boolean);
+                store.logs.push({
+                    timestamp: Date.now(),
+                    level: logObj.level <= 0 ? 'Error' : 'Warning',
+                    category: logObj.tag ?? '',
+                    message: msg.length > MAX_MSG_LENGTH ? `${msg.slice(0, MAX_MSG_LENGTH)}…` : msg,
+                    stack,
+                });
+            },
+        });
+    }
+    // Wrap the root h3 handler: both the node listener (dev and node-server
+    // production entries) and route dispatch go through h3App.handler, so the
+    // als.run() scope covers every hook, middleware, and route handler.
+    const originalHandler = nitroApp.h3App.handler;
+    nitroApp.h3App.handler = ((event) => {
+        const store = { logs: [], spans: [], startMs: Date.now() };
+        event.context._piwiLogs = store.logs;
+        event.context._piwiSpans = store.spans;
+        // Patch res.end so the X-Piwi-Logs / X-Piwi-Trace headers are injected for
+        // ALL responses, including H3 error responses where Nitro bypasses the
+        // 'beforeResponse' hook (h3 skips onBeforeResponse once the error handler
+        // has called res.end).
+        const res = event.node.res;
+        const originalEnd = res.end.bind(res);
+        res.end = (...args) => {
+            if (!res.headersSent) {
+                // Collect any unhandled H3/Nitro errors — they are synchronously pushed
+                // to event.context.nitro.errors before errorHandler runs, so they're
+                // always available here even for error responses.
+                const nitroErrors = event.context.nitro?.errors;
+                if (nitroErrors?.length) {
+                    for (const { error } of nitroErrors) {
+                        const msg = error instanceof Error ? (error.message || String(error)) : String(error);
+                        store.logs.push({
+                            timestamp: Date.now(),
+                            level: 'Error',
+                            category: 'server',
+                            message: msg.length > MAX_MSG_LENGTH ? `${msg.slice(0, MAX_MSG_LENGTH)}…` : msg,
+                            stack: extractStack(error),
+                        });
+                    }
+                }
+                const logPayload = store.logs.length > MAX_ENTRIES ? store.logs.slice(0, MAX_ENTRIES) : store.logs;
+                res.setHeader('X-Piwi-Logs', gzipSync(Buffer.from(JSON.stringify(logPayload))).toString('base64'));
+                // Synthesize the root request span (server-side processing time, route,
+                // status), correlate any app-recorded child spans under it, and ship the
+                // whole tree. When the caller sent a W3C traceparent, reuse its trace id
+                // so the spans line up with an external tracing backend.
+                const endMs = Date.now();
+                const method = String(event.method ?? event.node.req.method ?? 'GET');
+                const path = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
+                const statusCode = Number(res.statusCode) || 0;
+                const traceId = parseTraceparent(event.node.req.headers['traceparent']) ?? randomBytes(16).toString('hex');
+                const rootSpan = {
+                    id: randomBytes(8).toString('hex'),
+                    name: `${method} ${path}`.trim(),
+                    kind: 'server',
+                    startMs: store.startMs,
+                    durMs: Math.max(0, endMs - store.startMs),
+                    status: statusCode >= 500 ? 'error' : 'ok',
+                    traceId,
+                    attrs: { 'http.method': method, 'http.route': path, 'http.status_code': statusCode },
+                };
+                for (const s of store.spans)
+                    if (!s.parentId)
+                        s.parentId = rootSpan.id;
+                const spanPayload = [rootSpan, ...store.spans].slice(0, MAX_SPANS);
+                res.setHeader('X-Piwi-Trace', gzipSync(Buffer.from(JSON.stringify(spanPayload))).toString('base64'));
+            }
+            return originalEnd(...args);
+        };
+        return als.run(store, () => originalHandler(event));
+    });
+};
+export default piwiTestLogs;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@piwitests/instrumentation-nitro",
+  "version": "0.21.0",
+  "description": "Nitro/Nuxt server plugin for sending backend logs to Piwi Dashboard via the X-Piwi-Logs response header",
+  "homepage": "https://piwitests.github.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PiwiTests/platform"
+  },
+  "bugs": {
+    "url": "https://github.com/PiwiTests/platform/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "nitro",
+    "nuxt",
+    "playwright",
+    "piwi-dashboard",
+    "server-logs",
+    "test-results"
+  ],
+  "author": "piwitests",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/"
+  ],
+  "peerDependencies": {
+    "consola": ">=3.0.0",
+    "h3": ">=1.0.0",
+    "nitropack": ">=2.0.0"
+  }
+}