ai-prompt-guide-mcp 1.0.0

package/dist/shared/reference-loader.js

@@ -0,0 +1,265 @@
+/**
+ * Reference loading system for hierarchical content loading
+ *
+ * This module provides recursive loading of documents and their references
+ * to build hierarchical content structures with cycle detection and depth limits.
+ *
+ * Key Features:
+ * - Recursive reference loading with depth control
+ * - Cycle detection to prevent infinite loops
+ * - Hierarchical content organization
+ * - Integration with existing DocumentManager
+ * - Namespace-aware content loading
+ */
+import { ReferenceExtractor } from './reference-extractor.js';
+import { pathToNamespace } from './path-utilities.js';
+import { getGlobalLogger } from '../utils/logger.js';
+import { AccessContext } from '../document-cache.js';
+const logger = getGlobalLogger();
+/**
+ * Reference loading system with hierarchical content organization
+ *
+ * Provides recursive loading of documents and their references
+ * with intelligent cycle detection and depth management.
+ */
+export class ReferenceLoader {
+    extractor;
+    MAX_TOTAL_NODES = 1000;
+    DEFAULT_TIMEOUT_MS = 30000; // 30 seconds
+    constructor() {
+        this.extractor = new ReferenceExtractor();
+    }
+    /**
+     * Load references recursively to build hierarchical content structure
+     *
+     * Processes normalized references and loads their target documents,
+     * recursively processing nested references up to specified depth.
+     *
+     * @param refs - Array of normalized references to load
+     * @param manager - DocumentManager for loading documents
+     * @param maxDepth - Maximum recursion depth (default: 3)
+     * @param currentDepth - Current recursion depth (default: 0)
+     * @param visitedPaths - Set of visited paths for cycle detection (internal use)
+     * @param totalNodesLoaded - Node count tracker across all branches (internal use)
+     * @param startTime - Operation start timestamp for timeout tracking (internal use)
+     * @returns Promise resolving to hierarchical content array
+     *
+     * @example Basic reference loading
+     * ```typescript
+     * const loader = new ReferenceLoader();
+     * const extractor = new ReferenceExtractor();
+     *
+     * const refs = extractor.normalizeReferences(
+     *   ['@/api/auth.md', '@/api/tokens.md'],
+     *   '/current/doc.md'
+     * );
+     *
+     * const hierarchy = await loader.loadReferences(refs, manager, 2);
+     * ```
+     */
+    async loadReferences(refs, manager, maxDepth = 3, currentDepth = 0, visitedPaths, totalNodesLoaded, startTime) {
+        // Input validation
+        if (!Array.isArray(refs)) {
+            return [];
+        }
+        if (typeof maxDepth !== 'number' || maxDepth < 0) {
+            throw new Error('maxDepth must be a non-negative number');
+        }
+        if (typeof currentDepth !== 'number' || currentDepth < 0) {
+            throw new Error('currentDepth must be a non-negative number');
+        }
+        // Initialize operation start time on first call
+        const operationStart = startTime ?? Date.now();
+        // Check for timeout
+        if (Date.now() - operationStart > this.DEFAULT_TIMEOUT_MS) {
+            throw new Error(`Reference loading operation exceeded timeout of ${this.DEFAULT_TIMEOUT_MS}ms. ` +
+                'This may indicate a very large or deeply nested reference tree.');
+        }
+        // Initialize node tracker on first call
+        const nodeTracker = totalNodesLoaded ?? { count: 0 };
+        // Check total node count limit to prevent exponential growth
+        if (nodeTracker.count >= this.MAX_TOTAL_NODES) {
+            logger.error(`Total node limit (${this.MAX_TOTAL_NODES}) exceeded. Stopping reference loading to prevent memory exhaustion.`);
+            return [];
+        }
+        // Check depth limit
+        if (currentDepth >= maxDepth) {
+            return [];
+        }
+        // Track visited paths to prevent cycles (create new set if not provided)
+        const pathsToTrack = visitedPaths ?? new Set();
+        const results = [];
+        for (const ref of refs) {
+            try {
+                const content = await this.loadSingleReference(ref, manager, maxDepth, currentDepth, pathsToTrack, nodeTracker, operationStart);
+                if (content != null) {
+                    results.push(content);
+                }
+            }
+            catch (error) {
+                // Log error but continue processing other references
+                logger.warn(`Failed to load reference "${ref.originalRef}"`, {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Load a single reference with cycle detection
+     *
+     * @param ref - Normalized reference to load
+     * @param manager - DocumentManager for loading
+     * @param maxDepth - Maximum recursion depth
+     * @param currentDepth - Current recursion depth
+     * @param visitedPaths - Set of already visited paths for cycle detection
+     * @param nodeTracker - Node count tracker across all branches
+     * @param startTime - Operation start timestamp for timeout tracking
+     * @returns Promise resolving to hierarchical content or null if skipped
+     */
+    async loadSingleReference(ref, manager, maxDepth, currentDepth, visitedPaths, nodeTracker, startTime) {
+        // Check for cycles (should not happen due to filtering, but keeping as safety check)
+        if (visitedPaths.has(ref.documentPath)) {
+            logger.warn(`Unexpected cycle detected for path: ${ref.documentPath}`);
+            return null;
+        }
+        // Add to visited set
+        visitedPaths.add(ref.documentPath);
+        // Increment node counter to track total nodes across all branches
+        nodeTracker.count++;
+        // Load the document with 'reference' context for 2x eviction resistance
+        const document = await manager.cache.getDocument(ref.documentPath, AccessContext.REFERENCE);
+        if (document == null) {
+            logger.warn(`Document not found: ${ref.documentPath}`);
+            return null;
+        }
+        // Get content (section-specific or full document)
+        let content;
+        let title;
+        if (ref.sectionSlug != null) {
+            // Load specific section using DocumentManager to ensure proper loading
+            const sectionContent = await manager.getSectionContent(ref.documentPath, ref.sectionSlug);
+            if (sectionContent == null) {
+                logger.warn(`Section "${ref.sectionSlug}" not found in ${ref.documentPath}`);
+                return null;
+            }
+            content = sectionContent;
+            // Find section title from headings
+            const heading = document.headings.find(h => h.slug === ref.sectionSlug);
+            title = heading?.title ?? `Section: ${ref.sectionSlug}`;
+        }
+        else {
+            // Load full document content directly
+            content = await manager.cache.readDocumentContent(ref.documentPath) ?? '';
+            title = document.metadata.title;
+        }
+        // Extract nested references from content
+        const nestedRefs = this.extractor.extractReferences(content);
+        const normalizedNestedRefs = this.extractor.normalizeReferences(nestedRefs, ref.documentPath);
+        // Filter out self-references and already visited paths (with cycle detection logging)
+        const filteredNestedRefs = normalizedNestedRefs.filter(nestedRef => {
+            if (visitedPaths.has(nestedRef.documentPath)) {
+                logger.warn(`Cycle detected for path: ${nestedRef.documentPath}`);
+                return false;
+            }
+            return true;
+        });
+        // Recursively load nested references with visited path tracking
+        const children = await this.loadReferences(filteredNestedRefs, manager, maxDepth, currentDepth + 1, visitedPaths, nodeTracker, startTime);
+        // Build hierarchical content
+        const hierarchicalContent = {
+            path: ref.documentPath,
+            title,
+            content,
+            depth: currentDepth,
+            namespace: pathToNamespace(ref.documentPath),
+            children
+        };
+        return hierarchicalContent;
+    }
+    /**
+     * Load references from content string with automatic extraction
+     *
+     * Convenience method that combines reference extraction and loading
+     * in a single operation.
+     *
+     * @param content - Content to extract references from
+     * @param contextPath - Context document path for resolution
+     * @param manager - DocumentManager for loading
+     * @param maxDepth - Maximum recursion depth (default: 3)
+     * @returns Promise resolving to hierarchical content array
+     *
+     * @example Direct content loading
+     * ```typescript
+     * const loader = new ReferenceLoader();
+     * const content = 'See @/api/auth.md and @/api/tokens.md for details.';
+     *
+     * const hierarchy = await loader.loadReferencesFromContent(
+     *   content,
+     *   '/current/doc.md',
+     *   manager
+     * );
+     * ```
+     */
+    async loadReferencesFromContent(content, contextPath, manager, maxDepth = 3) {
+        // Extract references from content
+        const refs = this.extractor.extractReferences(content);
+        // Normalize references
+        const normalizedRefs = this.extractor.normalizeReferences(refs, contextPath);
+        // Load hierarchical content
+        return await this.loadReferences(normalizedRefs, manager, maxDepth);
+    }
+    /**
+     * Get flattened list of all documents in hierarchy
+     *
+     * Utility method to extract all document paths from hierarchical content
+     * for analysis or batch operations.
+     *
+     * @param hierarchy - Hierarchical content array
+     * @returns Array of document paths in depth-first order
+     *
+     * @example Flatten hierarchy
+     * ```typescript
+     * const hierarchy = await loader.loadReferences(refs, manager);
+     * const allPaths = loader.flattenHierarchy(hierarchy);
+     * // Returns: ['/api/auth.md', '/api/tokens.md', '/api/errors.md']
+     * ```
+     */
+    flattenHierarchy(hierarchy) {
+        const paths = [];
+        const collect = (items) => {
+            for (const item of items) {
+                paths.push(item.path);
+                collect(item.children);
+            }
+        };
+        collect(hierarchy);
+        return paths;
+    }
+    /**
+     * Get hierarchy statistics for analysis
+     *
+     * @param hierarchy - Hierarchical content array
+     * @returns Statistics about the hierarchy structure
+     */
+    getHierarchyStats(hierarchy) {
+        let totalDocuments = 0;
+        let maxDepth = -1;
+        const namespaceSet = new Set();
+        const analyze = (items) => {
+            for (const item of items) {
+                totalDocuments++;
+                maxDepth = Math.max(maxDepth, item.depth);
+                namespaceSet.add(item.namespace);
+                analyze(item.children);
+            }
+        };
+        analyze(hierarchy);
+        return {
+            totalDocuments,
+            maxDepth: maxDepth === -1 ? 0 : maxDepth,
+            namespaces: Array.from(namespaceSet).sort()
+        };
+    }
+}
+//# sourceMappingURL=reference-loader.js.map

package/dist/shared/reference-loader.js.map

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

package/dist/shared/section-operations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Section editing operations
+ */
+import type { DocumentManager } from '../document-manager.js';
+/**
+ * Helper function to perform a single section edit operation
+ */
+export declare function performSectionEdit(manager: DocumentManager, normalizedPath: string, sectionSlug: string, content: string, operation: string, title?: string): Promise<{
+    action: 'edited' | 'created' | 'removed';
+    section: string;
+    depth?: number;
+    removedContent?: string;
+}>;
+//# sourceMappingURL=section-operations.d.ts.map

package/dist/shared/section-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"section-operations.d.ts","sourceRoot":"","sources":["../../src/shared/section-operations.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkJjH"}

package/dist/shared/section-operations.js

@@ -0,0 +1,115 @@
+/**
+ * Section editing operations
+ */
+import { getSectionContentForRemoval, deleteSection } from '../sections.js';
+import { DocumentNotFoundError, AddressingError } from './addressing-system.js';
+/**
+ * Helper function to perform a single section edit operation
+ */
+export async function performSectionEdit(manager, normalizedPath, sectionSlug, content, operation, title) {
+    // Check if document exists
+    const document = await manager.getDocument(normalizedPath);
+    if (document == null) {
+        throw new DocumentNotFoundError(normalizedPath);
+    }
+    const creationOperations = ['insert_before', 'insert_after', 'append_child'];
+    const editOperations = ['replace', 'append', 'prepend'];
+    const removeOperations = ['remove'];
+    if (removeOperations.includes(operation)) {
+        // Remove operations - delete section
+        const section = document.headings.find(h => h.slug === sectionSlug);
+        if (section == null) {
+            throw new AddressingError(`Section not found: ${sectionSlug}`, 'SECTION_NOT_FOUND', {
+                slug: sectionSlug,
+                documentPath: normalizedPath,
+                availableSections: document.headings.map(h => h.slug)
+            });
+        }
+        // Get the actual content that will be removed (excluding boundary markers)
+        // This ensures the reported removed_content matches what deleteSection actually removes
+        const absolutePath = manager.pathResolver.resolve(normalizedPath);
+        const { readFileSnapshot, writeFileIfUnchanged } = await import('../fsio.js');
+        const snapshot = await readFileSnapshot(absolutePath, { bypassValidation: true });
+        // Get the content that will actually be removed (matches deleteSection behavior)
+        const removedContent = getSectionContentForRemoval(snapshot.content, sectionSlug) ?? '';
+        const updatedContent = deleteSection(snapshot.content, sectionSlug);
+        await writeFileIfUnchanged(absolutePath, snapshot.mtimeMs, updatedContent, { bypassValidation: true });
+        return {
+            action: 'removed',
+            section: sectionSlug,
+            removedContent
+        };
+    }
+    else if (creationOperations.includes(operation)) {
+        // Creation operations - create new section
+        if (title == null || title === '') {
+            throw new AddressingError(`Title is required for creation operation: ${operation}`, 'MISSING_PARAMETER', { operation, requiredParameter: 'title' });
+        }
+        // Map operation to InsertMode
+        const insertMode = operation === 'insert_before' ? 'insert_before'
+            : operation === 'insert_after' ? 'insert_after'
+                : 'append_child';
+        const targetSlug = sectionSlug;
+        // Insert the section with automatic depth calculation
+        await manager.insertSection(normalizedPath, targetSlug, insertMode, undefined, // Let it auto-calculate depth
+        title, content, { updateToc: true });
+        // Get the created section's slug and depth
+        const updatedDocument = await manager.getDocument(normalizedPath);
+        if (updatedDocument == null) {
+            throw new DocumentNotFoundError(normalizedPath);
+        }
+        // Find the newly created section
+        const { titleToSlug } = await import('../slug.js');
+        const newSlug = titleToSlug(title);
+        const newSection = updatedDocument.headings.find(h => h.slug === newSlug);
+        return {
+            action: 'created',
+            section: newSlug,
+            ...(newSection?.depth !== undefined && { depth: newSection.depth })
+        };
+    }
+    else if (editOperations.includes(operation)) {
+        // Edit operations - modify existing section
+        if (operation === 'replace') {
+            const section = document.headings.find(h => h.slug === sectionSlug);
+            if (section == null) {
+                throw new AddressingError(`Section not found: ${sectionSlug}`, 'SECTION_NOT_FOUND', {
+                    slug: sectionSlug,
+                    documentPath: normalizedPath,
+                    availableSections: document.headings.map(h => h.slug)
+                });
+            }
+            await manager.updateSection(normalizedPath, sectionSlug, content, {
+                updateToc: true,
+                validateLinks: true
+            });
+        }
+        else {
+            // For append/prepend, get current content and modify it
+            const currentContent = await manager.getSectionContent(normalizedPath, sectionSlug) ?? '';
+            let newContent;
+            if (operation === 'append') {
+                newContent = currentContent.trim() !== '' ? `${currentContent}\n\n${content}` : content;
+            }
+            else if (operation === 'prepend') {
+                newContent = currentContent.trim() !== '' ? `${content}\n\n${currentContent}` : content;
+            }
+            else {
+                throw new AddressingError(`Invalid operation: ${operation}`, 'INVALID_OPERATION', { operation, validOperations: ['replace', 'append', 'prepend'] });
+            }
+            await manager.updateSection(normalizedPath, sectionSlug, newContent, {
+                updateToc: true,
+                validateLinks: true
+            });
+        }
+        return {
+            action: 'edited',
+            section: sectionSlug
+        };
+    }
+    else {
+        const validOperations = [...editOperations, ...creationOperations, ...removeOperations];
+        throw new AddressingError(`Invalid operation: ${operation}`, 'INVALID_OPERATION', { operation, validOperations });
+    }
+}
+//# sourceMappingURL=section-operations.js.map

package/dist/shared/section-operations.js.map

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

package/dist/shared/slug-utils.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Hierarchical slug utilities for the Document Linking System
+ */
+import type { HierarchicalSlug, SlugPathOperation } from '../types/linking.js';
+/**
+ * Generate a hierarchical slug by combining parent slug with child title
+ *
+ * @param parentSlug - Parent slug path (e.g., "api/endpoints")
+ * @param childTitle - Title to convert to slug and append
+ * @returns Combined hierarchical slug (e.g., "api/endpoints/users")
+ */
+export declare function generateHierarchicalSlug(parentSlug: string, childTitle: string): string;
+/**
+ * Split a hierarchical slug path into component parts
+ *
+ * @param slugPath - Hierarchical slug path (e.g., "api/authentication/jwt-tokens")
+ * @returns Array of slug components (e.g., ["api", "authentication", "jwt-tokens"])
+ */
+export declare function splitSlugPath(slugPath: string): string[];
+/**
+ * Join slug path components into a hierarchical slug
+ *
+ * @param parts - Array of slug components
+ * @returns Combined slug path with normalized separators
+ */
+export declare function joinSlugPath(parts: string[]): string;
+/**
+ * Get the depth (nesting level) of a hierarchical slug
+ *
+ * @param slugPath - Hierarchical slug path
+ * @returns Number of levels in the hierarchy (e.g., "api/auth/jwt" returns 3)
+ */
+export declare function getSlugDepth(slugPath: string): number;
+/**
+ * Get the parent slug from a hierarchical slug path
+ *
+ * @param slugPath - Hierarchical slug path (e.g., "api/auth/jwt")
+ * @returns Parent slug path (e.g., "api/auth") or undefined for top-level
+ */
+export declare function getParentSlug(slugPath: string): string | undefined;
+/**
+ * Get the leaf (final) component of a hierarchical slug
+ *
+ * @param slugPath - Hierarchical slug path (e.g., "api/auth/jwt-tokens")
+ * @returns Leaf component (e.g., "jwt-tokens")
+ */
+export declare function getSlugLeaf(slugPath: string): string;
+/**
+ * Create a complete hierarchical slug structure with metadata
+ *
+ * @param slugPath - Hierarchical slug path
+ * @returns HierarchicalSlug object with full structure information
+ */
+export declare function createHierarchicalSlug(slugPath: string): HierarchicalSlug;
+/**
+ * Check if one slug is an ancestor of another
+ *
+ * @param ancestorSlug - Potential ancestor slug path
+ * @param descendantSlug - Potential descendant slug path
+ * @returns True if ancestor is a parent/grandparent/etc. of descendant
+ */
+export declare function isSlugAncestor(ancestorSlug: string, descendantSlug: string): boolean;
+/**
+ * Check if one slug is a direct child of another
+ *
+ * @param parentSlug - Potential parent slug path
+ * @param childSlug - Potential child slug path
+ * @returns True if child is a direct child of parent (one level deeper)
+ */
+export declare function isDirectChild(parentSlug: string, childSlug: string): boolean;
+/**
+ * Get all direct children of a slug from a list of slugs
+ *
+ * @param parentSlug - Parent slug path
+ * @param allSlugs - Array of all available slug paths
+ * @returns Array of direct child slug paths
+ */
+export declare function getDirectChildren(parentSlug: string, allSlugs: string[]): string[];
+/**
+ * Get all descendants (children, grandchildren, etc.) of a slug
+ *
+ * @param ancestorSlug - Ancestor slug path
+ * @param allSlugs - Array of all available slug paths
+ * @returns Array of descendant slug paths
+ */
+export declare function getAllDescendants(ancestorSlug: string, allSlugs: string[]): string[];
+/**
+ * Calculate the relative path between two slug paths
+ *
+ * @param fromSlug - Source slug path
+ * @param toSlug - Target slug path
+ * @returns Relative path or operation result with error details
+ */
+export declare function getRelativeSlugPath(fromSlug: string, toSlug: string): SlugPathOperation;
+/**
+ * Validate a hierarchical slug path structure
+ *
+ * @param slugPath - Slug path to validate
+ * @returns Validation result with success status and details
+ */
+export declare function validateSlugPath(slugPath: string): SlugPathOperation;
+/**
+ * Normalize a slug path by removing extra separators and ensuring consistent format
+ *
+ * @param slugPath - Raw slug path to normalize
+ * @returns Normalized slug path
+ */
+export declare function normalizeSlugPath(slugPath: string): string;
+//# sourceMappingURL=slug-utils.d.ts.map

package/dist/shared/slug-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug-utils.d.ts","sourceRoot":"","sources":["../../src/shared/slug-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG/E;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAiBvF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAYxD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAWpD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYrD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYlE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAiBzE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAWpF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAW5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMlF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAMpF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAgDvF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAgDpE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAc1D"}