byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/tools/implementations/edit-memory-tool.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for edit memory tool.
+ */
+const EditMemoryInputSchema = z
+    .object({
+    content: z
+        .string()
+        .min(1, 'Memory content cannot be empty')
+        .max(10_000, 'Memory content cannot exceed 10,000 characters')
+        .optional()
+        .describe('Updated content for the memory'),
+    id: z.string().min(1).describe('Unique identifier of the memory to edit'),
+    pinned: z.boolean().optional().describe('Updated pinned status'),
+})
+    .strict();
+/**
+ * Creates the edit memory tool.
+ *
+ * Updates an existing memory's content, tags, or pinned status. Metadata is merged
+ * while content and tags are replaced if provided. Use this to refine or update
+ * context in the scratch pad.
+ *
+ * @param memoryManager - Memory manager service dependency
+ * @returns Configured edit memory tool
+ */
+export function createEditMemoryTool(memoryManager) {
+    return {
+        description: 'Edit an existing memory. Update content, tags, or pinned status. Use this to refine or update previously stored context.',
+        async execute(input, _context) {
+            const { content, id, pinned } = input;
+            // Build update input
+            const updateInput = {};
+            if (content !== undefined) {
+                updateInput.content = content;
+            }
+            if (pinned !== undefined) {
+                updateInput.metadata = { pinned };
+            }
+            // Update memory
+            const updatedMemory = await memoryManager.update(id, updateInput);
+            // Return formatted result
+            return {
+                content: updatedMemory.content,
+                id: updatedMemory.id,
+                updatedAt: new Date(updatedMemory.updatedAt).toISOString(),
+            };
+        },
+        id: ToolName.EDIT_MEMORY,
+        inputSchema: EditMemoryInputSchema,
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+/**
+ * Factory function to create the find knowledge topics tool.
+ *
+ * @returns Configured Tool instance
+ */
+export declare function createFindKnowledgeTopicsTool(): Tool;

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

@@ -0,0 +1,421 @@
+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 { parseRelations } from '../../../../core/domain/knowledge/relation-parser.js';
+/**
+ * Input schema for finding knowledge topics.
+ * Supports pattern matching, scoping, depth control, and pagination.
+ */
+const FindKnowledgeTopicsInputSchema = z.object({
+    basePath: z
+        .string()
+        .default('.brv/context-tree')
+        .describe('Base path to context tree structure'),
+    // Scoping
+    domain: z
+        .string()
+        .optional()
+        .describe('Restrict search to specific domain (exact match)'),
+    // Search filters (substring matching)
+    domainPattern: z
+        .string()
+        .optional()
+        .describe('Domain name pattern for substring matching'),
+    // Relation traversal
+    followRelations: z
+        .boolean()
+        .default(false)
+        .describe('Automatically fetch related topics referenced in Relations section'),
+    includeContent: z
+        .boolean()
+        .default(false)
+        .describe('Include content preview from context.md files'),
+    // Depth control
+    includeSubtopics: z
+        .boolean()
+        .default(false)
+        .describe('Include subtopic details in results'),
+    // Pagination
+    limit: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Maximum number of results to return'),
+    offset: z
+        .number()
+        .int()
+        .nonnegative()
+        .default(0)
+        .describe('Number of results to skip'),
+    relationDepth: z
+        .number()
+        .int()
+        .positive()
+        .default(1)
+        .describe('How many levels deep to follow relations (default: 1, max: 3)'),
+    subtopicPattern: z
+        .string()
+        .optional()
+        .describe('Subtopic name pattern for substring matching'),
+    topicPattern: z
+        .string()
+        .optional()
+        .describe('Topic name pattern for substring matching'),
+});
+/**
+ * Read content preview from a file, truncating to 500 characters if needed.
+ */
+async function readContentPreview(filePath) {
+    try {
+        const content = await DirectoryManager.readFile(filePath);
+        return content.length > 500 ? content.slice(0, 500) + '...' : content;
+    }
+    catch {
+        return '[Content unavailable]';
+    }
+}
+/**
+ * Read and parse relations from a context.md file.
+ */
+async function readRelations(filePath) {
+    try {
+        const content = await DirectoryManager.readFile(filePath);
+        return parseRelations(content);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Process a single subtopic file and return its entry.
+ */
+async function processSubtopicFile(params) {
+    const { domainName, includeContent, subtopicFile, subtopicPattern, topicName, topicPath } = 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') {
+        return null;
+    }
+    const subtopicName = subtopicParts[0];
+    // Apply subtopic pattern filter if specified (case-insensitive)
+    if (subtopicPattern && !subtopicName.toLowerCase().includes(subtopicPattern.toLowerCase())) {
+        return null;
+    }
+    const subtopicEntry = {
+        name: subtopicName,
+        path: `${domainName}/${topicName}/${subtopicName}`,
+    };
+    // Include subtopic content preview if requested
+    if (includeContent) {
+        subtopicEntry.contentPreview = await readContentPreview(subtopicFile);
+    }
+    // Always parse relations to enable relation traversal
+    const relations = await readRelations(subtopicFile);
+    if (relations.length > 0) {
+        subtopicEntry.relations = relations;
+    }
+    return subtopicEntry;
+}
+/**
+ * Collect all subtopics for a given topic.
+ */
+async function collectSubtopics(params) {
+    const { basePath, domainName, includeContent, subtopicPattern, topicName } = params;
+    const topicPath = join(basePath, domainName, topicName);
+    const subtopicFiles = await DirectoryManager.listMarkdownFiles(topicPath);
+    const subtopics = [];
+    for (const subtopicFile of subtopicFiles) {
+        // eslint-disable-next-line no-await-in-loop
+        const subtopicEntry = await processSubtopicFile({
+            domainName,
+            includeContent,
+            subtopicFile,
+            subtopicPattern,
+            topicName,
+            topicPath,
+        });
+        if (subtopicEntry) {
+            subtopics.push(subtopicEntry);
+        }
+    }
+    return subtopics;
+}
+/**
+ * Check if a topic matches the filter criteria.
+ */
+function matchesFilters(params) {
+    const { domain, domainName, domainPattern, topicName, topicPattern } = params;
+    // Normalize all strings to lowercase for case-insensitive matching
+    const normalizedDomainName = domainName.toLowerCase();
+    const normalizedTopicName = topicName.toLowerCase();
+    // Apply domain scoping filter (exact match, case-insensitive)
+    if (domain && normalizedDomainName !== domain.toLowerCase())
+        return false;
+    // Apply pattern filters (substring matching, case-insensitive)
+    if (domainPattern && !normalizedDomainName.includes(domainPattern.toLowerCase()))
+        return false;
+    if (topicPattern && !normalizedTopicName.includes(topicPattern.toLowerCase()))
+        return false;
+    return true;
+}
+/**
+ * Collect relations from subtopics.
+ */
+function collectSubtopicRelations(subtopics) {
+    const relations = [];
+    for (const subtopic of subtopics) {
+        if (subtopic.relations) {
+            relations.push(...subtopic.relations);
+        }
+    }
+    return relations;
+}
+/**
+ * Collect all relation paths from a set of results.
+ */
+function collectAllRelations(results) {
+    const allRelations = new Set();
+    for (const result of results) {
+        if (result.relations) {
+            for (const rel of result.relations)
+                allRelations.add(rel);
+        }
+        if (result.subtopics) {
+            const subtopicRelations = collectSubtopicRelations(result.subtopics);
+            for (const rel of subtopicRelations)
+                allRelations.add(rel);
+        }
+    }
+    return allRelations;
+}
+/**
+ * Fetch related topics by following relation references.
+ * Recursively traverses relations up to the specified depth.
+ */
+async function fetchRelatedTopics(params) {
+    const { basePath, currentDepth, includeContent, maxDepth, relationPaths, seenPaths } = params;
+    if (currentDepth > maxDepth || relationPaths.length === 0) {
+        return [];
+    }
+    const relatedTopics = [];
+    for (const relationPath of relationPaths) {
+        // Avoid circular references
+        if (seenPaths.has(relationPath))
+            continue;
+        seenPaths.add(relationPath);
+        const parts = relationPath.split('/');
+        if (parts.length < 2 || parts.length > 3)
+            continue;
+        const [domainName, topicName] = parts;
+        const contextPath = join(basePath, ...parts, 'context.md');
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const fileExists = await DirectoryManager.fileExists(contextPath);
+            if (!fileExists)
+                continue;
+            const entry = {
+                domain: domainName,
+                path: relationPath,
+                topic: topicName,
+            };
+            // Include content preview if requested
+            if (includeContent) {
+                // eslint-disable-next-line no-await-in-loop
+                entry.contentPreview = await readContentPreview(contextPath);
+            }
+            // Parse relations from this topic
+            // eslint-disable-next-line no-await-in-loop
+            const nestedRelations = await readRelations(contextPath);
+            if (nestedRelations.length > 0) {
+                entry.relations = nestedRelations;
+                // Recursively fetch nested relations if depth allows
+                if (currentDepth < maxDepth) {
+                    // eslint-disable-next-line no-await-in-loop
+                    const nestedTopics = await fetchRelatedTopics({
+                        basePath,
+                        currentDepth: currentDepth + 1,
+                        includeContent,
+                        maxDepth,
+                        relationPaths: nestedRelations,
+                        seenPaths,
+                    });
+                    relatedTopics.push(...nestedTopics);
+                }
+            }
+            relatedTopics.push(entry);
+        }
+        catch {
+            // Skip missing or invalid relations
+            continue;
+        }
+    }
+    return relatedTopics;
+}
+/**
+ * Execute the find knowledge topics operation.
+ * Searches the context tree structure and applies filters.
+ *
+ * @param input - Validated input parameters
+ * @param _context - Tool execution context (unused)
+ * @returns Structured results with total count and paginated data
+ */
+async function executeFindKnowledgeTopics(input, _context) {
+    const { basePath, domain, domainPattern, followRelations, includeContent, includeSubtopics, limit, offset, relationDepth, subtopicPattern, topicPattern, } = input;
+    const results = [];
+    const seenTopics = new Set(); // Track unique topic paths to avoid duplicates
+    try {
+        // List all markdown files in the context tree
+        const mdFiles = await DirectoryManager.listMarkdownFiles(basePath);
+        // Process each markdown file
+        for (const filePath of mdFiles) {
+            // Extract relative path from base
+            const relativePath = filePath.replace(basePath, '').replace(/^\//, '');
+            const parts = relativePath.split('/');
+            // Context tree structure: domain/topic/context.md or domain/topic/subtopic/context.md
+            if (parts.length < 2)
+                continue; // Need at least domain/file
+            const [domainName, topicName, ...rest] = parts;
+            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')
+                continue;
+            // Handle subtopic pattern filtering (case-insensitive)
+            if (isSubtopic) {
+                const subtopicName = rest[0];
+                if (subtopicPattern && !subtopicName.toLowerCase().includes(subtopicPattern.toLowerCase()))
+                    continue;
+                // Skip subtopics for now - we'll collect them when processing their parent topic
+                continue;
+            }
+            // Apply filters
+            if (!matchesFilters({
+                domain,
+                domainName,
+                domainPattern,
+                topicName,
+                topicPattern,
+            })) {
+                continue;
+            }
+            // Create unique key for this topic to avoid duplicates
+            const topicKey = `${domainName}/${topicName}`;
+            if (seenTopics.has(topicKey))
+                continue;
+            seenTopics.add(topicKey);
+            // Build result entry for this topic
+            const entry = {
+                domain: domainName,
+                path: `${domainName}/${topicName}`,
+                topic: topicName,
+            };
+            // Include content preview if requested
+            if (includeContent) {
+                // eslint-disable-next-line no-await-in-loop
+                entry.contentPreview = await readContentPreview(filePath);
+            }
+            // Always parse relations to enable relation traversal
+            // eslint-disable-next-line no-await-in-loop
+            const topicRelations = await readRelations(filePath);
+            if (topicRelations.length > 0) {
+                entry.relations = topicRelations;
+            }
+            // Include subtopics if requested
+            if (includeSubtopics) {
+                // eslint-disable-next-line no-await-in-loop
+                const subtopics = await collectSubtopics({
+                    basePath,
+                    domainName,
+                    includeContent,
+                    subtopicPattern,
+                    topicName,
+                });
+                if (subtopics.length > 0) {
+                    entry.subtopics = subtopics;
+                }
+            }
+            results.push(entry);
+        }
+        // Apply pagination
+        const total = results.length;
+        const effectiveOffset = offset ?? 0;
+        const paginatedResults = limit
+            ? results.slice(effectiveOffset, effectiveOffset + limit)
+            : results.slice(effectiveOffset);
+        // Follow relations if requested
+        if (followRelations && paginatedResults.length > 0) {
+            const maxDepth = Math.min(relationDepth ?? 1, 3); // Cap at 3 to prevent excessive traversal
+            const allRelations = collectAllRelations(paginatedResults);
+            // Fetch related topics recursively
+            if (allRelations.size > 0) {
+                const relatedTopics = await fetchRelatedTopics({
+                    basePath,
+                    currentDepth: 1,
+                    includeContent,
+                    maxDepth,
+                    relationPaths: [...allRelations],
+                    seenPaths: seenTopics, // Reuse seenTopics to avoid duplicates
+                });
+                // Append related topics to results
+                paginatedResults.push(...relatedTopics);
+            }
+        }
+        return {
+            results: paginatedResults,
+            total,
+        };
+    }
+    catch {
+        // If base path doesn't exist or other errors, return empty results
+        return {
+            results: [],
+            total: 0,
+        };
+    }
+}
+/**
+ * Factory function to create the find knowledge topics tool.
+ *
+ * @returns Configured Tool instance
+ */
+export function createFindKnowledgeTopicsTool() {
+    return {
+        description: `Search and filter knowledge topics in the context tree structure with relation support.
+
+This tool helps discover what knowledge has been stored and navigate the domain/topic hierarchy. It works similarly to find_symbol but for knowledge organization, with the ability to follow relations between topics.
+
+**Use cases:**
+- Discover what knowledge topics exist in a domain
+- Find topics matching specific patterns
+- Navigate the knowledge hierarchy via relations
+- Retrieve context for specific areas
+- Check what has been documented
+- Follow related topics for comprehensive context
+
+**Search capabilities:**
+- Pattern matching on domain, topic, and subtopic names (substring matching)
+- Scope searches to specific domains (exact match)
+- Optional subtopic inclusion (depth control)
+- Optional content preview (500 character limit)
+- Pagination for large result sets
+- Relation traversal (automatically fetch related topics up to 3 levels deep)
+
+**Examples:**
+- Find all topics in "testing" domain: {domain: "testing"}
+- Find topics about "eslint": {topicPattern: "eslint"}
+- Find subtopics with "config": {subtopicPattern: "config", includeSubtopics: true}
+- Get content previews: {domain: "architecture", includeContent: true}
+- Follow relations: {topicPattern: "auth", followRelations: true, relationDepth: 2}
+- Paginate results: {limit: 10, offset: 0}
+
+**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`,
+        execute: executeFindKnowledgeTopics,
+        id: ToolName.FIND_KNOWLEDGE_TOPICS,
+        inputSchema: FindKnowledgeTopicsInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/glob-files-tool.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../../core/interfaces/cipher/i-file-system.js';
+/**
+ * Creates the glob files tool.
+ *
+ * Finds files matching a glob pattern.
+ * Supports standard glob syntax with ** for recursive matching.
+ *
+ * Features:
+ * - Case sensitivity control
+ * - Gitignore filtering (respects .gitignore rules by default)
+ * - Smart sorting: recently modified files (within 24h) appear first
+ * - Handles file names containing glob special characters
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured glob files tool
+ */
+export declare function createGlobFilesTool(fileSystemService: IFileSystem): Tool;

package/dist/infra/cipher/tools/implementations/glob-files-tool.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for glob files tool.
+ */
+const GlobFilesInputSchema = z
+    .object({
+    caseSensitive: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Case-sensitive pattern matching (default: true)'),
+    maxResults: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(1000)
+        .describe('Maximum number of results to return (default: 1000)'),
+    path: z.string().optional().describe('Base directory to search from (defaults to working directory)'),
+    pattern: z.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.js")')
+})
+    .strict();
+/**
+ * Creates the glob files tool.
+ *
+ * Finds files matching a glob pattern.
+ * Supports standard glob syntax with ** for recursive matching.
+ *
+ * Features:
+ * - Case sensitivity control
+ * - Gitignore filtering (respects .gitignore rules by default)
+ * - Smart sorting: recently modified files (within 24h) appear first
+ * - Handles file names containing glob special characters
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured glob files tool
+ */
+export function createGlobFilesTool(fileSystemService) {
+    return {
+        description: 'Find files matching a glob pattern. Supports ** for recursive matching (e.g., "**/*.ts" finds all TypeScript files)',
+        async execute(input, _context) {
+            const { caseSensitive, maxResults, path, pattern } = input;
+            // Call file system service with new options
+            const result = await fileSystemService.globFiles(pattern, {
+                caseSensitive,
+                cwd: path,
+                includeMetadata: true,
+                maxResults,
+                respectGitignore: true,
+            });
+            // Format file metadata
+            const files = result.files.map((file) => ({
+                modified: file.modified.toISOString(),
+                path: file.path,
+                size: file.size,
+            }));
+            // Return formatted result with message for LLM context
+            return {
+                files,
+                ignoredCount: result.ignoredCount,
+                message: result.message,
+                totalFound: result.totalFound,
+                truncated: result.truncated,
+            };
+        },
+        id: ToolName.GLOB_FILES,
+        inputSchema: GlobFilesInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/grep-content-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IFileSystem } from '../../../../core/interfaces/cipher/i-file-system.js';
+/**
+ * Creates the grep content tool.
+ *
+ * Searches file contents for a regex pattern.
+ * Can filter files with glob patterns and include context lines.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured grep content tool
+ */
+export declare function createGrepContentTool(fileSystemService: IFileSystem): Tool;

package/dist/infra/cipher/tools/implementations/grep-content-tool.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
+/**
+ * Input schema for grep content tool.
+ */
+const GrepContentInputSchema = z
+    .object({
+    caseInsensitive: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Perform case-insensitive search (default: false)'),
+    contextLines: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .default(0)
+        .describe('Number of context lines to include before and after each match (default: 0)'),
+    glob: z.string().optional().describe('Glob pattern to filter files (e.g., "*.ts", "**/*.js")'),
+    maxResults: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .default(100)
+        .describe('Maximum number of results to return (default: 100)'),
+    path: z.string().optional().describe('Directory to search in (defaults to working directory)'),
+    pattern: z.string().describe('Regular expression pattern to search for'),
+})
+    .strict();
+/**
+ * Creates the grep content tool.
+ *
+ * Searches file contents for a regex pattern.
+ * Can filter files with glob patterns and include context lines.
+ *
+ * @param fileSystemService - File system service dependency
+ * @returns Configured grep content tool
+ */
+export function createGrepContentTool(fileSystemService) {
+    return {
+        description: 'Search file contents for a regex pattern. Can filter files with glob patterns and include context lines around matches.',
+        async execute(input, _context) {
+            const { caseInsensitive, contextLines, glob, maxResults, path, pattern } = input;
+            // Call file system service
+            const result = await fileSystemService.searchContent(pattern, {
+                caseInsensitive,
+                contextLines,
+                cwd: path,
+                globPattern: glob,
+                maxResults,
+            });
+            // Format matches
+            const matches = result.matches.map((match) => ({
+                context: match.context
+                    ? {
+                        after: match.context.after,
+                        before: match.context.before,
+                    }
+                    : undefined,
+                file: match.file,
+                line: match.line,
+                lineNumber: match.lineNumber,
+            }));
+            // Return formatted result
+            return {
+                filesSearched: result.filesSearched,
+                matches,
+                totalMatches: result.totalMatches,
+                truncated: result.truncated,
+            };
+        },
+        id: ToolName.GREP_CONTENT,
+        inputSchema: GrepContentInputSchema,
+    };
+}

package/dist/infra/cipher/tools/implementations/kill-process-tool.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from '../../../../core/domain/cipher/tools/types.js';
+import type { IProcessService } from '../../../../core/interfaces/cipher/i-process-service.js';
+/**
+ * Create kill_process tool.
+ *
+ * Terminates a background process started by bash_exec.
+ * Uses graceful shutdown (SIGTERM) with escalation to SIGKILL after 5 seconds.
+ *
+ * @param processService - Process service for killing processes
+ * @returns kill_process tool instance
+ */
+export declare function createKillProcessTool(processService: IProcessService): Tool;