specmem-hardwicksoftware 3.5.99

package/dist/utils/pathValidator.js

@@ -0,0 +1,320 @@
+/**
+ * pathValidator.ts - File Path Security for SpecMem
+ *
+ * yo this module sanitizes all file paths
+ * prevents directory traversal attacks and other sketchy stuff
+ * no more ../../../etc/passwd fr fr
+ *
+ * Issue #36 fix - input sanitization on file paths
+ */
+import * as path from 'path';
+import * as fs from 'fs';
+import { logger } from './logger.js';
+const DEFAULT_CONFIG = {
+    allowedBaseDirs: [], // Must be explicitly set
+    maxPathLength: 4096,
+    allowSymlinks: false,
+    blockedPatterns: [
+        /\.\./, // Directory traversal
+        /^\/etc\//i, // System config
+        /^\/var\/log/i, // System logs
+        /^\/proc\//i, // Process info
+        /^\/sys\//i, // System info
+        /^\/dev\//i, // Device files
+        /^~\//, // Home directory shorthand (use absolute paths)
+        /\x00/, // Null bytes
+        /[\r\n]/, // Newlines (injection)
+    ],
+    blockedFileNames: [
+        '.env',
+        '.env.local',
+        '.env.production',
+        'credentials.json',
+        'secrets.json',
+        '.ssh',
+        '.aws',
+        '.gnupg',
+        'id_rsa',
+        'id_ed25519',
+        '.netrc',
+        '.npmrc',
+        '.pypirc',
+    ]
+};
+/**
+ * PathValidator - secure file path handling
+ *
+ * Features that keep us SAFE:
+ * - Directory traversal detection
+ * - Path normalization
+ * - Whitelist enforcement
+ * - Symlink protection
+ * - Sensitive file blocking
+ */
+export class PathValidator {
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Validate and normalize a file path
+     */
+    validate(inputPath, basePath) {
+        // Check for null/undefined
+        if (!inputPath || typeof inputPath !== 'string') {
+            return {
+                valid: false,
+                normalizedPath: null,
+                error: 'Path must be a non-empty string'
+            };
+        }
+        // Trim whitespace
+        const trimmedPath = inputPath.trim();
+        // Check length
+        if (trimmedPath.length > this.config.maxPathLength) {
+            return {
+                valid: false,
+                normalizedPath: null,
+                error: `Path exceeds maximum length of ${this.config.maxPathLength}`,
+                securityIssue: 'path_too_long'
+            };
+        }
+        // Check for null bytes and newlines (injection attacks)
+        if (/[\x00\r\n]/.test(trimmedPath)) {
+            logger.warn({ path: trimmedPath.slice(0, 50) }, 'path contains dangerous characters');
+            return {
+                valid: false,
+                normalizedPath: null,
+                error: 'Path contains illegal characters',
+                securityIssue: 'injection_attempt'
+            };
+        }
+        // Check for directory traversal BEFORE normalization
+        if (this.containsTraversal(trimmedPath)) {
+            logger.warn({ path: trimmedPath }, 'directory traversal detected');
+            return {
+                valid: false,
+                normalizedPath: null,
+                error: 'Directory traversal not allowed',
+                securityIssue: 'directory_traversal'
+            };
+        }
+        // Check blocked patterns
+        for (const pattern of this.config.blockedPatterns) {
+            if (pattern.test(trimmedPath)) {
+                logger.warn({ path: trimmedPath, pattern: pattern.toString() }, 'path matches blocked pattern');
+                return {
+                    valid: false,
+                    normalizedPath: null,
+                    error: 'Path matches blocked pattern',
+                    securityIssue: 'blocked_pattern'
+                };
+            }
+        }
+        // Check blocked file names
+        const fileName = path.basename(trimmedPath);
+        if (this.config.blockedFileNames.includes(fileName) ||
+            this.config.blockedFileNames.includes(fileName.toLowerCase())) {
+            logger.warn({ path: trimmedPath, fileName }, 'blocked file name');
+            return {
+                valid: false,
+                normalizedPath: null,
+                error: 'Access to this file is not allowed',
+                securityIssue: 'blocked_file'
+            };
+        }
+        // Normalize the path
+        let normalizedPath;
+        try {
+            if (basePath) {
+                // Resolve relative to base path
+                normalizedPath = path.resolve(basePath, trimmedPath);
+            }
+            else if (path.isAbsolute(trimmedPath)) {
+                normalizedPath = path.normalize(trimmedPath);
+            }
+            else {
+                // Relative path without base - resolve against cwd
+                normalizedPath = path.resolve(process.cwd(), trimmedPath);
+            }
+        }
+        catch (error) {
+            return {
+                valid: false,
+                normalizedPath: null,
+                error: 'Failed to normalize path'
+            };
+        }
+        // Re-check for traversal after normalization
+        if (basePath) {
+            const normalizedBase = path.resolve(basePath);
+            if (!normalizedPath.startsWith(normalizedBase + path.sep) && normalizedPath !== normalizedBase) {
+                logger.warn({
+                    inputPath: trimmedPath,
+                    basePath,
+                    resolvedPath: normalizedPath
+                }, 'path escapes base directory');
+                return {
+                    valid: false,
+                    normalizedPath: null,
+                    error: 'Path must be within allowed directory',
+                    securityIssue: 'path_escape'
+                };
+            }
+        }
+        // Check whitelist if configured
+        if (this.config.allowedBaseDirs.length > 0) {
+            const isAllowed = this.config.allowedBaseDirs.some(baseDir => {
+                const normalizedBase = path.resolve(baseDir);
+                return normalizedPath.startsWith(normalizedBase + path.sep) || normalizedPath === normalizedBase;
+            });
+            if (!isAllowed) {
+                logger.warn({
+                    path: normalizedPath,
+                    allowedDirs: this.config.allowedBaseDirs
+                }, 'path not in whitelist');
+                return {
+                    valid: false,
+                    normalizedPath: null,
+                    error: 'Path is not in allowed directories',
+                    securityIssue: 'not_whitelisted'
+                };
+            }
+        }
+        // Check for symlinks if not allowed
+        if (!this.config.allowSymlinks) {
+            try {
+                const stat = fs.lstatSync(normalizedPath);
+                if (stat.isSymbolicLink()) {
+                    logger.warn({ path: normalizedPath }, 'symlink not allowed');
+                    return {
+                        valid: false,
+                        normalizedPath: null,
+                        error: 'Symbolic links are not allowed',
+                        securityIssue: 'symlink_blocked'
+                    };
+                }
+            }
+            catch {
+                // File doesn't exist yet - that's OK
+            }
+        }
+        return {
+            valid: true,
+            normalizedPath
+        };
+    }
+    /**
+     * Quick check for directory traversal patterns
+     */
+    containsTraversal(inputPath) {
+        // Check for various traversal patterns
+        const traversalPatterns = [
+            /\.\.\//, // ../
+            /\.\.\\/, // ..\
+            /\.\.$/, // ends with ..
+            /^\.\.$/, // just ..
+            /%2e%2e/i, // URL encoded ..
+            /%252e%252e/i, // Double URL encoded
+            /\.\./, // Any ..
+        ];
+        return traversalPatterns.some(p => p.test(inputPath));
+    }
+    /**
+     * Sanitize a filename (just the name, no path)
+     */
+    sanitizeFileName(fileName) {
+        // Remove path separators
+        let sanitized = fileName.replace(/[\/\\]/g, '_');
+        // Remove null bytes and control characters
+        sanitized = sanitized.replace(/[\x00-\x1f\x7f]/g, '');
+        // Remove leading/trailing dots and spaces
+        sanitized = sanitized.replace(/^[\s.]+|[\s.]+$/g, '');
+        // Replace multiple underscores with single
+        sanitized = sanitized.replace(/_+/g, '_');
+        // Limit length
+        if (sanitized.length > 255) {
+            const ext = path.extname(sanitized);
+            const base = path.basename(sanitized, ext);
+            sanitized = base.slice(0, 255 - ext.length) + ext;
+        }
+        return sanitized || 'unnamed';
+    }
+    /**
+     * Check if a path is within a specific directory
+     */
+    isWithinDirectory(targetPath, baseDir) {
+        const normalizedTarget = path.resolve(targetPath);
+        const normalizedBase = path.resolve(baseDir);
+        return normalizedTarget.startsWith(normalizedBase + path.sep) ||
+            normalizedTarget === normalizedBase;
+    }
+    /**
+     * Get a safe relative path
+     */
+    getSafeRelativePath(fullPath, baseDir) {
+        const validation = this.validate(fullPath, baseDir);
+        if (!validation.valid || !validation.normalizedPath) {
+            return null;
+        }
+        const normalizedBase = path.resolve(baseDir);
+        return path.relative(normalizedBase, validation.normalizedPath);
+    }
+    /**
+     * Add a directory to the whitelist
+     */
+    addAllowedBaseDir(dir) {
+        const normalized = path.resolve(dir);
+        if (!this.config.allowedBaseDirs.includes(normalized)) {
+            this.config.allowedBaseDirs.push(normalized);
+            logger.debug({ dir: normalized }, 'added to path whitelist');
+        }
+    }
+    /**
+     * Remove a directory from the whitelist
+     */
+    removeAllowedBaseDir(dir) {
+        const normalized = path.resolve(dir);
+        const index = this.config.allowedBaseDirs.indexOf(normalized);
+        if (index > -1) {
+            this.config.allowedBaseDirs.splice(index, 1);
+            logger.debug({ dir: normalized }, 'removed from path whitelist');
+        }
+    }
+}
+// Singleton instance
+let validatorInstance = null;
+/**
+ * Get the global path validator
+ */
+export function getPathValidator(config) {
+    if (!validatorInstance) {
+        validatorInstance = new PathValidator(config);
+    }
+    return validatorInstance;
+}
+/**
+ * Reset the global path validator (for testing)
+ */
+export function resetPathValidator() {
+    validatorInstance = null;
+}
+/**
+ * Convenience function - validate a path
+ */
+export function validatePath(inputPath, basePath) {
+    return getPathValidator().validate(inputPath, basePath);
+}
+/**
+ * Convenience function - sanitize a filename
+ */
+export function sanitizeFileName(fileName) {
+    return getPathValidator().sanitizeFileName(fileName);
+}
+/**
+ * Convenience function - check if path is within directory
+ */
+export function isPathWithin(targetPath, baseDir) {
+    return getPathValidator().isWithinDirectory(targetPath, baseDir);
+}
+//# sourceMappingURL=pathValidator.js.map

package/dist/utils/pathValidator.js.map

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

package/dist/utils/portAllocator.d.ts

@@ -0,0 +1,296 @@
+/**
+ * portAllocator.ts - Dynamic Port Allocation for SpecMem Instances
+ *
+ * Provides unique, consistent port allocation for each SpecMem instance
+ * based on project path. Uses deterministic hashing with conflict detection
+ * and automatic fallback to alternative ports.
+ *
+ * Strategy: Hash-based port generation with conflict detection
+ * - Hash project path to get a base port offset
+ * - Check for port conflicts
+ * - Persist allocated ports for consistency across restarts
+ * - Automatic retry with next available port if conflict detected
+ *
+ * @author hardwicksoftwareservices
+ */
+/**
+ * FORBIDDEN PORTS - These ports must NEVER be used
+ * Port 8787 is explicitly forbidden per project requirements
+ */
+export declare const FORBIDDEN_PORTS: readonly number[];
+/**
+ * Port configuration for SpecMem services
+ *
+ * IMPORTANT: Dynamic port range is 8595-8720 (125 ports for instances)
+ * Port 8787 is FORBIDDEN and must never be allocated
+ */
+export declare const PORT_CONFIG: {
+    /** Minimum port number for dynamic allocation */
+    readonly MIN_PORT: 8595;
+    /** Maximum port number for dynamic allocation (125 ports: 8595-8720) */
+    readonly MAX_PORT: 8720;
+    /** Total ports available in the dynamic range */
+    readonly DYNAMIC_RANGE_SIZE: 126;
+    /** Range size for each project's port block */
+    readonly PORT_RANGE_SIZE: 50;
+    /** Number of ports to allocate per instance (dashboard, coordination, postgres) */
+    readonly PORTS_PER_INSTANCE: 3;
+    /** Port indices within instance allocation */
+    readonly PORT_INDICES: {
+        readonly DASHBOARD: 0;
+        readonly COORDINATION: 1;
+        readonly POSTGRES: 2;
+    };
+    /** Reserved port ranges for common services to avoid */
+    readonly RESERVED_RANGES: readonly [{
+        readonly start: 8080;
+        readonly end: 8090;
+    }, {
+        readonly start: 3000;
+        readonly end: 3010;
+    }, {
+        readonly start: 5000;
+        readonly end: 5010;
+    }, {
+        readonly start: 5432;
+        readonly end: 5432;
+    }, {
+        readonly start: 6379;
+        readonly end: 6380;
+    }, {
+        readonly start: 27017;
+        readonly end: 27018;
+    }];
+    /** Default ports (fallback when no project-specific config) */
+    readonly DEFAULTS: {
+        readonly DASHBOARD: 8595;
+        readonly COORDINATION: 8596;
+        readonly POSTGRES: 5432;
+    };
+    /** Max attempts to find available ports */
+    readonly MAX_ALLOCATION_ATTEMPTS: 125;
+    /** PostgreSQL - always system postgres on 5432 (no dynamic allocation) */
+    readonly POSTGRES: {
+        readonly MIN_PORT: 5432;
+        readonly MAX_PORT: 5432;
+    };
+    /** System PostgreSQL port (always use system postgres on 5432) */
+    readonly SYSTEM_POSTGRES_PORT: 5432;
+};
+/**
+ * Allocated ports for a SpecMem instance
+ */
+export interface AllocatedPorts {
+    /** Dashboard web server port */
+    dashboard: number;
+    /** Coordination server port */
+    coordination: number;
+    /** PostgreSQL port - always system postgres 5432 */
+    postgres: number;
+    /** Project path this allocation is for */
+    projectPath: string;
+    /** Hash used for deterministic allocation */
+    projectHash: string;
+    /** Timestamp of allocation */
+    allocatedAt: number;
+    /** Whether ports were verified as available */
+    verified: boolean;
+}
+/**
+ * Port allocation configuration
+ */
+export interface PortAllocationConfig {
+    /** Project root path (used for hashing) */
+    projectPath: string;
+    /** Minimum port to use */
+    minPort?: number;
+    /** Maximum port to use */
+    maxPort?: number;
+    /** Whether to verify port availability */
+    verifyAvailability?: boolean;
+    /** Whether to persist allocation to project config */
+    persistAllocation?: boolean;
+    /** Custom config file path (default: .specmem/ports.json) */
+    configPath?: string;
+}
+/**
+ * Port configuration file structure
+ */
+interface PortConfigFile {
+    version: 1;
+    projectPath: string;
+    projectHash: string;
+    ports: {
+        dashboard: number;
+        coordination: number;
+        postgres?: number;
+    };
+    allocatedAt: number;
+    lastVerified?: number;
+}
+/**
+ * Generate a deterministic hash from project path
+ * Returns a number that can be used as a port offset
+ */
+export declare function hashProjectPath(projectPath: string): {
+    hash: string;
+    offset: number;
+};
+/**
+ * Calculate base port for a project
+ * Uses dynamic range 8595-8720 (125 ports), never uses forbidden port 8787
+ */
+export declare function calculateBasePort(projectPath: string): number;
+/**
+ * Get the default config file path for a project
+ */
+export declare function getConfigFilePath(projectPath: string, customPath?: string): string;
+/**
+ * Load persisted port configuration from file
+ */
+export declare function loadPortConfig(projectPath: string, configPath?: string): Promise<PortConfigFile | null>;
+/**
+ * Save port configuration to file
+ */
+export declare function savePortConfig(projectPath: string, ports: {
+    dashboard: number;
+    coordination: number;
+}, configPath?: string): Promise<boolean>;
+/**
+ * Check if a port is forbidden (must NEVER be used)
+ * Port 8787 is explicitly forbidden per project requirements
+ */
+export declare function isForbiddenPort(port: number): boolean;
+/**
+ * Check if a port is in a reserved range
+ */
+export declare function isReservedPort(port: number): boolean;
+/**
+ * Check if a port is within the valid dynamic allocation range
+ * Valid range: 8595-8720 (excluding forbidden ports)
+ */
+export declare function isInDynamicRange(port: number): boolean;
+/**
+ * Verify that allocated ports are available
+ */
+export declare function verifyPortsAvailable(ports: {
+    dashboard: number;
+    coordination: number;
+}, host?: string): Promise<{
+    dashboard: boolean;
+    coordination: boolean;
+}>;
+/**
+ * Find next available port pair starting from base port
+ * Uses dynamic allocation within range 8595-8720, never uses forbidden ports (8787)
+ */
+export declare function findAvailablePortPair(startPort: number, host?: string, maxAttempts?: number): Promise<{
+    dashboard: number;
+    coordination: number;
+} | null>;
+/**
+ * Calculate PostgreSQL port for a project using hash-based allocation
+ * Uses same deterministic hashing as dashboard/coordination but in the PostgreSQL range
+ */
+export declare function calculatePostgresPort(projectPath: string): number;
+/**
+ * Check if a port is being used by a PostgreSQL process
+ * This provides more specific detection than generic port checks
+ */
+export declare function isPostgresPortInUse(port: number, host?: string): Promise<boolean>;
+/**
+ * Verify PostgreSQL port is available
+ * Checks both generic port availability and PostgreSQL-specific indicators
+ */
+export declare function verifyPostgresPortAvailable(port: number, host?: string): Promise<boolean>;
+/**
+ * Find an available PostgreSQL port starting from the hash-based port
+ * Iterates through the PostgreSQL port range to find an unused port
+ */
+export declare function findAvailablePostgresPort(startPort: number, host?: string, maxAttempts?: number): Promise<number | null>;
+/**
+ * Allocate a PostgreSQL port for a project
+ *
+ * Process:
+ * 1. Check for existing allocation in ports.json
+ * 2. If found and port available, use it
+ * 3. Otherwise, calculate hash-based port
+ * 4. Find available port if conflicts exist
+ * 5. Persist allocation
+ */
+export declare function allocatePostgresPort(config: PortAllocationConfig): Promise<{
+    port: number;
+    projectPath: string;
+    projectHash: string;
+    verified: boolean;
+}>;
+/**
+ * Get PostgreSQL port synchronously (from cached allocation)
+ */
+export declare function getPostgresPort(): number;
+/**
+ * Get PostgreSQL connection string for the allocated port
+ */
+export declare function getPostgresConnectionString(database?: string, user?: string, host?: string): string;
+/**
+ * Allocate ports for a SpecMem instance
+ *
+ * Process:
+ * 1. Check for persisted port config
+ * 2. If found and ports available, use them
+ * 3. Otherwise, calculate hash-based ports
+ * 4. Find available ports if conflicts exist
+ * 5. Persist allocation for future use
+ */
+export declare function allocatePorts(config: PortAllocationConfig): Promise<AllocatedPorts>;
+/**
+ * Get allocated ports for the current project
+ * Uses singleton pattern for consistent ports across the application
+ */
+export declare function getInstancePorts(projectPath?: string, options?: Partial<PortAllocationConfig>): Promise<AllocatedPorts>;
+/**
+ * Get ports synchronously (uses cached value or defaults)
+ * Useful for immediate access before async allocation completes
+ */
+export declare function getInstancePortsSync(): AllocatedPorts | null;
+/**
+ * Get dashboard port (sync with fallback)
+ */
+export declare function getDashboardPort(): number;
+/**
+ * Get coordination port (sync with fallback)
+ */
+export declare function getCoordinationPort(): number;
+/**
+ * Reset allocated ports (for testing)
+ */
+export declare function resetAllocatedPorts(): void;
+/**
+ * Set allocated ports explicitly (for testing or external configuration)
+ */
+export declare function setAllocatedPorts(ports: AllocatedPorts): void;
+/**
+ * Format allocated ports for display
+ */
+export declare function formatPortsForDisplay(ports: AllocatedPorts): string;
+/**
+ * Get port allocation summary
+ */
+export declare function getPortAllocationSummary(ports: AllocatedPorts): {
+    dashboard: {
+        port: number;
+        url: string;
+    };
+    coordination: {
+        port: number;
+        wsUrl: string;
+    };
+    postgres: {
+        port: number;
+        connectionString: string;
+    };
+    projectPath: string;
+    verified: boolean;
+};
+export {};
+//# sourceMappingURL=portAllocator.d.ts.map

package/dist/utils/portAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portAllocator.d.ts","sourceRoot":"","sources":["../../src/utils/portAllocator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAEnC,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,WAAW;IACtB,iDAAiD;;IAEjD,wEAAwE;;IAExE,iDAAiD;;IAEjD,+CAA+C;;IAE/C,mFAAmF;;IAEnF,8CAA8C;;;;;;IAM9C,wDAAwD;;;;;;;;;;;;;;;;;;;;IASxD,+DAA+D;;;;;;IAM/D,2CAA2C;;IAE3C,0EAA0E;;;;;IAK1E,kEAAkE;;CAE1D,CAAC;AAMX;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,UAAU,cAAc;IACtB,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAerF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA0B7D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAoC7G;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAClD,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CA8BlB;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAClD,IAAI,GAAE,MAAoB,GACzB,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC,CAUxD;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,MAAoB,EAC1B,WAAW,GAAE,MAA4C,GACxD,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA4E7D;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAapG;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAoB,GACzB,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,MAAoB,EAC1B,WAAW,GAAE,MAA4C,GACxD,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoCxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAkGD;AAsCD;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,GAAE,MAAuC,EACjD,IAAI,GAAE,MAAuC,EAC7C,IAAI,GAAE,MAAoB,GACzB,MAAM,CAGR;AAMD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAwIzF;AAWD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACtC,OAAO,CAAC,cAAc,CAAC,CAoBzB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAM5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAE7D;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAMnE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG;IAC/D,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAiBA"}