bluera-knowledge 0.14.0 → 0.14.2

package/src/types/store.ts

@@ -1,47 +0,0 @@
-import type { StoreId } from './brands.js';
-
-export type StoreType = 'file' | 'repo' | 'web';
-export type StoreStatus = 'ready' | 'indexing' | 'error';
-
-interface BaseStore {
-  readonly id: StoreId;
-  readonly name: string;
-  readonly description?: string | undefined;
-  readonly tags?: readonly string[] | undefined;
-  readonly status?: StoreStatus | undefined;
-  readonly createdAt: Date;
-  readonly updatedAt: Date;
-}
-
-export interface FileStore extends BaseStore {
-  readonly type: 'file';
-  readonly path: string;
-}
-
-export interface RepoStore extends BaseStore {
-  readonly type: 'repo';
-  readonly path: string;
-  readonly url?: string | undefined;
-  readonly branch?: string | undefined;
-}
-
-export interface WebStore extends BaseStore {
-  readonly type: 'web';
-  readonly url: string;
-  readonly depth: number;
-  readonly maxPages?: number | undefined;
-}
-
-export type Store = FileStore | RepoStore | WebStore;
-
-export function isFileStore(store: Store): store is FileStore {
-  return store.type === 'file';
-}
-
-export function isRepoStore(store: Store): store is RepoStore {
-  return store.type === 'repo';
-}
-
-export function isWebStore(store: Store): store is WebStore {
-  return store.type === 'web';
-}

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

@@ -1,351 +0,0 @@
-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

@@ -1,61 +0,0 @@
-/**
- * Type guard utilities to replace type assertions
- */
-
-import type { AppConfig } from '../types/config.js';
-import type { DocumentMetadata } from '../types/document.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.test.ts

@@ -1,35 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { readFileSync } from 'fs';
-import { join } from 'path';
-
-/**
- * Tests to verify background-worker-cli.ts uses file logging instead of console.
- * This prevents silent failures when the worker is spawned with stdio: 'ignore'.
- */
-describe('BackgroundWorkerCLI Logging', () => {
-  const sourceFile = join(process.cwd(), 'src/workers/background-worker-cli.ts');
-  const source = readFileSync(sourceFile, 'utf-8');
-
-  it('imports createLogger from logging module', () => {
-    expect(source).toContain('createLogger');
-    expect(source).toContain("from '../logging/index.js'");
-  });
-
-  it('imports shutdownLogger for graceful exit', () => {
-    expect(source).toContain('shutdownLogger');
-  });
-
-  it('does not use console.log', () => {
-    // Filter out comments
-    const lines = source.split('\n').filter((line) => !line.trim().startsWith('//'));
-    const hasConsoleLog = lines.some((line) => /\bconsole\.log\b/.test(line));
-    expect(hasConsoleLog).toBe(false);
-  });
-
-  it('does not use console.error', () => {
-    // Filter out comments
-    const lines = source.split('\n').filter((line) => !line.trim().startsWith('//'));
-    const hasConsoleError = lines.some((line) => /\bconsole\.error\b/.test(line));
-    expect(hasConsoleError).toBe(false);
-  });
-});

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

@@ -1,149 +0,0 @@
-#!/usr/bin/env node
-import { platform } from 'os';
-import { BackgroundWorker } from './background-worker.js';
-import { writePidFile, deletePidFile, buildPidFilePath } from './pid-file.js';
-import { createLogger, shutdownLogger } from '../logging/index.js';
-import { createServices, destroyServices } from '../services/index.js';
-import { JobService } from '../services/job.service.js';
-
-/**
- * Force exit the process to avoid ONNX runtime mutex crash on macOS.
- *
- * On macOS, the ONNX runtime (used by transformers.js for embeddings) has a known
- * bug where static mutex cleanup fails during process exit, causing a crash with:
- * "mutex lock failed: Invalid argument"
- *
- * This doesn't affect job completion - all work is done and persisted before exit.
- * Using SIGKILL bypasses the problematic cleanup code.
- *
- * See: https://github.com/microsoft/onnxruntime/issues/24579
- */
-function forceExitOnMacOS(exitCode: number): void {
-  if (platform() === 'darwin') {
-    // Give time for any pending I/O to flush
-    setTimeout(() => {
-      process.kill(process.pid, 'SIGKILL');
-    }, 100);
-  } else {
-    process.exit(exitCode);
-  }
-}
-
-const logger = createLogger('background-worker-cli');
-
-/**
- * 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 === '') {
-    logger.error('Job ID required. Usage: background-worker-cli <job-id>');
-    await shutdownLogger();
-    process.exit(1);
-  }
-
-  // Initialize services
-  const jobService = new JobService(dataDir);
-  const services = await createServices(undefined, dataDir);
-
-  // Write PID file for job cancellation - CRITICAL: must succeed or job cannot be cancelled
-  const pidFile = buildPidFilePath(
-    jobService['jobsDir'], // Access private field for PID path
-    jobId
-  );
-
-  try {
-    writePidFile(pidFile, process.pid);
-  } catch (error) {
-    // CRITICAL: Cannot proceed without PID file - job would be uncancellable
-    logger.error(
-      { error: error instanceof Error ? error.message : String(error) },
-      'Failed to write PID file'
-    );
-    await shutdownLogger();
-    process.exit(1);
-  }
-
-  // Handle SIGTERM for graceful shutdown
-  process.on('SIGTERM', () => {
-    logger.info({ jobId }, 'Received SIGTERM, cancelling job');
-    jobService.updateJob(jobId, {
-      status: 'cancelled',
-      message: 'Job cancelled by user',
-    });
-
-    // Clean up PID file (best-effort - don't block shutdown)
-    const deleteResult = deletePidFile(pidFile, 'sigterm');
-    if (!deleteResult.success && deleteResult.error !== undefined) {
-      logger.warn(
-        { jobId, error: deleteResult.error.message },
-        'Could not remove PID file during SIGTERM'
-      );
-    }
-
-    // Flush logs before exit (best-effort, don't await in signal handler)
-    void shutdownLogger().finally(() => 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 (best-effort - don't change exit code)
-    const successCleanup = deletePidFile(pidFile, 'success');
-    if (!successCleanup.success && successCleanup.error !== undefined) {
-      logger.warn(
-        { jobId, error: successCleanup.error.message },
-        'Could not remove PID file after success'
-      );
-    }
-
-    logger.info({ jobId }, 'Job completed successfully');
-    await destroyServices(services);
-    await shutdownLogger();
-    forceExitOnMacOS(0);
-  } catch (error) {
-    // Job service already updated with failure status in BackgroundWorker
-    logger.error(
-      { jobId, error: error instanceof Error ? error.message : String(error) },
-      'Job failed'
-    );
-
-    // Clean up PID file on failure (best-effort - exit code reflects job failure)
-    const failureCleanup = deletePidFile(pidFile, 'failure');
-    if (!failureCleanup.success && failureCleanup.error !== undefined) {
-      logger.warn(
-        { jobId, error: failureCleanup.error.message },
-        'Could not remove PID file after failure'
-      );
-    }
-
-    await destroyServices(services);
-    await shutdownLogger();
-    forceExitOnMacOS(1);
-  }
-}
-
-main().catch(async (error: unknown) => {
-  logger.error(
-    { error: error instanceof Error ? error.message : String(error) },
-    'Fatal error in background worker'
-  );
-  await shutdownLogger();
-  forceExitOnMacOS(1);
-});