mcp-adr-analysis-server 2.1.11 → 2.1.20

package/dist/src/utils/conditional-request.js

@@ -0,0 +1,186 @@
+/**
+ * Conditional Request Support
+ *
+ * Implements HTTP conditional request headers (ETag, If-Modified-Since)
+ * for efficient resource caching and bandwidth reduction.
+ *
+ * Features:
+ * - ETag generation (strong and weak)
+ * - If-None-Match validation
+ * - If-Modified-Since validation
+ * - 304 Not Modified support
+ */
+import crypto from 'crypto';
+/**
+ * Generate strong ETag from content
+ * Format: "hash"
+ */
+export function generateStrongETag(content) {
+    const data = typeof content === 'string' ? content : JSON.stringify(content);
+    const hash = crypto.createHash('sha256').update(data).digest('hex').substring(0, 16);
+    return `"${hash}"`;
+}
+/**
+ * Generate weak ETag from metadata
+ * Format: W/"timestamp-hash"
+ * Useful when content hasn't changed but metadata has
+ */
+export function generateWeakETag(timestamp, identifier) {
+    const hash = crypto.createHash('md5').update(`${timestamp}:${identifier}`).digest('hex').substring(0, 8);
+    return `W/"${timestamp.substring(0, 10)}-${hash}"`;
+}
+/**
+ * Parse ETag from header
+ * Handles both strong and weak ETags
+ */
+export function parseETag(etag) {
+    const isWeak = etag.startsWith('W/');
+    const value = isWeak ? etag.substring(3) : etag;
+    return { value: value.replace(/"/g, ''), isWeak };
+}
+/**
+ * Compare two ETags for equality
+ * Supports both strong and weak comparison
+ */
+export function compareETags(etag1, etag2, weakComparison = false) {
+    const parsed1 = parseETag(etag1);
+    const parsed2 = parseETag(etag2);
+    // Strong comparison: both must be strong and equal
+    if (!weakComparison) {
+        if (parsed1.isWeak || parsed2.isWeak) {
+            return false;
+        }
+        return parsed1.value === parsed2.value;
+    }
+    // Weak comparison: values must match (ignoring weak flag)
+    return parsed1.value === parsed2.value;
+}
+/**
+ * Parse If-None-Match header
+ * Returns array of ETags to check
+ */
+export function parseIfNoneMatch(header) {
+    if (!header) {
+        return [];
+    }
+    // Handle wildcard
+    if (header.trim() === '*') {
+        return ['*'];
+    }
+    // Split by comma and trim
+    return header.split(',').map((etag) => etag.trim());
+}
+/**
+ * Check if resource matches If-None-Match condition
+ * Returns true if resource has NOT been modified
+ */
+export function checkIfNoneMatch(currentETag, ifNoneMatchHeader) {
+    if (!ifNoneMatchHeader) {
+        return false;
+    }
+    const etags = parseIfNoneMatch(ifNoneMatchHeader);
+    // Wildcard matches any resource
+    if (etags.includes('*')) {
+        return true;
+    }
+    // Check if current ETag matches any in the list
+    return etags.some((etag) => compareETags(currentETag, etag, true));
+}
+/**
+ * Parse If-Modified-Since header to Date
+ */
+export function parseIfModifiedSince(header) {
+    if (!header) {
+        return null;
+    }
+    try {
+        const date = new Date(header);
+        return isNaN(date.getTime()) ? null : date;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if resource has been modified since given date
+ * Returns true if resource has been modified
+ */
+export function checkIfModifiedSince(lastModified, ifModifiedSinceHeader) {
+    const ifModifiedSince = parseIfModifiedSince(ifModifiedSinceHeader);
+    if (!ifModifiedSince) {
+        return true; // No header, treat as modified
+    }
+    const lastModifiedDate = new Date(lastModified);
+    if (isNaN(lastModifiedDate.getTime())) {
+        return true; // Invalid date, treat as modified
+    }
+    // Resource is modified if lastModified > ifModifiedSince
+    return lastModifiedDate > ifModifiedSince;
+}
+export function evaluateConditionalRequest(params) {
+    const { currentETag, lastModified, ifNoneMatch, ifModifiedSince } = params;
+    // If-None-Match has priority over If-Modified-Since
+    if (ifNoneMatch) {
+        const matches = checkIfNoneMatch(currentETag, ifNoneMatch);
+        if (matches) {
+            return { notModified: true, reason: 'ETag match' };
+        }
+        // If-None-Match present but doesn't match, resource is modified
+        return { notModified: false, reason: 'ETag mismatch' };
+    }
+    // Check If-Modified-Since
+    if (ifModifiedSince) {
+        const modified = checkIfModifiedSince(lastModified, ifModifiedSince);
+        if (!modified) {
+            return { notModified: true, reason: 'Not modified since' };
+        }
+        return { notModified: false, reason: 'Modified since' };
+    }
+    // No conditional headers present
+    return { notModified: false, reason: 'No conditional headers' };
+}
+export function generateCacheHeaders(params) {
+    const { etag, lastModified, maxAge = 300, mustRevalidate = true, vary } = params;
+    const cacheControl = [
+        `max-age=${maxAge}`,
+        mustRevalidate ? 'must-revalidate' : '',
+        'private', // Resources are user-specific
+    ]
+        .filter(Boolean)
+        .join(', ');
+    const headers = {
+        ETag: etag,
+        'Last-Modified': lastModified,
+        'Cache-Control': cacheControl,
+    };
+    if (vary && vary.length > 0) {
+        headers.Vary = vary.join(', ');
+    }
+    return headers;
+}
+export function createNotModifiedResponse(params) {
+    const { etag, lastModified, maxAge } = params;
+    // Build headers params without undefined values
+    const headersParams = { etag, lastModified };
+    if (maxAge !== undefined) {
+        headersParams.maxAge = maxAge;
+    }
+    return {
+        status: 304,
+        statusText: 'Not Modified',
+        headers: generateCacheHeaders(headersParams),
+    };
+}
+/**
+ * Calculate cache freshness
+ * Returns true if cache is still fresh
+ */
+export function isCacheFresh(lastModified, maxAge) {
+    const lastModifiedDate = new Date(lastModified);
+    if (isNaN(lastModifiedDate.getTime())) {
+        return false;
+    }
+    const ageSeconds = (Date.now() - lastModifiedDate.getTime()) / 1000;
+    return ageSeconds < maxAge;
+}
+//# sourceMappingURL=conditional-request.js.map

package/dist/src/utils/conditional-request.js.map

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

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

@@ -9,31 +9,53 @@ import { z } from 'zod';
 declare const ConfigSchema: z.ZodObject<{
     projectPath: z.ZodString;
     adrDirectory: z.ZodDefault<z.ZodString>;
-    logLevel: z.ZodDefault<z.ZodEnum<["DEBUG", "INFO", "WARN", "ERROR"]>>;
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        DEBUG: "DEBUG";
+        INFO: "INFO";
+        WARN: "WARN";
+        ERROR: "ERROR";
+    }>>;
     cacheEnabled: z.ZodDefault<z.ZodBoolean>;
     cacheDirectory: z.ZodDefault<z.ZodString>;
     maxCacheSize: z.ZodDefault<z.ZodNumber>;
     analysisTimeout: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    cacheEnabled: boolean;
-    projectPath: string;
-    adrDirectory: string;
-    logLevel: "DEBUG" | "INFO" | "WARN" | "ERROR";
-    cacheDirectory: string;
-    maxCacheSize: number;
-    analysisTimeout: number;
-}, {
-    projectPath: string;
-    cacheEnabled?: boolean | undefined;
-    adrDirectory?: string | undefined;
-    logLevel?: "DEBUG" | "INFO" | "WARN" | "ERROR" | undefined;
-    cacheDirectory?: string | undefined;
-    maxCacheSize?: number | undefined;
-    analysisTimeout?: number | undefined;
-}>;
+    firecrawlApiKey: z.ZodOptional<z.ZodString>;
+    firecrawlBaseUrl: z.ZodDefault<z.ZodString>;
+    firecrawlEnabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
 export type ServerConfig = z.infer<typeof ConfigSchema>;
 /**
  * Load and validate configuration from environment variables
+ *
+ * @description Loads server configuration from environment variables with fallback defaults.
+ * Validates all configuration values using Zod schema and returns a type-safe config object.
+ *
+ * @returns {ServerConfig} Validated configuration object with all required settings
+ *
+ * @throws {Error} When configuration validation fails or required values are missing
+ *
+ * @example
+ * ```typescript
+ * // Load configuration with environment variables
+ * process.env.PROJECT_PATH = '/path/to/project';
+ * process.env.LOG_LEVEL = 'DEBUG';
+ *
+ * const config = loadConfig();
+ * console.log(config.projectPath); // '/path/to/project'
+ * console.log(config.logLevel);    // 'DEBUG'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load configuration with defaults
+ * const config = loadConfig();
+ * console.log(config.adrDirectory);  // 'docs/adrs'
+ * console.log(config.cacheEnabled);  // true
+ * console.log(config.maxCacheSize);  // 104857600 (100MB)
+ * ```
+ *
+ * @since 2.0.0
+ * @category Configuration
  */
 export declare function loadConfig(): ServerConfig;
 /**
@@ -46,6 +68,38 @@ export declare function getAdrDirectoryPath(config: ServerConfig): string;
 export declare function getCacheDirectoryPath(config: ServerConfig): string;
 /**
  * Validate that the project path exists and is accessible
+ *
+ * @description Performs filesystem validation to ensure the specified project path
+ * exists, is accessible, and is a directory. This is critical for server initialization
+ * as all ADR analysis operations depend on a valid project root.
+ *
+ * @param {string} projectPath - Absolute or relative path to validate
+ *
+ * @returns {Promise<void>} Resolves if path is valid, rejects with descriptive error
+ *
+ * @throws {Error} When path doesn't exist, isn't a directory, or isn't accessible
+ *
+ * @example
+ * ```typescript
+ * // Validate existing project directory
+ * await validateProjectPath('/path/to/project');
+ * console.log('Project path is valid');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle validation errors
+ * try {
+ *   await validateProjectPath('/invalid/path');
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message);
+ *   // Error: PROJECT_PATH does not exist: /invalid/path
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ * @category Configuration
+ * @category Validation
  */
 export declare function validateProjectPath(projectPath: string): Promise<void>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAQhB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;GAEG;AACH,wBAAgB,UAAU,IAAI,YAAY,CA4BzC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAGlE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc5E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY;qBAK5B,MAAM,WAAW,GAAG,EAAE;oBAGvB,MAAM,WAAW,GAAG,EAAE;oBAGtB,MAAM,WAAW,GAAG,EAAE;qBAGrB,MAAM,WAAW,GAAG,EAAE;EAI1C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAW7D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;iBAYhB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,UAAU,IAAI,YAAY,CAiCzC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAGlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc5E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY;qBAK5B,MAAM,WAAW,GAAG,EAAE;oBAGvB,MAAM,WAAW,GAAG,EAAE;oBAGtB,MAAM,WAAW,GAAG,EAAE;qBAGrB,MAAM,WAAW,GAAG,EAAE;EAI1C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAgB7D"}

package/dist/src/utils/config.js

@@ -15,9 +15,43 @@ const ConfigSchema = z.object({
     cacheDirectory: z.string().default('.mcp-adr-cache'),
     maxCacheSize: z.number().default(100 * 1024 * 1024), // 100MB
     analysisTimeout: z.number().default(30000), // 30 seconds
+    // Firecrawl configuration
+    firecrawlApiKey: z.string().optional(),
+    firecrawlBaseUrl: z.string().default('http://localhost:3000'),
+    firecrawlEnabled: z.boolean().default(false),
 });
 /**
  * Load and validate configuration from environment variables
+ *
+ * @description Loads server configuration from environment variables with fallback defaults.
+ * Validates all configuration values using Zod schema and returns a type-safe config object.
+ *
+ * @returns {ServerConfig} Validated configuration object with all required settings
+ *
+ * @throws {Error} When configuration validation fails or required values are missing
+ *
+ * @example
+ * ```typescript
+ * // Load configuration with environment variables
+ * process.env.PROJECT_PATH = '/path/to/project';
+ * process.env.LOG_LEVEL = 'DEBUG';
+ *
+ * const config = loadConfig();
+ * console.log(config.projectPath); // '/path/to/project'
+ * console.log(config.logLevel);    // 'DEBUG'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load configuration with defaults
+ * const config = loadConfig();
+ * console.log(config.adrDirectory);  // 'docs/adrs'
+ * console.log(config.cacheEnabled);  // true
+ * console.log(config.maxCacheSize);  // 104857600 (100MB)
+ * ```
+ *
+ * @since 2.0.0
+ * @category Configuration
  */
 export function loadConfig() {
     // Get PROJECT_PATH from environment or use current working directory
@@ -32,6 +66,10 @@ export function loadConfig() {
         cacheDirectory: process.env['CACHE_DIRECTORY'] || '.mcp-adr-cache',
         maxCacheSize: parseInt(process.env['MAX_CACHE_SIZE'] || '104857600'), // 100MB
         analysisTimeout: parseInt(process.env['ANALYSIS_TIMEOUT'] || '30000'), // 30 seconds
+        // Firecrawl configuration
+        firecrawlApiKey: process.env['FIRECRAWL_API_KEY'],
+        firecrawlBaseUrl: process.env['FIRECRAWL_BASE_URL'] || 'http://localhost:3000',
+        firecrawlEnabled: process.env['FIRECRAWL_ENABLED'] === 'true' || !!process.env['FIRECRAWL_API_KEY'],
     };
     try {
         return ConfigSchema.parse(rawConfig);
@@ -61,6 +99,38 @@ export function getCacheDirectoryPath(config) {
 }
 /**
  * Validate that the project path exists and is accessible
+ *
+ * @description Performs filesystem validation to ensure the specified project path
+ * exists, is accessible, and is a directory. This is critical for server initialization
+ * as all ADR analysis operations depend on a valid project root.
+ *
+ * @param {string} projectPath - Absolute or relative path to validate
+ *
+ * @returns {Promise<void>} Resolves if path is valid, rejects with descriptive error
+ *
+ * @throws {Error} When path doesn't exist, isn't a directory, or isn't accessible
+ *
+ * @example
+ * ```typescript
+ * // Validate existing project directory
+ * await validateProjectPath('/path/to/project');
+ * console.log('Project path is valid');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Handle validation errors
+ * try {
+ *   await validateProjectPath('/invalid/path');
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message);
+ *   // Error: PROJECT_PATH does not exist: /invalid/path
+ * }
+ * ```
+ *
+ * @since 2.0.0
+ * @category Configuration
+ * @category Validation
  */
 export async function validateProjectPath(projectPath) {
     const fs = await import('fs/promises');
@@ -115,5 +185,10 @@ export function printConfigSummary(config) {
     logger.info(`  Cache Directory: ${config.cacheDirectory}`);
     logger.info(`  Max Cache Size: ${Math.round(config.maxCacheSize / 1024 / 1024)}MB`);
     logger.info(`  Analysis Timeout: ${config.analysisTimeout}ms`);
+    logger.info(`  Firecrawl Enabled: ${config.firecrawlEnabled}`);
+    if (config.firecrawlEnabled) {
+        logger.info(`  Firecrawl Base URL: ${config.firecrawlBaseUrl}`);
+        logger.info(`  Firecrawl API Key: ${config.firecrawlApiKey ? '***configured***' : 'not set'}`);
+    }
 }
 //# sourceMappingURL=config.js.map

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

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

package/dist/src/utils/context-document-manager.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Metadata for tool context documents
+ */
+export interface ToolContextMetadata {
+    toolName: string;
+    toolVersion: string;
+    generated: string;
+    projectPath: string;
+    projectName: string;
+    status: 'success' | 'failed' | 'partial';
+    confidence?: number;
+}
+/**
+ * Decision record within a context document
+ */
+export interface Decision {
+    decision: string;
+    rationale: string;
+    alternatives?: string[];
+}
+/**
+ * Learning record from tool execution
+ */
+export interface Learnings {
+    successes: string[];
+    failures: string[];
+    recommendations: string[];
+    environmentSpecific: string[];
+}
+/**
+ * Related documents and references
+ */
+export interface RelatedDocuments {
+    adrs: string[];
+    configs: string[];
+    otherContexts: string[];
+}
+/**
+ * Complete tool context document structure
+ */
+export interface ToolContextDocument {
+    metadata: ToolContextMetadata;
+    quickReference: string;
+    executionSummary: {
+        status: string;
+        confidence?: number;
+        keyFindings: string[];
+    };
+    detectedContext: Record<string, any>;
+    generatedArtifacts?: string[];
+    keyDecisions?: Decision[];
+    learnings?: Learnings;
+    relatedDocuments?: RelatedDocuments;
+    rawData?: any;
+}
+/**
+ * Manages creation, storage, and retrieval of tool context documents
+ */
+export declare class ToolContextManager {
+    private contextDir;
+    private logger;
+    constructor(projectPath: string);
+    /**
+     * Initialize context directory structure
+     */
+    initialize(): Promise<void>;
+    /**
+     * Save a context document to the appropriate category
+     * @param category - Category subdirectory (bootstrap, deployment, etc.)
+     * @param document - Context document to save
+     * @returns Path to the saved document
+     */
+    saveContext(category: string, document: ToolContextDocument): Promise<string>;
+    /**
+     * Load the latest context document for a category
+     * @param category - Category to load from
+     * @returns Context document or null if not found
+     */
+    loadLatestContext(category: string): Promise<ToolContextDocument | null>;
+    /**
+     * Load a specific context document by timestamp
+     * @param category - Category to search in
+     * @param timestamp - Timestamp identifier
+     * @returns Context document or null if not found
+     */
+    loadContextByTimestamp(category: string, timestamp: string): Promise<ToolContextDocument | null>;
+    /**
+     * List all context documents in a category
+     * @param category - Category to list
+     * @returns Array of filenames
+     */
+    listContexts(category: string): Promise<string[]>;
+    /**
+     * Update the latest.md symlink or copy for a category
+     * @param category - Category directory
+     * @param filePath - Path to the latest context document
+     */
+    updateLatestSymlink(category: string, filePath: string): Promise<void>;
+    /**
+     * Clean up old context documents, keeping only the most recent N
+     * @param category - Category to clean up
+     * @param keepCount - Number of recent contexts to keep (default: 10)
+     */
+    cleanupOldContexts(category: string, keepCount?: number): Promise<void>;
+    /**
+     * Generate markdown content from a context document
+     * @param document - Context document to convert
+     * @returns Markdown string
+     */
+    generateMarkdown(document: ToolContextDocument): string;
+}
+//# sourceMappingURL=context-document-manager.d.ts.map

package/dist/src/utils/context-document-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-document-manager.d.ts","sourceRoot":"","sources":["../../../src/utils/context-document-manager.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,CAAC;IACF,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC;IAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAiB;gBAEnB,WAAW,EAAE,MAAM;IAK/B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCjC;;;;;OAKG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BnF;;;;OAIG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IA4B9E;;;;;OAKG;IACG,sBAAsB,CAC1B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAgCtC;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBvD;;;;OAIG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB5E;;;;OAIG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BjF;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM;CA2KxD"}