byterover-cli 3.2.0 → 3.3.0

package/dist/server/core/domain/transport/schemas.js

@@ -314,7 +314,7 @@ export const TaskExecuteSchema = z.object({
     /** Unique task identifier */
     taskId: z.string(),
     /** Task type */
-    type: z.enum(['curate', 'curate-folder', 'query']),
+    type: z.enum(['curate', 'curate-folder', 'query', 'search']),
     /** Workspace root for scoped query/curate */
     worktreeRoot: z.string().optional(),
 });
@@ -374,7 +374,7 @@ export const TaskCreatedSchema = z.object({
     /** Unique task identifier */
     taskId: z.string(),
     /** Task type */
-    type: z.enum(['curate', 'curate-folder', 'query']),
+    type: z.enum(['curate', 'curate-folder', 'query', 'search']),
 });
 /**
  * task:started - Agent begins processing the task
@@ -475,7 +475,7 @@ export const LlmToolResultEventSchema = z.object({
 // ============================================================================
 // Request/Response Schemas (for client → server commands)
 // ============================================================================
-export const TaskTypeSchema = z.enum(['curate', 'curate-folder', 'query']);
+export const TaskTypeSchema = z.enum(['curate', 'curate-folder', 'query', 'search']);
 /**
  * Request to create a new task
  */

package/dist/server/core/interfaces/executor/i-search-executor.d.ts

@@ -0,0 +1,34 @@
+import type { SearchKnowledgeResult } from '../../../../agent/infra/sandbox/tools-sdk.js';
+/**
+ * Options for executing a context tree search.
+ * Search is stateless — no agent session, no LLM, no task isolation needed.
+ */
+export interface SearchExecuteOptions {
+    /** Maximum number of results to return (default: 10) */
+    limit?: number;
+    /** Search query */
+    query: string;
+    /** Path prefix to scope results (e.g. "auth/" for auth domain only) */
+    scope?: string;
+}
+/**
+ * ISearchExecutor - Executes search against the context tree's BM25 index.
+ *
+ * Unlike QueryExecutor (which requires a CipherAgent for LLM synthesis),
+ * SearchExecutor is stateless and returns raw search results directly.
+ * No agent session, no sandbox, no LLM call.
+ *
+ * Architecture:
+ * - SearchKnowledgeService provides BM25-indexed search
+ * - Executor wraps it with option validation
+ * - Results are SearchKnowledgeResult (paths, scores, excerpts)
+ */
+export interface ISearchExecutor {
+    /**
+     * Execute a context tree search.
+     *
+     * @param options - Search options (query, limit, scope)
+     * @returns Raw search results with paths, scores, and excerpts
+     */
+    execute(options: SearchExecuteOptions): Promise<SearchKnowledgeResult>;
+}

package/dist/server/core/interfaces/executor/i-search-executor.js

@@ -0,0 +1 @@
+export {};

package/dist/server/core/interfaces/executor/index.d.ts

@@ -1,3 +1,4 @@
 export * from './i-curate-executor.js';
 export * from './i-folder-pack-executor.js';
 export * from './i-query-executor.js';
+export * from './i-search-executor.js';

package/dist/server/core/interfaces/executor/index.js

@@ -1,3 +1,4 @@
 export * from './i-curate-executor.js';
 export * from './i-folder-pack-executor.js';
 export * from './i-query-executor.js';
+export * from './i-search-executor.js';

package/dist/server/infra/daemon/agent-process.js

@@ -28,6 +28,7 @@ import { FolderPackService } from '../../../agent/infra/folder-pack/folder-pack-
 import { SessionMetadataStore } from '../../../agent/infra/session/session-metadata-store.js';
 import { createSearchKnowledgeService } from '../../../agent/infra/tools/implementations/search-knowledge-service.js';
 import { AuthEvents } from '../../../shared/transport/events/auth-events.js';
+import { decodeSearchContent } from '../../../shared/transport/search-content.js';
 import { getCurrentConfig } from '../../config/environment.js';
 import { DEFAULT_LLM_MODEL, PROJECT } from '../../constants.js';
 import { serializeTaskError, TaskError, TaskErrorCode } from '../../core/domain/errors/task-error.js';
@@ -36,6 +37,7 @@ import { TransportAgentEventNames, TransportDaemonEventNames, TransportStateEven
 import { CurateExecutor } from '../executor/curate-executor.js';
 import { FolderPackExecutor } from '../executor/folder-pack-executor.js';
 import { QueryExecutor } from '../executor/query-executor.js';
+import { SearchExecutor } from '../executor/search-executor.js';
 import { AgentInstanceDiscovery } from '../transport/agent-instance-discovery.js';
 import { createAgentLogger } from './agent-logger.js';
 import { resolveSessionId } from './session-resolver.js';
@@ -301,10 +303,11 @@ async function start() {
         fileSystem: fileSystemService,
         searchService,
     });
+    const searchExecutor = new SearchExecutor(searchService);
     transport.on(TransportTaskEventNames.EXECUTE, (task) => {
         agentLog(`task:execute received taskId=${task.taskId} type=${task.type} activeTaskCount=${activeTaskCount + 1}`);
         // eslint-disable-next-line no-void
-        void executeTask(task, curateExecutor, folderPackExecutor, queryExecutor);
+        void executeTask(task, curateExecutor, folderPackExecutor, queryExecutor, searchExecutor);
     });
     // 8. Register with transport server (for TransportHandlers tracking)
     await transport.requestWithAck('agent:register', { projectPath });
@@ -312,15 +315,19 @@ async function start() {
     process.send?.({ clientId, type: 'ready' });
     agentLog('Ready — listening for tasks');
 }
-async function executeTask(task, curateExecutor, folderPackExecutor, queryExecutor) {
+async function executeTask(task, curateExecutor, folderPackExecutor, queryExecutor, searchExecutor) {
     const { clientCwd, clientId, content, files, folderPath, taskId, type, worktreeRoot } = task;
     if (!transport || !agent)
         return;
-    const freshProviderConfig = await transport.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
-    const validationError = validateProviderForTask(freshProviderConfig);
-    if (validationError) {
-        transport.request(TransportTaskEventNames.ERROR, { clientId, error: validationError, taskId });
-        return;
+    // Search tasks are pure BM25 retrieval — no LLM, no provider needed.
+    // Skip provider validation so search works even without a configured provider.
+    if (type !== 'search') {
+        const freshProviderConfig = await transport.requestWithAck(TransportStateEventNames.GET_PROVIDER_CONFIG);
+        const validationError = validateProviderForTask(freshProviderConfig);
+        if (validationError) {
+            transport.request(TransportTaskEventNames.ERROR, { clientId, error: validationError, taskId });
+            return;
+        }
     }
     activeTaskCount++;
     try {
@@ -398,6 +405,12 @@ async function executeTask(task, curateExecutor, folderPackExecutor, queryExecut
                     result = await queryExecutor.executeWithAgent(agent, { query: content, taskId, worktreeRoot });
                     break;
                 }
+                case 'search': {
+                    const searchOptions = decodeSearchContent(content);
+                    const searchResult = await searchExecutor.execute(searchOptions);
+                    result = JSON.stringify(searchResult);
+                    break;
+                }
             }
             // Emit task:completed
             agentLog(`task:completed taskId=${taskId}`);

package/dist/server/infra/executor/search-executor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SearchExecutor - Executes context tree searches via SearchKnowledgeService.
+ *
+ * Unlike QueryExecutor (Tier 0-4 with LLM synthesis), SearchExecutor is
+ * pure retrieval: BM25 index lookup → scored results. No LLM, no agent
+ * session, no sandbox, no token cost.
+ *
+ * This is the engine behind `brv search`. The CLI command and transport
+ * layer handle I/O; this module handles the search logic.
+ */
+import type { ISearchKnowledgeService, SearchKnowledgeResult } from '../../../agent/infra/sandbox/tools-sdk.js';
+import type { ISearchExecutor, SearchExecuteOptions } from '../../core/interfaces/executor/i-search-executor.js';
+export declare class SearchExecutor implements ISearchExecutor {
+    private readonly searchService;
+    constructor(searchService: ISearchKnowledgeService);
+    execute(options: SearchExecuteOptions): Promise<SearchKnowledgeResult>;
+}

package/dist/server/infra/executor/search-executor.js

@@ -0,0 +1,30 @@
+/**
+ * SearchExecutor - Executes context tree searches via SearchKnowledgeService.
+ *
+ * Unlike QueryExecutor (Tier 0-4 with LLM synthesis), SearchExecutor is
+ * pure retrieval: BM25 index lookup → scored results. No LLM, no agent
+ * session, no sandbox, no token cost.
+ *
+ * This is the engine behind `brv search`. The CLI command and transport
+ * layer handle I/O; this module handles the search logic.
+ */
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 50;
+export class SearchExecutor {
+    searchService;
+    constructor(searchService) {
+        this.searchService = searchService;
+    }
+    async execute(options) {
+        const query = options.query.trim();
+        if (!query) {
+            return { message: 'Empty query', results: [], totalFound: 0 };
+        }
+        const scope = options.scope?.trim() || undefined;
+        const limit = Math.min(MAX_LIMIT, Math.max(1, Math.trunc(options.limit ?? DEFAULT_LIMIT)));
+        return this.searchService.search(query, {
+            limit,
+            ...(scope ? { scope } : {}),
+        });
+    }
+}

package/dist/server/infra/transport/handlers/pull-handler.js

@@ -1,5 +1,5 @@
 import { PullEvents, } from '../../../../shared/transport/events/pull-events.js';
-import { LocalChangesExistError, NotAuthenticatedError, ProjectNotInitError, SpaceNotConfiguredError, } from '../../../core/domain/errors/task-error.js';
+import { LegacySyncUnavailableError, LocalChangesExistError, NotAuthenticatedError, ProjectNotInitError, } from '../../../core/domain/errors/task-error.js';
 import { guardAgainstGitVc, hasAnyChanges, resolveRequiredProjectPath, } from './handler-types.js';
 /**
  * Handles pull:* events.
@@ -42,7 +42,7 @@ export class PullHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         // Check for local changes that would be overwritten
         const changes = await this.contextTreeSnapshotService.getChanges(projectPath);
@@ -79,7 +79,7 @@ export class PullHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         const changes = await this.contextTreeSnapshotService.getChanges(projectPath);
         const hasLocalChanges = hasAnyChanges(changes);

package/dist/server/infra/transport/handlers/push-handler.js

@@ -1,6 +1,6 @@
 import { join, relative } from 'node:path';
 import { PushEvents, } from '../../../../shared/transport/events/push-events.js';
-import { NotAuthenticatedError, ProjectNotInitError, SpaceNotConfiguredError, } from '../../../core/domain/errors/task-error.js';
+import { LegacySyncUnavailableError, NotAuthenticatedError, ProjectNotInitError, } from '../../../core/domain/errors/task-error.js';
 import { mapToPushContexts } from '../../cogit/context-tree-to-push-context-mapper.js';
 import { guardAgainstGitVc, resolveRequiredProjectPath, } from './handler-types.js';
 /** Path prefix of the context tree relative to the project root. */
@@ -88,7 +88,7 @@ export class PushHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         this.broadcastToProject(projectPath, PushEvents.PROGRESS, { message: 'Reading context files...', step: 'reading' });
         const changes = await this.contextTreeSnapshotService.getChanges(projectPath);
@@ -163,7 +163,7 @@ export class PushHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         const hasSnapshot = await this.contextTreeSnapshotService.hasSnapshot(projectPath);
         if (!hasSnapshot) {

package/dist/server/infra/transport/handlers/status-handler.js

@@ -84,13 +84,14 @@ export class StatusHandler {
             result.authStatus = 'unknown';
         }
         // Project status — use effectiveProjectPath for consistency with resolved root
+        let projectConfig;
         try {
             const isInitialized = await this.projectConfigStore.exists(effectiveProjectPath);
             if (isInitialized) {
-                const config = await this.projectConfigStore.read(effectiveProjectPath);
-                if (config) {
-                    result.teamName = config.teamName;
-                    result.spaceName = config.spaceName;
+                projectConfig = await this.projectConfigStore.read(effectiveProjectPath);
+                if (projectConfig) {
+                    result.teamName = projectConfig.teamName;
+                    result.spaceName = projectConfig.spaceName;
                 }
             }
         }
@@ -115,22 +116,28 @@ export class StatusHandler {
                 else {
                     result.contextTreeDir = join(effectiveProjectPath, BRV_DIR, CONTEXT_TREE_DIR);
                     result.contextTreeRelativeDir = join(BRV_DIR, CONTEXT_TREE_DIR);
-                    const hasSnapshot = await this.contextTreeSnapshotService.hasSnapshot(effectiveProjectPath);
-                    if (!hasSnapshot) {
-                        await this.contextTreeSnapshotService.initEmptySnapshot(effectiveProjectPath);
-                    }
-                    const changes = await this.contextTreeSnapshotService.getChanges(effectiveProjectPath);
-                    const hasChanges = changes.added.length > 0 || changes.modified.length > 0 || changes.deleted.length > 0;
-                    if (hasChanges) {
-                        result.contextTreeStatus = 'has_changes';
-                        result.contextTreeChanges = {
-                            added: changes.added,
-                            deleted: changes.deleted,
-                            modified: changes.modified,
-                        };
+                    const hasLegacySyncConfig = Boolean(projectConfig?.teamId && projectConfig?.spaceId);
+                    if (hasLegacySyncConfig) {
+                        const hasSnapshot = await this.contextTreeSnapshotService.hasSnapshot(effectiveProjectPath);
+                        if (!hasSnapshot) {
+                            await this.contextTreeSnapshotService.initEmptySnapshot(effectiveProjectPath);
+                        }
+                        const changes = await this.contextTreeSnapshotService.getChanges(effectiveProjectPath);
+                        const hasChanges = changes.added.length > 0 || changes.modified.length > 0 || changes.deleted.length > 0;
+                        if (hasChanges) {
+                            result.contextTreeStatus = 'has_changes';
+                            result.contextTreeChanges = {
+                                added: changes.added,
+                                deleted: changes.deleted,
+                                modified: changes.modified,
+                            };
+                        }
+                        else {
+                            result.contextTreeStatus = 'no_changes';
+                        }
                     }
                     else {
-                        result.contextTreeStatus = 'no_changes';
+                        result.contextTreeStatus = 'no_vc';
                     }
                 }
             }

package/dist/server/templates/skill/SKILL.md

@@ -34,7 +34,27 @@ Knowledge is stored in `.brv/context-tree/` as human-readable Markdown files.
 brv query "How is authentication implemented?"
 ```
 
-### 2. Curate Context
+### 2. Search Context Tree
+**Overview:** Retrieve a ranked list of matching files from `.brv/context-tree/` via pure BM25 lookup. Unlike `brv query`, this does NOT call an LLM — no synthesis, no token cost, no provider setup needed. Returns structured results with paths, scores, and excerpts.
+
+**Use this skill when:**
+- You need file paths to read rather than a synthesized answer
+- You want fast, cheap retrieval with no LLM overhead
+- You're in an automated pipeline that consumes structured results
+
+**Do NOT use this skill when:**
+- You need a natural-language answer synthesized from multiple files — use `brv query` instead
+- The information is already present in your current context
+
+```bash
+brv search "authentication patterns"
+brv search "JWT tokens" --limit 5 --scope "auth/"
+brv search "auth" --format json
+```
+
+**Flags:** `--limit N` (1-50, default 10), `--scope "domain/"` (path prefix filter), `--format json` (structured output for automation).
+
+### 3. Curate Context
 **Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.
 
 **Use this skill when:**
@@ -79,7 +99,7 @@ brv curate view --since 1h --status completed
 brv curate view --help
 ```
 
-### 3. Review Pending Changes
+### 4. Review Pending Changes
 **Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.
 
 **Use this when:**
@@ -142,7 +162,7 @@ brv review approve <taskId> --format json
 brv review reject <taskId> --format json
 ```
 
-### 4. LLM Provider Setup
+### 5. LLM Provider Setup
 `brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):
 
 ```bash
@@ -156,7 +176,7 @@ brv providers list
 brv providers connect openai --api-key sk-xxx --model gpt-4.1
 ```
 
-### 5. Project Locations
+### 6. Project Locations
 **Overview:** List registered projects and their context tree paths. Returns project metadata including initialization status and active state. Use `-f json` for machine-readable output.
 
 **Use this when:**
@@ -174,7 +194,7 @@ brv locations -f json
 
 JSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.
 
-### 6. Version Control
+### 7. Version Control
 **Overview:** `brv vc` provides git-based version control for your context tree. It uses standard git semantics — branching, committing, merging, history, and conflict resolution — all working locally with no authentication required. Remote sync with a team is optional. The legacy `brv push`, `brv pull`, and `brv space` commands are deprecated — use `brv vc push`, `brv vc pull`, and `brv vc clone`/`brv vc remote add` instead.
 
 **Use this when:**

package/dist/shared/transport/search-content.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Encode/decode helpers for search task content payloads.
+ *
+ * The transport layer's TaskCreateRequest has a single `content: string`
+ * field. For search tasks, we pack {query, limit?, scope?} as JSON so
+ * the agent process can reconstruct the structured options.
+ *
+ * Lives in shared/ because both the CLI (encoder) and the daemon
+ * agent-process (decoder) depend on it. Keeping it in oclif/ would
+ * create a circular dependency (server → oclif).
+ */
+/**
+ * Encode search options as JSON content payload for the transport layer.
+ */
+export declare function encodeSearchContent(options: {
+    limit?: number;
+    query: string;
+    scope?: string;
+}): string;
+/**
+ * Parse a JSON-encoded search content payload back into options.
+ * Falls back to treating the entire string as a plain query if parsing fails.
+ */
+export declare function decodeSearchContent(content: string): {
+    limit?: number;
+    query: string;
+    scope?: string;
+};

package/dist/shared/transport/search-content.js

@@ -0,0 +1,38 @@
+/**
+ * Encode/decode helpers for search task content payloads.
+ *
+ * The transport layer's TaskCreateRequest has a single `content: string`
+ * field. For search tasks, we pack {query, limit?, scope?} as JSON so
+ * the agent process can reconstruct the structured options.
+ *
+ * Lives in shared/ because both the CLI (encoder) and the daemon
+ * agent-process (decoder) depend on it. Keeping it in oclif/ would
+ * create a circular dependency (server → oclif).
+ */
+/**
+ * Encode search options as JSON content payload for the transport layer.
+ */
+export function encodeSearchContent(options) {
+    return JSON.stringify({
+        limit: options.limit,
+        query: options.query,
+        scope: options.scope,
+    });
+}
+/**
+ * Parse a JSON-encoded search content payload back into options.
+ * Falls back to treating the entire string as a plain query if parsing fails.
+ */
+export function decodeSearchContent(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return {
+            limit: typeof parsed.limit === 'number' ? parsed.limit : undefined,
+            query: typeof parsed.query === 'string' ? parsed.query : content,
+            scope: typeof parsed.scope === 'string' ? parsed.scope : undefined,
+        };
+    }
+    catch {
+        return { query: content };
+    }
+}

package/dist/shared/transport/types/dto.d.ts

@@ -133,7 +133,7 @@ export interface StatusDTO {
     contextTreeDir?: string;
     /** Relative path to the context tree directory from project root (e.g., '.brv/context-tree') */
     contextTreeRelativeDir?: string;
-    contextTreeStatus: 'git_vc' | 'has_changes' | 'no_changes' | 'not_initialized' | 'unknown';
+    contextTreeStatus: 'git_vc' | 'has_changes' | 'no_changes' | 'no_vc' | 'not_initialized' | 'unknown';
     /** @deprecated Use projectRoot instead. Kept for backward compatibility. */
     currentDirectory: string;
     /** Number of files with pending HITL review (0 if none or unavailable). */

package/dist/tui/features/status/utils/format-status.js

@@ -76,6 +76,10 @@ export function formatStatus(status, version) {
             lines.push('Context Tree: No changes');
             break;
         }
+        case 'no_vc': {
+            lines.push('Context Tree: Managed by Byterover version control (use /vc commands)');
+            break;
+        }
         case 'not_initialized': {
             lines.push('Context Tree: Not initialized');
             break;
@@ -89,5 +93,6 @@ export function formatStatus(status, version) {
         lines.push(chalk.yellow(`Pending Reviews: ${status.pendingReviewCount} ${fileLabel} need review`) +
             (status.reviewUrl ? `\n  Review: ${chalk.blue(status.reviewUrl)}` : ''));
     }
+    lines.push('', 'Tip: Version control is now available for your context tree.', 'Learn more: https://docs.byterover.dev/git-semantic/overview');
     return lines.join('\n');
 }

package/dist/tui/utils/error-messages.js

@@ -9,20 +9,20 @@
 const USER_FRIENDLY_MESSAGES = {
     ERR_AGENT_NOT_INITIALIZED: "Agent failed to initialize. Run 'brv restart' to force a clean restart.",
     ERR_CONTEXT_TREE_NOT_INIT: 'Context tree not initialized.',
+    ERR_LEGACY_SYNC_UNAVAILABLE: 'Legacy cloud sync (push/pull) is not available for this project. Use /vc init to start using version control. Learn more: https://docs.byterover.dev/git-semantic/overview',
     ERR_LOCAL_CHANGES_EXIST: 'You have local changes. Run /push to save your changes before pulling.',
     ERR_NOT_AUTHENTICATED: 'Not authenticated. This is required for cloud sync. Run /login to connect your account.',
     ERR_OAUTH_REFRESH_FAILED: 'OAuth token refresh failed. Run /providers to reconnect your provider.',
     ERR_OAUTH_TOKEN_EXPIRED: 'OAuth token has expired. Run /providers to reconnect your provider.',
     ERR_PROJECT_NOT_INIT: "Project not initialized. Run 'brv restart' to reinitialize.",
     ERR_PROVIDER_NOT_CONFIGURED: 'No provider connected. Run /providers connect byterover to use the free built-in provider, or connect another provider.',
-    ERR_SPACE_NOT_CONFIGURED: 'No space configured. Run /space switch to select a space first.',
     ERR_SPACE_NOT_FOUND: 'Space not found. Check your configuration.',
     ERR_VC_AUTH_FAILED: 'Authentication failed. Run /login.',
     ERR_VC_BRANCH_ALREADY_EXISTS: 'Branch already exists.',
     ERR_VC_CANNOT_DELETE_CURRENT_BRANCH: 'Cannot delete the currently checked-out branch.',
     ERR_VC_CONFIG_KEY_NOT_SET: 'Config key is not set.',
     ERR_VC_CONFLICT_MARKERS_PRESENT: 'Conflict markers detected. Run /vc conflicts to view them. Resolve conflicts and run /vc add before pushing.',
-    ERR_VC_GIT_INITIALIZED: 'ByteRover version control is active. Use /vc commands instead of legacy sync commands.',
+    ERR_VC_GIT_INITIALIZED: 'ByteRover version control is active. Use /vc commands instead of legacy sync commands. Learn more: https://docs.byterover.dev/git-semantic/overview',
     ERR_VC_GIT_NOT_INITIALIZED: 'ByteRover version control not initialized. Run /vc init first.',
     ERR_VC_INVALID_ACTION: 'Invalid action.',
     // ERR_VC_INVALID_BRANCH_NAME intentionally omitted: fall through to server's message with actual branch name