bluera-knowledge 0.9.21

package/src/utils/type-guards.test.ts

@@ -0,0 +1,346 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseJSON,
+  isDocumentMetadata,
+  isPartialAppConfig,
+  isFloat32ArrayData,
+  hasDefaultExport
+} from './type-guards.js';
+import type { DocumentMetadata } from '../types/document.js';
+
+describe('TypeGuards - parseJSON', () => {
+  it('parses valid JSON with validator', () => {
+    const validator = (value: unknown): value is { name: string } => {
+      return typeof value === 'object' && value !== null && 'name' in value;
+    };
+
+    const result = parseJSON('{"name":"test"}', validator);
+
+    expect(result).toEqual({ name: 'test' });
+  });
+
+  it('throws on invalid JSON structure', () => {
+    const validator = (value: unknown): value is { name: string } => {
+      return typeof value === 'object' && value !== null && 'name' in value && typeof (value as any).name === 'string';
+    };
+
+    expect(() => {
+      parseJSON('{"age":25}', validator);
+    }).toThrow('Invalid JSON structure');
+  });
+
+  it('throws on malformed JSON', () => {
+    const validator = (value: unknown): value is object => true;
+
+    expect(() => {
+      parseJSON('{ invalid json }', validator);
+    }).toThrow();
+  });
+
+  it('handles arrays with validator', () => {
+    const validator = (value: unknown): value is string[] => {
+      return Array.isArray(value) && value.every(v => typeof v === 'string');
+    };
+
+    const result = parseJSON('["a","b","c"]', validator);
+
+    expect(result).toEqual(['a', 'b', 'c']);
+  });
+
+  it('handles numbers with validator', () => {
+    const validator = (value: unknown): value is number => {
+      return typeof value === 'number';
+    };
+
+    const result = parseJSON('42', validator);
+
+    expect(result).toBe(42);
+  });
+
+  it('rejects when validator returns false', () => {
+    const strictValidator = (value: unknown): value is { required: string } => {
+      return (
+        typeof value === 'object' &&
+        value !== null &&
+        'required' in value &&
+        typeof (value as any).required === 'string' &&
+        (value as any).required.length > 0
+      );
+    };
+
+    expect(() => {
+      parseJSON('{"required":""}', strictValidator);
+    }).toThrow('Invalid JSON structure');
+  });
+});
+
+describe('TypeGuards - isDocumentMetadata', () => {
+  it('returns true for valid DocumentMetadata', () => {
+    const metadata: DocumentMetadata = {
+      storeId: 'store-123',
+      path: '/path/to/file.ts',
+      docType: 'code'
+    };
+
+    expect(isDocumentMetadata(metadata)).toBe(true);
+  });
+
+  it('returns false for null', () => {
+    expect(isDocumentMetadata(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isDocumentMetadata(undefined)).toBe(false);
+  });
+
+  it('returns false for non-object types', () => {
+    expect(isDocumentMetadata('string')).toBe(false);
+    expect(isDocumentMetadata(123)).toBe(false);
+    expect(isDocumentMetadata(true)).toBe(false);
+  });
+
+  it('returns false when missing required storeId', () => {
+    const invalid = {
+      path: '/path/to/file.ts',
+      docType: 'code'
+    };
+
+    expect(isDocumentMetadata(invalid)).toBe(false);
+  });
+
+  it('returns false when missing required path', () => {
+    const invalid = {
+      storeId: 'store-123',
+      docType: 'code'
+    };
+
+    expect(isDocumentMetadata(invalid)).toBe(false);
+  });
+
+  it('returns false when missing required docType', () => {
+    const invalid = {
+      storeId: 'store-123',
+      path: '/path/to/file.ts'
+    };
+
+    expect(isDocumentMetadata(invalid)).toBe(false);
+  });
+
+  it('returns false when storeId is not a string', () => {
+    const invalid = {
+      storeId: 123,
+      path: '/path/to/file.ts',
+      docType: 'code'
+    };
+
+    expect(isDocumentMetadata(invalid)).toBe(false);
+  });
+
+  it('returns false when path is not a string', () => {
+    const invalid = {
+      storeId: 'store-123',
+      path: 123,
+      docType: 'code'
+    };
+
+    expect(isDocumentMetadata(invalid)).toBe(false);
+  });
+
+  it('returns false when docType is not a string', () => {
+    const invalid = {
+      storeId: 'store-123',
+      path: '/path/to/file.ts',
+      docType: 123
+    };
+
+    expect(isDocumentMetadata(invalid)).toBe(false);
+  });
+
+  it('returns true with extra properties', () => {
+    const metadata = {
+      storeId: 'store-123',
+      path: '/path/to/file.ts',
+      docType: 'code',
+      extraProp: 'allowed'
+    };
+
+    expect(isDocumentMetadata(metadata)).toBe(true);
+  });
+});
+
+describe('TypeGuards - isPartialAppConfig', () => {
+  it('returns true for valid partial config', () => {
+    const config = {
+      port: 3000,
+      host: 'localhost'
+    };
+
+    expect(isPartialAppConfig(config)).toBe(true);
+  });
+
+  it('returns true for empty object', () => {
+    expect(isPartialAppConfig({})).toBe(true);
+  });
+
+  it('returns false for null', () => {
+    expect(isPartialAppConfig(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isPartialAppConfig(undefined)).toBe(false);
+  });
+
+  it('returns false for non-object types', () => {
+    expect(isPartialAppConfig('string')).toBe(false);
+    expect(isPartialAppConfig(123)).toBe(false);
+    expect(isPartialAppConfig(true)).toBe(false);
+  });
+
+  it('returns true for object with any properties', () => {
+    const config = {
+      anyProp: 'value',
+      anotherProp: 123
+    };
+
+    expect(isPartialAppConfig(config)).toBe(true);
+  });
+});
+
+describe('TypeGuards - isFloat32ArrayData', () => {
+  it('returns true for Float32Array instance', () => {
+    const data = new Float32Array([1.0, 2.0, 3.0]);
+
+    expect(isFloat32ArrayData(data)).toBe(true);
+  });
+
+  it('returns false for regular array', () => {
+    const data = [1.0, 2.0, 3.0];
+
+    expect(isFloat32ArrayData(data)).toBe(false);
+  });
+
+  it('returns false for null', () => {
+    expect(isFloat32ArrayData(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isFloat32ArrayData(undefined)).toBe(false);
+  });
+
+  it('returns false for objects', () => {
+    const obj = { 0: 1.0, 1: 2.0, length: 2 };
+
+    expect(isFloat32ArrayData(obj)).toBe(false);
+  });
+
+  it('returns false for other typed arrays', () => {
+    const int32 = new Int32Array([1, 2, 3]);
+    const uint8 = new Uint8Array([1, 2, 3]);
+
+    expect(isFloat32ArrayData(int32)).toBe(false);
+    expect(isFloat32ArrayData(uint8)).toBe(false);
+  });
+
+  it('returns true for empty Float32Array', () => {
+    const data = new Float32Array();
+
+    expect(isFloat32ArrayData(data)).toBe(true);
+  });
+});
+
+describe('TypeGuards - hasDefaultExport', () => {
+  it('returns true for object with default property', () => {
+    const module = { default: 'value' };
+
+    expect(hasDefaultExport(module)).toBe(true);
+  });
+
+  it('returns true when default is a function', () => {
+    const module = { default: () => {} };
+
+    expect(hasDefaultExport(module)).toBe(true);
+  });
+
+  it('returns true when default is null', () => {
+    const module = { default: null };
+
+    expect(hasDefaultExport(module)).toBe(true);
+  });
+
+  it('returns true when default is undefined', () => {
+    const module = { default: undefined };
+
+    expect(hasDefaultExport(module)).toBe(true);
+  });
+
+  it('returns false when default property is missing', () => {
+    const module = { other: 'value' };
+
+    expect(hasDefaultExport(module)).toBe(false);
+  });
+
+  it('returns false for null', () => {
+    expect(hasDefaultExport(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(hasDefaultExport(undefined)).toBe(false);
+  });
+
+  it('returns false for non-object types', () => {
+    expect(hasDefaultExport('string')).toBe(false);
+    expect(hasDefaultExport(123)).toBe(false);
+    expect(hasDefaultExport(true)).toBe(false);
+  });
+
+  it('returns true for object with default and other properties', () => {
+    const module = {
+      default: 'value',
+      named: 'export'
+    };
+
+    expect(hasDefaultExport(module)).toBe(true);
+  });
+});
+
+describe('TypeGuards - Type Narrowing', () => {
+  it('narrows type after isDocumentMetadata check', () => {
+    const data: unknown = {
+      storeId: 'store-123',
+      path: '/file.ts',
+      docType: 'code'
+    };
+
+    if (isDocumentMetadata(data)) {
+      // TypeScript should know data is DocumentMetadata here
+      expect(data.storeId).toBe('store-123');
+      expect(data.path).toBe('/file.ts');
+      expect(data.docType).toBe('code');
+    } else {
+      throw new Error('Should be DocumentMetadata');
+    }
+  });
+
+  it('narrows type after isFloat32ArrayData check', () => {
+    const data: unknown = new Float32Array([1.0, 2.0, 3.0]);
+
+    if (isFloat32ArrayData(data)) {
+      // TypeScript should know data is Float32Array here
+      expect(data.length).toBe(3);
+      expect(data[0]).toBe(1.0);
+    } else {
+      throw new Error('Should be Float32Array');
+    }
+  });
+
+  it('narrows type after hasDefaultExport check', () => {
+    const module: unknown = { default: 'test' };
+
+    if (hasDefaultExport(module)) {
+      // TypeScript should know module has default property
+      expect(module.default).toBe('test');
+    } else {
+      throw new Error('Should have default export');
+    }
+  });
+});

package/src/utils/type-guards.ts

@@ -0,0 +1,61 @@
+/**
+ * Type guard utilities to replace type assertions
+ */
+
+import type { DocumentMetadata } from '../types/document.js';
+import type { AppConfig } from '../types/config.js';
+
+/**
+ * Safely parse JSON with validation
+ */
+export function parseJSON<T>(json: string, validator: (value: unknown) => value is T): T {
+  const parsed: unknown = JSON.parse(json);
+  if (!validator(parsed)) {
+    throw new Error('Invalid JSON structure');
+  }
+  return parsed;
+}
+
+/**
+ * Type guard for DocumentMetadata
+ */
+export function isDocumentMetadata(value: unknown): value is DocumentMetadata {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj['storeId'] === 'string' &&
+    typeof obj['path'] === 'string' &&
+    typeof obj['docType'] === 'string'
+  );
+}
+
+/**
+ * Type guard for AppConfig
+ */
+export function isPartialAppConfig(value: unknown): value is Partial<AppConfig> {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  // Allow partial config - will be merged with defaults
+  return true;
+}
+
+/**
+ * Type guard for Float32Array-like data
+ */
+export function isFloat32ArrayData(value: unknown): value is Float32Array {
+  return value instanceof Float32Array;
+}
+
+/**
+ * Check if value is a valid module export that might have a default property
+ */
+export function hasDefaultExport(value: unknown): value is { default: unknown } {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return 'default' in value;
+}

package/src/workers/background-worker-cli.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { JobService } from '../services/job.service.js';
+import { BackgroundWorker } from './background-worker.js';
+import { createServices } from '../services/index.js';
+
+/**
+ * Background worker CLI entry point
+ *
+ * Usage: background-worker-cli <job-id>
+ *
+ * This process runs detached from the parent and executes a single job.
+ */
+
+async function main(): Promise<void> {
+  const jobId = process.argv[2];
+  const dataDir = process.env['BLUERA_DATA_DIR'];
+
+  if (jobId === undefined || jobId === '') {
+    console.error('Error: Job ID required');
+    console.error('Usage: background-worker-cli <job-id>');
+    process.exit(1);
+  }
+
+  // Initialize services
+  const jobService = new JobService(dataDir);
+  const services = await createServices(undefined, dataDir);
+
+  // Write PID file for job cancellation
+  const pidFile = path.join(
+    jobService['jobsDir'], // Access private field for PID path
+    `${jobId}.pid`
+  );
+
+  try {
+    fs.writeFileSync(pidFile, process.pid.toString(), 'utf-8');
+  } catch (error) {
+    console.error('Warning: Could not write PID file:', error);
+  }
+
+  // Handle SIGTERM for graceful shutdown
+  process.on('SIGTERM', () => {
+    console.log(`[${jobId}] Received SIGTERM, cancelling job...`);
+    jobService.updateJob(jobId, {
+      status: 'cancelled',
+      message: 'Job cancelled by user'
+    });
+
+    // Clean up PID file
+    try {
+      if (fs.existsSync(pidFile)) {
+        fs.unlinkSync(pidFile);
+      }
+    } catch (error) {
+      console.error('Warning: Could not remove PID file:', error);
+    }
+
+    process.exit(0);
+  });
+
+  // Create worker and execute job
+  const worker = new BackgroundWorker(
+    jobService,
+    services.store,
+    services.index,
+    services.lance,
+    services.embeddings
+  );
+
+  try {
+    await worker.executeJob(jobId);
+
+    // Clean up PID file on success
+    try {
+      if (fs.existsSync(pidFile)) {
+        fs.unlinkSync(pidFile);
+      }
+    } catch (error) {
+      console.error('Warning: Could not remove PID file:', error);
+    }
+
+    console.log(`[${jobId}] Job completed successfully`);
+    process.exit(0);
+  } catch (error) {
+    // Job service already updated with failure status in BackgroundWorker
+    console.error(`[${jobId}] Job failed:`, error);
+
+    // Clean up PID file on failure
+    try {
+      if (fs.existsSync(pidFile)) {
+        fs.unlinkSync(pidFile);
+      }
+    } catch (cleanupError) {
+      console.error('Warning: Could not remove PID file:', cleanupError);
+    }
+
+    process.exit(1);
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error('Fatal error in background worker:', error);
+  process.exit(1);
+});

package/src/workers/background-worker.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { BackgroundWorker } from './background-worker.js';
+import { JobService } from '../services/job.service.js';
+import { StoreService } from '../services/store.service.js';
+import { IndexService } from '../services/index.service.js';
+import type { LanceStore } from '../db/lance.js';
+import type { EmbeddingEngine } from '../db/embeddings.js';
+import { mkdtempSync, rmSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+describe('BackgroundWorker', () => {
+  let tempDir: string;
+  let jobService: JobService;
+  let storeService: StoreService;
+  let indexService: IndexService;
+  let lanceStore: LanceStore;
+  let embeddingEngine: EmbeddingEngine;
+  let worker: BackgroundWorker;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), 'background-worker-test-'));
+    jobService = new JobService(tempDir);
+    storeService = new StoreService(tempDir);
+    indexService = new IndexService(tempDir);
+    // Mock LanceStore and EmbeddingEngine for testing
+    lanceStore = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      addDocuments: vi.fn().mockResolvedValue(undefined),
+    } as unknown as LanceStore;
+    embeddingEngine = {
+      embed: vi.fn().mockResolvedValue(new Array(384).fill(0)),
+    } as unknown as EmbeddingEngine;
+    worker = new BackgroundWorker(jobService, storeService, indexService, lanceStore, embeddingEngine);
+  });
+
+  afterEach(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('executeJob', () => {
+    it('should throw error for non-existent job', async () => {
+      await expect(worker.executeJob('non-existent')).rejects.toThrow(
+        'Job non-existent not found'
+      );
+    });
+
+    it('should throw error for unknown job type', async () => {
+      const job = jobService.createJob({
+        // @ts-expect-error testing invalid job type
+        type: 'unknown',
+        details: { storeId: 'test' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Unknown job type: unknown'
+      );
+    });
+
+    it('should set job to running status before execution', async () => {
+      const job = jobService.createJob({
+        type: 'crawl',
+        details: { storeId: 'test' }
+      });
+
+      try {
+        await worker.executeJob(job.id);
+      } catch {
+        // Expected to fail since store doesn't exist
+      }
+
+      const updated = jobService.getJob(job.id);
+      // Should have been set to running before throwing error
+      expect(updated?.status).toBe('failed');
+    });
+
+    it('should update job to failed status on error', async () => {
+      const job = jobService.createJob({
+        type: 'crawl',
+        details: { storeId: 'test', url: 'https://example.com' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Web store test not found'
+      );
+
+      const updated = jobService.getJob(job.id);
+      expect(updated?.status).toBe('failed');
+      expect(updated?.message).toBe('Web store test not found');
+    });
+  });
+
+  describe('executeIndexJob', () => {
+    it('should throw error for job without storeId', async () => {
+      const job = jobService.createJob({
+        type: 'index',
+        details: {}
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Store ID required for index job'
+      );
+    });
+
+    it('should throw error for non-existent store', async () => {
+      const job = jobService.createJob({
+        type: 'index',
+        details: { storeId: 'non-existent-store' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Store non-existent-store not found'
+      );
+    });
+
+  });
+
+  describe('executeCloneJob', () => {
+    it('should throw error for job without storeId', async () => {
+      const job = jobService.createJob({
+        type: 'clone',
+        details: {}
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Store ID required for clone job'
+      );
+    });
+
+    it('should throw error for non-existent store', async () => {
+      const job = jobService.createJob({
+        type: 'clone',
+        details: { storeId: 'non-existent-store' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Store non-existent-store not found'
+      );
+    });
+  });
+
+  describe('executeCrawlJob', () => {
+    it('should throw error for job without storeId', async () => {
+      const job = jobService.createJob({
+        type: 'crawl',
+        details: { url: 'https://example.com' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Store ID required for crawl job'
+      );
+    });
+
+    it('should throw error for job without url', async () => {
+      const job = jobService.createJob({
+        type: 'crawl',
+        details: { storeId: 'test-store' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'URL required for crawl job'
+      );
+    });
+
+    it('should throw error for non-existent store', async () => {
+      const job = jobService.createJob({
+        type: 'crawl',
+        details: { storeId: 'non-existent-store', url: 'https://example.com' }
+      });
+
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        'Web store non-existent-store not found'
+      );
+    });
+  });
+});