specweave 0.23.8 → 0.23.12

package/dist/src/core/cache/cache-manager.d.ts

@@ -0,0 +1,119 @@
+import { Logger } from '../../utils/logger.js';
+/**
+ * Cached data wrapper with TTL metadata
+ */
+export interface CachedData<T> {
+    data: T;
+    timestamp: number;
+    ttl: number;
+}
+/**
+ * Cache statistics for monitoring and debugging
+ */
+export interface CacheStats {
+    totalFiles: number;
+    totalSize: number;
+    oldestCache: string | null;
+    oldestCacheAge: number | null;
+    providers: {
+        [provider: string]: {
+            files: number;
+            size: number;
+        };
+    };
+}
+/**
+ * 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 declare class CacheManager {
+    private cacheDir;
+    private logger;
+    private defaultTTL;
+    constructor(projectRoot: string, options?: {
+        logger?: Logger;
+        ttl?: number;
+    });
+    /**
+     * 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
+     */
+    get<T>(key: string): Promise<T | 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)
+     */
+    getStale<T>(key: string): Promise<T | 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)
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * Delete cached data
+     *
+     * @param key Cache key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cached data
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get cache statistics for monitoring
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Delete caches older than specified age
+     *
+     * @param maxAgeMs Maximum age in milliseconds
+     * @returns Count of deleted caches
+     */
+    deleteOlderThan(maxAgeMs: number): Promise<number>;
+    /**
+     * Check if cached data is still valid (within TTL)
+     */
+    private isValid;
+    /**
+     * Validate cache structure has required fields
+     */
+    private isValidCacheStructure;
+    /**
+     * Get full cache file path for a key
+     */
+    private getCachePath;
+    /**
+     * Ensure cache directory exists
+     */
+    private ensureCacheDir;
+    /**
+     * Log cache errors to dedicated error log
+     */
+    private logCacheError;
+}
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/src/core/cache/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../../../../src/core/cache/cache-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAiB,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,CAAC;IACR,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE;QACT,CAAC,QAAQ,EAAE,MAAM,GAAG;YAClB,KAAK,EAAE,MAAM,CAAC;YACd,IAAI,EAAE,MAAM,CAAC;SACd,CAAC;KACH,CAAC;CACH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAA+B;gBAG/C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;KACT;IASR;;;;;OAKG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IA0C5C;;;;;;;;OAQG;IACG,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAkCjD;;;;;;;;OAQG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/D;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB/B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAwDrC;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkCxD;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;YACW,cAAc;IAM5B;;OAEG;YACW,aAAa;CAa5B"}

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"}