@deimoscloud/coreai 0.1.0

package/src/config/loader.ts

@@ -0,0 +1,188 @@
+/**
+ * Configuration Loader
+ *
+ * Handles config file discovery, parsing, validation, and defaults.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import Ajv, { type ErrorObject } from 'ajv';
+import addFormats from 'ajv-formats';
+import type { CoreAIConfig, ResolvedCoreAIConfig } from './types.js';
+
+// Import schema as JSON
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const configSchema = require('../../schemas/coreai.config.schema.json') as object;
+
+const CONFIG_FILE_NAME = 'coreai.config.yaml';
+const CONFIG_FILE_NAMES = [CONFIG_FILE_NAME, 'coreai.config.yml'];
+
+export class ConfigError extends Error {
+  constructor(
+    message: string,
+    public readonly code: ConfigErrorCode,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+export type ConfigErrorCode = 'NOT_FOUND' | 'PARSE_ERROR' | 'VALIDATION_ERROR' | 'READ_ERROR';
+
+/**
+ * Default team agents
+ */
+const DEFAULT_AGENTS = [
+  'backend-engineer',
+  'frontend-engineer',
+  'devops-engineer',
+  'engineering-manager',
+];
+
+/**
+ * Find the config file by walking up the directory tree
+ */
+export function findConfigFile(startDir: string = process.cwd()): string | null {
+  let currentDir = resolve(startDir);
+  const root = dirname(currentDir);
+
+  while (currentDir !== root) {
+    for (const fileName of CONFIG_FILE_NAMES) {
+      const configPath = join(currentDir, fileName);
+      if (existsSync(configPath)) {
+        return configPath;
+      }
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  // Check root directory
+  for (const fileName of CONFIG_FILE_NAMES) {
+    const configPath = join(currentDir, fileName);
+    if (existsSync(configPath)) {
+      return configPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse YAML content into an object
+ */
+export function parseConfig(content: string, filePath?: string): unknown {
+  try {
+    return parseYaml(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown parse error';
+    throw new ConfigError(
+      `Failed to parse YAML${filePath ? ` in ${filePath}` : ''}: ${message}`,
+      'PARSE_ERROR',
+      error
+    );
+  }
+}
+
+/**
+ * Validate config against JSON schema
+ */
+export function validateConfig(config: unknown): CoreAIConfig {
+  const ajv = new Ajv.default({ allErrors: true, strict: false });
+  addFormats.default(ajv);
+
+  const validate = ajv.compile<CoreAIConfig>(configSchema);
+  const valid = validate(config);
+
+  if (!valid) {
+    const errors: ErrorObject[] = validate.errors ?? [];
+    const errorMessages = errors.map((err: ErrorObject) => {
+      const path = err.instancePath || 'root';
+      return `${path}: ${err.message ?? 'unknown error'}`;
+    });
+
+    throw new ConfigError(
+      `Configuration validation failed:\n  - ${errorMessages.join('\n  - ')}`,
+      'VALIDATION_ERROR',
+      errors
+    );
+  }
+
+  return config as CoreAIConfig;
+}
+
+/**
+ * Apply default values to config
+ */
+export function applyDefaults(config: CoreAIConfig): ResolvedCoreAIConfig {
+  return {
+    ...config,
+    project: {
+      name: config.project?.name ?? 'unnamed',
+      type: config.project?.type ?? 'software',
+      root: config.project?.root ?? process.cwd(),
+    },
+    team: {
+      agents: config.team?.agents ?? DEFAULT_AGENTS,
+    },
+  };
+}
+
+/**
+ * Load and validate configuration from a file path
+ */
+export function loadConfigFromFile(filePath: string): ResolvedCoreAIConfig {
+  let content: string;
+
+  try {
+    content = readFileSync(filePath, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown read error';
+    throw new ConfigError(
+      `Failed to read config file ${filePath}: ${message}`,
+      'READ_ERROR',
+      error
+    );
+  }
+
+  const parsed = parseConfig(content, filePath);
+  const validated = validateConfig(parsed);
+  return applyDefaults(validated);
+}
+
+/**
+ * Load configuration by searching for config file
+ */
+export function loadConfig(startDir?: string): ResolvedCoreAIConfig {
+  const configPath = findConfigFile(startDir);
+
+  if (!configPath) {
+    throw new ConfigError(
+      `Configuration file not found. Create a ${CONFIG_FILE_NAME} file or run 'coreai init'.`,
+      'NOT_FOUND'
+    );
+  }
+
+  return loadConfigFromFile(configPath);
+}
+
+/**
+ * Check if a config file exists in the given directory or parent directories
+ */
+export function configExists(startDir?: string): boolean {
+  return findConfigFile(startDir) !== null;
+}
+
+/**
+ * Get the path to the config file, or null if not found
+ */
+export function getConfigPath(startDir?: string): string | null {
+  return findConfigFile(startDir);
+}

package/src/config/types.ts

@@ -0,0 +1,154 @@
+/**
+ * CoreAI Configuration Types
+ *
+ * TypeScript types corresponding to the JSON schema at schemas/coreai.config.schema.json
+ */
+
+export type ProjectType = 'software' | 'infrastructure' | 'data' | 'mobile';
+
+export type IssueTrackerProvider = 'jira' | 'linear' | 'github-issues' | 'azure-devops';
+export type GitProvider = 'github' | 'gitlab' | 'bitbucket' | 'azure-devops';
+export type DocumentationProvider = 'confluence' | 'notion' | 'github-wiki' | 'local';
+export type StateProvider = 'confluence' | 'notion' | 's3' | 'github-repo' | 'local';
+
+export type AdapterStrategy = 'mcp' | 'native' | 'auto';
+
+export interface ProjectConfig {
+  name: string;
+  type?: ProjectType;
+  root?: string;
+}
+
+export interface TeamConfig {
+  agents?: string[];
+}
+
+export interface IssueTrackerConfig {
+  project_key?: string;
+  base_url?: string;
+  [key: string]: unknown;
+}
+
+export interface IssueTrackerIntegration {
+  provider: IssueTrackerProvider;
+  config?: IssueTrackerConfig;
+  strategy?: AdapterStrategy;
+}
+
+export interface GitConfig {
+  owner?: string;
+  repo?: string;
+  default_branch?: string;
+  [key: string]: unknown;
+}
+
+export interface GitIntegration {
+  provider: GitProvider;
+  config?: GitConfig;
+  strategy?: AdapterStrategy;
+}
+
+export interface DocumentationConfig {
+  space_key?: string;
+  base_url?: string;
+  base_path?: string;
+  [key: string]: unknown;
+}
+
+export interface DocumentationIntegration {
+  provider: DocumentationProvider;
+  config?: DocumentationConfig;
+  strategy?: AdapterStrategy;
+}
+
+export interface StateConfig {
+  space_key?: string;
+  base_path?: string;
+  bucket?: string;
+  [key: string]: unknown;
+}
+
+export interface StateIntegration {
+  provider: StateProvider;
+  config?: StateConfig;
+  strategy?: AdapterStrategy;
+}
+
+export interface IntegrationsConfig {
+  issue_tracker?: IssueTrackerIntegration;
+  git?: GitIntegration;
+  documentation?: DocumentationIntegration;
+  state?: StateIntegration;
+}
+
+export interface QualityGate {
+  command: string;
+  required?: boolean;
+}
+
+export type QualityGatesConfig = Record<string, QualityGate>;
+
+export interface TechStackConfig {
+  primary_language?: string;
+  frameworks?: string[];
+  cloud?: string;
+  [key: string]: unknown;
+}
+
+export interface McpConfig {
+  expose_adapters?: boolean;
+}
+
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+  /**
+   * Enable caching (default: true)
+   */
+  enabled?: boolean;
+
+  /**
+   * Cache directory path (default: .coreai/cache)
+   */
+  path?: string;
+
+  /**
+   * Default TTL in seconds (default: 3600)
+   */
+  ttl?: number;
+
+  /**
+   * Maximum cache size in bytes (default: 100MB)
+   */
+  max_size?: number;
+
+  /**
+   * Maximum number of entries (default: 1000)
+   */
+  max_entries?: number;
+
+  /**
+   * Enable automatic cleanup of expired entries (default: true)
+   */
+  auto_cleanup?: boolean;
+}
+
+export interface CoreAIConfig {
+  version?: '1.0';
+  project?: ProjectConfig;
+  team?: TeamConfig;
+  integrations?: IntegrationsConfig;
+  quality_gates?: QualityGatesConfig;
+  tech_stack?: TechStackConfig;
+  mcp?: McpConfig;
+  cache?: CacheConfig;
+}
+
+/**
+ * Configuration with all defaults applied
+ */
+export interface ResolvedCoreAIConfig extends CoreAIConfig {
+  project: Required<ProjectConfig>;
+  team: Required<TeamConfig>;
+}

package/src/context/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Context Module
+ *
+ * Provides context loading and resolution from remote documentation providers.
+ */
+
+export type {
+  ContextSource,
+  ContextLoadResult,
+  ContextLoaderOptions,
+  LoadOptions,
+} from './loader.js';
+
+export { ContextLoader, createContextLoader } from './loader.js';

package/src/context/loader.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Context Loader Tests
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { ContextLoader, createContextLoader } from './loader.js';
+import { FileCacheProvider } from '../cache/provider.js';
+import { CacheManager } from '../cache/manager.js';
+import type { RemoteFetcher, ContextSource } from '../index.js';
+
+describe('ContextLoader', () => {
+  let testDir: string;
+  let cacheProvider: FileCacheProvider;
+  let cacheManager: CacheManager;
+  let loader: ContextLoader;
+
+  // 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/markdown',
+          title: `Doc: ${url}`,
+        },
+      };
+    },
+    async hasChanged() {
+      return true;
+    },
+  });
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `context-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await fs.mkdir(testDir, { recursive: true });
+
+    cacheProvider = new FileCacheProvider({ basePath: testDir });
+    await cacheProvider.initialize();
+
+    cacheManager = new CacheManager({ cache: cacheProvider });
+
+    loader = new ContextLoader({
+      cacheManager,
+      defaultTtl: 3600,
+    });
+  });
+
+  afterEach(async () => {
+    try {
+      await fs.rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('constructor', () => {
+    it('should create loader with options', () => {
+      expect(loader).toBeInstanceOf(ContextLoader);
+    });
+  });
+
+  describe('load', () => {
+    it('should load a single context', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs/readme': '# README\nProject documentation',
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      const source: ContextSource = {
+        key: 'readme',
+        url: 'https://github.com/docs/readme',
+        title: 'README',
+      };
+
+      const entry = await loader.load(source);
+
+      expect(entry.content).toBe('# README\nProject documentation');
+      expect(entry.metadata.key).toBe('readme');
+    });
+
+    it('should throw for required context if fetch fails', async () => {
+      const fetcher = createMockFetcher({}); // No responses
+      cacheManager.registerFetcher('github', fetcher);
+
+      const source: ContextSource = {
+        key: 'missing',
+        url: 'https://github.com/missing',
+        required: true,
+      };
+
+      await expect(loader.load(source)).rejects.toThrow(/Failed to load required context/);
+    });
+
+    it('should apply tags from source', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs': 'Content',
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      const source: ContextSource = {
+        key: 'tagged',
+        url: 'https://github.com/docs',
+        tags: ['docs', 'architecture'],
+      };
+
+      await loader.load(source);
+
+      const metadata = await cacheProvider.getMetadata('tagged');
+      expect(metadata?.tags).toEqual(['docs', 'architecture']);
+    });
+  });
+
+  describe('loadMany', () => {
+    it('should load multiple contexts', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs/1': 'Content 1',
+        'https://github.com/docs/2': 'Content 2',
+        'https://github.com/docs/3': 'Content 3',
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      const sources: ContextSource[] = [
+        { key: 'doc1', url: 'https://github.com/docs/1' },
+        { key: 'doc2', url: 'https://github.com/docs/2' },
+        { key: 'doc3', url: 'https://github.com/docs/3' },
+      ];
+
+      const result = await loader.loadMany(sources);
+
+      expect(result.loaded).toHaveLength(3);
+      expect(result.failed).toHaveLength(0);
+      expect(result.duration).toBeGreaterThan(0);
+    });
+
+    it('should report failures with continueOnError', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs/1': 'Content 1',
+        // doc2 missing
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      const sources: ContextSource[] = [
+        { key: 'doc1', url: 'https://github.com/docs/1' },
+        { key: 'doc2', url: 'https://github.com/docs/2' },
+      ];
+
+      const result = await loader.loadMany(sources, { continueOnError: true });
+
+      expect(result.loaded).toHaveLength(1);
+      expect(result.failed).toHaveLength(1);
+      expect(result.failed[0].key).toBe('doc2');
+    });
+
+    it('should fail on required context by default', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs/1': 'Content',
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      const sources: ContextSource[] = [
+        { key: 'doc1', url: 'https://github.com/docs/1' },
+        { key: 'required-missing', url: 'https://github.com/missing', required: true },
+      ];
+
+      await expect(loader.loadMany(sources)).rejects.toThrow(/Failed to load required context/);
+    });
+
+    it('should track fromCache status', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs/cached': 'Cached content',
+        'https://github.com/docs/fresh': 'Fresh content',
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      // Pre-cache one entry
+      await cacheProvider.set('cached-doc', 'Pre-cached content', {
+        source: 'github',
+        sourceUrl: 'https://github.com/docs/cached',
+      });
+
+      const sources: ContextSource[] = [
+        { key: 'cached-doc', url: 'https://github.com/docs/cached' },
+        { key: 'fresh-doc', url: 'https://github.com/docs/fresh' },
+      ];
+
+      const result = await loader.loadMany(sources);
+
+      const cachedEntry = result.loaded.find((l) => l.key === 'cached-doc');
+      const freshEntry = result.loaded.find((l) => l.key === 'fresh-doc');
+
+      expect(cachedEntry?.fromCache).toBe(true);
+      expect(freshEntry?.fromCache).toBe(false);
+    });
+
+    it('should call progress callback', async () => {
+      const fetcher = createMockFetcher({
+        'https://github.com/docs/1': 'Content 1',
+        'https://github.com/docs/2': 'Content 2',
+      });
+      cacheManager.registerFetcher('github', fetcher);
+
+      const progressCalls: { loaded: number; total: number; current: string }[] = [];
+
+      const sources: ContextSource[] = [
+        { key: 'doc1', url: 'https://github.com/docs/1' },
+        { key: 'doc2', url: 'https://github.com/docs/2' },
+      ];
+
+      await loader.loadMany(sources, {
+        onProgress: (loaded, total, current) => {
+          progressCalls.push({ loaded, total, current });
+        },
+      });
+
+      expect(progressCalls.length).toBeGreaterThan(0);
+      expect(progressCalls[progressCalls.length - 1].loaded).toBe(2);
+    });
+  });
+
+  describe('refresh', () => {
+    it('should force refresh all contexts', async () => {
+      const responses = {
+        'https://github.com/docs/1': 'Original',
+      };
+      const fetcher = createMockFetcher(responses);
+      cacheManager.registerFetcher('github', fetcher);
+
+      const sources: ContextSource[] = [{ key: 'doc1', url: 'https://github.com/docs/1' }];
+
+      // Initial load
+      await loader.loadMany(sources);
+
+      // Change content
+      responses['https://github.com/docs/1'] = 'Updated';
+
+      // Refresh
+      const result = await loader.refresh(sources);
+
+      expect(result.loaded).toHaveLength(1);
+      expect(result.loaded[0].content).toBe('Updated');
+    });
+  });
+
+  describe('loadByTag', () => {
+    it('should load all contexts with a specific tag', async () => {
+      // Pre-cache entries with tags
+      await cacheProvider.set(
+        'doc1',
+        'Content 1',
+        { source: 'github', sourceUrl: '' },
+        { tags: ['architecture'] }
+      );
+      await cacheProvider.set(
+        'doc2',
+        'Content 2',
+        { source: 'github', sourceUrl: '' },
+        { tags: ['architecture', 'design'] }
+      );
+      await cacheProvider.set(
+        'doc3',
+        'Content 3',
+        { source: 'github', sourceUrl: '' },
+        { tags: ['other'] }
+      );
+
+      const result = await loader.loadByTag('architecture');
+
+      expect(result.loaded).toHaveLength(2);
+      expect(result.loaded.map((l) => l.key).sort()).toEqual(['doc1', 'doc2']);
+    });
+  });
+
+  describe('checkAvailability', () => {
+    it('should report available cached contexts', async () => {
+      cacheManager.registerFetcher('github', createMockFetcher({}));
+
+      // Pre-cache an entry
+      await cacheProvider.set('cached', 'Content', {
+        source: 'github',
+        sourceUrl: 'https://github.com/test',
+      });
+
+      const sources: ContextSource[] = [
+        { key: 'cached', url: 'https://github.com/test' },
+        { key: 'missing', url: 'https://github.com/missing' },
+      ];
+
+      const { available, missing } = await loader.checkAvailability(sources);
+
+      expect(available).toContain('cached');
+      expect(missing).toContain('missing');
+    });
+
+    it('should report errors for sources without fetchers', async () => {
+      const sources: ContextSource[] = [
+        { key: 'no-fetcher', url: 'https://unknown-source.com/doc' },
+      ];
+
+      const { errors } = await loader.checkAvailability(sources);
+
+      expect(errors.length).toBe(1);
+      expect(errors[0]).toContain('No fetcher');
+    });
+  });
+
+  describe('getCacheManager', () => {
+    it('should return the cache manager', () => {
+      expect(loader.getCacheManager()).toBe(cacheManager);
+    });
+  });
+});
+
+describe('createContextLoader', () => {
+  it('should create a loader instance', async () => {
+    const testDir = join(tmpdir(), `create-loader-${Date.now()}`);
+    await fs.mkdir(testDir, { recursive: true });
+
+    const cache = new FileCacheProvider({ basePath: testDir });
+    await cache.initialize();
+
+    const manager = new CacheManager({ cache });
+    const loader = createContextLoader({ cacheManager: manager });
+
+    expect(loader).toBeInstanceOf(ContextLoader);
+
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+});