byterover-cli 0.1.0

package/dist/infra/playbook/file-playbook-service.js

@@ -0,0 +1,133 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ACE_DIR, BR_DIR, DELTAS_DIR, EXECUTOR_OUTPUTS_DIR, REFLECTIONS_DIR } from '../../constants.js';
+import { Playbook } from '../../core/domain/entities/playbook.js';
+import { FilePlaybookStore } from '../ace/file-playbook-store.js';
+/**
+ * File-based implementation of IPlaybookService.
+ * Provides high-level playbook operations including initialization,
+ * bullet management, delta application, and reflection tag processing.
+ */
+export class FilePlaybookService {
+    static BULLETS_DIR = 'bullets';
+    static SUBDIRS = [REFLECTIONS_DIR, EXECUTOR_OUTPUTS_DIR, DELTAS_DIR, FilePlaybookService.BULLETS_DIR];
+    config;
+    playbookStore;
+    constructor(config = {}, playbookStore = new FilePlaybookStore()) {
+        this.config = config;
+        this.playbookStore = playbookStore;
+    }
+    async addOrUpdateBullet(params) {
+        // Validate input
+        if (!params.section || params.section.trim().length === 0) {
+            throw new Error('Section is required');
+        }
+        if (!params.content || params.content.trim().length === 0) {
+            throw new Error('Content is required');
+        }
+        const directory = params.directory ?? this.config.baseDirectory;
+        // Load existing playbook or create new one
+        let playbook = await this.playbookStore.load(directory);
+        if (!playbook) {
+            playbook = new Playbook();
+        }
+        let bullet;
+        // Determine operation type based on bulletId presence
+        if (params.bulletId) {
+            // UPDATE operation
+            const existingBullet = playbook.getBullet(params.bulletId);
+            if (!existingBullet) {
+                throw new Error(`Bullet with ID '${params.bulletId}' not found`);
+            }
+            const updatedBullet = playbook.updateBullet(params.bulletId, {
+                content: params.content,
+                metadata: params.metadata,
+            });
+            if (!updatedBullet) {
+                throw new Error(`Failed to update bullet '${params.bulletId}'`);
+            }
+            bullet = updatedBullet;
+        }
+        else {
+            // ADD operation
+            // Ensure metadata has at least one tag (required by Bullet entity)
+            const metadata = params.metadata ?? {
+                relatedFiles: [],
+                tags: ['manual'],
+                timestamp: new Date().toISOString(),
+            };
+            // If metadata is provided but tags are empty, add default tag
+            if (metadata.tags.length === 0) {
+                metadata.tags = ['manual'];
+            }
+            bullet = playbook.addBullet(params.section, params.content, undefined, metadata);
+        }
+        // Save updated playbook
+        await this.playbookStore.save(playbook, directory);
+        return bullet;
+    }
+    async applyDelta(params) {
+        const directory = params.directory ?? this.config.baseDirectory;
+        // Load existing playbook or create new one
+        let playbook = await this.playbookStore.load(directory);
+        if (!playbook) {
+            playbook = new Playbook();
+        }
+        // Apply delta operations
+        playbook.applyDelta(params.delta);
+        // Save updated playbook
+        await this.playbookStore.save(playbook, directory);
+        return {
+            operationsApplied: params.delta.getOperationCount(),
+            playbook,
+        };
+    }
+    async applyReflectionTags(params) {
+        const directory = params.directory ?? this.config.baseDirectory;
+        // Load playbook
+        const playbook = await this.playbookStore.load(directory);
+        if (!playbook) {
+            throw new Error('Playbook not found. Run `br init` to initialize.');
+        }
+        // Apply tags from reflection
+        let tagsApplied = 0;
+        for (const bulletTag of params.reflection.bulletTags) {
+            const { id, tag } = bulletTag;
+            // Check if bullet exists
+            const bullet = playbook.getBullet(id);
+            if (!bullet) {
+                // Skip non-existent bullets (might have been removed)
+                continue;
+            }
+            // Add tag to bullet (appends to tags array if not already present)
+            const updated = playbook.addTagToBullet(id, tag);
+            if (updated) {
+                tagsApplied++;
+            }
+        }
+        // Save updated playbook
+        await this.playbookStore.save(playbook, directory);
+        return {
+            playbook,
+            tagsApplied,
+        };
+    }
+    async initialize(directory) {
+        const baseDir = directory ?? this.config.baseDirectory ?? process.cwd();
+        const brDir = join(baseDir, BR_DIR);
+        const aceDir = join(brDir, ACE_DIR);
+        // Create .br/ace/ directory
+        await mkdir(aceDir, { recursive: true });
+        // Create subdirectories
+        await Promise.all(FilePlaybookService.SUBDIRS.map((subdir) => mkdir(join(aceDir, subdir), { recursive: true })));
+        // Check if playbook already exists
+        const exists = await this.playbookStore.exists(directory ?? this.config.baseDirectory);
+        if (exists) {
+            throw new Error('Playbook already exists. Use `br clear` to remove it first.');
+        }
+        // Create empty playbook
+        const playbook = new Playbook();
+        await this.playbookStore.save(playbook, directory ?? this.config.baseDirectory);
+        return join(aceDir, 'playbook.json');
+    }
+}

package/dist/infra/rule/agent-rule-config.d.ts

@@ -0,0 +1,19 @@
+import { type Agent } from '../../core/domain/entities/agent.js';
+import { type WriteMode } from '../../core/interfaces/i-file-service.js';
+/**
+ * Configuration for agent-specific rule files.
+ */
+export type AgentRuleConfig = {
+    /**
+     * The file path where the agent's rules should be written.
+     */
+    filePath: string;
+    /**
+     * The write mode to use when writing the rule file.
+     */
+    writeMode: WriteMode;
+};
+/**
+ * Mapping of agents to their rule file configurations.
+ */
+export declare const AGENT_RULE_CONFIGS: Record<Agent, AgentRuleConfig>;

package/dist/infra/rule/agent-rule-config.js

@@ -0,0 +1,77 @@
+/**
+ * Mapping of agents to their rule file configurations.
+ */
+export const AGENT_RULE_CONFIGS = {
+    Amp: {
+        filePath: 'AGENTS.md',
+        writeMode: 'append',
+    },
+    'Augment Code': {
+        filePath: '.augment/rules/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    'Claude Code': {
+        filePath: 'CLAUDE.md',
+        writeMode: 'append',
+    },
+    Cline: {
+        filePath: '.clinerules/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    Codex: {
+        filePath: 'AGENTS.md',
+        writeMode: 'append',
+    },
+    Cursor: {
+        filePath: '.cursor/rules/agent-context-engineering.mdc',
+        writeMode: 'overwrite',
+    },
+    'Gemini CLI': {
+        filePath: 'GEMINI.md',
+        writeMode: 'append',
+    },
+    'Github Copilot': {
+        filePath: '.github/copilot-instructions.md',
+        writeMode: 'append',
+    },
+    Junie: {
+        filePath: '.junie/guidelines.md',
+        writeMode: 'append',
+    },
+    'Kilo Code': {
+        filePath: '.kilocode/rules/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    Kiro: {
+        filePath: '.kiro/steering/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    Qoder: {
+        filePath: '.qoder/rules/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    'Qwen Code': {
+        filePath: 'QWEN.md',
+        writeMode: 'append',
+    },
+    'Roo Code': {
+        filePath: '.roo/rules/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    'Trae.ai': {
+        filePath: 'project_rules.md',
+        writeMode: 'append',
+    },
+    Warp: {
+        filePath: 'WARP.md',
+        writeMode: 'append',
+    },
+    Windsurf: {
+        filePath: '.windsurf/rules/agent-context-engineering.md',
+        writeMode: 'overwrite',
+    },
+    Zed: {
+        filePath: 'agent-context-engineering.rules',
+        writeMode: 'overwrite',
+    },
+};

package/dist/infra/rule/rule-template-service.d.ts

@@ -0,0 +1,18 @@
+import { type Agent } from '../../core/domain/entities/agent.js';
+import { type IRuleTemplateService } from '../../core/interfaces/i-rule-template-service.js';
+import { type ITemplateLoader } from '../../core/interfaces/i-template-loader.js';
+/**
+ * Service for generating rule templates for different agents.
+ * Loads templates from external files and assembles them with agent-specific context.
+ */
+export declare class RuleTemplateService implements IRuleTemplateService {
+    private readonly templateLoader;
+    constructor(templateLoader: ITemplateLoader);
+    /**
+     * Generates rule content for the specified agent by loading and assembling templates.
+     * @param agent The agent for which to generate rules.
+     * @returns Promise resolving to the rule content as a string.
+     * @throws Error if templates cannot be loaded or assembled.
+     */
+    generateRuleContent(agent: Agent): Promise<string>;
+}

package/dist/infra/rule/rule-template-service.js

@@ -0,0 +1,80 @@
+import { BR_RULE_TAG } from '../../core/interfaces/i-rule-template-service.js';
+const guideHeaders = [
+    {
+        agent: 'Augment Code',
+        value: `---
+type: "always_apply"
+---`,
+    },
+    {
+        agent: 'Cursor',
+        value: `---
+description: ByteRover CLI Rules
+alwaysApply: true
+---`,
+    },
+    {
+        agent: 'Kiro',
+        value: `---
+inclusion: always
+---`,
+    },
+    {
+        agent: 'Qoder',
+        value: `---
+trigger: always_on
+alwaysApply: true
+---`,
+    },
+    {
+        agent: 'Windsurf',
+        value: `---
+trigger: always_on
+---`,
+    },
+];
+/**
+ * Service for generating rule templates for different agents.
+ * Loads templates from external files and assembles them with agent-specific context.
+ */
+export class RuleTemplateService {
+    templateLoader;
+    constructor(templateLoader) {
+        this.templateLoader = templateLoader;
+    }
+    /**
+     * Generates rule content for the specified agent by loading and assembling templates.
+     * @param agent The agent for which to generate rules.
+     * @returns Promise resolving to the rule content as a string.
+     * @throws Error if templates cannot be loaded or assembled.
+     */
+    async generateRuleContent(agent) {
+        try {
+            // Load section templates
+            const workflow = await this.templateLoader.loadSection('workflow');
+            const commandReference = await this.templateLoader.loadSection('command-reference');
+            // Load base template
+            const baseTemplate = await this.templateLoader.loadTemplate('base.md');
+            // Assemble context for variable substitution
+            const context = {
+                /* eslint-disable camelcase */
+                agent_name: agent,
+                command_reference: commandReference,
+                workflow,
+                /* eslint-enable camelcase */
+            };
+            // Substitute variables and get content
+            const content = this.templateLoader.substituteVariables(baseTemplate, context);
+            // Add agent-specific header if available (from develop branch)
+            const header = guideHeaders.find((h) => h.agent === agent)?.value || '';
+            return `${header}
+${content}
+---
+${BR_RULE_TAG} ${agent}
+`;
+        }
+        catch (error) {
+            throw new Error(`Failed to generate rule content for agent '${agent}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

package/dist/infra/rule/rule-writer-service.d.ts

@@ -0,0 +1,19 @@
+import { type Agent } from '../../core/domain/entities/agent.js';
+import { type IFileService } from '../../core/interfaces/i-file-service.js';
+import { IRuleTemplateService } from '../../core/interfaces/i-rule-template-service.js';
+import { type IRuleWriterService } from '../../core/interfaces/i-rule-writer-service.js';
+/**
+ * Service for writing agent-specific rule files.
+ * Uses IFileService to write files and RuleTemplateService to generate content.
+ */
+export declare class RuleWriterService implements IRuleWriterService {
+    private readonly fileService;
+    private readonly templateService;
+    /**
+     * Creates a new RuleWriterService.
+     * @param fileService The file service to use for writing files.
+     * @param templateService The template service to use for generating rule content.
+     */
+    constructor(fileService: IFileService, templateService: IRuleTemplateService);
+    writeRule(agent: Agent, force: boolean): Promise<void>;
+}

package/dist/infra/rule/rule-writer-service.js

@@ -0,0 +1,43 @@
+import { RuleExistsError } from '../../core/domain/errors/rule-error.js';
+import { BR_RULE_TAG } from '../../core/interfaces/i-rule-template-service.js';
+import { AGENT_RULE_CONFIGS } from './agent-rule-config.js';
+/**
+ * Service for writing agent-specific rule files.
+ * Uses IFileService to write files and RuleTemplateService to generate content.
+ */
+export class RuleWriterService {
+    fileService;
+    templateService;
+    /**
+     * Creates a new RuleWriterService.
+     * @param fileService The file service to use for writing files.
+     * @param templateService The template service to use for generating rule content.
+     */
+    constructor(fileService, templateService) {
+        this.fileService = fileService;
+        this.templateService = templateService;
+    }
+    async writeRule(agent, force) {
+        const config = AGENT_RULE_CONFIGS[agent];
+        if (!config) {
+            throw new Error(`No configuration found for agent: ${agent}`);
+        }
+        const { filePath, writeMode } = config;
+        const fileExists = await this.fileService.exists(filePath);
+        // Throw an error if the file exists and force is not set
+        if (writeMode === 'overwrite' && fileExists && !force) {
+            throw new RuleExistsError();
+        }
+        if (writeMode === 'append' && fileExists && !force) {
+            const content = await this.fileService.read(filePath);
+            // Throw an error if the rule already exists
+            if (content.includes(BR_RULE_TAG)) {
+                throw new RuleExistsError();
+            }
+        }
+        // Generate rule content
+        const ruleContent = await this.templateService.generateRuleContent(agent);
+        // Write the rule file
+        await this.fileService.write(ruleContent, filePath, writeMode);
+    }
+}

package/dist/infra/space/http-space-service.d.ts

@@ -0,0 +1,20 @@
+import type { ISpaceService } from '../../core/interfaces/i-space-service.js';
+import { Space } from '../../core/domain/entities/space.js';
+export type SpaceServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+export declare class HttpSpaceService implements ISpaceService {
+    private readonly config;
+    constructor(config: SpaceServiceConfig);
+    getSpaces(accessToken: string, sessionKey: string, teamId: string, option?: {
+        fetchAll?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        spaces: Space[];
+        total: number;
+    }>;
+    private fetchAllSpaces;
+    private mapToSpace;
+}

package/dist/infra/space/http-space-service.js

@@ -0,0 +1,67 @@
+import { Space } from '../../core/domain/entities/space.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+export class HttpSpaceService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: 10_000, // Default 10 seconds timeout
+        };
+    }
+    async getSpaces(accessToken, sessionKey, teamId, option) {
+        try {
+            const httpClient = new AuthenticatedHttpClient(accessToken, sessionKey);
+            // Scenario 1: Fetch all automatically via auto-pagination
+            if (option?.fetchAll === true) {
+                return await this.fetchAllSpaces(httpClient, teamId);
+            }
+            // Scenario 2 & 3: Single request (with or without pagination params)
+            const params = new URLSearchParams();
+            params.append('team_id', teamId);
+            if (option?.limit !== undefined) {
+                params.append('limit', option.limit.toString());
+            }
+            if (option?.offset !== undefined) {
+                params.append('offset', option.offset.toString());
+            }
+            const url = `${this.config.apiBaseUrl}/spaces?${params.toString()}`;
+            const response = await httpClient.get(url, {
+                timeout: this.config.timeout,
+            });
+            return {
+                spaces: response.data.spaces.map((spaceData) => this.mapToSpace(spaceData)),
+                total: response.data.total,
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch spaces: ${error.message}`);
+        }
+    }
+    async fetchAllSpaces(httpClient, teamId) {
+        const pageSize = 100; // Larger pages for fewer requests
+        let offset = 0;
+        let allSpaces = [];
+        let total = 0;
+        while (true) {
+            const params = new URLSearchParams({
+                limit: pageSize.toString(),
+                offset: offset.toString(),
+                team_id: teamId,
+            });
+            // eslint-disable-next-line no-await-in-loop
+            const response = await httpClient.get(`${this.config.apiBaseUrl}/spaces?${params.toString()}`, { timeout: this.config.timeout });
+            const pageSpaces = response.data.spaces.map((spaceData) => this.mapToSpace(spaceData));
+            allSpaces = [...allSpaces, ...pageSpaces];
+            total = response.data.total;
+            // Stop if we've fetched everything or got empty page
+            if (allSpaces.length >= total || pageSpaces.length === 0) {
+                break;
+            }
+            offset += pageSize;
+        }
+        return { spaces: allSpaces, total };
+    }
+    mapToSpace(spaceData) {
+        return new Space(spaceData.id, spaceData.name, spaceData.team_id, spaceData.team.name);
+    }
+}

package/dist/infra/storage/keychain-token-store.d.ts

@@ -0,0 +1,10 @@
+import type { ITokenStore } from '../../core/interfaces/i-token-store.js';
+import { AuthToken } from '../../core/domain/entities/auth-token.js';
+/**
+ * Token store implementation using the system keychain via the keytar library.
+ */
+export declare class KeychainTokenStore implements ITokenStore {
+    clear(): Promise<void>;
+    load(): Promise<AuthToken | undefined>;
+    save(token: AuthToken): Promise<void>;
+}

package/dist/infra/storage/keychain-token-store.js

@@ -0,0 +1,40 @@
+import keytar from 'keytar';
+import { AuthToken } from '../../core/domain/entities/auth-token.js';
+const SERVICE_NAME = 'byterover-cli';
+const ACCOUNT_NAME = 'auth-token';
+/**
+ * Token store implementation using the system keychain via the keytar library.
+ */
+export class KeychainTokenStore {
+    async clear() {
+        try {
+            await keytar.deletePassword(SERVICE_NAME, ACCOUNT_NAME);
+        }
+        catch {
+            // Ignore errors - token might not exist or keychain might be unavailable
+        }
+    }
+    async load() {
+        try {
+            const data = await keytar.getPassword(SERVICE_NAME, ACCOUNT_NAME);
+            if (data === null) {
+                return undefined;
+            }
+            const deserialized = JSON.parse(data);
+            return AuthToken.fromJson(deserialized);
+        }
+        catch {
+            // Return undefined on any error (missing token, invalid JSON, keychain errors)
+            return undefined;
+        }
+    }
+    async save(token) {
+        try {
+            const data = JSON.stringify(token);
+            await keytar.setPassword(SERVICE_NAME, ACCOUNT_NAME, data);
+        }
+        catch (error) {
+            throw new Error(`Failed to save token to keychain: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}

package/dist/infra/team/http-team-service.d.ts

@@ -0,0 +1,21 @@
+import type { ITeamService } from '../../core/interfaces/i-team-service.js';
+import { Team } from '../../core/domain/entities/team.js';
+export type TeamServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+export declare class HttpTeamService implements ITeamService {
+    private readonly config;
+    constructor(config: TeamServiceConfig);
+    getTeams(accessToken: string, sessionKey: string, option?: {
+        fetchAll?: boolean;
+        isActive?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        teams: Team[];
+        total: number;
+    }>;
+    private fetchAllTeams;
+    private mapToTeam;
+}

package/dist/infra/team/http-team-service.js

@@ -0,0 +1,71 @@
+import { Team } from '../../core/domain/entities/team.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+export class HttpTeamService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: 10_000, // Default 10 seconds timeout
+        };
+    }
+    async getTeams(accessToken, sessionKey, option) {
+        try {
+            const httpClient = new AuthenticatedHttpClient(accessToken, sessionKey);
+            // Scenario 1: Fetch all automatically via auto-pagination
+            if (option?.fetchAll === true) {
+                return await this.fetchAllTeams(httpClient, option?.isActive);
+            }
+            // Scenario 2 & 3: Single request (with or without pagination params)
+            const params = new URLSearchParams();
+            if (option?.limit !== undefined) {
+                params.append('limit', option.limit.toString());
+            }
+            if (option?.offset !== undefined) {
+                params.append('offset', option.offset.toString());
+            }
+            if (option?.isActive !== undefined) {
+                params.append('is_active', option.isActive.toString());
+            }
+            const url = `${this.config.apiBaseUrl}/teams${params.toString() ? `?${params.toString()}` : ''}`;
+            const response = await httpClient.get(url, {
+                timeout: this.config.timeout,
+            });
+            return {
+                teams: response.data.teams.map((teamData) => this.mapToTeam(teamData)),
+                total: response.data.total,
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch teams: ${error.message}`);
+        }
+    }
+    async fetchAllTeams(httpClient, isActive) {
+        const pageSize = 100; // Larger pages for fewer requests
+        let offset = 0;
+        let allTeams = [];
+        let total = 0;
+        while (true) {
+            const params = new URLSearchParams({
+                limit: pageSize.toString(),
+                offset: offset.toString(),
+            });
+            if (isActive !== undefined) {
+                params.append('is_active', isActive.toString());
+            }
+            // eslint-disable-next-line no-await-in-loop
+            const response = await httpClient.get(`${this.config.apiBaseUrl}/teams?${params.toString()}`, { timeout: this.config.timeout });
+            const pageTeams = response.data.teams.map((teamData) => this.mapToTeam(teamData));
+            allTeams = [...allTeams, ...pageTeams];
+            total = response.data.total;
+            // Stop if we've fetched everything or got empty page
+            if (allTeams.length >= total || pageTeams.length === 0) {
+                break;
+            }
+            offset += pageSize;
+        }
+        return { teams: allTeams, total };
+    }
+    mapToTeam(teamData) {
+        return Team.fromJson(teamData);
+    }
+}

package/dist/infra/template/fs-template-loader.d.ts

@@ -0,0 +1,33 @@
+import { type IFileService } from '../../core/interfaces/i-file-service.js';
+import { type ITemplateLoader } from '../../core/interfaces/i-template-loader.js';
+/**
+ * File system-based template loader.
+ * Loads templates from src/templates/ directory and performs variable substitution.
+ */
+export declare class FsTemplateLoader implements ITemplateLoader {
+    private readonly fileService;
+    private readonly templatesDir;
+    constructor(fileService: IFileService);
+    /**
+     * Loads a section template from the sections/ directory.
+     * @param sectionName - Name of the section (e.g., 'workflow', 'command-reference')
+     * @returns Promise resolving to section content
+     * @throws Error if section file cannot be read
+     */
+    loadSection(sectionName: string): Promise<string>;
+    /**
+     * Loads a template file from the templates directory.
+     * @param templatePath - Relative path to template (e.g., 'base.md', 'sections/workflow.md')
+     * @returns Promise resolving to template content
+     * @throws Error if template file cannot be read
+     */
+    loadTemplate(templatePath: string): Promise<string>;
+    /**
+     * Substitutes variables in a template string.
+     * Replaces {{variable_name}} with corresponding values from context.
+     * @param template - Template string with {{variable}} placeholders
+     * @param context - Object mapping variable names to values
+     * @returns Template with variables replaced
+     */
+    substituteVariables(template: string, context: Record<string, string>): string;
+}