byterover-cli 0.2.0 → 0.3.0

package/dist/commands/query.js

@@ -0,0 +1,349 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { randomUUID } from 'node:crypto';
+import { getCurrentConfig, isDevelopment } from '../config/environment.js';
+import { PROJECT } from '../constants.js';
+import { CipherAgent } from '../infra/cipher/cipher-agent.js';
+import { ExitCode, ExitError, exitWithCode } from '../infra/cipher/exit-codes.js';
+import { WorkspaceNotInitializedError } from '../infra/cipher/validation/workspace-validator.js';
+import { ProjectConfigStore } from '../infra/config/file-config-store.js';
+import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
+import { formatError } from '../utils/error-handler.js';
+import { formatToolCall, formatToolResult } from '../utils/tool-display-formatter.js';
+export default class Query extends Command {
+    static args = {
+        query: Args.string({
+            description: 'Natural language question about your codebase or project knowledge',
+            required: true,
+        }),
+    };
+    static description = `Query and retrieve information from the context tree
+Good:
+- "How is user authentication implemented?"
+- "What are the API rate limits and where are they enforced?"
+Bad:
+- "auth" or "authentication" (too vague, not a question)
+- "show me code" (not specific about what information is needed)`;
+    static examples = [
+        '# Ask questions about patterns, decisions, or implementation details',
+        '<%= config.bin %> <%= command.id %> What are the coding standards?',
+        '<%= config.bin %> <%= command.id %> How is authentication implemented?',
+        '',
+        ...(isDevelopment()
+            ? [
+                '# Query with OpenRouter (development only)',
+                '<%= config.bin %> <%= command.id %> -k YOUR_API_KEY Show me all API endpoints',
+                '',
+                '# Query with custom model (development only)',
+                '<%= config.bin %> <%= command.id %> -k YOUR_API_KEY -m anthropic/claude-sonnet-4 Explain the database schema',
+                '',
+                '# Query with verbose output (development only)',
+                '<%= config.bin %> <%= command.id %> -v What testing strategies are used?',
+            ]
+            : []),
+    ];
+    static flags = {
+        ...(isDevelopment()
+            ? {
+                apiKey: Flags.string({
+                    char: 'k',
+                    description: 'OpenRouter API key (use OpenRouter instead of internal gRPC backend) [Development only]',
+                    env: 'OPENROUTER_API_KEY',
+                }),
+                model: Flags.string({
+                    char: 'm',
+                    description: 'Model to use (default: google/gemini-2.5-pro for OpenRouter, gemini-2.5-pro for gRPC) [Development only]',
+                }),
+                verbose: Flags.boolean({
+                    char: 'v',
+                    default: false,
+                    description: 'Enable verbose debug output [Development only]',
+                }),
+            }
+            : {}),
+    };
+    static strict = false;
+    // Override catch to prevent oclif from logging errors that were already displayed
+    async catch(error) {
+        // Check if error is ExitError (message already displayed by exitWithCode)
+        if (error instanceof ExitError) {
+            return;
+        }
+        // Backwards compatibility: also check oclif.exit property
+        if (error.oclif?.exit !== undefined) {
+            // Error already displayed by exitWithCode, silently exit
+            return;
+        }
+        // For other errors, re-throw to let oclif handle them
+        throw error;
+    }
+    createServices() {
+        return {
+            projectConfigStore: new ProjectConfigStore(),
+            trackingService: new MixpanelTrackingService(new KeychainTokenStore()),
+        };
+    }
+    /**
+     * Generate a unique session ID for the query agent.
+     * Uses crypto.randomUUID() for guaranteed uniqueness (122 bits of entropy).
+     */
+    generateSessionId() {
+        return randomUUID();
+    }
+    async run() {
+        const { argv, flags } = await this.parse(Query);
+        const { projectConfigStore, trackingService } = this.createServices();
+        try {
+            // Get authentication token
+            const tokenStore = new KeychainTokenStore();
+            const token = await tokenStore.load();
+            if (!token) {
+                exitWithCode(ExitCode.CONFIG_ERROR, 'Authentication required. Please run "brv login" first.');
+            }
+            // Load project config
+            const brvConfig = await projectConfigStore.read();
+            // Validate workspace is initialized
+            if (!brvConfig) {
+                throw new WorkspaceNotInitializedError('Project not initialized. Please run "brv init" to select your team and workspace.', '.brv');
+            }
+            // Create LLM config
+            const model = flags.model ?? (flags.apiKey ? 'google/gemini-2.5-pro' : 'gemini-2.5-pro');
+            const envConfig = getCurrentConfig();
+            const llmConfig = {
+                accessToken: token.accessToken,
+                fileSystemConfig: { workingDirectory: process.cwd() },
+                grpcEndpoint: envConfig.llmGrpcEndpoint,
+                maxIterations: 5,
+                maxTokens: 2048,
+                model,
+                openRouterApiKey: flags.apiKey,
+                projectId: PROJECT,
+                sessionKey: token.sessionKey,
+                temperature: 0.7,
+                topK: 10,
+                topP: 0.95,
+                verbose: flags.verbose ?? false,
+            };
+            // Create and start CipherAgent
+            const agent = new CipherAgent(llmConfig, brvConfig);
+            this.log('Querying context tree...');
+            await agent.start();
+            try {
+                const sessionId = this.generateSessionId();
+                // Setup event listeners
+                this.setupEventListeners(agent, flags.verbose ?? false);
+                // Combine all query terms from argv (everything after flags)
+                const queryTerms = argv.join(' ');
+                // Execute with autonomous mode and query commandType
+                const prompt = `Search the context tree for: ${queryTerms}`;
+                const response = await agent.execute(prompt, sessionId, {
+                    executionContext: { commandType: 'query' },
+                    mode: 'autonomous',
+                });
+                this.log('\nQuery Results:');
+                this.log(response);
+                await trackingService.track('ace:query');
+            }
+            finally {
+                // console.log('Logic for agent stopping and resource cleanup may go here!')
+            }
+        }
+        catch (error) {
+            if (error instanceof WorkspaceNotInitializedError) {
+                this.handleWorkspaceError(error);
+                return;
+            }
+            // Display context on one line, error on separate line
+            process.stderr.write('Failed to query context tree:\n');
+            exitWithCode(ExitCode.RUNTIME_ERROR, formatError(error));
+        }
+    }
+    /**
+     * Format items count from list_directory result
+     */
+    formatItemsCount(result) {
+        if (typeof result === 'string') {
+            const lines = result.split('\n').filter((line) => line.trim());
+            return `${lines.length} items`;
+        }
+        if (Array.isArray(result)) {
+            return `${result.length} items`;
+        }
+        return '';
+    }
+    /**
+     * Format matches count from grep_content result
+     */
+    formatMatchesCount(result) {
+        if (typeof result === 'string') {
+            const lines = result.split('\n').filter((line) => line.trim());
+            return `${lines.length} matches found`;
+        }
+        if (Array.isArray(result)) {
+            return `${result.length} matches found`;
+        }
+        return '';
+    }
+    /**
+     * Format tool result summary for display
+     */
+    formatToolResultSummary(toolName, result) {
+        try {
+            switch (toolName) {
+                case 'bash_exec':
+                case 'create_knowledge_topic':
+                case 'delete_knowledge_topic':
+                case 'detect_domains':
+                case 'read_file':
+                case 'update_knowledge_topic':
+                case 'write_file': {
+                    return '';
+                }
+                case 'find_knowledge_topics': {
+                    return this.formatTopicsCount(result);
+                }
+                case 'grep_content': {
+                    return this.formatMatchesCount(result);
+                }
+                case 'list_directory': {
+                    return this.formatItemsCount(result);
+                }
+                default: {
+                    return '';
+                }
+            }
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Format topics count from find_knowledge_topics result
+     */
+    formatTopicsCount(result) {
+        if (typeof result === 'string') {
+            try {
+                const parsed = JSON.parse(result);
+                const count = Array.isArray(parsed) ? parsed.length : Object.keys(parsed).length;
+                return `${count} topics retrieved`;
+            }
+            catch {
+                return '';
+            }
+        }
+        if (typeof result === 'object' && result !== null) {
+            const resultObj = result;
+            if (Array.isArray(resultObj.results)) {
+                return `${resultObj.results.length} topics retrieved`;
+            }
+            if (typeof resultObj.total === 'number') {
+                return `${resultObj.total} topics retrieved`;
+            }
+            if (Array.isArray(result)) {
+                return `${result.length} topics retrieved`;
+            }
+        }
+        return '';
+    }
+    /**
+     * Get user-friendly description for a tool
+     *
+     * @param toolName - Name of the tool
+     * @param args - Tool arguments
+     * @returns User-friendly description
+     */
+    getToolDescription(toolName, args) {
+        switch (toolName) {
+            case 'bash_exec': {
+                const cmd = String(args.command ?? '');
+                return cmd.length > 60 ? `Running command...` : `Running: ${cmd}`;
+            }
+            case 'create_knowledge_topic': {
+                return 'Creating knowledge topic...';
+            }
+            case 'find_knowledge_topics': {
+                return 'Querying knowledge base...';
+            }
+            case 'grep_content': {
+                return 'Searching context tree...';
+            }
+            case 'list_directory': {
+                return 'Listing directory...';
+            }
+            case 'read_file': {
+                return `Reading file...`;
+            }
+            case 'update_knowledge_topic': {
+                return 'Updating knowledge topic...';
+            }
+            case 'write_file': {
+                return 'Writing file...';
+            }
+            default: {
+                return 'Processing...';
+            }
+        }
+    }
+    /**
+     * Handle workspace not initialized error
+     */
+    handleWorkspaceError(_error) {
+        const message = 'Project not initialized. Please run "brv init" to select your team and workspace.';
+        exitWithCode(ExitCode.VALIDATION_ERROR, message);
+    }
+    /**
+     * Setup event listeners for CipherAgent
+     */
+    setupEventListeners(agent, verbose) {
+        if (!agent.agentEventBus) {
+            throw new Error('Agent event bus not initialized');
+        }
+        const eventBus = agent.agentEventBus;
+        if (verbose) {
+            // Verbose mode: show detailed events
+            eventBus.on('llmservice:thinking', () => {
+                this.log('🤔 [Event] LLM is thinking...');
+            });
+            eventBus.on('llmservice:response', (payload) => {
+                this.log(`✅ [Event] LLM Response (${payload.provider}/${payload.model})`);
+            });
+            eventBus.on('llmservice:toolCall', (payload) => {
+                // Clear any spinner on current line before printing (use spaces instead of ANSI codes)
+                const formattedCall = formatToolCall(payload.toolName, payload.args);
+                this.log(`🔧 [Event] Tool Call: ${formattedCall}`);
+            });
+            eventBus.on('llmservice:toolResult', (payload) => {
+                const resultSummary = formatToolResult(payload.toolName, payload.success, payload.result, payload.error);
+                if (payload.success) {
+                    this.log(`✓ [Event] Tool Success: ${payload.toolName} → ${resultSummary}`);
+                }
+                else {
+                    this.log(`✗ [Event] Tool Error: ${payload.toolName} → ${resultSummary}`);
+                }
+            });
+            // NOTE: llmservice:error is handled by catch block in the run method
+            // which displays error via this.error(). DO NOT display here to avoid duplicate.
+        }
+        else {
+            // Non-verbose mode: show concise tool progress with descriptions
+            eventBus.on('llmservice:toolCall', (payload) => {
+                // Clear any spinner on current line before printing (use spaces instead of ANSI codes)
+                const description = this.getToolDescription(payload.toolName, payload.args);
+                this.log(`🔧 ${payload.toolName} → ${description}`);
+            });
+            eventBus.on('llmservice:toolResult', (payload) => {
+                if (payload.success) {
+                    // Show brief success summary for tool completion
+                    const summary = this.formatToolResultSummary(payload.toolName, payload.result);
+                    const completionText = summary ? `Complete (${summary})` : 'Complete';
+                    this.log(`✅ ${payload.toolName} → ${completionText}`);
+                }
+                else {
+                    this.log(`✗ ${payload.toolName} → Failed: ${payload.error}`);
+                }
+            });
+            // NOTE: llmservice:error is handled by catch block in the run method
+            // which displays error via this.error(). DO NOT display here to avoid duplicate.
+        }
+    }
+}

package/dist/commands/space/list.d.ts

@@ -2,7 +2,6 @@ import { Command } from '@oclif/core';
 import type { IProjectConfigStore } from '../../core/interfaces/i-project-config-store.js';
 import type { ISpaceService } from '../../core/interfaces/i-space-service.js';
 import type { ITokenStore } from '../../core/interfaces/i-token-store.js';
-import { AuthToken } from '../../core/domain/entities/auth-token.js';
 export default class SpaceList extends Command {
     static description: string;
     static examples: string[];
@@ -12,11 +11,15 @@ export default class SpaceList extends Command {
         limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         offset: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
     };
+    catch(error: Error & {
+        oclif?: {
+            exit: number;
+        };
+    }): Promise<void>;
     protected createServices(): {
         projectConfigStore: IProjectConfigStore;
         spaceService: ISpaceService;
         tokenStore: ITokenStore;
     };
     run(): Promise<void>;
-    protected validateAuth(tokenStore: ITokenStore): Promise<AuthToken>;
 }

package/dist/commands/space/list.js

@@ -1,5 +1,6 @@
 import { Command, Flags, ux } from '@oclif/core';
 import { getCurrentConfig } from '../../config/environment.js';
+import { ExitCode, ExitError, exitWithCode } from '../../infra/cipher/exit-codes.js';
 import { ProjectConfigStore } from '../../infra/config/file-config-store.js';
 import { HttpSpaceService } from '../../infra/space/http-space-service.js';
 import { KeychainTokenStore } from '../../infra/storage/keychain-token-store.js';
@@ -36,6 +37,18 @@ export default class SpaceList extends Command {
             description: 'Number of spaces to skip',
         }),
     };
+    async catch(error) {
+        // Check if error is ExitError (message already displayed)
+        if (error instanceof ExitError) {
+            return;
+        }
+        // Backwards compatibility: also check oclif.exit property
+        if (error.oclif?.exit !== undefined) {
+            return;
+        }
+        // For unexpected errors, show the message
+        this.error(error instanceof Error ? error.message : 'Failed to list spaces');
+    }
     createServices() {
         const envConfig = getCurrentConfig();
         return {
@@ -45,66 +58,57 @@ export default class SpaceList extends Command {
         };
     }
     async run() {
-        try {
-            const { flags } = await this.parse(SpaceList);
-            const { projectConfigStore, spaceService, tokenStore } = this.createServices();
-            // Check project initialization
-            const projectConfig = await projectConfigStore.read();
-            if (projectConfig === undefined) {
-                this.error('Project not initialized. Run "brv init" first.');
-            }
-            const token = await this.validateAuth(tokenStore);
-            // Fetch spaces for the team from project config
-            ux.action.start(`Fetching spaces for ${projectConfig.teamName}`);
-            let result;
-            try {
-                result = await spaceService.getSpaces(token.accessToken, token.sessionKey, projectConfig.teamId, flags.all ? { fetchAll: true } : { limit: flags.limit, offset: flags.offset });
-            }
-            finally {
-                ux.action.stop();
-            }
-            // Handle empty results
-            if (result.spaces.length === 0) {
-                this.log(`No spaces found in team "${projectConfig.teamName}".`);
-                return;
-            }
-            // Display results based on format
-            if (flags.json) {
-                this.log(JSON.stringify({
-                    showing: result.spaces.length,
-                    spaces: result.spaces.map((s) => s.toJson()),
-                    team: { id: projectConfig.teamId, name: projectConfig.teamName },
-                    total: result.total,
-                }, null, 2));
-                return;
-            }
-            // Human-readable format
-            this.log(`\nSpaces in team "${projectConfig.teamName}":\n`);
-            this.log(`Found ${result.spaces.length} space(s):\n`);
-            for (const [index, space] of result.spaces.entries()) {
-                this.log(`  ${index + 1}. ${space.getDisplayName()}`);
-            }
-            // Pagination warning
-            if (!flags.all && result.spaces.length < result.total) {
-                const remaining = result.total - result.spaces.length - flags.offset;
-                this.log(`\nShowing ${result.spaces.length} of ${result.total} spaces.`);
-                if (remaining > 0) {
-                    this.log('Use --all to fetch all spaces, or use --limit and --offset for pagination.');
-                }
-            }
+        const { flags } = await this.parse(SpaceList);
+        const { projectConfigStore, spaceService, tokenStore } = this.createServices();
+        // Check project initialization
+        const projectConfig = await projectConfigStore.read();
+        if (!projectConfig) {
+            exitWithCode(ExitCode.VALIDATION_ERROR, 'Project not initialized. Please run "brv init" first.');
         }
-        catch (error) {
-            this.error(error instanceof Error ? error.message : 'Failed to list spaces');
-        }
-    }
-    async validateAuth(tokenStore) {
         const token = await tokenStore.load();
-        if (token === undefined) {
-            this.error('Not authenticated. Please run "brv login" first.');
+        if (!token) {
+            exitWithCode(ExitCode.VALIDATION_ERROR, 'Not authenticated. Please run "brv login" first.');
         }
         if (!token.isValid()) {
-            this.error('Authentication token expired. Please run "brv login" again.');
+            exitWithCode(ExitCode.VALIDATION_ERROR, 'Authentication token expired. Please run "brv login" again.');
+        }
+        // Fetch spaces for the team from project config
+        ux.action.start(`Fetching spaces for ${projectConfig.teamName}`);
+        let result;
+        try {
+            result = await spaceService.getSpaces(token.accessToken, token.sessionKey, projectConfig.teamId, flags.all ? { fetchAll: true } : { limit: flags.limit, offset: flags.offset });
+        }
+        finally {
+            ux.action.stop();
+        }
+        // Handle empty results
+        if (result.spaces.length === 0) {
+            this.log(`No spaces found in team "${projectConfig.teamName}".`);
+            return;
+        }
+        // Display results based on format
+        if (flags.json) {
+            this.log(JSON.stringify({
+                showing: result.spaces.length,
+                spaces: result.spaces.map((s) => s.toJson()),
+                team: { id: projectConfig.teamId, name: projectConfig.teamName },
+                total: result.total,
+            }, null, 2));
+            return;
+        }
+        // Human-readable format
+        this.log(`\nSpaces in team "${projectConfig.teamName}":\n`);
+        this.log(`Found ${result.spaces.length} space(s):\n`);
+        for (const [index, space] of result.spaces.entries()) {
+            this.log(`  ${index + 1}. ${space.getDisplayName()}`);
+        }
+        // Pagination warning
+        if (!flags.all && result.spaces.length < result.total) {
+            const remaining = result.total - result.spaces.length - flags.offset;
+            this.log(`\nShowing ${result.spaces.length} of ${result.total} spaces.`);
+            if (remaining > 0) {
+                this.log('Use --all to fetch all spaces, or use --limit and --offset for pagination.');
+            }
         }
-        return token;
     }
 }

package/dist/commands/space/switch.d.ts

@@ -5,15 +5,31 @@ import type { IProjectConfigStore } from '../../core/interfaces/i-project-config
 import type { ISpaceService } from '../../core/interfaces/i-space-service.js';
 import type { ITeamService } from '../../core/interfaces/i-team-service.js';
 import type { ITokenStore } from '../../core/interfaces/i-token-store.js';
+import { Agent } from '../../core/domain/entities/agent.js';
 export default class SpaceSwitch extends Command {
     static description: string;
     static examples: string[];
+    catch(error: Error & {
+        oclif?: {
+            exit: number;
+        };
+    }): Promise<void>;
     protected createServices(): {
         projectConfigStore: IProjectConfigStore;
         spaceService: ISpaceService;
         teamService: ITeamService;
         tokenStore: ITokenStore;
     };
+    protected detectWorkspacesForAgent(agent: Agent): {
+        chatLogPath: string;
+        cwd: string;
+    };
+    /**
+     * Prompts the user to select an agent.
+     * This method is protected to allow test overrides.
+     * @returns The selected agent
+     */
+    protected promptForAgentSelection(): Promise<Agent>;
     protected promptForSpaceSelection(spaces: Space[]): Promise<Space>;
     protected promptForTeamSelection(teams: Team[]): Promise<Team>;
     run(): Promise<void>;