specweave 0.23.10 → 0.23.14

package/dist/src/core/cache/cache-manager.js

@@ -0,0 +1,304 @@
+import { promises as fs } from 'fs';
+import { existsSync } from 'fs';
+import path from 'path';
+import { consoleLogger } from '../../utils/logger.js';
+/**
+ * CacheManager - Manages file-based caching with TTL validation
+ *
+ * Features:
+ * - 24-hour TTL by default (configurable)
+ * - Atomic writes (temp file + rename)
+ * - Corruption detection and auto-recovery
+ * - Per-project cache separation
+ * - Thread-safe operations
+ *
+ * Cache file format:
+ * {
+ *   "data": <T>,
+ *   "timestamp": 1700000000000,
+ *   "ttl": 86400000
+ * }
+ */
+export class CacheManager {
+    constructor(projectRoot, options = {}) {
+        this.defaultTTL = 24 * 60 * 60 * 1000; // 24 hours in milliseconds
+        this.cacheDir = path.join(projectRoot, '.specweave', 'cache');
+        this.logger = options.logger ?? consoleLogger;
+        if (options.ttl) {
+            this.defaultTTL = options.ttl;
+        }
+    }
+    /**
+     * Get cached data if valid (within TTL)
+     *
+     * @param key Cache key (e.g., "jira-projects", "jira-BACKEND-deps")
+     * @returns Cached data or null if cache miss/expired/corrupted
+     */
+    async get(key) {
+        const filePath = this.getCachePath(key);
+        if (!existsSync(filePath)) {
+            this.logger.log(`Cache miss: ${key}`);
+            return null;
+        }
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const cached = JSON.parse(content);
+            // Validate cache structure
+            if (!this.isValidCacheStructure(cached)) {
+                this.logger.error(`Invalid cache structure for ${key}, deleting...`);
+                await this.delete(key);
+                return null;
+            }
+            // Check TTL
+            if (!this.isValid(cached)) {
+                const age = Date.now() - cached.timestamp;
+                const ageHours = (age / (1000 * 60 * 60)).toFixed(1);
+                this.logger.log(`Cache expired: ${key} (age: ${ageHours}h, TTL: ${cached.ttl / (1000 * 60 * 60)}h)`);
+                // Don't delete expired cache immediately - might be used as stale fallback
+                return null;
+            }
+            const remaining = cached.timestamp + cached.ttl - Date.now();
+            const remainingHours = (remaining / (1000 * 60 * 60)).toFixed(1);
+            this.logger.log(`Cache hit: ${key} (TTL remaining: ${remainingHours}h)`);
+            return cached.data;
+        }
+        catch (error) {
+            // Corruption detected
+            this.logger.error(`Cache corruption detected for ${key}: ${error.message}`);
+            await this.logCacheError(key, error);
+            await this.delete(key);
+            return null;
+        }
+    }
+    /**
+     * Get cached data even if expired (stale cache fallback)
+     *
+     * Used for rate limit fallback: when API rate limit hit,
+     * use stale cache instead of failing
+     *
+     * @param key Cache key
+     * @returns Cached data or null if missing/corrupted (ignores TTL)
+     */
+    async getStale(key) {
+        const filePath = this.getCachePath(key);
+        if (!existsSync(filePath)) {
+            this.logger.log(`No stale cache available: ${key}`);
+            return null;
+        }
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const cached = JSON.parse(content);
+            // Validate structure only (ignore TTL)
+            if (!this.isValidCacheStructure(cached)) {
+                this.logger.error(`Invalid cache structure for ${key}, deleting...`);
+                await this.delete(key);
+                return null;
+            }
+            const age = Date.now() - cached.timestamp;
+            const ageHours = (age / (1000 * 60 * 60)).toFixed(1);
+            const ttlHours = cached.ttl / (1000 * 60 * 60);
+            const expiredHoursAgo = (parseFloat(ageHours) - ttlHours).toFixed(1);
+            this.logger.warn(`Using stale cache: ${key} (age: ${ageHours}h, expired ${expiredHoursAgo}h ago)`);
+            return cached.data;
+        }
+        catch (error) {
+            this.logger.error(`Failed to read stale cache for ${key}: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Set cached data with current timestamp and TTL
+     *
+     * Uses atomic write pattern (temp file + rename) to prevent corruption
+     *
+     * @param key Cache key
+     * @param data Data to cache
+     * @param ttl Optional custom TTL (overrides default)
+     */
+    async set(key, data, ttl) {
+        await this.ensureCacheDir();
+        const filePath = this.getCachePath(key);
+        const tempPath = `${filePath}.tmp`;
+        const cached = {
+            data,
+            timestamp: Date.now(),
+            ttl: ttl ?? this.defaultTTL,
+        };
+        try {
+            // Write to temp file first (atomic write pattern)
+            await fs.writeFile(tempPath, JSON.stringify(cached, null, 2), 'utf-8');
+            // Rename temp file to final name (atomic operation)
+            await fs.rename(tempPath, filePath);
+            this.logger.log(`Cache set: ${key} (TTL: ${cached.ttl / (1000 * 60 * 60)}h)`);
+        }
+        catch (error) {
+            this.logger.error(`Failed to write cache for ${key}: ${error.message}`);
+            // Cleanup temp file if exists
+            if (existsSync(tempPath)) {
+                await fs.unlink(tempPath).catch(() => { });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Delete cached data
+     *
+     * @param key Cache key
+     */
+    async delete(key) {
+        const filePath = this.getCachePath(key);
+        if (existsSync(filePath)) {
+            await fs.unlink(filePath);
+            this.logger.log(`Cache deleted: ${key}`);
+        }
+    }
+    /**
+     * Clear all cached data
+     */
+    async clearAll() {
+        if (!existsSync(this.cacheDir)) {
+            return;
+        }
+        const files = await fs.readdir(this.cacheDir);
+        const jsonFiles = files.filter(f => f.endsWith('.json'));
+        for (const file of jsonFiles) {
+            const filePath = path.join(this.cacheDir, file);
+            await fs.unlink(filePath);
+        }
+        this.logger.log(`Cleared ${jsonFiles.length} cache files`);
+    }
+    /**
+     * Get cache statistics for monitoring
+     */
+    async getStats() {
+        const stats = {
+            totalFiles: 0,
+            totalSize: 0,
+            oldestCache: null,
+            oldestCacheAge: null,
+            providers: {},
+        };
+        if (!existsSync(this.cacheDir)) {
+            return stats;
+        }
+        const files = await fs.readdir(this.cacheDir);
+        const jsonFiles = files.filter(f => f.endsWith('.json'));
+        let oldestTimestamp = Date.now();
+        let oldestFile = null;
+        for (const file of jsonFiles) {
+            const filePath = path.join(this.cacheDir, file);
+            const fileStats = await fs.stat(filePath);
+            stats.totalFiles++;
+            stats.totalSize += fileStats.size;
+            // Determine provider from filename (e.g., "jira-projects.json" → "jira")
+            const provider = file.split('-')[0];
+            if (!stats.providers[provider]) {
+                stats.providers[provider] = { files: 0, size: 0 };
+            }
+            stats.providers[provider].files++;
+            stats.providers[provider].size += fileStats.size;
+            // Find oldest cache
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const cached = JSON.parse(content);
+                if (cached.timestamp < oldestTimestamp) {
+                    oldestTimestamp = cached.timestamp;
+                    oldestFile = file;
+                }
+            }
+            catch {
+                // Ignore corrupted files
+            }
+        }
+        if (oldestFile) {
+            stats.oldestCache = oldestFile;
+            stats.oldestCacheAge = (Date.now() - oldestTimestamp) / (1000 * 60 * 60); // hours
+        }
+        return stats;
+    }
+    /**
+     * Delete caches older than specified age
+     *
+     * @param maxAgeMs Maximum age in milliseconds
+     * @returns Count of deleted caches
+     */
+    async deleteOlderThan(maxAgeMs) {
+        if (!existsSync(this.cacheDir)) {
+            return 0;
+        }
+        const files = await fs.readdir(this.cacheDir);
+        const jsonFiles = files.filter(f => f.endsWith('.json'));
+        let deletedCount = 0;
+        const cutoffTime = Date.now() - maxAgeMs;
+        for (const file of jsonFiles) {
+            const filePath = path.join(this.cacheDir, file);
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const cached = JSON.parse(content);
+                if (cached.timestamp < cutoffTime) {
+                    await fs.unlink(filePath);
+                    deletedCount++;
+                    this.logger.log(`Deleted old cache: ${file}`);
+                }
+            }
+            catch {
+                // Delete corrupted files too
+                await fs.unlink(filePath);
+                deletedCount++;
+                this.logger.log(`Deleted corrupted cache: ${file}`);
+            }
+        }
+        return deletedCount;
+    }
+    /**
+     * Check if cached data is still valid (within TTL)
+     */
+    isValid(cached) {
+        const now = Date.now();
+        const age = now - cached.timestamp;
+        return age < cached.ttl;
+    }
+    /**
+     * Validate cache structure has required fields
+     */
+    isValidCacheStructure(cached) {
+        return (cached &&
+            typeof cached === 'object' &&
+            'data' in cached &&
+            'timestamp' in cached &&
+            'ttl' in cached &&
+            typeof cached.timestamp === 'number' &&
+            typeof cached.ttl === 'number');
+    }
+    /**
+     * Get full cache file path for a key
+     */
+    getCachePath(key) {
+        return path.join(this.cacheDir, `${key}.json`);
+    }
+    /**
+     * Ensure cache directory exists
+     */
+    async ensureCacheDir() {
+        if (!existsSync(this.cacheDir)) {
+            await fs.mkdir(this.cacheDir, { recursive: true });
+        }
+    }
+    /**
+     * Log cache errors to dedicated error log
+     */
+    async logCacheError(key, error) {
+        const logDir = path.join(path.dirname(this.cacheDir), 'logs');
+        const logPath = path.join(logDir, 'cache-errors.log');
+        try {
+            await fs.mkdir(logDir, { recursive: true });
+            const timestamp = new Date().toISOString();
+            const logEntry = `[${timestamp}] Cache error for ${key}: ${error.message}\n`;
+            await fs.appendFile(logPath, logEntry, 'utf-8');
+        }
+        catch {
+            // Ignore logging errors
+        }
+    }
+}
+//# sourceMappingURL=cache-manager.js.map

package/dist/src/core/cache/cache-manager.js.map

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

package/dist/src/core/cache/rate-limit-checker.d.ts

@@ -0,0 +1,92 @@
+import { Logger } from '../../utils/logger.js';
+/**
+ * Rate limit response headers (JIRA, GitHub, ADO)
+ */
+export interface RateLimitHeaders {
+    remaining?: number;
+    reset?: number;
+    retryAfter?: number;
+}
+/**
+ * Rate limit check result
+ */
+export interface RateLimitCheckResult {
+    canProceed: boolean;
+    reason?: string;
+    retryAfter?: number;
+    remaining?: number;
+}
+/**
+ * RateLimitChecker - Detects API rate limits and prevents hitting limits
+ *
+ * Features:
+ * - Parses rate limit headers from JIRA, GitHub, ADO
+ * - Handles 429 (Too Many Requests) errors
+ * - Suggests using stale cache when rate limit low
+ * - Supports exponential backoff
+ *
+ * Supported headers:
+ * - X-RateLimit-Remaining (JIRA Cloud, GitHub)
+ * - X-RateLimit-Reset (JIRA Cloud, GitHub)
+ * - Retry-After (Standard HTTP, JIRA Server, ADO)
+ * - x-ms-ratelimit-remaining (Azure DevOps)
+ *
+ * Threshold: 10 requests remaining (configurable)
+ */
+export declare class RateLimitChecker {
+    private logger;
+    private threshold;
+    constructor(options?: {
+        logger?: Logger;
+        threshold?: number;
+    });
+    /**
+     * Check if safe to proceed with API call based on response headers
+     *
+     * @param headers Response headers from previous API call
+     * @returns RateLimitCheckResult with canProceed flag
+     */
+    shouldProceed(headers: RateLimitHeaders): RateLimitCheckResult;
+    /**
+     * Handle 429 (Too Many Requests) error
+     *
+     * @param error Error object with response headers
+     * @returns Promise<void>
+     */
+    handleRateLimitError(error: any): Promise<void>;
+    /**
+     * Extract rate limit headers from HTTP response
+     *
+     * Supports multiple header formats:
+     * - JIRA Cloud: X-RateLimit-Remaining, X-RateLimit-Reset
+     * - GitHub: X-RateLimit-Remaining, X-RateLimit-Reset
+     * - ADO: x-ms-ratelimit-remaining-resource, Retry-After
+     * - Standard: Retry-After
+     *
+     * @param response HTTP response or response-like object
+     * @returns RateLimitHeaders object
+     */
+    extractHeaders(response: any): RateLimitHeaders;
+    /**
+     * Extract Retry-After from error response
+     *
+     * @param error Error object
+     * @returns Retry-After in seconds, or null
+     */
+    private extractRetryAfter;
+    /**
+     * Extract X-RateLimit-Reset from error response
+     *
+     * @param error Error object
+     * @returns Reset timestamp (Unix seconds), or null
+     */
+    private extractReset;
+    /**
+     * Check if error is a rate limit error (429 status)
+     *
+     * @param error Error object
+     * @returns True if 429 error
+     */
+    isRateLimitError(error: any): boolean;
+}
+//# sourceMappingURL=rate-limit-checker.d.ts.map

package/dist/src/core/cache/rate-limit-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit-checker.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/rate-limit-checker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAKjE;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,oBAAoB;IA4B9D;;;;;OAKG;IACG,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBrD;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,GAAG,GAAG,gBAAgB;IAsC/C;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;CAGtC"}

package/dist/src/core/cache/rate-limit-checker.js

@@ -0,0 +1,160 @@
+import { consoleLogger } from '../../utils/logger.js';
+/**
+ * RateLimitChecker - Detects API rate limits and prevents hitting limits
+ *
+ * Features:
+ * - Parses rate limit headers from JIRA, GitHub, ADO
+ * - Handles 429 (Too Many Requests) errors
+ * - Suggests using stale cache when rate limit low
+ * - Supports exponential backoff
+ *
+ * Supported headers:
+ * - X-RateLimit-Remaining (JIRA Cloud, GitHub)
+ * - X-RateLimit-Reset (JIRA Cloud, GitHub)
+ * - Retry-After (Standard HTTP, JIRA Server, ADO)
+ * - x-ms-ratelimit-remaining (Azure DevOps)
+ *
+ * Threshold: 10 requests remaining (configurable)
+ */
+export class RateLimitChecker {
+    constructor(options = {}) {
+        this.logger = options.logger ?? consoleLogger;
+        this.threshold = options.threshold ?? 10; // Default: warn when < 10 requests remaining
+    }
+    /**
+     * Check if safe to proceed with API call based on response headers
+     *
+     * @param headers Response headers from previous API call
+     * @returns RateLimitCheckResult with canProceed flag
+     */
+    shouldProceed(headers) {
+        const remaining = headers.remaining;
+        // No rate limit headers = assume safe to proceed
+        if (remaining === undefined) {
+            return { canProceed: true };
+        }
+        // Low rate limit = use stale cache instead
+        if (remaining < this.threshold) {
+            const reason = `Rate limit low (${remaining} requests remaining, threshold: ${this.threshold})`;
+            this.logger.warn(reason);
+            this.logger.warn('Suggestion: Use stale cache to avoid hitting rate limit');
+            return {
+                canProceed: false,
+                reason,
+                remaining,
+            };
+        }
+        // Safe to proceed
+        return {
+            canProceed: true,
+            remaining,
+        };
+    }
+    /**
+     * Handle 429 (Too Many Requests) error
+     *
+     * @param error Error object with response headers
+     * @returns Promise<void>
+     */
+    async handleRateLimitError(error) {
+        const retryAfter = this.extractRetryAfter(error);
+        const reset = this.extractReset(error);
+        if (retryAfter) {
+            this.logger.error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
+            this.logger.warn('Suggestion: Use stale cache while waiting for rate limit reset');
+        }
+        else if (reset) {
+            const waitTime = Math.max(0, reset - Date.now() / 1000);
+            this.logger.error(`Rate limit exceeded. Reset in ${Math.ceil(waitTime)} seconds.`);
+            this.logger.warn('Suggestion: Use stale cache while waiting for rate limit reset');
+        }
+        else {
+            this.logger.error('Rate limit exceeded (no retry time provided)');
+            this.logger.warn('Suggestion: Use stale cache and retry later');
+        }
+    }
+    /**
+     * Extract rate limit headers from HTTP response
+     *
+     * Supports multiple header formats:
+     * - JIRA Cloud: X-RateLimit-Remaining, X-RateLimit-Reset
+     * - GitHub: X-RateLimit-Remaining, X-RateLimit-Reset
+     * - ADO: x-ms-ratelimit-remaining-resource, Retry-After
+     * - Standard: Retry-After
+     *
+     * @param response HTTP response or response-like object
+     * @returns RateLimitHeaders object
+     */
+    extractHeaders(response) {
+        const headers = {};
+        // Handle different response formats (axios, fetch, etc.)
+        const getHeader = (name) => {
+            if (response.headers) {
+                // Axios-style headers object
+                if (typeof response.headers.get === 'function') {
+                    return response.headers.get(name) ?? undefined;
+                }
+                // Plain object headers
+                return response.headers[name] ?? response.headers[name.toLowerCase()] ?? undefined;
+            }
+            return undefined;
+        };
+        // X-RateLimit-Remaining (JIRA Cloud, GitHub)
+        const remaining = getHeader('X-RateLimit-Remaining') || getHeader('x-ms-ratelimit-remaining-resource');
+        if (remaining) {
+            headers.remaining = parseInt(remaining, 10);
+        }
+        // X-RateLimit-Reset (JIRA Cloud, GitHub)
+        const reset = getHeader('X-RateLimit-Reset');
+        if (reset) {
+            headers.reset = parseInt(reset, 10);
+        }
+        // Retry-After (Standard HTTP, JIRA Server, ADO)
+        const retryAfter = getHeader('Retry-After');
+        if (retryAfter) {
+            headers.retryAfter = parseInt(retryAfter, 10);
+        }
+        return headers;
+    }
+    /**
+     * Extract Retry-After from error response
+     *
+     * @param error Error object
+     * @returns Retry-After in seconds, or null
+     */
+    extractRetryAfter(error) {
+        if (error.response?.headers) {
+            const retryAfter = error.response.headers['Retry-After'] || error.response.headers['retry-after'];
+            if (retryAfter) {
+                return parseInt(retryAfter, 10);
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract X-RateLimit-Reset from error response
+     *
+     * @param error Error object
+     * @returns Reset timestamp (Unix seconds), or null
+     */
+    extractReset(error) {
+        if (error.response?.headers) {
+            const reset = error.response.headers['X-RateLimit-Reset'] ||
+                error.response.headers['x-ratelimit-reset'];
+            if (reset) {
+                return parseInt(reset, 10);
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if error is a rate limit error (429 status)
+     *
+     * @param error Error object
+     * @returns True if 429 error
+     */
+    isRateLimitError(error) {
+        return error.response?.status === 429 || error.status === 429;
+    }
+}
+//# sourceMappingURL=rate-limit-checker.js.map

package/dist/src/core/cache/rate-limit-checker.js.map

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

package/dist/src/core/progress/cancelation-handler.d.ts

@@ -0,0 +1,79 @@
+/**
+ * CancelationHandler - Graceful Ctrl+C (SIGINT) handling with state persistence
+ *
+ * Features:
+ * - Single Ctrl+C: Save state and exit gracefully
+ * - Double Ctrl+C (within 2s): Force exit immediately
+ * - Polling mechanism for cooperative cancelation
+ * - State persistence to resume later
+ *
+ * @module core/progress/cancelation-handler
+ */
+import type { Logger } from '../../utils/logger.js';
+/**
+ * Cancelation handler options
+ */
+export interface CancelationOptions {
+    /** State save callback - called when Ctrl+C is pressed */
+    onSaveState?: () => Promise<void>;
+    /** Logger instance */
+    logger?: Logger;
+    /** Force exit timeout in milliseconds (default: 2000ms) */
+    forceExitTimeout?: number;
+}
+/**
+ * CancelationHandler - Handles SIGINT gracefully with double Ctrl+C force exit
+ *
+ * @example
+ * ```typescript
+ * const handler = new CancelationHandler({
+ *   onSaveState: async () => {
+ *     await saveImportState();
+ *   }
+ * });
+ *
+ * handler.register();
+ *
+ * // In import loop
+ * for (const project of projects) {
+ *   if (handler.shouldCancel()) {
+ *     break;
+ *   }
+ *   await importProject(project);
+ * }
+ *
+ * handler.unregister();
+ * ```
+ */
+export declare class CancelationHandler {
+    private logger;
+    private onSaveState?;
+    private forceExitTimeout;
+    private cancelRequested;
+    private firstCtrlCTime;
+    private sigintHandler;
+    constructor(options?: CancelationOptions);
+    /**
+     * Register SIGINT listener
+     */
+    register(): void;
+    /**
+     * Unregister SIGINT listener
+     */
+    unregister(): void;
+    /**
+     * Check if cancelation was requested (polling mechanism)
+     *
+     * @returns true if Ctrl+C was pressed
+     */
+    shouldCancel(): boolean;
+    /**
+     * Handle SIGINT signal (Ctrl+C)
+     */
+    private handleSigint;
+    /**
+     * Reset cancelation state (useful for testing)
+     */
+    reset(): void;
+}
+//# sourceMappingURL=cancelation-handler.d.ts.map

package/dist/src/core/progress/cancelation-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancelation-handler.d.ts","sourceRoot":"","sources":["../../../../src/core/progress/cancelation-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAC,CAAsB;IAC1C,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,kBAAuB;IAM5C;;OAEG;IACH,QAAQ,IAAI,IAAI;IAQhB;;OAEG;IACH,UAAU,IAAI,IAAI;IAOlB;;;;OAIG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;YACW,YAAY;IAiC1B;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}