@deimoscloud/coreai 0.1.0

package/src/cache/types.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Cache Types Tests
+ */
+
+import { CacheError, CACHE_PATHS, DEFAULT_CACHE_CONFIG } from './types.js';
+import type {
+  CacheSource,
+  CacheStatus,
+  CacheMetadata,
+  CacheEntry,
+  CacheOptions,
+  CacheListOptions,
+  CacheStats,
+  SyncResult,
+} from './types.js';
+
+describe('CacheError', () => {
+  it('should create error with message and code', () => {
+    const error = new CacheError('Entry not found', 'not_found');
+    expect(error.message).toBe('Entry not found');
+    expect(error.code).toBe('not_found');
+    expect(error.name).toBe('CacheError');
+  });
+
+  it('should create error with key', () => {
+    const error = new CacheError('Entry not found', 'not_found', 'test-key');
+    expect(error.key).toBe('test-key');
+  });
+
+  it('should create error with cause', () => {
+    const cause = new Error('Original error');
+    const error = new CacheError('Wrapped error', 'read_failed', undefined, cause);
+    expect(error.cause).toBe(cause);
+  });
+
+  it('should be instanceof Error', () => {
+    const error = new CacheError('Test', 'not_found');
+    expect(error).toBeInstanceOf(Error);
+    expect(error).toBeInstanceOf(CacheError);
+  });
+});
+
+describe('CACHE_PATHS', () => {
+  it('should define root path', () => {
+    expect(CACHE_PATHS.ROOT).toBe('.coreai/cache');
+  });
+
+  it('should define content path', () => {
+    expect(CACHE_PATHS.CONTENT).toBe('.coreai/cache/content');
+  });
+
+  it('should define metadata path', () => {
+    expect(CACHE_PATHS.METADATA).toBe('.coreai/cache/metadata');
+  });
+
+  it('should define index path', () => {
+    expect(CACHE_PATHS.INDEX).toBe('.coreai/cache/index.json');
+  });
+
+  it('should define lock path', () => {
+    expect(CACHE_PATHS.LOCK).toBe('.coreai/cache/.lock');
+  });
+});
+
+describe('DEFAULT_CACHE_CONFIG', () => {
+  it('should have default TTL of 1 hour', () => {
+    expect(DEFAULT_CACHE_CONFIG.ttl).toBe(3600);
+  });
+
+  it('should have default max size of 100MB', () => {
+    expect(DEFAULT_CACHE_CONFIG.maxSize).toBe(100 * 1024 * 1024);
+  });
+
+  it('should have default max entries of 1000', () => {
+    expect(DEFAULT_CACHE_CONFIG.maxEntries).toBe(1000);
+  });
+
+  it('should enable auto cleanup by default', () => {
+    expect(DEFAULT_CACHE_CONFIG.autoCleanup).toBe(true);
+  });
+
+  it('should have cleanup interval of 1 hour', () => {
+    expect(DEFAULT_CACHE_CONFIG.cleanupInterval).toBe(3600);
+  });
+});
+
+describe('Type shapes', () => {
+  it('should accept valid CacheSource values', () => {
+    const sources: CacheSource[] = ['confluence', 'github', 'notion', 'local', 'custom'];
+    expect(sources).toHaveLength(5);
+  });
+
+  it('should accept valid CacheStatus values', () => {
+    const statuses: CacheStatus[] = ['valid', 'stale', 'expired', 'error'];
+    expect(statuses).toHaveLength(4);
+  });
+
+  it('should create valid CacheMetadata', () => {
+    const metadata: CacheMetadata = {
+      key: 'test-key',
+      source: 'confluence',
+      sourceUrl: 'https://example.com/page',
+      cachedAt: new Date().toISOString(),
+      expiresAt: new Date(Date.now() + 3600000).toISOString(),
+      contentHash: 'abc123',
+      size: 1024,
+      contentType: 'text/markdown',
+    };
+
+    expect(metadata.key).toBe('test-key');
+    expect(metadata.source).toBe('confluence');
+  });
+
+  it('should create valid CacheEntry', () => {
+    const entry: CacheEntry = {
+      metadata: {
+        key: 'test-key',
+        source: 'github',
+        sourceUrl: 'https://github.com/owner/repo',
+        cachedAt: new Date().toISOString(),
+        expiresAt: new Date(Date.now() + 3600000).toISOString(),
+        contentHash: 'def456',
+        size: 2048,
+        contentType: 'text/markdown',
+      },
+      content: '# Test Content',
+    };
+
+    expect(entry.metadata.key).toBe('test-key');
+    expect(entry.content).toBe('# Test Content');
+  });
+
+  it('should create valid CacheOptions', () => {
+    const options: CacheOptions = {
+      ttl: 7200,
+      forceRefresh: false,
+      skipCache: false,
+      tags: ['docs', 'architecture'],
+    };
+
+    expect(options.ttl).toBe(7200);
+    expect(options.tags).toHaveLength(2);
+  });
+
+  it('should create valid CacheListOptions', () => {
+    const options: CacheListOptions = {
+      source: 'confluence',
+      tag: 'docs',
+      status: 'valid',
+      limit: 10,
+    };
+
+    expect(options.source).toBe('confluence');
+    expect(options.limit).toBe(10);
+  });
+
+  it('should create valid CacheStats', () => {
+    const stats: CacheStats = {
+      totalEntries: 100,
+      totalSize: 1024 * 1024,
+      validEntries: 80,
+      staleEntries: 15,
+      expiredEntries: 5,
+      bySource: {
+        confluence: 50,
+        github: 30,
+        notion: 10,
+        local: 10,
+        custom: 0,
+      },
+      oldestEntry: new Date(Date.now() - 86400000).toISOString(),
+      newestEntry: new Date().toISOString(),
+    };
+
+    expect(stats.totalEntries).toBe(100);
+    expect(stats.bySource.confluence).toBe(50);
+  });
+
+  it('should create valid SyncResult', () => {
+    const result: SyncResult = {
+      added: 5,
+      updated: 10,
+      removed: 2,
+      failed: 1,
+      errors: [{ key: 'failed-key', error: 'Network error' }],
+      duration: 5000,
+    };
+
+    expect(result.added).toBe(5);
+    expect(result.errors).toHaveLength(1);
+  });
+});

package/src/cache/types.ts

@@ -0,0 +1,313 @@
+/**
+ * Cache Types
+ *
+ * Type definitions for the shared context cache system.
+ */
+
+/**
+ * Source type for cached content
+ */
+export type CacheSource = 'confluence' | 'github' | 'notion' | 'local' | 'custom';
+
+/**
+ * Cache entry status
+ */
+export type CacheStatus = 'valid' | 'stale' | 'expired' | 'error';
+
+/**
+ * Metadata for a cached entry
+ */
+export interface CacheMetadata {
+  /**
+   * Unique key for this cache entry
+   */
+  key: string;
+
+  /**
+   * Source provider (e.g., 'confluence', 'github')
+   */
+  source: CacheSource;
+
+  /**
+   * Original source URL or identifier
+   */
+  sourceUrl: string;
+
+  /**
+   * When the content was cached
+   */
+  cachedAt: string;
+
+  /**
+   * When the content expires (ISO date string)
+   */
+  expiresAt: string;
+
+  /**
+   * ETag or version hash from source (for conditional fetching)
+   */
+  etag?: string;
+
+  /**
+   * Content hash for integrity checking
+   */
+  contentHash: string;
+
+  /**
+   * Size in bytes
+   */
+  size: number;
+
+  /**
+   * Content type (e.g., 'text/markdown', 'application/json')
+   */
+  contentType: string;
+
+  /**
+   * Original title or name
+   */
+  title?: string;
+
+  /**
+   * Last modified timestamp from source
+   */
+  lastModified?: string;
+
+  /**
+   * Custom tags for categorization
+   */
+  tags?: string[];
+}
+
+/**
+ * A cached content entry
+ */
+export interface CacheEntry<T = string> {
+  /**
+   * Entry metadata
+   */
+  metadata: CacheMetadata;
+
+  /**
+   * The cached content
+   */
+  content: T;
+}
+
+/**
+ * Options for cache operations
+ */
+export interface CacheOptions {
+  /**
+   * Time-to-live in seconds (default: 3600 = 1 hour)
+   */
+  ttl?: number;
+
+  /**
+   * Force refresh even if cached
+   */
+  forceRefresh?: boolean;
+
+  /**
+   * Skip cache and fetch directly
+   */
+  skipCache?: boolean;
+
+  /**
+   * Custom tags to apply
+   */
+  tags?: string[];
+}
+
+/**
+ * Options for listing cache entries
+ */
+export interface CacheListOptions {
+  /**
+   * Filter by source
+   */
+  source?: CacheSource;
+
+  /**
+   * Filter by tag
+   */
+  tag?: string;
+
+  /**
+   * Filter by status
+   */
+  status?: CacheStatus;
+
+  /**
+   * Maximum entries to return
+   */
+  limit?: number;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  /**
+   * Total number of entries
+   */
+  totalEntries: number;
+
+  /**
+   * Total size in bytes
+   */
+  totalSize: number;
+
+  /**
+   * Number of valid entries
+   */
+  validEntries: number;
+
+  /**
+   * Number of stale entries
+   */
+  staleEntries: number;
+
+  /**
+   * Number of expired entries
+   */
+  expiredEntries: number;
+
+  /**
+   * Entries by source
+   */
+  bySource: Record<CacheSource, number>;
+
+  /**
+   * Oldest entry timestamp
+   */
+  oldestEntry?: string;
+
+  /**
+   * Newest entry timestamp
+   */
+  newestEntry?: string;
+}
+
+/**
+ * Result of a sync operation
+ */
+export interface SyncResult {
+  /**
+   * Number of entries added
+   */
+  added: number;
+
+  /**
+   * Number of entries updated
+   */
+  updated: number;
+
+  /**
+   * Number of entries removed
+   */
+  removed: number;
+
+  /**
+   * Number of entries that failed to sync
+   */
+  failed: number;
+
+  /**
+   * Error messages for failed entries
+   */
+  errors: { key: string; error: string }[];
+
+  /**
+   * Duration of sync in milliseconds
+   */
+  duration: number;
+}
+
+/**
+ * Cache error codes
+ */
+export type CacheErrorCode =
+  | 'not_found'
+  | 'expired'
+  | 'invalid_key'
+  | 'write_failed'
+  | 'read_failed'
+  | 'fetch_failed'
+  | 'invalid_config'
+  | 'storage_full';
+
+/**
+ * Cache-specific error
+ */
+export class CacheError extends Error {
+  constructor(
+    message: string,
+    public readonly code: CacheErrorCode,
+    public readonly key?: string,
+    public override readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'CacheError';
+  }
+}
+
+/**
+ * Default cache directory paths
+ */
+export const CACHE_PATHS = {
+  /**
+   * Root cache directory (relative to project root)
+   */
+  ROOT: '.coreai/cache',
+
+  /**
+   * Content storage directory
+   */
+  CONTENT: '.coreai/cache/content',
+
+  /**
+   * Metadata storage directory
+   */
+  METADATA: '.coreai/cache/metadata',
+
+  /**
+   * Index file for fast lookups
+   */
+  INDEX: '.coreai/cache/index.json',
+
+  /**
+   * Lock file for concurrent access
+   */
+  LOCK: '.coreai/cache/.lock',
+} as const;
+
+/**
+ * Default cache configuration
+ */
+export const DEFAULT_CACHE_CONFIG = {
+  /**
+   * Default TTL in seconds (1 hour)
+   */
+  ttl: 3600,
+
+  /**
+   * Maximum cache size in bytes (100MB)
+   */
+  maxSize: 100 * 1024 * 1024,
+
+  /**
+   * Maximum number of entries
+   */
+  maxEntries: 1000,
+
+  /**
+   * Enable automatic cleanup of expired entries
+   */
+  autoCleanup: true,
+
+  /**
+   * Cleanup interval in seconds (1 hour)
+   */
+  cleanupInterval: 3600,
+} as const;