@deimoscloud/coreai 0.1.0

package/src/agents/types.ts

@@ -0,0 +1,87 @@
+/**
+ * CoreAI Agent Types
+ *
+ * TypeScript types corresponding to the JSON schema at schemas/agent.schema.json
+ */
+
+export type AgentType = 'ic-engineer' | 'manager' | 'specialist' | 'coordinator';
+
+export type WorkflowType =
+  | 'ticket-implementation'
+  | 'bug-investigation'
+  | 'code-review'
+  | 'planning-estimation';
+
+export interface AgentExpertise {
+  primary?: string[];
+  tech_stack?: string;
+  [key: string]: unknown;
+}
+
+export interface AgentPrinciples {
+  code_quality?: string[];
+  testing?: string[];
+  security?: string[];
+  performance?: string[];
+  [key: string]: string[] | undefined;
+}
+
+export interface AgentBehaviors {
+  workflow?: WorkflowType;
+  quality_gates?: string;
+  [key: string]: unknown;
+}
+
+export interface AgentContextSources {
+  shared?: string[];
+  personal?: string[];
+}
+
+export interface AgentCommunication {
+  inbox?: string;
+  outbox?: string;
+}
+
+/**
+ * Raw agent definition as loaded from YAML (before variable resolution)
+ */
+export interface AgentDefinition {
+  role: string;
+  type: AgentType;
+  display_name: string;
+  description: string;
+  responsibilities?: string[];
+  expertise?: AgentExpertise;
+  skills?: string[];
+  principles?: AgentPrinciples;
+  behaviors?: AgentBehaviors;
+  context_sources?: AgentContextSources;
+  communication?: AgentCommunication;
+}
+
+/**
+ * Agent definition after variable resolution
+ */
+export interface ResolvedAgentDefinition extends AgentDefinition {
+  // After resolution, these fields may have expanded values
+  expertise?: AgentExpertise & {
+    tech_stack?: Record<string, unknown>;
+  };
+  behaviors?: AgentBehaviors & {
+    quality_gates?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Agent source location
+ */
+export type AgentSource = 'core' | 'custom' | 'override';
+
+/**
+ * Agent metadata including source information
+ */
+export interface AgentMetadata {
+  definition: AgentDefinition;
+  source: AgentSource;
+  filePath: string;
+}

package/src/cache/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Cache Module
+ *
+ * Provides the shared context cache system for storing and retrieving
+ * content from remote documentation providers.
+ */
+
+// Types
+export type {
+  CacheSource,
+  CacheStatus,
+  CacheMetadata,
+  CacheEntry,
+  CacheOptions,
+  CacheListOptions,
+  CacheStats,
+  SyncResult,
+  CacheErrorCode,
+} from './types.js';
+
+export { CacheError, CACHE_PATHS, DEFAULT_CACHE_CONFIG } from './types.js';
+
+// Interfaces
+export type {
+  CacheProvider,
+  RemoteFetcher,
+  FetchOptions,
+  CacheManager,
+  SyncOptions,
+} from './interfaces.js';
+
+// Provider
+export type { FileCacheProviderOptions } from './provider.js';
+export { FileCacheProvider, createFileCacheProvider } from './provider.js';
+
+// Manager
+export type { CacheManagerOptions } from './manager.js';
+export { CacheManager as FileCacheManager, createCacheManager } from './manager.js';

package/src/cache/interfaces.ts

@@ -0,0 +1,283 @@
+/**
+ * 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

@@ -0,0 +1,266 @@
+/**
+ * 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 });
+  });
+});