@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/telemetry/trace.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Helpers for working with trace context across boundaries.
+ * Provides utilities for W3C traceparent headers, distributed tracing,
+ * custom span creation, and context propagation across async boundaries.
+ * @module src/utils/telemetry/trace
+ */
+import { type Span } from '@opentelemetry/api';
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Parsed fields from a W3C `traceparent` header (`00-<traceId>-<spanId>-<flags>`).
+ * Used to propagate distributed trace context across service boundaries.
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export interface TraceparentInfo {
+    /** Whether the trace is sampled (flags byte `01` = sampled, `00` = not sampled). */
+    sampled: boolean;
+    /** W3C parent span ID — 16 lowercase hex characters identifying the caller's span. */
+    spanId: string;
+    /** W3C trace ID — 32 lowercase hex characters shared across the entire distributed trace. */
+    traceId: string;
+}
+/**
+ * Builds a W3C `traceparent` header value from a `RequestContext` or the currently active span.
+ * Uses `ctx.traceId`/`ctx.spanId` when provided; falls back to the active OTel span context.
+ * The version field is always `00` and the flags byte is hardcoded to `01` (sampled).
+ * Returns `undefined` when neither source yields a trace ID and span ID.
+ *
+ * @param ctx - Optional RequestContext containing `traceId` and `spanId`
+ * @returns Formatted `traceparent` string (e.g., `00-<traceId>-<spanId>-01`), or `undefined`
+ *
+ * @example
+ * ```typescript
+ * const traceparent = buildTraceparent(requestContext);
+ * if (traceparent) {
+ *   fetch(url, { headers: { traceparent } });
+ * }
+ * ```
+ */
+export declare function buildTraceparent(ctx?: RequestContext): string | undefined;
+/**
+ * Extracts W3C traceparent from headers and returns parsed trace/span IDs.
+ * Returns undefined if header is missing or malformed.
+ *
+ * @param headers - Headers object (Web API Headers or plain object)
+ * @returns Parsed traceparent info or undefined
+ *
+ * @example
+ * ```typescript
+ * // Extract trace context from incoming request
+ * const trace = extractTraceparent(request.headers);
+ * if (trace) {
+ *   logger.info('Processing with parent trace', {
+ *     traceId: trace.traceId,
+ *     sampled: trace.sampled
+ *   });
+ * }
+ * ```
+ */
+export declare function extractTraceparent(headers: Headers | Record<string, string | undefined>): TraceparentInfo | undefined;
+/**
+ * Creates a child RequestContext with parent trace context extracted from headers.
+ * Useful for propagating trace context from incoming HTTP requests.
+ *
+ * @param parentHeaders - Headers containing traceparent
+ * @param operation - Operation name for the new context
+ * @returns New RequestContext with inherited trace context
+ *
+ * @example
+ * ```typescript
+ * // In HTTP handler
+ * const context = createContextWithParentTrace(
+ *   request.headers,
+ *   'handleApiRequest'
+ * );
+ * logger.info('Processing request', context);
+ * ```
+ */
+export declare function createContextWithParentTrace(parentHeaders: Headers | Record<string, string | undefined>, operation: string): RequestContext;
+/**
+ * Injects the current active context into a carrier, returning it.
+ * Useful for HTTP headers: pass an object and use resulting key/values.
+ *
+ * @param carrier - Object to inject context into (typically headers)
+ * @returns Same carrier with injected trace context
+ *
+ * @example
+ * ```typescript
+ * const headers = injectCurrentContextInto({
+ *   'Content-Type': 'application/json'
+ * });
+ * // headers now contains traceparent, tracestate, etc.
+ * ```
+ */
+export declare function injectCurrentContextInto<T extends Record<string, unknown>>(carrier: T): T;
+/**
+ * Creates a new span for manual instrumentation with automatic error handling.
+ * The span is automatically marked as OK on success or ERROR on exception.
+ * Errors are recorded as exceptions and automatically propagated.
+ *
+ * @param operationName - Name of the span (e.g., 'database.query', 'external.api')
+ * @param fn - Async function to execute within the span
+ * @param attributes - Optional attributes to attach to the span
+ * @returns Promise resolving to the function's return value
+ *
+ * @example
+ * ```typescript
+ * // Instrument a database query
+ * const users = await withSpan(
+ *   'database.query.users',
+ *   async () => db.users.findMany(),
+ *   { 'db.table': 'users', 'db.operation': 'select' }
+ * );
+ * ```
+ */
+export declare function withSpan<T>(operationName: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+/**
+ * Runs a function within the currently active OpenTelemetry context.
+ * Useful for carrying the active context across async boundaries (e.g., `setTimeout`, `queueMicrotask`).
+ *
+ * **Limitation:** When `ctx` contains trace IDs, this function executes within the
+ * current active context rather than restoring `ctx`'s specific span context.
+ * Full span restoration would require span recreation, which this utility intentionally avoids.
+ * If `ctx` has no trace IDs, `fn` is called directly without any context wrapping.
+ *
+ * @param ctx - RequestContext containing trace IDs; if missing or lacking IDs, `fn` runs directly
+ * @param fn - Function to execute within the active OTel context
+ * @returns Result of `fn`
+ *
+ * @example
+ * ```typescript
+ * // Carry the active OTel context into a setTimeout callback
+ * const context = requestContextService.createRequestContext({ operation: 'delayed' });
+ * setTimeout(() => {
+ *   runInContext(context, () => {
+ *     logger.info('Still in trace context', context);
+ *   });
+ * }, 1000);
+ * ```
+ */
+export declare function runInContext<T>(ctx: RequestContext | undefined, fn: () => T): T;
+//# sourceMappingURL=trace.d.ts.map

package/dist/utils/telemetry/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/trace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAGL,KAAK,IAAI,EAGV,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAOzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACpD,eAAe,GAAG,SAAS,CAc7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC3D,SAAS,EAAE,MAAM,GAChB,cAAc,CAShB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAGzF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,aAAa,EAAE,MAAM,EACrB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,OAAO,CAAC,CAAC,CAAC,CA0BZ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAU/E"}

package/dist/utils/telemetry/trace.js

@@ -0,0 +1,193 @@
+/**
+ * @fileoverview Helpers for working with trace context across boundaries.
+ * Provides utilities for W3C traceparent headers, distributed tracing,
+ * custom span creation, and context propagation across async boundaries.
+ * @module src/utils/telemetry/trace
+ */
+import { context as otContext, propagation, SpanStatusCode, trace, } from '@opentelemetry/api';
+import { config } from '../../config/index.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+/**
+ * Builds a W3C `traceparent` header value from a `RequestContext` or the currently active span.
+ * Uses `ctx.traceId`/`ctx.spanId` when provided; falls back to the active OTel span context.
+ * The version field is always `00` and the flags byte is hardcoded to `01` (sampled).
+ * Returns `undefined` when neither source yields a trace ID and span ID.
+ *
+ * @param ctx - Optional RequestContext containing `traceId` and `spanId`
+ * @returns Formatted `traceparent` string (e.g., `00-<traceId>-<spanId>-01`), or `undefined`
+ *
+ * @example
+ * ```typescript
+ * const traceparent = buildTraceparent(requestContext);
+ * if (traceparent) {
+ *   fetch(url, { headers: { traceparent } });
+ * }
+ * ```
+ */
+export function buildTraceparent(ctx) {
+    const traceId = ctx?.traceId ?? trace.getActiveSpan()?.spanContext().traceId;
+    const spanId = ctx?.spanId ?? trace.getActiveSpan()?.spanContext().spanId;
+    if (!traceId || !spanId)
+        return;
+    // We do not currently read flags reliably from context; assume sampled
+    return `00-${traceId}-${spanId}-01`;
+}
+/**
+ * Extracts W3C traceparent from headers and returns parsed trace/span IDs.
+ * Returns undefined if header is missing or malformed.
+ *
+ * @param headers - Headers object (Web API Headers or plain object)
+ * @returns Parsed traceparent info or undefined
+ *
+ * @example
+ * ```typescript
+ * // Extract trace context from incoming request
+ * const trace = extractTraceparent(request.headers);
+ * if (trace) {
+ *   logger.info('Processing with parent trace', {
+ *     traceId: trace.traceId,
+ *     sampled: trace.sampled
+ *   });
+ * }
+ * ```
+ */
+export function extractTraceparent(headers) {
+    const headerValue = headers instanceof Headers ? headers.get('traceparent') : headers.traceparent;
+    if (!headerValue)
+        return;
+    // W3C traceparent format: 00-{traceId}-{spanId}-{flags}
+    const match = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(headerValue);
+    if (!match || !match[1] || !match[2] || !match[3])
+        return;
+    return {
+        traceId: match[1],
+        spanId: match[2],
+        sampled: match[3] === '01',
+    };
+}
+/**
+ * Creates a child RequestContext with parent trace context extracted from headers.
+ * Useful for propagating trace context from incoming HTTP requests.
+ *
+ * @param parentHeaders - Headers containing traceparent
+ * @param operation - Operation name for the new context
+ * @returns New RequestContext with inherited trace context
+ *
+ * @example
+ * ```typescript
+ * // In HTTP handler
+ * const context = createContextWithParentTrace(
+ *   request.headers,
+ *   'handleApiRequest'
+ * );
+ * logger.info('Processing request', context);
+ * ```
+ */
+export function createContextWithParentTrace(parentHeaders, operation) {
+    const traceInfo = extractTraceparent(parentHeaders);
+    return requestContextService.createRequestContext({
+        operation,
+        ...(traceInfo && {
+            traceId: traceInfo.traceId,
+            parentSpanId: traceInfo.spanId,
+        }),
+    });
+}
+/**
+ * Injects the current active context into a carrier, returning it.
+ * Useful for HTTP headers: pass an object and use resulting key/values.
+ *
+ * @param carrier - Object to inject context into (typically headers)
+ * @returns Same carrier with injected trace context
+ *
+ * @example
+ * ```typescript
+ * const headers = injectCurrentContextInto({
+ *   'Content-Type': 'application/json'
+ * });
+ * // headers now contains traceparent, tracestate, etc.
+ * ```
+ */
+export function injectCurrentContextInto(carrier) {
+    propagation.inject(otContext.active(), carrier);
+    return carrier;
+}
+/**
+ * Creates a new span for manual instrumentation with automatic error handling.
+ * The span is automatically marked as OK on success or ERROR on exception.
+ * Errors are recorded as exceptions and automatically propagated.
+ *
+ * @param operationName - Name of the span (e.g., 'database.query', 'external.api')
+ * @param fn - Async function to execute within the span
+ * @param attributes - Optional attributes to attach to the span
+ * @returns Promise resolving to the function's return value
+ *
+ * @example
+ * ```typescript
+ * // Instrument a database query
+ * const users = await withSpan(
+ *   'database.query.users',
+ *   async () => db.users.findMany(),
+ *   { 'db.table': 'users', 'db.operation': 'select' }
+ * );
+ * ```
+ */
+export async function withSpan(operationName, fn, attributes) {
+    const tracer = trace.getTracer(config.openTelemetry.serviceName, config.openTelemetry.serviceVersion);
+    return await tracer.startActiveSpan(operationName, async (span) => {
+        if (attributes) {
+            span.setAttributes(attributes);
+        }
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Runs a function within the currently active OpenTelemetry context.
+ * Useful for carrying the active context across async boundaries (e.g., `setTimeout`, `queueMicrotask`).
+ *
+ * **Limitation:** When `ctx` contains trace IDs, this function executes within the
+ * current active context rather than restoring `ctx`'s specific span context.
+ * Full span restoration would require span recreation, which this utility intentionally avoids.
+ * If `ctx` has no trace IDs, `fn` is called directly without any context wrapping.
+ *
+ * @param ctx - RequestContext containing trace IDs; if missing or lacking IDs, `fn` runs directly
+ * @param fn - Function to execute within the active OTel context
+ * @returns Result of `fn`
+ *
+ * @example
+ * ```typescript
+ * // Carry the active OTel context into a setTimeout callback
+ * const context = requestContextService.createRequestContext({ operation: 'delayed' });
+ * setTimeout(() => {
+ *   runInContext(context, () => {
+ *     logger.info('Still in trace context', context);
+ *   });
+ * }, 1000);
+ * ```
+ */
+export function runInContext(ctx, fn) {
+    // If no trace context, run directly
+    if (!ctx?.traceId || !ctx?.spanId) {
+        return fn();
+    }
+    // Execute within the active context
+    // Note: Full context restoration would require span recreation
+    // This simplified version maintains execution but doesn't create new spans
+    return otContext.with(otContext.active(), fn);
+}
+//# sourceMappingURL=trace.js.map

package/dist/utils/telemetry/trace.js.map

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

package/dist/utils/types/guards.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Type guard utilities for safe runtime type narrowing.
+ * @module utils/types/guards
+ *
+ * Provides reusable type guards to replace unsafe type assertions throughout the codebase.
+ * All guards perform proper runtime validation and narrow TypeScript types safely.
+ */
+/**
+ * Type guard to check if a value is a non-null object.
+ *
+ * @param value - Value to check
+ * @returns True if value is an object (excluding null and arrays)
+ *
+ * @example
+ * ```typescript
+ * if (isObject(someValue)) {
+ *   // someValue is now typed as object
+ *   console.log(someValue.toString());
+ * }
+ * ```
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Type guard to check if a value is a plain record (non-null, non-array object with string keys).
+ *
+ * Arrays are excluded — this guard is intended for key-value objects only.
+ * Delegates to {@link isObject} for the underlying check.
+ *
+ * @param value - Value to check
+ * @returns True if value is a `Record<string, unknown>` (plain object, not null, not an array)
+ *
+ * @example
+ * ```typescript
+ * if (isRecord(data)) {
+ *   // data is now typed as Record<string, unknown>
+ *   const keys = Object.keys(data);
+ * }
+ * ```
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if an object has a specific property.
+ *
+ * @param obj - Object to check
+ * @param key - Property key to look for
+ * @returns True if object has the specified property
+ *
+ * @example
+ * ```typescript
+ * if (hasProperty(error, 'message')) {
+ *   // TypeScript now knows error has a 'message' property
+ *   console.log(error.message);
+ * }
+ * ```
+ */
+export declare function hasProperty<K extends PropertyKey>(obj: unknown, key: K): obj is Record<K, unknown>;
+/**
+ * Type guard to check if an object has a property of a specific type.
+ *
+ * @param obj - Object to check
+ * @param key - Property key to look for
+ * @param typeGuard - Type guard function for the property value
+ * @returns True if object has the property and it matches the type
+ *
+ * @example
+ * ```typescript
+ * if (hasPropertyOfType(obj, 'count', (v): v is number => typeof v === 'number')) {
+ *   // obj.count is now typed as number
+ *   console.log(obj.count + 1);
+ * }
+ * ```
+ */
+export declare function hasPropertyOfType<K extends PropertyKey, T>(obj: unknown, key: K, typeGuard: (value: unknown) => value is T): obj is Record<K, T>;
+/**
+ * Type guard to check if a value is a string.
+ *
+ * @param value - Value to check
+ * @returns True if value is a string
+ *
+ * @example
+ * ```typescript
+ * if (isString(value)) {
+ *   // value is now typed as string
+ *   console.log(value.toUpperCase());
+ * }
+ * ```
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a number.
+ *
+ * `NaN` is explicitly excluded — `typeof NaN === 'number'` is true in JavaScript,
+ * but `NaN` is almost never a valid value in the contexts where this guard is used.
+ *
+ * @param value - Value to check
+ * @returns True if value is a finite or infinite number (excluding NaN)
+ *
+ * @example
+ * ```typescript
+ * if (isNumber(value)) {
+ *   // value is now typed as number (NaN excluded)
+ *   console.log(value.toFixed(2));
+ * }
+ * ```
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Type guard to check if an error is an AggregateError.
+ *
+ * AggregateError contains multiple errors in an 'errors' array property.
+ * This guard safely checks for the errors property without unsafe type assertions.
+ *
+ * @param error - Error to check
+ * @returns True if error is an AggregateError with errors array
+ *
+ * @example
+ * ```typescript
+ * if (isAggregateError(error)) {
+ *   // error.errors is now safely typed as unknown[]
+ *   error.errors.forEach(innerError => console.log(innerError));
+ * }
+ * ```
+ */
+export declare function isAggregateError(error: unknown): error is Error & {
+    errors: unknown[];
+};
+/**
+ * Type guard to check if an error has a code property.
+ *
+ * @param error - Error to check
+ * @returns True if error has a code property
+ *
+ * @example
+ * ```typescript
+ * if (isErrorWithCode(error)) {
+ *   console.log(`Error code: ${error.code}`);
+ * }
+ * ```
+ */
+export declare function isErrorWithCode(error: unknown): error is Error & {
+    code: unknown;
+};
+/**
+ * Type guard to check if an error has a status property.
+ *
+ * @param error - Error to check
+ * @returns True if error has a status property
+ *
+ * @example
+ * ```typescript
+ * if (isErrorWithStatus(error)) {
+ *   console.log(`HTTP status: ${error.status}`);
+ * }
+ * ```
+ */
+export declare function isErrorWithStatus(error: unknown): error is Error & {
+    status: unknown;
+};
+/**
+ * Safely get a property from an object if it exists.
+ *
+ * @param obj - Object to get property from
+ * @param key - Property key
+ * @returns Property value or undefined if property doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const message = getProperty(error, 'message');
+ * // message is typed as unknown
+ * ```
+ */
+export declare function getProperty<K extends PropertyKey>(obj: unknown, key: K): unknown;
+/**
+ * Safely get a string property from an object.
+ *
+ * @param obj - Object to get property from
+ * @param key - Property key
+ * @returns String value or undefined if property doesn't exist or is not a string
+ *
+ * @example
+ * ```typescript
+ * const traceId = getStringProperty(context, 'traceId');
+ * if (traceId) {
+ *   // traceId is typed as string
+ *   console.log(traceId.toUpperCase());
+ * }
+ * ```
+ */
+export declare function getStringProperty<K extends PropertyKey>(obj: unknown, key: K): string | undefined;
+/**
+ * Safely get a number property from an object.
+ *
+ * Returns `undefined` if the property is absent, not a number, or is `NaN`.
+ *
+ * @param obj - Object to get property from
+ * @param key - Property key
+ * @returns Number value or undefined if property doesn't exist, is not a number, or is NaN
+ *
+ * @example
+ * ```typescript
+ * const retries = getNumberProperty(config, 'maxRetries');
+ * if (retries !== undefined) {
+ *   // retries is typed as number
+ *   console.log(`Max retries: ${retries}`);
+ * }
+ * ```
+ */
+export declare function getNumberProperty<K extends PropertyKey>(obj: unknown, key: K): number | undefined;
+//# sourceMappingURL=guards.d.ts.map

package/dist/utils/types/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../../src/utils/types/guards.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAC/C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,CAAC,GACL,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,CAE3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,EACxD,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,CAAC,EACN,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACxC,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAErB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG;IAAE,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAEvF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAElF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAEtF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAEhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAGjG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAGjG"}