@expressots/studio-agent 4.0.0-preview.1

package/dist/instrumentation/tracer.js

@@ -0,0 +1,190 @@
+/**
+ * OpenTelemetry tracer configuration for ExpressoTS Studio
+ */
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from '@opentelemetry/semantic-conventions';
+import { trace, context, SpanKind, SpanStatusCode } from '@opentelemetry/api';
+/** Custom span processor that emits spans to Studio */
+export class StudioSpanProcessor {
+    spans = new Map();
+    onTraceComplete;
+    traceTimeouts = new Map();
+    traceCompletionDelay = 1000; // Wait 1 second for all spans
+    constructor(onTraceComplete) {
+        this.onTraceComplete = onTraceComplete;
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+    onStart(_span) {
+        // Span started - can emit event if needed
+    }
+    onEnd(span) {
+        const traceId = span.spanContext().traceId;
+        const spanInfo = this.convertSpan(span);
+        if (!this.spans.has(traceId)) {
+            this.spans.set(traceId, []);
+        }
+        this.spans.get(traceId).push(spanInfo);
+        // Reset timeout for this trace
+        const existingTimeout = this.traceTimeouts.get(traceId);
+        if (existingTimeout) {
+            clearTimeout(existingTimeout);
+        }
+        // Set new timeout to complete the trace
+        const timeout = setTimeout(() => {
+            this.completeTrace(traceId);
+        }, this.traceCompletionDelay);
+        this.traceTimeouts.set(traceId, timeout);
+    }
+    completeTrace(traceId) {
+        const spans = this.spans.get(traceId);
+        if (!spans || spans.length === 0)
+            return;
+        // Find root span (one without parent or with parent not in this trace)
+        const spanIds = new Set(spans.map((s) => s.spanId));
+        const rootSpan = spans.find((s) => !s.parentSpanId || !spanIds.has(s.parentSpanId)) || spans[0];
+        const traceInfo = {
+            traceId,
+            rootSpan,
+            spans: spans.sort((a, b) => a.startTime - b.startTime),
+            startTime: Math.min(...spans.map((s) => s.startTime)),
+            endTime: Math.max(...spans.map((s) => s.endTime)),
+            duration: 0,
+        };
+        traceInfo.duration = traceInfo.endTime - traceInfo.startTime;
+        this.onTraceComplete?.(traceInfo);
+        // Cleanup
+        this.spans.delete(traceId);
+        this.traceTimeouts.delete(traceId);
+    }
+    convertSpan(span) {
+        const attributes = {};
+        for (const [key, value] of Object.entries(span.attributes)) {
+            if (typeof value === 'string' ||
+                typeof value === 'number' ||
+                typeof value === 'boolean') {
+                attributes[key] = value;
+            }
+            else if (value !== undefined) {
+                attributes[key] = String(value);
+            }
+        }
+        return {
+            traceId: span.spanContext().traceId,
+            spanId: span.spanContext().spanId,
+            parentSpanId: span.parentSpanContext?.spanId,
+            name: span.name,
+            kind: this.getSpanKindName(span.kind),
+            startTime: span.startTime[0] * 1000 + span.startTime[1] / 1e6,
+            endTime: span.endTime[0] * 1000 + span.endTime[1] / 1e6,
+            duration: (span.endTime[0] - span.startTime[0]) * 1000 +
+                (span.endTime[1] - span.startTime[1]) / 1e6,
+            status: this.getStatusName(span.status.code),
+            attributes,
+            events: span.events.map((e) => ({
+                name: e.name,
+                timestamp: e.time[0] * 1000 + e.time[1] / 1e6,
+                attributes: e.attributes,
+            })),
+        };
+    }
+    getSpanKindName(kind) {
+        switch (kind) {
+            case SpanKind.SERVER:
+                return 'SERVER';
+            case SpanKind.CLIENT:
+                return 'CLIENT';
+            case SpanKind.PRODUCER:
+                return 'PRODUCER';
+            case SpanKind.CONSUMER:
+                return 'CONSUMER';
+            default:
+                return 'INTERNAL';
+        }
+    }
+    getStatusName(code) {
+        switch (code) {
+            case SpanStatusCode.OK:
+                return 'OK';
+            case SpanStatusCode.ERROR:
+                return 'ERROR';
+            default:
+                return 'UNSET';
+        }
+    }
+    shutdown() {
+        for (const timeout of this.traceTimeouts.values()) {
+            clearTimeout(timeout);
+        }
+        this.traceTimeouts.clear();
+        this.spans.clear();
+        return Promise.resolve();
+    }
+}
+/** OpenTelemetry SDK wrapper */
+export class StudioTracer {
+    sdk = null;
+    spanProcessor = null;
+    serviceName;
+    serviceVersion;
+    constructor(serviceName = 'expressots-app', serviceVersion = '1.0.0') {
+        this.serviceName = serviceName;
+        this.serviceVersion = serviceVersion;
+    }
+    /** Initialize the OpenTelemetry SDK */
+    async start(onTraceComplete) {
+        this.spanProcessor = new StudioSpanProcessor(onTraceComplete);
+        this.sdk = new NodeSDK({
+            resource: resourceFromAttributes({
+                [ATTR_SERVICE_NAME]: this.serviceName,
+                [ATTR_SERVICE_VERSION]: this.serviceVersion,
+            }),
+            spanProcessors: [this.spanProcessor],
+            instrumentations: [
+                getNodeAutoInstrumentations({
+                    '@opentelemetry/instrumentation-fs': { enabled: false },
+                }),
+            ],
+        });
+        await this.sdk.start();
+    }
+    /** Stop the OpenTelemetry SDK */
+    async stop() {
+        if (this.sdk) {
+            await this.sdk.shutdown();
+            this.sdk = null;
+        }
+    }
+    /** Get the current tracer */
+    getTracer(name = 'studio-agent') {
+        return trace.getTracer(name);
+    }
+    /** Create a custom span */
+    createSpan(name, fn, attributes) {
+        const tracer = this.getTracer();
+        return tracer.startActiveSpan(name, async (span) => {
+            if (attributes) {
+                span.setAttributes(attributes);
+            }
+            try {
+                await fn();
+                span.setStatus({ code: SpanStatusCode.OK });
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+}
+export { trace, context, SpanKind, SpanStatusCode };
+//# sourceMappingURL=tracer.js.map

package/dist/instrumentation/tracer.js.map

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

package/dist/introspection/container-introspector.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Container Introspector
+ *
+ * Builds a DI snapshot (bindings + summary + dependency graph) from an
+ * ExpressoTS `AppContainer` and tracks which bindings are resolved during
+ * each request via Inversify's middleware hook + AsyncLocalStorage.
+ *
+ * Designed to fail gracefully: if the container is missing, if it isn't
+ * the expected ExpressoTS/Inversify shape, or if Reflect metadata is
+ * unavailable, every method returns an empty result instead of throwing.
+ */
+export interface BindingNode {
+    id: string;
+    serviceIdentifier: string;
+    className: string;
+    scope: string;
+    type: string;
+    activated: boolean;
+    cached: boolean;
+    moduleId?: number | string | null;
+}
+export interface BindingEdge {
+    source: string;
+    target: string;
+}
+export interface ContainerSnapshot {
+    bindings: BindingNode[];
+    edges: BindingEdge[];
+    summary: {
+        total: number;
+        byScope: Record<string, number>;
+        byType: Record<string, number>;
+        cached: number;
+        activated: number;
+    };
+    options?: Record<string, unknown>;
+    timestamp: string;
+    containerId: number;
+}
+interface RequestContext {
+    traceId?: string;
+    resolved: Set<string>;
+}
+export declare class ContainerIntrospector {
+    private appContainer;
+    private als;
+    private snapshot;
+    constructor(appContainer: unknown);
+    /** Whether we have a usable AppContainer / Inversify container reference. */
+    isAvailable(): boolean;
+    /** Builds the snapshot once and caches it. */
+    capture(): ContainerSnapshot;
+    /**
+     * Installs an Inversify middleware that records every `container.get(...)`
+     * resolution into the active request's resolved-set. Safe to call once.
+     */
+    installResolutionTracker(): void;
+    /**
+     * Runs `fn` inside a request scope so resolutions get attributed to a
+     * traceId. Returns the set of resolved service identifiers when the
+     * callback completes.
+     */
+    runWithRequest<T>(traceId: string | undefined, fn: () => T): {
+        result: T;
+        resolved: Set<string>;
+    };
+    /** Get the current request context (or undefined when not in a request). */
+    getCurrentRequest(): RequestContext | undefined;
+    private getInversifyContainer;
+    private scanBindings;
+    /**
+     * Reads inversify's constructor-injection metadata and returns the list of
+     * service identifiers each constructor parameter depends on.
+     */
+    private getConstructorDependencies;
+    private computeSummary;
+    private formatServiceIdentifier;
+    private emptySnapshot;
+}
+export {};
+//# sourceMappingURL=container-introspector.d.ts.map

package/dist/introspection/container-introspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-introspector.d.ts","sourceRoot":"","sources":["../../src/introspection/container-introspector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB;AAcD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,GAAG,CAAoC;IAC/C,OAAO,CAAC,QAAQ,CAAkC;gBAEtC,YAAY,EAAE,OAAO;IAKjC,6EAA6E;IAC7E,WAAW,IAAI,OAAO;IAMtB,8CAA8C;IAC9C,OAAO,IAAI,iBAAiB;IAgC5B;;;OAGG;IACH,wBAAwB,IAAI,IAAI;IA2BhC;;;;OAIG;IACH,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG;QAC3D,MAAM,EAAE,CAAC,CAAC;QACV,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;KACvB;IAMD,4EAA4E;IAC5E,iBAAiB,IAAI,cAAc,GAAG,SAAS;IAQ/C,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,YAAY;IA0DpB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAoClC,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,aAAa;CAUtB"}

package/dist/introspection/container-introspector.js

@@ -0,0 +1,251 @@
+/**
+ * Container Introspector
+ *
+ * Builds a DI snapshot (bindings + summary + dependency graph) from an
+ * ExpressoTS `AppContainer` and tracks which bindings are resolved during
+ * each request via Inversify's middleware hook + AsyncLocalStorage.
+ *
+ * Designed to fail gracefully: if the container is missing, if it isn't
+ * the expected ExpressoTS/Inversify shape, or if Reflect metadata is
+ * unavailable, every method returns an empty result instead of throwing.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Reflect metadata keys used by Inversify (vendored copy in @expressots/core). */
+const INVERSIFY_TAGGED = 'inversify:tagged';
+const INVERSIFY_TAGGED_PROPS = 'inversify:tagged_props';
+/**
+ * Typed view of `Reflect.getMetadata` (provided by `reflect-metadata` which
+ * `inversify` already loads — but our local `tsconfig` doesn't pull in those
+ * type declarations, so we cast through `any` for compile time).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ReflectAny = Reflect;
+export class ContainerIntrospector {
+    appContainer;
+    als;
+    snapshot = null;
+    constructor(appContainer) {
+        this.appContainer = appContainer;
+        this.als = new AsyncLocalStorage();
+    }
+    /** Whether we have a usable AppContainer / Inversify container reference. */
+    isAvailable() {
+        if (!this.appContainer)
+            return false;
+        const inversify = this.getInversifyContainer();
+        return Boolean(inversify);
+    }
+    /** Builds the snapshot once and caches it. */
+    capture() {
+        if (this.snapshot)
+            return this.snapshot;
+        const inversify = this.getInversifyContainer();
+        if (!inversify) {
+            this.snapshot = this.emptySnapshot();
+            return this.snapshot;
+        }
+        let introspection = null;
+        try {
+            introspection = typeof this.appContainer.introspect === 'function'
+                ? this.appContainer.introspect()
+                : null;
+        }
+        catch {
+            introspection = null;
+        }
+        const { nodes, edges } = this.scanBindings(inversify);
+        const summary = this.computeSummary(nodes);
+        this.snapshot = {
+            bindings: nodes,
+            edges,
+            summary,
+            options: introspection?.options ?? {},
+            timestamp: new Date().toISOString(),
+            containerId: introspection?.containerId ?? inversify?.id ?? -1,
+        };
+        return this.snapshot;
+    }
+    /**
+     * Installs an Inversify middleware that records every `container.get(...)`
+     * resolution into the active request's resolved-set. Safe to call once.
+     */
+    installResolutionTracker() {
+        const inversify = this.getInversifyContainer();
+        if (!inversify || typeof inversify.applyMiddleware !== 'function') {
+            return;
+        }
+        const als = this.als;
+        const trackingMiddleware = (planAndResolve) => (args) => {
+            const ctx = als.getStore();
+            if (ctx) {
+                try {
+                    ctx.resolved.add(this.formatServiceIdentifier(args?.serviceIdentifier));
+                }
+                catch {
+                    // Tracking is best-effort; never break resolution.
+                }
+            }
+            return planAndResolve(args);
+        };
+        try {
+            inversify.applyMiddleware(trackingMiddleware);
+        }
+        catch {
+            // Older Inversify versions or wrapped containers may not allow this.
+            // Failing to track per-request resolutions is non-fatal.
+        }
+    }
+    /**
+     * Runs `fn` inside a request scope so resolutions get attributed to a
+     * traceId. Returns the set of resolved service identifiers when the
+     * callback completes.
+     */
+    runWithRequest(traceId, fn) {
+        const ctx = { traceId, resolved: new Set() };
+        const result = this.als.run(ctx, fn);
+        return { result, resolved: ctx.resolved };
+    }
+    /** Get the current request context (or undefined when not in a request). */
+    getCurrentRequest() {
+        return this.als.getStore();
+    }
+    // ────────────────────────────────────────────────────────────────────────
+    // Internals
+    // ────────────────────────────────────────────────────────────────────────
+    getInversifyContainer() {
+        if (!this.appContainer)
+            return null;
+        // ExpressoTS AppContainer exposes `Container` as the inversify instance.
+        const inv = this.appContainer.Container ??
+            this.appContainer.container ??
+            this.appContainer;
+        if (!inv)
+            return null;
+        if (!inv._bindingDictionary)
+            return null;
+        return inv;
+    }
+    scanBindings(inversify) {
+        const nodes = [];
+        const edges = [];
+        const dict = inversify._bindingDictionary;
+        const map = dict?._map;
+        if (!map)
+            return { nodes, edges };
+        // First pass: build all nodes so we know which service identifiers exist.
+        const sidToNodeId = new Map();
+        for (const [sid, bindings] of map) {
+            for (const binding of bindings) {
+                const sidStr = this.formatServiceIdentifier(sid);
+                const impl = binding?.implementationType;
+                const className = (impl && impl.name) || sidStr;
+                // Unique id per binding (multiple bindings may share an identifier).
+                const id = `${sidStr}#${nodes.length}`;
+                nodes.push({
+                    id,
+                    serviceIdentifier: sidStr,
+                    className,
+                    scope: String(binding?.scope ?? 'Singleton'),
+                    type: String(binding?.type ?? 'Instance'),
+                    activated: Boolean(binding?.activated),
+                    cached: binding?.cache !== null && binding?.cache !== undefined,
+                    moduleId: binding?.moduleId ?? null,
+                });
+                if (!sidToNodeId.has(sidStr)) {
+                    sidToNodeId.set(sidStr, id);
+                }
+            }
+        }
+        // Second pass: emit edges using inversify's tagged-paramtypes metadata.
+        for (const [sid, bindings] of map) {
+            for (const binding of bindings) {
+                const impl = binding?.implementationType;
+                if (!impl)
+                    continue;
+                const sidStr = this.formatServiceIdentifier(sid);
+                const sourceId = sidToNodeId.get(sidStr);
+                if (!sourceId)
+                    continue;
+                const deps = this.getConstructorDependencies(impl);
+                for (const depSid of deps) {
+                    const targetId = sidToNodeId.get(depSid);
+                    if (targetId) {
+                        edges.push({ source: sourceId, target: targetId });
+                    }
+                }
+            }
+        }
+        return { nodes, edges };
+    }
+    /**
+     * Reads inversify's constructor-injection metadata and returns the list of
+     * service identifiers each constructor parameter depends on.
+     */
+    getConstructorDependencies(impl) {
+        const out = [];
+        if (!impl)
+            return out;
+        // Inversify stores `@inject(SID)` constructor params under "inversify:tagged"
+        // keyed by the prototype + index. The simpler `inversify:paramtypes` key on
+        // the prototype gives the TS design types — useful as a fallback.
+        const tagged = ReflectAny.getMetadata?.(INVERSIFY_TAGGED, impl);
+        if (tagged && typeof tagged.forEach === 'function') {
+            tagged.forEach((metadataList) => {
+                for (const m of metadataList || []) {
+                    if (m?.key === 'inject' && m?.value !== undefined) {
+                        out.push(this.formatServiceIdentifier(m.value));
+                    }
+                }
+            });
+        }
+        // Property-injected dependencies via @inject() on properties.
+        const taggedProps = ReflectAny.getMetadata?.(INVERSIFY_TAGGED_PROPS, impl);
+        if (taggedProps && typeof taggedProps === 'object') {
+            for (const propKey of Object.keys(taggedProps)) {
+                for (const m of taggedProps[propKey] || []) {
+                    if (m?.key === 'inject' && m?.value !== undefined) {
+                        out.push(this.formatServiceIdentifier(m.value));
+                    }
+                }
+            }
+        }
+        return out;
+    }
+    computeSummary(nodes) {
+        const byScope = {};
+        const byType = {};
+        let cached = 0;
+        let activated = 0;
+        for (const n of nodes) {
+            byScope[n.scope] = (byScope[n.scope] ?? 0) + 1;
+            byType[n.type] = (byType[n.type] ?? 0) + 1;
+            if (n.cached)
+                cached++;
+            if (n.activated)
+                activated++;
+        }
+        return { total: nodes.length, byScope, byType, cached, activated };
+    }
+    formatServiceIdentifier(sid) {
+        if (sid == null)
+            return 'unknown';
+        if (typeof sid === 'string')
+            return sid;
+        if (typeof sid === 'symbol')
+            return sid.toString();
+        if (typeof sid === 'function')
+            return sid.name || sid.toString();
+        return String(sid);
+    }
+    emptySnapshot() {
+        return {
+            bindings: [],
+            edges: [],
+            summary: { total: 0, byScope: {}, byType: {}, cached: 0, activated: 0 },
+            options: {},
+            timestamp: new Date().toISOString(),
+            containerId: -1,
+        };
+    }
+}
+//# sourceMappingURL=container-introspector.js.map

package/dist/introspection/container-introspector.js.map

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

package/dist/logging/log-capture.d.ts

@@ -0,0 +1,58 @@
+/**
+ * LogCapture — intercepts `console.*` calls so Studio can stream the app's
+ * stdout/stderr alongside requests, correlated by traceId when available.
+ *
+ * Design notes:
+ * - We patch the global `console` once at agent startup and forward to the
+ *   originals untouched, so the user still sees their logs in their own
+ *   terminal exactly as before.
+ * - A per-process AsyncLocalStorage carries the active traceId, populated
+ *   by the Studio middleware. Logs emitted inside that scope are tagged.
+ * - A re-entry guard prevents infinite recursion if a listener — or its
+ *   transitive dependencies — happens to log.
+ * - The buffer is bounded (default 1000 lines) and drops oldest first.
+ */
+export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: number;
+    traceId?: string;
+}
+export declare class LogCapture {
+    private buffer;
+    private readonly maxBuffer;
+    /**
+     * The "currently-installed" implementation for each level. Reading
+     * `console[level]` always returns a stable wrapper that delegates to
+     * the value stored here, so callers that assign to `console[level]`
+     * (e.g. ExpressoTS's startup buffering, then its restore) end up
+     * updating the cell instead of replacing our wrapper.
+     */
+    private readonly current;
+    private listeners;
+    private installed;
+    constructor(maxBuffer?: number);
+    /**
+     * Install a permanent hook on each console method. Uses an accessor
+     * property so subsequent `console.log = …` assignments (which the
+     * framework performs during its startup buffering lifecycle) are
+     * absorbed by our setter rather than wiping out the wrapper.
+     */
+    install(): void;
+    /** Restore the original console methods (used in tests / hot-reload). */
+    uninstall(): void;
+    /**
+     * Run `fn` inside a request scope so any `console.*` calls during the
+     * request body are tagged with the given traceId.
+     */
+    runWith<T>(traceId: string, fn: () => T): T;
+    /** Subscribe to live log events. Returns an unsubscribe function. */
+    onLog(listener: (entry: LogEntry) => void): () => void;
+    /** Snapshot of the in-memory ring buffer (oldest first). */
+    getBuffer(): LogEntry[];
+    /** Clear the in-memory buffer. */
+    clear(): void;
+    private handleLog;
+}
+//# sourceMappingURL=log-capture.d.ts.map

package/dist/logging/log-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-capture.d.ts","sourceRoot":"","sources":["../../src/logging/log-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnE,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAcD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqD;IAC7E,OAAO,CAAC,SAAS,CAAwC;IACzD,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,SAAO;IAI5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAqDf,yEAAyE;IACzE,SAAS,IAAI,IAAI;IAiBjB;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAI3C,qEAAqE;IACrE,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;IAKtD,4DAA4D;IAC5D,SAAS,IAAI,QAAQ,EAAE;IAIvB,kCAAkC;IAClC,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,SAAS;CAuBlB"}