byterover-cli 0.1.0

package/dist/core/domain/entities/team.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Parameters for creating a Team instance
+ */
+interface TeamParams {
+    avatarUrl: string;
+    createdAt: Date;
+    description: string;
+    displayName: string;
+    id: string;
+    isActive: boolean;
+    name: string;
+    updatedAt: Date;
+}
+/**
+ * Represents a ByteRover team that contains spaces.
+ * A team is a group of users collaborating on one or more codebases.
+ */
+export declare class Team {
+    readonly avatarUrl: string;
+    readonly createdAt: Date;
+    readonly description: string;
+    readonly displayName: string;
+    readonly id: string;
+    readonly isActive: boolean;
+    readonly name: string;
+    readonly updatedAt: Date;
+    constructor(params: TeamParams);
+    /**
+     * Deserializes a team from JSON format (API response with snake_case)
+     */
+    static fromJson(json: Record<string, unknown>): Team;
+    /**
+     * Returns the display name for UI purposes
+     * Example: "Acme Corporation"
+     */
+    getDisplayName(): string;
+    /**
+     * Serializes the team to JSON format (camelCase for storage)
+     */
+    toJson(): Record<string, unknown>;
+}
+export {};

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

@@ -0,0 +1,89 @@
+/**
+ * Represents a ByteRover team that contains spaces.
+ * A team is a group of users collaborating on one or more codebases.
+ */
+export class Team {
+    avatarUrl;
+    createdAt;
+    description;
+    displayName;
+    id;
+    isActive;
+    name;
+    updatedAt;
+    constructor(params) {
+        if (params.id.trim().length === 0) {
+            throw new Error('Team ID cannot be empty');
+        }
+        if (params.name.trim().length === 0) {
+            throw new Error('Team name cannot be empty');
+        }
+        if (params.displayName.trim().length === 0) {
+            throw new Error('Team display name cannot be empty');
+        }
+        this.avatarUrl = params.avatarUrl;
+        this.createdAt = params.createdAt;
+        this.description = params.description;
+        this.displayName = params.displayName;
+        this.id = params.id;
+        this.isActive = params.isActive;
+        this.name = params.name;
+        this.updatedAt = params.updatedAt;
+    }
+    /**
+     * Deserializes a team from JSON format (API response with snake_case)
+     */
+    static fromJson(json) {
+        // Validate required fields
+        if (typeof json.id !== 'string') {
+            throw new TypeError('Team JSON must have a string id field');
+        }
+        if (typeof json.name !== 'string') {
+            throw new TypeError('Team JSON must have a string name field');
+        }
+        if (typeof json.display_name !== 'string') {
+            throw new TypeError('Team JSON must have a string display_name field');
+        }
+        if (typeof json.is_active !== 'boolean') {
+            throw new TypeError('Team JSON must have a boolean is_active field');
+        }
+        if (typeof json.created_at !== 'string') {
+            throw new TypeError('Team JSON must have a string created_at field');
+        }
+        if (typeof json.updated_at !== 'string') {
+            throw new TypeError('Team JSON must have a string updated_at field');
+        }
+        return new Team({
+            avatarUrl: typeof json.avatar_url === 'string' ? json.avatar_url : '',
+            createdAt: new Date(json.created_at),
+            description: typeof json.description === 'string' ? json.description : '',
+            displayName: json.display_name,
+            id: json.id,
+            isActive: json.is_active,
+            name: json.name,
+            updatedAt: new Date(json.updated_at),
+        });
+    }
+    /**
+     * Returns the display name for UI purposes
+     * Example: "Acme Corporation"
+     */
+    getDisplayName() {
+        return this.displayName;
+    }
+    /**
+     * Serializes the team to JSON format (camelCase for storage)
+     */
+    toJson() {
+        return {
+            avatarUrl: this.avatarUrl,
+            createdAt: this.createdAt.toISOString(),
+            description: this.description,
+            displayName: this.displayName,
+            id: this.id,
+            isActive: this.isActive,
+            name: this.name,
+            updatedAt: this.updatedAt.toISOString(),
+        };
+    }
+}

package/dist/core/domain/entities/user.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Represents a user in the system.
+ */
+export declare class User {
+    readonly email: string;
+    readonly id: string;
+    readonly name: string;
+    constructor(email: string, id: string, name: string);
+    /**
+     * Create a User instance from a JSON object.
+     * @param json JSON object representing the User
+     * @returns An instance of User
+     */
+    static fromJson(json: Record<string, string>): User;
+    /**
+     * Convert the User instance to a JSON object.
+     * @returns A JSON object representing the User
+     */
+    toJson(): Record<string, string>;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Represents a user in the system.
+ */
+export class User {
+    email;
+    id;
+    name;
+    constructor(email, id, name) {
+        this.email = email;
+        this.id = id;
+        this.name = name;
+    }
+    /**
+     * Create a User instance from a JSON object.
+     * @param json JSON object representing the User
+     * @returns An instance of User
+     */
+    static fromJson(json) {
+        return new User(json.email, json.id, json.name);
+    }
+    /**
+     * Convert the User instance to a JSON object.
+     * @returns A JSON object representing the User
+     */
+    toJson() {
+        return {
+            email: this.email,
+            id: this.id,
+            name: this.name,
+        };
+    }
+}

package/dist/core/domain/errors/ace-error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Base error for ACE operations
+ */
+export declare class AceError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Error when a bullet is not found
+ */
+export declare class BulletNotFoundError extends AceError {
+    readonly bulletId: string;
+    constructor(bulletId: string);
+}
+/**
+ * Error when a playbook is not found
+ */
+export declare class PlaybookNotFoundError extends AceError {
+    readonly playbookPath: string;
+    constructor(playbookPath: string);
+}
+/**
+ * Error when delta operation fails
+ */
+export declare class DeltaOperationError extends AceError {
+    readonly operation: string;
+    constructor(operation: string, message: string);
+}
+/**
+ * Error when playbook validation fails
+ */
+export declare class PlaybookValidationError extends AceError {
+    constructor(message: string);
+}

package/dist/core/domain/errors/ace-error.js

@@ -0,0 +1,53 @@
+/**
+ * Base error for ACE operations
+ */
+export class AceError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'AceError';
+        this.code = code;
+    }
+}
+/**
+ * Error when a bullet is not found
+ */
+export class BulletNotFoundError extends AceError {
+    bulletId;
+    constructor(bulletId) {
+        super(`Bullet not found: ${bulletId}`, 'BULLET_NOT_FOUND');
+        this.name = 'BulletNotFoundError';
+        this.bulletId = bulletId;
+    }
+}
+/**
+ * Error when a playbook is not found
+ */
+export class PlaybookNotFoundError extends AceError {
+    playbookPath;
+    constructor(playbookPath) {
+        super(`Playbook not found: ${playbookPath}`, 'PLAYBOOK_NOT_FOUND');
+        this.name = 'PlaybookNotFoundError';
+        this.playbookPath = playbookPath;
+    }
+}
+/**
+ * Error when delta operation fails
+ */
+export class DeltaOperationError extends AceError {
+    operation;
+    constructor(operation, message) {
+        super(`Delta operation failed (${operation}): ${message}`, 'DELTA_OPERATION_FAILED');
+        this.name = 'DeltaOperationError';
+        this.operation = operation;
+    }
+}
+/**
+ * Error when playbook validation fails
+ */
+export class PlaybookValidationError extends AceError {
+    constructor(message) {
+        super(`Playbook validation failed: ${message}`, 'PLAYBOOK_VALIDATION_FAILED');
+        this.name = 'PlaybookValidationError';
+    }
+}

package/dist/core/domain/errors/auth-error.d.ts

@@ -0,0 +1,10 @@
+export declare class AuthenticationError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+export declare class TokenExpiredError extends Error {
+    constructor(message?: string);
+}
+export declare class InvalidTokenError extends Error {
+    constructor(message?: string);
+}

package/dist/core/domain/errors/auth-error.js

@@ -0,0 +1,20 @@
+export class AuthenticationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'AuthenticationError';
+        this.code = code;
+    }
+}
+export class TokenExpiredError extends Error {
+    constructor(message = 'Token has expired') {
+        super(message);
+        this.name = 'TokenExpiredError';
+    }
+}
+export class InvalidTokenError extends Error {
+    constructor(message = 'Token is invalid') {
+        super(message);
+        this.name = 'InvalidTokenError';
+    }
+}

package/dist/core/domain/errors/discovery-error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base error for OIDC discovery failures.
+ */
+export declare class DiscoveryError extends Error {
+    readonly attemptCount?: number;
+    readonly issuerUrl: string;
+    constructor(message: string, issuerUrl: string, attemptCount?: number);
+}
+/**
+ * Error thrown when discovery request times out.
+ */
+export declare class DiscoveryTimeoutError extends DiscoveryError {
+    constructor(issuerUrl: string, timeoutMs: number, attemptCount?: number);
+}
+/**
+ * Error thrown when discovery encounters a network error.
+ */
+export declare class DiscoveryNetworkError extends DiscoveryError {
+    readonly originalError?: Error;
+    constructor(issuerUrl: string, originalError?: Error, attemptCount?: number);
+}

package/dist/core/domain/errors/discovery-error.js

@@ -0,0 +1,33 @@
+/**
+ * Base error for OIDC discovery failures.
+ */
+export class DiscoveryError extends Error {
+    attemptCount;
+    issuerUrl;
+    constructor(message, issuerUrl, attemptCount) {
+        super(message);
+        this.name = 'DiscoveryError';
+        this.issuerUrl = issuerUrl;
+        this.attemptCount = attemptCount;
+    }
+}
+/**
+ * Error thrown when discovery request times out.
+ */
+export class DiscoveryTimeoutError extends DiscoveryError {
+    constructor(issuerUrl, timeoutMs, attemptCount) {
+        super(`OIDC discovery timed out after ${timeoutMs}ms for issuer: ${issuerUrl}`, issuerUrl, attemptCount);
+        this.name = 'DiscoveryTimeoutError';
+    }
+}
+/**
+ * Error thrown when discovery encounters a network error.
+ */
+export class DiscoveryNetworkError extends DiscoveryError {
+    originalError;
+    constructor(issuerUrl, originalError, attemptCount) {
+        super(`Network error during OIDC discovery for issuer: ${issuerUrl}${originalError ? `: ${originalError.message}` : ''}`, issuerUrl, attemptCount);
+        this.name = 'DiscoveryNetworkError';
+        this.originalError = originalError;
+    }
+}

package/dist/core/domain/errors/rule-error.d.ts

@@ -0,0 +1,6 @@
+export declare class RuleError extends Error {
+    constructor(message: string);
+}
+export declare class RuleExistsError extends RuleError {
+    constructor(message?: string);
+}

package/dist/core/domain/errors/rule-error.js

@@ -0,0 +1,12 @@
+export class RuleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RuleError';
+    }
+}
+export class RuleExistsError extends RuleError {
+    constructor(message = 'Rule already exists') {
+        super(message);
+        this.name = 'RuleExistsError';
+    }
+}

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

@@ -0,0 +1,48 @@
+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-ace-prompt-builder.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,35 @@
+import { OAuthTokenData } from '../domain/entities/oauth-token-data.js';
+/**
+ * Authorization context containing the URL and state for OAuth flow.
+ * The code_verifier is managed internally by the auth service.
+ */
+export type AuthorizationContext = {
+    authUrl: string;
+    state: string;
+};
+/**
+ * Interface for authentication services.
+ */
+export interface IAuthService {
+    /**
+     * Exchanges an authorization code for OAuth token data.
+     * @param code The authorization code to exchange.
+     * @param context The authorization context from initiateAuthorization (contains state for verifier lookup).
+     * @param redirectUri The redirect URI used in the authorization request (must match for OAuth 2.0 compliance).
+     * @returns The OAuth token data (without user information).
+     */
+    exchangeCodeForToken: (code: string, context: AuthorizationContext, redirectUri: string) => Promise<OAuthTokenData>;
+    /**
+     * Initiates the authorization flow by generating PKCE parameters and building the authorization URL.
+     * The code_verifier is generated and stored internally by the service.
+     * @param redirectUri The redirect URI where authorization codes will be received.
+     * @returns Authorization context containing the URL and state for CSRF protection.
+     */
+    initiateAuthorization: (redirectUri: string) => AuthorizationContext;
+    /**
+     * Refreshes an access token using a refresh token.
+     * @param refreshToken The refresh token to use.
+     * @returns The new OAuth token data (without user information).
+     */
+    refreshToken: (refreshToken: string) => Promise<OAuthTokenData>;
+}

package/dist/core/interfaces/i-auth-service.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/i-browser-launcher.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interface for browser launcher implementations.
+ */
+export interface IBrowserLauncher {
+    /**
+     * Launches the system browser to open the specified URL.
+     * @param url The URL to open.
+     * @returns A promise that resolves when the browser has been launched.
+     */
+    open: (url: string) => Promise<void>;
+}

package/dist/core/interfaces/i-browser-launcher.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,36 @@
+/**
+ * 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-bullet-content-store.js

@@ -0,0 +1 @@
+export {};

package/dist/core/interfaces/i-callback-handler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Result from OAuth callback containing authorization code and state.
+ */
+export type CallbackResult = {
+    code: string;
+    state: string;
+};
+/**
+ * Interface for handling OAuth callback during authentication flow.
+ * Implementations manage a local HTTP server that receives OAuth redirect.
+ */
+export interface ICallbackHandler {
+    /**
+     * Get the current port of the callback server.
+     * @returns The port number if server is running, undefined otherwise.
+     */
+    getPort(): number | undefined;
+    /**
+     * Start the callback server.
+     * @returns Promise that resolves with the port number the server is listening on.
+     */
+    start(): Promise<number>;
+    /**
+     * Stop the callback server.
+     * @returns Promise that resolves when the server is stopped.
+     */
+    stop(): Promise<void>;
+    /**
+     * Wait for OAuth callback with timeout.
+     * @param expectedState The state parameter to validate against CSRF attacks.
+     * @param timeoutMs Timeout in milliseconds.
+     * @returns Promise that resolves with the authorization code and state, or rejects on timeout or state mismatch.
+     */
+    waitForCallback(expectedState: string, timeoutMs: number): Promise<CallbackResult>;
+}

package/dist/core/interfaces/i-callback-handler.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+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-delta-store.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,14 @@
+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-executor-output-store.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,34 @@
+/**
+ * Write mode for file operations.
+ * - `append`: Add content to the end of the file
+ * - `overwrite`: Replace the entire file content
+ */
+export type WriteMode = 'append' | 'overwrite';
+/**
+ * Interface for file service operations.
+ */
+export interface IFileService {
+    /**
+     * Checks if a file exists at the specified path.
+     *
+     * @param filePath The path to the file to check.
+     * @returns A promise that resolves with `true` if the file exists, `false` otherwise.
+     */
+    exists: (filePath: string) => Promise<boolean>;
+    /**
+     * Reads content from the specified file.
+     *
+     * @param filePath The path to the file to read from.
+     * @returns A promise that resolves with the content of the file.
+     */
+    read: (filePath: string) => Promise<string>;
+    /**
+     * Writes content to the specified file.
+     *
+     * @param content The content to write.
+     * @param filePath The path to the file to write to.
+     * @param mode The mode to write the content in.
+     * @returns A promise that resolves when the content has been written.
+     */
+    write: (content: string, filePath: string, mode: WriteMode) => Promise<void>;
+}

package/dist/core/interfaces/i-file-service.js

@@ -0,0 +1 @@
+export {};