byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/system-prompt/environment-context-builder.js

@@ -0,0 +1,256 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { SystemPromptError } from '../../../core/domain/cipher/errors/system-prompt-error.js';
+import { EnvironmentContextOptionsSchema } from './schemas.js';
+/**
+ * Patterns to exclude from file tree.
+ */
+const EXCLUDE_PATTERNS = [
+    'node_modules',
+    '.git',
+    '.brv',
+    'dist',
+    'build',
+    '.next',
+    'coverage',
+    '.DS_Store',
+    '.env',
+    '.env.local',
+    '__pycache__',
+    '.pytest_cache',
+    '.venv',
+    'venv',
+    '.idea',
+    '.vscode',
+    '*.log',
+    '.turbo',
+    '.cache',
+];
+/**
+ * Builds environment context for system prompts.
+ *
+ * Gathers information about:
+ * - Working directory
+ * - Git repository status
+ * - Platform and OS version
+ * - Project file tree
+ * - .brv directory structure
+ */
+export class EnvironmentContextBuilder {
+    /**
+     * Build the complete environment context.
+     *
+     * @param options - Configuration options
+     * @returns Environment context object
+     */
+    async build(options) {
+        // Validate options with Zod schema
+        const parseResult = EnvironmentContextOptionsSchema.safeParse(options);
+        if (!parseResult.success) {
+            const errorMessages = parseResult.error.errors
+                .map((err) => `${err.path.join('.')}: ${err.message}`)
+                .join('; ');
+            throw SystemPromptError.configInvalid(errorMessages, parseResult.error.errors);
+        }
+        const validatedOptions = parseResult.data;
+        const { includeBrvStructure = true, includeFileTree = true, maxFileTreeDepth = 3, maxFileTreeEntries = 100, workingDirectory, } = validatedOptions;
+        const isGitRepository = this.detectGitRepository(workingDirectory);
+        let fileTree = '';
+        if (includeFileTree) {
+            fileTree = this.buildFileTree(workingDirectory, maxFileTreeDepth, maxFileTreeEntries);
+        }
+        let brvStructure = '';
+        if (includeBrvStructure) {
+            brvStructure = this.buildBrvStructure(workingDirectory);
+        }
+        return {
+            brvStructure,
+            fileTree,
+            isGitRepository,
+            nodeVersion: process.version,
+            osVersion: os.release(),
+            platform: os.platform(),
+            workingDirectory,
+        };
+    }
+    /**
+     * Build an explanation of the .brv directory structure.
+     *
+     * @param dir - Working directory path
+     * @returns Formatted .brv structure explanation
+     */
+    buildBrvStructure(dir) {
+        const brvDir = path.join(dir, '.brv');
+        if (!fs.existsSync(brvDir)) {
+            return '<brv-structure>\nByteRover not initialized (.brv directory not found)\n</brv-structure>';
+        }
+        // Build actual structure by reading the directory
+        const structure = ['<brv-structure>', '.brv/'];
+        try {
+            const entries = fs.readdirSync(brvDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const description = this.getBrvDirectoryDescription(entry.name);
+                    structure.push(`  ${entry.name}/          ${description}`);
+                }
+                else {
+                    const description = this.getBrvFileDescription(entry.name);
+                    structure.push(`  ${entry.name}          ${description}`);
+                }
+            }
+        }
+        catch {
+            structure.push('  (unable to read directory contents)');
+        }
+        structure.push('</brv-structure>');
+        return structure.join('\n');
+    }
+    /**
+     * Build a formatted file tree of the project.
+     *
+     * @param dir - Root directory to start from
+     * @param maxDepth - Maximum traversal depth
+     * @param maxEntries - Maximum number of entries to include
+     * @returns Formatted file tree string
+     */
+    buildFileTree(dir, maxDepth, maxEntries) {
+        const entriesCount = { value: 0 };
+        const truncatedCount = { value: 0 };
+        const lines = ['<files>'];
+        this.traverseDirectory({
+            currentDepth: 0,
+            dir,
+            entriesCount,
+            lines,
+            maxDepth,
+            maxEntries,
+            truncatedCount,
+        });
+        if (truncatedCount.value > 0) {
+            lines.push(`[${truncatedCount.value} entries truncated]`);
+        }
+        lines.push('</files>');
+        return lines.join('\n');
+    }
+    /**
+     * Check if a directory is a git repository.
+     *
+     * @param dir - Directory path to check
+     * @returns True if the directory contains a .git folder
+     */
+    detectGitRepository(dir) {
+        try {
+            const gitDir = path.join(dir, '.git');
+            return fs.existsSync(gitDir);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get description for a .brv directory.
+     *
+     * @param name - Directory name
+     * @returns Description string
+     */
+    getBrvDirectoryDescription(name) {
+        const descriptions = {
+            blobs: '# Storage for conversation history',
+            'context-tree': '# Semantic knowledge organized by domain',
+            logs: '# Debug logs for troubleshooting',
+        };
+        return descriptions[name] ?? '';
+    }
+    /**
+     * Get description for a .brv file.
+     *
+     * @param name - File name
+     * @returns Description string
+     */
+    getBrvFileDescription(name) {
+        const descriptions = {
+            'config.json': '# Project configuration',
+        };
+        return descriptions[name] ?? '';
+    }
+    /**
+     * Check if a file or directory should be excluded from the tree.
+     *
+     * @param name - File or directory name
+     * @returns True if should be excluded
+     */
+    shouldExclude(name) {
+        for (const pattern of EXCLUDE_PATTERNS) {
+            if (pattern.startsWith('*')) {
+                // Wildcard pattern (e.g., *.log)
+                const extension = pattern.slice(1);
+                if (name.endsWith(extension)) {
+                    return true;
+                }
+            }
+            else if (name === pattern) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Recursively traverse a directory and build tree lines.
+     *
+     * @param options - Traversal options
+     * @param options.dir - Current directory path
+     * @param options.maxDepth - Maximum depth to traverse
+     * @param options.maxEntries - Maximum entries to include
+     * @param options.currentDepth - Current traversal depth
+     * @param options.entriesCount - Counter for entries added (mutable object with value property)
+     * @param options.truncatedCount - Counter for truncated entries (mutable object with value property)
+     * @param options.lines - Array to append lines to
+     */
+    traverseDirectory(options) {
+        const { currentDepth, dir, entriesCount, lines, maxDepth, maxEntries, truncatedCount } = options;
+        if (currentDepth >= maxDepth) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Filter and sort: directories first, then alphabetically
+        const filteredEntries = entries
+            .filter((entry) => !this.shouldExclude(entry.name))
+            .sort((a, b) => {
+            if (a.isDirectory() && !b.isDirectory())
+                return -1;
+            if (!a.isDirectory() && b.isDirectory())
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        const indent = '  '.repeat(currentDepth);
+        for (const entry of filteredEntries) {
+            if (entriesCount.value >= maxEntries) {
+                truncatedCount.value += filteredEntries.length - filteredEntries.indexOf(entry);
+                break;
+            }
+            entriesCount.value++;
+            if (entry.isDirectory()) {
+                lines.push(`${indent}${entry.name}/`);
+                this.traverseDirectory({
+                    currentDepth: currentDepth + 1,
+                    dir: path.join(dir, entry.name),
+                    entriesCount,
+                    lines,
+                    maxDepth,
+                    maxEntries,
+                    truncatedCount,
+                });
+            }
+            else {
+                lines.push(`${indent}${entry.name}`);
+            }
+        }
+    }
+}

package/dist/infra/cipher/system-prompt/prompt-cache.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Cache entry for a prompt configuration.
+ */
+export interface PromptCacheEntry<T> {
+    /** Cached content */
+    content: T;
+    /** Timestamp when this entry was loaded */
+    loadedAt: number;
+    /** File modification time in milliseconds when cached */
+    mtimeMs: number;
+}
+/**
+ * Options for configuring the prompt cache.
+ */
+export interface PromptCacheOptions {
+    /** Maximum number of entries to store (default: 100) */
+    maxSize?: number;
+    /** TTL in milliseconds, 0 means no TTL (default: 0) */
+    ttlMs?: number;
+    /** Whether to validate file mtime on cache hit (default: true) */
+    validateMtime?: boolean;
+}
+/**
+ * Prompt cache with file modification time and TTL validation.
+ *
+ * Features:
+ * - Validates cached entries against file modification time
+ * - Optional TTL-based expiration
+ * - LRU-style eviction when max size is reached
+ */
+export declare class PromptCache<T> {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    private readonly validateMtime;
+    /**
+     * Creates a new prompt cache.
+     *
+     * @param options - Cache configuration options
+     */
+    constructor(options?: PromptCacheOptions);
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Get a cached entry if valid.
+     *
+     * Returns undefined if:
+     * - Entry doesn't exist
+     * - TTL has expired
+     * - File has been modified (mtime validation enabled)
+     *
+     * @param filepath - Absolute path to the file
+     * @returns Cached content or undefined if not valid
+     */
+    get(filepath: string): T | undefined;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Object with size and maxSize
+     */
+    getStats(): {
+        maxSize: number;
+        size: number;
+    };
+    /**
+     * Check if an entry exists and is valid.
+     *
+     * @param filepath - Absolute path to the file
+     * @returns True if a valid entry exists
+     */
+    has(filepath: string): boolean;
+    /**
+     * Invalidate a specific cache entry.
+     *
+     * @param filepath - Absolute path to the file
+     * @returns True if an entry was removed
+     */
+    invalidate(filepath: string): boolean;
+    /**
+     * Get all cached filepaths.
+     *
+     * @returns Array of cached filepaths
+     */
+    keys(): string[];
+    /**
+     * Store content in the cache.
+     *
+     * If the cache is at max capacity, the oldest entry is evicted.
+     *
+     * @param filepath - Absolute path to the file
+     * @param content - Content to cache
+     */
+    set(filepath: string, content: T): void;
+    /**
+     * Find the oldest cache entry by loadedAt timestamp.
+     *
+     * @returns Filepath of the oldest entry, or undefined if cache is empty
+     */
+    private findOldestEntry;
+}

package/dist/infra/cipher/system-prompt/prompt-cache.js

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+/**
+ * Prompt cache with file modification time and TTL validation.
+ *
+ * Features:
+ * - Validates cached entries against file modification time
+ * - Optional TTL-based expiration
+ * - LRU-style eviction when max size is reached
+ */
+export class PromptCache {
+    cache = new Map();
+    maxSize;
+    ttlMs;
+    validateMtime;
+    /**
+     * Creates a new prompt cache.
+     *
+     * @param options - Cache configuration options
+     */
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? 100;
+        this.ttlMs = options.ttlMs ?? 0;
+        this.validateMtime = options.validateMtime ?? true;
+    }
+    /**
+     * Clear all cached entries.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get a cached entry if valid.
+     *
+     * Returns undefined if:
+     * - Entry doesn't exist
+     * - TTL has expired
+     * - File has been modified (mtime validation enabled)
+     *
+     * @param filepath - Absolute path to the file
+     * @returns Cached content or undefined if not valid
+     */
+    get(filepath) {
+        const entry = this.cache.get(filepath);
+        if (!entry) {
+            return undefined;
+        }
+        // Check TTL
+        if (this.ttlMs > 0) {
+            const age = Date.now() - entry.loadedAt;
+            if (age > this.ttlMs) {
+                this.cache.delete(filepath);
+                return undefined;
+            }
+        }
+        // Check file modification time
+        if (this.validateMtime) {
+            try {
+                const stats = fs.statSync(filepath);
+                if (stats.mtimeMs > entry.mtimeMs) {
+                    this.cache.delete(filepath);
+                    return undefined;
+                }
+            }
+            catch {
+                // File doesn't exist or can't be accessed, invalidate cache
+                this.cache.delete(filepath);
+                return undefined;
+            }
+        }
+        return entry.content;
+    }
+    /**
+     * Get cache statistics.
+     *
+     * @returns Object with size and maxSize
+     */
+    getStats() {
+        return {
+            maxSize: this.maxSize,
+            size: this.cache.size,
+        };
+    }
+    /**
+     * Check if an entry exists and is valid.
+     *
+     * @param filepath - Absolute path to the file
+     * @returns True if a valid entry exists
+     */
+    has(filepath) {
+        return this.get(filepath) !== undefined;
+    }
+    /**
+     * Invalidate a specific cache entry.
+     *
+     * @param filepath - Absolute path to the file
+     * @returns True if an entry was removed
+     */
+    invalidate(filepath) {
+        return this.cache.delete(filepath);
+    }
+    /**
+     * Get all cached filepaths.
+     *
+     * @returns Array of cached filepaths
+     */
+    keys() {
+        return [...this.cache.keys()];
+    }
+    /**
+     * Store content in the cache.
+     *
+     * If the cache is at max capacity, the oldest entry is evicted.
+     *
+     * @param filepath - Absolute path to the file
+     * @param content - Content to cache
+     */
+    set(filepath, content) {
+        // Evict oldest entry if at max size
+        if (this.cache.size >= this.maxSize && !this.cache.has(filepath)) {
+            const oldest = this.findOldestEntry();
+            if (oldest) {
+                this.cache.delete(oldest);
+            }
+        }
+        // Get file mtime
+        let mtimeMs = Date.now();
+        try {
+            const stats = fs.statSync(filepath);
+            mtimeMs = stats.mtimeMs;
+        }
+        catch {
+            // Use current time if file doesn't exist
+        }
+        this.cache.set(filepath, {
+            content,
+            loadedAt: Date.now(),
+            mtimeMs,
+        });
+    }
+    /**
+     * Find the oldest cache entry by loadedAt timestamp.
+     *
+     * @returns Filepath of the oldest entry, or undefined if cache is empty
+     */
+    findOldestEntry() {
+        let oldestPath;
+        let oldestTime = Number.POSITIVE_INFINITY;
+        for (const [filepath, entry] of this.cache.entries()) {
+            if (entry.loadedAt < oldestTime) {
+                oldestTime = entry.loadedAt;
+                oldestPath = filepath;
+            }
+        }
+        return oldestPath;
+    }
+}

package/dist/infra/cipher/system-prompt/schemas.d.ts

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+/**
+ * Schema for prompt configuration loaded from YAML files.
+ *
+ * Either 'prompt' (single template) or 'prompts' (named templates) is required.
+ *
+ * Handles mapping from YAML snake_case (excluded_tools) to TypeScript camelCase (excludedTools).
+ */
+export declare const PromptConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    excludedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    prompt: z.ZodOptional<z.ZodString>;
+    prompts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    prompt?: string | undefined;
+    description?: string | undefined;
+    excludedTools?: string[] | undefined;
+    prompts?: Record<string, string> | undefined;
+}, {
+    prompt?: string | undefined;
+    description?: string | undefined;
+    excludedTools?: string[] | undefined;
+    prompts?: Record<string, string> | undefined;
+}>, {
+    prompt?: string | undefined;
+    description?: string | undefined;
+    excludedTools?: string[] | undefined;
+    prompts?: Record<string, string> | undefined;
+}, {
+    prompt?: string | undefined;
+    description?: string | undefined;
+    excludedTools?: string[] | undefined;
+    prompts?: Record<string, string> | undefined;
+}>, {
+    prompt?: string | undefined;
+    description?: string | undefined;
+    excludedTools?: string[] | undefined;
+    prompts?: Record<string, string> | undefined;
+}, unknown>;
+/**
+ * Validated prompt configuration type.
+ */
+export type ValidatedPromptConfig = z.infer<typeof PromptConfigSchema>;
+/**
+ * Schema for conversation metadata.
+ */
+export declare const ConversationMetadataSchema: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    title?: string | undefined;
+    conversationId?: string | undefined;
+}, {
+    title?: string | undefined;
+    conversationId?: string | undefined;
+}>;
+/**
+ * Schema for build context passed to system prompt builder.
+ *
+ * Contains runtime information needed to construct the system prompt.
+ */
+export declare const BuildContextSchema: z.ZodObject<{
+    availableMarkers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    availableTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    commandType: z.ZodOptional<z.ZodEnum<["curate", "query"]>>;
+    conversationMetadata: z.ZodOptional<z.ZodObject<{
+        conversationId: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        title?: string | undefined;
+        conversationId?: string | undefined;
+    }, {
+        title?: string | undefined;
+        conversationId?: string | undefined;
+    }>>;
+    environmentContext: z.ZodOptional<z.ZodAny>;
+    fileReferenceInstructions: z.ZodOptional<z.ZodString>;
+    memoryManager: z.ZodOptional<z.ZodAny>;
+}, "strict", z.ZodTypeAny, {
+    availableMarkers?: Record<string, string> | undefined;
+    availableTools?: string[] | undefined;
+    commandType?: "curate" | "query" | undefined;
+    conversationMetadata?: {
+        title?: string | undefined;
+        conversationId?: string | undefined;
+    } | undefined;
+    environmentContext?: any;
+    fileReferenceInstructions?: string | undefined;
+    memoryManager?: any;
+}, {
+    availableMarkers?: Record<string, string> | undefined;
+    availableTools?: string[] | undefined;
+    commandType?: "curate" | "query" | undefined;
+    conversationMetadata?: {
+        title?: string | undefined;
+        conversationId?: string | undefined;
+    } | undefined;
+    environmentContext?: any;
+    fileReferenceInstructions?: string | undefined;
+    memoryManager?: any;
+}>;
+/**
+ * Validated build context type.
+ */
+export type ValidatedBuildContext = z.infer<typeof BuildContextSchema>;
+/**
+ * Schema for environment context builder options.
+ */
+export declare const EnvironmentContextOptionsSchema: z.ZodObject<{
+    includeBrvStructure: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    includeFileTree: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    maxFileTreeDepth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxFileTreeEntries: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    workingDirectory: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    workingDirectory: string;
+    includeBrvStructure: boolean;
+    includeFileTree: boolean;
+    maxFileTreeDepth: number;
+    maxFileTreeEntries: number;
+}, {
+    workingDirectory: string;
+    includeBrvStructure?: boolean | undefined;
+    includeFileTree?: boolean | undefined;
+    maxFileTreeDepth?: number | undefined;
+    maxFileTreeEntries?: number | undefined;
+}>;
+/**
+ * Validated environment context options type.
+ */
+export type ValidatedEnvironmentContextOptions = z.infer<typeof EnvironmentContextOptionsSchema>;
+/**
+ * Schema for reflection prompt context.
+ */
+export declare const ReflectionContextSchema: z.ZodObject<{
+    currentIteration: z.ZodOptional<z.ZodNumber>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodEnum<["completion_check", "final_iteration", "mid_point_check", "near_max_iterations"]>;
+}, "strict", z.ZodTypeAny, {
+    type: "completion_check" | "final_iteration" | "mid_point_check" | "near_max_iterations";
+    maxIterations?: number | undefined;
+    currentIteration?: number | undefined;
+}, {
+    type: "completion_check" | "final_iteration" | "mid_point_check" | "near_max_iterations";
+    maxIterations?: number | undefined;
+    currentIteration?: number | undefined;
+}>;
+/**
+ * Validated reflection context type.
+ */
+export type ValidatedReflectionContext = z.infer<typeof ReflectionContextSchema>;