@flareapp/node 0.7.0 → 0.9.0

package/dist/index.mjs

@@ -1,57 +1,27 @@
-import { Api, DEFAULT_URL_DENYLIST, DEFAULT_URL_DENYLIST as DEFAULT_URL_DENYLIST$1, Flare, Flare as Flare$1, GlobalScopeProvider, Logger, NullFileReader, Scope, Scope as Scope$1, convertToError, redactUrlQuery, redactUrlQuery as redactUrlQuery$1, resolveDenylist } from "@flareapp/core";
+import { Api, DEFAULT_URL_DENYLIST, DEFAULT_URL_DENYLIST as DEFAULT_URL_DENYLIST$1, Flare, Flare as Flare$1, FrameworkName, GlobalScopeProvider, Logger, NullFileReader, Scope, Scope as Scope$1, convertToError, redactUrlQuery, redactUrlQuery as redactUrlQuery$1, resolveDenylist, urlAttributes } from "@flareapp/core";
 import os from "node:os";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 //#region src/context/body.ts
-/**
-* Content types accepted by default for body capture. JSON and
-* URL-encoded forms cover the vast majority of API payloads while keeping
-* the parser surface tiny. `\b` after the second alternative prevents
-* accidental matches like `application/x-www-form-urlencoded-foo` (artificial
-* but cheap to defend against). The leading `^` plus `\b` lets us match
-* either bare types or types with `; charset=utf-8` style suffixes.
-*/
+/** `^` plus `\b` accepts a `; charset=utf-8` suffix while still rejecting `...-urlencoded-foo`. */
 const DEFAULT_BODY_CONTENT_TYPES = /^application\/(json|x-www-form-urlencoded)\b/i;
-/**
-* Keys whose values get replaced with `[redacted]` during body redaction.
-* Reuses core's URL denylist so credentials, tokens, etc are caught with the
-* same regex everywhere (less surface for users to keep in sync).
-*/
+/** Reuses core's URL denylist, so credentials are caught by the same regex everywhere. */
 const DEFAULT_BODY_KEY_DENYLIST = DEFAULT_URL_DENYLIST$1;
 /**
-* Normalize, redact, serialize, and size-cap a request body for inclusion in
-* a Flare report.
-*
-* Accepts four runtime shapes (whatever the user hands us via
-* `runWithContext({ body, ... })`):
-*
-* - `string` — assumed to match the declared `contentType`. Must be JSON or
-*   form-encoded text per `bodyAllowedContentTypes`; otherwise dropped.
-* - `Buffer` — decoded as UTF-8 then treated like a string.
-* - `URLSearchParams` — flattened to a plain `Record<string, string>`. No
-*   content-type gate (the type is unambiguous from the shape).
-* - Other `object` (POJO, array) — used as-is, no content-type gate. This is
-*   the common middleware path (Express's `req.body`, Fastify's, etc).
-*
-* Anything else (`number`, `boolean`, class instance, stream) returns `null`
-* and the body is not reported.
-*
-* After parsing:
-*
-* 1. **Redact.** Walk the value, replacing any property whose key matches
-*    `bodyKeyDenylist` with `'[redacted]'`. Handles arrays, nested objects,
-*    and circular references (`WeakSet`-tracked, emits `'[Circular]'` on
-*    repeat sight).
-* 2. **Stringify.** `JSON.stringify`; if it throws (BigInt, Symbol, etc),
-*    drop the body entirely.
-* 3. **Truncate.** Cap at `bodyMaxBytes` UTF-8 bytes (the option's named
-*    semantic) INCLUDING the suffix. Truncation respects codepoint boundaries
-*    so the result decodes cleanly with no replacement characters.
-*
-* Returns the final JSON string, or `null` when the body should not be
-* reported (unknown shape, content-type miss, serialization failure).
+* Normalize, redact, serialize, and size-cap a request body for a Flare report. Returns the JSON string,
+* or `null` when the body should not be reported (unknown shape, content-type miss, serialization fail).
+*
+* Accepts four runtime shapes:
+* - `string`: must match `contentType` per `bodyAllowedContentTypes`, else dropped.
+* - `Buffer`: decoded UTF-8 then treated as a string.
+* - `URLSearchParams`: flattened to a plain record. No content-type gate (shape is unambiguous).
+* - Other `object`/array: used as-is, no gate. The common middleware path (Express/Fastify `req.body`).
+* Anything else returns `null`.
+*
+* Then: redact (denylisted keys become `'[redacted]'`, cycles become `'[Circular]'`), `JSON.stringify`
+* (drop body if it throws on BigInt/Symbol/etc), and truncate to `bodyMaxBytes` including the suffix.
 */
 function captureBody(body, contentType, opts) {
 	if (body === void 0 || body === null) return null;
@@ -78,15 +48,7 @@ function captureBody(body, contentType, opts) {
 }
 const TRUNCATION_SUFFIX = "…[truncated]";
 const TRUNCATION_SUFFIX_BYTES = Buffer.byteLength(TRUNCATION_SUFFIX, "utf8");
-/**
-* Truncate a serialized string so the resulting UTF-8 byte length never
-* exceeds `maxBytes`, including the appended truncation suffix.
-*
-* Walks backwards from the budget index while the byte at that position is a
-* UTF-8 continuation byte (`10xxxxxx`), stopping at the first byte that
-* starts a new codepoint. Slicing at that index leaves a buffer that decodes
-* cleanly with no replacement characters.
-*/
+/** Walks back over continuation bytes (`10xxxxxx`) to a codepoint boundary, so the result still decodes. */
 function truncateToByteLimit(serialized, maxBytes) {
 	const buf = Buffer.from(serialized, "utf8");
 	if (buf.length <= maxBytes) return serialized;
@@ -100,28 +62,15 @@ function truncateToByteLimit(serialized, maxBytes) {
 	while (cut > 0 && (buf[cut] & 192) === 128) cut--;
 	return buf.subarray(0, cut).toString("utf8") + TRUNCATION_SUFFIX;
 }
-/**
-* Check whether a `content-type` header is on the allowlist. Normalizes to the
-* bare media type first: strips any parameters (`; charset=utf-8`), trims, and
-* lowercases, so the regex is tested against `application/json` rather than the
-* full header. This lets a strict custom regex like `/^application\/json$/`
-* still match `application/json; charset=utf-8`. Empty/missing is a hard miss.
-*/
+/** Normalizes to the bare media type first, so a strict custom regex like `/^application\/json$/` still
+*  matches `application/json; charset=utf-8`. */
 function matchesContentType(ct, allowed) {
 	if (!ct) return false;
 	const mediaType = ct.split(";")[0].trim().toLowerCase();
 	if (!mediaType) return false;
 	return allowed.test(mediaType);
 }
-/**
-* Parse a serialized body string into a JS value, branching on the declared
-* content type.
-*
-* - URL-encoded forms become a flat object so the same `redact` walker works.
-* - Otherwise treat as JSON. Returns `undefined` (NOT `null`, which is a
-*   legitimate JSON value) when parsing fails, so the caller can distinguish
-*   "couldn't parse" from "parsed to literal null".
-*/
+/** Returns `undefined` rather than `null` on failure, since `null` is itself a valid JSON value. */
 function parseString(text, contentType) {
 	if (contentType && /x-www-form-urlencoded/i.test(contentType)) return Object.fromEntries(new URLSearchParams(text).entries());
 	try {
@@ -130,29 +79,13 @@ function parseString(text, contentType) {
 		return;
 	}
 }
-/**
-* True only for `Object.create(null)` or `{}`-shaped values. Excludes class
-* instances (their prototype chain points somewhere other than Object.prototype
-* or null), streams, FormData, ArrayBuffer views, Buffer, URLSearchParams,
-* and other built-ins that happen to be `typeof === 'object'`.
-*/
+/** Excludes class instances, streams, FormData, ArrayBuffer views, Buffer and URLSearchParams. */
 function isPlainObject(value) {
 	if (value === null || typeof value !== "object") return false;
 	const proto = Object.getPrototypeOf(value);
 	return proto === null || proto === Object.prototype;
 }
-/**
-* Recursively walk `value`, replacing values for denylisted keys with
-* `'[redacted]'` and substituting `'[Circular]'` for any object visited more
-* than once.
-*
-* `seen` is a `WeakSet` of already-visited objects. Carried as a parameter
-* (rather than a closure variable) so the same recursive call can pass it
-* down without per-call allocation.
-*
-* Primitives and `null` pass through unchanged. Arrays preserve order;
-* objects preserve keys.
-*/
+/** `seen` is a parameter rather than a closure to avoid allocating a WeakSet per recursion. */
 function redact(value, denylist, seen = /* @__PURE__ */ new WeakSet()) {
 	if (value === null || typeof value !== "object") return value;
 	if (seen.has(value)) return "[Circular]";
@@ -165,14 +98,9 @@ function redact(value, denylist, seen = /* @__PURE__ */ new WeakSet()) {
 
 //#endregion
 //#region src/context/headers.ts
-/**
-* Case-insensitively look up a header value. Returns the first defined value
-* for the lowercased name, or undefined. Array values (rare but valid for
-* some headers) are coalesced to the first element since the consumers in
-* this package treat the value as scalar.
-*/
+/** Case-insensitive. An array value collapses to its first element; callers here want a single value. */
 function findHeader(headers, name) {
-	if (!headers) return void 0;
+	if (!headers) return;
 	const target = name.toLowerCase();
 	for (const [key, value] of Object.entries(headers)) {
 		if (key.toLowerCase() !== target) continue;
@@ -180,55 +108,19 @@ function findHeader(headers, name) {
 		return Array.isArray(value) ? value[0] : value;
 	}
 }
-/**
-* Default-redacted header names. The pattern is anchored to the FULL header
-* name (`^...$`) and case-insensitive so it catches `Authorization`,
-* `AUTHORIZATION`, `authorization`, etc. Anchoring matters: an unanchored
-* `cookie` would match `X-Some-Cookie-Hint` too, which we do NOT want — only
-* the exact header by name should be redacted by default.
-*
-* Covers the usual credential carriers (`authorization`, `cookie`, etc) plus
-* common proxy-set headers that often expose client IPs (`forwarded`,
-* `x-forwarded-for`, `x-forwarded-user`). Users add domain-specific entries
-* via `configureNode({ headerDenylist: ... })`.
-*/
+/** The `^` and `$` matter: without them, `cookie` would also match a header like `X-Some-Cookie-Hint`. */
 const DEFAULT_HEADER_DENYLIST = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|x-csrf-token|x-xsrf-token|x-auth-token|forwarded|x-forwarded-(?:for|user))$/i;
-/**
-* Combine the built-in denylist with an optional user-supplied one.
-*
-* - No custom regex          -> use the default as-is.
-* - Custom + replace = true  -> use only the custom pattern (with `g`/`y`
-*                               flags stripped so `.test()` stays stateless).
-* - Custom + replace = false -> union: `(?:default)|(?:custom)`, forcing case
-*                               insensitivity since header names are
-*                               case-insensitive over the wire.
-*/
+/** `g`/`y` are stripped from a custom pattern: those carry lastIndex, which makes `.test()` stateful. */
 function resolveHeaderDenylist(custom, replaceDefault = false) {
 	if (!custom) return DEFAULT_HEADER_DENYLIST;
 	if (replaceDefault) return new RegExp(custom.source, custom.flags.replace(/[gy]/g, ""));
 	return new RegExp(`(?:${DEFAULT_HEADER_DENYLIST.source})|(?:${custom.source})`, "i");
 }
 /**
-* Project an HTTP request `headers` object into report attributes.
-*
-* Behavior per header:
-*
-* - **Unset values** (entry exists but the value is `undefined`) are dropped
-*   entirely — `node:http` represents "header was not sent" this way.
-* - **Names are lowercased.** OTel's attribute convention uses lowercase
-*   header keys, and HTTP header names are case-insensitive anyway.
-* - **Allowlist gate.** If `headerAllowlist` is set, only headers whose
-*   lowercased name matches are emitted; everything else is silently dropped
-*   (NOT redacted, dropped). This is the strongest filter — useful for
-*   compliance scenarios where you must opt into headers explicitly.
-* - **Array values** (`set-cookie` can be `string[]`) are joined with `, ` so
-*   the emitted value is a flat string, matching the on-the-wire shape that
-*   most HTTP clients render.
-* - **Denylist redaction.** If the name matches `headerDenylist`, the value
-*   is replaced with `'[redacted]'` (the key still appears so consumers can
-*   tell the header was present).
-*
-* Output keys are `http.request.header.<lowercased-name>`, per OTel.
+* Turns headers into `http.request.header.<name>` attributes. The two lists differ on purpose: an
+* allowlist drops a header entirely, for apps that may only send named headers, while the denylist
+* keeps the name and replaces the value, so you can still see the header was there. `undefined` is
+* how `node:http` says "not sent", so those are dropped.
 */
 function projectHeaders(headers, options) {
 	const out = {};
@@ -246,13 +138,9 @@ function projectHeaders(headers, options) {
 //#endregion
 //#region src/context/process.ts
 /**
-* Snapshot the Node runtime + host environment at report time and project
-* into OTel-style attribute keys. Cheap (just property reads + a couple of
-* syscalls via `os`), so called per-report rather than cached; this keeps
-* `process.uptime` honest and follows the value of `os.hostname()` if it
-* changes mid-run (unlikely but free correctness).
-*
-* Keys are stable OTel resource attributes; the Flare backend recognizes them.
+* Snapshot the Node runtime + host environment at report time as OTel resource attributes. Called
+* per-report rather than cached so `process.uptime()` stays accurate and `os.hostname()` tracks mid-run
+* changes; cheap enough (property reads plus a couple `os` syscalls).
 */
 function collectProcessAttributes() {
 	return {
@@ -270,29 +158,16 @@ function collectProcessAttributes() {
 //#endregion
 //#region src/context/collectNode.ts
 /**
-* Build the Node-side `ContextCollector` that core's `Flare` calls on every
-* report. The returned function projects two sources into OTel-style report
-* attributes:
-*
-* 1. **Process info** — runtime version, pid, hostname, etc. Always present.
-* 2. **Active request scope** — method, path/url (with query-string keys
-*    redacted), headers (with the denylist applied), and optional body. Present
-*    when `runWithContext(...)` is active; falls back to the shared scope
-*    otherwise (no request attrs emitted then). User identity is no longer
-*    projected here: `Flare.setUser` writes it straight to `pendingAttributes`.
-*
-* Both `provider` and `getOptions` are passed in (not captured by reference to
-* concrete instances) so the closure stays decoupled from `NodeFlare`'s
-* internals. `getOptions` is a getter (not a value) so that `configureNode(...)`
-* changes are visible on subsequent reports without rebuilding the collector.
+* Turns process info (always) and the active request scope (only inside `runWithContext`) into
+* OTel-style attributes. User identity is not handled here: `Flare.setUser` writes straight to
+* `pendingAttributes`.
 *
-* The function returned matches `ContextCollector = (config) => Attributes`,
-* which is core's interface for `Flare`'s third constructor parameter.
+* `getOptions` is a getter so `configureNode(...)` shows up on later reports without rebuilding this.
 */
 function makeNodeContextCollector(provider, getOptions) {
 	return (config) => {
 		const attrs = {
-			"flare.entry_point.type": "server",
+			"flare.entry_point.type": "web",
 			...collectProcessAttributes()
 		};
 		const { request } = provider.active();
@@ -307,7 +182,11 @@ function makeNodeContextCollector(provider, getOptions) {
 				attrs["url.query"] = redactedQuery.slice(redactedQueryStart + 1);
 			}
 		}
-		if (request.url) attrs["url.full"] = redactUrlQuery$1(request.url, config.urlDenylist);
+		if (request.url) {
+			const fromUrl = urlAttributes(request.url, config.urlDenylist);
+			attrs["url.full"] = fromUrl["url.full"];
+			if (fromUrl["url.scheme"] !== void 0) attrs["url.scheme"] = fromUrl["url.scheme"];
+		}
 		const opts = getOptions();
 		Object.assign(attrs, projectHeaders(request.headers, opts));
 		if (opts.captureRequestBody) {
@@ -361,41 +240,22 @@ function buildFatalCallbacks(flare, getOpts, exit = process.exit.bind(process))
 //#endregion
 //#region src/process/handlers.ts
 /**
-* Owns the lifecycle of the two process-level error listeners that capture
-* fatal failures and feed them to Flare:
-*
-* - `process.on('uncaughtException', ...)`
-* - `process.on('unhandledRejection', ...)`
-*
-* The manager has two responsibilities:
-*
-* 1. **Reconcile listener state with intent.** Given the current `FatalMode`
-*    for each event (`'off' | 'report' | 'report-and-exit'`), make the actual
-*    listener attachment match: attach when it should be attached but isn't,
-*    detach when it shouldn't be attached but is, no-op when already in the
-*    desired state. This is idempotent — calling `reconcile(...)` repeatedly
-*    with the same options is safe.
-* 2. **Tear down on demand.** `detach()` removes both listeners regardless of
-*    intent, for tests and graceful shutdown.
-*
-* Why keep this separate from `NodeFlare`: the attach/detach logic is purely
-* about Node `process` events and contains no Flare semantics. Isolating it
-* makes it trivial to test (the test suite drives `reconcile()` directly with
-* stub callbacks and asserts on `process.listeners(...)`) and keeps
-* `NodeFlare` focused on report assembly + user-facing API.
+* Owns the `uncaughtException` and `unhandledRejection` listeners that feed fatal failures to Flare.
+* Separate from `NodeFlare` because it is pure `process`-event plumbing with no Flare semantics, which
+* keeps it trivially testable.
+*
+* Deliberately kept separate from electron's ProcessHandlerManager, not a shared module. @flareapp/electron
+* does not depend on @flareapp/node, and the only package both import is @flareapp/core, which ships in
+* every browser bundle and touches `process` only behind a typeof guard. A shared manager belongs in a new
+* package, not in core, and one method does not pay for one.
 */
 var ProcessHandlerManager = class {
-	/** The currently-attached listener for `uncaughtException`, or `null`. */
 	uncaughtHandler = null;
-	/** The currently-attached listener for `unhandledRejection`, or `null`. */
 	rejectionHandler = null;
 	constructor(cbs) {
 		this.cbs = cbs;
 	}
-	/**
-	* Bring the attached listeners into agreement with the supplied modes.
-	* Idempotent: when current state already matches intent, this is a no-op.
-	*/
+	/** Idempotent: a no-op when the attached listeners already match the supplied modes. */
 	reconcile(opts) {
 		this.reconcileOne("uncaughtException", opts.uncaughtExceptionMode, () => this.uncaughtHandler, (h) => {
 			this.uncaughtHandler = h;
@@ -404,11 +264,7 @@ var ProcessHandlerManager = class {
 			this.rejectionHandler = h;
 		}, (reason) => this.cbs.onRejection(reason));
 	}
-	/**
-	* Remove both listeners regardless of current intent. Used by tests and by
-	* `NodeFlare.removeProcessListeners()`. Safe to call when nothing is
-	* attached.
-	*/
+	/** Remove both listeners regardless of intent. Safe when nothing is attached. */
 	detach() {
 		if (this.uncaughtHandler) {
 			process.off("uncaughtException", this.uncaughtHandler);
@@ -420,26 +276,21 @@ var ProcessHandlerManager = class {
 		}
 	}
 	/**
-	* Generic attach/detach for one event. The `get`/`set` closures let us
-	* share this body between the two events while still mutating distinct
-	* fields (`uncaughtHandler` vs `rejectionHandler`).
-	*
-	* Truth table:
-	* - intent off, currently attached -> detach
-	* - intent off, not attached       -> no-op
-	* - intent on,  currently attached -> no-op (already correct)
-	* - intent on,  not attached       -> attach
+	* Generic attach/detach for one event. The `get`/`set` closures share this body across both events
+	* while mutating distinct fields (`uncaughtHandler` vs `rejectionHandler`). Attaches when wanted and
+	* absent, detaches when unwanted and present, else no-op.
 	*/
 	reconcileOne(event, mode, get, set, impl) {
 		const current = get();
 		const wants = mode !== "off";
-		if (wants && !current) {
-			set(impl);
-			process.on(event, impl);
-		} else if (!wants && current) {
+		if (wants === (current !== null)) return;
+		if (!wants) {
 			process.off(event, current);
 			set(null);
+			return;
 		}
+		set(impl);
+		process.on(event, impl);
 	}
 };
 
@@ -452,66 +303,29 @@ var NodeScope = class extends Scope$1 {
 //#endregion
 //#region src/scope/AsyncLocalStorageScopeProvider.ts
 /**
-* `ScopeProvider` implementation that gives every in-flight request its own
-* `NodeScope`, isolated from concurrent requests.
-*
-* Built on Node's `node:async_hooks#AsyncLocalStorage`: when code runs inside
-* `als.run(scope, fn)`, every `als.getStore()` call from within `fn` (and any
-* async work `fn` awaits, including timers, promises, `process.nextTick`, etc)
-* returns that `scope`. Outside any `als.run` call, `getStore()` returns
-* `undefined`. This is the same primitive that lets observability libraries
-* propagate trace context across async boundaries without manual plumbing.
+* Gives every in-flight request its own `NodeScope`, isolated from concurrent requests.
 *
-* Two "kinds of read" surfaced separately:
-*
-* - `active()` — never returns null. The internal read used by `Flare` for
-*   every glow, attribute set, and report. When called inside `runWithContext`,
-*   returns the per-request `NodeScope`. Outside, returns a shared `fallback`
-*   scope so glows/attributes/reports issued outside any request still have
-*   somewhere to land (process-level reports, startup errors, scheduled jobs).
-* - `getContext()` — public debug helper. Returns `null` outside any
-*   `runWithContext`, so consumers can distinguish "I am inside a request" from
-*   "I am not". The fallback is intentionally NOT exposed here.
-*
-* The fallback is also a per-instance `NodeScope` so that writes from outside
-* a request scope persist for subsequent outside-scope reports.
+* The `fallback` scope catches work outside any request (process-level reports, startup errors,
+* scheduled jobs). It is per-instance rather than fresh per read, so outside-scope writes persist for a
+* later outside report.
 */
 var AsyncLocalStorageScopeProvider = class {
 	als = new AsyncLocalStorage();
 	fallback = new NodeScope();
-	/**
-	* Internal: returns the per-request scope when inside `runWithContext`,
-	* or the shared fallback otherwise. Always returns a real `NodeScope`.
-	*/
+	/** Never null: falls back to the shared scope outside `runWithContext`. */
 	active() {
 		return this.als.getStore() ?? this.fallback;
 	}
-	/**
-	* Public: returns the per-request scope when inside `runWithContext`, or
-	* `null` otherwise. Useful for assertions like "am I in a request?".
-	*/
+	/** Null outside `runWithContext`, so callers can tell "inside a request" from "not". */
 	getContext() {
 		return this.als.getStore() ?? null;
 	}
-	/**
-	* Open a fresh request scope around `fn` and run it. Every async hop
-	* inside `fn` (awaits, timers, promise chains) sees the same scope via
-	* `active()`/`getContext()`; concurrent calls each get their own.
-	*
-	* `request` is shallow-cloned so later edits to the caller's object do not
-	* leak into the stored scope.
-	*/
+	/** `request` is shallow-cloned so later edits to the caller's object do not leak into the scope. */
 	runWithContext(request, fn) {
 		const scope = new NodeScope();
 		scope.request = { ...request };
 		return this.als.run(scope, fn);
 	}
-	/**
-	* Patch the current scope's `request` shape. When called inside
-	* `runWithContext`, the patch is visible to all subsequent reads from
-	* within the same request chain. When called outside, the patch lands on
-	* the fallback scope.
-	*/
 	mergeContext(partial) {
 		const scope = this.als.getStore() ?? this.fallback;
 		scope.request = {
@@ -524,30 +338,9 @@ var AsyncLocalStorageScopeProvider = class {
 //#endregion
 //#region src/stacktrace/DiskFileReader.ts
 /**
-* Node `FileReader` implementation that reads source files from disk.
-*
-* Wired into `@flareapp/node`'s singleton so the stack-trace builder can pull
-* source for each frame and render a snippet. On the server the frame's "URL"
-* is usually a local path (e.g. `/app/dist/server.js`) or a `file://` URL
-* (from `import.meta.url`), so we resolve straight off disk instead of going
-* over the network.
-*
-* Safety gates:
-*
-* 1. **Local-path allowlist.** Only `file://` URLs and absolute filesystem
-*    paths (POSIX `/foo`, Windows `C:\foo` or `\\server\share\foo`) are
-*    accepted. HTTP URLs and relative paths return `null` immediately. We
-*    refuse to read anything that does not unambiguously identify a local
-*    file — no surprise traversal, no following http stack frames in a
-*    server build, no relative-path ambiguity around the current working
-*    directory.
-* 2. **Catch-all.** Missing files, permission errors, and any other failure
-*    return `null`. The `read()` contract returns `null` on every failure
-*    path and never throws.
-*
-* `fileURLToPath` is used when the input is a `file://` URL so we hand
-* `readFile` a real OS path. Otherwise the URL IS already a path and is
-* passed through unchanged.
+* Reads snippet sources off disk: on the server a frame's "URL" is usually a local path or a `file://`
+* URL from `import.meta.url`. Only unambiguously local paths are read, which rules out traversal,
+* following an http frame in a server build, and cwd-relative ambiguity. Never throws.
 */
 var DiskFileReader = class {
 	async read(url) {
@@ -559,17 +352,7 @@ var DiskFileReader = class {
 		}
 	}
 };
-/**
-* Return true when `url` is something we are willing to treat as a local
-* file. Matches four shapes:
-*
-* - `file://...` URLs (any casing of the scheme)
-* - POSIX absolute paths starting with `/`
-* - Windows drive-letter paths like `C:\foo` or `c:/foo`
-* - Windows UNC paths starting with `\\`
-*
-* Anything else (relative paths, http, data, blob, etc) is rejected.
-*/
+/** `file://` (any casing), POSIX absolute, Windows drive-letter (`C:\foo`), Windows UNC (`\\`). */
 function isLocalFileUrl(url) {
 	return /^file:\/\//i.test(url) || url.startsWith("/") || /^[a-z]:[\\/]/i.test(url) || url.startsWith("\\\\");
 }
@@ -577,16 +360,9 @@ function isLocalFileUrl(url) {
 //#endregion
 //#region src/Flare.ts
 const NODE_SDK_NAME = "@flareapp/node";
-const NODE_SDK_VERSION = typeof process !== "undefined" && true ? "0.7.0" : "?";
-/**
-* Strip the `g` and `y` flags from a user-supplied regex.
-*
-* `RegExp.prototype.test()` and `.exec()` keep `lastIndex` state when either of
-* these flags is set, which means reusing the same regex across many keys (as
-* the header denylist and body redaction do) silently skips matches after the
-* first hit. Reconstructing the regex without those flags gives stateless
-* matching while preserving everything else (`i`, `m`, `s`, `u`, source).
-*/
+const NODE_SDK_VERSION = typeof process !== "undefined" && true ? "0.9.0" : "?";
+/** `g`/`y` make `.test()` keep `lastIndex` state, so reusing the regex across keys skips every other
+*  match. All other flags are preserved. */
 function sanitizeRegex(re) {
 	const safeFlags = re.flags.replace(/[gy]/g, "");
 	return new RegExp(re.source, safeFlags);
@@ -607,22 +383,15 @@ const DEFAULT_NODE_OPTIONS = {
 * Node.js-specific `Flare` singleton, exposed from `@flareapp/node` as `flare`.
 *
 * Subclasses core's `Flare` and wires the Node-only seams in its constructor:
-*
-* - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback
-*   gets its own `NodeScope` (glows, attributes, entry-point, request),
+* - `AsyncLocalStorageScopeProvider` so each `runWithContext(...)` callback gets its own `NodeScope`,
 *   isolated from concurrent requests.
-* - `makeNodeContextCollector(...)` to project the current `NodeScope` and
-*   process info into report attributes (http.request.*, url.path, etc).
-* - `DiskFileReader` to read source files for stack-trace snippets via
-*   `node:fs/promises` instead of the browser's `fetch`.
-* - `ProcessHandlerManager` to attach/detach `uncaughtException` and
-*   `unhandledRejection` listeners based on the current `NodeOptions`.
+* - `makeNodeContextCollector(...)` turns the current `NodeScope` + process info into report attributes.
+* - `DiskFileReader` reads source for stack-trace snippets via `node:fs/promises`, not `fetch`.
+* - `ProcessHandlerManager` attaches/detaches the fatal process listeners per `NodeOptions`.
 *
-* Also adds Node-only API surface on top of core: `configureNode(...)`,
-* `runWithContext(...)`, `mergeContext(...)`, `getContext()`,
-* `removeProcessListeners()`. Inherited core methods (`light`, `configure`,
-* `addContext`, `glow`, etc.) return `this`, so chaining keeps the
-* `NodeFlare` type and `configureNode(...)` stays callable mid-chain.
+* Adds Node-only API on top of core: `configureNode`, `runWithContext`, `mergeContext`, `getContext`,
+* `removeProcessListeners`. Inherited core methods return `this`, so chaining keeps the `NodeFlare`
+* type and `configureNode(...)` stays callable mid-chain.
 */
 var NodeFlare = class extends Flare$1 {
 	nodeOptions = { ...DEFAULT_NODE_OPTIONS };
@@ -638,14 +407,10 @@ var NodeFlare = class extends Flare$1 {
 			name: NODE_SDK_NAME,
 			version: NODE_SDK_VERSION
 		});
+		this.setFramework({ name: FrameworkName.Node });
 		this.handlerManager = new ProcessHandlerManager(buildFatalCallbacks(this, () => this.nodeOptions));
 	}
-	/**
-	* Set the API key (and optional debug flag), then reconcile process
-	* listeners with the current `nodeOptions`. Reconcile runs on EVERY call,
-	* not just the first, so `light()` is the right escape hatch to re-attach
-	* after `removeProcessListeners()`.
-	*/
+	/** Reconcile runs on every call, so `light()` re-attaches after `removeProcessListeners()`. */
 	light(key, debug) {
 		super.light(key, debug);
 		this.isLit = true;
@@ -653,20 +418,8 @@ var NodeFlare = class extends Flare$1 {
 		return this;
 	}
 	/**
-	* Merge Node-only options (fatal-handler modes, header/body redaction
-	* config, shutdown timeout) into the active configuration. Safe to call
-	* before or after `light()`:
-	*
-	* - Before `light()`: options are stored; listeners are attached when
-	*   `light()` runs.
-	* - After `light()`: options are stored AND listeners are reconciled
-	*   immediately, so flipping a mode to `'off'` detaches the handler and
-	*   flipping it back to `'report'`/`'report-and-exit'` re-attaches.
-	*
-	* Regex options (`headerAllowlist`, `bodyAllowedContentTypes`,
-	* `bodyKeyDenylist`) are passed through `sanitizeRegex` to strip stateful
-	* `g`/`y` flags; without that, `RegExp.prototype.test` would skip matches
-	* across keys.
+	* Safe before or after `light()`. Before, the listeners attach on `light()`; after, they reconcile
+	* immediately, so flipping a mode to `'off'` detaches and flipping it back re-attaches.
 	*/
 	configureNode(partial) {
 		if (partial.headerDenylist !== void 0 || partial.replaceDefaultHeaderDenylist !== void 0) {
@@ -685,47 +438,25 @@ var NodeFlare = class extends Flare$1 {
 		return this;
 	}
 	/**
-	* Run `fn` inside a fresh `NodeScope` carrying the supplied request
-	* metadata. Inside `fn` (and any async work it awaits), `flare.glow(...)`,
-	* `flare.addContext(...)`, `flare.setUser(...)`, and `flare.report(...)`
-	* see a scope that is isolated from other concurrent requests.
-	*
-	* Mirrors a typical web-framework middleware: call once per request,
-	* wrapping the request handler, and the SDK will attribute any error
-	* reported inside the chain to the right request.
+	* Use as web-framework middleware, once per request around the handler. Inside `fn` and any async
+	* work it awaits, reports are attributed to that request rather than to a concurrent one.
 	*/
 	runWithContext(request, fn) {
 		return this.nodeScopeProvider.runWithContext(request, fn);
 	}
 	/**
-	* Patch the request metadata on the active scope after `runWithContext(...)`
-	* has already started. Useful when fields become known partway through a
-	* request (e.g., the resolved absolute URL after proxy headers are parsed).
-	*
-	* Outside any `runWithContext(...)` callback, this writes to the fallback
-	* scope; the patch is visible to subsequent reports issued from outside a
-	* request scope but is NOT inherited by future `runWithContext(...)` calls.
+	* For fields that only become known partway through a request, such as the absolute URL once proxy
+	* headers are parsed. Outside `runWithContext(...)` this writes to the fallback scope, which future
+	* `runWithContext(...)` calls do not inherit.
 	*/
 	mergeContext(partial) {
 		this.nodeScopeProvider.mergeContext(partial);
 	}
-	/**
-	* Returns the request scope when called inside `runWithContext(...)`, or
-	* `null` outside. Intentionally returns `null` (not the fallback scope)
-	* when no request is active, so callers can distinguish "we are inside a
-	* request" from "we are not". Primarily useful for debugging.
-	*/
+	/** Null (not the fallback scope) outside a request, so callers can tell the two apart. Debugging aid. */
 	getContext() {
 		return this.nodeScopeProvider.getContext();
 	}
-	/**
-	* Detach the `uncaughtException` and `unhandledRejection` listeners
-	* without changing `nodeOptions`. Intended for tests and for graceful
-	* shutdown paths where you want to take ownership of process exit
-	* yourself.
-	*
-	* Calling `light()` afterwards re-attaches based on the current options.
-	*/
+	/** Leaves `nodeOptions` alone, so a later `light()` re-attaches. For tests and graceful shutdown. */
 	removeProcessListeners() {
 		this.handlerManager.detach();
 	}