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

package/dist/utils/formatting/treeFormatter.js

@@ -0,0 +1,400 @@
+/**
+ * @fileoverview Tree formatter utility for visualizing hierarchical data structures.
+ * Supports ASCII, Unicode box-drawing, and compact tree styles with icons and metadata.
+ * @module src/utils/formatting/treeFormatter
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+/**
+ * Utility class for formatting hierarchical data as tree structures.
+ *
+ * Renders a {@link TreeNode} graph as a multi-line string using ASCII, Unicode
+ * box-drawing, or compact indented styles. Handles arbitrary depth, optional icons,
+ * inline metadata, and detects circular references at render time.
+ *
+ * Use the exported {@link treeFormatter} singleton rather than constructing directly.
+ *
+ * @example
+ * ```typescript
+ * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
+ *
+ * const tree: TreeNode = {
+ *   name: 'src',
+ *   children: [
+ *     { name: 'index.ts' },
+ *     { name: 'utils', children: [{ name: 'helper.ts' }] },
+ *   ],
+ * };
+ *
+ * console.log(treeFormatter.format(tree, { style: 'unicode' }));
+ * // src
+ * // ├── index.ts
+ * // └── utils
+ * //     └── helper.ts
+ * ```
+ */
+export class TreeFormatter {
+    /**
+     * Default formatting options.
+     * @private
+     */
+    defaultOptions = {
+        style: 'unicode',
+        maxDepth: undefined,
+        showMetadata: false,
+        icons: false,
+        indent: '  ',
+        folderIcon: '📁',
+        fileIcon: '📄',
+    };
+    /**
+     * Track seen nodes for circular reference detection.
+     * @private
+     */
+    seenNodes = new Set();
+    /**
+     * Format a single tree into a multi-line string.
+     *
+     * Merges `options` with defaults, resets circular-reference tracking, then
+     * recursively renders each node with branch connectors, optional icons, and
+     * optional metadata. Lines are joined with `\n`.
+     *
+     * @param root - Root node of the tree. Must have a non-empty `name` string.
+     * @param options - Formatting options. Merged with defaults; all fields are optional.
+     * @param context - Optional request context for correlated log output. A new context
+     *   is created automatically when omitted.
+     * @returns Multi-line tree string. The root node appears on the first line with no
+     *   connector prefix; child nodes are indented and prefixed with branch connectors.
+     * @throws {McpError} With code `ValidationError` if `root` is missing or has no `name`.
+     * @throws {McpError} With code `InternalError` if rendering fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const tree = {
+     *   name: 'src',
+     *   children: [
+     *     { name: 'index.ts' },
+     *     {
+     *       name: 'utils',
+     *       children: [
+     *         { name: 'helper.ts' },
+     *         { name: 'types.ts' },
+     *       ],
+     *     },
+     *   ],
+     * };
+     *
+     * console.log(treeFormatter.format(tree, { style: 'unicode', icons: true }));
+     * // 📁 src
+     * // ├── 📄 index.ts
+     * // └── 📁 utils
+     * //     ├── 📄 helper.ts
+     * //     └── 📄 types.ts
+     * ```
+     */
+    format(root, options, context) {
+        const logContext = context ||
+            requestContextService.createRequestContext({
+                operation: 'TreeFormatter.format',
+            });
+        // Validate input
+        if (!root || typeof root.name !== 'string') {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'Root node must have a name property', logContext);
+        }
+        const opts = {
+            ...this.defaultOptions,
+            ...options,
+        };
+        try {
+            // Reset circular reference detection
+            this.seenNodes.clear();
+            logger.debug('Formatting tree structure', {
+                ...logContext,
+                rootName: root.name,
+                style: opts.style,
+            });
+            const lines = [];
+            this.renderNode(root, '', true, true, lines, opts, 0);
+            const result = lines.join('\n');
+            logger.debug('Tree formatted successfully', {
+                ...logContext,
+                lineCount: lines.length,
+            });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof McpError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            const stack = error instanceof Error ? error.stack : undefined;
+            logger.error('Failed to format tree', {
+                ...logContext,
+                error: message,
+            });
+            throw new McpError(JsonRpcErrorCode.InternalError, `Failed to format tree: ${message}`, {
+                ...logContext,
+                originalError: stack,
+            });
+        }
+    }
+    /**
+     * Format multiple independent trees (forest) into a single string.
+     *
+     * Calls {@link format} on each root in order and joins the results with a blank
+     * line (`\n\n`) between them. Useful for rendering several top-level structures
+     * side-by-side in one output block (e.g. `src/`, `tests/`, `docs/`).
+     *
+     * @param roots - Non-empty array of root nodes. Each must satisfy the same
+     *   constraints as the `root` parameter of {@link format}.
+     * @param options - Formatting options applied uniformly to every tree.
+     * @param context - Optional request context for correlated log output. A new context
+     *   is created automatically when omitted.
+     * @returns Each formatted tree separated by a blank line.
+     * @throws {McpError} With code `ValidationError` if `roots` is empty or not an array.
+     * @throws {McpError} With code `ValidationError` / `InternalError` propagated from
+     *   {@link format} if any individual tree fails to render.
+     *
+     * @example
+     * ```typescript
+     * const roots = [
+     *   { name: 'src', children: [{ name: 'index.ts' }] },
+     *   { name: 'tests', children: [{ name: 'index.test.ts' }] },
+     * ];
+     *
+     * console.log(treeFormatter.formatMultiple(roots, { style: 'unicode' }));
+     * // src
+     * // └── index.ts
+     * //
+     * // tests
+     * // └── index.test.ts
+     * ```
+     */
+    formatMultiple(roots, options, context) {
+        const logContext = context ||
+            requestContextService.createRequestContext({
+                operation: 'TreeFormatter.formatMultiple',
+            });
+        if (!Array.isArray(roots) || roots.length === 0) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'Roots must be a non-empty array', logContext);
+        }
+        try {
+            logger.debug('Formatting multiple tree structures', {
+                ...logContext,
+                count: roots.length,
+            });
+            const results = roots.map((root) => this.format(root, options, logContext));
+            return results.join('\n\n');
+        }
+        catch (error) {
+            if (error instanceof McpError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            const stack = error instanceof Error ? error.stack : undefined;
+            throw new McpError(JsonRpcErrorCode.InternalError, `Failed to format multiple trees: ${message}`, { ...logContext, originalError: stack });
+        }
+    }
+    /**
+     * Recursively render a tree node and its children into `lines`.
+     *
+     * Uses a post-order removal strategy for circular-reference detection: the node is
+     * added to `seenNodes` before descending into children and removed afterward, so
+     * the same node can appear in multiple independent branches without false positives —
+     * only true ancestor-descendant cycles are flagged.
+     *
+     * @param node - Current node to render.
+     * @param prefix - String prepended to every line produced by this call and its
+     *   descendants (carries the vertical-connector continuation from parent levels).
+     * @param isRoot - Whether this is the top-level node (suppresses the leading connector).
+     * @param isLast - Whether this node is the last sibling (determines corner vs. tee connector).
+     * @param lines - Accumulator array; rendered lines are pushed here in order.
+     * @param options - Resolved formatting options.
+     * @param depth - Current render depth (0 = root). Used to enforce `maxDepth`.
+     * @private
+     */
+    renderNode(node, prefix, isRoot, isLast, lines, options, depth) {
+        // Check max depth
+        if (options.maxDepth !== undefined && depth > options.maxDepth) {
+            return;
+        }
+        // Check for circular references
+        if (this.seenNodes.has(node)) {
+            lines.push(`${prefix}${this.getConnector('circular', isLast, options.style)} [Circular Reference]`);
+            return;
+        }
+        this.seenNodes.add(node);
+        // Build node line
+        const connector = isRoot ? '' : this.getConnector('node', isLast, options.style);
+        const icon = this.getIcon(node, options);
+        const name = node.name;
+        const metadata = this.formatMetadata(node, options);
+        const line = `${prefix}${connector}${icon}${name}${metadata}`;
+        lines.push(line);
+        // Render children
+        const children = node.children || [];
+        if (children.length > 0) {
+            const childPrefix = isRoot
+                ? ''
+                : prefix + this.getChildPrefix(isLast, options.style, options.indent);
+            children.forEach((child, index) => {
+                const isLastChild = index === children.length - 1;
+                this.renderNode(child, childPrefix, false, isLastChild, lines, options, depth + 1);
+            });
+        }
+        this.seenNodes.delete(node);
+    }
+    /**
+     * Return the branch-connector string that precedes a node's name.
+     *
+     * For `type === 'circular'`, always uses a minimal connector regardless of style
+     * (compact: two spaces; others: corner or tee). For normal nodes, the connector
+     * depends on `style` and whether this is the last sibling.
+     *
+     * @param type - `'node'` for a normal node; `'circular'` for a cycle marker.
+     * @param isLast - Whether this node is the last among its siblings.
+     * @param style - Active tree style.
+     * @returns Connector string (e.g. `'└── '`, `'+-- '`, or `''`).
+     * @private
+     */
+    getConnector(type, isLast, style) {
+        if (type === 'circular') {
+            return style === 'compact' ? '  ' : isLast ? '└─ ' : '├─ ';
+        }
+        switch (style) {
+            case 'unicode':
+                return isLast ? '└── ' : '├── ';
+            case 'ascii':
+                return isLast ? '\\-- ' : '+-- ';
+            case 'compact':
+                return '';
+            default:
+                return '';
+        }
+    }
+    /**
+     * Return the prefix string to prepend to all lines produced by child nodes.
+     *
+     * When the parent is not the last sibling, a vertical connector (`│` for unicode,
+     * `|` for ascii) is prepended and padded to match `indent`'s width, keeping the
+     * tree visually connected. When the parent is last, a blank indent is used instead.
+     *
+     * @param isLast - Whether the parent node is the last among its siblings.
+     * @param style - Active tree style.
+     * @param indent - Configured indentation string (its length determines padding width).
+     * @returns Prefix string to pass as `prefix` when recursing into children.
+     * @private
+     */
+    getChildPrefix(isLast, style, indent) {
+        // When not the last child, replace the first character of indent with a vertical
+        // connector so the tree lines stay visually connected. Pad to match indent width.
+        const padding = indent.length > 1 ? ' '.repeat(indent.length - 1) : '';
+        switch (style) {
+            case 'unicode':
+                return isLast ? indent : `│${padding}`;
+            case 'ascii':
+                return isLast ? indent : `|${padding}`;
+            case 'compact':
+                return indent;
+            default:
+                return indent;
+        }
+    }
+    /**
+     * Return the icon prefix string for a node, or an empty string when icons are disabled.
+     *
+     * A node is treated as a "folder" (uses `folderIcon`) if it has at least one child;
+     * otherwise it uses `fileIcon`. The returned string includes a trailing space so
+     * the icon is separated from the node name.
+     *
+     * @param node - Node to select an icon for.
+     * @param options - Resolved formatting options.
+     * @returns Icon string with trailing space (e.g. `'📁 '`), or `''` if `icons` is false.
+     * @private
+     */
+    getIcon(node, options) {
+        if (!options.icons) {
+            return '';
+        }
+        const hasChildren = node.children && node.children.length > 0;
+        const icon = hasChildren ? options.folderIcon : options.fileIcon;
+        return `${icon} `;
+    }
+    /**
+     * Return the metadata suffix string for a node, or an empty string when metadata display
+     * is disabled or the node has no metadata.
+     *
+     * Entries are formatted as `key=value` pairs joined by `', '` and wrapped in
+     * parentheses: ` (size=1KB, type=text)`. All values are coerced to strings via
+     * `String()`. Returns `''` if the resulting entry list is empty.
+     *
+     * @param node - Node whose `metadata` record to format.
+     * @param options - Resolved formatting options (`showMetadata` must be `true` to emit output).
+     * @returns Metadata suffix string (e.g. `' (size=1KB)'`) or `''`.
+     * @private
+     */
+    formatMetadata(node, options) {
+        if (!options.showMetadata || !node.metadata) {
+            return '';
+        }
+        const entries = Object.entries(node.metadata)
+            .map(([key, value]) => `${key}=${String(value)}`)
+            .join(', ');
+        return entries ? ` (${entries})` : '';
+    }
+}
+/**
+ * Singleton instance of TreeFormatter.
+ * Use this instance to format hierarchical data as tree structures.
+ *
+ * @example
+ * ```typescript
+ * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
+ *
+ * // Simple directory tree
+ * const tree = {
+ *   name: 'project',
+ *   children: [
+ *     {
+ *       name: 'src',
+ *       children: [
+ *         { name: 'index.ts' },
+ *         { name: 'types.ts' }
+ *       ]
+ *     },
+ *     { name: 'package.json' },
+ *     { name: 'README.md' }
+ *   ]
+ * };
+ *
+ * // Unicode tree with icons
+ * console.log(treeFormatter.format(tree, {
+ *   style: 'unicode',
+ *   icons: true
+ * }));
+ * // 📁 project
+ * // ├── 📁 src
+ * // │   ├── 📄 index.ts
+ * // │   └── 📄 types.ts
+ * // ├── 📄 package.json
+ * // └── 📄 README.md
+ *
+ * // With metadata
+ * const treeWithMeta = {
+ *   name: 'files',
+ *   metadata: { count: 3 },
+ *   children: [
+ *     { name: 'file1.txt', metadata: { size: '1KB' } },
+ *     { name: 'file2.txt', metadata: { size: '2KB' } }
+ *   ]
+ * };
+ *
+ * console.log(treeFormatter.format(treeWithMeta, { showMetadata: true }));
+ * // files (count=3)
+ * // ├── file1.txt (size=1KB)
+ * // └── file2.txt (size=2KB)
+ * ```
+ */
+export const treeFormatter = new TreeFormatter();
+//# sourceMappingURL=treeFormatter.js.map

package/dist/utils/formatting/treeFormatter.js.map

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

package/dist/utils/internal/encoding.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Encodes an ArrayBuffer into a base64 string in a cross-platform manner.
+ * Prefers Node.js Buffer for performance if available, otherwise uses a
+ * chunked `btoa` fallback to avoid stack overflow on large buffers.
+ *
+ * @param buffer - The ArrayBuffer to encode.
+ * @returns The base64-encoded string.
+ * @example
+ * ```typescript
+ * const buf = new TextEncoder().encode('hello').buffer;
+ * arrayBufferToBase64(buf); // 'aGVsbG8='
+ * ```
+ */
+export declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+/**
+ * Encodes a UTF-8 string to base64 in a cross-platform manner.
+ * Prefers Node.js Buffer for performance if available, otherwise uses
+ * TextEncoder + {@link arrayBufferToBase64} for Cloudflare Workers compatibility.
+ *
+ * @param str - The UTF-8 string to encode.
+ * @returns The base64-encoded string.
+ * @example
+ * ```typescript
+ * stringToBase64('hello'); // 'aGVsbG8='
+ * ```
+ */
+export declare function stringToBase64(str: string): string;
+/**
+ * Decodes a base64-encoded string to UTF-8 in a cross-platform manner.
+ * Prefers Node.js Buffer for performance if available, otherwise uses
+ * `atob` + TextDecoder for Cloudflare Workers compatibility.
+ *
+ * @param base64 - The base64-encoded string to decode.
+ * @returns The decoded UTF-8 string.
+ * @throws {Error} If the input is not valid base64 (thrown by `Buffer` or `atob`).
+ * @example
+ * ```typescript
+ * base64ToString('aGVsbG8='); // 'hello'
+ * ```
+ */
+export declare function base64ToString(base64: string): string;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/utils/internal/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/encoding.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAgB/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAarD"}

package/dist/utils/internal/encoding.js

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Provides cross-platform encoding utilities.
+ * @module src/utils/internal/encoding
+ */
+import { runtimeCaps } from './runtime.js';
+/**
+ * Encodes an ArrayBuffer into a base64 string in a cross-platform manner.
+ * Prefers Node.js Buffer for performance if available, otherwise uses a
+ * chunked `btoa` fallback to avoid stack overflow on large buffers.
+ *
+ * @param buffer - The ArrayBuffer to encode.
+ * @returns The base64-encoded string.
+ * @example
+ * ```typescript
+ * const buf = new TextEncoder().encode('hello').buffer;
+ * arrayBufferToBase64(buf); // 'aGVsbG8='
+ * ```
+ */
+export function arrayBufferToBase64(buffer) {
+    if (runtimeCaps.hasBuffer) {
+        // Node.js environment
+        return Buffer.from(buffer).toString('base64');
+    }
+    else {
+        // Browser/Worker environment — chunked to avoid stack overflow on large buffers
+        const bytes = new Uint8Array(buffer);
+        const chunks = [];
+        const CHUNK_SIZE = 0x8000; // 32KB
+        for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+            chunks.push(String.fromCharCode.apply(null, bytes.subarray(i, i + CHUNK_SIZE)));
+        }
+        return btoa(chunks.join(''));
+    }
+}
+/**
+ * Encodes a UTF-8 string to base64 in a cross-platform manner.
+ * Prefers Node.js Buffer for performance if available, otherwise uses
+ * TextEncoder + {@link arrayBufferToBase64} for Cloudflare Workers compatibility.
+ *
+ * @param str - The UTF-8 string to encode.
+ * @returns The base64-encoded string.
+ * @example
+ * ```typescript
+ * stringToBase64('hello'); // 'aGVsbG8='
+ * ```
+ */
+export function stringToBase64(str) {
+    if (runtimeCaps.hasBuffer) {
+        // Node.js environment - most performant
+        return Buffer.from(str, 'utf-8').toString('base64');
+    }
+    else {
+        // Worker/Browser environment - use Web APIs
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(str);
+        return arrayBufferToBase64(bytes.buffer);
+    }
+}
+/**
+ * Decodes a base64-encoded string to UTF-8 in a cross-platform manner.
+ * Prefers Node.js Buffer for performance if available, otherwise uses
+ * `atob` + TextDecoder for Cloudflare Workers compatibility.
+ *
+ * @param base64 - The base64-encoded string to decode.
+ * @returns The decoded UTF-8 string.
+ * @throws {Error} If the input is not valid base64 (thrown by `Buffer` or `atob`).
+ * @example
+ * ```typescript
+ * base64ToString('aGVsbG8='); // 'hello'
+ * ```
+ */
+export function base64ToString(base64) {
+    if (runtimeCaps.hasBuffer) {
+        // Node.js environment - most performant
+        return Buffer.from(base64, 'base64').toString('utf-8');
+    }
+    else {
+        // Worker/Browser environment - use Web APIs
+        const decoded = atob(base64);
+        const bytes = new Uint8Array(decoded.length);
+        for (let i = 0; i < decoded.length; i++) {
+            bytes[i] = decoded.charCodeAt(i);
+        }
+        return new TextDecoder().decode(bytes);
+    }
+}
+//# sourceMappingURL=encoding.js.map

package/dist/utils/internal/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../../src/utils/internal/encoding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC1B,sBAAsB;QACtB,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,gFAAgF;QAChF,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,MAAM,CAAC,CAAC,OAAO;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,UAAU,EAAE,CAAC;YAClD,MAAM,CAAC,IAAI,CACT,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAwB,CAAC,CAC1F,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC1B,wCAAwC;QACxC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN,4CAA4C;QAC5C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAClC,OAAO,mBAAmB,CAAC,KAAK,CAAC,MAAqB,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;QAC1B,wCAAwC;QACxC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;SAAM,CAAC;QACN,4CAA4C;QAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;AACH,CAAC"}