bluera-knowledge 0.10.0 → 0.11.0

package/src/services/store-definition.service.test.ts

@@ -0,0 +1,440 @@
+import { describe, it, expect } from 'vitest';
+import { StoreDefinitionService } from './store-definition.service.js';
+import { rm, mkdtemp, writeFile, readFile, mkdir, access } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import type { StoreDefinitionsConfig, FileStoreDefinition } from '../types/store-definition.js';
+
+/**
+ * Helper to create isolated test context.
+ * Each test creates its own temp directory to ensure complete isolation.
+ */
+async function createTestContext(): Promise<{
+  service: StoreDefinitionService;
+  tempDir: string;
+  cleanup: () => Promise<void>;
+}> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'store-def-test-'));
+  const service = new StoreDefinitionService(tempDir);
+  return {
+    service,
+    tempDir,
+    cleanup: async () => {
+      await rm(tempDir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe('StoreDefinitionService', () => {
+  describe('load', () => {
+    it('returns empty config when file does not exist', async () => {
+      const ctx = await createTestContext();
+      try {
+        const config = await ctx.service.load();
+        expect(config.version).toBe(1);
+        expect(config.stores).toEqual([]);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('loads existing config file', async () => {
+      const ctx = await createTestContext();
+      try {
+        const configPath = join(ctx.tempDir, '.bluera/bluera-knowledge/stores.config.json');
+        await mkdir(dirname(configPath), { recursive: true });
+        const existingConfig: StoreDefinitionsConfig = {
+          version: 1,
+          stores: [{ type: 'file', name: 'test', path: './test' }],
+        };
+        await writeFile(configPath, JSON.stringify(existingConfig));
+
+        const config = await ctx.service.load();
+        expect(config.stores).toHaveLength(1);
+        expect(config.stores[0].name).toBe('test');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('throws on invalid JSON (fail fast per CLAUDE.md)', async () => {
+      const ctx = await createTestContext();
+      try {
+        const configPath = join(ctx.tempDir, '.bluera/bluera-knowledge/stores.config.json');
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, '{invalid json');
+
+        await expect(ctx.service.load()).rejects.toThrow(/parse|JSON/i);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('throws on invalid schema (fail fast per CLAUDE.md)', async () => {
+      const ctx = await createTestContext();
+      try {
+        const configPath = join(ctx.tempDir, '.bluera/bluera-knowledge/stores.config.json');
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, JSON.stringify({ version: 1, stores: [{ type: 'invalid' }] }));
+
+        await expect(ctx.service.load()).rejects.toThrow();
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('throws on wrong version (fail fast per CLAUDE.md)', async () => {
+      const ctx = await createTestContext();
+      try {
+        const configPath = join(ctx.tempDir, '.bluera/bluera-knowledge/stores.config.json');
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, JSON.stringify({ version: 99, stores: [] }));
+
+        await expect(ctx.service.load()).rejects.toThrow();
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('caches loaded config', async () => {
+      const ctx = await createTestContext();
+      try {
+        const config1 = await ctx.service.load();
+        const config2 = await ctx.service.load();
+        expect(config1).toBe(config2); // Same reference
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('save', () => {
+    it('creates directory if not exists', async () => {
+      const ctx = await createTestContext();
+      try {
+        const config: StoreDefinitionsConfig = { version: 1, stores: [] };
+        await ctx.service.save(config);
+
+        const configPath = ctx.service.getConfigPath();
+        await expect(access(configPath)).resolves.toBeUndefined();
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('writes formatted JSON', async () => {
+      const ctx = await createTestContext();
+      try {
+        const config: StoreDefinitionsConfig = {
+          version: 1,
+          stores: [{ type: 'file', name: 'test', path: './test' }],
+        };
+        await ctx.service.save(config);
+
+        const content = await readFile(ctx.service.getConfigPath(), 'utf-8');
+        expect(content).toContain('\n'); // Formatted with newlines
+        expect(content).toContain('"version": 1');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('updates cache after save', async () => {
+      const ctx = await createTestContext();
+      try {
+        const config: StoreDefinitionsConfig = {
+          version: 1,
+          stores: [{ type: 'file', name: 'test', path: './test' }],
+        };
+        await ctx.service.save(config);
+
+        const loaded = await ctx.service.load();
+        expect(loaded.stores).toHaveLength(1);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('addDefinition', () => {
+    it('adds definition to empty config', async () => {
+      const ctx = await createTestContext();
+      try {
+        const definition: FileStoreDefinition = {
+          type: 'file',
+          name: 'docs',
+          path: './docs',
+        };
+        await ctx.service.addDefinition(definition);
+
+        const config = await ctx.service.load();
+        expect(config.stores).toHaveLength(1);
+        expect(config.stores[0].name).toBe('docs');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('adds definition to existing config', async () => {
+      const ctx = await createTestContext();
+      try {
+        // Pre-populate
+        await ctx.service.save({
+          version: 1,
+          stores: [{ type: 'file', name: 'existing', path: './existing' }],
+        });
+        // Clear cache to force reload
+        ctx.service.clearCache();
+
+        // Add new
+        await ctx.service.addDefinition({ type: 'file', name: 'new', path: './new' });
+
+        const config = await ctx.service.load();
+        expect(config.stores).toHaveLength(2);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('throws when adding duplicate name', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+
+        await expect(
+          ctx.service.addDefinition({ type: 'file', name: 'docs', path: './other' })
+        ).rejects.toThrow(/already exists/i);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('persists to file', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+
+        // Create fresh service (no cache)
+        const freshService = new StoreDefinitionService(ctx.tempDir);
+        const config = await freshService.load();
+        expect(config.stores).toHaveLength(1);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('removeDefinition', () => {
+    it('removes existing definition', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+        await ctx.service.addDefinition({ type: 'file', name: 'other', path: './other' });
+
+        const removed = await ctx.service.removeDefinition('docs');
+        expect(removed).toBe(true);
+
+        const config = await ctx.service.load();
+        expect(config.stores).toHaveLength(1);
+        expect(config.stores[0].name).toBe('other');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('returns false for non-existent name', async () => {
+      const ctx = await createTestContext();
+      try {
+        const removed = await ctx.service.removeDefinition('nonexistent');
+        expect(removed).toBe(false);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('persists removal to file', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+        await ctx.service.removeDefinition('docs');
+
+        // Create fresh service
+        const freshService = new StoreDefinitionService(ctx.tempDir);
+        const config = await freshService.load();
+        expect(config.stores).toHaveLength(0);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('updateDefinition', () => {
+    it('updates existing definition', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({
+          type: 'file',
+          name: 'docs',
+          path: './docs',
+          description: 'old',
+        });
+
+        await ctx.service.updateDefinition('docs', { description: 'new description' });
+
+        const config = await ctx.service.load();
+        expect(config.stores[0].description).toBe('new description');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('preserves unchanged fields', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({
+          type: 'file',
+          name: 'docs',
+          path: './docs',
+          description: 'desc',
+          tags: ['tag1'],
+        });
+
+        await ctx.service.updateDefinition('docs', { description: 'updated' });
+
+        const config = await ctx.service.load();
+        const store = config.stores[0] as FileStoreDefinition;
+        expect(store.path).toBe('./docs');
+        expect(store.tags).toEqual(['tag1']);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('throws for non-existent definition', async () => {
+      const ctx = await createTestContext();
+      try {
+        await expect(
+          ctx.service.updateDefinition('nonexistent', { description: 'x' })
+        ).rejects.toThrow(/not found/i);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('persists update to file', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+        await ctx.service.updateDefinition('docs', { description: 'updated' });
+
+        const freshService = new StoreDefinitionService(ctx.tempDir);
+        const config = await freshService.load();
+        expect(config.stores[0].description).toBe('updated');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('getByName', () => {
+    it('returns definition by name', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+
+        const def = await ctx.service.getByName('docs');
+        expect(def).toBeDefined();
+        expect(def?.name).toBe('docs');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('returns undefined for non-existent name', async () => {
+      const ctx = await createTestContext();
+      try {
+        const def = await ctx.service.getByName('nonexistent');
+        expect(def).toBeUndefined();
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('resolvePath', () => {
+    it('resolves relative paths against project root', async () => {
+      const ctx = await createTestContext();
+      try {
+        const resolved = ctx.service.resolvePath('./docs');
+        expect(resolved).toBe(join(ctx.tempDir, 'docs'));
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('resolves paths starting with ./ against project root', async () => {
+      const ctx = await createTestContext();
+      try {
+        const resolved = ctx.service.resolvePath('./src/utils');
+        expect(resolved).toBe(join(ctx.tempDir, 'src/utils'));
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('resolves paths without leading ./ against project root', async () => {
+      const ctx = await createTestContext();
+      try {
+        const resolved = ctx.service.resolvePath('docs');
+        expect(resolved).toBe(join(ctx.tempDir, 'docs'));
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('keeps absolute paths as-is', async () => {
+      const ctx = await createTestContext();
+      try {
+        const resolved = ctx.service.resolvePath('/absolute/path');
+        expect(resolved).toBe('/absolute/path');
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('getConfigPath', () => {
+    it('returns correct config path', async () => {
+      const ctx = await createTestContext();
+      try {
+        const configPath = ctx.service.getConfigPath();
+        expect(configPath).toBe(join(ctx.tempDir, '.bluera/bluera-knowledge/stores.config.json'));
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+
+  describe('hasDefinitions', () => {
+    it('returns false when no definitions', async () => {
+      const ctx = await createTestContext();
+      try {
+        const has = await ctx.service.hasDefinitions();
+        expect(has).toBe(false);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+
+    it('returns true when definitions exist', async () => {
+      const ctx = await createTestContext();
+      try {
+        await ctx.service.addDefinition({ type: 'file', name: 'docs', path: './docs' });
+        const has = await ctx.service.hasDefinitions();
+        expect(has).toBe(true);
+      } finally {
+        await ctx.cleanup();
+      }
+    });
+  });
+});

package/src/services/store-definition.service.ts

@@ -0,0 +1,198 @@
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { dirname, resolve, isAbsolute, join } from 'node:path';
+import { ProjectRootService } from './project-root.service.js';
+import {
+  StoreDefinitionsConfigSchema,
+  DEFAULT_STORE_DEFINITIONS_CONFIG,
+} from '../types/store-definition.js';
+import type { StoreDefinitionsConfig, StoreDefinition } from '../types/store-definition.js';
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Service for managing git-committable store definitions.
+ *
+ * Store definitions are saved to `.bluera/bluera-knowledge/stores.config.json`
+ * within the project root. This file is designed to be committed to version
+ * control, allowing teams to share store configurations.
+ *
+ * The actual store data (vector embeddings, cloned repos) lives in the data
+ * directory and should be gitignored.
+ */
+export class StoreDefinitionService {
+  private readonly configPath: string;
+  private readonly projectRoot: string;
+  private config: StoreDefinitionsConfig | null = null;
+
+  constructor(projectRoot?: string) {
+    this.projectRoot = projectRoot ?? ProjectRootService.resolve();
+    this.configPath = join(this.projectRoot, '.bluera/bluera-knowledge/stores.config.json');
+  }
+
+  /**
+   * Load store definitions from config file.
+   * Returns empty config if file doesn't exist.
+   * Throws on parse/validation errors (fail fast per CLAUDE.md).
+   */
+  async load(): Promise<StoreDefinitionsConfig> {
+    if (this.config !== null) {
+      return this.config;
+    }
+
+    const exists = await fileExists(this.configPath);
+    if (!exists) {
+      // Deep clone to avoid mutating the shared default
+      this.config = {
+        ...DEFAULT_STORE_DEFINITIONS_CONFIG,
+        stores: [...DEFAULT_STORE_DEFINITIONS_CONFIG.stores],
+      };
+      return this.config;
+    }
+
+    const content = await readFile(this.configPath, 'utf-8');
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(content);
+    } catch (error) {
+      throw new Error(
+        `Failed to parse store definitions at ${this.configPath}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+
+    const result = StoreDefinitionsConfigSchema.safeParse(parsed);
+    if (!result.success) {
+      throw new Error(`Invalid store definitions at ${this.configPath}: ${result.error.message}`);
+    }
+
+    this.config = result.data;
+    return this.config;
+  }
+
+  /**
+   * Save store definitions to config file.
+   */
+  async save(config: StoreDefinitionsConfig): Promise<void> {
+    await mkdir(dirname(this.configPath), { recursive: true });
+    await writeFile(this.configPath, JSON.stringify(config, null, 2));
+    this.config = config;
+  }
+
+  /**
+   * Add a store definition.
+   * Throws if a definition with the same name already exists.
+   */
+  async addDefinition(definition: StoreDefinition): Promise<void> {
+    const config = await this.load();
+    const existing = config.stores.find((s) => s.name === definition.name);
+    if (existing !== undefined) {
+      throw new Error(`Store definition "${definition.name}" already exists`);
+    }
+    config.stores.push(definition);
+    await this.save(config);
+  }
+
+  /**
+   * Remove a store definition by name.
+   * Returns true if removed, false if not found.
+   */
+  async removeDefinition(name: string): Promise<boolean> {
+    const config = await this.load();
+    const index = config.stores.findIndex((s) => s.name === name);
+    if (index === -1) {
+      return false;
+    }
+    config.stores.splice(index, 1);
+    await this.save(config);
+    return true;
+  }
+
+  /**
+   * Update an existing store definition.
+   * Only updates the provided fields, preserving others.
+   * Throws if definition not found.
+   */
+  async updateDefinition(
+    name: string,
+    updates: { description?: string; tags?: string[] }
+  ): Promise<void> {
+    const config = await this.load();
+    const index = config.stores.findIndex((s) => s.name === name);
+    if (index === -1) {
+      throw new Error(`Store definition "${name}" not found`);
+    }
+
+    // Merge updates while preserving type safety
+    // We only allow updating common optional fields (description, tags)
+    const existing = config.stores[index];
+    if (existing === undefined) {
+      throw new Error(`Store definition "${name}" not found at index ${String(index)}`);
+    }
+    if (updates.description !== undefined) {
+      existing.description = updates.description;
+    }
+    if (updates.tags !== undefined) {
+      existing.tags = updates.tags;
+    }
+    await this.save(config);
+  }
+
+  /**
+   * Get a store definition by name.
+   * Returns undefined if not found.
+   */
+  async getByName(name: string): Promise<StoreDefinition | undefined> {
+    const config = await this.load();
+    return config.stores.find((s) => s.name === name);
+  }
+
+  /**
+   * Check if any definitions exist.
+   */
+  async hasDefinitions(): Promise<boolean> {
+    const config = await this.load();
+    return config.stores.length > 0;
+  }
+
+  /**
+   * Resolve a file store path relative to project root.
+   */
+  resolvePath(path: string): string {
+    if (isAbsolute(path)) {
+      return path;
+    }
+    return resolve(this.projectRoot, path);
+  }
+
+  /**
+   * Get the config file path.
+   */
+  getConfigPath(): string {
+    return this.configPath;
+  }
+
+  /**
+   * Get the project root.
+   */
+  getProjectRoot(): string {
+    return this.projectRoot;
+  }
+
+  /**
+   * Clear the cached config (useful for testing).
+   */
+  clearCache(): void {
+    this.config = null;
+  }
+}