byterover-cli 0.2.1 → 0.3.0

package/dist/core/domain/entities/playbook.js

@@ -1,8 +1,8 @@
 import { Bullet } from './bullet.js';
 /**
  * The central knowledge repository that stores and manages bullets.
- * Playbooks are organized into sections and support delta operations.
- * Playbooks are used as an temporary notes then will be pushed to byterover for usage
+ * Playbooks are organized into sections.
+ * Playbooks are used as temporary notes then will be pushed to byterover for usage.
  */
 export class Playbook {
     bullets;
@@ -13,46 +13,6 @@ export class Playbook {
         this.sections = new Map(sections);
         this.nextId = nextId;
     }
-    // ===== Static Factory Methods =====
-    /**
-     * Creates a Playbook instance from a JSON object
-     * @param json The playbook JSON data
-     * @param contentStore Optional content store for loading bullet content from files
-     * @param directory Optional directory for loading content files
-     */
-    static async fromJson(json, contentStore, directory) {
-        const bullets = new Map();
-        const sections = new Map();
-        // Deserialize bullets
-        const bulletEntries = Object.entries(json.bullets ?? {});
-        // Load all content in parallel if needed
-        const contentPromises = bulletEntries.map(async ([id, bulletData]) => {
-            if (bulletData.content) {
-                return bulletData.content;
-            }
-            return contentStore.load(id, directory);
-        });
-        const contents = await Promise.all(contentPromises);
-        // Create bullets with loaded content
-        for (const [index, [id, bulletData]] of bulletEntries.entries()) {
-            bullets.set(id, Bullet.fromJson(bulletData, contents[index]));
-        }
-        // Deserialize sections
-        for (const [section, bulletIds] of Object.entries(json.sections ?? {})) {
-            sections.set(section, bulletIds);
-        }
-        return new Playbook(bullets, sections, json.nextId ?? 1);
-    }
-    /**
-     * Deserializes from JSON string
-     * @param data The JSON string
-     * @param contentStore Optional content store for loading bullet content from files
-     * @param directory Optional directory for loading content files
-     */
-    static async loads(data, contentStore, directory) {
-        const json = JSON.parse(data);
-        return Playbook.fromJson(json, contentStore, directory);
-    }
     // ===== CRUD Operations =====
     /**
      * Adds a new bullet to the playbook
@@ -96,14 +56,6 @@ export class Playbook {
         this.bullets.set(bulletId, updatedBullet);
         return updatedBullet;
     }
-    /**
-     * Applies a batch of delta operations to the playbook
-     */
-    applyDelta(delta) {
-        for (const operation of delta.operations) {
-            this._applyOperation(operation);
-        }
-    }
     /**
      * Converts playbook to markdown format for LLM prompts
      */
@@ -162,7 +114,6 @@ export class Playbook {
     getSections() {
         return [...this.sections.keys()].sort();
     }
-    // ===== Delta Operations =====
     /**
      * Removes a bullet from the playbook
      */
@@ -249,25 +200,6 @@ export class Playbook {
         this.bullets.set(bulletId, updatedBullet);
         return updatedBullet;
     }
-    _applyOperation(operation) {
-        switch (operation.type) {
-            case 'ADD': {
-                this.addBullet(operation.section, operation.content, operation.bulletId, operation.metadata);
-                break;
-            }
-            case 'REMOVE': {
-                this.removeBullet(operation.bulletId);
-                break;
-            }
-            case 'UPDATE': {
-                this.updateBullet(operation.bulletId, {
-                    content: operation.content,
-                    metadata: operation.metadata,
-                });
-                break;
-            }
-        }
-    }
     // ===== Private Helpers =====
     _generateId(section) {
         // Convert section to prefix: "Common Errors" -> "common"

package/dist/core/domain/errors/brv-config-version-error.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error thrown when the BrvConfig version is missing or incompatible.
+ *
+ * This error is used to detect outdated `.brv/config.json` files that need
+ * to be reinitialized via `brv init`.
+ */
+export declare class BrvConfigVersionError extends Error {
+    /** The version found in the config file, or undefined if missing. */
+    readonly currentVersion: string | undefined;
+    /** The version expected by the current CLI. */
+    readonly expectedVersion: string;
+    constructor(params: {
+        currentVersion: string | undefined;
+        expectedVersion: string;
+    });
+}

package/dist/core/domain/errors/brv-config-version-error.js

@@ -0,0 +1,21 @@
+/**
+ * Error thrown when the BrvConfig version is missing or incompatible.
+ *
+ * This error is used to detect outdated `.brv/config.json` files that need
+ * to be reinitialized via `brv init`.
+ */
+export class BrvConfigVersionError extends Error {
+    /** The version found in the config file, or undefined if missing. */
+    currentVersion;
+    /** The version expected by the current CLI. */
+    expectedVersion;
+    constructor(params) {
+        const message = params.currentVersion
+            ? `Config version mismatch (found: ${params.currentVersion}, expected: ${params.expectedVersion}). Please run 'brv init' to reinitialize.`
+            : `Config version missing. Please run 'brv init' to reinitialize.`;
+        super(message);
+        this.name = 'BrvConfigVersionError';
+        this.currentVersion = params.currentVersion;
+        this.expectedVersion = params.expectedVersion;
+    }
+}

package/dist/core/domain/knowledge/directory-manager.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Result of ensuring knowledge structure exists.
+ */
+export interface EnsureStructureResult {
+    contextTreeExisted: boolean;
+    indexExisted: boolean;
+}
+/**
+ * Result of creating or updating a domain/topic.
+ */
+export interface CreateOrUpdateResult {
+    created: boolean;
+    skipped: boolean;
+    updated: boolean;
+}
+/**
+ * Manages directory and file operations for knowledge structure.
+ * Handles existing directories and files without recreating them.
+ */
+export declare const DirectoryManager: {
+    /**
+     * Create or update a domain folder.
+     * If domain exists, returns indication to update; if new, creates folder.
+     *
+     * @param domainPath - Full path to domain folder
+     * @returns Whether domain was created, updated, or skipped
+     */
+    createOrUpdateDomain(domainPath: string): Promise<CreateOrUpdateResult>;
+    /**
+     * Create or update a topic folder.
+     * If topic exists, returns indication to update; if new, creates folder.
+     *
+     * @param topicPath - Full path to topic folder
+     * @returns Whether topic was created, updated, or skipped
+     */
+    createOrUpdateTopic(topicPath: string): Promise<CreateOrUpdateResult>;
+    /**
+     * Ensure the base knowledge structure exists.
+     * Creates .brv/context-tree/ directory if it doesn't exist.
+     *
+     * @param basePath - Base path for knowledge storage (typically .brv/context-tree)
+     * @returns Information about what existed and what was created
+     */
+    ensureKnowledgeStructure(basePath: string): Promise<EnsureStructureResult>;
+    /**
+     * Ensure parent directory exists for a file path.
+     *
+     * @param filePath - Path to file
+     */
+    ensureParentDirectory(filePath: string): Promise<void>;
+    /**
+     * Check if a file exists.
+     *
+     * @param filePath - Path to file
+     * @returns true if file exists, false otherwise
+     */
+    fileExists(filePath: string): Promise<boolean>;
+    /**
+     * List all markdown files recursively in a directory.
+     *
+     * @param dirPath - Directory to scan
+     * @returns Array of absolute paths to .md files
+     */
+    listMarkdownFiles(dirPath: string): Promise<string[]>;
+    /**
+     * Read a file's content.
+     *
+     * @param filePath - Path to file
+     * @returns File content as string
+     */
+    readFile(filePath: string): Promise<string>;
+    /**
+     * Write a file atomically (write to temp, then rename).
+     * This ensures the file is never in a partially written state.
+     *
+     * @param filePath - Path to file
+     * @param content - Content to write
+     */
+    writeFileAtomic(filePath: string, content: string): Promise<void>;
+};

package/dist/core/domain/knowledge/directory-manager.js

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Manages directory and file operations for knowledge structure.
+ * Handles existing directories and files without recreating them.
+ */
+export const DirectoryManager = {
+    /**
+     * Create or update a domain folder.
+     * If domain exists, returns indication to update; if new, creates folder.
+     *
+     * @param domainPath - Full path to domain folder
+     * @returns Whether domain was created, updated, or skipped
+     */
+    async createOrUpdateDomain(domainPath) {
+        try {
+            await fs.access(domainPath);
+            // Domain exists
+            return { created: false, skipped: false, updated: true };
+        }
+        catch {
+            // Domain doesn't exist, create it
+            await fs.mkdir(domainPath, { recursive: true });
+            return { created: true, skipped: false, updated: false };
+        }
+    },
+    /**
+     * Create or update a topic folder.
+     * If topic exists, returns indication to update; if new, creates folder.
+     *
+     * @param topicPath - Full path to topic folder
+     * @returns Whether topic was created, updated, or skipped
+     */
+    async createOrUpdateTopic(topicPath) {
+        try {
+            await fs.access(topicPath);
+            // Topic exists
+            return { created: false, skipped: false, updated: true };
+        }
+        catch {
+            // Topic doesn't exist, create it
+            await fs.mkdir(topicPath, { recursive: true });
+            return { created: true, skipped: false, updated: false };
+        }
+    },
+    /**
+     * Ensure the base knowledge structure exists.
+     * Creates .brv/context-tree/ directory if it doesn't exist.
+     *
+     * @param basePath - Base path for knowledge storage (typically .brv/context-tree)
+     * @returns Information about what existed and what was created
+     */
+    async ensureKnowledgeStructure(basePath) {
+        // Check if .brv/context-tree/ exists
+        let contextTreeExisted = false;
+        try {
+            await fs.access(basePath);
+            contextTreeExisted = true;
+        }
+        catch {
+            // Directory doesn't exist, create it
+            await fs.mkdir(basePath, { recursive: true });
+        }
+        return {
+            contextTreeExisted,
+            indexExisted: false, // No longer creating index.json
+        };
+    },
+    /**
+     * Ensure parent directory exists for a file path.
+     *
+     * @param filePath - Path to file
+     */
+    async ensureParentDirectory(filePath) {
+        const parentDir = dirname(filePath);
+        await fs.mkdir(parentDir, { recursive: true });
+    },
+    /**
+     * Check if a file exists.
+     *
+     * @param filePath - Path to file
+     * @returns true if file exists, false otherwise
+     */
+    async fileExists(filePath) {
+        try {
+            await fs.access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    /**
+     * List all markdown files recursively in a directory.
+     *
+     * @param dirPath - Directory to scan
+     * @returns Array of absolute paths to .md files
+     */
+    async listMarkdownFiles(dirPath) {
+        const mdFiles = [];
+        const scanDirectory = async (currentPath) => {
+            try {
+                const entries = await fs.readdir(currentPath, { withFileTypes: true });
+                const subdirectories = [];
+                for (const entry of entries) {
+                    const fullPath = join(currentPath, entry.name);
+                    if (entry.isDirectory()) {
+                        subdirectories.push(fullPath);
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.md')) {
+                        mdFiles.push(fullPath);
+                    }
+                }
+                // Process subdirectories recursively
+                await Promise.all(subdirectories.map((subdir) => scanDirectory(subdir)));
+            }
+            catch {
+                // Directory doesn't exist or not accessible, skip it
+            }
+        };
+        await scanDirectory(dirPath);
+        return mdFiles;
+    },
+    /**
+     * Read a file's content.
+     *
+     * @param filePath - Path to file
+     * @returns File content as string
+     */
+    async readFile(filePath) {
+        return fs.readFile(filePath, 'utf8');
+    },
+    /**
+     * Write a file atomically (write to temp, then rename).
+     * This ensures the file is never in a partially written state.
+     *
+     * @param filePath - Path to file
+     * @param content - Content to write
+     */
+    async writeFileAtomic(filePath, content) {
+        const tempPath = `${filePath}.tmp`;
+        await fs.writeFile(tempPath, content, 'utf8');
+        await fs.rename(tempPath, filePath);
+    },
+};

package/dist/core/domain/knowledge/markdown-writer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Context data for generating context.md files.
+ */
+export interface ContextData {
+    name: string;
+    relations?: string[];
+    snippets: string[];
+}
+/**
+ * Generates Markdown files for knowledge context.
+ */
+export declare const MarkdownWriter: {
+    /**
+     * Generate context.md content with snippets and optional relations.
+     * Used for both topics and subtopics in the knowledge hierarchy.
+     */
+    generateContext(data: ContextData): string;
+};

package/dist/core/domain/knowledge/markdown-writer.js

@@ -0,0 +1,18 @@
+import { generateRelationsSection } from './relation-parser.js';
+/**
+ * Generates Markdown files for knowledge context.
+ */
+export const MarkdownWriter = {
+    /**
+     * Generate context.md content with snippets and optional relations.
+     * Used for both topics and subtopics in the knowledge hierarchy.
+     */
+    generateContext(data) {
+        const snippets = data.snippets || [];
+        const relations = data.relations || [];
+        const relationsSection = generateRelationsSection(relations);
+        return `${relationsSection}
+${snippets.length > 0 ? snippets.map(s => `${s}`).join('\n\n---\n\n') : 'No context available.'}
+`;
+    },
+};

package/dist/core/domain/knowledge/relation-parser.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Utilities for parsing and managing context relations.
+ * Relations are expressed using @ notation: @domain/topic or @domain/topic/subtopic
+ */
+/**
+ * Parse relations from context.md content.
+ * Extracts all @domain/topic or @domain/topic/subtopic references.
+ *
+ * @param content - Markdown content to parse
+ * @returns Array of unique relation paths (without @ prefix)
+ *
+ * @example
+ * ```ts
+ * const content = `
+ * ## Relations
+ * @code_style/error-handling
+ * @structure/api-endpoints
+ * `
+ * parseRelations(content) // ['code_style/error-handling', 'structure/api-endpoints']
+ * ```
+ */
+export declare function parseRelations(content: string): string[];
+/**
+ * Validate a relation path format.
+ * Valid formats: domain/topic or domain/topic/subtopic
+ *
+ * @param path - Relation path to validate (without @ prefix)
+ * @returns True if path format is valid
+ *
+ * @example
+ * ```ts
+ * validateRelationPath('code_style/error-handling') // true
+ * validateRelationPath('code_style/error-handling/try-catch') // true
+ * validateRelationPath('invalid') // false
+ * validateRelationPath('too/many/parts/here') // false
+ * ```
+ */
+export declare function validateRelationPath(path: string): boolean;
+/**
+ * Resolve a relation path to an absolute file system path.
+ *
+ * @param basePath - Base path to context tree (e.g., '.brv/context-tree')
+ * @param relation - Relation path (e.g., 'domain/topic' or 'domain/topic/subtopic')
+ * @returns Absolute path to the context.md file
+ *
+ * @example
+ * ```ts
+ * resolveRelationPath('.brv/context-tree', 'code_style/error-handling')
+ * // => '.brv/context-tree/code_style/error-handling/context.md'
+ *
+ * resolveRelationPath('.brv/context-tree', 'structure/api/endpoints')
+ * // => '.brv/context-tree/structure/api/endpoints/context.md'
+ * ```
+ */
+export declare function resolveRelationPath(basePath: string, relation: string): string;
+/**
+ * Format a relation path using @ notation.
+ *
+ * @param domain - Domain name
+ * @param topic - Topic name
+ * @param subtopic - Optional subtopic name
+ * @returns Formatted relation string with @ prefix
+ *
+ * @example
+ * ```ts
+ * formatRelation('code_style', 'error-handling')
+ * // => '@code_style/error-handling'
+ *
+ * formatRelation('structure', 'api', 'endpoints')
+ * // => '@structure/api/endpoints'
+ * ```
+ */
+export declare function formatRelation(domain: string, topic: string, subtopic?: string): string;
+/**
+ * Generate the Relations section for context.md.
+ * Returns empty string if no relations provided.
+ *
+ * @param relations - Array of relation paths (without @ prefix)
+ * @returns Markdown formatted Relations section or empty string
+ *
+ * @example
+ * ```ts
+ * generateRelationsSection(['code_style/error-handling', 'structure/api'])
+ * // => '\n## Relations\n@code_style/error-handling\n@structure/api\n'
+ *
+ * generateRelationsSection([])
+ * // => ''
+ * ```
+ */
+export declare function generateRelationsSection(relations: string[]): string;

package/dist/core/domain/knowledge/relation-parser.js

@@ -0,0 +1,131 @@
+/**
+ * Utilities for parsing and managing context relations.
+ * Relations are expressed using @ notation: @domain/topic or @domain/topic/subtopic
+ */
+/**
+ * Regular expression to match relation paths in markdown content.
+ * Matches: @domain/topic or @domain/topic/subtopic
+ */
+const RELATION_PATTERN = /@([\w-]+)\/([\w-]+)(?:\/([\w-]+))?/g;
+/**
+ * Parse relations from context.md content.
+ * Extracts all @domain/topic or @domain/topic/subtopic references.
+ *
+ * @param content - Markdown content to parse
+ * @returns Array of unique relation paths (without @ prefix)
+ *
+ * @example
+ * ```ts
+ * const content = `
+ * ## Relations
+ * @code_style/error-handling
+ * @structure/api-endpoints
+ * `
+ * parseRelations(content) // ['code_style/error-handling', 'structure/api-endpoints']
+ * ```
+ */
+export function parseRelations(content) {
+    const relations = new Set();
+    // Extract all @domain/topic or @domain/topic/subtopic patterns
+    const matches = content.matchAll(RELATION_PATTERN);
+    for (const match of matches) {
+        const [, domain, topic, subtopic] = match;
+        const relation = subtopic
+            ? `${domain}/${topic}/${subtopic}`
+            : `${domain}/${topic}`;
+        relations.add(relation);
+    }
+    return [...relations];
+}
+/**
+ * Validate a relation path format.
+ * Valid formats: domain/topic or domain/topic/subtopic
+ *
+ * @param path - Relation path to validate (without @ prefix)
+ * @returns True if path format is valid
+ *
+ * @example
+ * ```ts
+ * validateRelationPath('code_style/error-handling') // true
+ * validateRelationPath('code_style/error-handling/try-catch') // true
+ * validateRelationPath('invalid') // false
+ * validateRelationPath('too/many/parts/here') // false
+ * ```
+ */
+export function validateRelationPath(path) {
+    const parts = path.split('/');
+    // Must have 2 or 3 parts: domain/topic or domain/topic/subtopic
+    if (parts.length < 2 || parts.length > 3) {
+        return false;
+    }
+    // Each part must be non-empty and contain only valid characters
+    const validPartPattern = /^[\w-]+$/;
+    return parts.every(part => validPartPattern.test(part));
+}
+/**
+ * Resolve a relation path to an absolute file system path.
+ *
+ * @param basePath - Base path to context tree (e.g., '.brv/context-tree')
+ * @param relation - Relation path (e.g., 'domain/topic' or 'domain/topic/subtopic')
+ * @returns Absolute path to the context.md file
+ *
+ * @example
+ * ```ts
+ * resolveRelationPath('.brv/context-tree', 'code_style/error-handling')
+ * // => '.brv/context-tree/code_style/error-handling/context.md'
+ *
+ * resolveRelationPath('.brv/context-tree', 'structure/api/endpoints')
+ * // => '.brv/context-tree/structure/api/endpoints/context.md'
+ * ```
+ */
+export function resolveRelationPath(basePath, relation) {
+    const parts = relation.split('/');
+    return `${basePath}/${parts.join('/')}/context.md`;
+}
+/**
+ * Format a relation path using @ notation.
+ *
+ * @param domain - Domain name
+ * @param topic - Topic name
+ * @param subtopic - Optional subtopic name
+ * @returns Formatted relation string with @ prefix
+ *
+ * @example
+ * ```ts
+ * formatRelation('code_style', 'error-handling')
+ * // => '@code_style/error-handling'
+ *
+ * formatRelation('structure', 'api', 'endpoints')
+ * // => '@structure/api/endpoints'
+ * ```
+ */
+export function formatRelation(domain, topic, subtopic) {
+    return subtopic
+        ? `@${domain}/${topic}/${subtopic}`
+        : `@${domain}/${topic}`;
+}
+/**
+ * Generate the Relations section for context.md.
+ * Returns empty string if no relations provided.
+ *
+ * @param relations - Array of relation paths (without @ prefix)
+ * @returns Markdown formatted Relations section or empty string
+ *
+ * @example
+ * ```ts
+ * generateRelationsSection(['code_style/error-handling', 'structure/api'])
+ * // => '\n## Relations\n@code_style/error-handling\n@structure/api\n'
+ *
+ * generateRelationsSection([])
+ * // => ''
+ * ```
+ */
+export function generateRelationsSection(relations) {
+    if (relations.length === 0) {
+        return '';
+    }
+    const formattedRelations = relations
+        .map(rel => `@${rel}`)
+        .join('\n');
+    return `\n## Relations\n${formattedRelations}\n`;
+}