bluera-knowledge 0.14.0 → 0.14.1

package/src/workers/pid-file.test.ts

@@ -1,167 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync, existsSync, chmodSync, writeFileSync, readFileSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
-import { writePidFile, deletePidFile, buildPidFilePath } from './pid-file.js';
-
-/**
- * PID File Operations Tests
- *
- * SAFETY: All tests use fake PID 999999999 - never real PIDs.
- * This prevents accidentally killing VSCode, terminals, or other processes.
- */
-describe('PID File Operations', () => {
-  let tempDir: string;
-  let pidFile: string;
-
-  // Fake PID - guaranteed not to be a real process
-  const FAKE_PID = 999999999;
-
-  beforeEach(() => {
-    tempDir = mkdtempSync(join(tmpdir(), 'pid-file-test-'));
-    pidFile = join(tempDir, 'test_job.pid');
-  });
-
-  afterEach(() => {
-    if (existsSync(tempDir)) {
-      // Restore permissions before cleanup (in case test made it read-only)
-      try {
-        chmodSync(tempDir, 0o755);
-      } catch {
-        // Ignore - might not exist
-      }
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  describe('writePidFile', () => {
-    it('should write PID to file successfully', () => {
-      writePidFile(pidFile, FAKE_PID);
-
-      expect(existsSync(pidFile)).toBe(true);
-      const content = readFileSync(pidFile, 'utf-8');
-      expect(content).toBe('999999999');
-    });
-
-    it('should overwrite existing PID file', () => {
-      writeFileSync(pidFile, '123456', 'utf-8');
-
-      writePidFile(pidFile, FAKE_PID);
-
-      const content = readFileSync(pidFile, 'utf-8');
-      expect(content).toBe('999999999');
-    });
-
-    it('should throw with CRITICAL message when write fails (permission denied)', () => {
-      // Make directory read-only to prevent file creation
-      chmodSync(tempDir, 0o444);
-
-      expect(() => writePidFile(pidFile, FAKE_PID)).toThrow(/CRITICAL/);
-      expect(() => writePidFile(pidFile, FAKE_PID)).toThrow(/Failed to write PID file/);
-      expect(() => writePidFile(pidFile, FAKE_PID)).toThrow(/Job cannot be cancelled/);
-    });
-
-    it('should include file path in error message', () => {
-      chmodSync(tempDir, 0o444);
-
-      try {
-        writePidFile(pidFile, FAKE_PID);
-        expect.fail('Should have thrown');
-      } catch (error) {
-        expect(error).toBeInstanceOf(Error);
-        expect((error as Error).message).toContain(pidFile);
-      }
-    });
-
-    it('should throw when path directory does not exist', () => {
-      const invalidPath = '/nonexistent/directory/test.pid';
-
-      expect(() => writePidFile(invalidPath, FAKE_PID)).toThrow(/CRITICAL/);
-    });
-  });
-
-  describe('deletePidFile', () => {
-    it('should delete PID file successfully', () => {
-      writeFileSync(pidFile, FAKE_PID.toString(), 'utf-8');
-
-      const result = deletePidFile(pidFile, 'success');
-
-      expect(result.success).toBe(true);
-      expect(result.error).toBeUndefined();
-      expect(existsSync(pidFile)).toBe(false);
-    });
-
-    it('should return success when PID file does not exist', () => {
-      // File doesn't exist
-      expect(existsSync(pidFile)).toBe(false);
-
-      const result = deletePidFile(pidFile, 'success');
-
-      expect(result.success).toBe(true);
-      expect(result.error).toBeUndefined();
-    });
-
-    it('should return failure (NOT throw) when delete fails', () => {
-      writeFileSync(pidFile, FAKE_PID.toString(), 'utf-8');
-      // Make directory read-only to prevent deletion
-      chmodSync(tempDir, 0o444);
-
-      // Should NOT throw
-      const result = deletePidFile(pidFile, 'success');
-
-      expect(result.success).toBe(false);
-      expect(result.error).toBeInstanceOf(Error);
-    });
-
-    it('should never throw on delete failure - returns result instead', () => {
-      writeFileSync(pidFile, FAKE_PID.toString(), 'utf-8');
-      chmodSync(tempDir, 0o444);
-
-      // Must not throw - this is best-effort cleanup
-      expect(() => deletePidFile(pidFile, 'failure')).not.toThrow();
-      expect(() => deletePidFile(pidFile, 'sigterm')).not.toThrow();
-      expect(() => deletePidFile(pidFile, 'success')).not.toThrow();
-    });
-
-    it('should handle sigterm context', () => {
-      writeFileSync(pidFile, FAKE_PID.toString(), 'utf-8');
-
-      const result = deletePidFile(pidFile, 'sigterm');
-
-      expect(result.success).toBe(true);
-      expect(existsSync(pidFile)).toBe(false);
-    });
-
-    it('should handle failure context', () => {
-      writeFileSync(pidFile, FAKE_PID.toString(), 'utf-8');
-
-      const result = deletePidFile(pidFile, 'failure');
-
-      expect(result.success).toBe(true);
-      expect(existsSync(pidFile)).toBe(false);
-    });
-  });
-
-  describe('buildPidFilePath', () => {
-    it('should build correct PID file path', () => {
-      const result = buildPidFilePath('/data/jobs', 'job_123');
-
-      expect(result).toBe('/data/jobs/job_123.pid');
-    });
-
-    it('should handle job IDs with various formats', () => {
-      expect(buildPidFilePath('/jobs', 'abc123def')).toBe('/jobs/abc123def.pid');
-      expect(buildPidFilePath('/jobs', 'test-job')).toBe('/jobs/test-job.pid');
-      expect(buildPidFilePath('/jobs', 'job_with_underscore')).toBe(
-        '/jobs/job_with_underscore.pid'
-      );
-    });
-
-    it('should handle paths with trailing slash', () => {
-      // path.join normalizes this
-      const result = buildPidFilePath('/data/jobs/', 'job_123');
-
-      expect(result).toBe('/data/jobs/job_123.pid');
-    });
-  });
-});

package/src/workers/pid-file.ts

@@ -1,82 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-/**
- * Result of a PID file delete operation.
- * Delete operations are best-effort and should not throw.
- */
-export interface PidFileResult {
-  success: boolean;
-  error?: Error;
-}
-
-/**
- * Context for PID file deletion - indicates when the delete is happening.
- * Used for logging/debugging purposes.
- */
-export type PidFileDeleteContext = 'sigterm' | 'success' | 'failure';
-
-/**
- * Write PID file - CRITICAL operation that must succeed.
- *
- * If the PID file cannot be written, the job cannot be cancelled through
- * the job management system. This is a critical failure and the job
- * should not proceed.
- *
- * @param pidFile - Absolute path to the PID file
- * @param pid - Process ID to write
- * @throws Error if PID file cannot be written
- */
-export function writePidFile(pidFile: string, pid: number): void {
-  try {
-    fs.writeFileSync(pidFile, pid.toString(), 'utf-8');
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `CRITICAL: Failed to write PID file ${pidFile}. ` +
-        `Job cannot be cancelled without PID file. ` +
-        `Original error: ${message}`
-    );
-  }
-}
-
-/**
- * Delete PID file - best-effort cleanup during shutdown.
- *
- * This operation should NEVER throw. During process shutdown (SIGTERM,
- * job success, job failure), failing to delete a PID file should not
- * prevent the process from exiting cleanly.
- *
- * Stale PID files are cleaned up by JobService.cleanupOldJobs().
- *
- * @param pidFile - Absolute path to the PID file
- * @param _context - Context indicating when the delete is happening (for future logging)
- * @returns Result indicating success or failure with error details
- */
-export function deletePidFile(pidFile: string, _context: PidFileDeleteContext): PidFileResult {
-  try {
-    fs.unlinkSync(pidFile);
-    return { success: true };
-  } catch (error) {
-    // ENOENT = file doesn't exist - that's success (nothing to delete)
-    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
-      return { success: true };
-    }
-    // Any other error = failure (permission denied, etc.)
-    return {
-      success: false,
-      error: error instanceof Error ? error : new Error(String(error)),
-    };
-  }
-}
-
-/**
- * Build the path to a PID file for a given job.
- *
- * @param jobsDir - Directory where job files are stored
- * @param jobId - Job identifier
- * @returns Absolute path to the PID file
- */
-export function buildPidFilePath(jobsDir: string, jobId: string): string {
-  return path.join(jobsDir, `${jobId}.pid`);
-}

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

@@ -1,194 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-
-// Mock child_process before importing spawn-worker
-const mockUnref = vi.fn();
-const mockOn = vi.fn();
-const mockSpawn = vi.fn(() => ({
-  unref: mockUnref,
-  on: mockOn,
-  pid: 12345,
-}));
-
-vi.mock('child_process', () => ({
-  spawn: mockSpawn,
-}));
-
-// Import after mocking
-const { spawnBackgroundWorker } = await import('./spawn-worker.js');
-
-describe('spawnBackgroundWorker', () => {
-  beforeEach(() => {
-    mockSpawn.mockClear();
-    mockUnref.mockClear();
-    mockOn.mockClear();
-  });
-
-  it('should use tsx in development mode (src folder)', () => {
-    spawnBackgroundWorker('test-job', '/test/data');
-
-    expect(mockSpawn).toHaveBeenCalledTimes(1);
-    const [command, args] = mockSpawn.mock.calls[0] as [string, string[], object];
-
-    // In development (src folder), should use npx tsx
-    expect(command).toBe('npx');
-    expect(args[0]).toBe('tsx');
-  });
-
-  it('should spawn a background worker process', () => {
-    spawnBackgroundWorker('test-job-id', '/test/data/dir');
-
-    expect(mockSpawn).toHaveBeenCalledTimes(1);
-    expect(mockUnref).toHaveBeenCalledTimes(1);
-  });
-
-  it('should pass job ID as argument', () => {
-    spawnBackgroundWorker('my-job-123', '/test/data/dir');
-
-    expect(mockSpawn).toHaveBeenCalledTimes(1);
-    const [, args] = mockSpawn.mock.calls[0] as [string, string[], object];
-
-    expect(args).toContain('my-job-123');
-  });
-
-  it('should spawn detached process with ignored stdio', () => {
-    spawnBackgroundWorker('test-job', '/test/data/dir');
-
-    expect(mockSpawn).toHaveBeenCalledTimes(1);
-    const [, , options] = mockSpawn.mock.calls[0] as [
-      string,
-      string[],
-      { detached: boolean; stdio: string },
-    ];
-
-    expect(options).toMatchObject({
-      detached: true,
-      stdio: 'ignore',
-    });
-  });
-
-  it('should pass environment variables including BLUERA_DATA_DIR', () => {
-    const dataDir = '/custom/data/directory';
-    spawnBackgroundWorker('test-job', dataDir);
-
-    expect(mockSpawn).toHaveBeenCalledTimes(1);
-    const [, , options] = mockSpawn.mock.calls[0] as [
-      string,
-      string[],
-      { env: Record<string, string> },
-    ];
-
-    expect(options.env).toMatchObject({
-      ...process.env,
-      BLUERA_DATA_DIR: dataDir,
-    });
-  });
-
-  it('should pass dataDir via BLUERA_DATA_DIR environment variable', () => {
-    const testDataDir = '.bluera/bluera-knowledge/data';
-    spawnBackgroundWorker('job-456', testDataDir);
-
-    expect(mockSpawn).toHaveBeenCalledTimes(1);
-    const [, , options] = mockSpawn.mock.calls[0] as [
-      string,
-      string[],
-      { env: Record<string, string> },
-    ];
-
-    expect(options.env.BLUERA_DATA_DIR).toBe(testDataDir);
-  });
-
-  it('should NOT set BLUERA_DATA_DIR when dataDir is undefined', () => {
-    spawnBackgroundWorker('test-job');
-
-    const [, , options] = mockSpawn.mock.calls[0] as [
-      string,
-      string[],
-      { env: Record<string, string> },
-    ];
-
-    expect(options.env).not.toHaveProperty('BLUERA_DATA_DIR');
-  });
-
-  it('should NOT set BLUERA_DATA_DIR when dataDir is empty string', () => {
-    spawnBackgroundWorker('test-job', '');
-
-    const [, , options] = mockSpawn.mock.calls[0] as [
-      string,
-      string[],
-      { env: Record<string, string> },
-    ];
-
-    expect(options.env).not.toHaveProperty('BLUERA_DATA_DIR');
-  });
-});
-
-// Test production mode with separate import to get fresh module
-describe('spawnBackgroundWorker (production mode)', () => {
-  const mockUnrefProd = vi.fn();
-  const mockOnProd = vi.fn();
-  const mockSpawnProd = vi.fn(() => ({
-    unref: mockUnrefProd,
-    on: mockOnProd,
-    pid: 12345,
-  }));
-
-  beforeEach(() => {
-    vi.resetModules();
-    mockSpawnProd.mockClear();
-    mockUnrefProd.mockClear();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('should use Node.js directly in production mode (dist folder)', async () => {
-    // Mock child_process
-    vi.doMock('child_process', () => ({
-      spawn: mockSpawnProd,
-    }));
-
-    // Mock url module to return a path containing /dist/
-    vi.doMock('url', () => ({
-      fileURLToPath: () => '/app/dist/workers/spawn-worker.js',
-    }));
-
-    // Import fresh module with production path
-    const { spawnBackgroundWorker: spawnProd } = await import('./spawn-worker.js');
-
-    spawnProd('test-job', '/test/data');
-
-    expect(mockSpawnProd).toHaveBeenCalledTimes(1);
-    const [command, args] = mockSpawnProd.mock.calls[0] as [string, string[]];
-
-    // In production (dist folder), should use Node.js directly
-    expect(command).toBe(process.execPath);
-    expect(args[0]).toContain('background-worker-cli.js');
-    expect(args[1]).toBe('test-job');
-  });
-
-  it('should correctly calculate worker path when bundled in chunk file (dist root)', async () => {
-    // Mock child_process
-    vi.doMock('child_process', () => ({
-      spawn: mockSpawnProd,
-    }));
-
-    // Mock url module to return a CHUNK file path in dist root (the bug case)
-    vi.doMock('url', () => ({
-      fileURLToPath: () => '/app/dist/chunk-ABC123.js',
-    }));
-
-    // Import fresh module with chunk path
-    const { spawnBackgroundWorker: spawnChunk } = await import('./spawn-worker.js');
-
-    spawnChunk('test-job', '/test/data');
-
-    expect(mockSpawnProd).toHaveBeenCalledTimes(1);
-    const [command, args] = mockSpawnProd.mock.calls[0] as [string, string[]];
-
-    // Should still correctly point to dist/workers/background-worker-cli.js
-    expect(command).toBe(process.execPath);
-    expect(args[0]).toBe('/app/dist/workers/background-worker-cli.js');
-    expect(args[1]).toBe('test-job');
-  });
-});

package/src/workers/spawn-worker.ts

@@ -1,70 +0,0 @@
-import { spawn } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { createLogger } from '../logging/index.js';
-
-const logger = createLogger('spawn-worker');
-
-/**
- * Spawn a background worker process to execute a job
- *
- * The worker runs detached from the parent process, allowing the
- * parent to exit while the worker continues running.
- *
- * @param jobId - The ID of the job to execute
- * @param dataDir - Optional data directory (uses default if undefined)
- */
-export function spawnBackgroundWorker(jobId: string, dataDir?: string): void {
-  // Determine the worker script path
-  // In production, this will be the compiled dist file
-  // In development, we need to use tsx to run TypeScript
-  const currentFilePath = fileURLToPath(import.meta.url);
-  const currentDir = path.dirname(currentFilePath);
-
-  // Check if we're running from dist (production) or src (development)
-  // Note: In bundled code, import.meta.url may point to a chunk file in dist root
-  const isProduction = currentFilePath.includes('/dist/');
-
-  let command: string;
-  let args: string[];
-
-  if (isProduction) {
-    // Production: Use Node.js directly with compiled file
-    // When bundled, the chunk may be in dist/ root, but worker CLI is in dist/workers/
-    // Find the dist directory and construct the correct path
-    const distIndex = currentFilePath.indexOf('/dist/');
-    const distDir = currentFilePath.substring(0, distIndex + 6); // includes '/dist/'
-    const workerScript = path.join(distDir, 'workers', 'background-worker-cli.js');
-    command = process.execPath; // Use the same Node.js binary
-    args = [workerScript, jobId];
-    logger.debug({ workerScript, distDir, currentFilePath }, 'Production worker path');
-  } else {
-    // Development: Use tsx to run TypeScript directly
-    const workerScript = path.join(currentDir, 'background-worker-cli.ts');
-    command = 'npx';
-    args = ['tsx', workerScript, jobId];
-    logger.debug({ workerScript, currentDir }, 'Development worker path');
-  }
-
-  logger.info({ jobId, command, args, dataDir, isProduction }, 'Spawning background worker');
-
-  // Spawn the worker process
-  const worker = spawn(command, args, {
-    detached: true, // Detach from parent process
-    stdio: 'ignore', // Don't pipe stdio (fully independent)
-    env: {
-      ...process.env, // Inherit environment variables
-      ...(dataDir !== undefined && dataDir !== '' ? { BLUERA_DATA_DIR: dataDir } : {}), // Only set if provided
-    },
-  });
-
-  // Handle spawn errors
-  worker.on('error', (err) => {
-    logger.error({ jobId, error: err.message }, 'Failed to spawn background worker');
-  });
-
-  logger.info({ jobId, pid: worker.pid }, 'Background worker spawned');
-
-  // Unref the worker so the parent can exit
-  worker.unref();
-}

package/tests/analysis/ast-parser.test.ts

@@ -1,98 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { ASTParser } from '../../src/analysis/ast-parser.js';
-
-describe('ASTParser', () => {
-  it('should extract functions from TypeScript code', () => {
-    const code = `
-export async function validateToken(token: string): Promise<boolean> {
-  return token.length > 0;
-}
-
-function helperFunction() {
-  return true;
-}
-`;
-
-    const parser = new ASTParser();
-    const nodes = parser.parse(code, 'typescript');
-
-    expect(nodes).toHaveLength(2);
-    expect(nodes[0]?.type).toBe('function');
-    expect(nodes[0]?.name).toBe('validateToken');
-    expect(nodes[0]?.exported).toBe(true);
-    expect(nodes[0]?.async).toBe(true);
-    expect(nodes[1]?.name).toBe('helperFunction');
-    expect(nodes[1]?.exported).toBe(false);
-  });
-
-  it('should extract classes with methods', () => {
-    const code = `
-export class UserService {
-  constructor(private repo: UserRepo) {}
-
-  async create(data: CreateUserData): Promise<User> {
-    return this.repo.save(data);
-  }
-
-  delete(id: string): void {
-    this.repo.delete(id);
-  }
-}
-`;
-
-    const parser = new ASTParser();
-    const nodes = parser.parse(code, 'typescript');
-
-    const classNode = nodes.find((n) => n.type === 'class');
-    expect(classNode).toBeDefined();
-    expect(classNode?.name).toBe('UserService');
-    expect(classNode?.methods).toHaveLength(3); // constructor + create + delete
-  });
-
-  it('should extract imports', () => {
-    const code = `
-import { User } from './models/user.js';
-import type { Repository } from '../types.js';
-import express from 'express';
-`;
-
-    const parser = new ASTParser();
-    const imports = parser.extractImports(code);
-
-    expect(imports).toHaveLength(3);
-    expect(imports[0]?.source).toBe('./models/user.js');
-    expect(imports[0]?.specifiers).toContain('User');
-    expect(imports[2]?.specifiers).toContain('express');
-  });
-
-  it('should extract correct line numbers', () => {
-    const code = `
-export function foo() {
-  return true;
-}
-
-class Bar {
-  method() {}
-}`;
-
-    const parser = new ASTParser();
-    const nodes = parser.parse(code, 'typescript');
-
-    const fooNode = nodes.find((n) => n.name === 'foo');
-    expect(fooNode?.startLine).toBe(2);
-    expect(fooNode?.endLine).toBe(4);
-
-    const barNode = nodes.find((n) => n.name === 'Bar');
-    expect(barNode?.startLine).toBe(6);
-    expect(barNode?.endLine).toBe(8);
-  });
-
-  it('should handle malformed code gracefully', () => {
-    const code = 'function broken(';
-
-    const parser = new ASTParser();
-    const nodes = parser.parse(code, 'typescript');
-
-    expect(nodes).toEqual([]);
-  });
-});

package/tests/analysis/code-graph.test.ts

@@ -1,60 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { CodeGraph } from '../../src/analysis/code-graph.js';
-import type { CodeNode } from '../../src/analysis/ast-parser.js';
-
-describe('CodeGraph', () => {
-  it('should build graph from code nodes', () => {
-    const nodes: CodeNode[] = [
-      {
-        type: 'function',
-        name: 'validateToken',
-        exported: true,
-        startLine: 1,
-        endLine: 5,
-      },
-      {
-        type: 'function',
-        name: 'parseToken',
-        exported: false,
-        startLine: 7,
-        endLine: 10,
-      },
-    ];
-
-    const graph = new CodeGraph();
-    graph.addNodes(nodes, 'src/auth.ts');
-
-    expect(graph.getNode('src/auth.ts:validateToken')).toBeDefined();
-    expect(graph.getNode('src/auth.ts:parseToken')).toBeDefined();
-  });
-
-  it('should track import relationships', () => {
-    const graph = new CodeGraph();
-
-    graph.addImport('src/controllers/user.ts', './services/user.js', ['UserService']);
-
-    const edges = graph.getEdges('src/controllers/user.ts');
-    expect(edges).toHaveLength(1);
-    expect(edges[0]?.type).toBe('imports');
-    expect(edges[0]?.to).toContain('UserService');
-  });
-
-  it('should detect call relationships from code', () => {
-    const code = `
-export function handler(req) {
-  const valid = validateToken(req.token);
-  if (!valid) return error();
-  return success();
-}
-`;
-
-    const graph = new CodeGraph();
-    graph.analyzeCallRelationships(code, 'src/handler.ts', 'handler');
-
-    const edges = graph.getEdges('src/handler.ts:handler');
-    const callEdges = edges.filter((e) => e.type === 'calls');
-
-    expect(callEdges.length).toBeGreaterThan(0);
-    expect(callEdges.some((e) => e.to.includes('validateToken'))).toBe(true);
-  });
-});