viberag 0.6.2 → 0.7.1

package/README.md

@@ -132,6 +132,8 @@ The following sections describe manual MCP server setup configurations for vario
 claude mcp add viberag -- npx viberag-mcp
 ```
 
+> **Tool Search:** Claude Code supports MCP Tool Search (beta) to discover MCP tools on-demand when many tools are installed. It is enabled by default; to force-enable set `ENABLE_TOOL_SEARCH=true` when launching `claude`.
+
 **Global Config:** `~/.claude.json`
 
 ```json

package/dist/cli/app.js

@@ -28,9 +28,17 @@ import { getViberagDir } from '../daemon/lib/constants.js';
 import { loadConfig } from '../daemon/lib/config.js';
 import { checkNpmForUpdate } from '../daemon/lib/update-check.js';
 import { checkV2IndexCompatibility } from '../daemon/services/v2/manifest.js';
+import { createTelemetryClient } from '../daemon/lib/telemetry/client.js';
+import { initSentry } from '../daemon/lib/telemetry/sentry.js';
 const require = createRequire(import.meta.url);
 // Path is relative from dist/ after compilation
 const { version } = require('../../package.json');
+const cliTelemetry = createTelemetryClient({
+    service: 'cli',
+    projectRoot: process.cwd(),
+    version,
+});
+const cliSentry = initSentry({ service: 'cli', version });
 // Available slash commands for autocomplete with descriptions
 const COMMANDS = [
     { command: '/help', description: 'Show available commands' },
@@ -46,6 +54,8 @@ const COMMANDS = [
     { command: '/status', description: 'Show daemon and index status' },
     { command: '/cancel', description: 'Cancel indexing or warmup' },
     { command: '/mcp-setup', description: 'Configure MCP for AI tools' },
+    { command: '/telemetry', description: 'Configure telemetry mode' },
+    { command: '/privacy-policy', description: 'Show privacy policy' },
     { command: '/clean', description: 'Remove Viberag from project' },
     { command: '/quit', description: 'Exit the application' },
 ];
@@ -218,6 +228,11 @@ function AppContent() {
         startMcpSetupWizard,
         startCleanWizard,
         isInitialized: isInitialized ?? false,
+        telemetry: cliTelemetry,
+        shutdownTelemetry: async () => {
+            await cliTelemetry.shutdown();
+            await cliSentry.shutdown();
+        },
     });
     const handleSubmit = (text) => {
         if (!text.trim())

package/dist/cli/commands/useCommands.d.ts

@@ -3,6 +3,7 @@
  * Consolidates all command routing and handler implementations.
  */
 import type { SearchResultsData } from '../../common/types.js';
+import type { TelemetryClient } from '../../daemon/lib/telemetry/client.js';
 type CommandContext = {
     addOutput: (type: 'user' | 'system', content: string) => void;
     addSearchResults: (data: SearchResultsData) => void;
@@ -12,8 +13,10 @@ type CommandContext = {
     startMcpSetupWizard: (showPrompt?: boolean) => void;
     startCleanWizard: () => void;
     isInitialized: boolean;
+    telemetry: TelemetryClient;
+    shutdownTelemetry: () => Promise<void>;
 };
-export declare function useCommands({ addOutput, addSearchResults, projectRoot, stdout, startInitWizard, startMcpSetupWizard, startCleanWizard, isInitialized, }: CommandContext): {
+export declare function useCommands({ addOutput, addSearchResults, projectRoot, stdout, startInitWizard, startMcpSetupWizard, startCleanWizard, isInitialized, telemetry, shutdownTelemetry, }: CommandContext): {
     isCommand: (text: string) => boolean;
     executeCommand: (text: string) => void;
 };

package/dist/cli/commands/useCommands.js

@@ -2,13 +2,22 @@
  * CLI command handling hook.
  * Consolidates all command routing and handler implementations.
  */
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { useCallback } from 'react';
 import { useApp } from 'ink';
 import { runIndex, formatIndexStats, runSearch, getStatus, loadIndexStats, cancelActivity, runEval, formatEvalReport, } from './handlers.js';
 import { setupVSCodeTerminal } from '../../common/commands/terminalSetup.js';
 import { useAppDispatch } from '../store/hooks.js';
 import { AppActions } from '../store/app/slice.js';
-export function useCommands({ addOutput, addSearchResults, projectRoot, stdout, startInitWizard, startMcpSetupWizard, startCleanWizard, isInitialized, }) {
+import { DaemonClient } from '../../client/index.js';
+import { VIBERAG_PRIVACY_POLICY } from '../../daemon/lib/telemetry/privacy-policy.js';
+import { loadUserSettings, parseTelemetryMode, resolveEffectiveTelemetryMode, setTelemetryMode, } from '../../daemon/lib/user-settings.js';
+import { captureException, flushSentry, } from '../../daemon/lib/telemetry/sentry.js';
+export function useCommands({ addOutput, addSearchResults, projectRoot, stdout, startInitWizard, startMcpSetupWizard, startCleanWizard, isInitialized, telemetry, shutdownTelemetry, }) {
     const dispatch = useAppDispatch();
     const { exit } = useApp();
     // Command handlers
@@ -25,6 +34,8 @@ export function useCommands({ addOutput, addSearchResults, projectRoot, stdout,
   /status         - Show index status
   /cancel [target] - Cancel indexing or warmup (targets: indexing, warmup)
   /mcp-setup      - Configure MCP server for AI coding tools
+  /telemetry [mode] - Set telemetry (disabled|stripped|default)
+  /privacy-policy - Show privacy policy for telemetry
   /clean          - Remove VibeRAG from project (delete project data)
   /quit           - Exit
 
@@ -126,6 +137,134 @@ Manual MCP Setup:
     const handleClean = useCallback(() => {
         startCleanWizard();
     }, [startCleanWizard]);
+    const handleTelemetry = useCallback((arg) => {
+        const requested = arg?.trim();
+        const showCurrent = async () => {
+            const settings = await loadUserSettings();
+            const effective = resolveEffectiveTelemetryMode(settings);
+            const source = effective.source === 'env'
+                ? 'VIBERAG_TELEMETRY env var'
+                : 'global settings file';
+            addOutput('system', `Telemetry mode: ${effective.mode} (from ${source})\n\nModes:\n  disabled - no telemetry or error reporting\n  stripped - privacy-preserving telemetry (no query text)\n  default  - includes query text (best-effort redaction)\n\nSet with:\n  /telemetry disabled|stripped|default\n\nThis setting is global (applies to CLI, daemon, and MCP).`);
+            await telemetry.captureOperation({
+                operation_kind: 'cli_command',
+                name: '/telemetry',
+                projectRoot,
+                input: { action: 'show', effective_mode: effective.mode },
+                output: null,
+                success: true,
+                duration_ms: 0,
+            });
+        };
+        const setMode = async (mode) => {
+            const parsed = parseTelemetryMode(mode);
+            if (!parsed) {
+                addOutput('system', `Invalid telemetry mode: ${mode}\n\nUsage:\n  /telemetry disabled|stripped|default`);
+                return;
+            }
+            await setTelemetryMode(parsed);
+            addOutput('system', `Telemetry mode set to: ${parsed}\n\nThis setting is global (applies to CLI, daemon, and MCP).\nIf the daemon is already running, it may take a few seconds to pick up the change.`);
+            await telemetry.captureOperation({
+                operation_kind: 'cli_command',
+                name: '/telemetry',
+                projectRoot,
+                input: { action: 'set', mode: parsed },
+                output: null,
+                success: true,
+                duration_ms: 0,
+            });
+        };
+        void (async () => {
+            if (!requested) {
+                await showCurrent();
+                return;
+            }
+            await setMode(requested);
+        })().catch(err => {
+            addOutput('system', `Telemetry error: ${err.message}`);
+        });
+    }, [addOutput, projectRoot, telemetry]);
+    const handlePrivacyPolicy = useCallback(() => {
+        addOutput('system', VIBERAG_PRIVACY_POLICY);
+        telemetry.capture({
+            event: 'viberag_privacy_policy_viewed',
+            properties: { service: 'cli' },
+        });
+    }, [addOutput, telemetry]);
+    const handleTestException = useCallback((arg) => {
+        void (async () => {
+            const testId = crypto.randomUUID();
+            const settings = await loadUserSettings();
+            const effective = resolveEffectiveTelemetryMode(settings);
+            if (effective.mode === 'disabled') {
+                addOutput('system', `Telemetry is disabled, so error reporting is also disabled.\n\nSet with:\n  /telemetry default\n\nThen re-run:\n  /test-exception`);
+                return;
+            }
+            addOutput('system', `Triggering test exceptions (test_id=${testId}).\nThis is an undocumented command.`);
+            // CLI exception (captured, not fatal)
+            const cliError = new Error(`VibeRAG test exception (cli)${arg ? `: ${arg}` : ''}`);
+            captureException(cliError, {
+                tags: { service: 'cli', test_exception: 'true' },
+                extra: { test_id: testId },
+            });
+            await flushSentry(2000);
+            // Daemon exception (captured inside daemon handler)
+            if (isInitialized) {
+                const client = new DaemonClient(projectRoot);
+                try {
+                    await client.testException(`test_id=${testId}`);
+                }
+                catch {
+                    // Expected: daemon throws
+                }
+                finally {
+                    await client.disconnect();
+                }
+            }
+            else {
+                addOutput('system', 'Skipping daemon test exception (project not initialized).');
+            }
+            // MCP exception (one-shot process)
+            const modulePath = fileURLToPath(import.meta.url);
+            const mcpScriptPath = path.resolve(path.dirname(modulePath), '../../mcp/index.js');
+            const env = {
+                ...process.env,
+                VIBERAG_TEST_EXCEPTION: '1',
+                VIBERAG_TEST_EXCEPTION_ID: testId,
+            };
+            const spawnAndWait = (command, args) => new Promise((resolve, reject) => {
+                const child = spawn(command, args, {
+                    cwd: projectRoot,
+                    env,
+                    stdio: 'ignore',
+                    windowsHide: true,
+                });
+                child.on('error', reject);
+                child.on('exit', code => resolve(code));
+            });
+            try {
+                await fs.access(mcpScriptPath);
+                const exitCode = await spawnAndWait(process.execPath, [
+                    mcpScriptPath,
+                ]);
+                addOutput('system', `MCP test exception process exited (code ${exitCode ?? 'unknown'}).`);
+            }
+            catch {
+                try {
+                    const exitCode = await spawnAndWait('npx', ['viberag-mcp']);
+                    addOutput('system', `MCP test exception process exited (code ${exitCode ?? 'unknown'}).`);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    addOutput('system', `Failed to run MCP test exception process: ${message}\n\nTry manually:\n  VIBERAG_TEST_EXCEPTION=1 npx viberag-mcp`);
+                }
+            }
+            addOutput('system', `Done. Check Sentry for events tagged test_exception=true (test_id=${testId}).`);
+        })().catch(err => {
+            const message = err instanceof Error ? err.message : String(err);
+            addOutput('system', `Test exception command failed: ${message}`);
+        });
+    }, [addOutput, isInitialized, projectRoot]);
     const handleUnknown = useCallback((command) => {
         addOutput('system', `Unknown command: ${command}. Type /help for available commands.`);
     }, [addOutput]);
@@ -153,6 +292,16 @@ Manual MCP Setup:
             handleCancel(target || undefined);
             return;
         }
+        if (command.startsWith('/telemetry')) {
+            const arg = trimmed.slice('/telemetry'.length).trim();
+            handleTelemetry(arg || undefined);
+            return;
+        }
+        if (command.startsWith('/test-exception')) {
+            const arg = trimmed.slice('/test-exception'.length).trim();
+            handleTestException(arg || undefined);
+            return;
+        }
         switch (command) {
             case '/help':
                 handleHelp();
@@ -181,6 +330,9 @@ Manual MCP Setup:
             case '/mcp-setup':
                 handleMcpSetup();
                 break;
+            case '/privacy-policy':
+                handlePrivacyPolicy();
+                break;
             case '/clean':
             case '/uninstall':
                 handleClean();
@@ -188,7 +340,9 @@ Manual MCP Setup:
             case '/quit':
             case '/exit':
             case '/q':
-                exit();
+                void shutdownTelemetry()
+                    .catch(() => { })
+                    .finally(() => exit());
                 break;
             default:
                 handleUnknown(command);
@@ -206,6 +360,10 @@ Manual MCP Setup:
         handleEval,
         handleCancel,
         handleMcpSetup,
+        handleTelemetry,
+        handlePrivacyPolicy,
+        handleTestException,
+        shutdownTelemetry,
         handleClean,
         handleUnknown,
     ]);

package/dist/client/index.d.ts

@@ -19,6 +19,7 @@ export declare class DaemonClient {
     private readonly socketPath;
     private readonly autoStart;
     private readonly connectTimeout;
+    private readonly clientSource;
     private connection;
     private connectPromise;
     constructor(options: DaemonClientOptions | string);
@@ -48,6 +49,7 @@ export declare class DaemonClient {
      * Ensure connected before making a request.
      */
     private ensureConnected;
+    private request;
     /**
      * Search the codebase.
      */
@@ -75,7 +77,7 @@ export declare class DaemonClient {
     /**
      * Index the codebase.
      */
-    index(options?: ClientIndexOptions): Promise<IndexStats>;
+    index(options?: ClientIndexOptions, timeoutMs?: number): Promise<IndexStats>;
     /**
      * Start indexing asynchronously.
      */
@@ -115,6 +117,12 @@ export declare class DaemonClient {
         indexStatus: string;
         protocolVersion: number;
     }>;
+    /**
+     * Trigger a test exception in the daemon (undocumented).
+     *
+     * Useful for validating Sentry error reporting.
+     */
+    testException(message?: string): Promise<void>;
 }
 export { getSocketPath, getLockPath, isDaemonRunning, isDaemonLocked, } from './auto-start.js';
 export type { DaemonClientOptions, ClientSearchOptions, ClientIndexOptions, DaemonStatusResponse, PingResponse, SearchResults, IndexStats, WatcherStatus, SlotState, FailedChunk, } from './types.js';

package/dist/client/index.js

@@ -44,6 +44,12 @@ export class DaemonClient {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "clientSource", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "connection", {
             enumerable: true,
             configurable: true,
@@ -61,11 +67,13 @@ export class DaemonClient {
             this.projectRoot = options;
             this.autoStart = true;
             this.connectTimeout = 5000;
+            this.clientSource = 'cli';
         }
         else {
             this.projectRoot = options.projectRoot;
             this.autoStart = options.autoStart ?? true;
             this.connectTimeout = options.connectTimeout ?? 5000;
+            this.clientSource = options.clientSource ?? 'cli';
         }
         this.socketPath = getSocketPath(this.projectRoot);
     }
@@ -144,12 +152,18 @@ export class DaemonClient {
             await this.connect();
         }
     }
+    async request(method, params, timeoutMs) {
+        await this.ensureConnected();
+        const withMeta = params
+            ? { ...params, __client: { source: this.clientSource } }
+            : { __client: { source: this.clientSource } };
+        return this.connection.request(method, withMeta, timeoutMs);
+    }
     /**
      * Search the codebase.
      */
     async search(query, options) {
-        await this.ensureConnected();
-        return this.connection.request('search', {
+        return this.request('search', {
             query,
             ...options,
         });
@@ -158,86 +172,82 @@ export class DaemonClient {
      * Fetch a symbol definition row by symbol_id.
      */
     async getSymbol(symbol_id) {
-        await this.ensureConnected();
-        return this.connection.request('getSymbol', { symbol_id });
+        return this.request('getSymbol', { symbol_id });
     }
     /**
      * Find usages for a symbol name or symbol_id.
      */
     async findUsages(options) {
-        await this.ensureConnected();
-        return this.connection.request('findUsages', options);
+        return this.request('findUsages', options);
     }
     /**
      * Run the v2 eval harness (quality + latency).
      */
     async eval(options) {
-        await this.ensureConnected();
-        return this.connection.request('eval', options);
+        return this.request('eval', options);
     }
     /**
      * Expand context for a hit (symbols/chunks/files).
      */
     async expandContext(args) {
-        await this.ensureConnected();
-        return this.connection.request('expandContext', args);
+        return this.request('expandContext', args);
     }
     /**
      * Index the codebase.
      */
-    async index(options) {
-        await this.ensureConnected();
-        return this.connection.request('index', options);
+    async index(options, timeoutMs) {
+        return this.request('index', options, timeoutMs);
     }
     /**
      * Start indexing asynchronously.
      */
     async indexAsync(options) {
-        await this.ensureConnected();
-        return this.connection.request('indexAsync', options);
+        return this.request('indexAsync', options);
     }
     /**
      * Get daemon status.
      * Clients should poll this endpoint for state updates.
      */
     async status() {
-        await this.ensureConnected();
-        return this.connection.request('status');
+        return this.request('status');
     }
     /**
      * Get watcher status.
      */
     async watchStatus() {
-        await this.ensureConnected();
-        return this.connection.request('watchStatus');
+        return this.request('watchStatus');
     }
     /**
      * Request daemon shutdown.
      */
     async shutdown(reason) {
-        await this.ensureConnected();
-        await this.connection.request('shutdown', { reason });
+        await this.request('shutdown', { reason });
     }
     /**
      * Cancel the current daemon activity (indexing or warmup).
      */
     async cancel(options) {
-        await this.ensureConnected();
-        return this.connection.request('cancel', options);
+        return this.request('cancel', options);
     }
     /**
      * Ping the daemon.
      */
     async ping() {
-        await this.ensureConnected();
-        return this.connection.request('ping');
+        return this.request('ping');
     }
     /**
      * Get health information.
      */
     async health() {
-        await this.ensureConnected();
-        return this.connection.request('health');
+        return this.request('health');
+    }
+    /**
+     * Trigger a test exception in the daemon (undocumented).
+     *
+     * Useful for validating Sentry error reporting.
+     */
+    async testException(message) {
+        await this.request('testException', { message });
     }
 }
 // Re-export types and utilities

package/dist/client/types.d.ts

@@ -37,6 +37,13 @@ export interface DaemonClientOptions {
     autoStart?: boolean;
     /** Connection timeout in ms (default: 5000) */
     connectTimeout?: number;
+    /**
+     * Caller identity for telemetry correlation and filtering.
+     *
+     * Used to reduce duplicate telemetry events (e.g. when MCP tools already
+     * capture operations at the tool boundary).
+     */
+    clientSource?: 'cli' | 'mcp' | 'unknown';
 }
 /**
  * Search options for client.

package/dist/daemon/handlers.js

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { PROTOCOL_VERSION } from './protocol.js';
 import { daemonState } from './state.js';
 import { isAbortError } from './lib/abort.js';
+import { captureException, flushSentry } from './lib/telemetry/sentry.js';
 // ============================================================================
 // Parameter Schemas
 // ============================================================================
@@ -232,6 +233,23 @@ const healthHandler = async (_params, ctx) => {
         protocolVersion: PROTOCOL_VERSION,
     };
 };
+/**
+ * Test exception handler (undocumented).
+ *
+ * Used to validate Sentry error reporting across services.
+ */
+const testExceptionHandler = async (params, _ctx) => {
+    const messageValue = params?.['message'];
+    const message = typeof messageValue === 'string' ? messageValue : undefined;
+    const error = new Error(`VibeRAG test exception (daemon)${message ? `: ${message}` : ''}`);
+    captureException(error, {
+        tags: { service: 'daemon', test_exception: 'true' },
+        extra: { message: message ?? null },
+    });
+    // Best-effort flush so it shows up quickly.
+    await flushSentry(2000);
+    throw error;
+};
 // ============================================================================
 // Handler Registry
 // ============================================================================
@@ -253,5 +271,6 @@ export function createHandlers() {
         shutdown: shutdownHandler,
         ping: pingHandler,
         health: healthHandler,
+        testException: testExceptionHandler,
     };
 }

package/dist/daemon/index.js

@@ -22,6 +22,7 @@
  * - Auto-shutdown after 5 minutes of idle (no connected clients)
  */
 import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import lockfile from 'proper-lockfile';
 import { DaemonOwner } from './owner.js';
 import { DaemonServer } from './server.js';
@@ -29,7 +30,17 @@ import { LifecycleManager } from './lifecycle.js';
 import { createHandlers } from './handlers.js';
 import { configExists, loadConfig } from './lib/config.js';
 import { getCanonicalProjectRoot, getDaemonLockPath, getRunDir, } from './lib/constants.js';
+import { createTelemetryClient } from './lib/telemetry/client.js';
+import { captureException, initSentry } from './lib/telemetry/sentry.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
 const projectRoot = getCanonicalProjectRoot(process.env['VIBERAG_PROJECT_ROOT'] ?? process.cwd());
+const telemetry = createTelemetryClient({
+    service: 'daemon',
+    projectRoot,
+    version: pkg.version,
+});
+const sentry = initSentry({ service: 'daemon', version: pkg.version });
 // Lock file path - inside the global run directory
 const LOCK_FILE_PATH = getDaemonLockPath(projectRoot);
 const RUN_DIR = getRunDir(projectRoot);
@@ -106,7 +117,11 @@ async function main() {
     // Create components
     const owner = new DaemonOwner(projectRoot);
     const server = new DaemonServer(owner);
-    const lifecycle = new LifecycleManager(server, owner, idleTimeoutMs);
+    server.setTelemetry(telemetry);
+    const lifecycle = new LifecycleManager(server, owner, idleTimeoutMs, async () => {
+        await telemetry.shutdown();
+        await sentry.shutdown();
+    });
     // Register handlers
     server.setHandlers(createHandlers());
     // Start server
@@ -122,8 +137,11 @@ async function main() {
     console.error(`[daemon] PID: ${process.pid}`);
 }
 // Run main with error handling
-main().catch(error => {
+main().catch(async (error) => {
     // Pass Error object directly to preserve stack trace (ADR-011)
     console.error('[daemon] Fatal error:', error);
+    captureException(error, { tags: { service: 'daemon', fatal: 'true' } });
+    await telemetry.shutdown();
+    await sentry.shutdown();
     process.exit(1);
 });

package/dist/daemon/lib/constants.d.ts

@@ -86,6 +86,12 @@ export declare function getDaemonPidPath(projectRoot: string): string;
  * Get the daemon lock file path.
  */
 export declare function getDaemonLockPath(projectRoot: string): string;
+/**
+ * Get the global user settings file path.
+ *
+ * Path: {VIBERAG_HOME}/settings.json
+ */
+export declare function getUserSettingsPath(): string;
 /**
  * Get the global secrets directory.
  */

package/dist/daemon/lib/constants.js

@@ -150,6 +150,14 @@ export function getDaemonLockPath(projectRoot) {
 // ============================================================================
 // Secrets Paths
 // ============================================================================
+/**
+ * Get the global user settings file path.
+ *
+ * Path: {VIBERAG_HOME}/settings.json
+ */
+export function getUserSettingsPath() {
+    return path.join(getViberagHomeDir(), 'settings.json');
+}
 /**
  * Get the global secrets directory.
  */

package/dist/daemon/lib/telemetry/client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PostHog telemetry client wrapper for VibeRAG.
+ *
+ * - Telemetry is enabled by default (opt-out).
+ * - Settings are global under VIBERAG_HOME and shared by CLI/daemon/MCP.
+ * - Captures inputs/outputs but strips file contents / code text.
+ */
+export type TelemetryServiceName = 'cli' | 'daemon' | 'mcp';
+export type TelemetryClient = {
+    captureOperation: (args: {
+        operation_kind: 'daemon_method' | 'mcp_tool' | 'cli_command';
+        name: string;
+        projectRoot?: string;
+        input?: unknown;
+        output?: unknown;
+        success: boolean;
+        duration_ms: number;
+        error?: unknown;
+        request_id?: string;
+    }) => Promise<string>;
+    capture: (args: {
+        event: string;
+        properties?: Record<string, unknown>;
+    }) => void;
+    shutdown: () => Promise<void>;
+};
+export declare function createTelemetryClient(args: {
+    service: TelemetryServiceName;
+    projectRoot?: string;
+    version: string;
+}): TelemetryClient;