byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/tools/tool-registry.js

@@ -0,0 +1,144 @@
+import { ToolName } from '../../../core/domain/cipher/tools/constants.js';
+import { createBashExecTool } from './implementations/bash-exec-tool.js';
+import { createBashOutputTool } from './implementations/bash-output-tool.js';
+import { createCreateKnowledgeTopicTool } from './implementations/create-knowledge-topic-tool.js';
+import { createDeleteMemoryTool } from './implementations/delete-memory-tool.js';
+import { createDetectDomainsTool } from './implementations/detect-domains-tool.js';
+import { createEditFileTool } from './implementations/edit-file-tool.js';
+import { createEditMemoryTool } from './implementations/edit-memory-tool.js';
+import { createFindKnowledgeTopicsTool } from './implementations/find-knowledge-topics-tool.js';
+import { createGlobFilesTool } from './implementations/glob-files-tool.js';
+import { createGrepContentTool } from './implementations/grep-content-tool.js';
+import { createKillProcessTool } from './implementations/kill-process-tool.js';
+import { createListMemoriesTool } from './implementations/list-memories-tool.js';
+import { createReadFileTool } from './implementations/read-file-tool.js';
+import { createReadMemoryTool } from './implementations/read-memory-tool.js';
+import { createSearchHistoryTool } from './implementations/search-history-tool.js';
+import { createWriteFileTool } from './implementations/write-file-tool.js';
+import { createWriteMemoryTool } from './implementations/write-memory-tool.js';
+import { createWriteTodosTool } from './implementations/write-todos-tool.js';
+import { ToolMarker } from './tool-markers.js';
+/**
+ * Helper function to safely retrieve a required service.
+ * Throws a descriptive error if the service is not available.
+ *
+ * @param service - The service to retrieve
+ * @param serviceName - Name of the service for error messages
+ * @returns The service if available
+ * @throws Error if service is undefined
+ */
+function getRequiredService(service, serviceName) {
+    if (!service) {
+        throw new Error(`Required service '${serviceName}' is not available. This is a bug.`);
+    }
+    return service;
+}
+/**
+ * Central registry of all tools.
+ * Maps tool names to their factory functions and required services.
+ *
+ * To add a new tool:
+ * 1. Add tool name to ToolName constants
+ * 2. Create tool implementation file
+ * 3. Add entry to this registry
+ */
+export const TOOL_REGISTRY = {
+    [ToolName.BASH_EXEC]: {
+        factory: (services) => createBashExecTool(getRequiredService(services.processService, 'processService')),
+        markers: [ToolMarker.Execution],
+        requiredServices: ['processService'],
+    },
+    [ToolName.BASH_OUTPUT]: {
+        factory: (services) => createBashOutputTool(getRequiredService(services.processService, 'processService')),
+        markers: [ToolMarker.Execution, ToolMarker.Optional],
+        requiredServices: ['processService'],
+    },
+    [ToolName.CREATE_KNOWLEDGE_TOPIC]: {
+        factory: () => createCreateKnowledgeTopicTool(),
+        markers: [ToolMarker.ContextBuilding],
+        outputGuidance: 'create_knowledge_topic',
+        requiredServices: [], // Uses DirectoryManager for file operations
+    },
+    [ToolName.DELETE_MEMORY]: {
+        factory: (services) => createDeleteMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
+        markers: [ToolMarker.ContextBuilding],
+        outputGuidance: 'delete_memory',
+        requiredServices: ['memoryManager'],
+    },
+    [ToolName.DETECT_DOMAINS]: {
+        factory: () => createDetectDomainsTool(),
+        markers: [ToolMarker.ContextBuilding],
+        outputGuidance: 'detect_domains',
+        requiredServices: [], // No services required (validates LLM-detected domains)
+    },
+    [ToolName.EDIT_FILE]: {
+        factory: (services) => createEditFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        markers: [ToolMarker.Modification],
+        requiredServices: ['fileSystemService'],
+    },
+    [ToolName.EDIT_MEMORY]: {
+        factory: (services) => createEditMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
+        markers: [ToolMarker.ContextBuilding],
+        outputGuidance: 'edit_memory',
+        requiredServices: ['memoryManager'],
+    },
+    [ToolName.FIND_KNOWLEDGE_TOPICS]: {
+        factory: () => createFindKnowledgeTopicsTool(),
+        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
+        outputGuidance: 'find_knowledge_topics',
+        requiredServices: [], // Uses DirectoryManager for file operations
+    },
+    [ToolName.GLOB_FILES]: {
+        factory: (services) => createGlobFilesTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        markers: [ToolMarker.Core, ToolMarker.Discovery],
+        requiredServices: ['fileSystemService'],
+    },
+    [ToolName.GREP_CONTENT]: {
+        factory: (services) => createGrepContentTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        markers: [ToolMarker.Core, ToolMarker.Discovery],
+        requiredServices: ['fileSystemService'],
+    },
+    [ToolName.KILL_PROCESS]: {
+        factory: (services) => createKillProcessTool(getRequiredService(services.processService, 'processService')),
+        markers: [ToolMarker.Execution, ToolMarker.Optional],
+        requiredServices: ['processService'],
+    },
+    [ToolName.LIST_MEMORIES]: {
+        factory: (services) => createListMemoriesTool(getRequiredService(services.memoryManager, 'memoryManager')),
+        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
+        outputGuidance: 'list_memories',
+        requiredServices: ['memoryManager'],
+    },
+    [ToolName.READ_FILE]: {
+        factory: (services) => createReadFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        markers: [ToolMarker.Core, ToolMarker.Discovery],
+        requiredServices: ['fileSystemService'],
+    },
+    [ToolName.READ_MEMORY]: {
+        factory: (services) => createReadMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
+        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
+        outputGuidance: 'read_memory',
+        requiredServices: ['memoryManager'],
+    },
+    [ToolName.SEARCH_HISTORY]: {
+        factory: (_services) => createSearchHistoryTool(),
+        markers: [ToolMarker.ContextBuilding, ToolMarker.Discovery],
+        requiredServices: [], // No services required yet (stub implementation)
+    },
+    [ToolName.WRITE_FILE]: {
+        factory: (services) => createWriteFileTool(getRequiredService(services.fileSystemService, 'fileSystemService')),
+        markers: [ToolMarker.Modification],
+        requiredServices: ['fileSystemService'],
+    },
+    [ToolName.WRITE_MEMORY]: {
+        factory: (services) => createWriteMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
+        markers: [ToolMarker.ContextBuilding],
+        outputGuidance: 'write_memory',
+        requiredServices: ['memoryManager'],
+    },
+    [ToolName.WRITE_TODOS]: {
+        factory: () => createWriteTodosTool(),
+        markers: [ToolMarker.Planning, ToolMarker.Core],
+        requiredServices: [], // No services required (stateless tool)
+    },
+};

package/dist/infra/cipher/tools/utils/schema-converter.d.ts

@@ -0,0 +1,10 @@
+import type { ZodSchema } from 'zod';
+import type { JSONSchema7 } from '../../../../core/domain/cipher/tools/types.js';
+/**
+ * Convert a Zod schema to JSON Schema v7.
+ * Used to expose tool schemas to the LLM.
+ *
+ * @param zodSchema - Zod schema to convert
+ * @returns JSON Schema v7 representation
+ */
+export declare function convertZodToJsonSchema(zodSchema: ZodSchema): JSONSchema7;

package/dist/infra/cipher/tools/utils/schema-converter.js

@@ -0,0 +1,29 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { getErrorMessage } from '../../../../utils/error-helpers.js';
+/**
+ * Convert a Zod schema to JSON Schema v7.
+ * Used to expose tool schemas to the LLM.
+ *
+ * @param zodSchema - Zod schema to convert
+ * @returns JSON Schema v7 representation
+ */
+export function convertZodToJsonSchema(zodSchema) {
+    try {
+        // Convert using zod-to-json-schema library
+        const jsonSchema = zodToJsonSchema(zodSchema, {
+            // Remove $schema field as it's not needed for tool definitions
+            $refStrategy: 'none',
+        });
+        // Cast to JSONSchema7 (zod-to-json-schema returns compatible format)
+        return jsonSchema;
+    }
+    catch (error) {
+        // Fallback to basic object schema if conversion fails
+        console.warn(`Failed to convert Zod schema to JSON Schema: ${getErrorMessage(error)}`);
+        return {
+            additionalProperties: false,
+            properties: {},
+            type: 'object',
+        };
+    }
+}

package/dist/infra/cipher/validation/workspace-validator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Error thrown when ByteRover workspace is not initialized.
+ */
+export declare class WorkspaceNotInitializedError extends Error {
+    /** The expected workspace directory path */
+    readonly expectedPath: string;
+    constructor(message: string, expectedPath: string);
+}
+/**
+ * Validates that the ByteRover workspace is properly initialized.
+ *
+ * Checks for the existence of:
+ * - `.brv` directory (created by `brv init`)
+ * - `.brv/blobs` directory (for blob storage)
+ *
+ * @param workingDirectory - The working directory to check (defaults to process.cwd())
+ * @throws WorkspaceNotInitializedError if workspace is not initialized
+ */
+export declare function validateWorkspaceInitialized(workingDirectory?: string): void;

package/dist/infra/cipher/validation/workspace-validator.js

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Error thrown when ByteRover workspace is not initialized.
+ */
+export class WorkspaceNotInitializedError extends Error {
+    /** The expected workspace directory path */
+    expectedPath;
+    constructor(message, expectedPath) {
+        super(message);
+        this.name = 'WorkspaceNotInitializedError';
+        this.expectedPath = expectedPath;
+    }
+}
+/**
+ * Validates that the ByteRover workspace is properly initialized.
+ *
+ * Checks for the existence of:
+ * - `.brv` directory (created by `brv init`)
+ * - `.brv/blobs` directory (for blob storage)
+ *
+ * @param workingDirectory - The working directory to check (defaults to process.cwd())
+ * @throws WorkspaceNotInitializedError if workspace is not initialized
+ */
+export function validateWorkspaceInitialized(workingDirectory) {
+    const cwd = workingDirectory ?? process.cwd();
+    const brvDir = join(cwd, '.brv');
+    const blobsDir = join(cwd, '.brv', 'blobs');
+    // Check if .brv directory exists
+    if (!existsSync(brvDir)) {
+        throw new WorkspaceNotInitializedError('Workspace not initialized', brvDir);
+    }
+    // Check if .brv/blobs directory exists
+    if (!existsSync(blobsDir)) {
+        throw new WorkspaceNotInitializedError('Blob storage directory not found', blobsDir);
+    }
+}

package/dist/infra/cipher/watcher/coding-agent-log-watcher.d.ts

@@ -0,0 +1,14 @@
+import type { ICodingAgentLogParser } from '../../../core/interfaces/cipher/i-coding-agent-log-parser.js';
+import type { CodingAgentLogWatcherOptions, ICodingAgentLogWatcher } from '../../../core/interfaces/cipher/i-coding-agent-log-watcher.js';
+import type { IFileWatcherService } from '../../../core/interfaces/i-file-watcher-service.js';
+export declare class CodingAgentLogWatcher implements ICodingAgentLogWatcher {
+    private callback;
+    private readonly fileWatcher;
+    private readonly parser;
+    private watching;
+    constructor(fileWatcher: IFileWatcherService, parser: ICodingAgentLogParser);
+    isWatching(): boolean;
+    start(options: CodingAgentLogWatcherOptions): Promise<void>;
+    stop(): Promise<void>;
+    private handleFileEvent;
+}

package/dist/infra/cipher/watcher/coding-agent-log-watcher.js

@@ -0,0 +1,55 @@
+export class CodingAgentLogWatcher {
+    callback;
+    fileWatcher;
+    parser;
+    watching;
+    constructor(fileWatcher, parser) {
+        this.watching = false;
+        this.fileWatcher = fileWatcher;
+        this.parser = parser;
+    }
+    isWatching() {
+        return this.watching;
+    }
+    async start(options) {
+        if (this.watching) {
+            throw new Error('Already watching. Stop the watcher before starting again.');
+        }
+        this.callback = options.onCleanSession;
+        this.watching = true;
+        this.fileWatcher.setFileEventHandler(async (event) => {
+            await this.handleFileEvent(event, options.codingAgentInfo.name);
+        });
+        await this.fileWatcher.start([options.codingAgentInfo.chatLogPath]);
+    }
+    async stop() {
+        if (!this.watching) {
+            return;
+        }
+        await this.fileWatcher.stop();
+        this.callback = undefined;
+        this.watching = false;
+    }
+    async handleFileEvent(event, codingAgent) {
+        try {
+            if (event.type !== 'add' && event.type !== 'change') {
+                return;
+            }
+            const sessions = await this.parser.parse(event.path, codingAgent);
+            if (this.callback !== undefined) {
+                for (const session of sessions) {
+                    try {
+                        // eslint-disable-next-line no-await-in-loop
+                        await this.callback(session);
+                    }
+                    catch (error) {
+                        console.error(`[CodingAgentLogWatcher] Error in session callback: ${error}`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[CodingAgentLogWatcher] Error processing file ${event.path}: ${error}`);
+        }
+    }
+}

package/dist/infra/cogit/context-tree-to-push-context-mapper.d.ts

@@ -0,0 +1,21 @@
+import type { ContextFileContent } from '../../core/interfaces/i-context-file-reader.js';
+import { CogitPushContext } from '../../core/domain/entities/cogit-push-context.js';
+/**
+ * Parameters for mapping context files to push contexts.
+ */
+export type MapToPushContextsParams = {
+    /** Files to be added (new files) */
+    addedFiles: ContextFileContent[];
+    /** Paths of files to be deleted (only path needed, files no longer exist) */
+    deletedPaths: string[];
+    /** Files to be edited (modified files) */
+    modifiedFiles: ContextFileContent[];
+};
+/**
+ * Maps context file contents to CogitPushContext instances for the CoGit API.
+ * Converts file reader output to the format expected by the push service.
+ *
+ * @param params - The mapping parameters containing files to process
+ * @returns Array of CogitPushContext instances ready for the push API
+ */
+export declare const mapToPushContexts: (params: MapToPushContextsParams) => CogitPushContext[];

package/dist/infra/cogit/context-tree-to-push-context-mapper.js

@@ -0,0 +1,32 @@
+import { CogitPushContext } from '../../core/domain/entities/cogit-push-context.js';
+/**
+ * Maps context file contents to CogitPushContext instances for the CoGit API.
+ * Converts file reader output to the format expected by the push service.
+ *
+ * @param params - The mapping parameters containing files to process
+ * @returns Array of CogitPushContext instances ready for the push API
+ */
+export const mapToPushContexts = (params) => {
+    const addedContextFiles = params.addedFiles.map((file) => new CogitPushContext({
+        content: file.content,
+        operation: 'add',
+        path: `/${file.path}`,
+        tags: [],
+        title: file.title,
+    }));
+    const editedContextFiles = params.modifiedFiles.map((file) => new CogitPushContext({
+        content: file.content,
+        operation: 'edit',
+        path: `/${file.path}`,
+        tags: [],
+        title: file.title,
+    }));
+    const deletedContextFiles = params.deletedPaths.map((path) => new CogitPushContext({
+        content: '',
+        operation: 'delete',
+        path: `/${path}`,
+        tags: [],
+        title: '',
+    }));
+    return [...addedContextFiles, ...editedContextFiles, ...deletedContextFiles];
+};

package/dist/infra/cogit/http-cogit-pull-service.d.ts

@@ -0,0 +1,15 @@
+import type { ICogitPullService, PullParams } from '../../core/interfaces/i-cogit-pull-service.js';
+import { CogitSnapshot } from '../../core/domain/entities/cogit-snapshot.js';
+export type HttpCogitPullServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+/**
+ * HTTP implementation of ICogitPullService for ByteRover CoGit service.
+ * Fetches context tree snapshots from a CoGit repository.
+ */
+export declare class HttpCogitPullService implements ICogitPullService {
+    private readonly config;
+    constructor(config: HttpCogitPullServiceConfig);
+    pull(params: PullParams): Promise<CogitSnapshot>;
+}

package/dist/infra/cogit/http-cogit-pull-service.js

@@ -0,0 +1,30 @@
+import { CogitSnapshot } from '../../core/domain/entities/cogit-snapshot.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+/**
+ * HTTP implementation of ICogitPullService for ByteRover CoGit service.
+ * Fetches context tree snapshots from a CoGit repository.
+ */
+export class HttpCogitPullService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 30_000,
+        };
+    }
+    async pull(params) {
+        const baseUrl = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/git/snapshot`;
+        const url = `${baseUrl}?branch=${encodeURIComponent(params.branch)}`;
+        const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+        try {
+            const response = await httpClient.get(url, {
+                timeout: this.config.timeout,
+            });
+            return CogitSnapshot.fromJson(response);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to pull from CoGit: ${message}`);
+        }
+    }
+}

package/dist/infra/cogit/http-cogit-push-service.d.ts

@@ -0,0 +1,17 @@
+import type { ICogitPushService, PushParams } from '../../core/interfaces/i-cogit-push-service.js';
+import { CogitPushResponse } from '../../core/domain/entities/cogit-push-response.js';
+export type HttpCogitPushServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+/**
+ * HTTP implementation of ICogitPushService for ByteRover CoGit service.
+ * Implements a two-request SHA flow to handle concurrent updates.
+ */
+export declare class HttpCogitPushService implements ICogitPushService {
+    private readonly config;
+    constructor(config: HttpCogitPushServiceConfig);
+    push(params: PushParams): Promise<CogitPushResponse>;
+    private extractShaFromError;
+    private makeRequest;
+}

package/dist/infra/cogit/http-cogit-push-service.js

@@ -0,0 +1,104 @@
+/* eslint-disable camelcase */
+import axios from 'axios';
+import { CogitPushResponse } from '../../core/domain/entities/cogit-push-response.js';
+import { getErrorMessage } from '../../utils/error-helpers.js';
+/**
+ * Extracts the current SHA from an error response details field.
+ * Error format: "...Expected SHA 'xxx' but current SHA is 'yyy'..."
+ * @param details The error details string
+ * @returns The extracted SHA or undefined if not found
+ */
+const extractShaFromErrorDetails = (details) => {
+    const shaMatch = /SHA is '([a-f0-9]+)'/i.exec(details);
+    return shaMatch?.[1];
+};
+/**
+ * HTTP implementation of ICogitPushService for ByteRover CoGit service.
+ * Implements a two-request SHA flow to handle concurrent updates.
+ */
+export class HttpCogitPushService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 30_000,
+        };
+    }
+    async push(params) {
+        const url = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/commits`;
+        const memories = params.contexts.map((context) => ({
+            content: context.content,
+            operation: context.operation,
+            path: context.path,
+            tags: [...context.tags],
+            title: context.title,
+        }));
+        // First request: Send with empty current_sha
+        // This is a temporary workaround to let CoGit determine the current SHA.
+        // In the future, we need to generate the SHA from the CLI.
+        try {
+            const response = await this.makeRequest({
+                accessToken: params.accessToken,
+                branch: params.branch,
+                currentSha: '',
+                memories,
+                sessionKey: params.sessionKey,
+                url,
+            });
+            return response;
+        }
+        catch (error) {
+            // Try to extract SHA from error response
+            const sha = this.extractShaFromError(error);
+            if (!sha) {
+                throw new Error(`Failed to push to CoGit: ${getErrorMessage(error)}`);
+            }
+            // Second request: Retry with extracted SHA
+            try {
+                const response = await this.makeRequest({
+                    accessToken: params.accessToken,
+                    branch: params.branch,
+                    currentSha: sha,
+                    memories,
+                    sessionKey: params.sessionKey,
+                    url,
+                });
+                return response;
+            }
+            catch (retryError) {
+                throw new Error(`Failed to push to CoGit: ${getErrorMessage(retryError)}`);
+            }
+        }
+    }
+    extractShaFromError(error) {
+        // Check if error has response data with details
+        if (error &&
+            typeof error === 'object' &&
+            'response' in error &&
+            error.response &&
+            typeof error.response === 'object' &&
+            'data' in error.response) {
+            const errorResponse = error.response.data;
+            if (errorResponse.details) {
+                return extractShaFromErrorDetails(errorResponse.details);
+            }
+        }
+        return undefined;
+    }
+    async makeRequest(params) {
+        const requestBody = {
+            branch: params.branch,
+            current_sha: params.currentSha,
+            memories: params.memories,
+        };
+        // Directly use axios here because of the work around to get current SHA from CoGit's error response
+        const response = await axios.post(params.url, requestBody, {
+            headers: {
+                Authorization: `Bearer ${params.accessToken}`,
+                'x-byterover-session-id': params.sessionKey,
+            },
+            timeout: this.config.timeout,
+        });
+        return CogitPushResponse.fromJson(response.data);
+    }
+}

package/dist/infra/config/file-config-store.js

@@ -3,6 +3,8 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { BRV_DIR, PROJECT_CONFIG_FILE } from '../../constants.js';
 import { BrvConfig } from '../../core/domain/entities/brv-config.js';
+import { BrvConfigVersionError } from '../../core/domain/errors/brv-config-version-error.js';
+import { getErrorMessage } from '../../utils/error-helpers.js';
 /**
  * File-based implementation of IProjectConfigStore.
  * Stores configuration in .brv/config.json in the project directory.
@@ -23,21 +25,25 @@ export class ProjectConfigStore {
             return BrvConfig.fromJson(json);
         }
         catch (error) {
-            throw new Error(`Failed to read config from ${configPath}: ${error.message}`);
+            if (error instanceof BrvConfigVersionError) {
+                throw error;
+            }
+            throw new Error(`Failed to read config from ${configPath}: ${getErrorMessage(error)}`);
         }
     }
     async write(config, directory) {
         const brDirPath = this.getBrvDirPath(directory);
         const configPath = this.getConfigPath(directory);
         try {
-            // Create .brv directory if it doesn't exist
+            // Create .brv directory and blobs subdirectory if they don't exist
             await mkdir(brDirPath, { recursive: true });
+            await mkdir(join(brDirPath, 'blobs'), { recursive: true });
             // Write config.json
             const content = JSON.stringify(config.toJson(), undefined, 2);
             await writeFile(configPath, content, 'utf8');
         }
         catch (error) {
-            throw new Error(`Failed to write config to ${configPath}: ${error.message}`);
+            throw new Error(`Failed to write config to ${configPath}: ${getErrorMessage(error)}`);
         }
     }
     /**

package/dist/infra/context-tree/file-context-file-reader.d.ts

@@ -0,0 +1,14 @@
+import type { ContextFileContent, IContextFileReader } from '../../core/interfaces/i-context-file-reader.js';
+export type FileContextFileReaderConfig = {
+    baseDirectory?: string;
+};
+/**
+ * File-based implementation of IContextFileReader.
+ * Reads context.md files from the context tree and extracts their metadata.
+ */
+export declare class FileContextFileReader implements IContextFileReader {
+    private readonly config;
+    constructor(config?: FileContextFileReaderConfig);
+    read(relativePath: string, directory?: string): Promise<ContextFileContent | undefined>;
+    readMany(relativePaths: string[], directory?: string): Promise<ContextFileContent[]>;
+}

package/dist/infra/context-tree/file-context-file-reader.js

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
+/**
+ * Extracts the title from the first markdown heading in the content.
+ * @param content - The file content
+ * @param fallbackTitle - The title to use if no heading is found
+ * @returns The extracted title or fallback
+ */
+const extractTitle = (content, fallbackTitle) => {
+    // Match the first line that starts with "# " (level 1 heading)
+    const match = /^# (.+)$/m.exec(content);
+    return match ? match[1].trim() : fallbackTitle;
+};
+/**
+ * File-based implementation of IContextFileReader.
+ * Reads context.md files from the context tree and extracts their metadata.
+ */
+export class FileContextFileReader {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    async read(relativePath, directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const fullPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, relativePath);
+        try {
+            const content = await readFile(fullPath, 'utf8');
+            const title = extractTitle(content, relativePath);
+            return {
+                content,
+                path: relativePath,
+                title,
+            };
+        }
+        catch {
+            // File doesn't exist or can't be read
+            return undefined;
+        }
+    }
+    async readMany(relativePaths, directory) {
+        const results = await Promise.all(relativePaths.map((path) => this.read(path, directory)));
+        // Filter out undefined results (files that couldn't be read)
+        return results.filter((result) => result !== undefined);
+    }
+}

package/dist/infra/context-tree/file-context-tree-service.d.ts

@@ -0,0 +1,14 @@
+import type { IContextTreeService } from '../../core/interfaces/i-context-tree-service.js';
+export type ContextTreeServiceConfig = {
+    baseDirectory?: string;
+};
+/**
+ * File-based implementation of IContextTreeService.
+ * Provides operations for managing the context tree structure.
+ */
+export declare class FileContextTreeService implements IContextTreeService {
+    private readonly config;
+    constructor(config?: ContextTreeServiceConfig);
+    exists(directory?: string): Promise<boolean>;
+    initialize(directory?: string): Promise<string>;
+}