byterover-cli 0.1.0

package/dist/infra/template/fs-template-loader.js

@@ -0,0 +1,62 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * File system-based template loader.
+ * Loads templates from src/templates/ directory and performs variable substitution.
+ */
+export class FsTemplateLoader {
+    fileService;
+    templatesDir;
+    constructor(fileService) {
+        this.fileService = fileService;
+        // Get the directory of this file
+        const currentFileUrl = import.meta.url;
+        const currentFilePath = fileURLToPath(currentFileUrl);
+        const currentDir = path.dirname(currentFilePath);
+        // Navigate from src/infra/template/ to src/templates/
+        this.templatesDir = path.join(currentDir, '..', '..', 'templates');
+    }
+    /**
+     * 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
+     */
+    async loadSection(sectionName) {
+        const sectionPath = `sections/${sectionName}.md`;
+        return this.loadTemplate(sectionPath);
+    }
+    /**
+     * 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
+     */
+    async loadTemplate(templatePath) {
+        const fullPath = path.join(this.templatesDir, templatePath);
+        try {
+            const content = await this.fileService.read(fullPath);
+            return content;
+        }
+        catch (error) {
+            throw new Error(`Failed to load template '${templatePath}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * 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, context) {
+        let result = template;
+        // Replace each variable in the context
+        for (const [key, value] of Object.entries(context)) {
+            const placeholder = `{{${key}}}`;
+            // Use global replace to handle multiple occurrences
+            result = result.replaceAll(placeholder, value);
+        }
+        return result;
+    }
+}

package/dist/infra/tracking/mixpanel-tracking-service.d.ts

@@ -0,0 +1,14 @@
+import { Mixpanel } from 'mixpanel';
+import { EventName, PropertyDict } from '../../core/domain/entities/event.js';
+import { ITokenStore } from '../../core/interfaces/i-token-store.js';
+import { ITrackingService } from '../../core/interfaces/i-tracking-service.js';
+/**
+ * Tracking service implementation using the Mixpanel library.
+ */
+export declare class MixpanelTrackingService implements ITrackingService {
+    private readonly mp;
+    private readonly tokenStore;
+    constructor(tokenStore: ITokenStore, mp?: Mixpanel);
+    track(eventName: EventName, properties?: PropertyDict): Promise<void>;
+    private getIdentificationProperties;
+}

package/dist/infra/tracking/mixpanel-tracking-service.js

@@ -0,0 +1,44 @@
+import mixpanel from 'mixpanel';
+import { getCurrentConfig } from '../../config/environment.js';
+/**
+ * Tracking service implementation using the Mixpanel library.
+ */
+export class MixpanelTrackingService {
+    mp;
+    tokenStore;
+    constructor(tokenStore, mp) {
+        this.tokenStore = tokenStore;
+        if (mp) {
+            // Injected dependencies for testing
+            this.mp = mp;
+        }
+        else {
+            // Initialize with real implementations for production
+            const envConfig = getCurrentConfig();
+            this.mp = mixpanel.init(envConfig.mixpanelToken);
+        }
+    }
+    async track(eventName, properties) {
+        try {
+            const identificationProps = await this.getIdentificationProperties();
+            this.mp.track(`cli:${eventName}`, {
+                ...identificationProps,
+                ...properties,
+                beta: true,
+            });
+        }
+        catch (error) {
+            console.error(`Failed to track event ${eventName}:`, error);
+        }
+    }
+    async getIdentificationProperties() {
+        // 2. Load and validate authentication token
+        const token = await this.tokenStore.load();
+        if (token) {
+            return {
+                $user_id: token.userId, // eslint-disable-line camelcase
+            };
+        }
+        return {};
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { IUserService } from '../../core/interfaces/i-user-service.js';
+import { User } from '../../core/domain/entities/user.js';
+export type UserServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+export declare class HttpUserService implements IUserService {
+    private readonly config;
+    constructor(config: UserServiceConfig);
+    getCurrentUser(accessToken: string, sessionKey: string): Promise<User>;
+    private mapToUser;
+}

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

@@ -0,0 +1,26 @@
+import { User } from '../../core/domain/entities/user.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+export class HttpUserService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 10_000, // Default 10 seconds timeout
+        };
+    }
+    async getCurrentUser(accessToken, sessionKey) {
+        try {
+            const httpClient = new AuthenticatedHttpClient(accessToken, sessionKey);
+            const response = await httpClient.get(`${this.config.apiBaseUrl}/user/me`, {
+                timeout: this.config.timeout,
+            });
+            return this.mapToUser(response.data);
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch user information: ${error.message}`);
+        }
+    }
+    mapToUser(userData) {
+        return new User(userData.email, userData.id, userData.name);
+    }
+}

package/dist/templates/README.md

@@ -0,0 +1,103 @@
+# ByteRover CLI Template System
+
+This directory contains template files used to generate agent instructions via the `br gen-rules` command.
+
+## Directory Structure
+
+```
+src/templates/
+├── base.md                      # Main template structure
+├── sections/                    # Reusable content sections
+│   ├── workflow.md               # workflow guide
+│   └── command-reference.md     # All BR CLI commands documentation
+└── README.md                    # This file
+```
+
+## Template Files
+
+### `base.md`
+The main template structure that combines all sections into the final output.
+
+**Variables:**
+- `{{agent_name}}` - Name of the agent (e.g., "Claude Code", "Cursor")
+- `{{workflow}}` - Content from `sections/workflow.md`
+- `{{command_reference}}` - Content from `sections/command-reference.md`
+
+### `sections/workflow.md`
+Complete guide to the ACE (Agentic Context Engineering) workflow:
+- Quick start examples
+- Command reference for ACE commands
+- ADD vs UPDATE modes explanation
+- Best practices for using ACE
+- Examples with real use cases
+
+### `sections/command-reference.md`
+Comprehensive documentation of all BR CLI commands:
+- Root commands (login, init, status, add, gen-rules, ace, push, retrieve, show, clear)
+- Space commands (list, switch)
+
+Each command includes:
+- Description
+- Arguments (if any)
+- Flags with defaults
+- Examples
+
+## How It Works
+
+1. User runs `br gen-rules`
+2. User selects an agent (e.g., "Claude Code")
+3. `RuleTemplateService` loads templates via `FsTemplateLoader`
+4. Templates are assembled:
+   - Load section templates (workflow, command-reference)
+   - Substitute variables in base template
+   - Combine all content
+5. Output written to `.clinerules/byterover-rules.md`
+
+## Variable Substitution
+
+The template system supports simple variable substitution using `{{variable_name}}` syntax.
+
+**Available Variables:**
+- `{{agent_name}}` - Agent name selected by user
+## Updating Templates
+
+### To Update Command Documentation:
+Edit `sections/command-reference.md` - changes will be reflected next time `br gen-rules` runs.
+
+### To Update ACE Workflow Guide:
+Edit `sections/workflow.md` - changes will be reflected next time `br gen-rules` runs.
+
+### To Change Output Structure:
+Edit `base.md` - modify how sections are combined.
+
+## Best Practices
+
+1. **Keep templates in sync with code**: When adding/modifying commands, update `command-reference.md`
+2. **Use clear examples**: Show realistic use cases in examples
+3. **Maintain markdown formatting**: Ensure proper headers, code blocks, and lists
+4. **Test after changes**: Run `br gen-rules` and verify output in `.clinerules/byterover-rules.md`
+
+## Future Enhancements
+
+This template system is designed to support future improvements:
+- Context-aware content (show different sections based on project state)
+- Agent-specific customizations (per-agent template overrides)
+- Conditional sections (e.g., show memory commands only if authenticated)
+- Dynamic variable injection (project status, playbook stats, etc.)
+
+## Technical Details
+
+**Template Loader:** `src/infra/template/fs-template-loader.ts`
+- Loads templates from filesystem
+- Performs variable substitution
+- Returns assembled content
+
+**Template Service:** `src/infra/rule/rule-template-service.ts`
+- Orchestrates template loading
+- Builds final instruction content
+- Injects agent-specific values
+
+**Command:** `src/commands/gen-rules.ts`
+- User-facing command
+- Prompts for agent selection
+- Writes output to `.clinerules/byterover-rules.md`

package/dist/templates/base.md

@@ -0,0 +1,3 @@
+{{workflow}}
+---
+{{command_reference}}

package/dist/templates/sections/command-reference.md

@@ -0,0 +1,141 @@
+# ByteRover CLI Command Reference
+
+## Memory Commands
+
+### `br add`
+
+**Description:** Add or update a bullet in the playbook (bypasses ACE workflow for direct agent usage)
+
+**Flags:**
+
+- `-s, --section <string>`: Section name for the bullet (required)
+- `-c, --content <string>`: Content of the bullet (required)
+- `-b, --bullet-id <string>`: Bullet ID to update (optional, creates new if omitted)
+
+**Examples:**
+
+```bash
+br add --section "Common Errors" --content "Authentication fails when token expires"
+br add --section "Common Errors" --bullet-id "common-00001" --content "Updated: Auth fails when token expires"
+br add -s "Best Practices" -c "Always validate user input before processing"
+```
+
+**Suggested Sections:** Common Errors, Best Practices, Strategies, Lessons Learned, Project Structure and Dependencies, Testing, Code Style and Quality, Styling and Design
+
+**Behavior:**
+
+- Warns if using non-standard section name
+- Creates new bullet with auto-generated ID if `--bullet-id` not provided
+- Updates existing bullet if `--bullet-id` matches existing bullet
+- Displays bullet ID, section, content, and tags after operation
+
+**Requirements:** Playbook must exist (run `br init` first)
+
+---
+
+### `br retrieve`
+
+**Description:** Retrieve memories from ByteRover Memora service and save to local ACE playbook
+
+**Flags:**
+
+- `-q, --query <string>`: Search query string (required)
+- `-n, --node-keys <string>`: Comma-separated list of node keys (file paths) to filter results
+
+**Examples:**
+
+```bash
+br retrieve --query "authentication best practices"
+br retrieve -q "error handling" -n "src/auth/login.ts,src/auth/oauth.ts"
+br retrieve -q "database connection issues"
+```
+
+**Behavior:**
+
+- **Clears existing playbook first** (destructive operation)
+- Retrieves memories and related memories from Memora service
+- Combines both result sets into playbook
+- Maps memory fields: `bulletId` → `id`, `tags` → `metadata.tags`, `nodeKeys` → `metadata.relatedFiles`
+- Displays results with score, content preview (200 chars), and related file paths
+- Fail-safe: warns on save error but still displays results
+
+**Output:** Shows count of memories and related memories, displays each with score and content
+
+**Requirements:** Must be authenticated and project initialized
+
+---
+
+### `br push`
+
+**Description:** Push playbook to ByteRover memory storage and clean up local ACE files
+
+**Flags:**
+
+- `-b, --branch <string>`: ByteRover branch name (default: "main", NOT git branch)
+
+**Examples:**
+
+```bash
+br push
+br push --branch develop
+```
+
+---
+
+### `br complete`
+
+**Description:** Complete ACE workflow: save executor output, generate reflection, and update playbook in one command
+
+**Arguments:**
+
+- `hint`: Short hint for naming output files (e.g., "user-auth", "bug-fix")
+- `reasoning`: Detailed reasoning and approach for completing the task
+- `finalAnswer`: The final answer/solution to the task
+
+**Flags:**
+
+- `-t, --tool-usage <string>`: Comma-separated list of tool calls with arguments (format: "ToolName:argument", required)
+- `-f, --feedback <string>`: Environment feedback about task execution (e.g., "Tests passed", "Build failed", required)
+- `-b, --bullet-ids <string>`: Comma-separated list of playbook bullet IDs referenced (optional)
+- `-u, --update-bullet <string>`: Bullet ID to update with new knowledge (if not provided, adds new bullet)
+
+**Examples:**
+
+```bash
+br complete "user-auth" "Implemented OAuth2 flow" "Auth works" --tool-usage "Read:src/auth.ts,Edit:src/auth.ts,Bash:npm test" --feedback "All tests passed"
+br complete "validation-fix" "Analyzed validator" "Fixed bug" --tool-usage "Grep:pattern:\"validate\",Read:src/validator.ts" --bullet-ids "bullet-123" --feedback "Tests passed"
+br complete "auth-update" "Improved error handling" "Better errors" --tool-usage "Edit:src/auth.ts" --feedback "Tests passed" --update-bullet "bullet-5"
+```
+
+**Behavior:**
+
+- **Phase 1 (Executor):** Saves executor output with hint, reasoning, answer, tool usage, and bullet IDs
+- **Phase 2 (Reflector):** Auto-generates reflection based on feedback and applies tags to playbook
+- **Phase 3 (Curator):** Creates delta operation (ADD or UPDATE) and applies to playbook
+- Adds new bullet to "Lessons Learned" section with tag `['auto-generated']`
+- If `--update-bullet` provided, updates existing bullet instead of adding new one
+- Extracts file paths from tool usage and adds to bullet metadata as `relatedFiles`
+
+**Output:** Shows summary with file paths, tags applied count, and delta operations breakdown
+
+---
+
+### `br show`
+
+## Best Practices
+
+### Efficient Workflow
+
+1. **Retrieve wisely:** Use `br retrieve` with specific queries and `--node-keys` to filter
+2. **Read only what's needed:** Check playbook with `br status` to see statistics before reading full content
+3. **Update precisely:** Use `br add` to add/update specific bullets or `br complete` for complete workflow
+4. **Push when appropriate:** Prompt user to run `br push` after completing significant work
+
+### Memory Management
+
+**Retrieve pattern:**
+
+- Use `br add` to directly add/update bullets
+- `br retrieve` **clears existing playbook** - use carefully
+- Retrieved memories use actual Memora tags (not "auto-generated")
+- Both memories and related memories are saved to playbook

package/dist/templates/sections/workflow.md

@@ -0,0 +1,46 @@
+# Workflow Instruction
+
+You are a coding agent focused on one codebase. Use the br CLI to manage working context.
+Core Rules:
+
+- Start from memory. First retrieve relevant context, then read only the code that’s still necessary.
+- Keep a local playbook. playbook.json is your local memory store—update it with what you learn.
+
+## user-centric
+
+Before running any `br` command, ask the user to choose:
+
+1. **Accept** - Review the command, then run if approved
+2. **Auto-run** - Execute immediately (remember this preference for the session)
+3. **No** - Cancel the command and continue without alternative
+4. **Custom** - Skip the command and provide different instruction
+
+Once the user chooses "Auto-run", apply that preference to all subsequent `br` commands in this conversation without asking again.
+
+
+## Daily Flow
+
+1.Retrieve context
+
+2.Do the work with minimal code reads
+
+3.Record new or refined knowledge in the playbook
+
+- Add only specific, actionable, contextual items; avoid secrets. Redact when in doubt.
+
+4.Sync policy (manual by default)
+
+- Do not auto-push.
+- When the playbook has meaningful updates, prompt the user to run the command
+- If the user has explicitly allowed auto-push, proceed non-interactively.
+
+## Playbook Guideline
+
+- Be specific (“Use React Query for data fetching in web modules”).
+- Be actionable (clear instruction a future agent/dev can apply).
+- Be contextual (mention module/service, constraints, links to source).
+- Include source (file + lines or commit) when possible.
+
+## CLI Usage Notes
+
+- Use --help on any command to discover flags. Provide exact arguments for the scenario.

package/dist/utils/file-helpers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Finds the most recent file in a directory by modification time.
+ * @param directory - Absolute path to directory to search
+ * @returns Absolute path to the most recent file
+ * @throws Error if directory is empty or doesn't exist
+ */
+export declare function findLatestFile(directory: string): Promise<string>;
+/**
+ * Removes all files from a directory while preserving the directory itself.
+ * Returns the number of files removed.
+ * Silently succeeds if directory doesn't exist.
+ * @param dirPath - Absolute path to directory to clear
+ * @returns Number of files removed
+ */
+export declare function clearDirectory(dirPath: string): Promise<number>;

package/dist/utils/file-helpers.js

@@ -0,0 +1,45 @@
+import { readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Finds the most recent file in a directory by modification time.
+ * @param directory - Absolute path to directory to search
+ * @returns Absolute path to the most recent file
+ * @throws Error if directory is empty or doesn't exist
+ */
+export async function findLatestFile(directory) {
+    const files = await readdir(directory, { withFileTypes: true });
+    const fileNames = files.filter((f) => f.isFile()).map((f) => f.name);
+    if (fileNames.length === 0) {
+        throw new Error(`No files found in directory: ${directory}`);
+    }
+    // Sort files by name (timestamp-based naming ensures latest is last)
+    // Assuming filenames follow pattern: prefix-{timestamp}.json
+    fileNames.sort();
+    const latestFile = fileNames.at(-1);
+    return join(directory, latestFile);
+}
+/**
+ * Removes all files from a directory while preserving the directory itself.
+ * Returns the number of files removed.
+ * Silently succeeds if directory doesn't exist.
+ * @param dirPath - Absolute path to directory to clear
+ * @returns Number of files removed
+ */
+export async function clearDirectory(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        // Filter to only get files (not subdirectories)
+        const files = entries.filter((entry) => entry.isFile());
+        // Remove each file
+        await Promise.all(files.map((file) => unlink(join(dirPath, file.name))));
+        return files.length;
+    }
+    catch (error) {
+        // If directory doesn't exist (ENOENT), return 0
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        // Re-throw other errors
+        throw error;
+    }
+}