byterover-cli 0.3.4 → 0.4.0

package/dist/infra/cipher/tools/implementations/curate-tool.js

@@ -0,0 +1,371 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+import { DirectoryManager } from '../../../../core/domain/knowledge/directory-manager.js';
+import { MarkdownWriter } from '../../../../core/domain/knowledge/markdown-writer.js';
+import { sanitizeFolderName } from '../../../../utils/file-helpers.js';
+/**
+ * Operation types for curating knowledge topics.
+ * Inspired by ACE Curator patterns.
+ */
+const OperationType = z.enum(['ADD', 'UPDATE', 'MERGE', 'DELETE']);
+/**
+ * Content structure for ADD and UPDATE operations.
+ */
+const ContentSchema = z.object({
+    relations: z
+        .array(z.string())
+        .optional()
+        .describe('Related topics using @domain/topic or @domain/topic/subtopic notation'),
+    snippets: z.array(z.string()).optional().describe('Code/text snippets'),
+});
+/**
+ * Single operation schema for curating knowledge.
+ */
+const OperationSchema = z.object({
+    content: ContentSchema.optional().describe('Content for ADD/UPDATE operations'),
+    mergeTarget: z.string().optional().describe('Target path for MERGE operation'),
+    path: z.string().describe('Path: domain/topic or domain/topic/subtopic'),
+    reason: z.string().describe('Reasoning for this operation'),
+    type: OperationType.describe('Operation type: ADD, UPDATE, MERGE, or DELETE'),
+});
+/**
+ * Input schema for curate tool.
+ */
+const CurateInputSchema = z.object({
+    basePath: z.string().default('.brv/context-tree').describe('Base path for knowledge storage'),
+    operations: z.array(OperationSchema).describe('Array of curate operations to apply'),
+});
+/**
+ * Parse a path into domain, topic, and optional subtopic.
+ */
+function parsePath(path) {
+    const parts = path.split('/');
+    if (parts.length < 2 || parts.length > 3) {
+        return null;
+    }
+    return {
+        domain: parts[0],
+        subtopic: parts[2],
+        topic: parts[1],
+    };
+}
+/**
+ * Build the full filesystem path from base path and knowledge path.
+ */
+function buildFullPath(basePath, knowledgePath) {
+    const parsed = parsePath(knowledgePath);
+    if (!parsed) {
+        throw new Error(`Invalid path format: ${knowledgePath}`);
+    }
+    const domainPath = join(basePath, sanitizeFolderName(parsed.domain));
+    const topicPath = join(domainPath, sanitizeFolderName(parsed.topic));
+    if (parsed.subtopic) {
+        return join(topicPath, sanitizeFolderName(parsed.subtopic));
+    }
+    return topicPath;
+}
+/**
+ * Execute ADD operation - create new domain/topic/subtopic with context.md
+ */
+async function executeAdd(basePath, operation) {
+    const { content, path, reason } = operation;
+    if (!content) {
+        return {
+            message: 'ADD operation requires content',
+            path,
+            status: 'failed',
+            type: 'ADD',
+        };
+    }
+    try {
+        const parsed = parsePath(path);
+        if (!parsed) {
+            return {
+                message: `Invalid path format: ${path}. Expected domain/topic or domain/topic/subtopic`,
+                path,
+                status: 'failed',
+                type: 'ADD',
+            };
+        }
+        // Ensure base structure exists
+        await DirectoryManager.ensureKnowledgeStructure(basePath);
+        // Create domain folder
+        const domainPath = join(basePath, sanitizeFolderName(parsed.domain));
+        await DirectoryManager.createOrUpdateDomain(domainPath);
+        // Create topic folder
+        const topicPath = join(domainPath, sanitizeFolderName(parsed.topic));
+        await DirectoryManager.createOrUpdateTopic(topicPath);
+        // Determine final path (topic or subtopic)
+        let finalPath = topicPath;
+        if (parsed.subtopic) {
+            finalPath = join(topicPath, sanitizeFolderName(parsed.subtopic));
+            await DirectoryManager.createOrUpdateTopic(finalPath);
+        }
+        // Generate and write context.md
+        const contextContent = MarkdownWriter.generateContext({
+            name: parsed.subtopic || parsed.topic,
+            relations: content.relations,
+            snippets: content.snippets || [],
+        });
+        const contextPath = join(finalPath, 'context.md');
+        await DirectoryManager.writeFileAtomic(contextPath, contextContent);
+        return {
+            message: `Created ${path} with ${content.snippets?.length || 0} snippets. Reason: ${reason}`,
+            path,
+            status: 'success',
+            type: 'ADD',
+        };
+    }
+    catch (error) {
+        return {
+            message: error instanceof Error ? error.message : String(error),
+            path,
+            status: 'failed',
+            type: 'ADD',
+        };
+    }
+}
+/**
+ * Execute UPDATE operation - modify existing context.md
+ */
+async function executeUpdate(basePath, operation) {
+    const { content, path, reason } = operation;
+    if (!content) {
+        return {
+            message: 'UPDATE operation requires content',
+            path,
+            status: 'failed',
+            type: 'UPDATE',
+        };
+    }
+    try {
+        const fullPath = buildFullPath(basePath, path);
+        const contextPath = join(fullPath, 'context.md');
+        // Check if topic exists
+        const exists = await DirectoryManager.fileExists(contextPath);
+        if (!exists) {
+            return {
+                message: `Topic does not exist: ${path}`,
+                path,
+                status: 'failed',
+                type: 'UPDATE',
+            };
+        }
+        // Generate and write updated context.md (full replacement)
+        const parsed = parsePath(path);
+        const contextContent = MarkdownWriter.generateContext({
+            name: parsed?.subtopic || parsed?.topic || path,
+            relations: content.relations,
+            snippets: content.snippets || [],
+        });
+        await DirectoryManager.writeFileAtomic(contextPath, contextContent);
+        return {
+            message: `Updated ${path}. Reason: ${reason}`,
+            path,
+            status: 'success',
+            type: 'UPDATE',
+        };
+    }
+    catch (error) {
+        return {
+            message: error instanceof Error ? error.message : String(error),
+            path,
+            status: 'failed',
+            type: 'UPDATE',
+        };
+    }
+}
+/**
+ * Execute MERGE operation - combine source into target, delete source
+ */
+async function executeMerge(basePath, operation) {
+    const { mergeTarget, path, reason } = operation;
+    if (!mergeTarget) {
+        return {
+            message: 'MERGE operation requires mergeTarget',
+            path,
+            status: 'failed',
+            type: 'MERGE',
+        };
+    }
+    try {
+        const sourcePath = buildFullPath(basePath, path);
+        const targetPath = buildFullPath(basePath, mergeTarget);
+        const sourceContextPath = join(sourcePath, 'context.md');
+        const targetContextPath = join(targetPath, 'context.md');
+        // Check if both exist
+        const sourceExists = await DirectoryManager.fileExists(sourceContextPath);
+        const targetExists = await DirectoryManager.fileExists(targetContextPath);
+        if (!sourceExists) {
+            return {
+                message: `Source topic does not exist: ${path}`,
+                path,
+                status: 'failed',
+                type: 'MERGE',
+            };
+        }
+        if (!targetExists) {
+            return {
+                message: `Target topic does not exist: ${mergeTarget}`,
+                path,
+                status: 'failed',
+                type: 'MERGE',
+            };
+        }
+        // Read both contexts
+        const sourceContent = await DirectoryManager.readFile(sourceContextPath);
+        const targetContent = await DirectoryManager.readFile(targetContextPath);
+        // Merge the contexts using MarkdownWriter
+        const mergedContent = MarkdownWriter.mergeContexts(sourceContent, targetContent);
+        await DirectoryManager.writeFileAtomic(targetContextPath, mergedContent);
+        // Delete source folder
+        await DirectoryManager.deleteTopicRecursive(sourcePath);
+        return {
+            message: `Merged ${path} into ${mergeTarget}. Reason: ${reason}`,
+            path,
+            status: 'success',
+            type: 'MERGE',
+        };
+    }
+    catch (error) {
+        return {
+            message: error instanceof Error ? error.message : String(error),
+            path,
+            status: 'failed',
+            type: 'MERGE',
+        };
+    }
+}
+/**
+ * Execute DELETE operation - remove topic/subtopic folder recursively
+ */
+async function executeDelete(basePath, operation) {
+    const { path, reason } = operation;
+    try {
+        const fullPath = buildFullPath(basePath, path);
+        const contextPath = join(fullPath, 'context.md');
+        // Check if topic exists
+        const exists = await DirectoryManager.fileExists(contextPath);
+        if (!exists) {
+            return {
+                message: `Topic does not exist: ${path}`,
+                path,
+                status: 'failed',
+                type: 'DELETE',
+            };
+        }
+        // Delete folder recursively
+        await DirectoryManager.deleteTopicRecursive(fullPath);
+        return {
+            message: `Deleted ${path}. Reason: ${reason}`,
+            path,
+            status: 'success',
+            type: 'DELETE',
+        };
+    }
+    catch (error) {
+        return {
+            message: error instanceof Error ? error.message : String(error),
+            path,
+            status: 'failed',
+            type: 'DELETE',
+        };
+    }
+}
+/**
+ * Execute curate operations on knowledge topics.
+ */
+async function executeCurate(input, _context) {
+    const { basePath, operations } = input;
+    const applied = [];
+    const summary = {
+        added: 0,
+        deleted: 0,
+        failed: 0,
+        merged: 0,
+        updated: 0,
+    };
+    // Process operations sequentially to maintain consistency
+    /* eslint-disable no-await-in-loop -- Sequential processing required for dependent operations */
+    for (const operation of operations) {
+        let result;
+        switch (operation.type) {
+            case 'ADD': {
+                result = await executeAdd(basePath, operation);
+                if (result.status === 'success')
+                    summary.added++;
+                break;
+            }
+            case 'DELETE': {
+                result = await executeDelete(basePath, operation);
+                if (result.status === 'success')
+                    summary.deleted++;
+                break;
+            }
+            case 'MERGE': {
+                result = await executeMerge(basePath, operation);
+                if (result.status === 'success')
+                    summary.merged++;
+                break;
+            }
+            case 'UPDATE': {
+                result = await executeUpdate(basePath, operation);
+                if (result.status === 'success')
+                    summary.updated++;
+                break;
+            }
+            default: {
+                result = {
+                    message: `Unknown operation type: ${operation.type}`,
+                    path: operation.path,
+                    status: 'failed',
+                    type: operation.type,
+                };
+            }
+        }
+        if (result.status === 'failed') {
+            summary.failed++;
+        }
+        applied.push(result);
+    }
+    /* eslint-enable no-await-in-loop */
+    return { applied, summary };
+}
+/**
+ * Creates the curate tool.
+ *
+ * This tool manages knowledge topics with atomic operations (ADD, UPDATE, MERGE, DELETE).
+ * It applies patterns from the ACE Curator for intelligent knowledge curation.
+ *
+ * @returns Configured curate tool
+ */
+export function createCurateTool() {
+    return {
+        description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types:
+
+**Operations:**
+1. **ADD** - Create new domain/topic/subtopic with context.md
+   - Requires: path, content (snippets and/or relations), reason
+   - Example: { type: "ADD", path: "code_style/error-handling", content: { snippets: ["..."], relations: ["logging/basics"] }, reason: "New pattern identified" }
+
+2. **UPDATE** - Modify existing context.md (full replacement)
+   - Requires: path, content, reason
+   - Example: { type: "UPDATE", path: "code_style/error-handling", content: { snippets: ["Updated content"] }, reason: "Improved guidance" }
+
+3. **MERGE** - Combine source topic into target, delete source
+   - Requires: path (source), mergeTarget (destination), reason
+   - Example: { type: "MERGE", path: "code_style/old-topic", mergeTarget: "code_style/new-topic", reason: "Consolidating duplicates" }
+
+4. **DELETE** - Remove topic/subtopic folder recursively
+   - Requires: path, reason
+   - Example: { type: "DELETE", path: "code_style/deprecated-topic", reason: "No longer relevant" }
+
+**Path format:** domain/topic or domain/topic/subtopic
+
+**Output:** Returns applied operations with status (success/failed) and a summary of counts.`,
+        execute: executeCurate,
+        id: ToolName.CURATE,
+        inputSchema: CurateInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/find-knowledge-topics-tool.js

@@ -1,5 +1,6 @@
 import { join } from 'node:path';
 import { z } from 'zod';
+import { BRV_DIR, CONTEXT_FILE, CONTEXT_TREE_DIR } from '../../../../constants.js';
 import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
 import { DirectoryManager } from '../../../../core/domain/knowledge/directory-manager.js';
 import { parseRelations } from '../../../../core/domain/knowledge/relation-parser.js';
@@ -10,7 +11,7 @@ import { parseRelations } from '../../../../core/domain/knowledge/relation-parse
 const FindKnowledgeTopicsInputSchema = z.object({
     basePath: z
         .string()
-        .default('.brv/context-tree')
+        .default(`${BRV_DIR}/${CONTEXT_TREE_DIR}`)
         .describe('Base path to context tree structure'),
     // Scoping
     domain: z
@@ -96,7 +97,7 @@ async function processSubtopicFile(params) {
     const subtopicRelativePath = subtopicFile.replace(topicPath, '').replace(/^\//, '');
     const subtopicParts = subtopicRelativePath.split('/');
     // Check if this is a subtopic context.md (not the topic's own context.md)
-    if (subtopicParts.length <= 1 || subtopicParts.at(-1) !== 'context.md') {
+    if (subtopicParts.length <= 1 || subtopicParts.at(-1) !== CONTEXT_FILE) {
         return null;
     }
     const subtopicName = subtopicParts[0];
@@ -106,7 +107,7 @@ async function processSubtopicFile(params) {
     }
     const subtopicEntry = {
         name: subtopicName,
-        path: `${domainName}/${topicName}/${subtopicName}`,
+        path: `${BRV_DIR}/${CONTEXT_TREE_DIR}/${domainName}/${topicName}/${subtopicName}/${CONTEXT_FILE}` // Full path
     };
     // Include subtopic content preview if requested
     if (includeContent) {
@@ -210,7 +211,7 @@ async function fetchRelatedTopics(params) {
         if (parts.length < 2 || parts.length > 3)
             continue;
         const [domainName, topicName] = parts;
-        const contextPath = join(basePath, ...parts, 'context.md');
+        const contextPath = join(basePath, ...parts, CONTEXT_FILE);
         try {
             // eslint-disable-next-line no-await-in-loop
             const fileExists = await DirectoryManager.fileExists(contextPath);
@@ -218,7 +219,7 @@ async function fetchRelatedTopics(params) {
                 continue;
             const entry = {
                 domain: domainName,
-                path: relationPath,
+                path: `${basePath}/${relationPath}/${CONTEXT_FILE}`,
                 topic: topicName,
             };
             // Include content preview if requested
@@ -281,8 +282,10 @@ async function executeFindKnowledgeTopics(input, _context) {
             const isSubtopic = rest.length > 1; // Has subtopic folder
             // Skip if not a context.md file (only process context files)
             const fileName = parts.at(-1);
-            if (fileName !== 'context.md')
+            if (fileName !== CONTEXT_FILE)
                 continue;
+            if (parts.length === 2)
+                continue; // Skip domain context.md files because they don't have much info
             // Handle subtopic pattern filtering (case-insensitive)
             if (isSubtopic) {
                 const subtopicName = rest[0];
@@ -309,7 +312,7 @@ async function executeFindKnowledgeTopics(input, _context) {
             // Build result entry for this topic
             const entry = {
                 domain: domainName,
-                path: `${domainName}/${topicName}`,
+                path: `${basePath}/${domainName}/${topicName}/${CONTEXT_FILE}`,
                 topic: topicName,
             };
             // Include content preview if requested
@@ -413,7 +416,7 @@ This tool helps discover what knowledge has been stored and navigate the domain/
 
 **Returns:**
 - total: Total number of matching topics (before relation traversal)
-- results: Array of topic entries with domain, topic name, path, optional relations, subtopics, and content`,
+- results: Array of topic entries with domain, topic name, optional relations, subtopics, and content with complete paths`,
         execute: executeFindKnowledgeTopics,
         id: ToolName.FIND_KNOWLEDGE_TOPICS,
         inputSchema: FindKnowledgeTopicsInputSchema,

package/dist/infra/cipher/tools/tool-manager.d.ts

@@ -21,6 +21,10 @@ import { type ToolExecutionResult } from '../../../core/domain/cipher/tools/tool
  * Without a scheduler, tools execute directly via the provider.
  */
 export declare class ToolManager {
+    /**
+     * Tools allowed for curate operations
+     */
+    private static readonly CURATE_TOOL_NAMES;
     /**
      * Read-only tools allowed for query operations
      */
@@ -83,9 +87,10 @@ export declare class ToolManager {
     /**
      * Get filtered tool names based on command type.
      * For 'query' command, returns only read-only discovery tools.
+     * For 'curate' command, returns only curate-specific tools.
      * For other commands, returns all tools.
      *
-     * @param commandType - The command type ('add', 'query', etc.)
+     * @param commandType - The command type ('curate', 'query', etc.)
      * @returns Array of filtered tool names
      */
     getToolNamesForCommand(commandType?: string): string[];
@@ -99,9 +104,10 @@ export declare class ToolManager {
     /**
      * Get filtered tools based on command type.
      * For 'query' command, returns only read-only discovery tools.
+     * For 'curate' command, returns only curate-specific tools.
      * For other commands, returns all tools.
      *
-     * @param commandType - The command type ('add', 'query', etc.)
+     * @param commandType - The command type ('curate', 'query', etc.)
      * @returns Filtered tool set with JSON Schema definitions
      */
     getToolsForCommand(commandType?: string): ToolSet;

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

@@ -17,6 +17,17 @@ import { ToolError, ToolErrorType, ToolErrorUtils } from '../../../core/domain/c
  * Without a scheduler, tools execute directly via the provider.
  */
 export class ToolManager {
+    /**
+     * Tools allowed for curate operations
+     */
+    static CURATE_TOOL_NAMES = [
+        'detect_domains',
+        'find_knowledge_topics',
+        'read_file',
+        'grep_content',
+        'glob_files',
+        'curate',
+    ];
     /**
      * Read-only tools allowed for query operations
      */
@@ -124,9 +135,10 @@ export class ToolManager {
     /**
      * Get filtered tool names based on command type.
      * For 'query' command, returns only read-only discovery tools.
+     * For 'curate' command, returns only curate-specific tools.
      * For other commands, returns all tools.
      *
-     * @param commandType - The command type ('add', 'query', etc.)
+     * @param commandType - The command type ('curate', 'query', etc.)
      * @returns Array of filtered tool names
      */
     getToolNamesForCommand(commandType) {
@@ -134,6 +146,10 @@ export class ToolManager {
             // For query: only allow read-only tools
             return [...ToolManager.QUERY_TOOL_NAMES].filter((name) => this.hasTool(name));
         }
+        if (commandType === 'curate') {
+            // For curate: only allow curate tools
+            return [...ToolManager.CURATE_TOOL_NAMES].filter((name) => this.hasTool(name));
+        }
         // For all other commands: return all tools
         return this.getToolNames();
     }
@@ -149,9 +165,10 @@ export class ToolManager {
     /**
      * Get filtered tools based on command type.
      * For 'query' command, returns only read-only discovery tools.
+     * For 'curate' command, returns only curate-specific tools.
      * For other commands, returns all tools.
      *
-     * @param commandType - The command type ('add', 'query', etc.)
+     * @param commandType - The command type ('curate', 'query', etc.)
      * @returns Filtered tool set with JSON Schema definitions
      */
     getToolsForCommand(commandType) {
@@ -166,6 +183,16 @@ export class ToolManager {
             }
             return filteredTools;
         }
+        if (commandType === 'curate') {
+            // For curate: only allow curate tools
+            const filteredTools = {};
+            for (const toolName of ToolManager.CURATE_TOOL_NAMES) {
+                if (allTools[toolName]) {
+                    filteredTools[toolName] = allTools[toolName];
+                }
+            }
+            return filteredTools;
+        }
         // For all other commands: return all tools
         return allTools;
     }

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

@@ -2,6 +2,7 @@ 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 { createCurateTool } from './implementations/curate-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';
@@ -59,6 +60,12 @@ export const TOOL_REGISTRY = {
         outputGuidance: 'create_knowledge_topic',
         requiredServices: [], // Uses DirectoryManager for file operations
     },
+    [ToolName.CURATE]: {
+        factory: () => createCurateTool(),
+        markers: [ToolMarker.ContextBuilding, ToolMarker.Modification],
+        outputGuidance: 'curate',
+        requiredServices: [], // Uses DirectoryManager and MarkdownWriter for file operations
+    },
     [ToolName.DELETE_MEMORY]: {
         factory: (services) => createDeleteMemoryTool(getRequiredService(services.memoryManager, 'memoryManager')),
         markers: [ToolMarker.ContextBuilding],

package/dist/infra/http/authenticated-http-client.d.ts

@@ -43,4 +43,25 @@ export declare class AuthenticatedHttpClient implements IHttpClient {
      * Preserves error information while abstracting axios-specific details.
      */
     private handleError;
+    /**
+     * Type guard to check if error is an axios error with response.
+     */
+    private isLLMServerError;
+    /**
+     * Parse HTTP error to extract user-friendly error message.
+     *
+     * Handles standardized API error responses from the server:
+     * ```json
+     * {
+     *   "statusCode": 401,
+     *   "code": "AUTH_INVALID_TOKEN",
+     *   "message": "Your authentication token is invalid. Please login again.",
+     *   "timestamp": "2024-01-01T00:00:00.000Z"
+     * }
+     * ```
+     *
+     * @param error - HTTP error object (may contain response data)
+     * @returns User-friendly error message
+     */
+    private parseHttpError;
 }

package/dist/infra/http/authenticated-http-client.js

@@ -76,6 +76,10 @@ export class AuthenticatedHttpClient {
      * Preserves error information while abstracting axios-specific details.
      */
     handleError(error) {
+        if (this.isLLMServerError(error)) {
+            // Extract standardized API error message
+            return new Error(this.parseHttpError(error));
+        }
         if (isAxiosError(error)) {
             if (error.response) {
                 // Server responded with error status
@@ -96,4 +100,38 @@ export class AuthenticatedHttpClient {
         }
         return new Error('Unknown error occurred');
     }
+    /**
+     * Type guard to check if error is an axios error with response.
+     */
+    isLLMServerError(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            'response' in error &&
+            typeof error.response === 'object');
+    }
+    /**
+     * Parse HTTP error to extract user-friendly error message.
+     *
+     * Handles standardized API error responses from the server:
+     * ```json
+     * {
+     *   "statusCode": 401,
+     *   "code": "AUTH_INVALID_TOKEN",
+     *   "message": "Your authentication token is invalid. Please login again.",
+     *   "timestamp": "2024-01-01T00:00:00.000Z"
+     * }
+     * ```
+     *
+     * @param error - HTTP error object (may contain response data)
+     * @returns User-friendly error message
+     */
+    parseHttpError(error) {
+        const responseData = error.response.data;
+        // If server returned standardized API error format, use the message
+        if ('message' in responseData && typeof responseData.message === 'string') {
+            return responseData.message;
+        }
+        // Fallback to HTTP status error
+        return `HTTP ${error.response.status}: ${error.response.statusText}`;
+    }
 }