@webiny/api-core 6.5.0-beta.1 → 6.5.0-beta.3

package/features/debugger/__tests__/serialize.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/__tests__/serialize.test.js","sources":["../../../../src/features/debugger/__tests__/serialize.test.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport { serialize } from \"../serialize.js\";\nimport { DEFAULT_LIMITS, type IDebuggerLimits } from \"../limits.js\";\n\nconst limits = (overrides: Partial<IDebuggerLimits> = {}): IDebuggerLimits => {\n    return { ...DEFAULT_LIMITS, ...overrides };\n};\n\nconst parse = (value: unknown, overrides: Partial<IDebuggerLimits> = {}) => {\n    const result = serialize(value, limits(overrides));\n    return { ...result, parsed: JSON.parse(result.json) };\n};\n\ndescribe(\"serialize\", () => {\n    it(\"should always produce parseable JSON\", () => {\n        const circular: Record<string, unknown> = { name: \"root\" };\n        circular.self = circular;\n\n        const { parsed } = parse(circular);\n\n        expect(parsed).toEqual({ name: \"root\", self: \"#[Circular]\" });\n    });\n\n    it(\"should not report siblings as circular\", () => {\n        const shared = { id: 1 };\n\n        const { parsed } = parse({ a: shared, b: shared });\n\n        expect(parsed).toEqual({ a: { id: 1 }, b: { id: 1 } });\n    });\n\n    it(\"should serialize an Error, which JSON.stringify renders as an empty object\", () => {\n        const error = new Error(\"Boom\");\n\n        const { parsed } = parse({ error });\n\n        expect(parsed.error.name).toBe(\"Error\");\n        expect(parsed.error.message).toBe(\"Boom\");\n        expect(typeof parsed.error.stack).toBe(\"string\");\n    });\n\n    it(\"should serialize a BigInt, which JSON.stringify throws on\", () => {\n        const { parsed } = parse({ value: BigInt(123) });\n\n        expect(parsed).toEqual({ value: \"123n\" });\n    });\n\n    it(\"should describe binary data without including its contents\", () => {\n        const { parsed } = parse({ buffer: Buffer.from(\"hello world\") });\n\n        expect(parsed).toEqual({ buffer: \"#[Buffer 11 bytes]\" });\n    });\n\n    it(\"should serialize Map and Set\", () => {\n        const { parsed } = parse({\n            map: new Map([[\"a\", 1]]),\n            set: new Set([1, 2])\n        });\n\n        expect(parsed.map).toEqual({ __type: \"Map\", entries: [[\"a\", 1]] });\n        expect(parsed.set).toEqual({ __type: \"Set\", items: [1, 2] });\n    });\n\n    it(\"should drop an undefined property, so a logged payload matches what was sent\", () => {\n        const { parsed } = parse({ kept: 1, dropped: undefined });\n\n        expect(parsed).toEqual({ kept: 1 });\n    });\n\n    it(\"should keep undefined array elements, where dropping would shift every later index\", () => {\n        const { parsed } = parse({ items: [1, undefined, 3] });\n\n        expect(parsed).toEqual({ items: [1, \"#[Undefined value]\", 3] });\n    });\n\n    it(\"should not throw when a getter throws\", () => {\n        const value = {\n            get exploding() {\n                throw new Error(\"Nope\");\n            },\n            safe: 1\n        };\n\n        const { parsed } = parse(value);\n\n        expect(parsed.exploding).toBe(\"#[Throws: Nope]\");\n        expect(parsed.safe).toBe(1);\n    });\n\n    it(\"should cap depth\", () => {\n        const { parsed } = parse({ a: { b: { c: { d: \"deep\" } } } }, { depth: 2 });\n\n        expect(parsed).toEqual({ a: { b: \"#[Depth limit]\" } });\n    });\n\n    it(\"should cap string length and say how much was cut\", () => {\n        const { parsed } = parse({ text: \"x\".repeat(20) }, { stringLength: 5 });\n\n        expect(parsed).toEqual({ text: \"xxxxx…(15 more)\" });\n    });\n\n    it(\"should cap array length and say how much was cut\", () => {\n        const { parsed } = parse({ items: [1, 2, 3, 4, 5] }, { arrayLength: 2 });\n\n        expect(parsed).toEqual({ items: [1, 2, \"…(3 more items)\"] });\n    });\n\n    it(\"should replace the payload wholesale when it exceeds the per-entry cap\", () => {\n        const result = parse({ text: \"x\".repeat(5000) }, { entryBytes: 100, stringLength: 100000 });\n\n        expect(result.truncated).toBe(true);\n        expect(result.parsed.truncated).toBe(true);\n        expect(result.parsed.originalBytes).toBeGreaterThan(100);\n        expect(result.bytes).toBeLessThanOrEqual(100);\n    });\n\n    it(\"should never invoke a custom toJSON, so it cannot be broken by one\", () => {\n        const value = {\n            id: 1,\n            toJSON() {\n                throw new Error(\"Nope\");\n            }\n        };\n\n        const { parsed } = parse({ value });\n\n        expect(parsed.value.id).toBe(1);\n        expect(parsed.value.toJSON).toBe(\"#[Function: toJSON]\");\n    });\n\n    it(\"should keep non-finite numbers readable instead of turning them into null\", () => {\n        const { parsed } = parse({ a: Infinity, b: NaN });\n\n        expect(parsed).toEqual({ a: \"Infinity\", b: \"NaN\" });\n    });\n});\n"],"names":["limits","overrides","DEFAULT_LIMITS","parse","value","result","serialize","JSON","describe","it","circular","parsed","expect","shared","error","Error","BigInt","Buffer","Map","Set","undefined","Infinity","NaN"],"mappings":"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"}

package/features/debugger/abstractions.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Registry of debug namespace prefixes.
+ *
+ * Packages augment this interface to claim their own prefix:
+ *
+ * ```ts
+ * declare module "@webiny/api-core/features/debugger/abstractions.js" {
+ *     interface DebugNamespaces {
+ *         cms: `cms.${string}`;
+ *     }
+ * }
+ * ```
+ *
+ * The module specifier must be exactly the one above - a relative path augments nothing.
+ */
+export interface DebugNamespaces {
+    core: `core.${string}`;
+}
+export type DebugNamespace = DebugNamespaces[keyof DebugNamespaces];
+/**
+ * Produces the payload to capture. Invoked only when capture is active, so building an expensive
+ * payload costs nothing when the debugger is off.
+ */
+export interface IDebugPayloadFactory {
+    (): unknown;
+}
+export interface IDebugEntry {
+    seq: number;
+    namespace: string;
+    timestamp: number;
+    /** Milliseconds since the session started. */
+    elapsed: number;
+    /** Already serialized and capped. Valid JSON. */
+    json: string;
+    bytes: number;
+}
+export interface IDebugSession {
+    namespaces: string[];
+    startedAt: number;
+    entries: IDebugEntry[];
+    bytes: number;
+    /** Entries discarded from the front of the buffer because the total budget was exceeded. */
+    dropped: number;
+    /** True once any single entry's payload was replaced by the per-entry cap marker. */
+    truncated: boolean;
+}
+export interface IDebuggerStartParams {
+    namespaces: string[];
+}
+export interface IDebugDeliveryTarget {
+    type: string;
+}
+export interface IDebuggerTransportDeliverParams {
+    target: IDebugDeliveryTarget;
+    session: IDebugSession;
+}
+export interface IDebugger {
+    /**
+     * Opens a capture session, replacing any existing one.
+     */
+    start(params: IDebuggerStartParams): void;
+    /**
+     * Captures a payload, if a session is open and the namespace matches its filter.
+     * Never throws.
+     */
+    log(namespace: DebugNamespace, payload: IDebugPayloadFactory): void;
+    /**
+     * Whether a namespace would currently be captured. For guarding expensive work *around* a log
+     * call - `log` already performs this check itself.
+     */
+    isEnabled(namespace: DebugNamespace): boolean;
+    /**
+     * Hands the session to every transport that can deliver it, then closes it.
+     */
+    flush(target: IDebugDeliveryTarget): Promise<void>;
+    /**
+     * Closes the session without delivering it.
+     */
+    discard(): void;
+}
+export interface IDebuggerTransport {
+    canDeliver(target: IDebugDeliveryTarget): boolean;
+    deliver(params: IDebuggerTransportDeliverParams): Promise<void> | void;
+}
+/** Captures debug payloads for the current request, for delivery to a permitted identity. */
+export declare const Debugger: import("@webiny/di").Abstraction<IDebugger>;
+export declare namespace Debugger {
+    type Interface = IDebugger;
+    type Session = IDebugSession;
+    type Entry = IDebugEntry;
+    type StartParams = IDebuggerStartParams;
+    type PayloadFactory = IDebugPayloadFactory;
+}
+/** Delivers a finished debug session to a sink. */
+export declare const DebuggerTransport: import("@webiny/di").Abstraction<IDebuggerTransport>;
+export declare namespace DebuggerTransport {
+    type Interface = IDebuggerTransport;
+    type Target = IDebugDeliveryTarget;
+    type DeliverParams = IDebuggerTransportDeliverParams;
+}

package/features/debugger/abstractions.js

@@ -0,0 +1,6 @@
+import { createAbstraction } from "@webiny/feature/api";
+const Debugger = createAbstraction("Debugger");
+const DebuggerTransport = createAbstraction("DebuggerTransport");
+export { Debugger, DebuggerTransport };
+
+//# sourceMappingURL=abstractions.js.map

package/features/debugger/abstractions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/abstractions.js","sources":["../../../src/features/debugger/abstractions.ts"],"sourcesContent":["import { createAbstraction } from \"@webiny/feature/api\";\n\n/**\n * Registry of debug namespace prefixes.\n *\n * Packages augment this interface to claim their own prefix:\n *\n * ```ts\n * declare module \"@webiny/api-core/features/debugger/abstractions.js\" {\n *     interface DebugNamespaces {\n *         cms: `cms.${string}`;\n *     }\n * }\n * ```\n *\n * The module specifier must be exactly the one above - a relative path augments nothing.\n */\nexport interface DebugNamespaces {\n    core: `core.${string}`;\n}\n\nexport type DebugNamespace = DebugNamespaces[keyof DebugNamespaces];\n\n/**\n * Produces the payload to capture. Invoked only when capture is active, so building an expensive\n * payload costs nothing when the debugger is off.\n */\nexport interface IDebugPayloadFactory {\n    (): unknown;\n}\n\nexport interface IDebugEntry {\n    seq: number;\n    namespace: string;\n    timestamp: number;\n    /** Milliseconds since the session started. */\n    elapsed: number;\n    /** Already serialized and capped. Valid JSON. */\n    json: string;\n    bytes: number;\n}\n\nexport interface IDebugSession {\n    namespaces: string[];\n    startedAt: number;\n    entries: IDebugEntry[];\n    bytes: number;\n    /** Entries discarded from the front of the buffer because the total budget was exceeded. */\n    dropped: number;\n    /** True once any single entry's payload was replaced by the per-entry cap marker. */\n    truncated: boolean;\n}\n\nexport interface IDebuggerStartParams {\n    namespaces: string[];\n}\n\nexport interface IDebugDeliveryTarget {\n    type: string;\n}\n\nexport interface IDebuggerTransportDeliverParams {\n    target: IDebugDeliveryTarget;\n    session: IDebugSession;\n}\n\nexport interface IDebugger {\n    /**\n     * Opens a capture session, replacing any existing one.\n     */\n    start(params: IDebuggerStartParams): void;\n    /**\n     * Captures a payload, if a session is open and the namespace matches its filter.\n     * Never throws.\n     */\n    log(namespace: DebugNamespace, payload: IDebugPayloadFactory): void;\n    /**\n     * Whether a namespace would currently be captured. For guarding expensive work *around* a log\n     * call - `log` already performs this check itself.\n     */\n    isEnabled(namespace: DebugNamespace): boolean;\n    /**\n     * Hands the session to every transport that can deliver it, then closes it.\n     */\n    flush(target: IDebugDeliveryTarget): Promise<void>;\n    /**\n     * Closes the session without delivering it.\n     */\n    discard(): void;\n}\n\nexport interface IDebuggerTransport {\n    canDeliver(target: IDebugDeliveryTarget): boolean;\n    deliver(params: IDebuggerTransportDeliverParams): Promise<void> | void;\n}\n\n/** Captures debug payloads for the current request, for delivery to a permitted identity. */\nexport const Debugger = createAbstraction<IDebugger>(\"Debugger\");\n\nexport namespace Debugger {\n    export type Interface = IDebugger;\n    export type Session = IDebugSession;\n    export type Entry = IDebugEntry;\n    export type StartParams = IDebuggerStartParams;\n    export type PayloadFactory = IDebugPayloadFactory;\n}\n\n/** Delivers a finished debug session to a sink. */\nexport const DebuggerTransport = createAbstraction<IDebuggerTransport>(\"DebuggerTransport\");\n\nexport namespace DebuggerTransport {\n    export type Interface = IDebuggerTransport;\n    export type Target = IDebugDeliveryTarget;\n    export type DeliverParams = IDebuggerTransportDeliverParams;\n}\n"],"names":["Debugger","createAbstraction","DebuggerTransport"],"mappings":";AAiGO,MAAMA,WAAWC,kBAA6B;AAW9C,MAAMC,oBAAoBD,kBAAsC"}

package/features/debugger/feature.d.ts

@@ -0,0 +1,5 @@
+import { Container } from "@webiny/di";
+export declare const DebuggerFeature: {
+    name: string;
+    register(container: Container): void;
+};

package/features/debugger/feature.js

@@ -0,0 +1,15 @@
+import { createFeature } from "@webiny/feature/api";
+import { Debugger } from "./Debugger.js";
+import { GraphQLDebuggerTransport } from "./GraphQLDebuggerTransport.js";
+import { DebuggerPermissionsFeature } from "./permissions.js";
+const DebuggerFeature = createFeature({
+    name: "DebuggerFeature",
+    register (container) {
+        container.register(Debugger).inSingletonScope();
+        container.register(GraphQLDebuggerTransport);
+        DebuggerPermissionsFeature.register(container);
+    }
+});
+export { DebuggerFeature };
+
+//# sourceMappingURL=feature.js.map

package/features/debugger/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/feature.js","sources":["../../../src/features/debugger/feature.ts"],"sourcesContent":["import { createFeature } from \"@webiny/feature/api\";\nimport { Container } from \"@webiny/di\";\nimport { Debugger } from \"./Debugger.js\";\nimport { GraphQLDebuggerTransport } from \"./GraphQLDebuggerTransport.js\";\nimport { DebuggerPermissionsFeature } from \"./permissions.js\";\n\nexport const DebuggerFeature = createFeature({\n    name: \"DebuggerFeature\",\n    register(container: Container) {\n        /**\n         * Must be a singleton. The session is instance state, so a transient registration would give\n         * the start plugin, every call site and the flush plugin three different instances - and the\n         * failure would be silent: nothing throws, nothing is reported.\n         */\n        container.register(Debugger).inSingletonScope();\n        container.register(GraphQLDebuggerTransport);\n        DebuggerPermissionsFeature.register(container);\n    }\n});\n"],"names":["DebuggerFeature","createFeature","container","Debugger","GraphQLDebuggerTransport","DebuggerPermissionsFeature"],"mappings":";;;;AAMO,MAAMA,kBAAkBC,cAAc;IACzC,MAAM;IACN,UAASC,SAAoB;QAMzBA,UAAU,QAAQ,CAACC,UAAU,gBAAgB;QAC7CD,UAAU,QAAQ,CAACE;QACnBC,2BAA2B,QAAQ,CAACH;IACxC;AACJ"}

package/features/debugger/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./abstractions.js";
+export { DebuggerFeature } from "./feature.js";
+export { createDebuggerPlugins, DEBUG_HEADER, DEBUG_PERMISSION } from "./plugins.js";
+export { GRAPHQL_TARGET, type IGraphQLDeliveryTarget } from "./GraphQLDebuggerTransport.js";
+export { DEFAULT_LIMITS, type IDebuggerLimits } from "./limits.js";
+export { DEBUGGER_PERMISSIONS_SCHEMA } from "./permissionsSchema.js";
+export { DebuggerPermissions, DebuggerPermissionsFeature } from "./permissions.js";

package/features/debugger/index.js

@@ -0,0 +1,7 @@
+export * from "./abstractions.js";
+export { DebuggerFeature } from "./feature.js";
+export { DEBUG_HEADER, DEBUG_PERMISSION, createDebuggerPlugins } from "./plugins.js";
+export { GRAPHQL_TARGET } from "./GraphQLDebuggerTransport.js";
+export { DEFAULT_LIMITS } from "./limits.js";
+export { DEBUGGER_PERMISSIONS_SCHEMA } from "./permissionsSchema.js";
+export { DebuggerPermissions, DebuggerPermissionsFeature } from "./permissions.js";

package/features/debugger/limits.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Capture limits. None of these are settable by the client.
+ */
+export interface IDebuggerLimits {
+    /** Total serialized bytes a session may hold. Overflow drops entries from the front. */
+    totalBytes: number;
+    /** Maximum serialized size of a single entry, after the walk caps below are applied. */
+    entryBytes: number;
+    /** Runaway-loop guard. The byte budget is the real control. */
+    entryCount: number;
+    /** Maximum nesting depth walked before emitting a marker. */
+    depth: number;
+    /** Maximum characters kept from a single string value. */
+    stringLength: number;
+    /** Maximum items kept from a single array. */
+    arrayLength: number;
+}
+export declare const DEFAULT_LIMITS: IDebuggerLimits;

package/features/debugger/limits.js

@@ -0,0 +1,11 @@
+const DEFAULT_LIMITS = {
+    totalBytes: 4194304,
+    entryBytes: 524288,
+    entryCount: 10000,
+    depth: 10,
+    stringLength: 10000,
+    arrayLength: 100
+};
+export { DEFAULT_LIMITS };
+
+//# sourceMappingURL=limits.js.map

package/features/debugger/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/limits.js","sources":["../../../src/features/debugger/limits.ts"],"sourcesContent":["/**\n * Capture limits. None of these are settable by the client.\n */\nexport interface IDebuggerLimits {\n    /** Total serialized bytes a session may hold. Overflow drops entries from the front. */\n    totalBytes: number;\n    /** Maximum serialized size of a single entry, after the walk caps below are applied. */\n    entryBytes: number;\n    /** Runaway-loop guard. The byte budget is the real control. */\n    entryCount: number;\n    /** Maximum nesting depth walked before emitting a marker. */\n    depth: number;\n    /** Maximum characters kept from a single string value. */\n    stringLength: number;\n    /** Maximum items kept from a single array. */\n    arrayLength: number;\n}\n\nexport const DEFAULT_LIMITS: IDebuggerLimits = {\n    totalBytes: 4 * 1024 * 1024,\n    entryBytes: 512 * 1024,\n    entryCount: 10000,\n    depth: 10,\n    stringLength: 10000,\n    arrayLength: 100\n};\n"],"names":["DEFAULT_LIMITS"],"mappings":"AAkBO,MAAMA,iBAAkC;IAC3C,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,OAAO;IACP,cAAc;IACd,aAAa;AACjB"}

package/features/debugger/matchNamespace.d.ts

@@ -0,0 +1,21 @@
+export interface INamespaceFilter {
+    matches(namespace: string): boolean;
+}
+/**
+ * Builds a namespace matcher from the patterns requested by the client.
+ *
+ * A namespace matches when at least one positive pattern matches it and no negative pattern does.
+ *
+ * `minimatch` has its own native `!` negation which *inverts* the result rather than reporting a
+ * match, so `!cms.os.*` would return `true` for every namespace that does not match it. Patterns are
+ * therefore split into positive and negative lists here and matched positively, with `nonegate` set
+ * as a second guard.
+ */
+export declare const createNamespaceFilter: (patterns: string[]) => INamespaceFilter;
+/**
+ * Parses the `x-webiny-debug` header into a namespace pattern list.
+ *
+ * Returns an empty array when capture was not requested. Never throws - a malformed header must not
+ * be able to fail the request it arrived on.
+ */
+export declare const parseNamespaceHeader: (value: string | string[] | undefined) => string[];

package/features/debugger/matchNamespace.js

@@ -0,0 +1,48 @@
+import { minimatch } from "minimatch";
+const createNamespaceFilter = (patterns)=>{
+    const positive = [];
+    const negative = [];
+    for (const pattern of patterns){
+        if (pattern.startsWith("!")) {
+            const stripped = pattern.slice(1);
+            if (stripped) negative.push(stripped);
+            continue;
+        }
+        if (pattern) positive.push(pattern);
+    }
+    const cache = new Map();
+    const test = (namespace)=>{
+        const isIncluded = positive.some((pattern)=>minimatch(namespace, pattern, {
+                nonegate: true
+            }));
+        if (!isIncluded) return false;
+        return !negative.some((pattern)=>minimatch(namespace, pattern, {
+                nonegate: true
+            }));
+    };
+    return {
+        matches (namespace) {
+            const cached = cache.get(namespace);
+            if (void 0 !== cached) return cached;
+            const result = test(namespace);
+            cache.set(namespace, result);
+            return result;
+        }
+    };
+};
+const parseNamespaceHeader = (value)=>{
+    if (!value) return [];
+    const raw = Array.isArray(value) ? value.join(",") : value;
+    const patterns = raw.split(",").map((item)=>item.trim()).filter(Boolean);
+    if (0 === patterns.length) return [];
+    if (1 === patterns.length) {
+        const only = patterns[0].toLowerCase();
+        if ("1" === only || "true" === only) return [
+            "*"
+        ];
+    }
+    return patterns;
+};
+export { createNamespaceFilter, parseNamespaceHeader };
+
+//# sourceMappingURL=matchNamespace.js.map

package/features/debugger/matchNamespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/matchNamespace.js","sources":["../../../src/features/debugger/matchNamespace.ts"],"sourcesContent":["import { minimatch } from \"minimatch\";\n\nexport interface INamespaceFilter {\n    matches(namespace: string): boolean;\n}\n\n/**\n * Builds a namespace matcher from the patterns requested by the client.\n *\n * A namespace matches when at least one positive pattern matches it and no negative pattern does.\n *\n * `minimatch` has its own native `!` negation which *inverts* the result rather than reporting a\n * match, so `!cms.os.*` would return `true` for every namespace that does not match it. Patterns are\n * therefore split into positive and negative lists here and matched positively, with `nonegate` set\n * as a second guard.\n */\nexport const createNamespaceFilter = (patterns: string[]): INamespaceFilter => {\n    const positive: string[] = [];\n    const negative: string[] = [];\n\n    for (const pattern of patterns) {\n        if (pattern.startsWith(\"!\")) {\n            const stripped = pattern.slice(1);\n            if (stripped) {\n                negative.push(stripped);\n            }\n            continue;\n        }\n        if (pattern) {\n            positive.push(pattern);\n        }\n    }\n\n    /**\n     * Matching is stable for the life of a session, so each distinct namespace is matched once.\n     */\n    const cache = new Map<string, boolean>();\n\n    const test = (namespace: string): boolean => {\n        const isIncluded = positive.some(pattern => {\n            return minimatch(namespace, pattern, { nonegate: true });\n        });\n\n        if (!isIncluded) {\n            return false;\n        }\n\n        return !negative.some(pattern => {\n            return minimatch(namespace, pattern, { nonegate: true });\n        });\n    };\n\n    return {\n        matches(namespace) {\n            const cached = cache.get(namespace);\n            if (cached !== undefined) {\n                return cached;\n            }\n            const result = test(namespace);\n            cache.set(namespace, result);\n            return result;\n        }\n    };\n};\n\n/**\n * Parses the `x-webiny-debug` header into a namespace pattern list.\n *\n * Returns an empty array when capture was not requested. Never throws - a malformed header must not\n * be able to fail the request it arrived on.\n */\nexport const parseNamespaceHeader = (value: string | string[] | undefined): string[] => {\n    if (!value) {\n        return [];\n    }\n\n    /**\n     * Duplicate headers arrive comma-joined from both Node and API Gateway; the array form only\n     * shows up under `app.inject`.\n     */\n    const raw = Array.isArray(value) ? value.join(\",\") : value;\n\n    const patterns = raw\n        .split(\",\")\n        .map(item => item.trim())\n        .filter(Boolean);\n\n    if (patterns.length === 0) {\n        return [];\n    }\n\n    /**\n     * `1` and `true` are shorthand for \"everything\". Anything else is treated as a pattern list.\n     */\n    if (patterns.length === 1) {\n        const only = patterns[0].toLowerCase();\n        if (only === \"1\" || only === \"true\") {\n            return [\"*\"];\n        }\n    }\n\n    return patterns;\n};\n"],"names":["createNamespaceFilter","patterns","positive","negative","pattern","stripped","cache","Map","test","namespace","isIncluded","minimatch","cached","undefined","result","parseNamespaceHeader","value","raw","Array","item","Boolean","only"],"mappings":";AAgBO,MAAMA,wBAAwB,CAACC;IAClC,MAAMC,WAAqB,EAAE;IAC7B,MAAMC,WAAqB,EAAE;IAE7B,KAAK,MAAMC,WAAWH,SAAU;QAC5B,IAAIG,QAAQ,UAAU,CAAC,MAAM;YACzB,MAAMC,WAAWD,QAAQ,KAAK,CAAC;YAC/B,IAAIC,UACAF,SAAS,IAAI,CAACE;YAElB;QACJ;QACA,IAAID,SACAF,SAAS,IAAI,CAACE;IAEtB;IAKA,MAAME,QAAQ,IAAIC;IAElB,MAAMC,OAAO,CAACC;QACV,MAAMC,aAAaR,SAAS,IAAI,CAACE,CAAAA,UACtBO,UAAUF,WAAWL,SAAS;gBAAE,UAAU;YAAK;QAG1D,IAAI,CAACM,YACD,OAAO;QAGX,OAAO,CAACP,SAAS,IAAI,CAACC,CAAAA,UACXO,UAAUF,WAAWL,SAAS;gBAAE,UAAU;YAAK;IAE9D;IAEA,OAAO;QACH,SAAQK,SAAS;YACb,MAAMG,SAASN,MAAM,GAAG,CAACG;YACzB,IAAIG,AAAWC,WAAXD,QACA,OAAOA;YAEX,MAAME,SAASN,KAAKC;YACpBH,MAAM,GAAG,CAACG,WAAWK;YACrB,OAAOA;QACX;IACJ;AACJ;AAQO,MAAMC,uBAAuB,CAACC;IACjC,IAAI,CAACA,OACD,OAAO,EAAE;IAOb,MAAMC,MAAMC,MAAM,OAAO,CAACF,SAASA,MAAM,IAAI,CAAC,OAAOA;IAErD,MAAMf,WAAWgB,IACZ,KAAK,CAAC,KACN,GAAG,CAACE,CAAAA,OAAQA,KAAK,IAAI,IACrB,MAAM,CAACC;IAEZ,IAAInB,AAAoB,MAApBA,SAAS,MAAM,EACf,OAAO,EAAE;IAMb,IAAIA,AAAoB,MAApBA,SAAS,MAAM,EAAQ;QACvB,MAAMoB,OAAOpB,QAAQ,CAAC,EAAE,CAAC,WAAW;QACpC,IAAIoB,AAAS,QAATA,QAAgBA,AAAS,WAATA,MAChB,OAAO;YAAC;SAAI;IAEpB;IAEA,OAAOpB;AACX"}

package/features/debugger/permissions.d.ts

@@ -0,0 +1,33 @@
+import { type Permissions } from "../../features/security/permissions/index.js";
+import type { IIdentityContext } from "../../features/security/IdentityContext/abstractions.js";
+import { DEBUGGER_PERMISSIONS_SCHEMA } from "./permissionsSchema.js";
+export declare const DEBUG_PERMISSION_NAME = "dev-tools.debug";
+export declare const DebuggerPermissions: import("@webiny/di").Abstraction<import("../security/permissions/types.js").PermissionsTyped<{
+    readonly prefix: "dev-tools";
+    readonly fullAccess: true;
+    readonly entities: readonly [{
+        readonly id: "debug";
+        readonly title: "Debugger";
+        readonly permission: "dev-tools.debug";
+        readonly scopes: readonly ["full"];
+    }];
+}>>;
+export declare namespace DebuggerPermissions {
+    type Interface = Permissions<typeof DEBUGGER_PERMISSIONS_SCHEMA>;
+}
+export declare const DebuggerPermissionsFeature: {
+    name: string;
+    register(container: import("@webiny/di").Container): void;
+};
+/**
+ * Whether an identity may capture debug data.
+ *
+ * Deliberately an exact match rather than `canAccess`, which grants on `*` and on `dev-tools.*`.
+ * Capture runs automatically for whoever holds this, so a wildcard would leave it permanently on for
+ * every full-access administrator - collecting record content on every request, indefinitely, for
+ * people who never asked for it.
+ *
+ * The consequence, which is intended: full access is not enough. The entity has to be granted
+ * deliberately, and that act is the opt-in.
+ */
+export declare const canCaptureDebugData: (identityContext: IIdentityContext) => Promise<boolean>;

package/features/debugger/permissions.js

@@ -0,0 +1,12 @@
+import { createPermissionsAbstraction, createPermissionsFeature } from "../security/permissions/index.js";
+import { DEBUGGER_PERMISSIONS_SCHEMA } from "./permissionsSchema.js";
+const DEBUG_PERMISSION_NAME = "dev-tools.debug";
+const DebuggerPermissions = createPermissionsAbstraction(DEBUGGER_PERMISSIONS_SCHEMA);
+const DebuggerPermissionsFeature = createPermissionsFeature(DEBUGGER_PERMISSIONS_SCHEMA, DebuggerPermissions);
+const canCaptureDebugData = async (identityContext)=>{
+    const permissions = await identityContext.listPermissions();
+    return permissions.some((permission)=>permission.name === DEBUG_PERMISSION_NAME);
+};
+export { DEBUG_PERMISSION_NAME, DebuggerPermissions, DebuggerPermissionsFeature, canCaptureDebugData };
+
+//# sourceMappingURL=permissions.js.map

package/features/debugger/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/permissions.js","sources":["../../../src/features/debugger/permissions.ts"],"sourcesContent":["import {\n    createPermissionsAbstraction,\n    createPermissionsFeature,\n    type Permissions\n} from \"~/features/security/permissions/index.js\";\nimport type { IIdentityContext } from \"~/features/security/IdentityContext/abstractions.js\";\nimport type { SecurityPermission } from \"~/types/security.js\";\nimport { DEBUGGER_PERMISSIONS_SCHEMA } from \"./permissionsSchema.js\";\n\nexport const DEBUG_PERMISSION_NAME = \"dev-tools.debug\";\n\nexport const DebuggerPermissions = createPermissionsAbstraction(DEBUGGER_PERMISSIONS_SCHEMA);\n\nexport namespace DebuggerPermissions {\n    export type Interface = Permissions<typeof DEBUGGER_PERMISSIONS_SCHEMA>;\n}\n\nexport const DebuggerPermissionsFeature = createPermissionsFeature(\n    DEBUGGER_PERMISSIONS_SCHEMA,\n    DebuggerPermissions\n);\n\n/**\n * Whether an identity may capture debug data.\n *\n * Deliberately an exact match rather than `canAccess`, which grants on `*` and on `dev-tools.*`.\n * Capture runs automatically for whoever holds this, so a wildcard would leave it permanently on for\n * every full-access administrator - collecting record content on every request, indefinitely, for\n * people who never asked for it.\n *\n * The consequence, which is intended: full access is not enough. The entity has to be granted\n * deliberately, and that act is the opt-in.\n */\nexport const canCaptureDebugData = async (identityContext: IIdentityContext): Promise<boolean> => {\n    const permissions = await identityContext.listPermissions();\n    return permissions.some(\n        (permission: SecurityPermission) => permission.name === DEBUG_PERMISSION_NAME\n    );\n};\n"],"names":["DEBUG_PERMISSION_NAME","DebuggerPermissions","createPermissionsAbstraction","DEBUGGER_PERMISSIONS_SCHEMA","DebuggerPermissionsFeature","createPermissionsFeature","canCaptureDebugData","identityContext","permissions","permission"],"mappings":";;AASO,MAAMA,wBAAwB;AAE9B,MAAMC,sBAAsBC,6BAA6BC;AAMzD,MAAMC,6BAA6BC,yBACtCF,6BACAF;AAcG,MAAMK,sBAAsB,OAAOC;IACtC,MAAMC,cAAc,MAAMD,gBAAgB,eAAe;IACzD,OAAOC,YAAY,IAAI,CACnB,CAACC,aAAmCA,WAAW,IAAI,KAAKT;AAEhE"}

package/features/debugger/permissionsSchema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The debugger lives under the `dev-tools` prefix, alongside the playgrounds.
+ *
+ * Note the consequence: `fullAccess: true` emits `dev-tools.*`, and permission matching is glob
+ * based, so any role holding Dev Tools full access can capture debug data without `dev-tools.debug`
+ * being granted explicitly.
+ */
+export declare const DEBUGGER_PERMISSIONS_SCHEMA: {
+    readonly prefix: "dev-tools";
+    readonly fullAccess: true;
+    readonly entities: readonly [{
+        readonly id: "debug";
+        readonly title: "Debugger";
+        readonly permission: "dev-tools.debug";
+        readonly scopes: readonly ["full"];
+    }];
+};

package/features/debugger/permissionsSchema.js

@@ -0,0 +1,18 @@
+import { createPermissionSchema } from "../security/permissions/index.js";
+const DEBUGGER_PERMISSIONS_SCHEMA = createPermissionSchema({
+    prefix: "dev-tools",
+    fullAccess: true,
+    entities: [
+        {
+            id: "debug",
+            title: "Debugger",
+            permission: "dev-tools.debug",
+            scopes: [
+                "full"
+            ]
+        }
+    ]
+});
+export { DEBUGGER_PERMISSIONS_SCHEMA };
+
+//# sourceMappingURL=permissionsSchema.js.map

package/features/debugger/permissionsSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/permissionsSchema.js","sources":["../../../src/features/debugger/permissionsSchema.ts"],"sourcesContent":["import { createPermissionSchema } from \"~/features/security/permissions/index.js\";\n\n/**\n * The debugger lives under the `dev-tools` prefix, alongside the playgrounds.\n *\n * Note the consequence: `fullAccess: true` emits `dev-tools.*`, and permission matching is glob\n * based, so any role holding Dev Tools full access can capture debug data without `dev-tools.debug`\n * being granted explicitly.\n */\nexport const DEBUGGER_PERMISSIONS_SCHEMA = createPermissionSchema({\n    prefix: \"dev-tools\",\n    fullAccess: true,\n    entities: [\n        {\n            id: \"debug\",\n            title: \"Debugger\",\n            permission: \"dev-tools.debug\",\n            scopes: [\"full\"]\n        }\n    ]\n});\n"],"names":["DEBUGGER_PERMISSIONS_SCHEMA","createPermissionSchema"],"mappings":";AASO,MAAMA,8BAA8BC,uBAAuB;IAC9D,QAAQ;IACR,YAAY;IACZ,UAAU;QACN;YACI,IAAI;YACJ,OAAO;YACP,YAAY;YACZ,QAAQ;gBAAC;aAAO;QACpB;KACH;AACL"}

package/features/debugger/plugins.d.ts

@@ -0,0 +1,4 @@
+import type { PluginCollection } from "@webiny/plugins/types.js";
+export declare const DEBUG_HEADER = "x-webiny-debug";
+export declare const DEBUG_PERMISSION = "dev-tools.debug";
+export declare const createDebuggerPlugins: () => PluginCollection;

package/features/debugger/plugins.js

@@ -0,0 +1,82 @@
+import { Request, RequestId, createBeforeHandlerPlugin, createHandlerResultPlugin } from "@webiny/handler";
+import { Debugger } from "./abstractions.js";
+import { IdentityContext } from "../security/IdentityContext/index.js";
+import { parseNamespaceHeader } from "./matchNamespace.js";
+import { canCaptureDebugData } from "./permissions.js";
+import { GRAPHQL_TARGET } from "./GraphQLDebuggerTransport.js";
+const DEBUG_HEADER = "x-webiny-debug";
+const DEBUG_PERMISSION = "dev-tools.debug";
+const isPlainObject = (value)=>"object" == typeof value && null !== value && !Array.isArray(value);
+const isGraphQLResult = (value)=>isPlainObject(value) && ("data" in value || "errors" in value);
+const resolveTarget = (payload)=>{
+    const candidate = Array.isArray(payload) ? payload.at(-1) : payload;
+    return isGraphQLResult(candidate) ? candidate : void 0;
+};
+const readOperationNames = (body)=>{
+    const operations = Array.isArray(body) ? body : [
+        body
+    ];
+    return operations.map((operation)=>isPlainObject(operation) && "string" == typeof operation.operationName ? operation.operationName : void 0).filter((name)=>Boolean(name));
+};
+const createStartPlugin = ()=>createBeforeHandlerPlugin(async (context)=>{
+        try {
+            const request = context.container.resolve(Request);
+            const requested = parseNamespaceHeader(request.headers[DEBUG_HEADER]);
+            const namespaces = requested.length > 0 ? requested : [
+                "*"
+            ];
+            context.container.resolve(Debugger).start({
+                namespaces
+            });
+        } catch  {}
+    });
+const createFlushPlugin = ()=>createHandlerResultPlugin(async (context, payload)=>{
+        try {
+            const debuggerService = context.container.resolve(Debugger);
+            const identityContext = context.container.resolve(IdentityContext);
+            const result = resolveTarget(payload);
+            if (!result) {
+                debuggerService.discard();
+                return payload;
+            }
+            if (identityContext.getIdentity().isAnonymous()) {
+                debuggerService.discard();
+                return payload;
+            }
+            const isAuthorized = identityContext.isAuthorizationEnabled() && await canCaptureDebugData(identityContext);
+            if (!isAuthorized) {
+                debuggerService.discard();
+                return payload;
+            }
+            let operations = [];
+            let requestId = "";
+            let url = "";
+            try {
+                const request = context.container.resolve(Request);
+                operations = readOperationNames(request.body);
+                requestId = context.container.resolve(RequestId).value;
+                url = request.url || "";
+            } catch  {}
+            const target = {
+                type: GRAPHQL_TARGET,
+                result,
+                requestId,
+                operations,
+                url
+            };
+            await debuggerService.flush(target);
+        } catch (ex) {
+            console.error("Debugger failed to flush.", ex instanceof Error ? `${ex.name}: ${ex.message}` : "Unknown error.");
+            try {
+                context.container.resolve(Debugger).discard();
+            } catch  {}
+        }
+        return payload;
+    });
+const createDebuggerPlugins = ()=>[
+        createStartPlugin(),
+        createFlushPlugin()
+    ];
+export { DEBUG_HEADER, DEBUG_PERMISSION, createDebuggerPlugins };
+
+//# sourceMappingURL=plugins.js.map

package/features/debugger/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features/debugger/plugins.js","sources":["../../../src/features/debugger/plugins.ts"],"sourcesContent":["import {\n    createBeforeHandlerPlugin,\n    createHandlerResultPlugin,\n    Request,\n    RequestId\n} from \"@webiny/handler\";\nimport type { PluginCollection } from \"@webiny/plugins/types.js\";\nimport type { Context } from \"@webiny/handler/types.js\";\nimport { Debugger } from \"./abstractions.js\";\nimport { IdentityContext } from \"~/features/security/IdentityContext/index.js\";\nimport { parseNamespaceHeader } from \"./matchNamespace.js\";\nimport { canCaptureDebugData } from \"./permissions.js\";\nimport { GRAPHQL_TARGET, type IGraphQLDeliveryTarget } from \"./GraphQLDebuggerTransport.js\";\n\nexport const DEBUG_HEADER = \"x-webiny-debug\";\nexport const DEBUG_PERMISSION = \"dev-tools.debug\";\n\nconst isPlainObject = (value: unknown): value is Record<string, any> => {\n    return typeof value === \"object\" && value !== null && !Array.isArray(value);\n};\n\n/**\n * A GraphQL result carries `data` or `errors`. Anything else - asset delivery, a plain string body -\n * is not ours to write to.\n */\nconst isGraphQLResult = (value: unknown): value is Record<string, any> => {\n    return isPlainObject(value) && (\"data\" in value || \"errors\" in value);\n};\n\n/**\n * Batched requests produce an array of results. The session spans the whole HTTP request, so it is\n * attached once, to the last element - duplicating it per operation would multiply it against the\n * byte budget.\n */\nconst resolveTarget = (payload: unknown): Record<string, any> | undefined => {\n    const candidate = Array.isArray(payload) ? payload.at(-1) : payload;\n    return isGraphQLResult(candidate) ? candidate : undefined;\n};\n\nconst readOperationNames = (body: unknown): string[] => {\n    const operations = Array.isArray(body) ? body : [body];\n    return operations\n        .map(operation => {\n            return isPlainObject(operation) && typeof operation.operationName === \"string\"\n                ? operation.operationName\n                : undefined;\n        })\n        .filter((name): name is string => Boolean(name));\n};\n\n/**\n * Opens the capture session.\n *\n * Runs as a `BeforeHandlerPlugin`, so it is in place before the route handler and therefore before\n * any resolver. Note that `ContextPlugin`s run earlier still, so anything logged from one of those\n * is not captured.\n */\nconst createStartPlugin = () => {\n    return createBeforeHandlerPlugin<Context>(async context => {\n        /**\n         * Must never throw: `ProcessBeforeHandlerPlugins` rethrows, which would turn a malformed\n         * header into a 500 for the whole request.\n         */\n        try {\n            const request = context.container.resolve(Request);\n\n            /**\n             * A session starts on every request, and the permission check at flush decides whether\n             * anything is delivered or the whole thing is discarded.\n             *\n             * Nothing is required from the client. Asking for a request header would mean putting it\n             * on the CORS allow-list, which is cached in preflight responses at CloudFront and in\n             * the browser for a day - so rolling one out breaks requests intermittently until every\n             * cache entry expires.\n             *\n             * The header is still honoured when present, so a direct API client can narrow what it\n             * captures.\n             */\n            const requested = parseNamespaceHeader(request.headers[DEBUG_HEADER]);\n            const namespaces = requested.length > 0 ? requested : [\"*\"];\n\n            context.container.resolve(Debugger).start({ namespaces });\n        } catch {\n            // A debugger that cannot start is not a reason to fail the request.\n        }\n    });\n};\n\n/**\n * Performs the permission gate and hands the session to the transports.\n *\n * This runs once per HTTP response, in the `preSerialization` hook - deliberately not in\n * `graphql-after-query`, which also fires for the nested executions that CMS resolvers perform\n * internally and would attach the session to a result that is then discarded.\n */\nconst createFlushPlugin = () => {\n    return createHandlerResultPlugin<Context>(async (context, payload) => {\n        /**\n         * The whole body is guarded: `preSerialization` rethrows whatever a `HandlerResultPlugin`\n         * throws, so an error here would turn a working response into a 500 - and only for requests\n         * that asked for debugging.\n         */\n        try {\n            const debuggerService = context.container.resolve(Debugger);\n            const identityContext = context.container.resolve(IdentityContext);\n\n            const result = resolveTarget(payload);\n            if (!result) {\n                debuggerService.discard();\n                return payload;\n            }\n\n            /**\n             * Anonymous callers are rejected before permissions are resolved: `getPermission` runs\n             * every registered Authorizer, some of which hit the database.\n             */\n            if (identityContext.getIdentity().isAnonymous()) {\n                debuggerService.discard();\n                return payload;\n            }\n\n            /**\n             * `getPermission` returns a wildcard permission whenever authorization is disabled, so a\n             * flush occurring inside a `withoutAuthorization` scope would pass for anyone.\n             */\n            const isAuthorized =\n                identityContext.isAuthorizationEnabled() &&\n                (await canCaptureDebugData(identityContext));\n\n            if (!isAuthorized) {\n                /**\n                 * Nothing is written. Reporting the denial would tell every unauthorized caller that\n                 * the feature exists, and the Admin app already knows from the identity's own\n                 * permissions whether capture is available to it.\n                 */\n                debuggerService.discard();\n                return payload;\n            }\n\n            let operations: string[] = [];\n            let requestId = \"\";\n            let url = \"\";\n            try {\n                const request = context.container.resolve(Request);\n                operations = readOperationNames(request.body);\n                requestId = context.container.resolve(RequestId).value;\n                /**\n                 * Which endpoint this was. An Admin session talks to several - the main API and the\n                 * CMS manage, read and preview endpoints - and knowing which one produced an entry\n                 * is most of the context when reading a report.\n                 */\n                url = request.url || \"\";\n            } catch {\n                // All three are conveniences; their absence must not stop the flush.\n            }\n\n            const target: IGraphQLDeliveryTarget = {\n                type: GRAPHQL_TARGET,\n                result,\n                requestId,\n                operations,\n                url\n            };\n\n            await debuggerService.flush(target);\n        } catch (ex) {\n            /**\n             * Only the message - never the session or the payload.\n             */\n            console.error(\n                \"Debugger failed to flush.\",\n                ex instanceof Error ? `${ex.name}: ${ex.message}` : \"Unknown error.\"\n            );\n            try {\n                context.container.resolve(Debugger).discard();\n            } catch {\n                // Nothing further to do.\n            }\n        }\n\n        /**\n         * `preSerialization` ignores this return value and serializes the original payload object,\n         * so every write above mutates `result` in place.\n         */\n        return payload;\n    });\n};\n\nexport const createDebuggerPlugins = (): PluginCollection => {\n    return [createStartPlugin(), createFlushPlugin()];\n};\n"],"names":["DEBUG_HEADER","DEBUG_PERMISSION","isPlainObject","value","Array","isGraphQLResult","resolveTarget","payload","candidate","undefined","readOperationNames","body","operations","operation","name","Boolean","createStartPlugin","createBeforeHandlerPlugin","context","request","Request","requested","parseNamespaceHeader","namespaces","Debugger","createFlushPlugin","createHandlerResultPlugin","debuggerService","identityContext","IdentityContext","result","isAuthorized","canCaptureDebugData","requestId","url","RequestId","target","GRAPHQL_TARGET","ex","console","Error","createDebuggerPlugins"],"mappings":";;;;;;AAcO,MAAMA,eAAe;AACrB,MAAMC,mBAAmB;AAEhC,MAAMC,gBAAgB,CAACC,QACZ,AAAiB,YAAjB,OAAOA,SAAsBA,AAAU,SAAVA,SAAkB,CAACC,MAAM,OAAO,CAACD;AAOzE,MAAME,kBAAkB,CAACF,QACdD,cAAcC,UAAW,WAAUA,SAAS,YAAYA,KAAI;AAQvE,MAAMG,gBAAgB,CAACC;IACnB,MAAMC,YAAYJ,MAAM,OAAO,CAACG,WAAWA,QAAQ,EAAE,CAAC,MAAMA;IAC5D,OAAOF,gBAAgBG,aAAaA,YAAYC;AACpD;AAEA,MAAMC,qBAAqB,CAACC;IACxB,MAAMC,aAAaR,MAAM,OAAO,CAACO,QAAQA,OAAO;QAACA;KAAK;IACtD,OAAOC,WACF,GAAG,CAACC,CAAAA,YACMX,cAAcW,cAAc,AAAmC,YAAnC,OAAOA,UAAU,aAAa,GAC3DA,UAAU,aAAa,GACvBJ,QAET,MAAM,CAAC,CAACK,OAAyBC,QAAQD;AAClD;AASA,MAAME,oBAAoB,IACfC,0BAAmC,OAAMC;QAK5C,IAAI;YACA,MAAMC,UAAUD,QAAQ,SAAS,CAAC,OAAO,CAACE;YAc1C,MAAMC,YAAYC,qBAAqBH,QAAQ,OAAO,CAACnB,aAAa;YACpE,MAAMuB,aAAaF,UAAU,MAAM,GAAG,IAAIA,YAAY;gBAAC;aAAI;YAE3DH,QAAQ,SAAS,CAAC,OAAO,CAACM,UAAU,KAAK,CAAC;gBAAED;YAAW;QAC3D,EAAE,OAAM,CAER;IACJ;AAUJ,MAAME,oBAAoB,IACfC,0BAAmC,OAAOR,SAASX;QAMtD,IAAI;YACA,MAAMoB,kBAAkBT,QAAQ,SAAS,CAAC,OAAO,CAACM;YAClD,MAAMI,kBAAkBV,QAAQ,SAAS,CAAC,OAAO,CAACW;YAElD,MAAMC,SAASxB,cAAcC;YAC7B,IAAI,CAACuB,QAAQ;gBACTH,gBAAgB,OAAO;gBACvB,OAAOpB;YACX;YAMA,IAAIqB,gBAAgB,WAAW,GAAG,WAAW,IAAI;gBAC7CD,gBAAgB,OAAO;gBACvB,OAAOpB;YACX;YAMA,MAAMwB,eACFH,gBAAgB,sBAAsB,MACrC,MAAMI,oBAAoBJ;YAE/B,IAAI,CAACG,cAAc;gBAMfJ,gBAAgB,OAAO;gBACvB,OAAOpB;YACX;YAEA,IAAIK,aAAuB,EAAE;YAC7B,IAAIqB,YAAY;YAChB,IAAIC,MAAM;YACV,IAAI;gBACA,MAAMf,UAAUD,QAAQ,SAAS,CAAC,OAAO,CAACE;gBAC1CR,aAAaF,mBAAmBS,QAAQ,IAAI;gBAC5Cc,YAAYf,QAAQ,SAAS,CAAC,OAAO,CAACiB,WAAW,KAAK;gBAMtDD,MAAMf,QAAQ,GAAG,IAAI;YACzB,EAAE,OAAM,CAER;YAEA,MAAMiB,SAAiC;gBACnC,MAAMC;gBACNP;gBACAG;gBACArB;gBACAsB;YACJ;YAEA,MAAMP,gBAAgB,KAAK,CAACS;QAChC,EAAE,OAAOE,IAAI;YAITC,QAAQ,KAAK,CACT,6BACAD,cAAcE,QAAQ,GAAGF,GAAG,IAAI,CAAC,EAAE,EAAEA,GAAG,OAAO,EAAE,GAAG;YAExD,IAAI;gBACApB,QAAQ,SAAS,CAAC,OAAO,CAACM,UAAU,OAAO;YAC/C,EAAE,OAAM,CAER;QACJ;QAMA,OAAOjB;IACX;AAGG,MAAMkC,wBAAwB,IAC1B;QAACzB;QAAqBS;KAAoB"}

package/features/debugger/serialize.d.ts

@@ -0,0 +1,11 @@
+import type { IDebuggerLimits } from "./limits.js";
+export interface ISerializeResult {
+    json: string;
+    bytes: number;
+    /** True if the value was replaced by the per-entry cap marker. */
+    truncated: boolean;
+}
+/**
+ * Serializes a captured payload to JSON, never throwing and always producing valid JSON.
+ */
+export declare const serialize: (value: unknown, limits: IDebuggerLimits) => ISerializeResult;