@synth-coder/memhub 0.1.0

package/dist/src/storage/frontmatter-parser.js

@@ -0,0 +1,207 @@
+/**
+ * FrontMatter Parser - Handles YAML Front Matter and Markdown content
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { slugify } from '../utils/slugify.js';
+/**
+ * Custom error for front matter parsing
+ */
+export class FrontMatterError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'FrontMatterError';
+    }
+}
+/**
+ * Parses a markdown file with YAML front matter
+ *
+ * Expected format:
+ * ---
+ * id: "uuid"
+ * created_at: "ISO8601"
+ * updated_at: "ISO8601"
+ * tags: ["tag1", "tag2"]
+ * category: "category"
+ * importance: 3
+ * ---
+ *
+ * # Title
+ *
+ * Content...
+ *
+ * @param markdown - The markdown content to parse
+ * @returns Parsed front matter, title, and content
+ * @throws FrontMatterError if parsing fails
+ */
+export function parseFrontMatter(markdown) {
+    // Check for front matter delimiter
+    if (!markdown.startsWith('---')) {
+        throw new FrontMatterError('Missing front matter delimiter');
+    }
+    // Find the end of front matter
+    const endMatch = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    if (!endMatch) {
+        throw new FrontMatterError('Invalid front matter format');
+    }
+    const frontMatterYaml = endMatch[1];
+    const restOfContent = markdown.slice(endMatch[0].length);
+    // Parse YAML front matter
+    let frontMatter;
+    try {
+        frontMatter = parseYaml(frontMatterYaml);
+    }
+    catch (error) {
+        throw new FrontMatterError('Invalid YAML in front matter', error);
+    }
+    // Validate required fields
+    if (!isValidFrontMatter(frontMatter)) {
+        throw new FrontMatterError('Missing required fields in front matter');
+    }
+    // Parse title and content from markdown body
+    const { title, content } = parseMarkdownBody(restOfContent);
+    return {
+        frontMatter,
+        title,
+        content,
+    };
+}
+/**
+ * Converts front matter and content to markdown string
+ *
+ * @param frontMatter - The front matter data
+ * @param title - The title (H1 heading)
+ * @param content - The markdown content
+ * @returns Complete markdown string
+ */
+export function stringifyFrontMatter(frontMatter, title, content) {
+    // Convert camelCase to snake_case for YAML
+    const yamlData = {
+        id: frontMatter.id,
+        created_at: frontMatter.created_at,
+        updated_at: frontMatter.updated_at,
+        ...(frontMatter.session_id ? { session_id: frontMatter.session_id } : {}),
+        ...(frontMatter.entry_type ? { entry_type: frontMatter.entry_type } : {}),
+        tags: frontMatter.tags.length > 0 ? frontMatter.tags : [],
+        category: frontMatter.category,
+        importance: frontMatter.importance,
+    };
+    // Stringify YAML with specific options for consistent formatting
+    const yamlString = stringifyYaml(yamlData, {
+        indent: 2,
+        defaultKeyType: 'PLAIN',
+        defaultStringType: 'QUOTE_DOUBLE',
+    });
+    // Build the complete markdown
+    const parts = ['---', yamlString.trim(), '---', ''];
+    // Add title if provided
+    if (title) {
+        parts.push(`# ${title}`, '');
+    }
+    // Add content if provided
+    if (content) {
+        parts.push(content);
+    }
+    // Ensure content ends with a single newline
+    let result = parts.join('\n');
+    if (!result.endsWith('\n')) {
+        result += '\n';
+    }
+    return result;
+}
+/**
+ * Parses the markdown body to extract title and content
+ *
+ * @param body - The markdown body (after front matter)
+ * @returns Title and content
+ */
+function parseMarkdownBody(body) {
+    const trimmed = body.trim();
+    if (!trimmed) {
+        return { title: '', content: '' };
+    }
+    // Try to extract H1 title
+    const h1Match = trimmed.match(/^#\s+(.+)$/m);
+    if (h1Match) {
+        const title = h1Match[1].trim();
+        // Remove the H1 line from content
+        const content = trimmed.replace(/^#\s+.+$/m, '').trim();
+        return { title, content };
+    }
+    // No H1 found, treat entire body as content
+    return { title: '', content: trimmed };
+}
+/**
+ * Type guard to validate front matter structure
+ *
+ * @param value - The value to check
+ * @returns True if valid front matter
+ */
+function isValidFrontMatter(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const fm = value;
+    // Check required fields
+    if (typeof fm.id !== 'string')
+        return false;
+    if (typeof fm.created_at !== 'string')
+        return false;
+    if (typeof fm.updated_at !== 'string')
+        return false;
+    if (fm.session_id !== undefined && typeof fm.session_id !== 'string')
+        return false;
+    if (fm.entry_type !== undefined && typeof fm.entry_type !== 'string')
+        return false;
+    if (!Array.isArray(fm.tags))
+        return false;
+    if (typeof fm.category !== 'string')
+        return false;
+    if (typeof fm.importance !== 'number')
+        return false;
+    return true;
+}
+/**
+ * Converts a Memory object to front matter format
+ *
+ * @param memory - The memory object
+ * @returns Memory in front matter format
+ */
+export function memoryToFrontMatter(memory) {
+    return {
+        id: memory.id,
+        created_at: memory.createdAt,
+        updated_at: memory.updatedAt,
+        session_id: memory.sessionId,
+        entry_type: memory.entryType,
+        tags: memory.tags,
+        category: memory.category,
+        importance: memory.importance,
+    };
+}
+/**
+ * Converts front matter format to Memory object
+ *
+ * @param frontMatter - The front matter data
+ * @param title - The memory title
+ * @param content - The memory content
+ * @returns Complete Memory object
+ */
+export function frontMatterToMemory(frontMatter, title, content) {
+    return {
+        id: frontMatter.id,
+        createdAt: frontMatter.created_at,
+        updatedAt: frontMatter.updated_at,
+        sessionId: frontMatter.session_id,
+        entryType: frontMatter.entry_type,
+        tags: frontMatter.tags,
+        category: frontMatter.category,
+        importance: frontMatter.importance,
+        title,
+        content,
+    };
+}
+// Re-export slugify for convenience
+export { slugify };
+//# sourceMappingURL=frontmatter-parser.js.map

package/dist/src/storage/frontmatter-parser.js.map

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

package/dist/src/storage/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Storage layer exports
+ */
+export * from './frontmatter-parser.js';
+export * from './markdown-storage.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}

package/dist/src/storage/index.js

@@ -0,0 +1,6 @@
+/**
+ * Storage layer exports
+ */
+export * from './frontmatter-parser.js';
+export * from './markdown-storage.js';
+//# sourceMappingURL=index.js.map

package/dist/src/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC"}

package/dist/src/storage/markdown-storage.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Markdown Storage - Handles file system operations for memory storage
+ */
+import type { Memory, MemoryFile } from '../contracts/types.js';
+/**
+ * Custom error for storage operations
+ */
+export declare class StorageError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Storage configuration
+ */
+export interface StorageConfig {
+    /** Root directory for memory storage */
+    storagePath: string;
+}
+/**
+ * Markdown file storage implementation
+ */
+export declare class MarkdownStorage {
+    private readonly storagePath;
+    constructor(config: StorageConfig);
+    /**
+     * Ensures the storage directory exists
+     */
+    initialize(): Promise<void>;
+    /**
+     * Writes a memory to a markdown file
+     *
+     * @param memory - The memory to write
+     * @returns The file path where the memory was stored
+     * @throws StorageError if write fails
+     */
+    write(memory: Memory): Promise<string>;
+    /**
+     * Reads a memory by its ID
+     *
+     * @param id - The memory ID
+     * @returns The memory object
+     * @throws StorageError if memory not found or read fails
+     */
+    read(id: string): Promise<Memory>;
+    /**
+     * Deletes a memory by its ID
+     *
+     * @param id - The memory ID
+     * @returns The file path of the deleted memory
+     * @throws StorageError if memory not found or delete fails
+     */
+    delete(id: string): Promise<string>;
+    /**
+     * Lists all memory files
+     *
+     * @returns Array of memory file information
+     * @throws StorageError if listing fails
+     */
+    list(): Promise<MemoryFile[]>;
+    /**
+     * Finds a memory file by ID
+     *
+     * @param id - The memory ID to find
+     * @returns The file path or null if not found
+     * @throws StorageError if search fails
+     */
+    findById(id: string): Promise<string | null>;
+    /**
+     * Generates nested path parts for a memory
+     *
+     * Format: {storage}/{YYYY-MM-DD}/{session_uuid}/{timestamp}-{slug}.md
+     */
+    private generatePathParts;
+    private collectMarkdownFiles;
+}
+//# sourceMappingURL=markdown-storage.d.ts.map

package/dist/src/storage/markdown-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-storage.d.ts","sourceRoot":"","sources":["../../../src/storage/markdown-storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAUhE;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;aAGnB,KAAK,CAAC,EAAE,OAAO;gBAD/B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,EAAE,aAAa;IAIjC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;;;;;OAMG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB5C;;;;;;OAMG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBvC;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAezC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAyBnC;;;;;;OAMG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAyBlD;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;YAWX,oBAAoB;CAgBnC"}

package/dist/src/storage/markdown-storage.js

@@ -0,0 +1,193 @@
+/**
+ * Markdown Storage - Handles file system operations for memory storage
+ */
+import { readFile, writeFile, unlink, readdir, stat, access, mkdir, } from 'fs/promises';
+import { join, extname } from 'path';
+import { constants } from 'fs';
+import { parseFrontMatter, stringifyFrontMatter, memoryToFrontMatter, frontMatterToMemory, FrontMatterError, } from './frontmatter-parser.js';
+import { slugify } from '../utils/slugify.js';
+/**
+ * Custom error for storage operations
+ */
+export class StorageError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'StorageError';
+    }
+}
+/**
+ * Markdown file storage implementation
+ */
+export class MarkdownStorage {
+    storagePath;
+    constructor(config) {
+        this.storagePath = config.storagePath;
+    }
+    /**
+     * Ensures the storage directory exists
+     */
+    async initialize() {
+        try {
+            await access(this.storagePath, constants.F_OK);
+        }
+        catch {
+            // Directory doesn't exist, create it
+            await mkdir(this.storagePath, { recursive: true });
+        }
+    }
+    /**
+     * Writes a memory to a markdown file
+     *
+     * @param memory - The memory to write
+     * @returns The file path where the memory was stored
+     * @throws StorageError if write fails
+     */
+    async write(memory) {
+        await this.initialize();
+        const { directoryPath, filename } = this.generatePathParts(memory);
+        const filePath = join(directoryPath, filename);
+        const frontMatter = memoryToFrontMatter(memory);
+        const content = stringifyFrontMatter(frontMatter, memory.title, memory.content);
+        try {
+            await mkdir(directoryPath, { recursive: true });
+            await writeFile(filePath, content, 'utf-8');
+            return filePath;
+        }
+        catch (error) {
+            throw new StorageError(`Failed to write memory file: ${filename}`, error);
+        }
+    }
+    /**
+     * Reads a memory by its ID
+     *
+     * @param id - The memory ID
+     * @returns The memory object
+     * @throws StorageError if memory not found or read fails
+     */
+    async read(id) {
+        const filePath = await this.findById(id);
+        if (!filePath) {
+            throw new StorageError(`Memory not found: ${id}`);
+        }
+        try {
+            const content = await readFile(filePath, 'utf-8');
+            const { frontMatter, title, content: bodyContent } = parseFrontMatter(content);
+            return frontMatterToMemory(frontMatter, title, bodyContent);
+        }
+        catch (error) {
+            if (error instanceof FrontMatterError) {
+                throw new StorageError(`Invalid memory file format: ${filePath}`, error);
+            }
+            throw new StorageError(`Failed to read memory file: ${filePath}`, error);
+        }
+    }
+    /**
+     * Deletes a memory by its ID
+     *
+     * @param id - The memory ID
+     * @returns The file path of the deleted memory
+     * @throws StorageError if memory not found or delete fails
+     */
+    async delete(id) {
+        const filePath = await this.findById(id);
+        if (!filePath) {
+            throw new StorageError(`Memory not found: ${id}`);
+        }
+        try {
+            await unlink(filePath);
+            return filePath;
+        }
+        catch (error) {
+            throw new StorageError(`Failed to delete memory file: ${filePath}`, error);
+        }
+    }
+    /**
+     * Lists all memory files
+     *
+     * @returns Array of memory file information
+     * @throws StorageError if listing fails
+     */
+    async list() {
+        await this.initialize();
+        try {
+            const markdownPaths = await this.collectMarkdownFiles(this.storagePath);
+            const files = [];
+            for (const filePath of markdownPaths) {
+                const stats = await stat(filePath);
+                const content = await readFile(filePath, 'utf-8');
+                files.push({
+                    path: filePath,
+                    filename: filePath.split(/[/\\]/).pop() ?? filePath,
+                    content,
+                    modifiedAt: stats.mtime.toISOString(),
+                });
+            }
+            return files;
+        }
+        catch (error) {
+            throw new StorageError('Failed to list memory files', error);
+        }
+    }
+    /**
+     * Finds a memory file by ID
+     *
+     * @param id - The memory ID to find
+     * @returns The file path or null if not found
+     * @throws StorageError if search fails
+     */
+    async findById(id) {
+        await this.initialize();
+        try {
+            const markdownPaths = await this.collectMarkdownFiles(this.storagePath);
+            for (const filePath of markdownPaths) {
+                try {
+                    const content = await readFile(filePath, 'utf-8');
+                    const { frontMatter } = parseFrontMatter(content);
+                    if (frontMatter.id === id) {
+                        return filePath;
+                    }
+                }
+                catch {
+                    // Skip files that can't be parsed
+                    continue;
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            throw new StorageError('Failed to search for memory file', error);
+        }
+    }
+    /**
+     * Generates nested path parts for a memory
+     *
+     * Format: {storage}/{YYYY-MM-DD}/{session_uuid}/{timestamp}-{slug}.md
+     */
+    generatePathParts(memory) {
+        const date = memory.createdAt.split('T')[0];
+        const sessionId = memory.sessionId ?? 'default-session';
+        const titleSlug = slugify(memory.title) || 'untitled';
+        const timestamp = memory.createdAt.replace(/[:.]/g, '-');
+        const filename = `${timestamp}-${titleSlug}.md`;
+        const directoryPath = join(this.storagePath, date, sessionId);
+        return { directoryPath, filename };
+    }
+    async collectMarkdownFiles(rootDir) {
+        const entries = await readdir(rootDir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const entryPath = join(rootDir, entry.name);
+            if (entry.isDirectory()) {
+                const nested = await this.collectMarkdownFiles(entryPath);
+                files.push(...nested);
+            }
+            else if (entry.isFile() && extname(entry.name) === '.md') {
+                files.push(entryPath);
+            }
+        }
+        return files;
+    }
+}
+//# sourceMappingURL=markdown-storage.js.map

package/dist/src/storage/markdown-storage.js.map

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

package/dist/src/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+export * from './slugify.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,cAAc,CAAC"}

package/dist/src/utils/index.js

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+export * from './slugify.js';
+//# sourceMappingURL=index.js.map

package/dist/src/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,cAAc,CAAC"}

package/dist/src/utils/slugify.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Slugify utility - Converts strings to URL-friendly slugs
+ */
+/**
+ * Converts a string to a URL-friendly slug
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ * - Removes special characters
+ * - Collapses multiple hyphens
+ * - Trims leading/trailing hyphens
+ *
+ * @param input - The string to convert
+ * @returns The slugified string
+ */
+export declare function slugify(input: string): string;
+/**
+ * Generates a unique slug by appending a timestamp or counter if needed
+ *
+ * @param title - The title to slugify
+ * @param existingSlugs - Array of existing slugs to check against
+ * @returns A unique slug
+ */
+export declare function generateUniqueSlug(title: string, existingSlugs?: readonly string[]): string;
+//# sourceMappingURL=slugify.d.ts.map

package/dist/src/utils/slugify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugify.d.ts","sourceRoot":"","sources":["../../../src/utils/slugify.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAwB7C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAc/F"}

package/dist/src/utils/slugify.js

@@ -0,0 +1,56 @@
+/**
+ * Slugify utility - Converts strings to URL-friendly slugs
+ */
+/**
+ * Converts a string to a URL-friendly slug
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ * - Removes special characters
+ * - Collapses multiple hyphens
+ * - Trims leading/trailing hyphens
+ *
+ * @param input - The string to convert
+ * @returns The slugified string
+ */
+export function slugify(input) {
+    if (!input || input.trim().length === 0) {
+        return 'untitled';
+    }
+    // Convert to lowercase and replace non-alphanumeric characters with hyphens
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '') // Remove special characters
+        .replace(/\s+/g, '-') // Replace spaces with hyphens
+        .replace(/-+/g, '-') // Collapse multiple hyphens
+        .replace(/^-+|-+$/g, ''); // Trim leading/trailing hyphens
+    // If empty after cleaning (e.g., only special characters), return 'untitled'
+    if (slug.length === 0) {
+        return 'untitled';
+    }
+    // Truncate to max 100 characters
+    if (slug.length > 100) {
+        return slug.substring(0, 100).replace(/-+$/, ''); // Don't end with hyphen
+    }
+    return slug;
+}
+/**
+ * Generates a unique slug by appending a timestamp or counter if needed
+ *
+ * @param title - The title to slugify
+ * @param existingSlugs - Array of existing slugs to check against
+ * @returns A unique slug
+ */
+export function generateUniqueSlug(title, existingSlugs = []) {
+    const slug = slugify(title);
+    let counter = 1;
+    let uniqueSlug = slug;
+    while (existingSlugs.includes(uniqueSlug)) {
+        const suffix = `-${counter}`;
+        const maxBaseLength = 100 - suffix.length;
+        const baseSlug = slug.substring(0, maxBaseLength).replace(/-+$/, '');
+        uniqueSlug = `${baseSlug}${suffix}`;
+        counter++;
+    }
+    return uniqueSlug;
+}
+//# sourceMappingURL=slugify.js.map

package/dist/src/utils/slugify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slugify.js","sourceRoot":"","sources":["../../../src/utils/slugify.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,4EAA4E;IAC5E,MAAM,IAAI,GAAG,KAAK;SACf,WAAW,EAAE;SACb,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC,4BAA4B;SACzD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,8BAA8B;SACnD,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,4BAA4B;SAChD,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,gCAAgC;IAE5D,6EAA6E;IAC7E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,iCAAiC;IACjC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,wBAAwB;IAC5E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,gBAAmC,EAAE;IACrF,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,UAAU,GAAG,IAAI,CAAC;IAEtB,OAAO,aAAa,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,aAAa,GAAG,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACrE,UAAU,GAAG,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAC;QACpC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}