@jterrats/smart-deployment 1.0.3

package/lib/utils/logger.js

@@ -0,0 +1,327 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+/**
+ * Log levels in order of severity
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "DEBUG";
+    LogLevel["INFO"] = "INFO";
+    LogLevel["WARN"] = "WARN";
+    LogLevel["ERROR"] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Numeric values for log level comparison
+ */
+const LOG_LEVEL_VALUES = {
+    [LogLevel.DEBUG]: 0,
+    [LogLevel.INFO]: 1,
+    [LogLevel.WARN]: 2,
+    [LogLevel.ERROR]: 3,
+};
+/**
+ * Default logger configuration
+ */
+const DEFAULT_CONFIG = {
+    level: LogLevel.INFO,
+    logToConsole: true,
+    logToFile: true,
+    format: 'json',
+    maxLogFileSizeMB: 10,
+    maxLogFiles: 5,
+};
+/**
+ * Performance timer for measuring operation duration
+ */
+export class PerformanceTimer {
+    startTime;
+    label;
+    constructor(label) {
+        this.label = label;
+        this.startTime = Date.now();
+    }
+    end() {
+        return Date.now() - this.startTime;
+    }
+    getLabel() {
+        return this.label;
+    }
+}
+/**
+ * Singleton Logger with file rotation and structured logging
+ *
+ * @example
+ * ```typescript
+ * const logger = Logger.getInstance({ component: 'MyComponent' });
+ * logger.info('Operation started', { userId: 123 });
+ * logger.error('Operation failed', { error, userId: 123 });
+ *
+ * const timer = logger.startTimer('expensive-operation');
+ * // ... do work ...
+ * logger.info('Operation completed', { duration: timer.end() });
+ * ```
+ */
+export class Logger {
+    static instances = new Map();
+    config;
+    logFilePath;
+    writeQueue = Promise.resolve();
+    /**
+     * Private constructor - use getInstance() instead
+     */
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        if (this.config.logToFile && !this.config.logDirectory) {
+            this.config.logDirectory = path.join(os.homedir(), '.sf', 'smart-deployment', 'logs');
+        }
+        if (this.config.logToFile && this.config.logDirectory) {
+            const sanitizedComponent = this.config.component.replaceAll(/[^\w-]/g, '_').toLowerCase();
+            const date = new Date().toISOString().split('T')[0];
+            this.logFilePath = path.join(this.config.logDirectory, `${sanitizedComponent}-${date}.log`);
+        }
+    }
+    /**
+     * Get logger instance for component (one instance per component)
+     */
+    static getInstance(config) {
+        const { component } = config;
+        if (!Logger.instances.has(component)) {
+            Logger.instances.set(component, new Logger(config));
+        }
+        return Logger.instances.get(component);
+    }
+    /**
+     * Reset all instances (for testing)
+     */
+    static resetInstances() {
+        Logger.instances.clear();
+    }
+    /**
+     * Log debug message
+     */
+    debug(message, context) {
+        this.log(LogLevel.DEBUG, message, context);
+    }
+    /**
+     * Log info message
+     */
+    info(message, context) {
+        this.log(LogLevel.INFO, message, context);
+    }
+    /**
+     * Log warning message
+     */
+    warn(message, context) {
+        this.log(LogLevel.WARN, message, context);
+    }
+    /**
+     * Log error message
+     */
+    error(message, context) {
+        this.log(LogLevel.ERROR, message, context);
+    }
+    /**
+     * Log with timer duration
+     */
+    logWithDuration(level, message, timer, context) {
+        this.log(level, message, {
+            ...context,
+            duration: timer.end(),
+            operation: timer.getLabel(),
+        });
+    }
+    /**
+     * Update logger configuration
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Flush any pending writes (useful for testing)
+     */
+    async flush() {
+        await this.writeQueue;
+    }
+    /**
+     * Core logging method
+     */
+    log(level, message, context) {
+        // Check if level is enabled
+        if (LOG_LEVEL_VALUES[level] < LOG_LEVEL_VALUES[this.config.level]) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            component: this.config.component,
+            message,
+        };
+        // Add context if provided
+        if (context) {
+            // Extract error if present
+            if (context.error instanceof Error) {
+                entry.error = {
+                    name: context.error.name,
+                    message: context.error.message,
+                    stack: context.error.stack,
+                };
+                // Remove error from context to avoid duplication
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { error: _, ...restContext } = context;
+                if (Object.keys(restContext).length > 0) {
+                    entry.context = restContext;
+                }
+            }
+            else {
+                entry.context = context;
+            }
+        }
+        // Log to console
+        if (this.config.logToConsole) {
+            this.logToConsoleOutput(entry);
+        }
+        // Log to file (async, non-blocking)
+        if (this.config.logToFile && this.logFilePath) {
+            void this.logToFileAsync(entry);
+        }
+    }
+    /**
+     * Log to console with color coding
+     */
+    logToConsoleOutput(entry) {
+        const formatted = this.formatEntry(entry);
+        switch (entry.level) {
+            case LogLevel.ERROR: {
+                // eslint-disable-next-line no-console
+                console.error(formatted);
+                break;
+            }
+            case LogLevel.WARN: {
+                // eslint-disable-next-line no-console
+                console.warn(formatted);
+                break;
+            }
+            default: {
+                // eslint-disable-next-line no-console
+                console.log(formatted);
+            }
+        }
+    }
+    /**
+     * Log to file asynchronously (queued to prevent race conditions)
+     */
+    async logToFileAsync(entry) {
+        // Queue writes to prevent concurrent file access
+        this.writeQueue = this.writeQueue.then(async () => {
+            try {
+                if (!this.logFilePath)
+                    return;
+                // Create log directory if it doesn't exist
+                await fs.mkdir(path.dirname(this.logFilePath), { recursive: true });
+                // Check if rotation is needed
+                await this.rotateIfNeeded();
+                // Format and write log entry
+                const formatted = this.formatEntry(entry);
+                await fs.appendFile(this.logFilePath, `${formatted}\n`, 'utf-8');
+            }
+            catch {
+                // Silently ignore file write errors (don't block application)
+            }
+        });
+        await this.writeQueue;
+    }
+    /**
+     * Check file size and rotate if needed
+     */
+    async rotateIfNeeded() {
+        if (!this.logFilePath)
+            return;
+        try {
+            const stats = await fs.stat(this.logFilePath);
+            const sizeMB = stats.size / (1024 * 1024);
+            if (sizeMB >= this.config.maxLogFileSizeMB) {
+                await this.rotateLogFile();
+            }
+        }
+        catch {
+            // File doesn't exist yet - no rotation needed
+        }
+    }
+    /**
+     * Rotate log file
+     */
+    async rotateLogFile() {
+        if (!this.logFilePath)
+            return;
+        try {
+            // Find existing rotated files
+            const dir = path.dirname(this.logFilePath);
+            const baseFileName = path.basename(this.logFilePath, '.log');
+            const files = await fs.readdir(dir);
+            const rotatedFiles = files
+                .filter((file) => file.startsWith(`${baseFileName}.`) && file.endsWith('.log'))
+                .map((file) => {
+                const match = /\.(\d+)\.log$/.exec(file);
+                return {
+                    file,
+                    index: match ? Number.parseInt(match[1], 10) : 0,
+                };
+            })
+                .sort((a, b) => b.index - a.index);
+            // Delete oldest files if we have too many
+            const filesToDelete = rotatedFiles.slice(this.config.maxLogFiles - 1);
+            await Promise.all(filesToDelete.map((f) => fs.unlink(path.join(dir, f.file))));
+            // Rotate existing files in parallel
+            await Promise.all(rotatedFiles.slice(0, this.config.maxLogFiles - 1).map(({ file, index }) => {
+                const oldPath = path.join(dir, file);
+                const newPath = path.join(dir, `${baseFileName}.${index + 1}.log`);
+                return fs.rename(oldPath, newPath);
+            }));
+            // Rotate current file to .1.log
+            await fs.rename(this.logFilePath, `${this.logFilePath.replace(/\.log$/, '')}.1.log`);
+        }
+        catch {
+            // Rotation failed - continue with current file
+        }
+    }
+    /**
+     * Format log entry based on configured format
+     */
+    formatEntry(entry) {
+        if (this.config.format === 'json') {
+            return JSON.stringify(entry);
+        }
+        // Text format
+        const parts = [`[${entry.timestamp}]`, `[${entry.level}]`, `[${entry.component}]`, entry.message];
+        if (entry.context && Object.keys(entry.context).length > 0) {
+            parts.push(JSON.stringify(entry.context));
+        }
+        if (entry.error) {
+            parts.push(`Error: ${entry.error.message}`);
+            if (entry.error.stack) {
+                parts.push(`\n${entry.error.stack}`);
+            }
+        }
+        return parts.join(' ');
+    }
+}
+/**
+ * Get or create logger instance
+ */
+export function getLogger(component, config) {
+    return Logger.getInstance({ component, ...config });
+}
+/**
+ * Create a performance timer for measuring operation duration
+ */
+export function startTimer(label) {
+    return new PerformanceTimer(label);
+}
+//# sourceMappingURL=logger.js.map

package/lib/utils/logger.js.map

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

package/lib/utils/network-handler.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Network Handler - US-072
+ * Enhanced network error handling with retries
+ *
+ * @ac US-072-AC-1: Detect network errors
+ * @ac US-072-AC-2: Exponential backoff retry
+ * @ac US-072-AC-3: Max retry limit (3)
+ * @ac US-072-AC-4: Timeout handling
+ * @ac US-072-AC-5: Fallback strategies
+ * @ac US-072-AC-6: User-friendly error messages
+ * @issue #72
+ */
+export type NetworkRequestOptions = {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout?: number;
+    retries?: number;
+};
+export type NetworkResponse<T> = {
+    data: T;
+    statusCode: number;
+    headers: Record<string, string>;
+    executionTime: number;
+};
+/**
+ * @ac US-072-AC-1: Detect network errors
+ * @ac US-072-AC-2: Exponential backoff retry
+ */
+export declare class NetworkHandler {
+    private readonly retryHandler;
+    private readonly defaultTimeout;
+    constructor(options?: {
+        timeout?: number;
+        maxRetries?: number;
+    });
+    /**
+     * @ac US-072-AC-2: Exponential backoff retry
+     * @ac US-072-AC-3: Max retry limit (3)
+     * @ac US-072-AC-4: Timeout handling
+     * Execute network request with retry
+     */
+    request<T>(options: NetworkRequestOptions): Promise<NetworkResponse<T>>;
+    /**
+     * @ac US-072-AC-4: Timeout handling
+     * Execute request with timeout
+     */
+    private executeRequest;
+    /**
+     * @ac US-072-AC-1: Detect network errors
+     * @ac US-072-AC-6: User-friendly error messages
+     * Transform generic error to specific network error
+     */
+    private transformError;
+    /**
+     * @ac US-072-AC-5: Fallback strategies
+     * Execute with fallback
+     */
+    requestWithFallback<T>(options: NetworkRequestOptions, fallback: () => T | Promise<T>): Promise<NetworkResponse<T> | {
+        data: T;
+        fromFallback: true;
+    }>;
+}

package/lib/utils/network-handler.js

@@ -0,0 +1,147 @@
+/**
+ * Network Handler - US-072
+ * Enhanced network error handling with retries
+ *
+ * @ac US-072-AC-1: Detect network errors
+ * @ac US-072-AC-2: Exponential backoff retry
+ * @ac US-072-AC-3: Max retry limit (3)
+ * @ac US-072-AC-4: Timeout handling
+ * @ac US-072-AC-5: Fallback strategies
+ * @ac US-072-AC-6: User-friendly error messages
+ * @issue #72
+ */
+import { NetworkError, TimeoutError, ConnectionError, HttpError } from '../errors/network-error.js';
+import { RetryHandler } from '../deployment/retry-handler.js';
+import { getLogger } from './logger.js';
+const logger = getLogger('NetworkHandler');
+/**
+ * @ac US-072-AC-1: Detect network errors
+ * @ac US-072-AC-2: Exponential backoff retry
+ */
+export class NetworkHandler {
+    retryHandler;
+    defaultTimeout;
+    constructor(options) {
+        this.defaultTimeout = options?.timeout ?? 30_000;
+        this.retryHandler = new RetryHandler({
+            maxRetries: options?.maxRetries ?? 3,
+            initialDelay: 1000,
+            maxDelay: 10_000,
+        });
+        logger.info('Network handler initialized', {
+            timeout: this.defaultTimeout,
+            maxRetries: options?.maxRetries ?? 3,
+        });
+    }
+    /**
+     * @ac US-072-AC-2: Exponential backoff retry
+     * @ac US-072-AC-3: Max retry limit (3)
+     * @ac US-072-AC-4: Timeout handling
+     * Execute network request with retry
+     */
+    async request(options) {
+        return this.retryHandler.executeWithRetry(async () => {
+            try {
+                const response = await this.executeRequest(options);
+                return response;
+            }
+            catch (error) {
+                // Transform to specific network error
+                throw this.transformError(error, options);
+            }
+        }, `network-${options.method ?? 'GET'}-${options.url}`);
+    }
+    /**
+     * @ac US-072-AC-4: Timeout handling
+     * Execute request with timeout
+     */
+    async executeRequest(options) {
+        const timeout = options.timeout ?? this.defaultTimeout;
+        const controller = new AbortController();
+        // Setup timeout
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, timeout);
+        try {
+            const response = await fetch(options.url, {
+                method: options.method ?? 'GET',
+                headers: options.headers,
+                body: options.body ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new HttpError(options.url, response.status, response.statusText);
+            }
+            const data = (await response.json());
+            return {
+                data,
+                statusCode: response.status,
+                headers: Object.fromEntries(response.headers.entries()),
+                executionTime: Date.now() - Date.now(),
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // Check if aborted (timeout)
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new TimeoutError(options.url, timeout);
+            }
+            throw error;
+        }
+    }
+    /**
+     * @ac US-072-AC-1: Detect network errors
+     * @ac US-072-AC-6: User-friendly error messages
+     * Transform generic error to specific network error
+     */
+    transformError(error, options) {
+        // Already a network error
+        if (error instanceof NetworkError) {
+            return error;
+        }
+        if (error instanceof Error) {
+            // Detect specific network error types
+            if (NetworkError.isNetworkError(error)) {
+                return new ConnectionError(options.url, error);
+            }
+            // Check for timeout
+            if (error.message.includes('timeout') || error.message.includes('ETIMEDOUT')) {
+                return new TimeoutError(options.url, options.timeout ?? this.defaultTimeout);
+            }
+            // Check for connection refused
+            if (error.message.includes('ECONNREFUSED')) {
+                return new ConnectionError(options.url, error);
+            }
+            // Generic network error
+            return new NetworkError(error.message, {
+                url: options.url,
+                originalError: error,
+            });
+        }
+        return new NetworkError('Unknown network error', {
+            url: options.url,
+        });
+    }
+    /**
+     * @ac US-072-AC-5: Fallback strategies
+     * Execute with fallback
+     */
+    async requestWithFallback(options, fallback) {
+        try {
+            return await this.request(options);
+        }
+        catch (error) {
+            logger.warn('Network request failed, using fallback', {
+                url: options.url,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            const data = await Promise.resolve(fallback());
+            return {
+                data,
+                fromFallback: true,
+            };
+        }
+    }
+}
+//# sourceMappingURL=network-handler.js.map

package/lib/utils/network-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-handler.js","sourceRoot":"","sources":["../../src/utils/network-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,GAAG,SAAS,CAAC,gBAAgB,CAAC,CAAC;AAkB3C;;;GAGG;AACH,MAAM,OAAO,cAAc;IACR,YAAY,CAAe;IAC3B,cAAc,CAAS;IAExC,YAAmB,OAAmD;QACpE,IAAI,CAAC,cAAc,GAAG,OAAO,EAAE,OAAO,IAAI,MAAM,CAAC;QACjD,IAAI,CAAC,YAAY,GAAG,IAAI,YAAY,CAAC;YACnC,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,CAAC;YACpC,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,6BAA6B,EAAE;YACzC,OAAO,EAAE,IAAI,CAAC,cAAc;YAC5B,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,CAAC;SACrC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,OAAO,CAAI,OAA8B;QACpD,OAAO,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,KAAK,IAAI,EAAE;YACnD,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,CAAI,OAAO,CAAC,CAAC;gBACvD,OAAO,QAAQ,CAAC;YAClB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,sCAAsC;gBACtC,MAAM,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC,EAAE,WAAW,OAAO,CAAC,MAAM,IAAI,KAAK,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,cAAc,CAAI,OAA8B;QAC5D,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC;QACvD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QAEzC,gBAAgB;QAChB,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC,EAAE,OAAO,CAAC,CAAC;QAEZ,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;gBACxC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;gBAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC7D,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;YACzE,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAM,CAAC;YAE1C,OAAO;gBACL,IAAI;gBACJ,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBACvD,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;aACvC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,6BAA6B;YAC7B,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC1D,MAAM,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,KAAc,EAAE,OAA8B;QACnE,0BAA0B;QAC1B,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,sCAAsC;YACtC,IAAI,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvC,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjD,CAAC;YAED,oBAAoB;YACpB,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC7E,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC;YAC/E,CAAC;YAED,+BAA+B;YAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC3C,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACjD,CAAC;YAED,wBAAwB;YACxB,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE;gBACrC,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,aAAa,EAAE,KAAK;aACrB,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,YAAY,CAAC,uBAAuB,EAAE;YAC/C,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,mBAAmB,CAC9B,OAA8B,EAC9B,QAA8B;QAE9B,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAI,OAAO,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,wCAAwC,EAAE;gBACpD,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC9D,CAAC,CAAC;YAEH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC/C,OAAO;gBACL,IAAI;gBACJ,YAAY,EAAE,IAAa;aAC5B,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}