viberag 0.3.2 → 0.4.0

package/dist/daemon/handlers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Daemon Method Handlers
+ *
+ * JSON-RPC method implementations for daemon IPC.
+ * Each handler receives params and a context with access to owner and server.
+ *
+ * Simplified for polling-based architecture:
+ * - Clients poll status() for state updates
+ * - No push notifications or subscriptions
+ */
+import type { HandlerRegistry } from './server.js';
+/**
+ * Create the handler registry.
+ */
+export declare function createHandlers(): HandlerRegistry;

package/dist/daemon/handlers.js

@@ -0,0 +1,157 @@
+/**
+ * Daemon Method Handlers
+ *
+ * JSON-RPC method implementations for daemon IPC.
+ * Each handler receives params and a context with access to owner and server.
+ *
+ * Simplified for polling-based architecture:
+ * - Clients poll status() for state updates
+ * - No push notifications or subscriptions
+ */
+import { z } from 'zod';
+import { PROTOCOL_VERSION } from './protocol.js';
+import { daemonState } from './state.js';
+// ============================================================================
+// Parameter Schemas
+// ============================================================================
+const searchParamsSchema = z.object({
+    query: z.string().min(1),
+    mode: z
+        .enum(['semantic', 'exact', 'hybrid', 'definition', 'similar'])
+        .optional(),
+    limit: z.number().min(1).max(100).optional(),
+    bm25Weight: z.number().min(0).max(1).optional(),
+    minScore: z.number().min(0).max(1).optional(),
+    filters: z.record(z.string(), z.unknown()).optional(),
+    codeSnippet: z.string().optional(),
+    symbolName: z.string().optional(),
+    autoBoost: z.boolean().optional(),
+    autoBoostThreshold: z.number().min(0).max(1).optional(),
+    returnDebug: z.boolean().optional(),
+});
+const indexParamsSchema = z.object({
+    force: z.boolean().optional(),
+});
+const ACTIVE_INDEX_STATUSES = new Set([
+    'initializing',
+    'scanning',
+    'chunking',
+    'embedding',
+]);
+const shutdownParamsSchema = z.object({
+    reason: z.string().optional(),
+});
+// ============================================================================
+// Handlers
+// ============================================================================
+/**
+ * Search handler.
+ */
+const searchHandler = async (params, ctx) => {
+    const validated = searchParamsSchema.parse(params ?? {});
+    const { query, ...options } = validated;
+    return ctx.owner.search(query, options);
+};
+/**
+ * Index handler.
+ * Simply runs indexing - clients poll status() for progress.
+ */
+const indexHandler = async (params, ctx) => {
+    const validated = indexParamsSchema.parse(params ?? {});
+    // Run indexing - Redux state is updated by indexer directly
+    // Clients poll status() to see progress
+    const stats = await ctx.owner.index({ force: validated.force });
+    return stats;
+};
+/**
+ * Index async handler.
+ * Starts indexing in the background and returns immediately.
+ * Clients poll status() to see progress and completion.
+ */
+const indexAsyncHandler = async (params, ctx) => {
+    const validated = indexParamsSchema.parse(params ?? {});
+    const currentStatus = daemonState.getSnapshot().indexing.status;
+    if (ACTIVE_INDEX_STATUSES.has(currentStatus)) {
+        return { started: false, reason: 'in_progress' };
+    }
+    void ctx.owner.index({ force: validated.force }).catch(error => {
+        console.error('[daemon] Async index failed:', error);
+        const logger = ctx.owner.getLogger();
+        if (logger) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            logger.error('DaemonServer', 'Async index failed', err);
+        }
+    });
+    return { started: true };
+};
+/**
+ * Status handler.
+ */
+const statusHandler = async (_params, ctx) => {
+    return ctx.owner.getStatus();
+};
+/**
+ * Watch status handler.
+ */
+const watchStatusHandler = async (_params, ctx) => {
+    return ctx.owner.getWatcherStatus();
+};
+/**
+ * Shutdown handler.
+ * Schedules server stop.
+ */
+const shutdownHandler = async (params, ctx) => {
+    const validated = shutdownParamsSchema.parse(params ?? {});
+    console.error(`[daemon] Shutdown requested: ${validated.reason ?? 'no reason'}`);
+    // Schedule shutdown after response is sent
+    setImmediate(async () => {
+        await ctx.owner.shutdown();
+        await ctx.server.stop();
+        process.exit(0);
+    });
+    return { success: true };
+};
+/**
+ * Ping handler.
+ * Simple health check.
+ */
+const pingHandler = async (_params, _ctx) => {
+    return {
+        pong: true,
+        timestamp: Date.now(),
+        protocolVersion: PROTOCOL_VERSION,
+    };
+};
+/**
+ * Health handler.
+ * Returns detailed health information.
+ */
+const healthHandler = async (_params, ctx) => {
+    const snapshot = daemonState.getSnapshot();
+    return {
+        healthy: true,
+        uptime: process.uptime(),
+        memoryUsage: process.memoryUsage(),
+        clients: ctx.server.getClientCount(),
+        indexStatus: snapshot.indexing.status,
+        protocolVersion: PROTOCOL_VERSION,
+    };
+};
+// ============================================================================
+// Handler Registry
+// ============================================================================
+/**
+ * Create the handler registry.
+ */
+export function createHandlers() {
+    return {
+        search: searchHandler,
+        index: indexHandler,
+        indexAsync: indexAsyncHandler,
+        status: statusHandler,
+        watchStatus: watchStatusHandler,
+        shutdown: shutdownHandler,
+        ping: pingHandler,
+        health: healthHandler,
+    };
+}

package/dist/daemon/index.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * VibeRAG Daemon Entry Point
+ *
+ * Single daemon per project, owns all mutable state.
+ * CLI and MCP connect as clients via Unix socket.
+ *
+ * Usage:
+ *   npx viberag-daemon
+ *
+ * The daemon uses the current working directory as the project root.
+ * It creates a socket at .viberag/daemon.sock and a PID file at .viberag/daemon.pid.
+ *
+ * The daemon will:
+ * - Acquire exclusive lock to prevent multiple instances
+ * - Start the file watcher for auto-indexing
+ * - Warm up the embedding provider
+ * - Listen for IPC requests (search, index, status, etc.)
+ * - Auto-shutdown after 5 minutes of idle (no connected clients)
+ */
+export {};

package/dist/daemon/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * VibeRAG Daemon Entry Point
+ *
+ * Single daemon per project, owns all mutable state.
+ * CLI and MCP connect as clients via Unix socket.
+ *
+ * Usage:
+ *   npx viberag-daemon
+ *
+ * The daemon uses the current working directory as the project root.
+ * It creates a socket at .viberag/daemon.sock and a PID file at .viberag/daemon.pid.
+ *
+ * The daemon will:
+ * - Acquire exclusive lock to prevent multiple instances
+ * - Start the file watcher for auto-indexing
+ * - Warm up the embedding provider
+ * - Listen for IPC requests (search, index, status, etc.)
+ * - Auto-shutdown after 5 minutes of idle (no connected clients)
+ */
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { DaemonOwner } from './owner.js';
+import { DaemonServer } from './server.js';
+import { LifecycleManager } from './lifecycle.js';
+import { createHandlers } from './handlers.js';
+import { configExists, loadConfig } from './lib/config.js';
+// Use current working directory as project root
+const projectRoot = process.cwd();
+// Lock file path - inside .viberag directory
+const LOCK_FILE_PATH = path.join(projectRoot, '.viberag', 'daemon.lock');
+// Lock release function - set when lock is acquired
+let releaseLock = null;
+/**
+ * Acquire exclusive daemon lock to prevent multiple instances.
+ * Uses proper-lockfile which is cross-platform and handles crash recovery.
+ */
+async function acquireDaemonLock() {
+    try {
+        const release = await lockfile.lock(projectRoot, {
+            lockfilePath: LOCK_FILE_PATH,
+            stale: 30000, // Lock is stale after 30s without mtime update
+            update: 10000, // Update mtime every 10s to prove liveness
+            retries: 0, // Fail immediately if locked
+            onCompromised: err => {
+                // Another process stole our lock (very rare edge case)
+                console.error('[daemon] Lock compromised:', err.message);
+                console.error('[daemon] Another daemon may have started. Exiting.');
+                process.exit(1);
+            },
+        });
+        console.error('[daemon] Acquired exclusive lock');
+        return release;
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ELOCKED') {
+            console.error('[daemon] Another daemon is already running');
+            console.error('[daemon] Only one daemon per project is allowed.');
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+/**
+ * Release the daemon lock on exit.
+ */
+function setupLockRelease(release) {
+    releaseLock = release;
+    // Release lock on clean exit
+    const cleanup = () => {
+        if (releaseLock) {
+            // Synchronous-ish cleanup - lockfile handles this gracefully
+            releaseLock().catch(() => { });
+            releaseLock = null;
+        }
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+}
+/**
+ * Main daemon entry point.
+ */
+async function main() {
+    console.error(`[daemon] Starting for ${projectRoot}`);
+    // Verify project is initialized (needed before lock since lock is in .viberag/)
+    if (!(await configExists(projectRoot))) {
+        console.error('[daemon] Project not initialized');
+        console.error('[daemon] Run "npx viberag" and use /init command to initialize.');
+        process.exit(1);
+    }
+    // Acquire exclusive lock BEFORE any other operations
+    // This prevents multiple daemons from running concurrently
+    const release = await acquireDaemonLock();
+    setupLockRelease(release);
+    // Load config
+    await loadConfig(projectRoot);
+    // Default idle timeout: 5 minutes (can be made configurable later)
+    const idleTimeoutMs = 5 * 60 * 1000;
+    // Create components
+    const owner = new DaemonOwner(projectRoot);
+    const server = new DaemonServer(owner);
+    const lifecycle = new LifecycleManager(server, owner, idleTimeoutMs);
+    // Register handlers
+    server.setHandlers(createHandlers());
+    // Initialize owner (starts watcher, begins warmup)
+    await owner.initialize();
+    // Start server
+    await server.start();
+    // Register signal handlers
+    lifecycle.registerSignalHandlers();
+    // Start idle timer (cancelled on first connect)
+    lifecycle.startInitialIdleTimer();
+    console.error(`[daemon] Ready`);
+    console.error(`[daemon] Socket: ${owner.getSocketPath()}`);
+    console.error(`[daemon] PID: ${process.pid}`);
+}
+// Run main with error handling
+main().catch(error => {
+    // Pass Error object directly to preserve stack trace (ADR-011)
+    console.error('[daemon] Fatal error:', error);
+    process.exit(1);
+});

package/dist/daemon/lib/chunker/bounded-channel.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bounded async channel with backpressure.
+ *
+ * Implements producer-consumer pattern where:
+ * - Producer blocks when buffer is full (backpressure)
+ * - Consumer blocks when buffer is empty
+ * - Provides memory-bounded streaming between async operations
+ *
+ * Used in indexing pipeline to decouple batch building from embedding.
+ */
+/**
+ * Bounded async channel for producer-consumer communication.
+ *
+ * @template T - Type of items in the channel
+ */
+export declare class BoundedChannel<T> {
+    private readonly capacity;
+    private buffer;
+    private closed;
+    private waitingPush;
+    private waitingPull;
+    /**
+     * Create a bounded channel.
+     * @param capacity - Maximum number of items in buffer (must be >= 1)
+     */
+    constructor(capacity: number);
+    /**
+     * Push an item to the channel.
+     * Blocks if buffer is full (backpressure).
+     *
+     * @throws Error if channel is closed
+     */
+    push(item: T): Promise<void>;
+    /**
+     * Pull an item from the channel.
+     * Blocks if buffer is empty.
+     * Returns null when channel is closed and empty.
+     */
+    pull(): Promise<T | null>;
+    /**
+     * Close the channel.
+     * Remaining items can still be pulled, but no new items can be pushed.
+     */
+    close(): void;
+    /** Current number of items in buffer */
+    get size(): number;
+    /** Whether channel is closed */
+    get isClosed(): boolean;
+    /** Maximum buffer capacity */
+    get maxCapacity(): number;
+}

package/dist/daemon/lib/chunker/bounded-channel.js

@@ -0,0 +1,138 @@
+/**
+ * Bounded async channel with backpressure.
+ *
+ * Implements producer-consumer pattern where:
+ * - Producer blocks when buffer is full (backpressure)
+ * - Consumer blocks when buffer is empty
+ * - Provides memory-bounded streaming between async operations
+ *
+ * Used in indexing pipeline to decouple batch building from embedding.
+ */
+/**
+ * Bounded async channel for producer-consumer communication.
+ *
+ * @template T - Type of items in the channel
+ */
+export class BoundedChannel {
+    /**
+     * Create a bounded channel.
+     * @param capacity - Maximum number of items in buffer (must be >= 1)
+     */
+    constructor(capacity) {
+        Object.defineProperty(this, "capacity", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: capacity
+        });
+        Object.defineProperty(this, "buffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "waitingPush", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "waitingPull", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        if (capacity < 1) {
+            throw new Error('BoundedChannel capacity must be >= 1');
+        }
+    }
+    /**
+     * Push an item to the channel.
+     * Blocks if buffer is full (backpressure).
+     *
+     * @throws Error if channel is closed
+     */
+    async push(item) {
+        if (this.closed) {
+            throw new Error('Cannot push to closed channel');
+        }
+        // If there's a waiting consumer, deliver directly
+        const consumer = this.waitingPull.shift();
+        if (consumer) {
+            consumer.resolve(item);
+            return;
+        }
+        // If buffer has space, add to it
+        if (this.buffer.length < this.capacity) {
+            this.buffer.push(item);
+            return;
+        }
+        // Buffer full - wait for space (backpressure)
+        await new Promise((resolve, reject) => {
+            this.waitingPush.push({ resolve, reject });
+        });
+        // After waking, add to buffer
+        this.buffer.push(item);
+    }
+    /**
+     * Pull an item from the channel.
+     * Blocks if buffer is empty.
+     * Returns null when channel is closed and empty.
+     */
+    async pull() {
+        // If buffer has items, return one
+        if (this.buffer.length > 0) {
+            const item = this.buffer.shift();
+            // Wake a waiting producer
+            const producer = this.waitingPush.shift();
+            if (producer) {
+                producer.resolve();
+            }
+            return item;
+        }
+        // If closed and empty, return null (signal completion)
+        if (this.closed) {
+            return null;
+        }
+        // Wait for item
+        return new Promise(resolve => {
+            this.waitingPull.push({ resolve });
+        });
+    }
+    /**
+     * Close the channel.
+     * Remaining items can still be pulled, but no new items can be pushed.
+     */
+    close() {
+        this.closed = true;
+        // Reject all waiting producers
+        for (const producer of this.waitingPush) {
+            producer.reject(new Error('Channel closed'));
+        }
+        this.waitingPush = [];
+        // Resolve all waiting consumers with null
+        for (const consumer of this.waitingPull) {
+            consumer.resolve(null);
+        }
+        this.waitingPull = [];
+    }
+    /** Current number of items in buffer */
+    get size() {
+        return this.buffer.length;
+    }
+    /** Whether channel is closed */
+    get isClosed() {
+        return this.closed;
+    }
+    /** Maximum buffer capacity */
+    get maxCapacity() {
+        return this.capacity;
+    }
+}

package/dist/daemon/lib/chunker/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Chunker - Tree-sitter based code chunking.
+ *
+ * Uses web-tree-sitter (WASM) to parse code and extract semantic chunks
+ * (functions, classes, methods) for embedding.
+ */
+import { type Chunk, type SupportedLanguage } from './types.js';
+/**
+ * Chunker that uses web-tree-sitter (WASM) to extract semantic code chunks.
+ * Provides 100% platform compatibility - no native compilation required.
+ */
+export declare class Chunker {
+    private parser;
+    private languages;
+    private initialized;
+    private wasmBasePath;
+    constructor();
+    /**
+     * Initialize web-tree-sitter and load language grammars.
+     * Must be called before using chunkFile().
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the language for a file extension.
+     */
+    getLanguageForExtension(ext: string): SupportedLanguage | null;
+    /**
+     * Check if a language is supported.
+     */
+    isLanguageSupported(lang: SupportedLanguage): boolean;
+    /**
+     * Check if a file is a markdown file.
+     */
+    private isMarkdownFile;
+    /**
+     * Extract chunks from a file.
+     *
+     * @param filepath - Path to the file (used for extension detection and context headers)
+     * @param content - File content to parse
+     * @param maxChunkSize - Maximum chunk size in characters (default: 2000)
+     * @returns Array of extracted chunks
+     */
+    chunkFile(filepath: string, content: string, maxChunkSize?: number): Chunk[];
+    /**
+     * Extract chunks from a syntax tree.
+     */
+    private extractChunks;
+    /**
+     * Recursively traverse nodes to extract chunks.
+     * Tracks parent context (class name) for context headers.
+     */
+    private traverseNode;
+    /**
+     * Convert a syntax node to a chunk.
+     */
+    private nodeToChunk;
+    /**
+     * Extract the signature line (first line of function/class declaration).
+     */
+    private extractSignature;
+    /**
+     * Extract docstring from a function/class node.
+     */
+    private extractDocstring;
+    /**
+     * Check if a node is exported/public.
+     */
+    private extractIsExported;
+    /**
+     * Helper to check for visibility modifiers in a node.
+     */
+    private hasVisibilityModifier;
+    /**
+     * Extract decorator names from a node.
+     */
+    private extractDecoratorNames;
+    /**
+     * Helper to find a child node of specific types.
+     */
+    private findChildOfType;
+    /**
+     * Build a context header for a chunk.
+     */
+    private buildContextHeader;
+    /**
+     * Extract the name of a function/class/method from its node.
+     */
+    private extractName;
+    /**
+     * Create a module-level chunk for the entire file.
+     */
+    private createModuleChunk;
+    /**
+     * Chunk markdown files with heading-aware splitting and overlap.
+     *
+     * Strategy:
+     * 1. Try to split at heading boundaries (# lines)
+     * 2. Use sliding window with overlap between chunks
+     * 3. Merge small final chunks to avoid orphans
+     */
+    private chunkMarkdown;
+    /**
+     * Create a chunk from markdown content.
+     */
+    private createMarkdownChunk;
+    /**
+     * Enforce size limits: split oversized chunks and merge tiny ones.
+     *
+     * @param overlapLines - Number of lines to overlap between chunks (for context continuity)
+     */
+    private enforceSizeLimits;
+    /**
+     * Split an oversized chunk by lines.
+     * Tries to split at natural boundaries (empty lines, statement ends).
+     *
+     * @param overlapLines - Number of lines from previous chunk to include for context
+     */
+    private splitChunkByLines;
+    /**
+     * Create a chunk from a split portion.
+     */
+    private createSplitChunk;
+    /**
+     * Extract class name from a context header string.
+     */
+    private extractClassFromContext;
+    /**
+     * Merge small adjacent chunks of the same type to avoid fragment explosion.
+     */
+    private mergeSmallChunks;
+    /**
+     * Close the parser and free resources.
+     */
+    close(): void;
+}