byterover-cli 0.2.0 → 0.3.0

package/dist/core/domain/entities/executor-output.d.ts

@@ -1,27 +0,0 @@
-export interface ExecutorOutputJson {
-    bulletIds: string[];
-    finalAnswer: string;
-    hint: string;
-    reasoning: string;
-    toolUsage: string[];
-}
-export interface ExecutorOutputOptions {
-    bulletIds?: string[];
-    finalAnswer: string;
-    hint: string;
-    reasoning: string;
-    toolUsage?: string[];
-}
-/**
- * Output from the executor (the coding agent) phase.
- * Contains reasoning, final answer, and bullets referenced.
- */
-export declare class ExecutorOutput {
-    readonly bulletIds: string[];
-    readonly finalAnswer: string;
-    readonly hint: string;
-    readonly reasoning: string;
-    readonly toolUsage: string[];
-    constructor(options: ExecutorOutputOptions);
-    toJson(): ExecutorOutputJson;
-}

package/dist/core/domain/entities/executor-output.js

@@ -1,33 +0,0 @@
-/**
- * Output from the executor (the coding agent) phase.
- * Contains reasoning, final answer, and bullets referenced.
- */
-export class ExecutorOutput {
-    bulletIds;
-    finalAnswer;
-    hint;
-    reasoning;
-    toolUsage;
-    constructor(options) {
-        if (options.reasoning.trim().length === 0) {
-            throw new Error('Executor reasoning cannot be empty');
-        }
-        if (options.finalAnswer.trim().length === 0) {
-            throw new Error('Executor final answer cannot be empty');
-        }
-        this.hint = options.hint;
-        this.reasoning = options.reasoning;
-        this.finalAnswer = options.finalAnswer;
-        this.bulletIds = [...(options.bulletIds ?? [])];
-        this.toolUsage = [...(options.toolUsage ?? [])];
-    }
-    toJson() {
-        return {
-            bulletIds: this.bulletIds,
-            finalAnswer: this.finalAnswer,
-            hint: this.hint,
-            reasoning: this.reasoning,
-            toolUsage: this.toolUsage,
-        };
-    }
-}

package/dist/core/domain/entities/reflector-output.d.ts

@@ -1,38 +0,0 @@
-export interface BulletTag {
-    id: string;
-    tag: string;
-}
-export interface ReflectorOutputInput {
-    bulletTags: BulletTag[];
-    correctApproach: string;
-    errorIdentification: string;
-    hint: string;
-    keyInsight: string;
-    reasoning: string;
-    rootCauseAnalysis: string;
-}
-export interface ReflectorOutputJson {
-    bulletTags: BulletTag[];
-    correctApproach: string;
-    errorIdentification: string;
-    hint: string;
-    keyInsight: string;
-    reasoning: string;
-    rootCauseAnalysis: string;
-}
-/**
- * Output from the reflector phase.
- * Contains error analysis and bullet tagging.
- */
-export declare class ReflectorOutput {
-    readonly bulletTags: BulletTag[];
-    readonly correctApproach: string;
-    readonly errorIdentification: string;
-    readonly hint: string;
-    readonly keyInsight: string;
-    readonly reasoning: string;
-    readonly rootCauseAnalysis: string;
-    constructor(input: ReflectorOutputInput);
-    static fromJson(json: ReflectorOutputJson): ReflectorOutput;
-    toJson(): ReflectorOutputJson;
-}

package/dist/core/domain/entities/reflector-output.js

@@ -1,44 +0,0 @@
-/**
- * Output from the reflector phase.
- * Contains error analysis and bullet tagging.
- */
-export class ReflectorOutput {
-    bulletTags;
-    correctApproach;
-    errorIdentification;
-    hint;
-    keyInsight;
-    reasoning;
-    rootCauseAnalysis;
-    constructor(input) {
-        this.reasoning = input.reasoning;
-        this.errorIdentification = input.errorIdentification;
-        this.rootCauseAnalysis = input.rootCauseAnalysis;
-        this.correctApproach = input.correctApproach;
-        this.keyInsight = input.keyInsight;
-        this.hint = input.hint;
-        this.bulletTags = [...input.bulletTags];
-    }
-    static fromJson(json) {
-        return new ReflectorOutput({
-            bulletTags: json.bulletTags,
-            correctApproach: json.correctApproach,
-            errorIdentification: json.errorIdentification,
-            hint: json.hint || '',
-            keyInsight: json.keyInsight,
-            reasoning: json.reasoning,
-            rootCauseAnalysis: json.rootCauseAnalysis,
-        });
-    }
-    toJson() {
-        return {
-            bulletTags: this.bulletTags,
-            correctApproach: this.correctApproach,
-            errorIdentification: this.errorIdentification,
-            hint: this.hint,
-            keyInsight: this.keyInsight,
-            reasoning: this.reasoning,
-            rootCauseAnalysis: this.rootCauseAnalysis,
-        };
-    }
-}

package/dist/core/interfaces/i-ace-prompt-builder.d.ts

@@ -1,48 +0,0 @@
-import type { ExecutorOutput } from '../domain/entities/executor-output.js';
-import type { Playbook } from '../domain/entities/playbook.js';
-import type { ReflectorOutput } from '../domain/entities/reflector-output.js';
-/**
- * Parameters for building a reflector prompt
- */
-export interface ReflectorPromptParams {
-    executorOutput: ExecutorOutput;
-    feedback: string;
-    groundTruth?: string;
-    playbook: Playbook;
-    task: string;
-}
-/**
- * Port for building prompts for ACE pipeline
- * This abstraction allows different prompt strategies for different roles of coding agent
- */
-export interface IAcePromptBuilder {
-    /**
-     * Builds the curator prompt for updating the playbook.
-     * The curator transforms reflections into structured playbook updates.
-     *
-     * @param reflection The reflector's analysis and insights
-     * @param playbook The current playbook to update
-     * @param questionContext Context about what task was being solved
-     * @returns A prompt string ready for the coding agent
-     */
-    buildCuratorPrompt: (reflection: ReflectorOutput, playbook: Playbook, questionContext: string) => string;
-    /**
-     * Builds the executor (generator) prompt for coding agents.
-     * The executor uses the playbook to solve tasks with context-aware reasoning.
-     *
-     * @param task The task or question to solve
-     * @param context Additional context about the task (e.g., file contents, error messages)
-     * @param playbook The knowledge playbook containing strategies and lessons
-     * @param recentReflections Recent reflection summaries to avoid repeating mistakes
-     * @returns A prompt string ready for the coding aqgent
-     */
-    buildExecutorPrompt: (task: string, context: string, playbook: Playbook, recentReflections: string[]) => string;
-    /**
-     * Builds the reflector prompt for analyzing execution results.
-     * The reflector identifies errors, root causes, and key insights.
-     *
-     * @param params The reflector prompt parameters
-     * @returns A prompt string ready for the coding agent
-     */
-    buildReflectorPrompt: (params: ReflectorPromptParams) => string;
-}

package/dist/core/interfaces/i-bullet-content-store.d.ts

@@ -1,36 +0,0 @@
-/**
- * Port for bullet content file persistence operations.
- * Manages individual markdown files for bullet content.
- */
-export interface IBulletContentStore {
-    /**
-     * Deletes a bullet content file from storage.
-     * Does nothing if the content file doesn't exist.
-     * @param bulletId The bullet ID
-     * @param directory The project directory (defaults to current working directory)
-     */
-    delete: (bulletId: string, directory?: string) => Promise<void>;
-    /**
-     * Checks if a bullet content file exists.
-     * @param bulletId The bullet ID
-     * @param directory The project directory (defaults to current working directory)
-     * @returns True if content file exists, false otherwise
-     */
-    exists: (bulletId: string, directory?: string) => Promise<boolean>;
-    /**
-     * Loads bullet content from a markdown file.
-     * @param bulletId The bullet ID
-     * @param directory The project directory (defaults to current working directory)
-     * @returns The content, or undefined if not found
-     */
-    load: (bulletId: string, directory?: string) => Promise<string | undefined>;
-    /**
-     * Saves bullet content to a markdown file.
-     * Creates the directory structure if it doesn't exist.
-     * @param bulletId The bullet ID
-     * @param content The bullet content
-     * @param directory The project directory (defaults to current working directory)
-     * @returns The file path where content was saved
-     */
-    save: (bulletId: string, content: string, directory?: string) => Promise<string>;
-}

package/dist/core/interfaces/i-delta-store.d.ts

@@ -1,15 +0,0 @@
-import type { DeltaBatch } from '../domain/entities/delta-batch.js';
-/**
- * Interface for delta batch storage operations.
- * Implementations can be file-based (for production) or in-memory (for testing).
- */
-export interface IDeltaStore {
-    /**
-     * Saves a delta batch to storage.
-     * @param deltaBatch - The delta batch to save
-     * @param hint - Optional hint to include in the filename for identification
-     * @param directory - Optional base directory (defaults to current working directory)
-     * @returns The absolute path where the delta batch was saved
-     */
-    save(deltaBatch: DeltaBatch, hint?: string, directory?: string): Promise<string>;
-}

package/dist/core/interfaces/i-executor-output-store.d.ts

@@ -1,14 +0,0 @@
-import type { ExecutorOutput } from '../domain/entities/executor-output.js';
-/**
- * Interface for executor output storage operations.
- * Implementations can be file-based (for production) or in-memory (for testing).
- */
-export interface IExecutorOutputStore {
-    /**
-     * Saves executor output to storage.
-     * @param output - The executor output to save
-     * @param directory - Optional base directory (defaults to current working directory)
-     * @returns The absolute path where the executor output was saved
-     */
-    save(output: ExecutorOutput, directory?: string): Promise<string>;
-}

package/dist/core/interfaces/i-playbook-service.d.ts

@@ -1,69 +0,0 @@
-import type { Bullet, BulletMetadata } from '../domain/entities/bullet.js';
-import type { DeltaBatch } from '../domain/entities/delta-batch.js';
-import type { Playbook } from '../domain/entities/playbook.js';
-import type { ReflectorOutput } from '../domain/entities/reflector-output.js';
-/**
- * Interface for playbook operations service.
- * Provides high-level operations for managing ACE playbooks including
- * initialization, bullet management, delta application, and reflection tag processing.
- */
-export interface IPlaybookService {
-    /**
-     * Adds a new bullet or updates an existing bullet in the playbook.
-     * @param params - Bullet parameters
-     * @param params.section - Section name for the bullet
-     * @param params.content - Content of the bullet
-     * @param params.bulletId - Optional bullet ID for update operation
-     * @param params.metadata - Optional metadata (tags, related files, timestamp)
-     * @param params.directory - Optional base directory (defaults to current working directory)
-     * @returns The created or updated bullet
-     * @throws Error if validation fails or bulletId not found for updates
-     */
-    addOrUpdateBullet(params: {
-        bulletId?: string;
-        content: string;
-        directory?: string;
-        metadata?: BulletMetadata;
-        section: string;
-    }): Promise<Bullet>;
-    /**
-     * Applies delta operations (ADD/UPDATE/REMOVE) to the playbook.
-     * Creates a new playbook if it doesn't exist.
-     * @param params - Delta application parameters
-     * @param params.delta - Delta batch containing operations to apply
-     * @param params.directory - Optional base directory (defaults to current working directory)
-     * @returns Result containing operations applied count and updated playbook
-     * @throws Error if delta application fails
-     */
-    applyDelta(params: {
-        delta: DeltaBatch;
-        directory?: string;
-    }): Promise<{
-        operationsApplied: number;
-        playbook: Playbook;
-    }>;
-    /**
-     * Applies reflection bullet tags to existing bullets in the playbook.
-     * Skips bullets that don't exist in the playbook.
-     * @param params - Reflection tag parameters
-     * @param params.reflection - Reflection output containing bullet tags
-     * @param params.directory - Optional base directory (defaults to current working directory)
-     * @returns Result containing tags applied count and updated playbook
-     * @throws Error if playbook not found or tag application fails
-     */
-    applyReflectionTags(params: {
-        directory?: string;
-        reflection: ReflectorOutput;
-    }): Promise<{
-        playbook: Playbook;
-        tagsApplied: number;
-    }>;
-    /**
-     * Initializes the ACE playbook directory structure and creates an empty playbook.
-     * Creates .brv/ace/ directory with subdirectories: reflections/, executor-outputs/, deltas/
-     * @param directory - Optional base directory (defaults to current working directory)
-     * @returns The absolute path to the created playbook file
-     * @throws Error if playbook already exists or initialization fails
-     */
-    initialize(directory?: string): Promise<string>;
-}

package/dist/core/interfaces/i-playbook-store.d.ts

@@ -1,38 +0,0 @@
-import type { Playbook } from '../domain/entities/playbook.js';
-/**
- * Port for playbook persistence operations.
- * Implementations can use file system, database, or remote storage.
- */
-export interface IPlaybookStore {
-    /**
-     * Clears the playbook content by replacing it with an empty playbook.
-     * Does nothing if the playbook doesn't exist.
-     * @param directory The project directory (defaults to current working directory)
-     */
-    clear: (directory?: string) => Promise<void>;
-    /**
-     * Deletes a playbook from storage.
-     * Does nothing if the playbook doesn't exist.
-     * @param directory The project directory (defaults to current working directory)
-     */
-    delete: (directory?: string) => Promise<void>;
-    /**
-     * Checks if a playbook exists in the specified directory.
-     * @param directory The project directory (defaults to current working directory)
-     * @returns True if playbook exists, false otherwise
-     */
-    exists: (directory?: string) => Promise<boolean>;
-    /**
-     * Loads a playbook from storage.
-     * @param directory The project directory (defaults to current working directory)
-     * @returns The playbook, or undefined if not found
-     */
-    load: (directory?: string) => Promise<Playbook | undefined>;
-    /**
-     * Saves a playbook to storage.
-     * Creates the directory structure if it doesn't exist.
-     * @param playbook The playbook to save
-     * @param directory The project directory (defaults to current working directory)
-     */
-    save: (playbook: Playbook, directory?: string) => Promise<void>;
-}

package/dist/core/interfaces/i-reflection-store.d.ts

@@ -1,21 +0,0 @@
-import type { ReflectorOutput } from '../domain/entities/reflector-output.js';
-/**
- * Interface for reflection output storage operations.
- * Implementations can be file-based (for production) or in-memory (for testing).
- */
-export interface IReflectionStore {
-    /**
-     * Loads the most recent reflections from storage.
-     * @param directory - Optional base directory (defaults to current working directory)
-     * @param count - Maximum number of recent reflections to load (default: 3)
-     * @returns Array of recent reflections, ordered from most recent to oldest
-     */
-    loadRecent(directory?: string, count?: number): Promise<ReflectorOutput[]>;
-    /**
-     * Saves a reflection output to storage.
-     * @param reflection - The reflection output to save
-     * @param directory - Optional base directory (defaults to current working directory)
-     * @returns The absolute path where the reflection was saved
-     */
-    save(reflection: ReflectorOutput, directory?: string): Promise<string>;
-}

package/dist/infra/ace/ace-file-utils.d.ts

@@ -1,46 +0,0 @@
-import { DeltaBatch } from '../../core/domain/entities/delta-batch.js';
-import { ExecutorOutput } from '../../core/domain/entities/executor-output.js';
-import { ReflectorOutput } from '../../core/domain/entities/reflector-output.js';
-/**
- * Sanitize hint for use in filename.
- * Converts to lowercase, replaces spaces/underscores with hyphens,
- * removes all non-alphanumeric characters except hyphens.
- * @param hint - The hint string to sanitize
- * @returns Sanitized hint suitable for filename
- */
-export declare function sanitizeHint(hint: string): string;
-/**
- * Generates a timestamped filename for ACE output files.
- * @param type - The file type prefix (e.g., 'delta', 'reflection', 'executor-output')
- * @param hint - Optional hint to include in filename
- * @returns Filename in format: {type}-{hint}-{timestamp}.json or {type}-{timestamp}.json
- */
-export declare function generateTimestampedFilename(type: string, hint?: string): string;
-/**
- * Ensures that an ACE subdirectory exists, creating it if necessary.
- * @param baseDir - The base project directory (defaults to current working directory)
- * @param subdir - The ACE subdirectory name (e.g., 'deltas', 'reflections', 'executor-outputs')
- * @returns The absolute path to the subdirectory
- */
-export declare function ensureAceDirectory(baseDir: string | undefined, subdir: string): Promise<string>;
-/**
- * Loads and parses an executor output file.
- * @param filePath - Absolute path to executor output JSON file
- * @returns ExecutorOutput entity
- * @throws Error if file doesn't exist or JSON is invalid
- */
-export declare function loadExecutorOutput(filePath: string): Promise<ExecutorOutput>;
-/**
- * Loads and parses a reflection output file.
- * @param filePath - Absolute path to reflection output JSON file
- * @returns ReflectorOutput entity
- * @throws Error if file doesn't exist or JSON is invalid
- */
-export declare function loadReflectionOutput(filePath: string): Promise<ReflectorOutput>;
-/**
- * Loads and parses a delta batch file.
- * @param filePath - Absolute path to delta batch JSON file
- * @returns DeltaBatch entity
- * @throws Error if file doesn't exist or JSON is invalid
- */
-export declare function loadDeltaBatch(filePath: string): Promise<DeltaBatch>;

package/dist/infra/ace/ace-file-utils.js

@@ -1,83 +0,0 @@
-import { mkdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { ACE_DIR, BRV_DIR } from '../../constants.js';
-import { DeltaBatch } from '../../core/domain/entities/delta-batch.js';
-import { ExecutorOutput } from '../../core/domain/entities/executor-output.js';
-import { ReflectorOutput } from '../../core/domain/entities/reflector-output.js';
-/**
- * Sanitize hint for use in filename.
- * Converts to lowercase, replaces spaces/underscores with hyphens,
- * removes all non-alphanumeric characters except hyphens.
- * @param hint - The hint string to sanitize
- * @returns Sanitized hint suitable for filename
- */
-export function sanitizeHint(hint) {
-    return hint
-        .toLowerCase()
-        .replaceAll(/[\s_]+/g, '-')
-        .replaceAll(/[^\da-z-]/g, '')
-        .replaceAll(/-+/g, '-')
-        .replaceAll(/^-|-$/g, '');
-}
-/**
- * Generates a timestamped filename for ACE output files.
- * @param type - The file type prefix (e.g., 'delta', 'reflection', 'executor-output')
- * @param hint - Optional hint to include in filename
- * @returns Filename in format: {type}-{hint}-{timestamp}.json or {type}-{timestamp}.json
- */
-export function generateTimestampedFilename(type, hint) {
-    const timestamp = new Date().toISOString().replaceAll(':', '-');
-    const sanitizedHint = hint ? sanitizeHint(hint) : '';
-    return sanitizedHint ? `${type}-${sanitizedHint}-${timestamp}.json` : `${type}-${timestamp}.json`;
-}
-/**
- * Ensures that an ACE subdirectory exists, creating it if necessary.
- * @param baseDir - The base project directory (defaults to current working directory)
- * @param subdir - The ACE subdirectory name (e.g., 'deltas', 'reflections', 'executor-outputs')
- * @returns The absolute path to the subdirectory
- */
-export async function ensureAceDirectory(baseDir, subdir) {
-    const resolvedBaseDir = baseDir ?? process.cwd();
-    const aceSubdir = join(resolvedBaseDir, BRV_DIR, ACE_DIR, subdir);
-    await mkdir(aceSubdir, { recursive: true });
-    return aceSubdir;
-}
-/**
- * Loads and parses an executor output file.
- * @param filePath - Absolute path to executor output JSON file
- * @returns ExecutorOutput entity
- * @throws Error if file doesn't exist or JSON is invalid
- */
-export async function loadExecutorOutput(filePath) {
-    const content = await readFile(filePath, 'utf8');
-    const json = JSON.parse(content);
-    return new ExecutorOutput({
-        bulletIds: json.bulletIds,
-        finalAnswer: json.finalAnswer,
-        hint: json.hint || '',
-        reasoning: json.reasoning,
-        toolUsage: json.toolUsage,
-    });
-}
-/**
- * Loads and parses a reflection output file.
- * @param filePath - Absolute path to reflection output JSON file
- * @returns ReflectorOutput entity
- * @throws Error if file doesn't exist or JSON is invalid
- */
-export async function loadReflectionOutput(filePath) {
-    const content = await readFile(filePath, 'utf8');
-    const json = JSON.parse(content);
-    return ReflectorOutput.fromJson(json);
-}
-/**
- * Loads and parses a delta batch file.
- * @param filePath - Absolute path to delta batch JSON file
- * @returns DeltaBatch entity
- * @throws Error if file doesn't exist or JSON is invalid
- */
-export async function loadDeltaBatch(filePath) {
-    const content = await readFile(filePath, 'utf8');
-    const json = JSON.parse(content);
-    return DeltaBatch.fromJson(json);
-}

package/dist/infra/ace/ace-prompt-templates.d.ts

@@ -1,13 +0,0 @@
-import type { Playbook } from '../../core/domain/entities/playbook.js';
-import type { ReflectorOutput } from '../../core/domain/entities/reflector-output.js';
-import type { IAcePromptBuilder, ReflectorPromptParams } from '../../core/interfaces/i-ace-prompt-builder.js';
-/**
- * Default implementation of ACE prompts using template strings.
- * These prompts are designed to work with coding agents (Claude Code, Cursor, etc.)
- * and LLMs that understand structured JSON output.
- */
-export declare class AcePromptTemplates implements IAcePromptBuilder {
-    buildCuratorPrompt(reflection: ReflectorOutput, playbook: Playbook, questionContext: string): string;
-    buildExecutorPrompt(task: string, context: string, playbook: Playbook, recentReflections: string[]): string;
-    buildReflectorPrompt(params: ReflectorPromptParams): string;
-}