bluera-knowledge 0.9.21

package/src/cli/commands/search.ts

@@ -0,0 +1,113 @@
+import { Command } from 'commander';
+import { createServices, destroyServices } from '../../services/index.js';
+import type { GlobalOptions } from '../program.js';
+import type { SearchMode, DetailLevel } from '../../types/search.js';
+
+export function createSearchCommand(getOptions: () => GlobalOptions): Command {
+  const search = new Command('search')
+    .description('Search indexed documents using vector similarity + full-text matching')
+    .argument('<query>', 'Search query')
+    .option('-s, --stores <stores>', 'Limit search to specific stores (comma-separated IDs or names)')
+    .option('-m, --mode <mode>', 'vector (embeddings only), fts (text only), hybrid (both, default)', 'hybrid')
+    .option('-n, --limit <count>', 'Maximum results to return (default: 10)', '10')
+    .option('-t, --threshold <score>', 'Minimum score 0-1; omit low-relevance results')
+    .option('--include-content', 'Show full document content, not just preview snippet')
+    .option('--detail <level>', 'Context detail: minimal, contextual, full (default: minimal)', 'minimal')
+    .action(async (query: string, options: {
+      stores?: string;
+      mode?: SearchMode;
+      limit?: string;
+      threshold?: string;
+      includeContent?: boolean;
+      detail?: DetailLevel;
+    }) => {
+      const globalOpts = getOptions();
+      const services = await createServices(globalOpts.config, globalOpts.dataDir);
+      try {
+        // Get store IDs
+        let storeIds = (await services.store.list()).map((s) => s.id);
+
+        if (options.stores !== undefined) {
+          const requestedStores = options.stores.split(',').map((s) => s.trim());
+          const resolvedStores = [];
+
+          for (const requested of requestedStores) {
+            const store = await services.store.getByIdOrName(requested);
+            if (store !== undefined) {
+              resolvedStores.push(store.id);
+            } else {
+              console.error(`Error: Store not found: ${requested}`);
+              process.exit(3);
+            }
+          }
+
+          storeIds = resolvedStores;
+        }
+
+        if (storeIds.length === 0) {
+          console.error('No stores to search. Create a store first.');
+          process.exit(1);
+        }
+
+        // Initialize LanceDB for each store
+        for (const storeId of storeIds) {
+          await services.lance.initialize(storeId);
+        }
+
+        const results = await services.search.search({
+          query,
+          stores: storeIds,
+          mode: options.mode ?? 'hybrid',
+          limit: parseInt(options.limit ?? '10', 10),
+          threshold: options.threshold !== undefined ? parseFloat(options.threshold) : undefined,
+          includeContent: options.includeContent,
+          detail: options.detail ?? 'minimal',
+        });
+
+        if (globalOpts.format === 'json') {
+          console.log(JSON.stringify(results, null, 2));
+        } else if (globalOpts.quiet === true) {
+          // Quiet mode: just list matching paths/URLs, one per line
+          for (const r of results.results) {
+            const path = r.metadata.path ?? r.metadata.url ?? 'unknown';
+            console.log(path);
+          }
+        } else {
+          console.log(`\nSearch: "${query}"`);
+          console.log(`Mode: ${results.mode} | Detail: ${String(options.detail)} | Stores: ${String(results.stores.length)} | Results: ${String(results.totalResults)} | Time: ${String(results.timeMs)}ms\n`);
+
+          if (results.results.length === 0) {
+            console.log('No results found.\n');
+          } else {
+            for (let i = 0; i < results.results.length; i++) {
+              const r = results.results[i];
+              if (r === undefined) continue;
+
+              if (r.summary) {
+                console.log(`${String(i + 1)}. [${r.score.toFixed(2)}] ${r.summary.type}: ${r.summary.name}`);
+                console.log(`   ${r.summary.location}`);
+                console.log(`   ${r.summary.purpose}`);
+
+                if (r.context && options.detail !== 'minimal') {
+                  console.log(`   Imports: ${r.context.keyImports.slice(0, 3).join(', ')}`);
+                  console.log(`   Related: ${r.context.relatedConcepts.slice(0, 3).join(', ')}`);
+                }
+
+                console.log();
+              } else {
+                // Fallback to old format
+                const path = r.metadata.path ?? r.metadata.url ?? 'unknown';
+                console.log(`${String(i + 1)}. [${r.score.toFixed(2)}] ${path}`);
+                const preview = r.highlight ?? r.content.slice(0, 150).replace(/\n/g, ' ') + (r.content.length > 150 ? '...' : '');
+                console.log(`   ${preview}\n`);
+              }
+            }
+          }
+        }
+      } finally {
+        await destroyServices(services);
+      }
+    });
+
+  return search;
+}

package/src/cli/commands/serve.test.ts

@@ -0,0 +1,329 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createServeCommand } from './serve.js';
+import type { GlobalOptions } from '../program.js';
+import type { ServiceContainer } from '../../services/index.js';
+
+// Mock all dependencies
+vi.mock('../../services/index.js', () => ({
+  createServices: vi.fn(),
+  destroyServices: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('@hono/node-server', () => ({
+  serve: vi.fn()
+}));
+
+vi.mock('../../server/app.js', () => ({
+  createApp: vi.fn()
+}));
+
+describe('Serve Command - Execution Tests', () => {
+  let mockServices: ServiceContainer;
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+  const getOptions = (): GlobalOptions => ({
+    config: undefined,
+    dataDir: '/tmp/test-data',
+    quiet: false,
+    format: undefined,
+  });
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    const { createServices } = await import('../../services/index.js');
+    const { createApp } = await import('../../server/app.js');
+    const { serve } = await import('@hono/node-server');
+
+    mockServices = {
+      store: {
+        list: vi.fn(),
+        getByIdOrName: vi.fn(),
+        create: vi.fn(),
+        delete: vi.fn()
+      },
+      lance: {
+        initialize: vi.fn()
+      },
+      search: {
+        search: vi.fn()
+      },
+      index: {
+        indexStore: vi.fn()
+      }
+    } as unknown as ServiceContainer;
+
+    vi.mocked(createServices).mockResolvedValue(mockServices);
+    vi.mocked(createApp).mockReturnValue({ fetch: vi.fn() } as any);
+    vi.mocked(serve).mockReturnValue(undefined as any);
+
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('server initialization', () => {
+    it('starts server with default port and host', async () => {
+      const { createServices } = await import('../../services/index.js');
+      const { createApp } = await import('../../server/app.js');
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(createServices).toHaveBeenCalledWith(undefined, '/tmp/test-data');
+      expect(createApp).toHaveBeenCalledWith(mockServices);
+      expect(serve).toHaveBeenCalledWith({
+        fetch: expect.any(Function),
+        port: 3847,
+        hostname: '127.0.0.1'
+      });
+    });
+
+    it('starts server with custom port', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '8080']);
+      await actionHandler([]);
+
+      expect(serve).toHaveBeenCalledWith(
+        expect.objectContaining({
+          port: 8080,
+          hostname: '127.0.0.1'
+        })
+      );
+    });
+
+    it('starts server with custom host', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--host', '0.0.0.0']);
+      await actionHandler([]);
+
+      expect(serve).toHaveBeenCalledWith(
+        expect.objectContaining({
+          port: 3847,
+          hostname: '0.0.0.0'
+        })
+      );
+    });
+
+    it('starts server with custom port and host', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '9000', '--host', '0.0.0.0']);
+      await actionHandler([]);
+
+      expect(serve).toHaveBeenCalledWith(
+        expect.objectContaining({
+          port: 9000,
+          hostname: '0.0.0.0'
+        })
+      );
+    });
+
+    it('uses short option -p for port', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '5000']);
+      await actionHandler([]);
+
+      expect(serve).toHaveBeenCalledWith(
+        expect.objectContaining({
+          port: 5000
+        })
+      );
+    });
+  });
+
+  describe('service configuration', () => {
+    it('creates services with global config', async () => {
+      const { createServices } = await import('../../services/index.js');
+
+      const customGetOptions = (): GlobalOptions => ({
+        config: '/custom/config.json',
+        dataDir: '/custom/data',
+        quiet: false,
+        format: undefined,
+      });
+
+      const command = createServeCommand(customGetOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(createServices).toHaveBeenCalledWith('/custom/config.json', '/custom/data');
+    });
+
+    it('creates app with service container', async () => {
+      const { createApp } = await import('../../server/app.js');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(createApp).toHaveBeenCalledWith(mockServices);
+    });
+
+    it('passes app fetch to serve', async () => {
+      const { createApp } = await import('../../server/app.js');
+      const { serve } = await import('@hono/node-server');
+
+      const mockFetch = vi.fn();
+      vi.mocked(createApp).mockReturnValue({ fetch: mockFetch } as any);
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(serve).toHaveBeenCalledWith(
+        expect.objectContaining({
+          fetch: mockFetch
+        })
+      );
+    });
+  });
+
+  describe('console output', () => {
+    it('logs server startup with default settings', async () => {
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Starting server on http://127.0.0.1:3847'
+      );
+    });
+
+    it('logs server startup with custom port', async () => {
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '8080']);
+      await actionHandler([]);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Starting server on http://127.0.0.1:8080'
+      );
+    });
+
+    it('logs server startup with custom host', async () => {
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--host', '0.0.0.0']);
+      await actionHandler([]);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Starting server on http://0.0.0.0:3847'
+      );
+    });
+
+    it('logs server startup with both custom port and host', async () => {
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '9000', '--host', '192.168.1.1']);
+      await actionHandler([]);
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        'Starting server on http://192.168.1.1:9000'
+      );
+    });
+  });
+
+  describe('port parsing', () => {
+    it('parses port as integer', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '8080']);
+      await actionHandler([]);
+
+      const serveCall = vi.mocked(serve).mock.calls[0]?.[0];
+      expect(typeof serveCall?.port).toBe('number');
+      expect(serveCall?.port).toBe(8080);
+    });
+
+    it('handles invalid port gracefully', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', 'invalid']);
+      await actionHandler([]);
+
+      const serveCall = vi.mocked(serve).mock.calls[0]?.[0];
+      // Should parse to NaN, which is still a number
+      expect(typeof serveCall?.port).toBe('number');
+    });
+
+    it('handles port as floating point by converting to integer', async () => {
+      const { serve } = await import('@hono/node-server');
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      command.parseOptions(['--port', '8080.5']);
+      await actionHandler([]);
+
+      const serveCall = vi.mocked(serve).mock.calls[0]?.[0];
+      expect(serveCall?.port).toBe(8080);
+    });
+  });
+
+  describe('execution order', () => {
+    it('creates services before creating app', async () => {
+      const { createServices } = await import('../../services/index.js');
+      const { createApp } = await import('../../server/app.js');
+
+      const callOrder: string[] = [];
+
+      vi.mocked(createServices).mockImplementation(async () => {
+        callOrder.push('createServices');
+        return mockServices;
+      });
+
+      vi.mocked(createApp).mockImplementation(() => {
+        callOrder.push('createApp');
+        return { fetch: vi.fn() } as any;
+      });
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(callOrder).toEqual(['createServices', 'createApp']);
+    });
+
+    it('creates app before starting server', async () => {
+      const { createApp } = await import('../../server/app.js');
+      const { serve } = await import('@hono/node-server');
+
+      const callOrder: string[] = [];
+
+      vi.mocked(createApp).mockImplementation(() => {
+        callOrder.push('createApp');
+        return { fetch: vi.fn() } as any;
+      });
+
+      vi.mocked(serve).mockImplementation(() => {
+        callOrder.push('serve');
+        return undefined as any;
+      });
+
+      const command = createServeCommand(getOptions);
+      const actionHandler = (command as any)._actionHandler;
+      await actionHandler([]);
+
+      expect(callOrder).toEqual(['createApp', 'serve']);
+    });
+  });
+});

package/src/cli/commands/serve.ts

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import { serve } from '@hono/node-server';
+import { createServices } from '../../services/index.js';
+import { createApp } from '../../server/app.js';
+import type { GlobalOptions } from '../program.js';
+
+export function createServeCommand(getOptions: () => GlobalOptions): Command {
+  return new Command('serve')
+    .description('Start HTTP API server for programmatic search access')
+    .option('-p, --port <port>', 'Port to listen on (default: 3847)', '3847')
+    .option('--host <host>', 'Bind address (default: 127.0.0.1, use 0.0.0.0 for all interfaces)', '127.0.0.1')
+    .action(async (options: { port?: string; host?: string }) => {
+      const globalOpts = getOptions();
+      const services = await createServices(globalOpts.config, globalOpts.dataDir);
+      const app = createApp(services);
+
+      const port = parseInt(options.port ?? '3847', 10);
+      const host = options.host ?? '127.0.0.1';
+
+      console.log(`Starting server on http://${host}:${String(port)}`);
+
+      serve({
+        fetch: app.fetch,
+        port,
+        hostname: host,
+      });
+    });
+}