@dot-ai/core 0.5.2

package/src/__tests__/loader.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { registerProvider, clearProviders, createProviders } from '../loader.js';
+
+beforeEach(() => {
+  clearProviders();
+});
+
+describe('clearProviders', () => {
+  it('resets the registry so registered factories are no longer used', async () => {
+    const factory = vi.fn().mockReturnValue({
+      search: vi.fn().mockResolvedValue([{ content: 'custom', type: 'fact', source: 'test' }]),
+      store: vi.fn().mockResolvedValue(undefined),
+    });
+    registerProvider('@dot-ai/provider-file-memory', factory);
+    clearProviders();
+
+    const providers = await createProviders({ memory: { use: '@dot-ai/provider-file-memory' } });
+    // After clear, factory should not be called — noop provider is used
+    expect(factory).not.toHaveBeenCalled();
+    const memories = await providers.memory.search('query');
+    expect(memories).toEqual([]);
+  });
+});
+
+describe('registerProvider + createProviders', () => {
+  it('uses registered memory factory', async () => {
+    const customMemory = {
+      search: vi.fn().mockResolvedValue([{ content: 'custom result', type: 'fact', source: 'test' }]),
+      store: vi.fn().mockResolvedValue(undefined),
+    };
+    registerProvider('@dot-ai/custom-memory', () => customMemory);
+
+    const providers = await createProviders({ memory: { use: '@dot-ai/custom-memory' } });
+    const results = await providers.memory.search('query');
+    expect(results[0]?.content).toBe('custom result');
+  });
+
+  it('passes options to the factory', async () => {
+    const factory = vi.fn().mockReturnValue({
+      search: vi.fn().mockResolvedValue([]),
+      store: vi.fn().mockResolvedValue(undefined),
+    });
+    registerProvider('@dot-ai/opts-memory', factory);
+
+    await createProviders({ memory: { use: '@dot-ai/opts-memory', with: { url: 'http://test' } } });
+    expect(factory).toHaveBeenCalledWith({ url: 'http://test' });
+  });
+
+  it('supports async factory (returns Promise)', async () => {
+    const customMemory = {
+      search: vi.fn().mockResolvedValue([]),
+      store: vi.fn().mockResolvedValue(undefined),
+    };
+    registerProvider('@dot-ai/async-memory', async () => customMemory);
+
+    const providers = await createProviders({ memory: { use: '@dot-ai/async-memory' } });
+    expect(providers.memory).toBe(customMemory);
+  });
+
+  it('registers and uses a skill provider', async () => {
+    const mockSkills = [{ name: 'my-skill', description: 'A skill', labels: ['test'] }];
+    registerProvider('@dot-ai/custom-skills', () => ({
+      list: vi.fn().mockResolvedValue(mockSkills),
+      match: vi.fn().mockResolvedValue([]),
+      load: vi.fn().mockResolvedValue(null),
+    }));
+
+    const providers = await createProviders({ skills: { use: '@dot-ai/custom-skills' } });
+    const skills = await providers.skills.list();
+    expect(skills).toEqual(mockSkills);
+  });
+
+  it('registers and uses an identity provider', async () => {
+    const mockIdentities = [{ type: 'agents', content: 'I am Kiwi', source: 'file', priority: 1 }];
+    registerProvider('@dot-ai/custom-identity', () => ({
+      load: vi.fn().mockResolvedValue(mockIdentities),
+    }));
+
+    const providers = await createProviders({ identity: { use: '@dot-ai/custom-identity' } });
+    const identities = await providers.identity.load();
+    expect(identities).toEqual(mockIdentities);
+  });
+});
+
+describe('auto-discovery via dynamic import', () => {
+  // NOTE: Dynamic import behavior is hard to mock reliably in vitest (import() is
+  // module-level). Auto-discovery with real packages is tested via E2E.
+  // The unit guarantee here is that an unknown provider name gracefully falls
+  // back to the noop implementation (i.e. tryImportProvider returns null for
+  // non-existent packages without throwing).
+  it('falls back to noop when provider package does not exist', async () => {
+    // '@dot-ai/nonexistent-provider' is not registered and cannot be imported
+    const providers = await createProviders({ memory: { use: '@dot-ai/nonexistent-provider' } });
+    const memories = await providers.memory.search('query');
+    expect(memories).toEqual([]);
+  });
+});
+
+describe('createProviders — noop fallbacks', () => {
+  // Use non-existent provider names to ensure noop fallbacks are returned
+  // (auto-discovery would find real packages for default names like @dot-ai/provider-file-memory)
+  const noopConfig = {
+    memory: { use: '@dot-ai/nonexistent-memory' },
+    skills: { use: '@dot-ai/nonexistent-skills' },
+    identity: { use: '@dot-ai/nonexistent-identity' },
+    routing: { use: '@dot-ai/nonexistent-routing' },
+    tasks: { use: '@dot-ai/nonexistent-tasks' },
+    tools: { use: '@dot-ai/nonexistent-tools' },
+  };
+
+  it('returns noop memory provider when nothing registered', async () => {
+    const providers = await createProviders(noopConfig);
+    const memories = await providers.memory.search('any query');
+    expect(memories).toEqual([]);
+  });
+
+  it('noop memory.store resolves without error', async () => {
+    const providers = await createProviders(noopConfig);
+    await expect(
+      providers.memory.store({ content: 'x', type: 'log' }),
+    ).resolves.toBeUndefined();
+  });
+
+  it('noop skills.list returns empty array', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.skills.list()).toEqual([]);
+  });
+
+  it('noop skills.match returns empty array', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.skills.match([])).toEqual([]);
+  });
+
+  it('noop skills.load returns null', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.skills.load('any-skill')).toBeNull();
+  });
+
+  it('noop identity.load returns empty array', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.identity.load()).toEqual([]);
+  });
+
+  it('noop routing.route returns a RoutingResult', async () => {
+    const providers = await createProviders(noopConfig);
+    const result = await providers.routing.route([]);
+    expect(result).toHaveProperty('model');
+    expect(result).toHaveProperty('reason');
+    expect(typeof result.model).toBe('string');
+  });
+
+  it('noop tasks.list returns empty array', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.tasks.list()).toEqual([]);
+  });
+
+  it('noop tasks.get returns null', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.tasks.get('123')).toBeNull();
+  });
+
+  it('noop tasks.create returns a task with generated id', async () => {
+    const providers = await createProviders(noopConfig);
+    const task = await providers.tasks.create({ text: 'Do something', status: 'pending' });
+    expect(task).toHaveProperty('id');
+    expect(task.text).toBe('Do something');
+    expect(task.status).toBe('pending');
+  });
+
+  it('noop tasks.update returns a task with the patched fields', async () => {
+    const providers = await createProviders(noopConfig);
+    const task = await providers.tasks.update('abc', { status: 'done' });
+    expect(task.id).toBe('abc');
+    expect(task.status).toBe('done');
+  });
+
+  it('noop tools.list returns empty array', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.tools.list()).toEqual([]);
+  });
+
+  it('noop tools.match returns empty array', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.tools.match([])).toEqual([]);
+  });
+
+  it('noop tools.load returns null', async () => {
+    const providers = await createProviders(noopConfig);
+    expect(await providers.tools.load('any-tool')).toBeNull();
+  });
+});

package/src/__tests__/logger.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { NoopLogger, JsonFileLogger, StderrLogger } from '../logger.js';
+import type { LogEntry } from '../logger.js';
+
+const makeEntry = (overrides?: Partial<LogEntry>): LogEntry => ({
+  timestamp: '2026-03-04T12:00:00.000Z',
+  level: 'info',
+  phase: 'boot',
+  event: 'test_event',
+  ...overrides,
+});
+
+describe('NoopLogger', () => {
+  it('log does nothing', () => {
+    const logger = new NoopLogger();
+    logger.log(makeEntry());
+    // No error thrown
+  });
+
+  it('flush resolves immediately', async () => {
+    const logger = new NoopLogger();
+    await logger.flush();
+  });
+});
+
+describe('JsonFileLogger', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'dot-ai-logger-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('writes JSONL on flush', async () => {
+    const logFile = join(tempDir, 'test.jsonl');
+    const logger = new JsonFileLogger(logFile);
+
+    logger.log(makeEntry({ event: 'event_1' }));
+    logger.log(makeEntry({ event: 'event_2' }));
+    await logger.flush();
+
+    const content = await readFile(logFile, 'utf-8');
+    const lines = content.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]).event).toBe('event_1');
+    expect(JSON.parse(lines[1]).event).toBe('event_2');
+  });
+
+  it('does nothing on flush when buffer is empty', async () => {
+    const logFile = join(tempDir, 'empty.jsonl');
+    const logger = new JsonFileLogger(logFile);
+    await logger.flush();
+    // File should not exist (no write)
+    await expect(readFile(logFile, 'utf-8')).rejects.toThrow();
+  });
+
+  it('clears buffer after flush', async () => {
+    const logFile = join(tempDir, 'clear.jsonl');
+    const logger = new JsonFileLogger(logFile);
+
+    logger.log(makeEntry({ event: 'first' }));
+    await logger.flush();
+    logger.log(makeEntry({ event: 'second' }));
+    await logger.flush();
+
+    const content = await readFile(logFile, 'utf-8');
+    const lines = content.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]).event).toBe('first');
+    expect(JSON.parse(lines[1]).event).toBe('second');
+  });
+
+  it('includes all LogEntry fields', async () => {
+    const logFile = join(tempDir, 'fields.jsonl');
+    const logger = new JsonFileLogger(logFile);
+
+    logger.log(makeEntry({
+      level: 'warn',
+      phase: 'enrich',
+      event: 'labels_extracted',
+      data: { labels: ['git', 'commit'], count: 2 },
+      durationMs: 42,
+    }));
+    await logger.flush();
+
+    const content = await readFile(logFile, 'utf-8');
+    const entry = JSON.parse(content.trim());
+    expect(entry.level).toBe('warn');
+    expect(entry.phase).toBe('enrich');
+    expect(entry.event).toBe('labels_extracted');
+    expect(entry.data.labels).toEqual(['git', 'commit']);
+    expect(entry.durationMs).toBe(42);
+  });
+});
+
+describe('StderrLogger', () => {
+  it('writes to stderr', () => {
+    const logger = new StderrLogger();
+    // Just verify it doesn't throw
+    logger.log(makeEntry());
+  });
+
+  it('flush resolves immediately', async () => {
+    const logger = new StderrLogger();
+    await logger.flush();
+  });
+});

package/src/__tests__/nodes.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { discoverNodes, parseScanDirs } from '../nodes.js';
+
+let root: string;
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'dot-ai-nodes-'));
+});
+
+describe('discoverNodes', () => {
+  it('returns root node even if .ai/ does not exist', () => {
+    const nodes = discoverNodes(root);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].name).toBe('root');
+    expect(nodes[0].root).toBe(true);
+  });
+
+  it('discovers sub-nodes in projects/ directory', async () => {
+    await mkdir(join(root, '.ai'), { recursive: true });
+    await mkdir(join(root, 'projects', 'pro', '.ai'), { recursive: true });
+    await mkdir(join(root, 'projects', 'cockpit', '.ai'), { recursive: true });
+    // This project has no .ai/ — should be skipped
+    await mkdir(join(root, 'projects', 'no-ai'), { recursive: true });
+
+    const nodes = discoverNodes(root);
+    expect(nodes).toHaveLength(3); // root + pro + cockpit
+    expect(nodes.map(n => n.name).sort()).toEqual(['cockpit', 'pro', 'root']);
+    expect(nodes.find(n => n.name === 'pro')?.root).toBe(false);
+  });
+
+  it('supports custom scanDirs', async () => {
+    await mkdir(join(root, '.ai'), { recursive: true });
+    await mkdir(join(root, 'apps', 'web', '.ai'), { recursive: true });
+
+    const nodes = discoverNodes(root, ['apps']);
+    expect(nodes).toHaveLength(2);
+    expect(nodes[1].name).toBe('web');
+  });
+
+  it('handles multiple scanDirs', async () => {
+    await mkdir(join(root, '.ai'), { recursive: true });
+    await mkdir(join(root, 'projects', 'a', '.ai'), { recursive: true });
+    await mkdir(join(root, 'apps', 'b', '.ai'), { recursive: true });
+
+    const nodes = discoverNodes(root, ['projects', 'apps']);
+    expect(nodes).toHaveLength(3);
+  });
+
+  it('returns only root when scanDirs is empty', async () => {
+    await mkdir(join(root, '.ai'), { recursive: true });
+    await mkdir(join(root, 'projects', 'pro', '.ai'), { recursive: true });
+
+    const nodes = discoverNodes(root, []);
+    expect(nodes).toHaveLength(1);
+  });
+
+  it('ignores non-directory entries in scan path', async () => {
+    await mkdir(join(root, '.ai'), { recursive: true });
+    await mkdir(join(root, 'projects'), { recursive: true });
+    await writeFile(join(root, 'projects', 'not-a-dir'), 'hello');
+
+    const nodes = discoverNodes(root);
+    expect(nodes).toHaveLength(1); // only root
+  });
+
+  it('node paths point to .ai/ directory', async () => {
+    await mkdir(join(root, '.ai'), { recursive: true });
+    await mkdir(join(root, 'projects', 'pro', '.ai'), { recursive: true });
+
+    const nodes = discoverNodes(root);
+    const pro = nodes.find(n => n.name === 'pro');
+    expect(pro?.path).toBe(join(root, 'projects', 'pro', '.ai'));
+  });
+});
+
+describe('parseScanDirs', () => {
+  it('returns empty for undefined', () => {
+    expect(parseScanDirs(undefined)).toEqual([]);
+  });
+
+  it('returns empty for empty string', () => {
+    expect(parseScanDirs('')).toEqual([]);
+  });
+
+  it('parses single value', () => {
+    expect(parseScanDirs('projects')).toEqual(['projects']);
+  });
+
+  it('parses comma-separated values', () => {
+    expect(parseScanDirs('projects, apps')).toEqual(['projects', 'apps']);
+  });
+
+  it('trims whitespace', () => {
+    expect(parseScanDirs('  projects , apps  ')).toEqual(['projects', 'apps']);
+  });
+
+  it('filters empty values', () => {
+    expect(parseScanDirs('projects,,apps')).toEqual(['projects', 'apps']);
+  });
+});

package/src/config.ts

@@ -0,0 +1,178 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { DotAiConfig, ProviderConfig } from './types.js';
+import { discoverNodes, parseScanDirs } from './nodes.js';
+
+/**
+ * Inject the workspace root into all provider sections of a DotAiConfig.
+ * This ensures file-based providers resolve paths relative to the workspace.
+ */
+export function injectRoot(config: DotAiConfig, root: string): DotAiConfig {
+  // Discover workspace nodes
+  const globalScanDirs = parseScanDirs(config.workspace?.scanDirs ?? 'projects');
+  const nodes = discoverNodes(root, globalScanDirs);
+
+  const result: DotAiConfig = {};
+  const providerKeys = ['memory', 'skills', 'identity', 'routing', 'tasks', 'tools'] as const;
+  for (const key of providerKeys) {
+    const section = config[key];
+    if (section && typeof section === 'object') {
+      result[key] = {
+        ...section,
+        with: { root, nodes, ...(section.with ?? {}) },
+      };
+    }
+  }
+  // Preserve non-provider sections
+  if (config.debug) {
+    result.debug = config.debug;
+  }
+  if (config.workspace) {
+    result.workspace = config.workspace;
+  }
+  return result;
+}
+
+/**
+ * Load and parse dot-ai.yml from a workspace root.
+ * Returns the config with defaults applied.
+ *
+ * Uses a minimal YAML parser (key: value pairs + nested objects).
+ * No dependency on yaml package.
+ */
+export async function loadConfig(workspaceRoot: string): Promise<DotAiConfig> {
+  const configPath = join(workspaceRoot, '.ai', 'dot-ai.yml');
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, 'utf-8');
+  } catch {
+    // No config file — return empty config (all defaults)
+    return {};
+  }
+
+  return parseYaml(raw);
+}
+
+/**
+ * Resolve a config with defaults.
+ * Any missing provider gets the built-in file-based default.
+ */
+export interface ResolvedConfig {
+  memory: ProviderConfig;
+  skills: ProviderConfig;
+  identity: ProviderConfig;
+  routing: ProviderConfig;
+  tasks: ProviderConfig;
+  tools: ProviderConfig;
+  debug?: import('./types.js').DebugConfig;
+}
+
+export function resolveConfig(config: DotAiConfig): ResolvedConfig {
+  return {
+    memory: config.memory ?? { use: '@dot-ai/provider-file-memory' },
+    skills: config.skills ?? { use: '@dot-ai/provider-file-skills' },
+    identity: config.identity ?? { use: '@dot-ai/provider-file-identity' },
+    routing: config.routing ?? { use: '@dot-ai/provider-rules-routing' },
+    tasks: config.tasks ?? { use: '@dot-ai/provider-file-tasks' },
+    tools: config.tools ?? { use: '@dot-ai/provider-file-tools' },
+    debug: config.debug,
+  };
+}
+
+// ── Minimal YAML parser ─────────────────────────────────────────────────────
+
+interface YamlNode {
+  [key: string]: string | YamlNode;
+}
+
+function stripQuotes(s: string): string {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function parseYaml(raw: string): DotAiConfig {
+  const lines = raw.split('\n');
+  const result: YamlNode = {};
+  let currentSection: string | null = null;
+
+  for (const line of lines) {
+    // Skip comments and empty lines
+    if (line.trim().startsWith('#') || line.trim() === '') continue;
+
+    // Top-level key (no indent)
+    const topMatch = line.match(/^(\w+):$/);
+    if (topMatch) {
+      currentSection = topMatch[1];
+      result[currentSection] = {};
+      continue;
+    }
+
+    // Nested key: value (2-space indent)
+    const nestedMatch = line.match(/^  (\w+):\s*(.+)$/);
+    if (nestedMatch && currentSection) {
+      const section = result[currentSection] as YamlNode;
+      let value = stripQuotes(nestedMatch[2].trim());
+
+      // Resolve ${ENV_VAR} references
+      value = value.replace(/\$\{(\w+)\}/g, (_, name: string) => process.env[name] ?? '');
+
+      section[nestedMatch[1]] = value;
+      continue;
+    }
+
+    // Deeper nested key: value (4-space indent) for 'with' block
+    const deepMatch = line.match(/^    (\w+):\s*(.+)$/);
+    if (deepMatch && currentSection) {
+      const section = result[currentSection] as YamlNode;
+      if (!section['with'] || typeof section['with'] === 'string') {
+        section['with'] = {};
+      }
+      let value = stripQuotes(deepMatch[2].trim());
+      value = value.replace(/\$\{(\w+)\}/g, (_, name: string) => process.env[name] ?? '');
+      (section['with'] as YamlNode)[deepMatch[1]] = value;
+    }
+  }
+
+  // Convert YamlNode to DotAiConfig
+  const config: DotAiConfig = {};
+  const providerKeys = ['memory', 'skills', 'identity', 'routing', 'tasks', 'tools'] as const;
+
+  for (const key of providerKeys) {
+    const section = result[key];
+    if (section && typeof section === 'object') {
+      const node = section as YamlNode;
+      const providerConfig: ProviderConfig = {
+        use: typeof node['use'] === 'string' ? node['use'] : '',
+      };
+      if (node['with'] && typeof node['with'] === 'object') {
+        providerConfig.with = node['with'] as Record<string, unknown>;
+      }
+      config[key] = providerConfig;
+    }
+  }
+
+  // Parse debug section
+  const debugSection = result['debug'];
+  if (debugSection && typeof debugSection === 'object') {
+    const node = debugSection as YamlNode;
+    config.debug = {};
+    if (typeof node['logPath'] === 'string') {
+      config.debug.logPath = node['logPath'];
+    }
+  }
+
+  // Parse workspace section
+  const workspaceSection = result['workspace'];
+  if (workspaceSection && typeof workspaceSection === 'object') {
+    const node = workspaceSection as YamlNode;
+    config.workspace = {};
+    if (typeof node['scanDirs'] === 'string') {
+      config.workspace.scanDirs = node['scanDirs'];
+    }
+  }
+
+  return config;
+}

package/src/contracts.ts

@@ -0,0 +1,71 @@
+import type {
+  MemoryEntry,
+  Skill,
+  Identity,
+  Tool,
+  Task,
+  TaskFilter,
+  RoutingResult,
+  Label,
+} from './types.js';
+
+/**
+ * Memory provider — search and store memories.
+ * Implementation decides WHERE and HOW (files, DB, API, etc.)
+ */
+export interface MemoryProvider {
+  search(query: string, labels?: string[]): Promise<MemoryEntry[]>;
+  store(entry: Omit<MemoryEntry, 'source'>): Promise<void>;
+}
+
+/**
+ * Skill provider — discover and load skills.
+ * Implementation decides WHERE skills come from (files, registry, API, etc.)
+ */
+export interface SkillProvider {
+  list(): Promise<Skill[]>;
+  match(labels: Label[]): Promise<Skill[]>;
+  load(name: string): Promise<string | null>; // returns content
+}
+
+/**
+ * Identity provider — load identity documents.
+ * Implementation decides format and source.
+ */
+export interface IdentityProvider {
+  load(): Promise<Identity[]>;
+}
+
+/**
+ * Routing provider — decide which model to use.
+ * Implementation decides the logic (rules, LLM, etc.)
+ */
+export interface RoutingProvider {
+  route(labels: Label[], context?: Record<string, unknown>): Promise<RoutingResult>;
+}
+
+/**
+ * Task provider — CRUD for tasks.
+ * Implementation decides storage (files, Cockpit API, Jira, etc.)
+ */
+export interface TaskProvider {
+  list(filter?: TaskFilter): Promise<Task[]>;
+  get(id: string): Promise<Task | null>;
+  create(task: Omit<Task, 'id'>): Promise<Task>;
+  update(id: string, patch: Partial<Task>): Promise<Task>;
+}
+
+/**
+ * Tool provider — discover and match tools.
+ * Implementation decides source (MCP config, files, registry, etc.)
+ */
+export interface ToolProvider {
+  list(): Promise<Tool[]>;
+  match(labels: Label[]): Promise<Tool[]>;
+  load(name: string): Promise<Tool | null>;
+}
+
+/**
+ * Factory function type for creating providers from config.
+ */
+export type ProviderFactory<T> = (options: Record<string, unknown>) => T | Promise<T>;