@deimoscloud/coreai 0.1.0

package/src/context/loader.ts

@@ -0,0 +1,357 @@
+/**
+ * Context Loader
+ *
+ * Loads shared context from remote documentation providers with cache-first resolution.
+ * Handles first-run scenarios when cache is empty.
+ */
+
+import type { CacheManager, CacheOptions, FetchOptions } from '../cache/index.js';
+import type { CacheEntry, CacheMetadata } from '../cache/types.js';
+
+/**
+ * Context source definition
+ */
+export interface ContextSource {
+  /**
+   * Unique identifier for this context
+   */
+  key: string;
+
+  /**
+   * Remote URL to fetch from
+   */
+  url: string;
+
+  /**
+   * Optional title for the context
+   */
+  title?: string;
+
+  /**
+   * Optional tags for categorization
+   */
+  tags?: string[];
+
+  /**
+   * Whether this context is required (fail if cannot load)
+   */
+  required?: boolean;
+}
+
+/**
+ * Context load result
+ */
+export interface ContextLoadResult {
+  /**
+   * Successfully loaded contexts
+   */
+  loaded: {
+    key: string;
+    content: string;
+    fromCache: boolean;
+    metadata: CacheMetadata;
+  }[];
+
+  /**
+   * Failed contexts
+   */
+  failed: {
+    key: string;
+    error: string;
+    required: boolean;
+  }[];
+
+  /**
+   * Total duration in milliseconds
+   */
+  duration: number;
+}
+
+/**
+ * Options for the context loader
+ */
+export interface ContextLoaderOptions {
+  /**
+   * The cache manager to use
+   */
+  cacheManager: CacheManager;
+
+  /**
+   * Default TTL for cached contexts (seconds)
+   */
+  defaultTtl?: number;
+
+  /**
+   * Whether to fail on any required context failure
+   */
+  failOnRequired?: boolean;
+
+  /**
+   * Maximum concurrent fetches
+   */
+  concurrency?: number;
+}
+
+/**
+ * Options for loading contexts
+ */
+export interface LoadOptions extends CacheOptions, FetchOptions {
+  /**
+   * Continue loading other contexts if one fails
+   */
+  continueOnError?: boolean;
+
+  /**
+   * Progress callback
+   */
+  onProgress?: (loaded: number, total: number, current: string) => void;
+}
+
+/**
+ * Context Loader
+ *
+ * Provides cache-first context resolution with graceful degradation
+ * for first-run scenarios when the cache is empty.
+ */
+export class ContextLoader {
+  private cacheManager: CacheManager;
+  private defaultTtl: number;
+  private failOnRequired: boolean;
+  private concurrency: number;
+
+  constructor(options: ContextLoaderOptions) {
+    this.cacheManager = options.cacheManager;
+    this.defaultTtl = options.defaultTtl ?? 3600;
+    this.failOnRequired = options.failOnRequired ?? true;
+    this.concurrency = options.concurrency ?? 5;
+  }
+
+  /**
+   * Load a single context
+   */
+  async load(source: ContextSource, options?: LoadOptions): Promise<CacheEntry<string>> {
+    try {
+      const cacheOptions: CacheOptions & FetchOptions = {
+        ...options,
+        ttl: options?.ttl ?? this.defaultTtl,
+      };
+      if (source.tags) {
+        cacheOptions.tags = source.tags;
+      }
+      const entry = await this.cacheManager.getWithFallback<string>(
+        source.key,
+        source.url,
+        cacheOptions
+      );
+
+      return entry;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+
+      if (source.required && this.failOnRequired) {
+        throw new Error(`Failed to load required context "${source.key}": ${message}`);
+      }
+
+      throw error;
+    }
+  }
+
+  /**
+   * Load multiple contexts
+   */
+  async loadMany(sources: ContextSource[], options?: LoadOptions): Promise<ContextLoadResult> {
+    const startTime = Date.now();
+    const result: ContextLoadResult = {
+      loaded: [],
+      failed: [],
+      duration: 0,
+    };
+
+    // Track which entries were loaded from cache vs fetched
+    const cacheStatuses = new Map<string, boolean>();
+
+    // Check cache status for all keys first
+    for (const source of sources) {
+      const status = await this.cacheManager.getCache().getStatus(source.key);
+      cacheStatuses.set(source.key, status === 'valid');
+    }
+
+    // Process in chunks for concurrency control
+    const chunks = this.chunkArray(sources, this.concurrency);
+
+    let completed = 0;
+    for (const chunk of chunks) {
+      const promises = chunk.map(async (source) => {
+        try {
+          const itemCacheOptions: CacheOptions & FetchOptions = {
+            ...options,
+            ttl: options?.ttl ?? this.defaultTtl,
+          };
+          if (source.tags) {
+            itemCacheOptions.tags = source.tags;
+          }
+          const entry = await this.cacheManager.getWithFallback<string>(
+            source.key,
+            source.url,
+            itemCacheOptions
+          );
+
+          result.loaded.push({
+            key: source.key,
+            content: entry.content,
+            fromCache: cacheStatuses.get(source.key) ?? false,
+            metadata: entry.metadata,
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          result.failed.push({
+            key: source.key,
+            error: message,
+            required: source.required ?? false,
+          });
+
+          if (source.required && this.failOnRequired && !options?.continueOnError) {
+            throw new Error(`Failed to load required context "${source.key}": ${message}`);
+          }
+        }
+      });
+
+      await Promise.all(promises);
+
+      completed += chunk.length;
+      if (options?.onProgress) {
+        const currentKey = chunk[chunk.length - 1]?.key ?? '';
+        options.onProgress(completed, sources.length, currentKey);
+      }
+    }
+
+    result.duration = Date.now() - startTime;
+
+    // Check for required failures
+    if (this.failOnRequired && !options?.continueOnError) {
+      const requiredFailures = result.failed.filter((f) => f.required);
+      if (requiredFailures.length > 0) {
+        throw new Error(
+          `Failed to load ${requiredFailures.length} required context(s): ${requiredFailures.map((f) => f.key).join(', ')}`
+        );
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Load contexts by tag
+   */
+  async loadByTag(tag: string, _options?: LoadOptions): Promise<ContextLoadResult> {
+    const startTime = Date.now();
+    const result: ContextLoadResult = {
+      loaded: [],
+      failed: [],
+      duration: 0,
+    };
+
+    // Get all cached entries with this tag
+    const entries = await this.cacheManager.getCache().list({ tag });
+
+    for (const entry of entries) {
+      try {
+        const cached = await this.cacheManager.getCache().get<string>(entry.key);
+        if (cached) {
+          result.loaded.push({
+            key: entry.key,
+            content: cached.content,
+            fromCache: true,
+            metadata: cached.metadata,
+          });
+        }
+      } catch (error) {
+        result.failed.push({
+          key: entry.key,
+          error: error instanceof Error ? error.message : String(error),
+          required: false,
+        });
+      }
+    }
+
+    result.duration = Date.now() - startTime;
+    return result;
+  }
+
+  /**
+   * Refresh all contexts (sync from remote)
+   */
+  async refresh(sources: ContextSource[], options?: LoadOptions): Promise<ContextLoadResult> {
+    return this.loadMany(sources, {
+      ...options,
+      forceRefresh: true,
+    });
+  }
+
+  /**
+   * Check if all required contexts are available (cached or fetchable)
+   */
+  async checkAvailability(
+    sources: ContextSource[]
+  ): Promise<{ available: string[]; missing: string[]; errors: string[] }> {
+    const available: string[] = [];
+    const missing: string[] = [];
+    const errors: string[] = [];
+
+    for (const source of sources) {
+      try {
+        // Check if cached
+        const hasCached = await this.cacheManager.getCache().has(source.key);
+        if (hasCached) {
+          available.push(source.key);
+          continue;
+        }
+
+        // Check if fetcher is available
+        const url = new URL(source.url);
+        const source_type = this.getSourceFromHostname(url.hostname);
+        if (this.cacheManager.hasFetcher(source_type)) {
+          missing.push(source.key); // Can be fetched but not cached
+        } else {
+          errors.push(`${source.key}: No fetcher for ${source_type}`);
+        }
+      } catch (error) {
+        errors.push(`${source.key}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+
+    return { available, missing, errors };
+  }
+
+  /**
+   * Get the cache manager
+   */
+  getCacheManager(): CacheManager {
+    return this.cacheManager;
+  }
+
+  // Private helpers
+
+  private getSourceFromHostname(hostname: string): string {
+    const lower = hostname.toLowerCase();
+    if (lower.includes('confluence') || lower.includes('atlassian.net')) return 'confluence';
+    if (lower.includes('github.com') || lower.includes('github')) return 'github';
+    if (lower.includes('notion.so') || lower.includes('notion')) return 'notion';
+    return 'custom';
+  }
+
+  private chunkArray<T>(array: T[], size: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < array.length; i += size) {
+      chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+  }
+}
+
+/**
+ * Create a context loader
+ */
+export function createContextLoader(options: ContextLoaderOptions): ContextLoader {
+  return new ContextLoader(options);
+}

package/src/index.test.ts

@@ -0,0 +1,13 @@
+import { VERSION } from './index.js';
+
+describe('CoreAI', () => {
+  describe('VERSION', () => {
+    it('should export the correct version', () => {
+      expect(VERSION).toBe('0.1.0');
+    });
+
+    it('should be a string', () => {
+      expect(typeof VERSION).toBe('string');
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,244 @@
+/**
+ * CoreAI - A configurable, team-ready AI agent orchestration platform.
+ *
+ * This is the main library export for programmatic usage.
+ */
+
+export const VERSION = '0.1.0';
+
+// Configuration
+export {
+  loadConfig,
+  loadConfigFromFile,
+  findConfigFile,
+  configExists,
+  getConfigPath,
+  ConfigError,
+} from './config/index.js';
+
+export type {
+  CoreAIConfig,
+  ResolvedCoreAIConfig,
+  ProjectConfig,
+  TeamConfig,
+  IntegrationsConfig,
+  QualityGatesConfig,
+  TechStackConfig,
+  CacheConfig,
+  ConfigErrorCode,
+} from './config/index.js';
+
+// Agents
+export {
+  loadAgentFromFile,
+  loadAgentsFromDirectory,
+  parseAgentYaml,
+  validateAgentDefinition,
+  getRoleFromFilename,
+  AgentError,
+  resolveString,
+  resolveObject,
+  resolveAgentDefinition,
+  hasVariables,
+  extractVariables,
+  ResolutionError,
+  generateAgentMarkdown,
+  compileAgent,
+  compileAgents,
+  loadAllAgents,
+  filterAgentsByTeam,
+  getCoreAgentsDir,
+} from './agents/index.js';
+
+export type {
+  AgentDefinition,
+  ResolvedAgentDefinition,
+  AgentType,
+  WorkflowType,
+  AgentMetadata,
+  AgentSource,
+  AgentErrorCode,
+  ResolutionContext,
+  ResolutionOptions,
+  CompileOptions,
+  CompileResult,
+} from './agents/index.js';
+
+// Adapters
+export {
+  AdapterFactory,
+  createAdapterFactory,
+  createAdapterInfo,
+  AdapterError,
+} from './adapters/index.js';
+
+export type {
+  AdapterType,
+  AdapterImplementation,
+  AdapterInfo,
+  AdapterFactoryOptions,
+  AdapterErrorCode,
+  BaseAdapter,
+  IssueTrackerAdapter,
+  GitProviderAdapter,
+  DocumentationProviderAdapter,
+  StateProviderAdapter,
+  Adapter,
+  Issue,
+  IssueQuery,
+  IssueStatus,
+  CreateIssueData,
+  UpdateIssueData,
+  PullRequest,
+  PullRequestQuery,
+  PullRequestStatus,
+  CreatePullRequestData,
+  Review,
+  CreateReviewData,
+  ReviewDecision,
+  ReviewComment,
+  DocumentationPage,
+  DocumentationQuery,
+  StateEntry,
+  StateOptions,
+} from './adapters/index.js';
+
+// Cache
+export {
+  CacheError,
+  CACHE_PATHS,
+  DEFAULT_CACHE_CONFIG,
+  FileCacheProvider,
+  createFileCacheProvider,
+  FileCacheManager,
+  createCacheManager,
+} from './cache/index.js';
+
+export type {
+  CacheSource,
+  CacheStatus,
+  CacheMetadata,
+  CacheEntry,
+  CacheOptions,
+  CacheListOptions,
+  CacheStats,
+  SyncResult,
+  CacheErrorCode,
+  CacheProvider,
+  RemoteFetcher,
+  FetchOptions,
+  CacheManager,
+  SyncOptions,
+  FileCacheProviderOptions,
+  CacheManagerOptions,
+} from './cache/index.js';
+
+// Context
+export { ContextLoader, createContextLoader } from './context/index.js';
+
+export type {
+  ContextSource,
+  ContextLoadResult,
+  ContextLoaderOptions,
+  LoadOptions,
+} from './context/index.js';
+
+// Commands
+export {
+  CommandRegistry,
+  createCommandRegistry,
+  getGlobalRegistry,
+  resetGlobalRegistry,
+  createCommandContext,
+  cleanupContext,
+  withContext,
+  loadCommandFromFile,
+  loadCommandsFromDirectory,
+  loadCoreAICommands,
+  loadAllCommands,
+  runCommand,
+  executeWithDegradation,
+  createDegradingHandler,
+  StepTracker,
+} from './commands/index.js';
+
+export type {
+  CommandCategory,
+  IntegrationDependency,
+  CommandMetadata,
+  CommandContext,
+  BaseCommandOptions,
+  CommandResult,
+  CommandHandler,
+  CommandDefinition,
+  CommandOptionDefinition,
+  CommandArgumentDefinition,
+  MarkdownCommand,
+  RegistryEntry,
+  CommandLoaderOptions,
+  CommandLoadResult,
+  CreateContextOptions,
+  RunCommandOptions,
+} from './commands/index.js';
+
+// Skills
+export {
+  extractVariables as extractSkillVariables,
+  substituteVariables,
+  checkDependencies,
+  loadCustomTemplates,
+  generateSkills,
+  formatGenerateResult,
+  builtInSkills,
+} from './skills/index.js';
+
+export type {
+  SkillTemplate,
+  SkillVariables,
+  SkillCategory,
+  SkillDependency,
+  GenerateSkillsOptions,
+  GenerateSkillsResult,
+  GeneratedSkill,
+  SkillError,
+} from './skills/index.js';
+
+// KnowledgeLibrary
+export {
+  DEFAULT_KNOWLEDGE_LIBRARY_PATH,
+  STANDARD_FILES,
+  AGENT_DIRECTORIES,
+  CONTROL_FILES,
+  getAgentDirectories,
+  initKnowledgeLibrary,
+  initAgentKnowledgeLibrary,
+  agentKnowledgeLibraryExists,
+  getAgentKnowledgeState,
+  generateMessageFilename,
+  readInboxMessages,
+  writeInboxMessage,
+  markMessageProcessed,
+  getKnowledgeLibraryState,
+  updateAgentContext,
+  formatKnowledgeLibraryState,
+  formatAgentKnowledgeState,
+} from './knowledge-library/index.js';
+
+export type {
+  MessageType,
+  MessagePriority,
+  MessageMetadata,
+  Message,
+  AgentContext,
+  Objective,
+  Decision,
+  Dependency,
+  AgentControl,
+  AgentDirectories,
+  AgentKnowledgeState,
+  InitKnowledgeLibraryOptions,
+  InitKnowledgeLibraryResult,
+  ReadMessagesOptions,
+  WriteMessageOptions,
+  KnowledgeLibraryState,
+} from './knowledge-library/index.js';

package/src/knowledge-library/index.ts

@@ -0,0 +1,44 @@
+/**
+ * KnowledgeLibrary Module
+ *
+ * Local agent state management with inbox/outbox directories.
+ */
+
+export {
+  DEFAULT_KNOWLEDGE_LIBRARY_PATH,
+  STANDARD_FILES,
+  AGENT_DIRECTORIES,
+  CONTROL_FILES,
+  getAgentDirectories,
+  initKnowledgeLibrary,
+  initAgentKnowledgeLibrary,
+  agentKnowledgeLibraryExists,
+  getAgentKnowledgeState,
+  generateMessageFilename,
+  readInboxMessages,
+  writeInboxMessage,
+  markMessageProcessed,
+  getKnowledgeLibraryState,
+  updateAgentContext,
+  formatKnowledgeLibraryState,
+  formatAgentKnowledgeState,
+} from './manager.js';
+
+export type {
+  MessageType,
+  MessagePriority,
+  MessageMetadata,
+  Message,
+  AgentContext,
+  Objective,
+  Decision,
+  Dependency,
+  AgentControl,
+  AgentDirectories,
+  AgentKnowledgeState,
+  InitKnowledgeLibraryOptions,
+  InitKnowledgeLibraryResult,
+  ReadMessagesOptions,
+  WriteMessageOptions,
+  KnowledgeLibraryState,
+} from './types.js';