bluera-knowledge 0.12.6 → 0.12.8

package/dist/index.js

@@ -7,10 +7,10 @@ import {
   isWebStoreDefinition,
   runMCPServer,
   spawnBackgroundWorker
-} from "./chunk-CC6EGZ4D.js";
+} from "./chunk-PDGOW3CH.js";
 import {
   IntelligentCrawler
-} from "./chunk-QCSFBMYW.js";
+} from "./chunk-BMY3BWB6.js";
 import {
   ASTParser,
   AdapterRegistry,
@@ -24,7 +24,7 @@ import {
   err,
   extractRepoName,
   ok
-} from "./chunk-C4SYGLAI.js";
+} from "./chunk-RISACKN5.js";
 import "./chunk-HRQD3MPH.js";
 
 // src/index.ts

package/dist/mcp/server.js

@@ -1,8 +1,8 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-CC6EGZ4D.js";
-import "../chunk-C4SYGLAI.js";
+} from "../chunk-PDGOW3CH.js";
+import "../chunk-RISACKN5.js";
 import "../chunk-HRQD3MPH.js";
 export {
   createMCPServer,

package/dist/workers/background-worker-cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   IntelligentCrawler
-} from "../chunk-QCSFBMYW.js";
+} from "../chunk-BMY3BWB6.js";
 import {
   JobService,
   createDocumentId,
@@ -9,7 +9,7 @@ import {
   createServices,
   createStoreId,
   shutdownLogger
-} from "../chunk-C4SYGLAI.js";
+} from "../chunk-RISACKN5.js";
 import "../chunk-HRQD3MPH.js";
 
 // src/workers/background-worker.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/src/db/lance.ts

@@ -1,5 +1,6 @@
 import * as lancedb from '@lancedb/lancedb';
 import { createDocumentId } from '../types/brands.js';
+import { DocumentMetadataSchema } from '../types/document.js';
 import type { StoreId, DocumentId } from '../types/brands.js';
 import type { Document, DocumentMetadata } from '../types/document.js';
 import type { Table, Connection } from '@lancedb/lancedb';
@@ -88,13 +89,17 @@ export class LanceStore {
 
     // Return all results - threshold filtering is applied after score normalization
     // in search.service.ts to match displayed scores
-    return results.map((r) => ({
-      id: createDocumentId(r.id),
-      content: r.content,
-      score: 1 - r._distance,
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      metadata: JSON.parse(r.metadata) as DocumentMetadata,
-    }));
+    return results.map((r) => {
+      const metadata = DocumentMetadataSchema.parse(JSON.parse(r.metadata));
+      return {
+        id: createDocumentId(r.id),
+        content: r.content,
+        score: 1 - r._distance,
+        // Schema validates structure, cast to branded type
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        metadata: metadata as DocumentMetadata,
+      };
+    });
   }
 
   async createFtsIndex(storeId: StoreId): Promise<void> {
@@ -121,13 +126,17 @@ export class LanceStore {
       _score: number;
     }>;
 
-    return results.map((r) => ({
-      id: createDocumentId(r.id),
-      content: r.content,
-      score: r._score,
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      metadata: JSON.parse(r.metadata) as DocumentMetadata,
-    }));
+    return results.map((r) => {
+      const metadata = DocumentMetadataSchema.parse(JSON.parse(r.metadata));
+      return {
+        id: createDocumentId(r.id),
+        content: r.content,
+        score: r._score,
+        // Schema validates structure, cast to branded type
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        metadata: metadata as DocumentMetadata,
+      };
+    });
   }
 
   async deleteStore(storeId: StoreId): Promise<void> {

package/src/mcp/handlers/store.handler.ts

@@ -157,8 +157,8 @@ export const handleCreateStore: ToolHandler<CreateStoreArgs> = async (
     message: `Indexing ${result.data.name}...`,
   });
 
-  // Spawn background worker (dataDir defaults to project-local .bluera if undefined)
-  spawnBackgroundWorker(job.id, options.dataDir ?? '');
+  // Spawn background worker
+  spawnBackgroundWorker(job.id, options.dataDir);
 
   return {
     content: [
@@ -223,8 +223,8 @@ export const handleIndexStore: ToolHandler<IndexStoreArgs> = async (
     message: `Re-indexing ${store.name}...`,
   });
 
-  // Spawn background worker (dataDir defaults to project-local .bluera if undefined)
-  spawnBackgroundWorker(job.id, options.dataDir ?? '');
+  // Spawn background worker
+  spawnBackgroundWorker(job.id, options.dataDir);
 
   return {
     content: [

package/src/services/job.service.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'crypto';
 import fs from 'fs';
 import path from 'path';
+import { JobSchema } from '../types/job.js';
 import { Result, ok, err } from '../types/result.js';
 import type { Job, CreateJobParams, UpdateJobParams, JobStatus } from '../types/job.js';
 
@@ -90,8 +91,7 @@ export class JobService {
 
     try {
       const content = fs.readFileSync(jobFile, 'utf-8');
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      return JSON.parse(content) as Job;
+      return JobSchema.parse(JSON.parse(content));
     } catch (error) {
       throw new Error(
         `Failed to read job ${jobId}: ${error instanceof Error ? error.message : String(error)}`
@@ -117,8 +117,7 @@ export class JobService {
 
       try {
         const content = fs.readFileSync(path.join(this.jobsDir, file), 'utf-8');
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-        const job = JSON.parse(content) as Job;
+        const job = JobSchema.parse(JSON.parse(content));
 
         if (statusFilter !== undefined) {
           const filters = Array.isArray(statusFilter) ? statusFilter : [statusFilter];

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

@@ -538,6 +538,30 @@ describe('StoreService', () => {
 
       await rm(corruptDir, { recursive: true, force: true });
     });
+
+    it('filters out null entries from stores array on load', async () => {
+      const nullDir = await mkdtemp(join(tmpdir(), 'null-entry-'));
+      const registryPath = join(nullDir, 'stores.json');
+      const validStore = {
+        id: 'test-id',
+        type: 'file',
+        name: 'valid-store',
+        path: '/some/path',
+        status: 'ready',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      await writeFile(registryPath, JSON.stringify({ stores: [null, validStore, null] }));
+
+      const freshService = new StoreService(nullDir);
+      await freshService.initialize();
+
+      const stores = await freshService.list();
+      expect(stores).toHaveLength(1);
+      expect(stores[0]?.name).toBe('valid-store');
+
+      await rm(nullDir, { recursive: true, force: true });
+    });
   });
 
   describe('store definition auto-update', () => {

package/src/services/store.service.ts

@@ -218,6 +218,12 @@ export class StoreService {
           updatedAt: now,
         } satisfies WebStore;
         break;
+
+      default: {
+        // Exhaustive check - if this is reached, input.type is invalid
+        const invalidType: never = input.type;
+        return err(new Error(`Invalid store type: ${String(invalidType)}`));
+      }
     }
 
     this.registry.stores.push(store);
@@ -332,14 +338,16 @@ export class StoreService {
     const content = await readFile(registryPath, 'utf-8');
     try {
       // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-      const data = JSON.parse(content) as { stores: Store[] };
+      const data = JSON.parse(content) as { stores: (Store | null)[] };
       this.registry = {
-        stores: data.stores.map((s) => ({
-          ...s,
-          id: createStoreId(s.id),
-          createdAt: new Date(s.createdAt),
-          updatedAt: new Date(s.updatedAt),
-        })),
+        stores: data.stores
+          .filter((s): s is Store => s !== null)
+          .map((s) => ({
+            ...s,
+            id: createStoreId(s.id),
+            createdAt: new Date(s.createdAt),
+            updatedAt: new Date(s.updatedAt),
+          })),
       };
     } catch (error) {
       throw new Error(

package/src/types/document.ts

@@ -1,6 +1,30 @@
+import { z } from 'zod';
 import type { DocumentId, StoreId } from './brands.js';
 
-export type DocumentType = 'file' | 'chunk' | 'web';
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+export const DocumentTypeSchema = z.enum(['file', 'chunk', 'web']);
+
+export const DocumentMetadataSchema = z
+  .object({
+    path: z.string().optional(),
+    url: z.string().optional(),
+    type: DocumentTypeSchema,
+    storeId: z.string(),
+    indexedAt: z.union([z.string(), z.date()]),
+    fileHash: z.string().optional(),
+    chunkIndex: z.number().optional(),
+    totalChunks: z.number().optional(),
+  })
+  .loose(); // Allow additional fields per index signature
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DocumentType = z.infer<typeof DocumentTypeSchema>;
 
 export interface DocumentMetadata {
   readonly path?: string | undefined;

package/src/types/job.ts

@@ -1,36 +1,51 @@
-export type JobType = 'clone' | 'index' | 'crawl';
-export type JobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-
-export interface JobDetails {
-  storeName?: string;
-  storeId?: string;
-  url?: string;
-  path?: string;
-  filesProcessed?: number;
-  totalFiles?: number;
-  startedAt?: string;
-  completedAt?: string;
-  cancelledAt?: string;
-  error?: string;
+import { z } from 'zod';
+
+// ============================================================================
+// Zod Schemas
+// ============================================================================
+
+export const JobTypeSchema = z.enum(['clone', 'index', 'crawl']);
+export const JobStatusSchema = z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']);
+
+export const JobDetailsSchema = z.object({
+  storeName: z.string().optional(),
+  storeId: z.string().optional(),
+  url: z.string().optional(),
+  path: z.string().optional(),
+  filesProcessed: z.number().optional(),
+  totalFiles: z.number().optional(),
+  startedAt: z.string().optional(),
+  completedAt: z.string().optional(),
+  cancelledAt: z.string().optional(),
+  error: z.string().optional(),
   // Crawl-specific fields
-  crawlInstruction?: string;
-  extractInstruction?: string;
-  maxPages?: number;
-  simple?: boolean;
-  useHeadless?: boolean;
-  pagesCrawled?: number;
-}
+  crawlInstruction: z.string().optional(),
+  extractInstruction: z.string().optional(),
+  maxPages: z.number().optional(),
+  simple: z.boolean().optional(),
+  useHeadless: z.boolean().optional(),
+  pagesCrawled: z.number().optional(),
+});
 
-export interface Job {
-  id: string;
-  type: JobType;
-  status: JobStatus;
-  progress: number; // 0-100
-  message: string;
-  details: JobDetails;
-  createdAt: string;
-  updatedAt: string;
-}
+export const JobSchema = z.object({
+  id: z.string(),
+  type: JobTypeSchema,
+  status: JobStatusSchema,
+  progress: z.number().min(0).max(100),
+  message: z.string(),
+  details: JobDetailsSchema.default({}),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+// ============================================================================
+// Types (inferred from schemas)
+// ============================================================================
+
+export type JobType = z.infer<typeof JobTypeSchema>;
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+export type JobDetails = z.infer<typeof JobDetailsSchema>;
+export type Job = z.infer<typeof JobSchema>;
 
 export interface CreateJobParams {
   type: JobType;

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

@@ -59,7 +59,10 @@ describe('BackgroundWorker', () => {
         details: { storeId: 'test' },
       });
 
-      await expect(worker.executeJob(job.id)).rejects.toThrow('Unknown job type: unknown');
+      // Zod validation catches invalid job type when reading the job file
+      await expect(worker.executeJob(job.id)).rejects.toThrow(
+        /Invalid option.*clone.*index.*crawl/
+      );
     });
 
     it('should set job to running status before execution', async () => {

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

@@ -92,6 +92,30 @@ describe('spawnBackgroundWorker', () => {
 
     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

package/src/workers/spawn-worker.ts

@@ -9,8 +9,9 @@ import { fileURLToPath } from 'url';
  * 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 {
+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
@@ -40,7 +41,7 @@ export function spawnBackgroundWorker(jobId: string, dataDir: string): void {
     stdio: 'ignore', // Don't pipe stdio (fully independent)
     env: {
       ...process.env, // Inherit environment variables
-      BLUERA_DATA_DIR: dataDir, // Pass dataDir to worker
+      ...(dataDir !== undefined && dataDir !== '' ? { BLUERA_DATA_DIR: dataDir } : {}), // Only set if provided
     },
   });