@deimoscloud/coreai 0.1.9 → 0.1.11

package/src/cache/interfaces.ts

@@ -1,283 +0,0 @@
-/**
- * Cache Interfaces
- *
- * Interface definitions for the cache system.
- */
-
-import type {
-  CacheEntry,
-  CacheMetadata,
-  CacheOptions,
-  CacheListOptions,
-  CacheStats,
-  CacheStatus,
-  SyncResult,
-} from './types.js';
-
-/**
- * Cache provider interface
- *
- * Defines the contract for cache implementations.
- */
-export interface CacheProvider {
-  /**
-   * Initialize the cache (create directories, load index)
-   */
-  initialize(): Promise<void>;
-
-  /**
-   * Check if the cache is initialized
-   */
-  isInitialized(): boolean;
-
-  /**
-   * Get a cached entry by key
-   *
-   * @param key - Cache key
-   * @param options - Optional cache options
-   * @returns The cached entry or null if not found/expired
-   */
-  get<T = string>(key: string, options?: CacheOptions): Promise<CacheEntry<T> | null>;
-
-  /**
-   * Get the content only (convenience method)
-   *
-   * @param key - Cache key
-   * @param options - Optional cache options
-   * @returns The cached content or null if not found/expired
-   */
-  getContent<T = string>(key: string, options?: CacheOptions): Promise<T | null>;
-
-  /**
-   * Set a cache entry
-   *
-   * @param key - Cache key
-   * @param content - Content to cache
-   * @param metadata - Partial metadata (key and cachedAt will be set automatically)
-   * @param options - Optional cache options
-   */
-  set<T = string>(
-    key: string,
-    content: T,
-    metadata: Partial<CacheMetadata>,
-    options?: CacheOptions
-  ): Promise<void>;
-
-  /**
-   * Check if a key exists in the cache
-   *
-   * @param key - Cache key
-   * @returns True if the key exists (regardless of expiration)
-   */
-  has(key: string): Promise<boolean>;
-
-  /**
-   * Delete a cache entry
-   *
-   * @param key - Cache key
-   * @returns True if the entry was deleted
-   */
-  delete(key: string): Promise<boolean>;
-
-  /**
-   * Get the status of a cache entry
-   *
-   * @param key - Cache key
-   * @returns The cache status or null if not found
-   */
-  getStatus(key: string): Promise<CacheStatus | null>;
-
-  /**
-   * Get metadata for a cache entry
-   *
-   * @param key - Cache key
-   * @returns The metadata or null if not found
-   */
-  getMetadata(key: string): Promise<CacheMetadata | null>;
-
-  /**
-   * Update metadata for a cache entry
-   *
-   * @param key - Cache key
-   * @param metadata - Partial metadata to update
-   */
-  updateMetadata(key: string, metadata: Partial<CacheMetadata>): Promise<void>;
-
-  /**
-   * List cache entries
-   *
-   * @param options - List filter options
-   * @returns Array of metadata entries
-   */
-  list(options?: CacheListOptions): Promise<CacheMetadata[]>;
-
-  /**
-   * Get cache statistics
-   */
-  getStats(): Promise<CacheStats>;
-
-  /**
-   * Clear all cache entries
-   *
-   * @returns Number of entries cleared
-   */
-  clear(): Promise<number>;
-
-  /**
-   * Clear expired entries only
-   *
-   * @returns Number of entries cleared
-   */
-  clearExpired(): Promise<number>;
-
-  /**
-   * Clear entries by source
-   *
-   * @param source - Source to clear
-   * @returns Number of entries cleared
-   */
-  clearBySource(source: string): Promise<number>;
-
-  /**
-   * Clear entries by tag
-   *
-   * @param tag - Tag to clear
-   * @returns Number of entries cleared
-   */
-  clearByTag(tag: string): Promise<number>;
-}
-
-/**
- * Remote fetcher interface
- *
- * Used by the cache to fetch content from remote sources.
- */
-export interface RemoteFetcher {
-  /**
-   * Fetch content from a remote source
-   *
-   * @param url - Source URL or identifier
-   * @param options - Fetch options
-   * @returns The fetched content and metadata
-   */
-  fetch(
-    url: string,
-    options?: FetchOptions
-  ): Promise<{ content: string; metadata: Partial<CacheMetadata> }>;
-
-  /**
-   * Check if content has changed (conditional fetch)
-   *
-   * @param url - Source URL or identifier
-   * @param etag - Previous ETag
-   * @returns True if content has changed
-   */
-  hasChanged(url: string, etag?: string): Promise<boolean>;
-}
-
-/**
- * Options for remote fetching
- */
-export interface FetchOptions {
-  /**
-   * Request timeout in milliseconds
-   */
-  timeout?: number;
-
-  /**
-   * ETag for conditional fetching
-   */
-  etag?: string;
-
-  /**
-   * Custom headers
-   */
-  headers?: Record<string, string>;
-}
-
-/**
- * Cache manager interface
- *
- * Higher-level interface that combines caching with remote fetching.
- */
-export interface CacheManager {
-  /**
-   * Get content with cache-first strategy
-   *
-   * 1. Check cache
-   * 2. If cached and valid, return cached content
-   * 3. If stale or missing, fetch from remote
-   * 4. Cache the fetched content
-   * 5. Return the content
-   *
-   * @param key - Cache key
-   * @param url - Remote URL to fetch if not cached
-   * @param options - Cache and fetch options
-   */
-  getWithFallback<T = string>(
-    key: string,
-    url: string,
-    options?: CacheOptions & FetchOptions
-  ): Promise<CacheEntry<T>>;
-
-  /**
-   * Sync all entries from a source
-   *
-   * @param source - Source to sync
-   * @param options - Sync options
-   */
-  syncSource(source: string, options?: SyncOptions): Promise<SyncResult>;
-
-  /**
-   * Sync specific entries
-   *
-   * @param keys - Keys to sync
-   * @param options - Sync options
-   */
-  syncEntries(keys: string[], options?: SyncOptions): Promise<SyncResult>;
-
-  /**
-   * Register a fetcher for a source
-   *
-   * @param source - Source identifier
-   * @param fetcher - Fetcher implementation
-   */
-  registerFetcher(source: string, fetcher: RemoteFetcher): void;
-
-  /**
-   * Check if a fetcher is registered for a source
-   *
-   * @param source - Source identifier
-   */
-  hasFetcher(source: string): boolean;
-
-  /**
-   * Get the underlying cache provider
-   */
-  getCache(): CacheProvider;
-}
-
-/**
- * Options for sync operations
- */
-export interface SyncOptions {
-  /**
-   * Force refresh all entries
-   */
-  force?: boolean;
-
-  /**
-   * Continue on error
-   */
-  continueOnError?: boolean;
-
-  /**
-   * Maximum concurrent fetches
-   */
-  concurrency?: number;
-
-  /**
-   * Progress callback
-   */
-  onProgress?: (completed: number, total: number) => void;
-}

package/src/cache/manager.test.ts

@@ -1,266 +0,0 @@
-/**
- * Cache Manager Tests
- */
-
-import { promises as fs } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-import { CacheManager, createCacheManager } from './manager.js';
-import { FileCacheProvider } from './provider.js';
-import { CacheError } from './types.js';
-import type { RemoteFetcher } from './index.js';
-
-describe('CacheManager', () => {
-  let testDir: string;
-  let cacheProvider: FileCacheProvider;
-  let manager: CacheManager;
-
-  // Mock fetcher for testing
-  const createMockFetcher = (responses: Record<string, string>): RemoteFetcher => ({
-    async fetch(url: string) {
-      const content = responses[url];
-      if (!content) {
-        throw new Error(`Not found: ${url}`);
-      }
-      return {
-        content,
-        metadata: {
-          contentType: 'text/plain',
-          etag: `etag-${url}`,
-          title: `Title for ${url}`,
-        },
-      };
-    },
-    async hasChanged(_url: string, _etag?: string) {
-      return true; // Always changed for testing
-    },
-  });
-
-  beforeEach(async () => {
-    testDir = join(tmpdir(), `manager-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    await fs.mkdir(testDir, { recursive: true });
-
-    cacheProvider = new FileCacheProvider({ basePath: testDir });
-    await cacheProvider.initialize();
-
-    manager = new CacheManager({
-      cache: cacheProvider,
-      defaultTtl: 3600,
-    });
-  });
-
-  afterEach(async () => {
-    try {
-      await fs.rm(testDir, { recursive: true, force: true });
-    } catch {
-      // Ignore cleanup errors
-    }
-  });
-
-  describe('constructor', () => {
-    it('should create manager with options', () => {
-      expect(manager).toBeInstanceOf(CacheManager);
-    });
-
-    it('should use default values', () => {
-      const m = new CacheManager({ cache: cacheProvider });
-      expect(m).toBeInstanceOf(CacheManager);
-    });
-  });
-
-  describe('registerFetcher', () => {
-    it('should register a fetcher', () => {
-      const fetcher = createMockFetcher({});
-      manager.registerFetcher('github', fetcher);
-      expect(manager.hasFetcher('github')).toBe(true);
-    });
-
-    it('should track registered sources', () => {
-      manager.registerFetcher('github', createMockFetcher({}));
-      manager.registerFetcher('confluence', createMockFetcher({}));
-
-      const sources = manager.getRegisteredSources();
-      expect(sources).toContain('github');
-      expect(sources).toContain('confluence');
-    });
-  });
-
-  describe('getWithFallback', () => {
-    it('should fetch and cache content', async () => {
-      const fetcher = createMockFetcher({
-        'https://github.com/test': 'GitHub content',
-      });
-      manager.registerFetcher('github', fetcher);
-
-      const entry = await manager.getWithFallback('test-key', 'https://github.com/test');
-
-      expect(entry.content).toBe('GitHub content');
-      expect(entry.metadata.source).toBe('github');
-    });
-
-    it('should return cached content on second call', async () => {
-      const responses = { 'https://github.com/test': 'Original content' };
-      const fetcher = createMockFetcher(responses);
-      manager.registerFetcher('github', fetcher);
-
-      // First call - fetches
-      await manager.getWithFallback('cached-key', 'https://github.com/test');
-
-      // Change the response
-      responses['https://github.com/test'] = 'Updated content';
-
-      // Second call - should return cached
-      const entry = await manager.getWithFallback('cached-key', 'https://github.com/test');
-      expect(entry.content).toBe('Original content');
-    });
-
-    it('should force refresh when option set', async () => {
-      const responses = { 'https://github.com/test': 'Original content' };
-      const fetcher = createMockFetcher(responses);
-      manager.registerFetcher('github', fetcher);
-
-      await manager.getWithFallback('force-key', 'https://github.com/test');
-
-      responses['https://github.com/test'] = 'Updated content';
-
-      const entry = await manager.getWithFallback('force-key', 'https://github.com/test', {
-        forceRefresh: true,
-      });
-      expect(entry.content).toBe('Updated content');
-    });
-
-    it('should throw if no fetcher registered', async () => {
-      await expect(manager.getWithFallback('key', 'https://unknown.com/test')).rejects.toThrow(
-        CacheError
-      );
-    });
-
-    it('should skip cache when option set', async () => {
-      const responses = { 'https://github.com/test': 'Content' };
-      const fetcher = createMockFetcher(responses);
-      manager.registerFetcher('github', fetcher);
-
-      // Cache something first
-      await manager.getWithFallback('skip-key', 'https://github.com/test');
-
-      responses['https://github.com/test'] = 'New content';
-
-      // Skip cache should fetch new content
-      const entry = await manager.getWithFallback('skip-key', 'https://github.com/test', {
-        skipCache: true,
-      });
-      expect(entry.content).toBe('New content');
-    });
-
-    it('should apply tags to cached entry', async () => {
-      const fetcher = createMockFetcher({
-        'https://github.com/test': 'Content',
-      });
-      manager.registerFetcher('github', fetcher);
-
-      await manager.getWithFallback('tagged-key', 'https://github.com/test', {
-        tags: ['docs', 'api'],
-      });
-
-      const metadata = await cacheProvider.getMetadata('tagged-key');
-      expect(metadata?.tags).toEqual(['docs', 'api']);
-    });
-  });
-
-  describe('getCache', () => {
-    it('should return the underlying cache provider', () => {
-      const cache = manager.getCache();
-      expect(cache).toBe(cacheProvider);
-    });
-  });
-
-  describe('hasFetcher', () => {
-    it('should return false for unregistered source', () => {
-      expect(manager.hasFetcher('unknown')).toBe(false);
-    });
-
-    it('should return true for registered source', () => {
-      manager.registerFetcher('test', createMockFetcher({}));
-      expect(manager.hasFetcher('test')).toBe(true);
-    });
-  });
-
-  describe('source detection', () => {
-    it('should detect GitHub URLs', async () => {
-      const fetcher = createMockFetcher({
-        'https://github.com/owner/repo': 'Content',
-      });
-      manager.registerFetcher('github', fetcher);
-
-      const entry = await manager.getWithFallback('github-key', 'https://github.com/owner/repo');
-      expect(entry.metadata.source).toBe('github');
-    });
-
-    it('should detect Confluence URLs', async () => {
-      const fetcher = createMockFetcher({
-        'https://mycompany.atlassian.net/wiki/page': 'Content',
-      });
-      manager.registerFetcher('confluence', fetcher);
-
-      const entry = await manager.getWithFallback(
-        'confluence-key',
-        'https://mycompany.atlassian.net/wiki/page'
-      );
-      expect(entry.metadata.source).toBe('confluence');
-    });
-
-    it('should detect Notion URLs', async () => {
-      const fetcher = createMockFetcher({
-        'https://notion.so/page': 'Content',
-      });
-      manager.registerFetcher('notion', fetcher);
-
-      const entry = await manager.getWithFallback('notion-key', 'https://notion.so/page');
-      expect(entry.metadata.source).toBe('notion');
-    });
-  });
-
-  describe('syncEntries', () => {
-    beforeEach(async () => {
-      const fetcher = createMockFetcher({
-        'https://github.com/test1': 'Content 1',
-        'https://github.com/test2': 'Content 2',
-      });
-      manager.registerFetcher('github', fetcher);
-
-      // Pre-populate cache
-      await manager.getWithFallback('key1', 'https://github.com/test1');
-      await manager.getWithFallback('key2', 'https://github.com/test2');
-    });
-
-    it('should sync specified entries', async () => {
-      const result = await manager.syncEntries(['key1', 'key2']);
-
-      expect(result.updated).toBeGreaterThanOrEqual(0);
-      expect(result.failed).toBe(0);
-      expect(result.duration).toBeGreaterThanOrEqual(0);
-    });
-
-    it('should report errors for missing entries', async () => {
-      const result = await manager.syncEntries(['missing-key'], { continueOnError: true });
-
-      expect(result.failed).toBe(1);
-      expect(result.errors[0].key).toBe('missing-key');
-    });
-  });
-});
-
-describe('createCacheManager', () => {
-  it('should create a manager instance', async () => {
-    const testDir = join(tmpdir(), `create-manager-${Date.now()}`);
-    await fs.mkdir(testDir, { recursive: true });
-
-    const cache = new FileCacheProvider({ basePath: testDir });
-    await cache.initialize();
-
-    const manager = createCacheManager({ cache });
-    expect(manager).toBeInstanceOf(CacheManager);
-
-    await fs.rm(testDir, { recursive: true, force: true });
-  });
-});