@eddacraft/anvil-runtime 0.1.0

package/dist/cache/providers/file-cache.js

@@ -0,0 +1,369 @@
+/**
+ * File-based cache provider
+ * Stores cache entries as JSON files in .anvil/cache/
+ */
+import { existsSync, unlinkSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFile, rm, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { createDebugger } from '@eddacraft/anvil-core';
+import { atomicWriteText } from '../../concurrency/atomic.js';
+const debug = createDebugger('cache');
+const CacheEntrySchema = z.object({
+    value: z.unknown(),
+    created_at: z.number(),
+    expires_at: z.number().optional(),
+    key: z.string(),
+    input_hash: z.string().optional(),
+});
+const CacheIndexEntrySchema = z.object({
+    file: z.string(),
+    created_at: z.number(),
+    expires_at: z.number().optional(),
+    size_bytes: z.number(),
+});
+const CacheIndexSchema = z.object({
+    version: z.number(),
+    entries: z.record(z.string(), CacheIndexEntrySchema),
+    stats: z.object({
+        hits: z.number(),
+        misses: z.number(),
+    }),
+});
+/**
+ * Default cache directory
+ */
+const DEFAULT_CACHE_DIR = '.anvil/cache';
+/**
+ * Default TTL: 24 hours
+ */
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * File-based cache provider
+ *
+ * Storage structure:
+ * .anvil/cache/
+ * ├── index.json         # Cache registry and stats
+ * └── entries/           # Cache entry files
+ *     └── {key-hash}.json
+ */
+export class FileCacheProvider {
+    name = 'file';
+    cacheDir;
+    entriesDir;
+    indexPath;
+    defaultTtl;
+    maxSizeBytes;
+    hmacKey;
+    index = null;
+    indexDirty = false;
+    constructor(workspaceRoot, config = {}) {
+        if (config.useGlobalCache) {
+            this.cacheDir = join(homedir(), '.anvil', 'cache');
+        }
+        else {
+            this.cacheDir = config.cacheDir || join(workspaceRoot, DEFAULT_CACHE_DIR);
+        }
+        this.entriesDir = join(this.cacheDir, 'entries');
+        this.indexPath = join(this.cacheDir, 'index.json');
+        this.defaultTtl = config.defaultTtl ?? DEFAULT_TTL_MS;
+        this.maxSizeBytes = config.maxSizeBytes ?? 100 * 1024 * 1024; // 100MB
+        // HMAC key: prefer env var, then persisted random key in cache dir
+        this.hmacKey = process.env['ANVIL_CACHE_HMAC_KEY'] ?? this.loadOrCreateHmacKey();
+    }
+    /**
+     * Load a persisted HMAC key from the cache dir, or generate and store one.
+     * The key is stored with 0o600 permissions so only the current user can read it.
+     */
+    loadOrCreateHmacKey() {
+        const keyPath = join(this.cacheDir, '.hmac-key');
+        try {
+            return readFileSync(keyPath, 'utf-8').trim();
+        }
+        catch {
+            const key = randomBytes(32).toString('hex');
+            mkdirSync(this.cacheDir, { recursive: true });
+            writeFileSync(keyPath, key, { mode: 0o600 });
+            return key;
+        }
+    }
+    async get(key) {
+        debug(`file-cache get: key=${key}`);
+        const index = await this.loadIndex();
+        const entryMeta = index.entries[key];
+        if (!entryMeta) {
+            debug(`file-cache miss: key=${key} (not in index)`);
+            index.stats.misses++;
+            this.indexDirty = true;
+            await this.saveIndex();
+            return null;
+        }
+        // Check expiration
+        if (entryMeta.expires_at && Date.now() > entryMeta.expires_at) {
+            debug(`file-cache miss: key=${key} (expired)`);
+            await this.invalidate(key);
+            index.stats.misses++;
+            this.indexDirty = true;
+            await this.saveIndex();
+            return null;
+        }
+        // Read entry file and verify HMAC integrity
+        const entryPath = join(this.entriesDir, entryMeta.file);
+        try {
+            const raw = await readFile(entryPath, 'utf-8');
+            const newlineIndex = raw.indexOf('\n');
+            const storedHmac = newlineIndex >= 0 ? raw.slice(0, newlineIndex) : '';
+            const content = newlineIndex >= 0 ? raw.slice(newlineIndex + 1) : raw;
+            // Verify HMAC integrity (mandatory — reject entries without valid HMAC)
+            if (!storedHmac || !/^[0-9a-f]{64}$/i.test(storedHmac)) {
+                debug('Cache entry missing HMAC, rejecting to prevent injection', { key });
+                await this.invalidate(key);
+                index.stats.misses++;
+                this.indexDirty = true;
+                await this.saveIndex();
+                return null;
+            }
+            const expectedHmac = this.computeHmac(content);
+            if (!timingSafeEqual(Buffer.from(storedHmac, 'hex'), Buffer.from(expectedHmac, 'hex'))) {
+                debug('Cache entry HMAC verification failed, possible tampering', { key });
+                await this.invalidate(key);
+                index.stats.misses++;
+                this.indexDirty = true;
+                await this.saveIndex();
+                return null;
+            }
+            const parseResult = CacheEntrySchema.safeParse(JSON.parse(content));
+            if (!parseResult.success) {
+                debug('Invalid cache entry schema, removing from index', parseResult.error);
+                await this.invalidate(key);
+                index.stats.misses++;
+                this.indexDirty = true;
+                await this.saveIndex();
+                return null;
+            }
+            const entry = parseResult.data;
+            debug(`file-cache hit: key=${key}`);
+            index.stats.hits++;
+            this.indexDirty = true;
+            await this.saveIndex();
+            return entry;
+        }
+        catch (error) {
+            debug('Cache entry file missing or corrupted, removing from index', error);
+            await this.invalidate(key);
+            index.stats.misses++;
+            this.indexDirty = true;
+            await this.saveIndex();
+            return null;
+        }
+    }
+    async set(key, value, options) {
+        debug(`file-cache set: key=${key} ttl=${options.ttl ?? this.defaultTtl}`);
+        await this.ensureCacheDir();
+        const index = await this.loadIndex();
+        const now = Date.now();
+        const expiresAt = options.ttl ? now + options.ttl : now + this.defaultTtl;
+        const entry = {
+            value,
+            created_at: now,
+            expires_at: expiresAt,
+            key,
+            input_hash: options.input_hash,
+        };
+        // Generate filename from key hash
+        const fileHash = this.hashKey(key);
+        const fileName = `${fileHash}.json`;
+        const filePath = join(this.entriesDir, fileName);
+        // Write entry file atomically to prevent corruption in multi-agent scenarios
+        // Include HMAC for integrity verification
+        const content = JSON.stringify(entry, null, 2);
+        const hmac = this.computeHmac(content);
+        await atomicWriteText(filePath, `${hmac}\n${content}`);
+        // Update index
+        index.entries[key] = {
+            file: fileName,
+            created_at: now,
+            expires_at: expiresAt,
+            size_bytes: Buffer.byteLength(content, 'utf-8'),
+        };
+        this.indexDirty = true;
+        await this.saveIndex();
+        // Check if cache size exceeds limit
+        await this.maybeEvict();
+    }
+    async invalidate(key) {
+        debug(`file-cache invalidate: key=${key}`);
+        const index = await this.loadIndex();
+        const entryMeta = index.entries[key];
+        if (!entryMeta) {
+            debug(`file-cache invalidate: key=${key} not found`);
+            return false;
+        }
+        // Remove entry file
+        const filePath = join(this.entriesDir, entryMeta.file);
+        try {
+            unlinkSync(filePath);
+        }
+        catch (error) {
+            debug('Cache entry file already deleted or inaccessible', error);
+        }
+        // Remove from index
+        delete index.entries[key];
+        this.indexDirty = true;
+        await this.saveIndex();
+        return true;
+    }
+    async invalidatePattern(pattern) {
+        debug(`file-cache invalidatePattern: pattern=${pattern}`);
+        const index = await this.loadIndex();
+        const regex = this.patternToRegex(pattern);
+        const keysToInvalidate = Object.keys(index.entries).filter((key) => regex.test(key));
+        debug(`file-cache invalidatePattern: matched ${keysToInvalidate.length} entries`);
+        for (const key of keysToInvalidate) {
+            await this.invalidate(key);
+        }
+        return keysToInvalidate.length;
+    }
+    async getStats() {
+        const index = await this.loadIndex();
+        const entries = Object.keys(index.entries).length;
+        const sizeBytes = Object.values(index.entries).reduce((sum, e) => sum + e.size_bytes, 0);
+        const totalRequests = index.stats.hits + index.stats.misses;
+        const hitRate = totalRequests > 0 ? (index.stats.hits / totalRequests) * 100 : 0;
+        return {
+            hits: index.stats.hits,
+            misses: index.stats.misses,
+            entries,
+            size_bytes: sizeBytes,
+            hit_rate: Math.round(hitRate * 100) / 100,
+        };
+    }
+    async clear() {
+        try {
+            await rm(this.cacheDir, { recursive: true, force: true });
+            this.index = null;
+            this.indexDirty = false;
+        }
+        catch (error) {
+            debug('Failed to clear cache directory (may not exist)', error);
+        }
+    }
+    async isAvailable() {
+        try {
+            await this.ensureCacheDir();
+            return true;
+        }
+        catch (error) {
+            debug('Cache directory not available or not writable', error);
+            return false;
+        }
+    }
+    /**
+     * Clean up expired entries
+     */
+    async cleanup() {
+        debug('file-cache cleanup: scanning for expired entries');
+        const index = await this.loadIndex();
+        const now = Date.now();
+        const expiredKeys = Object.entries(index.entries)
+            .filter(([, meta]) => meta.expires_at && meta.expires_at < now)
+            .map(([key]) => key);
+        debug(`file-cache cleanup: found ${expiredKeys.length} expired entries`);
+        for (const key of expiredKeys) {
+            await this.invalidate(key);
+        }
+        return expiredKeys.length;
+    }
+    async ensureCacheDir() {
+        if (!existsSync(this.entriesDir)) {
+            await mkdir(this.entriesDir, { recursive: true });
+        }
+    }
+    async loadIndex() {
+        if (this.index) {
+            return this.index;
+        }
+        try {
+            const content = await readFile(this.indexPath, 'utf-8');
+            const parseResult = CacheIndexSchema.safeParse(JSON.parse(content));
+            if (parseResult.success) {
+                this.index = parseResult.data;
+            }
+            else {
+                debug('Invalid cache index schema, creating new one', parseResult.error);
+                this.index = {
+                    version: 1,
+                    entries: {},
+                    stats: { hits: 0, misses: 0 },
+                };
+                this.indexDirty = true;
+            }
+        }
+        catch (error) {
+            debug('Cache index missing or corrupted, creating new one', error);
+            this.index = {
+                version: 1,
+                entries: {},
+                stats: { hits: 0, misses: 0 },
+            };
+            this.indexDirty = true;
+        }
+        return this.index;
+    }
+    async saveIndex() {
+        if (!this.indexDirty || !this.index) {
+            return;
+        }
+        await this.ensureCacheDir();
+        // Use atomic write to prevent corruption in multi-agent scenarios
+        await atomicWriteText(this.indexPath, JSON.stringify(this.index, null, 2));
+        this.indexDirty = false;
+    }
+    computeHmac(content) {
+        return createHmac('sha256', this.hmacKey).update(content).digest('hex');
+    }
+    hashKey(key) {
+        // Simple hash for filename safety
+        return createHash('sha256').update(key).digest('hex').slice(0, 32);
+    }
+    patternToRegex(pattern) {
+        const MAX_PATTERN_LENGTH = 200;
+        const MAX_WILDCARDS = 10;
+        if (pattern.length > MAX_PATTERN_LENGTH) {
+            throw new Error(`Cache pattern too long: ${pattern.length} > ${MAX_PATTERN_LENGTH}`);
+        }
+        const wildcardCount = (pattern.match(/\*/g) || []).length;
+        if (wildcardCount > MAX_WILDCARDS) {
+            throw new Error(`Too many wildcards in pattern: ${wildcardCount} > ${MAX_WILDCARDS}`);
+        }
+        const DOUBLE_STAR_PLACEHOLDER = '\x00DOUBLESTAR\x00';
+        const escaped = pattern
+            .replace(/\*\*/g, DOUBLE_STAR_PLACEHOLDER)
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '[^:]*')
+            .replace(new RegExp(DOUBLE_STAR_PLACEHOLDER, 'g'), '[^:]*(?::[^:]*)*');
+        return new RegExp(`^${escaped}$`);
+    }
+    async maybeEvict() {
+        const stats = await this.getStats();
+        if (stats.size_bytes <= this.maxSizeBytes) {
+            return;
+        }
+        const index = await this.loadIndex();
+        // Sort entries by creation time (oldest first)
+        const sortedEntries = Object.entries(index.entries).sort(([, a], [, b]) => a.created_at - b.created_at);
+        // Evict oldest entries until under limit
+        let currentSize = stats.size_bytes;
+        for (const [key] of sortedEntries) {
+            if (currentSize <= this.maxSizeBytes * 0.8) {
+                // Evict until 80% of limit
+                break;
+            }
+            const meta = index.entries[key];
+            currentSize -= meta.size_bytes;
+            await this.invalidate(key);
+        }
+    }
+}

package/dist/cache/providers/memory-cache.d.ts

@@ -0,0 +1,52 @@
+/**
+ * In-memory cache provider
+ * Used for watch mode and short-lived sessions
+ */
+import type { CacheProvider, CacheEntry, CacheSetOptions, CacheStats } from '../types.js';
+/**
+ * Memory cache configuration
+ */
+export interface MemoryCacheConfig {
+    /** Maximum number of entries (default: 1000) */
+    maxEntries?: number;
+    /** Default TTL in milliseconds (default: 5 minutes for watch mode) */
+    defaultTtl?: number;
+}
+/**
+ * In-memory cache provider
+ *
+ * Features:
+ * - Fast access for watch mode
+ * - LRU eviction when max entries exceeded
+ * - Automatic expiration cleanup
+ */
+export declare class MemoryCacheProvider implements CacheProvider {
+    readonly name = "memory";
+    private readonly cache;
+    private readonly accessOrder;
+    private readonly maxEntries;
+    private readonly defaultTtl;
+    private stats;
+    constructor(config?: MemoryCacheConfig);
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, value: T, options: CacheSetOptions): Promise<void>;
+    invalidate(key: string): Promise<boolean>;
+    invalidatePattern(pattern: string): Promise<number>;
+    getStats(): Promise<CacheStats>;
+    clear(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Get current entry count
+     */
+    get size(): number;
+    private updateAccessOrder;
+    private removeFromAccessOrder;
+    private evictLRU;
+    private patternToRegex;
+    private estimateSize;
+}
+//# sourceMappingURL=memory-cache.d.ts.map

package/dist/cache/providers/memory-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/providers/memory-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK1F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0C;IAChE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,KAAK,CAGX;gBAEU,MAAM,GAAE,iBAAsB;IAKpC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA0BlD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBtE,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQzC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBnD,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAqB/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAmBhC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,QAAQ;IAsBhB,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,YAAY;CAQrB"}

package/dist/cache/providers/memory-cache.js

@@ -0,0 +1,197 @@
+/**
+ * In-memory cache provider
+ * Used for watch mode and short-lived sessions
+ */
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('cache');
+/**
+ * In-memory cache provider
+ *
+ * Features:
+ * - Fast access for watch mode
+ * - LRU eviction when max entries exceeded
+ * - Automatic expiration cleanup
+ */
+export class MemoryCacheProvider {
+    name = 'memory';
+    cache = new Map();
+    accessOrder = [];
+    maxEntries;
+    defaultTtl;
+    stats = {
+        hits: 0,
+        misses: 0,
+    };
+    constructor(config = {}) {
+        this.maxEntries = config.maxEntries ?? 1000;
+        this.defaultTtl = config.defaultTtl ?? 5 * 60 * 1000; // 5 minutes
+    }
+    async get(key) {
+        debug(`memory-cache get: key=${key} size=${this.cache.size}`);
+        const entry = this.cache.get(key);
+        if (!entry) {
+            debug(`memory-cache miss: key=${key} (not found)`);
+            this.stats.misses++;
+            return null;
+        }
+        // Check expiration
+        if (entry.expires_at && Date.now() > entry.expires_at) {
+            debug(`memory-cache miss: key=${key} (expired)`);
+            await this.invalidate(key);
+            this.stats.misses++;
+            return null;
+        }
+        // Update access order (move to end)
+        this.updateAccessOrder(key);
+        debug(`memory-cache hit: key=${key}`);
+        this.stats.hits++;
+        return entry;
+    }
+    async set(key, value, options) {
+        debug(`memory-cache set: key=${key} size=${this.cache.size}/${this.maxEntries}`);
+        const now = Date.now();
+        const expiresAt = options.ttl ? now + options.ttl : now + this.defaultTtl;
+        const entry = {
+            value,
+            created_at: now,
+            expires_at: expiresAt,
+            key,
+            input_hash: options.input_hash,
+        };
+        // Check if we need to evict
+        if (!this.cache.has(key) && this.cache.size >= this.maxEntries) {
+            debug(`memory-cache set: evicting LRU (at capacity ${this.maxEntries})`);
+            this.evictLRU();
+        }
+        this.cache.set(key, entry);
+        this.updateAccessOrder(key);
+    }
+    async invalidate(key) {
+        debug(`memory-cache invalidate: key=${key}`);
+        const existed = this.cache.has(key);
+        this.cache.delete(key);
+        this.removeFromAccessOrder(key);
+        return existed;
+    }
+    async invalidatePattern(pattern) {
+        debug(`memory-cache invalidatePattern: pattern=${pattern}`);
+        const regex = this.patternToRegex(pattern);
+        const keysToDelete = [];
+        for (const key of this.cache.keys()) {
+            if (regex.test(key)) {
+                keysToDelete.push(key);
+            }
+        }
+        debug(`memory-cache invalidatePattern: matched ${keysToDelete.length} entries`);
+        for (const key of keysToDelete) {
+            await this.invalidate(key);
+        }
+        return keysToDelete.length;
+    }
+    async getStats() {
+        const entries = this.cache.size;
+        let sizeBytes = 0;
+        // Estimate size (rough approximation)
+        for (const entry of this.cache.values()) {
+            sizeBytes += this.estimateSize(entry);
+        }
+        const totalRequests = this.stats.hits + this.stats.misses;
+        const hitRate = totalRequests > 0 ? (this.stats.hits / totalRequests) * 100 : 0;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            entries,
+            size_bytes: sizeBytes,
+            hit_rate: Math.round(hitRate * 100) / 100,
+        };
+    }
+    async clear() {
+        this.cache.clear();
+        this.accessOrder.length = 0;
+        this.stats = { hits: 0, misses: 0 };
+    }
+    async isAvailable() {
+        return true; // Memory cache is always available
+    }
+    /**
+     * Clean up expired entries
+     */
+    async cleanup() {
+        debug(`memory-cache cleanup: scanning ${this.cache.size} entries`);
+        const now = Date.now();
+        const expiredKeys = [];
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expires_at && entry.expires_at < now) {
+                expiredKeys.push(key);
+            }
+        }
+        debug(`memory-cache cleanup: removing ${expiredKeys.length} expired entries`);
+        for (const key of expiredKeys) {
+            await this.invalidate(key);
+        }
+        return expiredKeys.length;
+    }
+    /**
+     * Get current entry count
+     */
+    get size() {
+        return this.cache.size;
+    }
+    updateAccessOrder(key) {
+        this.removeFromAccessOrder(key);
+        this.accessOrder.push(key);
+    }
+    removeFromAccessOrder(key) {
+        const index = this.accessOrder.indexOf(key);
+        if (index !== -1) {
+            this.accessOrder.splice(index, 1);
+        }
+    }
+    evictLRU() {
+        // Clean up expired entries first
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.expires_at && entry.expires_at < now) {
+                this.cache.delete(key);
+                this.removeFromAccessOrder(key);
+                if (this.cache.size < this.maxEntries) {
+                    return;
+                }
+            }
+        }
+        // If still over limit, evict least recently used
+        while (this.cache.size >= this.maxEntries && this.accessOrder.length > 0) {
+            const lruKey = this.accessOrder.shift();
+            if (lruKey) {
+                this.cache.delete(lruKey);
+            }
+        }
+    }
+    patternToRegex(pattern) {
+        const MAX_PATTERN_LENGTH = 200;
+        const MAX_WILDCARDS = 10;
+        if (pattern.length > MAX_PATTERN_LENGTH) {
+            throw new Error(`Cache pattern too long: ${pattern.length} > ${MAX_PATTERN_LENGTH}`);
+        }
+        const wildcardCount = (pattern.match(/\*/g) || []).length;
+        if (wildcardCount > MAX_WILDCARDS) {
+            throw new Error(`Too many wildcards in pattern: ${wildcardCount} > ${MAX_WILDCARDS}`);
+        }
+        const DOUBLE_STAR_PLACEHOLDER = '\x00DOUBLESTAR\x00';
+        const escaped = pattern
+            .replace(/\*\*/g, DOUBLE_STAR_PLACEHOLDER)
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '[^:]*')
+            .replace(new RegExp(DOUBLE_STAR_PLACEHOLDER, 'g'), '[^:]*(?::[^:]*)*');
+        return new RegExp(`^${escaped}$`);
+    }
+    estimateSize(entry) {
+        // Rough estimation of object size in memory
+        try {
+            return JSON.stringify(entry).length * 2; // UTF-16 chars
+        }
+        catch {
+            return 1024; // Default estimate for non-serialisable objects
+        }
+    }
+}

package/dist/cache/providers/null-cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Null cache provider (no-op)
+ * Used when caching is disabled via --no-cache flag
+ */
+import type { CacheProvider, CacheEntry, CacheSetOptions, CacheStats } from '../types.js';
+/**
+ * Null cache provider - disables caching
+ *
+ * All operations are no-ops that return appropriate null/empty values.
+ * Used when:
+ * - --no-cache flag is passed
+ * - Caching is disabled in configuration
+ * - Testing scenarios where caching should be bypassed
+ */
+export declare class NullCacheProvider implements CacheProvider {
+    readonly name = "null";
+    private stats;
+    get<T>(_key: string): Promise<CacheEntry<T> | null>;
+    set<T>(_key: string, _value: T, _options: CacheSetOptions): Promise<void>;
+    invalidate(_key: string): Promise<boolean>;
+    invalidatePattern(_pattern: string): Promise<number>;
+    getStats(): Promise<CacheStats>;
+    clear(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+}
+//# sourceMappingURL=null-cache.d.ts.map

package/dist/cache/providers/null-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-cache.d.ts","sourceRoot":"","sources":["../../../src/cache/providers/null-cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK1F;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,UAAU;IAEvB,OAAO,CAAC,KAAK,CAEX;IAEI,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAMnD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpD,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAU/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAGtC"}