@deimoscloud/coreai 0.1.0

package/src/agents/compiler.ts

@@ -0,0 +1,359 @@
+/**
+ * Agent Compiler
+ *
+ * Transforms YAML agent definitions into Claude-compatible Markdown files.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import type { CoreAIConfig } from '../config/types.js';
+import type { AgentDefinition, AgentMetadata, AgentSource } from './types.js';
+import { loadAgentsFromDirectory } from './loader.js';
+import { resolveAgentDefinition } from './resolver.js';
+
+/**
+ * Options for compiling agents
+ */
+export interface CompileOptions {
+  /**
+   * Output directory for compiled markdown files.
+   * Default: .claude/agents
+   */
+  outputDir?: string;
+
+  /**
+   * Core agents directory (built-in agents).
+   * Default: uses package's agents/ directory
+   */
+  coreAgentsDir?: string;
+
+  /**
+   * Custom agents directory (project-specific agents).
+   * Default: coreai/agents in project root
+   */
+  customAgentsDir?: string;
+
+  /**
+   * Project root directory.
+   * Default: process.cwd()
+   */
+  projectRoot?: string;
+
+  /**
+   * Filter function to select which agents to compile.
+   * Returns true to include the agent, false to exclude.
+   */
+  filter?: (agent: AgentDefinition) => boolean;
+}
+
+/**
+ * Result of compiling agents
+ */
+export interface CompileResult {
+  /**
+   * Successfully compiled agents
+   */
+  compiled: {
+    role: string;
+    source: AgentSource;
+    outputPath: string;
+  }[];
+
+  /**
+   * Agents that failed to compile
+   */
+  errors: {
+    role: string;
+    source: AgentSource;
+    error: string;
+  }[];
+}
+
+/**
+ * Generate markdown content from a resolved agent definition
+ */
+export function generateAgentMarkdown(agent: AgentDefinition): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`# ${agent.display_name}`);
+  lines.push('');
+  lines.push(`**Role:** ${agent.role}`);
+  lines.push(`**Type:** ${agent.type}`);
+  lines.push('');
+
+  // Description
+  lines.push('## Description');
+  lines.push('');
+  lines.push(agent.description.trim());
+  lines.push('');
+
+  // Responsibilities
+  if (agent.responsibilities && agent.responsibilities.length > 0) {
+    lines.push('## Responsibilities');
+    lines.push('');
+    for (const responsibility of agent.responsibilities) {
+      lines.push(`- ${responsibility}`);
+    }
+    lines.push('');
+  }
+
+  // Expertise
+  if (agent.expertise) {
+    lines.push('## Expertise');
+    lines.push('');
+
+    if (agent.expertise.primary && agent.expertise.primary.length > 0) {
+      lines.push('### Primary Areas');
+      lines.push('');
+      for (const area of agent.expertise.primary) {
+        lines.push(`- ${area}`);
+      }
+      lines.push('');
+    }
+
+    if (agent.expertise.tech_stack) {
+      lines.push('### Tech Stack');
+      lines.push('');
+      const techStack = agent.expertise.tech_stack;
+      if (typeof techStack === 'string') {
+        lines.push(techStack);
+      } else if (typeof techStack === 'object') {
+        lines.push('```json');
+        lines.push(JSON.stringify(techStack, null, 2));
+        lines.push('```');
+      }
+      lines.push('');
+    }
+  }
+
+  // Skills
+  if (agent.skills && agent.skills.length > 0) {
+    lines.push('## Skills');
+    lines.push('');
+    for (const skill of agent.skills) {
+      lines.push(`- ${skill}`);
+    }
+    lines.push('');
+  }
+
+  // Principles
+  if (agent.principles) {
+    lines.push('## Principles');
+    lines.push('');
+
+    for (const [category, items] of Object.entries(agent.principles)) {
+      if (items && Array.isArray(items) && items.length > 0) {
+        const title = formatTitle(category);
+        lines.push(`### ${title}`);
+        lines.push('');
+        for (const item of items) {
+          lines.push(`- ${item}`);
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  // Behaviors
+  if (agent.behaviors) {
+    lines.push('## Behaviors');
+    lines.push('');
+
+    if (agent.behaviors.workflow) {
+      lines.push(`**Workflow:** ${agent.behaviors.workflow}`);
+      lines.push('');
+    }
+
+    if (agent.behaviors.quality_gates) {
+      lines.push('### Quality Gates');
+      lines.push('');
+      const gates = agent.behaviors.quality_gates;
+      if (typeof gates === 'string') {
+        lines.push(gates);
+      } else if (typeof gates === 'object') {
+        lines.push('```json');
+        lines.push(JSON.stringify(gates, null, 2));
+        lines.push('```');
+      }
+      lines.push('');
+    }
+  }
+
+  // Context Sources
+  if (agent.context_sources) {
+    lines.push('## Context Sources');
+    lines.push('');
+
+    if (agent.context_sources.shared && agent.context_sources.shared.length > 0) {
+      lines.push('### Shared');
+      lines.push('');
+      for (const source of agent.context_sources.shared) {
+        lines.push(`- ${source}`);
+      }
+      lines.push('');
+    }
+
+    if (agent.context_sources.personal && agent.context_sources.personal.length > 0) {
+      lines.push('### Personal');
+      lines.push('');
+      for (const source of agent.context_sources.personal) {
+        lines.push(`- ${source}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Communication
+  if (agent.communication) {
+    lines.push('## Communication');
+    lines.push('');
+    if (agent.communication.inbox) {
+      lines.push(`**Inbox:** ${agent.communication.inbox}`);
+    }
+    if (agent.communication.outbox) {
+      lines.push(`**Outbox:** ${agent.communication.outbox}`);
+    }
+    lines.push('');
+  }
+
+  // Footer
+  lines.push('---');
+  lines.push('');
+  lines.push('*Generated by CoreAI*');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Format a snake_case or kebab-case string as a title
+ */
+function formatTitle(str: string): string {
+  return str.replace(/[_-]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Compile a single agent to markdown
+ */
+export function compileAgent(agent: AgentDefinition, config?: CoreAIConfig): string {
+  const resolved = resolveAgentDefinition(agent, config);
+  return generateAgentMarkdown(resolved);
+}
+
+/**
+ * Load all agents from core and custom directories
+ */
+export function loadAllAgents(options: CompileOptions = {}): Map<string, AgentMetadata> {
+  const agents = new Map<string, AgentMetadata>();
+
+  // Load core agents
+  if (options.coreAgentsDir && existsSync(options.coreAgentsDir)) {
+    const coreAgents = loadAgentsFromDirectory(options.coreAgentsDir, 'core');
+    for (const [role, metadata] of coreAgents) {
+      agents.set(role, metadata);
+    }
+  }
+
+  // Load custom agents (can override core agents)
+  if (options.customAgentsDir && existsSync(options.customAgentsDir)) {
+    const customAgents = loadAgentsFromDirectory(options.customAgentsDir, 'custom');
+    for (const [role, metadata] of customAgents) {
+      // Check if this is overriding a core agent
+      if (agents.has(role)) {
+        metadata.source = 'override';
+      }
+      agents.set(role, metadata);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Filter agents based on team configuration
+ */
+export function filterAgentsByTeam(
+  agents: Map<string, AgentMetadata>,
+  config?: CoreAIConfig
+): Map<string, AgentMetadata> {
+  if (!config?.team?.agents || config.team.agents.length === 0) {
+    // No team filter, return all agents
+    return agents;
+  }
+
+  const filtered = new Map<string, AgentMetadata>();
+  for (const role of config.team.agents) {
+    const metadata = agents.get(role);
+    if (metadata) {
+      filtered.set(role, metadata);
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Compile all agents and write to output directory
+ */
+export function compileAgents(config?: CoreAIConfig, options: CompileOptions = {}): CompileResult {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const outputDir = options.outputDir ?? join(projectRoot, '.claude', 'agents');
+  const customAgentsDir = options.customAgentsDir ?? join(projectRoot, 'coreai', 'agents');
+
+  const result: CompileResult = {
+    compiled: [],
+    errors: [],
+  };
+
+  // Load all agents
+  const allAgents = loadAllAgents({
+    ...options,
+    customAgentsDir,
+  });
+
+  // Filter by team if configured
+  const agents = filterAgentsByTeam(allAgents, config);
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Compile each agent
+  for (const [role, metadata] of agents) {
+    // Apply custom filter if provided
+    if (options.filter && !options.filter(metadata.definition)) {
+      continue;
+    }
+
+    try {
+      const markdown = compileAgent(metadata.definition, config);
+      const outputPath = join(outputDir, `${role}.md`);
+
+      writeFileSync(outputPath, markdown, 'utf-8');
+
+      result.compiled.push({
+        role,
+        source: metadata.source,
+        outputPath,
+      });
+    } catch (error) {
+      result.errors.push({
+        role,
+        source: metadata.source,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get the default core agents directory
+ */
+export function getCoreAgentsDir(): string {
+  // Navigate from dist/agents/compiler.js to agents/
+  return join(dirname(dirname(dirname(import.meta.url.replace('file://', '')))), 'agents');
+}

package/src/agents/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Agents Module
+ *
+ * Provides agent loading, validation, and management for CoreAI.
+ */
+
+export * from './types.js';
+export {
+  loadAgentFromFile,
+  loadAgentsFromDirectory,
+  parseAgentYaml,
+  validateAgentDefinition,
+  getRoleFromFilename,
+  AgentError,
+  type AgentErrorCode,
+} from './loader.js';
+export {
+  resolveString,
+  resolveObject,
+  resolveAgentDefinition,
+  hasVariables,
+  extractVariables,
+  ResolutionError,
+  type ResolutionContext,
+  type ResolutionOptions,
+} from './resolver.js';
+export {
+  generateAgentMarkdown,
+  compileAgent,
+  compileAgents,
+  loadAllAgents,
+  filterAgentsByTeam,
+  getCoreAgentsDir,
+  type CompileOptions,
+  type CompileResult,
+} from './compiler.js';

package/src/agents/loader.test.ts

@@ -0,0 +1,319 @@
+import { mkdtempSync, writeFileSync, rmSync } from 'fs';
+import { join, dirname } from 'path';
+import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
+import { jest } from '@jest/globals';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+import {
+  parseAgentYaml,
+  validateAgentDefinition,
+  loadAgentFromFile,
+  loadAgentsFromDirectory,
+  getRoleFromFilename,
+  AgentError,
+} from './loader.js';
+import type { AgentDefinition } from './types.js';
+
+/**
+ * Helper to check AgentError with specific code
+ */
+function expectAgentError(fn: () => unknown, code: string): void {
+  try {
+    fn();
+    fail('Expected AgentError to be thrown');
+  } catch (error) {
+    expect(error).toBeInstanceOf(AgentError);
+    expect((error as AgentError).code).toBe(code);
+  }
+}
+
+/**
+ * Create a valid minimal agent definition
+ */
+function createMinimalAgent(overrides: Partial<AgentDefinition> = {}): AgentDefinition {
+  return {
+    role: 'test-agent',
+    type: 'ic-engineer',
+    display_name: 'Test Agent',
+    description: 'A test agent for unit tests',
+    ...overrides,
+  };
+}
+
+describe('Agent Loader', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'coreai-agent-test-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('parseAgentYaml', () => {
+    it('should parse valid YAML', () => {
+      const yaml = `
+role: backend-engineer
+type: ic-engineer
+display_name: Backend Engineer
+description: Backend development specialist
+`;
+      const result = parseAgentYaml(yaml);
+      expect(result).toEqual({
+        role: 'backend-engineer',
+        type: 'ic-engineer',
+        display_name: 'Backend Engineer',
+        description: 'Backend development specialist',
+      });
+    });
+
+    it('should throw AgentError for invalid YAML', () => {
+      const invalidYaml = `
+role: "test
+  invalid: yaml
+`;
+      expectAgentError(() => parseAgentYaml(invalidYaml), 'PARSE_ERROR');
+    });
+  });
+
+  describe('validateAgentDefinition', () => {
+    it('should validate a minimal valid agent', () => {
+      const agent = createMinimalAgent();
+      const result = validateAgentDefinition(agent);
+      expect(result).toEqual(agent);
+    });
+
+    it('should validate a full agent definition', () => {
+      const agent: AgentDefinition = {
+        role: 'backend-engineer',
+        type: 'ic-engineer',
+        display_name: 'Backend Engineer',
+        description: 'Backend development specialist',
+        responsibilities: ['Implement APIs', 'Write tests'],
+        expertise: {
+          primary: ['API design', 'Database design'],
+          tech_stack: '${config.tech_stack}',
+        },
+        skills: ['Code review', 'Debugging'],
+        principles: {
+          code_quality: ['Write clean code', 'Follow SOLID'],
+          testing: ['Write tests first'],
+        },
+        behaviors: {
+          workflow: 'ticket-implementation',
+          quality_gates: '${config.quality_gates}',
+        },
+        context_sources: {
+          shared: ['${remote.documentation}/architecture'],
+          personal: ['KnowledgeLibrary/${agent.name}/context'],
+        },
+        communication: {
+          inbox: 'KnowledgeLibrary/${agent.name}/inbox',
+          outbox: 'KnowledgeLibrary/${agent.name}/outbox',
+        },
+      };
+
+      const result = validateAgentDefinition(agent);
+      expect(result).toEqual(agent);
+    });
+
+    it('should throw for missing required fields', () => {
+      const agent = { type: 'ic-engineer' }; // missing role, display_name, description
+      expectAgentError(() => validateAgentDefinition(agent), 'VALIDATION_ERROR');
+    });
+
+    it('should throw for invalid role format', () => {
+      const agent = createMinimalAgent({ role: 'Invalid Role' }); // uppercase and space
+      expectAgentError(() => validateAgentDefinition(agent), 'VALIDATION_ERROR');
+    });
+
+    it('should throw for invalid type', () => {
+      const agent = { ...createMinimalAgent(), type: 'invalid-type' };
+      expectAgentError(() => validateAgentDefinition(agent), 'VALIDATION_ERROR');
+    });
+
+    it('should throw for invalid workflow', () => {
+      const agent = createMinimalAgent();
+      agent.behaviors = { workflow: 'invalid-workflow' as never };
+      expectAgentError(() => validateAgentDefinition(agent), 'VALIDATION_ERROR');
+    });
+  });
+
+  describe('loadAgentFromFile', () => {
+    it('should load and validate an agent file', () => {
+      const agentPath = join(tempDir, 'test-agent.yaml');
+      writeFileSync(
+        agentPath,
+        `
+role: test-agent
+type: ic-engineer
+display_name: Test Agent
+description: A test agent
+`
+      );
+
+      const result = loadAgentFromFile(agentPath);
+      expect(result.role).toBe('test-agent');
+      expect(result.type).toBe('ic-engineer');
+    });
+
+    it('should throw for non-existent file', () => {
+      const agentPath = join(tempDir, 'nonexistent.yaml');
+      expectAgentError(() => loadAgentFromFile(agentPath), 'NOT_FOUND');
+    });
+
+    it('should throw for invalid agent', () => {
+      const agentPath = join(tempDir, 'invalid.yaml');
+      writeFileSync(agentPath, 'invalid: content');
+      expectAgentError(() => loadAgentFromFile(agentPath), 'VALIDATION_ERROR');
+    });
+  });
+
+  describe('loadAgentsFromDirectory', () => {
+    it('should load all agents from a directory', () => {
+      // Create multiple agent files
+      writeFileSync(
+        join(tempDir, 'agent-one.yaml'),
+        `
+role: agent-one
+type: ic-engineer
+display_name: Agent One
+description: First agent
+`
+      );
+      writeFileSync(
+        join(tempDir, 'agent-two.yaml'),
+        `
+role: agent-two
+type: manager
+display_name: Agent Two
+description: Second agent
+`
+      );
+
+      const agents = loadAgentsFromDirectory(tempDir, 'core');
+
+      expect(agents.size).toBe(2);
+      expect(agents.get('agent-one')?.definition.role).toBe('agent-one');
+      expect(agents.get('agent-two')?.definition.role).toBe('agent-two');
+      expect(agents.get('agent-one')?.source).toBe('core');
+    });
+
+    it('should return empty map for non-existent directory', () => {
+      const agents = loadAgentsFromDirectory(join(tempDir, 'nonexistent'), 'core');
+      expect(agents.size).toBe(0);
+    });
+
+    it('should skip invalid files and continue loading', () => {
+      writeFileSync(
+        join(tempDir, 'valid.yaml'),
+        `
+role: valid-agent
+type: ic-engineer
+display_name: Valid Agent
+description: A valid agent
+`
+      );
+      writeFileSync(join(tempDir, 'invalid.yaml'), 'invalid: content');
+
+      // Suppress console.warn for this test
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+      const agents = loadAgentsFromDirectory(tempDir, 'core');
+
+      expect(agents.size).toBe(1);
+      expect(agents.get('valid-agent')).toBeDefined();
+      expect(warnSpy).toHaveBeenCalled();
+
+      warnSpy.mockRestore();
+    });
+
+    it('should handle .yml extension', () => {
+      writeFileSync(
+        join(tempDir, 'agent.yml'),
+        `
+role: yml-agent
+type: specialist
+display_name: YML Agent
+description: Agent with .yml extension
+`
+      );
+
+      const agents = loadAgentsFromDirectory(tempDir, 'custom');
+      expect(agents.size).toBe(1);
+      expect(agents.get('yml-agent')?.source).toBe('custom');
+    });
+  });
+
+  describe('getRoleFromFilename', () => {
+    it('should extract role from .yaml filename', () => {
+      expect(getRoleFromFilename('/path/to/backend-engineer.yaml')).toBe('backend-engineer');
+    });
+
+    it('should extract role from .yml filename', () => {
+      expect(getRoleFromFilename('/path/to/frontend-engineer.yml')).toBe('frontend-engineer');
+    });
+
+    it('should handle simple filename', () => {
+      expect(getRoleFromFilename('devops.yaml')).toBe('devops');
+    });
+  });
+
+  describe('Core Agent Definitions', () => {
+    const coreAgentsDir = join(__dirname, '../../agents');
+
+    it('should load all core agents from agents/ directory', () => {
+      const agents = loadAgentsFromDirectory(coreAgentsDir, 'core');
+
+      expect(agents.size).toBe(4);
+      expect(agents.has('backend-engineer')).toBe(true);
+      expect(agents.has('frontend-engineer')).toBe(true);
+      expect(agents.has('devops-engineer')).toBe(true);
+      expect(agents.has('engineering-manager')).toBe(true);
+    });
+
+    it('should validate backend-engineer agent', () => {
+      const agent = loadAgentFromFile(join(coreAgentsDir, 'backend-engineer.yaml'));
+
+      expect(agent.role).toBe('backend-engineer');
+      expect(agent.type).toBe('ic-engineer');
+      expect(agent.display_name).toBe('Backend Engineer');
+      expect(agent.responsibilities).toBeDefined();
+      expect(agent.expertise?.primary).toBeDefined();
+      expect(agent.behaviors?.workflow).toBe('ticket-implementation');
+    });
+
+    it('should validate frontend-engineer agent', () => {
+      const agent = loadAgentFromFile(join(coreAgentsDir, 'frontend-engineer.yaml'));
+
+      expect(agent.role).toBe('frontend-engineer');
+      expect(agent.type).toBe('ic-engineer');
+      expect(agent.display_name).toBe('Frontend Engineer');
+      expect(agent.responsibilities).toBeDefined();
+      expect(agent.behaviors?.workflow).toBe('ticket-implementation');
+    });
+
+    it('should validate devops-engineer agent', () => {
+      const agent = loadAgentFromFile(join(coreAgentsDir, 'devops-engineer.yaml'));
+
+      expect(agent.role).toBe('devops-engineer');
+      expect(agent.type).toBe('specialist');
+      expect(agent.display_name).toBe('DevOps Engineer');
+      expect(agent.responsibilities).toBeDefined();
+      expect(agent.behaviors?.workflow).toBe('ticket-implementation');
+    });
+
+    it('should validate engineering-manager agent', () => {
+      const agent = loadAgentFromFile(join(coreAgentsDir, 'engineering-manager.yaml'));
+
+      expect(agent.role).toBe('engineering-manager');
+      expect(agent.type).toBe('manager');
+      expect(agent.display_name).toBe('Engineering Manager');
+      expect(agent.responsibilities).toBeDefined();
+      expect(agent.behaviors?.workflow).toBe('planning-estimation');
+    });
+  });
+});