specmem-hardwicksoftware 3.5.99

package/dist/utils/index.js

@@ -0,0 +1,71 @@
+/**
+ * utils/index.ts - Utility Module Exports
+ *
+ * yo this exports ALL the fire utility modules
+ * timer registry, path validation, metrics, all that fr fr
+ *
+ * Production readiness utilities for SpecMem
+ */
+// Timer Registry - Issue #18
+export { TimerRegistry, getTimerRegistry, resetTimerRegistry, registerInterval, registerTimeout, clearRegisteredTimer, clearAllTimers } from './timerRegistry.js';
+// Path Validator - Issue #36
+export { PathValidator, getPathValidator, resetPathValidator, validatePath, sanitizeFileName, isPathWithin } from './pathValidator.js';
+// Stats Cache - Issue #39
+export { StatsCache, DashboardStatsCache, getDashboardCache, resetDashboardCache } from './statsCache.js';
+// Circuit Breaker - Issue #44
+export { CircuitBreaker, CircuitState, CircuitBreakerError, CircuitBreakerTimeoutError, getCircuitBreaker, getCircuitBreakerRegistry, resetCircuitBreakerRegistry, DATABASE_BREAKER_CONFIG, API_BREAKER_CONFIG } from './circuitBreaker.js';
+// Metrics - Issue #27
+export { Counter, Gauge, Histogram, MetricsRegistry, getMetricsRegistry, resetMetricsRegistry, collectMetrics, getHttpRequestCounter, getHttpDurationHistogram, getDbQueryCounter, getDbDurationHistogram, getMcpToolCounter, getErrorCounter } from './metrics.js';
+// Tracing - Issue #43
+export { Tracer, Span, SpanStatus, SpanKind, ConsoleSpanExporter, InMemorySpanExporter, getTracer, resetTracer, startSpan, trace, traceSync, extractTraceContext, injectTraceContext } from './tracing.js';
+// File Processing Queue - Issue #16
+export { FileProcessingQueue, FileMutex, QueueItemStatus, getFileMutex, resetFileMutex, acquireFileLock, releaseFileLock, withFileLock, acquireAtomicLock, withAtomicLock, atomicMkdir, ensureSocketDirAtomic, 
+// Synchronous versions for use in config.ts and other sync contexts
+acquireAtomicLockSync, withAtomicLockSync, atomicMkdirSync, ensureSocketDirAtomicSync } from './fileProcessingQueue.js';
+// Re-export existing utilities
+export { logger } from './logger.js';
+export { getMemoryManager, MemoryManager, resetMemoryManager, LRUCache } from './memoryManager.js';
+// Chinese Compactor - Token Efficient Compression
+export { 
+// Core compression functions
+compressToTraditionalChinese, decompressFromTraditionalChinese, smartCompress, testSemanticPreservation, compressMemoryContext, 
+// Config-aware API (main entry points)
+shouldCompress, compactIfEnabled, compressMCPResponse, formatCompressedOutput, getCompressionStats, 
+// Internal exports for testing
+_internal as _compressionInternal } from './tokenCompressor.js';
+// Project Environment - Multi-instance isolation
+export { ensureProjectEnv, getProjectEnv, getSpawnEnv, // alias for getProjectEnv - use this when spawning child processes!
+getProjectEnvOnly, mergeWithProjectEnv, logProjectInfo, getPythonPath, // use this when spawning Python processes - respects venv & PYTHON_PATH
+// Re-exports from config
+getProjectPath, getProjectHash, getProjectHashFull, getInstanceDir, } from './projectEnv.js';
+// Session Injector - Screen session text injection with Enter key support
+export { getCurrentScreenSession, injectToCurrentSession, injectToSession, sendSpecialKey, selfMessage, isInScreenSession, listScreenSessions, } from './sessionInjector.js';
+// Progress Reporter - MCP-safe progress/loading bar system
+export { ProgressReporter, getProgressReporter, resetProgressReporter, reportProgress, reportStart, reportUpdate, reportComplete, reportError, reportRetry, setMcpServer, clearMcpServer, hasMcpServer, } from './progressReporter.js';
+// Safe Process Termination - Ownership-verified process management
+export { 
+// Ownership management
+registerProcessOwnership, registerProcessOwnershipSync, unregisterProcessOwnership, unregisterProcessOwnershipSync, getProcessOwnership, getProcessOwnershipSync, isOwnedProcess, 
+// Safe termination
+isProcessRunning, safeKillProcess, safeKillByPort, 
+// Screen session management
+getProjectScopedScreenName, isOwnedScreenSession, safeKillScreenSession, listOwnedScreenSessions, 
+// Docker container naming
+getProjectScopedContainerName, isOwnedContainer, 
+// Spawn with tracking
+spawnWithOwnership, 
+// Cleanup
+cleanupStaleOwnershipFiles, getOwnedProcesses, killAllOwnedProcesses, } from './safeProcessTermination.js';
+// Compact XML Response - Token-efficient XML formatting with compression
+export { compactXmlResponse, compactSearchResults, stripNewlines } from './compactXmlResponse.js';
+// Human Readable Output - Hook-style [SPECMEM-TOOL] tag formatting
+export { formatHumanReadable, formatHumanReadableStatus, formatHumanReadableError } from './humanReadableOutput.js';
+// Process Health Check - Robust process age checking and verification
+export { checkProcessHealth, } from './processHealthCheck.js';
+// COT Broadcast - Bridge between MCP tools and Dashboard
+export { broadcastCOT, cotStart, cotAnalyze, cotResult, cotError, clearCotLog } from './cotBroadcast.js';
+// Retry Helper - Exponential backoff for transient failures (Task #40)
+export { withRetry, tryWithRetry, retryQuery, isTransientDbError, calculateBackoffDelay, Retryable, DEFAULT_RETRY_CONFIG, AGGRESSIVE_RETRY_CONFIG, QUICK_RETRY_CONFIG } from './retryHelper.js';
+// Map Cleanup - Project-scoped Map memory leak prevention
+export { setupMapCleanup, setupMapCleanupWithEmbeddedTime, CleanableMap } from './mapCleanup.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

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

package/dist/utils/instanceManager.d.ts

@@ -0,0 +1,530 @@
+/**
+ * InstanceManager - Per-Project Instance Tracking for SpecMem
+ *
+ * Provides isolated instance management for each  session/project:
+ * - Each project gets its own .specmem/{project_hash}/ directory
+ * - PID files, sockets, and instance state are project-scoped
+ * - Global registry tracks all running instances across projects
+ * - Stale instance cleanup on startup
+ * - Kill command to terminate specific instances
+ *
+ * This fixes the issue where multiple SpecMem instances would conflict
+ * by writing to the same PID file in .specmem/
+ *
+ * @author hardwicksoftwareservices
+ */
+/**
+ * Docker container tracking for per-instance isolation
+ */
+export interface DockerContainers {
+    /** Embedding service container ID or name */
+    embedding?: string;
+    /** PostgreSQL container ID or name */
+    postgres?: string;
+}
+/**
+ * Port allocation for instance services
+ */
+export interface InstancePorts {
+    /** PostgreSQL port */
+    postgres?: number;
+    /** Embedding service port */
+    embedding?: number;
+    /** Dashboard web server port */
+    dashboard?: number;
+    /** Coordination/WebSocket port */
+    coordination?: number;
+}
+export interface InstanceInfo {
+    /** Process ID of the running instance */
+    pid: number;
+    /** Project path this instance is managing */
+    projectPath: string;
+    /** Hash of the project path (used for directory naming) */
+    projectHash: string;
+    /** When the instance started */
+    startTime: string;
+    /** Dashboard port if available */
+    dashboardPort?: number;
+    /** Coordination port if available */
+    coordinationPort?: number;
+    /** PostgreSQL port if available */
+    postgresPort?: number;
+    /** Embedding service port if available */
+    embeddingPort?: number;
+    /** Instance status */
+    status: 'running' | 'stopped' | 'crashed' | 'unknown';
+    /** Last heartbeat timestamp */
+    lastHeartbeat?: string;
+    /** Version of SpecMem */
+    version?: string;
+    /** Docker containers associated with this instance */
+    dockerContainers?: DockerContainers;
+    /** Port allocations for this instance */
+    ports?: InstancePorts;
+}
+export interface InstanceRegistry {
+    /** Version of the registry format */
+    version: 2;
+    /** Map of project hash to instance info */
+    instances: Record<string, InstanceInfo>;
+    /** Last updated timestamp */
+    lastUpdated: string;
+}
+export interface InstanceManagerConfig {
+    /** Base directory for all SpecMem data (default: ~/.specmem) */
+    baseDir?: string;
+    /** Project path for this instance */
+    projectPath: string;
+    /** Whether to auto-cleanup stale instances on init */
+    autoCleanup?: boolean;
+    /** Lock strategy: pid, socket, or both */
+    lockStrategy?: 'pid' | 'socket' | 'both';
+    /** Health check interval in ms */
+    healthCheckIntervalMs?: number;
+}
+/**
+ * Get the hashed project directory name for instance management (COLLISION-FREE!)
+ * Uses SHA256 hash of FULL project path to ensure different paths get different instances.
+ * This prevents collisions between /specmem and ~/specmem.
+ * Format: First 16 chars of hash (e.g., "a1b2c3d4e5f6a7b8")
+ */
+export declare function getProjectDirName(projectPath?: string): string;
+/**
+ * Generate a deterministic hash from project path (DEPRECATED)
+ * Uses first 16 characters of SHA256 for reasonable uniqueness while keeping paths short
+ * @deprecated Use getProjectDirName() for new code - it's human readable!
+ */
+export declare function hashProjectPath(projectPath: string): string;
+/**
+ * Get the full hash of a project path (for registry lookups)
+ * @deprecated Use getProjectDirName() for new code - it's human readable!
+ */
+export declare function getFullProjectHash(projectPath: string): string;
+/**
+ * Check if a process with the given PID is running
+ */
+export declare function isProcessRunning(pid: number): boolean;
+/**
+ * Check if a process is a SpecMem/Node process
+ */
+export declare function isSpecMemProcess(pid: number): boolean;
+/**
+ * InstanceManager - Manages per-project SpecMem instances
+ *
+ * Key features:
+ * - Project-scoped directories: ~/.specmem/{project_hash}/
+ * - Global registry: ~/.specmem/instance-registry.json
+ * - Socket-based locking for reliable instance detection
+ * - Automatic stale instance cleanup
+ */
+export declare class InstanceManager {
+    private config;
+    private projectDirName;
+    private projectHash;
+    private instanceDir;
+    private lockSocket;
+    private heartbeatInterval;
+    private initialized;
+    constructor(config: InstanceManagerConfig);
+    /**
+     * Get the instance directory for this project
+     */
+    getInstanceDir(): string;
+    /**
+     * Get the path to a file in the instance directory
+     */
+    getFilePath(filename: string): string;
+    /**
+     * Ensure the instance directory exists
+     */
+    ensureInstanceDir(): Promise<void>;
+    /**
+     * Ensure the instance directory exists (sync version)
+     */
+    ensureInstanceDirSync(): void;
+    /**
+     * Read the PID from the PID file
+     */
+    readPid(): number | null;
+    /**
+     * Write PID to the PID file
+     */
+    writePid(pid: number): void;
+    /**
+     * Remove the PID file
+     */
+    removePid(): void;
+    /**
+     * Get the age of the PID file in milliseconds
+     */
+    getPidFileAge(): number | null;
+    /**
+     * Try to acquire a socket-based lock
+     * Returns true if lock acquired, false if another instance is running
+     */
+    tryAcquireSocketLock(): boolean;
+    /**
+     * Release the socket lock
+     */
+    releaseSocketLock(): void;
+    /**
+     * Check if a socket lock is held by another process
+     */
+    checkSocketLock(): Promise<boolean>;
+    /**
+     * Get current instance info
+     */
+    getInstanceInfo(): InstanceInfo;
+    /**
+     * Write instance state to file
+     */
+    writeInstanceState(info?: Partial<InstanceInfo>): void;
+    /**
+     * Read instance state from file
+     */
+    readInstanceState(): InstanceInfo | null;
+    /**
+     * Remove instance state file
+     */
+    removeInstanceState(): void;
+    /**
+     * Get path to the global registry file
+     */
+    private getRegistryPath;
+    /**
+     * Load the global instance registry
+     */
+    loadRegistry(): InstanceRegistry;
+    /**
+     * Save the global instance registry
+     */
+    saveRegistry(registry: InstanceRegistry): void;
+    /**
+     * Register this instance in the global registry
+     */
+    registerInstance(ports?: {
+        dashboard?: number;
+        coordination?: number;
+        postgres?: number;
+    }): void;
+    /**
+     * Unregister this instance from the global registry
+     */
+    unregisterInstance(): void;
+    /**
+     * Update heartbeat in the registry
+     */
+    updateHeartbeat(): void;
+    /**
+     * Get all registered instances
+     */
+    getAllInstances(): InstanceInfo[];
+    /**
+     * Check if an instance is already running for this project
+     */
+    isInstanceRunning(): Promise<boolean>;
+    /**
+     * Clean up stale instances from the registry
+     * Registry is now keyed by readable project dir name (e.g., "myproject")
+     */
+    cleanupStaleInstances(): Promise<{
+        cleaned: string[];
+        running: string[];
+    }>;
+    /**
+     * Clean up stale locks for THIS project only (replaces cleanupStaleLocks in index.ts)
+     *
+     * SAFETY: This method operates ONLY within this project's instance directory.
+     * The PID file and instance state are project-scoped, so we can safely:
+     * 1. Kill processes whose PID is in OUR project's PID file
+     * 2. Clean up OUR project's lock files
+     *
+     * We NEVER touch processes or files from other projects.
+     */
+    cleanupStaleLocks(): void;
+    /**
+     * Initialize the instance manager
+     * Acquires locks, writes PID, registers in global registry
+     */
+    initialize(): Promise<{
+        success: boolean;
+        alreadyRunning?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Start heartbeat updates
+     */
+    private startHeartbeat;
+    /**
+     * Stop heartbeat updates
+     */
+    private stopHeartbeat;
+    /**
+     * Shutdown the instance manager
+     * Releases locks, removes PID, unregisters from registry
+     */
+    shutdown(): void;
+    /**
+     * Check if initialized
+     */
+    isInitialized(): boolean;
+}
+/**
+ * Result from cleaning up same-project instances
+ */
+export interface CleanupSameProjectResult {
+    /** PIDs that were successfully killed */
+    killed: number[];
+    /** PIDs that were skipped (e.g., our own process) */
+    skipped: number[];
+    /** Errors encountered during cleanup */
+    errors: string[];
+}
+/**
+ * Clean up any existing SpecMem instances running for the SAME project.
+ * This is called at startup to ensure only ONE instance per project.
+ *
+ * SAFETY: This function ONLY touches instances for the given projectPath.
+ * It uses getProjectDirName() to match instances, never hashes.
+ * Different projects are completely unaffected.
+ *
+ * Flow:
+ * 1. Read the registry to find any existing instances for this project
+ * 2. If found and PID is not our current process:
+ *    - Check if process is still running
+ *    - If running, send SIGTERM and wait up to 5 seconds
+ *    - If still alive, send SIGKILL
+ *    - Clean up PID file, socket file, and registry entry
+ * 3. Also clean up any associated Docker containers
+ *
+ * @param projectPath - Path to the project (used to derive projectDirName)
+ * @param options - Optional configuration
+ * @returns Object with killed PIDs, skipped PIDs, and any errors
+ */
+export declare function cleanupSameProjectInstances(projectPath: string, options?: {
+    baseDir?: string;
+    forceDocker?: boolean;
+    removeVolumes?: boolean;
+}): CleanupSameProjectResult;
+/**
+ * Ensure only a single SpecMem instance runs for a project.
+ * This is the "safe" entry point for startup that:
+ * 1. Cleans up any existing same-project instances
+ * 2. Initializes the new instance
+ *
+ * @param config - Instance manager configuration
+ * @returns Result from initialization (success or failure)
+ */
+export declare function ensureSingleInstance(config: InstanceManagerConfig): Promise<{
+    success: boolean;
+    alreadyRunning?: boolean;
+    error?: string;
+    cleanupResult?: CleanupSameProjectResult;
+}>;
+/**
+ * Kill a specific SpecMem instance by project path, dir name, or hash
+ * Also cleans up associated Docker containers
+ * Now supports readable project dir names (e.g., "myproject")
+ *
+ * SAFETY: This function is used for EXPLICIT user-requested kills (e.g., CLI commands).
+ * It reads the PID from the project's own PID file, ensuring we only kill processes
+ * that were registered for that specific project. The lookup flow is:
+ *
+ * 1. User provides project identifier (path, dir name, or hash)
+ * 2. We resolve to instance directory: ~/.specmem/instances/{identifier}/
+ * 3. Read PID from that directory's specmem.pid file
+ * 4. Kill only that specific PID
+ *
+ * This ensures cross-project safety because each project has its own PID file.
+ */
+export declare function killInstance(projectPathOrNameOrHash: string, options?: {
+    baseDir?: string;
+    signal?: NodeJS.Signals;
+    force?: boolean;
+    cleanupDocker?: boolean;
+    removeVolumes?: boolean;
+}): Promise<{
+    success: boolean;
+    pid?: number;
+    error?: string;
+    dockerCleanup?: {
+        embedding?: {
+            stopped: boolean;
+            containerId?: string;
+        };
+        postgres?: {
+            stopped: boolean;
+            containerId?: string;
+        };
+    };
+}>;
+/**
+ * Kill all running SpecMem instances
+ */
+export declare function killAllInstances(options?: {
+    baseDir?: string;
+    signal?: NodeJS.Signals;
+    force?: boolean;
+    excludeSelf?: boolean;
+}): Promise<{
+    killed: number[];
+    failed: number[];
+    errors: string[];
+}>;
+/**
+ * List all running instances with Docker container status
+ */
+export declare function listInstances(options?: {
+    baseDir?: string;
+    includeDockerStatus?: boolean;
+}): InstanceInfo[];
+/**
+ * Extended instance listing with full Docker and port details
+ */
+export interface InstanceListEntry extends InstanceInfo {
+    /** Whether the main process is alive */
+    processAlive: boolean;
+    /** Docker container statuses */
+    docker: {
+        embedding: {
+            id?: string;
+            running: boolean;
+        };
+        postgres: {
+            id?: string;
+            running: boolean;
+        };
+    };
+    /** Calculated/allocated ports */
+    allocatedPorts: {
+        dashboard: number;
+        coordination: number;
+        postgres: number;
+        embedding: number;
+    };
+}
+/**
+ * List all instances with comprehensive Docker and port information
+ */
+export declare function listInstancesDetailed(options?: {
+    baseDir?: string;
+}): InstanceListEntry[];
+/**
+ * Get or create the global instance manager
+ */
+export declare function getInstanceManager(config?: InstanceManagerConfig): InstanceManager;
+/**
+ * Reset the global instance manager (for testing)
+ */
+export declare function resetInstanceManager(): void;
+/**
+ * Check if instance manager is available
+ */
+export declare function hasInstanceManager(): boolean;
+/**
+ * Migrate from old .specmem/ directory to new per-project structure
+ * This handles the transition from single .specmem/ to ~/.specmem/instances/{dirname}/
+ * Now uses readable project dir names instead of hashes!
+ */
+export declare function migrateFromOldStructure(projectPath: string): Promise<void>;
+/**
+ * Register a Docker container for this project instance
+ * Now uses readable project dir name for instance directories!
+ *
+ * @param projectPath - Project path (uses SPECMEM_PROJECT_PATH env if not provided)
+ * @param containerType - Type of container: 'embedding' or 'postgres'
+ * @param containerId - Docker container ID or name
+ */
+export declare function registerDockerContainer(projectPath: string, containerType: 'embedding' | 'postgres', containerId: string): Promise<void>;
+/**
+ * Get Docker containers for a project instance
+ * Now uses readable project dir name for instance directories!
+ *
+ * @param projectPath - Project path
+ * @returns Object with embedding and postgres container IDs
+ */
+export declare function getDockerContainers(projectPath: string): Promise<DockerContainers>;
+/**
+ * Check if a Docker container is running
+ *
+ * @param containerId - Container ID or name
+ * @returns True if container is running
+ */
+export declare function isDockerContainerRunning(containerId: string): boolean;
+/**
+ * Stop and remove a Docker container
+ *
+ * @param containerId - Container ID or name
+ * @param options - Optional: force remove, remove volumes
+ * @returns True if successfully stopped
+ */
+export declare function stopDockerContainer(containerId: string, options?: {
+    force?: boolean;
+    removeVolumes?: boolean;
+}): Promise<boolean>;
+/**
+ * Clean up all Docker containers for a project instance
+ *
+ * @param projectPath - Project path
+ * @param options - Optional: force stop, remove volumes
+ * @returns Object with results for each container type
+ */
+export declare function cleanupDockerContainers(projectPath: string, options?: {
+    force?: boolean;
+    removeVolumes?: boolean;
+}): Promise<{
+    embedding?: {
+        stopped: boolean;
+        containerId?: string;
+    };
+    postgres?: {
+        stopped: boolean;
+        containerId?: string;
+    };
+}>;
+/**
+ * Calculate deterministic ports for an instance based on project hash.
+ * Uses the project path hash to generate unique, consistent port allocations.
+ *
+ * IMPORTANT: Uses dynamic range 8595-8720 (125 ports)
+ * Port 8787 is FORBIDDEN and will never be allocated
+ *
+ * Port ranges:
+ * - Dashboard: 8595-8720 (dynamic, skip 8787)
+ * - Coordination: 8595-8720 (dynamic, skip 8787)
+ * - PostgreSQL: 5433-5532 (unchanged)
+ * - Embedding: 9000-9099 (unchanged)
+ *
+ * @param projectPath - Project path to calculate ports for
+ * @returns Port allocations for all services
+ */
+export declare function calculateInstancePorts(projectPath: string): {
+    postgres: number;
+    embedding: number;
+    dashboard: number;
+    coordination: number;
+};
+/**
+ * Get instance ports, either from cache/registry or calculate new ones.
+ * This is the main entry point for getting port allocations.
+ * Now uses readable project dir name for registry lookups!
+ *
+ * @param projectPath - Project path (defaults to SPECMEM_PROJECT_PATH or cwd)
+ * @returns Port allocations for all services
+ */
+export declare function getInstancePortsFromManager(projectPath?: string): {
+    postgres: number;
+    embedding: number;
+    dashboard: number;
+    coordination: number;
+};
+/**
+ * Register port allocations for an instance
+ * Now uses readable project dir name for registry lookups!
+ *
+ * @param projectPath - Project path
+ * @param ports - Port allocations to register
+ */
+export declare function registerInstancePorts(projectPath: string, ports: InstancePorts): void;
+//# sourceMappingURL=instanceManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instanceManager.d.ts","sourceRoot":"","sources":["../../src/utils/instanceManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACtD,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,yCAAyC;IACzC,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,OAAO,EAAE,CAAC,CAAC;IACX,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACxC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACzC,kCAAkC;IAClC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAuBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAarD;AAWD;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,WAAW,CAAkB;gBAEzB,MAAM,EAAE,qBAAqB;IAmBzC;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIrC;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxC;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAc7B;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAWxB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM3B;;OAEG;IACH,SAAS,IAAI,IAAI;IASjB;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAc9B;;;OAGG;IACH,oBAAoB,IAAI,OAAO;IA8C/B;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAezB;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAkCzC;;OAEG;IACH,eAAe,IAAI,YAAY;IAY/B;;OAEG;IACH,kBAAkB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAUtD;;OAEG;IACH,iBAAiB,IAAI,YAAY,GAAG,IAAI;IAUxC;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAa3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,YAAY,IAAI,gBAAgB;IAuBhC;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAa9C;;OAEG;IACH,gBAAgB,CAAC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAWhG;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAM1B;;OAEG;IACH,eAAe,IAAI,IAAI;IAQvB;;OAEG;IACH,eAAe,IAAI,YAAY,EAAE;IASjC;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC;IAsB3C;;;OAGG;IACG,qBAAqB,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAiDhF;;;;;;;;;OASG;IACH,iBAAiB,IAAI,IAAI;IAkEzB;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA+C3F;;OAEG;IACH,OAAO,CAAC,cAAc;IAWtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACH,QAAQ,IAAI,IAAI;IAWhB;;OAEG;IACH,aAAa,IAAI,OAAO;CAGzB;AAMD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GACA,wBAAwB,CA6K1B;AA2CD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,wBAAwB,CAAC;CAC1C,CAAC,CA8CD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAChC,uBAAuB,EAAE,MAAM,EAC/B,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GACA,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE;QACd,SAAS,CAAC,EAAE;YAAE,OAAO,EAAE,OAAO,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACvD,QAAQ,CAAC,EAAE;YAAE,OAAO,EAAE,OAAO,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACvD,CAAC;CACH,CAAC,CAoKD;AAiBD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAqCnE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,YAAY,EAAE,CA+DjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,wCAAwC;IACxC,YAAY,EAAE,OAAO,CAAC;IACtB,gCAAgC;IAChC,MAAM,EAAE;QACN,SAAS,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC;QAC7C,QAAQ,EAAE;YAAE,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,OAAO,CAAA;SAAE,CAAC;KAC7C,CAAC;IACF,iCAAiC;IACjC,cAAc,EAAE;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,EAAE,CAiEzF;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CAgBlF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAMD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChF;AAkCD;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,WAAW,GAAG,UAAU,EACvC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAa3B;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAUrE;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACrD,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,GACrD,OAAO,CAAC;IACT,SAAS,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD,CAAC,CAwCD;AA4CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,CA0CA;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,CAmBA;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,GACnB,IAAI,CAYN"}