byterover-cli 0.1.0

package/bin/dev.cmd

@@ -0,0 +1,4 @@
+@echo off
+
+set BR_ENV=development
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+
+process.env.BR_ENV = 'development'
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.cmd

@@ -0,0 +1,4 @@
+@echo off
+
+set BR_ENV=production
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+process.env.BR_ENV = 'production'
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/commands/add.d.ts

@@ -0,0 +1,60 @@
+import { Command } from '@oclif/core';
+import type { Bullet } from '../core/domain/entities/bullet.js';
+import type { IPlaybookService } from '../core/interfaces/i-playbook-service.js';
+import type { IPlaybookStore } from '../core/interfaces/i-playbook-store.js';
+import type { ITrackingService } from '../core/interfaces/i-tracking-service.js';
+type UserAction = 'add' | 'update';
+interface SectionPromptOptions {
+    readonly existingSections: readonly string[];
+    readonly suggestedSections: readonly string[];
+}
+interface ContentPromptContext {
+    readonly action: UserAction;
+    readonly existingContent?: string;
+    readonly section: string;
+}
+export default class Add extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'bullet-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        content: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        interactive: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        section: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected createServices(): {
+        playbookService: IPlaybookService;
+        playbookStore: IPlaybookStore;
+        trackingService: ITrackingService;
+    };
+    /**
+     * Prompt user to choose between adding a new bullet or updating an existing one
+     */
+    protected promptForAction(): Promise<UserAction>;
+    /**
+     * Prompt user to select a bullet to update
+     */
+    protected promptForBullet(bullets: Bullet[]): Promise<string>;
+    /**
+     * Prompt user to enter bullet content
+     */
+    protected promptForContent(context: ContentPromptContext): Promise<string>;
+    /**
+     * Prompt user to select or create a section name
+     */
+    protected promptForSection(options: SectionPromptOptions): Promise<string>;
+    run(): Promise<void>;
+    /**
+     * Display success message after adding or updating a bullet
+     */
+    private displaySuccess;
+    /**
+     * Run in flag-based mode (non-interactive)
+     */
+    private runFlagBased;
+    /**
+     * Run in interactive mode
+     */
+    private runInteractive;
+}
+export {};

package/dist/commands/add.js

@@ -0,0 +1,230 @@
+import { input, search, select } from '@inquirer/prompts';
+import { Command, Flags } from '@oclif/core';
+import { Playbook } from '../core/domain/entities/playbook.js';
+import { FilePlaybookStore } from '../infra/ace/file-playbook-store.js';
+import { FilePlaybookService } from '../infra/playbook/file-playbook-service.js';
+import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
+import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
+// Constants
+const SUGGESTED_SECTIONS = [
+    'Common Errors',
+    'Best Practices',
+    'Strategies',
+    'Lessons Learned',
+    'Architecture',
+    'Testing',
+];
+const validateContent = (content) => content.trim().length > 0;
+export default class Add extends Command {
+    static description = 'Add or update a bullet in the playbook (bypasses ACE workflow for direct agent usage)';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --interactive',
+        '<%= config.bin %> <%= command.id %> -i',
+        '<%= config.bin %> <%= command.id %> --section "Common Errors" --content "Authentication fails when token expires"',
+        '<%= config.bin %> <%= command.id %> --section "Common Errors" --bullet-id "common-00001" --content "Updated: Auth fails when token expires"',
+        '<%= config.bin %> <%= command.id %> -s "Best Practices" -c "Always validate user input before processing"',
+    ];
+    static flags = {
+        'bullet-id': Flags.string({
+            char: 'b',
+            description: 'Bullet ID to update (if not provided, a new bullet will be created)',
+            required: false,
+        }),
+        content: Flags.string({
+            char: 'c',
+            description: 'Content of the bullet',
+            required: false,
+        }),
+        interactive: Flags.boolean({
+            char: 'i',
+            default: false,
+            description: 'Run in interactive mode',
+        }),
+        section: Flags.string({
+            char: 's',
+            description: 'Section name for the bullet',
+            required: false,
+        }),
+    };
+    createServices() {
+        return {
+            playbookService: new FilePlaybookService(),
+            playbookStore: new FilePlaybookStore(),
+            trackingService: new MixpanelTrackingService(new KeychainTokenStore()),
+        };
+    }
+    /**
+     * Prompt user to choose between adding a new bullet or updating an existing one
+     */
+    async promptForAction() {
+        const action = await select({
+            choices: [
+                { name: 'Add a new bullet', value: 'add' },
+                { name: 'Update an existing bullet', value: 'update' },
+            ],
+            message: 'What would you like to do?',
+        });
+        return action;
+    }
+    /**
+     * Prompt user to select a bullet to update
+     */
+    async promptForBullet(bullets) {
+        const displayBullets = bullets.map((bullet) => ({
+            contentPreview: bullet.content.length > 60 ? `${bullet.content.slice(0, 60)}...` : bullet.content,
+            id: bullet.id,
+            section: bullet.section,
+            tags: bullet.metadata.tags,
+            timestamp: new Date(bullet.metadata.timestamp).toLocaleDateString(),
+        }));
+        const bulletId = await search({
+            message: 'Select a bullet to update:',
+            async source(input) {
+                const filtered = input
+                    ? displayBullets.filter((b) => b.section.toLowerCase().includes(input.toLowerCase()) ||
+                        b.contentPreview.toLowerCase().includes(input.toLowerCase()) ||
+                        b.id.toLowerCase().includes(input.toLowerCase()))
+                    : displayBullets;
+                return filtered.map((b) => ({
+                    description: `Tags: ${b.tags.join(', ')} | Date: ${b.timestamp}`,
+                    name: `[${b.id}] ${b.section}: ${b.contentPreview}`,
+                    value: b.id,
+                }));
+            },
+        });
+        return bulletId;
+    }
+    /**
+     * Prompt user to enter bullet content
+     */
+    async promptForContent(context) {
+        const message = context.action === 'update'
+            ? `Enter new content for bullet in "${context.section}":`
+            : `Enter content for new bullet in "${context.section}":`;
+        const content = await input({
+            default: context.existingContent,
+            message,
+            validate(value) {
+                if (!validateContent(value)) {
+                    return 'Content cannot be empty';
+                }
+                return true;
+            },
+        });
+        return content;
+    }
+    /**
+     * Prompt user to select or create a section name
+     */
+    async promptForSection(options) {
+        const allSections = [...new Set([...options.existingSections, ...options.suggestedSections])];
+        const section = await search({
+            message: 'Select or type a section name:',
+            async source(input) {
+                if (!input) {
+                    return allSections.map((s) => ({ name: s, value: s }));
+                }
+                const filtered = allSections.filter((s) => s.toLowerCase().includes(input.toLowerCase()));
+                // Allow creating new section
+                if (filtered.length === 0 || !filtered.includes(input)) {
+                    filtered.unshift(input);
+                }
+                return filtered.map((s) => ({ name: s, value: s }));
+            },
+        });
+        return section;
+    }
+    async run() {
+        const { flags } = await this.parse(Add);
+        return flags.interactive ? this.runInteractive() : this.runFlagBased(flags);
+    }
+    /**
+     * Display success message after adding or updating a bullet
+     */
+    displaySuccess(bullet, action) {
+        const actionText = action === 'update' ? 'Updated' : 'Added';
+        this.log(`\n✓ ${actionText} bullet successfully!`);
+        this.log(`  ID: ${bullet.id}`);
+        this.log(`  Section: ${bullet.section}`);
+        this.log(`  Content: ${bullet.content}`);
+        if (bullet.metadata.tags.length > 0) {
+            this.log(`  Tags: ${bullet.metadata.tags.join(', ')}`);
+        }
+    }
+    /**
+     * Run in flag-based mode (non-interactive)
+     */
+    async runFlagBased(flags) {
+        const { playbookService, trackingService } = this.createServices();
+        try {
+            // Validate required flags
+            if (!flags.section || !flags.content) {
+                this.error('--section and --content are required in non-interactive mode');
+            }
+            // Warn if section is not a standard ACE section
+            if (!SUGGESTED_SECTIONS.includes(flags.section)) {
+                this.warn(`Section "${flags.section}" is not a standard ACE section.\n` +
+                    `  Suggested sections: ${SUGGESTED_SECTIONS.join(', ')}\n` +
+                    `  You can still proceed, but consider using a standard section for consistency.`);
+            }
+            await trackingService.track('ace:add_bullet');
+            const bullet = await playbookService.addOrUpdateBullet({
+                bulletId: flags['bullet-id'],
+                content: flags.content,
+                section: flags.section,
+            });
+            this.displaySuccess(bullet, flags['bullet-id'] ? 'update' : 'add');
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : 'Unexpected error occurred');
+        }
+    }
+    /**
+     * Run in interactive mode
+     */
+    async runInteractive() {
+        const { playbookService, playbookStore, trackingService } = this.createServices();
+        try {
+            // Load existing playbook or create new one
+            let playbook = await playbookStore.load();
+            if (!playbook) {
+                playbook = new Playbook();
+            }
+            const action = await this.promptForAction();
+            const sectionOptions = {
+                existingSections: playbook.getSections(),
+                suggestedSections: SUGGESTED_SECTIONS,
+            };
+            const section = await this.promptForSection(sectionOptions);
+            let bulletId;
+            let existingContent;
+            if (action === 'update') {
+                const bullets = playbook.getBullets();
+                if (bullets.length === 0) {
+                    this.warn('No bullets available to update. Creating new bullet instead.');
+                }
+                else {
+                    bulletId = await this.promptForBullet(bullets);
+                    const bullet = playbook.getBullet(bulletId);
+                    existingContent = bullet?.content;
+                }
+            }
+            const contentContext = {
+                action: bulletId ? 'update' : 'add',
+                existingContent,
+                section,
+            };
+            const content = await this.promptForContent(contentContext);
+            const bullet = await playbookService.addOrUpdateBullet({
+                bulletId,
+                content,
+                section,
+            });
+            await trackingService.track('ace:add_bullet');
+            this.displaySuccess(bullet, bulletId ? 'update' : 'add');
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : 'Unexpected error occurred');
+        }
+    }
+}

package/dist/commands/clear.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class Clear extends Command {
+    static args: {
+        directory: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    protected confirmClear(): Promise<boolean>;
+    run(): Promise<void>;
+}

package/dist/commands/clear.js

@@ -0,0 +1,57 @@
+import { confirm } from '@inquirer/prompts';
+import { Args, Command, Flags } from '@oclif/core';
+import { Playbook } from '../core/domain/entities/playbook.js';
+import { FilePlaybookStore } from '../infra/ace/file-playbook-store.js';
+export default class Clear extends Command {
+    static args = {
+        directory: Args.string({ description: 'Project directory (defaults to current directory)', required: false }),
+    };
+    static description = 'Clear local ACE context (playbook) managed by ByteRover CLI';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --yes',
+        '<%= config.bin %> <%= command.id %> /path/to/project',
+    ];
+    static flags = {
+        yes: Flags.boolean({
+            char: 'y',
+            default: false,
+            description: 'Skip confirmation prompt',
+        }),
+    };
+    // Protected method for testability - can be overridden in tests
+    async confirmClear() {
+        return confirm({
+            default: false,
+            message: 'Are you sure you want to clear the playbook? This action cannot be undone.',
+        });
+    }
+    async run() {
+        const { args, flags } = await this.parse(Clear);
+        try {
+            // Setup dependencies
+            const playbookStore = new FilePlaybookStore();
+            // Check if playbook exists
+            const exists = await playbookStore.exists(args.directory);
+            if (!exists) {
+                this.log('No playbook found. Nothing to clear.');
+                return;
+            }
+            // Confirmation prompt (unless --yes flag is used)
+            if (!flags.yes) {
+                const confirmed = await this.confirmClear();
+                if (!confirmed) {
+                    this.log('Cancelled. Playbook was not cleared.');
+                    return;
+                }
+            }
+            // Reset the playbook to empty structure
+            const emptyPlaybook = new Playbook();
+            await playbookStore.save(emptyPlaybook, args.directory);
+            this.log('✓ Playbook cleared successfully.');
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : 'Failed to clear playbook');
+        }
+    }
+}

package/dist/commands/complete.d.ts

@@ -0,0 +1,108 @@
+import { Command } from '@oclif/core';
+import type { IAcePromptBuilder } from '../core/interfaces/i-ace-prompt-builder.js';
+import type { IDeltaStore } from '../core/interfaces/i-delta-store.js';
+import type { IExecutorOutputStore } from '../core/interfaces/i-executor-output-store.js';
+import type { IPlaybookService } from '../core/interfaces/i-playbook-service.js';
+import type { IReflectionStore } from '../core/interfaces/i-reflection-store.js';
+export default class Complete extends Command {
+    static args: {
+        hint: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        reasoning: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        finalAnswer: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'bullet-ids': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        feedback: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'tool-usage': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'update-bullet': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    protected createServices(): {
+        deltaStore: IDeltaStore;
+        executorOutputStore: IExecutorOutputStore;
+        playbookService: IPlaybookService;
+        promptBuilder: IAcePromptBuilder;
+        reflectionStore: IReflectionStore;
+    };
+    run(): Promise<void>;
+    /**
+     * Displays a formatted summary of the completed ACE workflow.
+     * Shows file paths, delta operations breakdown, and success confirmation.
+     *
+     * @param summary - Summary data containing all workflow outputs
+     * @param summary.curatorOutput - The curator output containing delta operations
+     * @param summary.deltaFilePath - Path to the saved delta file
+     * @param summary.executorPath - Path to the saved executor output file
+     * @param summary.hint - The hint used for naming output files
+     * @param summary.reflectionFilePath - Path to the saved reflection file
+     * @param summary.tagsApplied - Number of tags applied to the playbook
+     */
+    private displayFinalSummary;
+    /**
+     * Extracts file paths from tool usage strings and formats them with project name prefix.
+     * Converts tool usage entries like "Read:src/file.ts" to "projectName/src/file.ts".
+     * Filters out non-file-like arguments (e.g., "Bash:npm test" is excluded).
+     *
+     * @param toolUsage - Array of tool usage strings (e.g., ["Read:src/file.ts", "Edit:src/other.ts"])
+     * @returns Array of formatted file paths with project name prefix
+     */
+    private extractFilePaths;
+    /**
+     * Phase 3: Generates curation and applies delta operations to the playbook.
+     * Creates delta operations (ADD or UPDATE) based on reflection insights and applies them to the playbook.
+     *
+     * @param services - The service instances
+     * @param services.deltaStore - Delta store for persisting deltas
+     * @param services.playbookService - Playbook service for applying deltas
+     * @param services.promptBuilder - Prompt builder for curation prompts
+     * @param reflection - The reflection output from Phase 2
+     * @param executorOutput - The executor output from Phase 1
+     * @param flags - Command flags containing optional update-bullet ID
+     * @returns Object containing curator output and delta file path
+     */
+    private generateCurationAndApplyDelta;
+    /**
+     * Phase 2: Generates reflection based on executor output and applies tags to the playbook.
+     * Auto-generates reflection analysis from feedback and applies bullet tags to relevant playbook sections.
+     *
+     * @param services - The service instances
+     * @param services.playbookService - Playbook service for applying reflection tags
+     * @param services.promptBuilder - Prompt builder for reflection prompts
+     * @param services.reflectionStore - Reflection store for persisting reflections
+     * @param executorOutput - The executor output from Phase 1
+     * @param feedback - Environment feedback about task execution (e.g., "Tests passed", "Build failed")
+     * @returns Object containing reflection output, file path, and number of tags applied
+     */
+    private generateReflectionAndApplyTags;
+    /**
+     * Parses comma-separated bullet IDs string into an array of trimmed IDs.
+     * Empty strings and whitespace-only entries are filtered out.
+     *
+     * @param bulletIdsStr - Comma-separated string of bullet IDs (e.g., "bullet-1, bullet-2")
+     * @returns Array of trimmed bullet ID strings (empty array if input is empty string)
+     */
+    private parseBulletIds;
+    /**
+     * Parses comma-separated tool usage string into an array of trimmed entries.
+     * Empty strings and whitespace-only entries are filtered out.
+     *
+     * @param toolUsageStr - Comma-separated string of tool usage (e.g., "Read:file.ts, Edit:other.ts")
+     * @returns Array of trimmed tool usage strings
+     */
+    private parseToolUsage;
+    /**
+     * Phase 1: Saves executor output to a file.
+     * Creates an ExecutorOutput entity from command arguments and persists it using the executor output store service.
+     *
+     * @param executorOutputStore - The executor output store service
+     * @param args - Command arguments
+     * @param args.hint - Short hint for naming output files
+     * @param args.reasoning - Detailed reasoning and approach for completing the task
+     * @param args.finalAnswer - The final answer/solution to the task
+     * @param bulletIds - Array of playbook bullet IDs referenced during task execution
+     * @param toolUsage - Array of tool usage strings (e.g., ["Read:src/file.ts", "Bash:npm test"])
+     * @returns Object containing the executor output entity and file path where it was saved
+     */
+    private saveExecutorOutput;
+}