byterover-cli 0.1.0

package/dist/core/interfaces/i-http-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Configuration options for HTTP requests.
+ */
+export type HttpRequestConfig = {
+    headers?: Record<string, string>;
+    timeout?: number;
+};
+/**
+ * Interface for HTTP client operations.
+ * Provides abstraction over HTTP libraries (axios, fetch, etc.) following Clean Architecture principles.
+ *
+ * Implementations should handle:
+ * - Request configuration (headers, timeout)
+ * - Error handling and transformation
+ * - Response parsing
+ */
+export interface IHttpClient {
+    /**
+     * Performs an HTTP GET request.
+     * @param url The URL to request
+     * @param config Optional request configuration (headers, timeout)
+     * @returns A promise that resolves to the response data
+     */
+    get: <T>(url: string, config?: HttpRequestConfig) => Promise<T>;
+    /**
+     * Performs an HTTP POST request.
+     * @param url The URL to request
+     * @param data The data to send in the request body
+     * @param config Optional request configuration (headers, timeout)
+     * @returns A promise that resolves to the response data
+     */
+    post: <TResponse, TData = unknown>(url: string, data?: TData, config?: HttpRequestConfig) => Promise<TResponse>;
+}

package/dist/core/interfaces/i-http-client.js

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

package/dist/core/interfaces/i-memory-retrieval-service.d.ts

@@ -0,0 +1,40 @@
+import type { RetrieveResult } from '../domain/entities/retrieve-result.js';
+export type RetrieveParams = {
+    accessToken: string;
+    nodeKeys?: string[];
+    query: string;
+    sessionKey: string;
+    spaceId: string;
+};
+/**
+ * Interface for memory retrieval operations from ByteRover Memora service.
+ * This service is responsible for fetching memories based on search queries.
+ */
+export interface IMemoryRetrievalService {
+    /**
+     * Retrieves memories from the ByteRover Memora service based on a search query.
+     *
+     * @param params The retrieve operation parameters
+     * @returns A promise that resolves to the RetrieveResult containing memories and related memories
+     *
+     * @example
+     * // Broad search across entire space
+     * const result = await memoryService.retrieve({
+     *   query: "authentication best practices",
+     *   spaceId: "a0000000-b001-0000-0000-000000000000",
+     *   accessToken: token.accessToken,
+     *   sessionKey: token.sessionKey,
+     * });
+     *
+     * @example
+     * // Scoped search to specific files
+     * const result = await memoryService.retrieve({
+     *   query: "error handling",
+     *   spaceId: "a0000000-b001-0000-0000-000000000000",
+     *   accessToken: token.accessToken,
+     *   sessionKey: token.sessionKey,
+     *   nodeKeys: ["src/auth/login.ts", "src/auth/oauth.ts"],
+     * });
+     */
+    retrieve: (params: RetrieveParams) => Promise<RetrieveResult>;
+}

package/dist/core/interfaces/i-memory-retrieval-service.js

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

package/dist/core/interfaces/i-memory-storage-service.d.ts

@@ -0,0 +1,55 @@
+import type { PresignedUrlsResponse } from '../domain/entities/presigned-urls-response.js';
+/**
+ * Parameters for requesting presigned URLs.
+ */
+export type GetPresignedUrlsParams = {
+    accessToken: string;
+    branch: string;
+    fileNames: string[];
+    sessionKey: string;
+    spaceId: string;
+    teamId: string;
+};
+/**
+ * Parameters for confirming upload completion.
+ */
+export type ConfirmUploadParams = {
+    accessToken: string;
+    requestId: string;
+    sessionKey: string;
+    spaceId: string;
+    teamId: string;
+};
+/**
+ * Interface for memory storage operations to ByteRover CoGit service.
+ * This service is responsible for uploading playbooks to blob storage.
+ */
+export interface IMemoryStorageService {
+    /**
+     * Confirms that file upload is complete.
+     * Notifies the server that all files have been successfully uploaded to blob storage.
+     *
+     * @param params Confirmation parameters including request ID from presigned URLs response
+     * @returns Promise that resolves when confirmation succeeds
+     * @throws Error if confirmation fails
+     */
+    confirmUpload: (params: ConfirmUploadParams) => Promise<void>;
+    /**
+     * Generates presigned URLs for uploading files to memory storage.
+     *
+     * @param params Request parameters including authentication, identifiers, and file list
+     * @returns Response object containing presigned URLs and request ID for confirmation
+     * @throws Error if the request fails
+     */
+    getPresignedUrls: (params: GetPresignedUrlsParams) => Promise<PresignedUrlsResponse>;
+    /**
+     * Uploads file content to a presigned URL.
+     * Uses HTTP PUT with the file content in the request body.
+     *
+     * @param uploadUrl The presigned URL from Google Cloud Storage
+     * @param content File content as string (typically JSON)
+     * @returns Promise that resolves when upload completes
+     * @throws Error if upload fails (network error, expired URL, etc.)
+     */
+    uploadFile: (uploadUrl: string, content: string) => Promise<void>;
+}

package/dist/core/interfaces/i-memory-storage-service.js

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

package/dist/core/interfaces/i-oidc-discovery-service.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OIDC metadata returned from the discovery endpoint.
+ */
+export type OidcMetadata = {
+    authorizationEndpoint: string;
+    issuer: string;
+    scopesSupported?: string[];
+    tokenEndpoint: string;
+};
+/**
+ * Interface for OIDC discovery services.
+ */
+export interface IOidcDiscoveryService {
+    /**
+     * Discovers OIDC configuration from the issuer's well-known endpoint.
+     * @param issuerUrl The base URL of the OIDC issuer.
+     * @returns The OIDC metadata.
+     */
+    discover: (issuerUrl: string) => Promise<OidcMetadata>;
+}

package/dist/core/interfaces/i-oidc-discovery-service.js

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

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

@@ -0,0 +1,69 @@
+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 .br/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-service.js

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

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

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

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

package/dist/core/interfaces/i-project-config-store.d.ts

@@ -0,0 +1,26 @@
+import type { BrConfig } from '../domain/entities/br-config.js';
+/**
+ * Interface for storing and retrieving ByteRover CLI configuration.
+ * Implementations handle persistence of .br/config.json files.
+ */
+export interface IProjectConfigStore {
+    /**
+     * Checks if a configuration file exists in the .br directory.
+     * @param directory The project directory to check (defaults to current working directory).
+     * @returns True if .br/config.json exists, false otherwise.
+     */
+    exists: (directory?: string) => Promise<boolean>;
+    /**
+     * Reads the configuration from the .br directory.
+     * @param directory The project directory containing .br folder (defaults to current working directory)
+     * @returns The configuration if found, undefined otherwise
+     */
+    read: (directory?: string) => Promise<BrConfig | undefined>;
+    /**
+     * Writes the configuration to the .br directory.
+     * @param config The configuration to write.
+     * @param directory The project directory to create .br folder in (defaults to current working directory)
+     * @returns
+     */
+    write: (config: BrConfig, directory?: string) => Promise<void>;
+}

package/dist/core/interfaces/i-project-config-store.js

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

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

@@ -0,0 +1,21 @@
+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/core/interfaces/i-reflection-store.js

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

package/dist/core/interfaces/i-rule-template-service.d.ts

@@ -0,0 +1,17 @@
+import { Agent } from '../domain/entities/agent.js';
+/**
+ * ByteRover CLI generated rule template tag.
+ */
+export declare const BR_RULE_TAG = "Generated by ByteRover CLI for";
+/**
+ * Interface for rule template service operations.
+ */
+export interface IRuleTemplateService {
+    /**
+     * Generates rule content based on the provided agent.
+     *
+     * @param agent The agent for which to generate the rule content.
+     * @returns Promise resolving to the generated rule content.
+     */
+    generateRuleContent: (agent: Agent) => Promise<string>;
+}

package/dist/core/interfaces/i-rule-template-service.js

@@ -0,0 +1,4 @@
+/**
+ * ByteRover CLI generated rule template tag.
+ */
+export const BR_RULE_TAG = 'Generated by ByteRover CLI for';

package/dist/core/interfaces/i-rule-writer-service.d.ts

@@ -0,0 +1,13 @@
+import { Agent } from '../domain/entities/agent.js';
+/**
+ * Interface for rule writer service operations.
+ */
+export interface IRuleWriterService {
+    /**
+     * Writes a rule for the given agent.
+     * @param agent The agent for which to write the rule.
+     * @param force Whether to force the rule to be written even if it already exists.
+     * @returns A promise that resolves when the rule has been written.
+     */
+    writeRule: (agent: Agent, force: boolean) => Promise<void>;
+}

package/dist/core/interfaces/i-rule-writer-service.js

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

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

@@ -0,0 +1,28 @@
+import type { Space } from '../domain/entities/space.js';
+/**
+ * Interface for space-related operations.
+ * Implementations can be HTTP-based (for production) or mock (for testing/development).
+ */
+export interface ISpaceService {
+    /**
+     * Fetches spaces accessible to the authenticated user within a specific team.
+     * @param accessToken The OAuth access token for authentication
+     * @param sessionKey The session key for tracking the user session
+     * @param teamId The team ID to filter spaces by
+     * @param option Optional pagination options
+     * @param option.limit Maximum number of spaces to fetch in a single request
+     * @param option.offset Number of spaces to skip (for pagination)
+     * @param option.fetchAll If true, automatically paginate to fetch all spaces
+     * @returns A promise that resolves to an object containing:
+     *  - spaces: Array of Space entities
+     *  - total: Total number of spaces available (across all pages)
+     */
+    getSpaces: (accessToken: string, sessionKey: string, teamId: string, option?: {
+        fetchAll?: boolean;
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        spaces: Space[];
+        total: number;
+    }>;
+}

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

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

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

@@ -0,0 +1,29 @@
+import type { Team } from '../domain/entities/team.js';
+/**
+ * Interface for team-related operations.
+ * Implementations can be HTTP-based (for production) or mock (for testing/development).
+ */
+export interface ITeamService {
+    /**
+     * Fetches teams where the authenticated user is a member.
+     * @param accessToken The OAuth access token for authentication
+     * @param sessionKey The session key for tracking the user session
+     * @param option Optional filtering and pagination options
+     * @param option.limit Maximum number of teams to fetch in a single request
+     * @param option.offset Number of teams to skip (for pagination)
+     * @param option.isActive Filter teams by active status
+     * @param option.fetchAll If true, automatically paginate to fetch all teams
+     * @returns A promise that resolves to an object containing:
+     *  - teams: Array of Team entities
+     *  - total: Total number of teams available (across all pages)
+     */
+    getTeams: (accessToken: string, sessionKey: string, option?: {
+        fetchAll?: boolean;
+        isActive?: boolean;
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        teams: Team[];
+        total: number;
+    }>;
+}

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

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

package/dist/core/interfaces/i-template-loader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Interface for loading and processing template files.
+ * Supports loading templates from various sources and performing variable substitution.
+ */
+export interface ITemplateLoader {
+    /**
+     * Loads a section template by name.
+     * Convenience method that loads from the sections/ directory.
+     * @param sectionName - Name of the section (e.g., 'workflow', 'command-reference')
+     * @returns Promise resolving to the section content as a string
+     * @throws Error if the section file cannot be found or read
+     */
+    loadSection(sectionName: string): Promise<string>;
+    /**
+     * Loads a template file from the specified path.
+     * @param templatePath - Relative path to the template file (e.g., 'base.md', 'sections/workflow.md')
+     * @returns Promise resolving to the template content as a string
+     * @throws Error if the template file cannot be found or read
+     */
+    loadTemplate(templatePath: string): Promise<string>;
+    /**
+     * Substitutes variables in a template string.
+     * Replaces {{variable_name}} with corresponding values from the context.
+     * @param template - Template string containing variables to substitute
+     * @param context - Object containing variable values (e.g., {agent_name: 'Claude Code'})
+     * @returns Template string with variables replaced by their values
+     */
+    substituteVariables(template: string, context: Record<string, string>): string;
+}

package/dist/core/interfaces/i-template-loader.js

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

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

@@ -0,0 +1,22 @@
+import { AuthToken } from '../domain/entities/auth-token.js';
+/**
+ * Interface for token storage mechanisms.
+ */
+export interface ITokenStore {
+    /**
+     * Clears the stored token.
+     * @returns A promise that resolves when the token is cleared.
+     */
+    clear: () => Promise<void>;
+    /**
+     * Loads the stored token.
+     * @returns A promise that resolves with the loaded token or undefined if not found.
+     */
+    load: () => Promise<AuthToken | undefined>;
+    /**
+     * Saves the token to storage.
+     * @param token The token to save.
+     * @returns A promise that resolves when the token is saved.
+     */
+    save: (token: AuthToken) => Promise<void>;
+}

package/dist/core/interfaces/i-token-store.js

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

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

@@ -0,0 +1,21 @@
+import { EventName, PropertyDict } from '../domain/entities/event.js';
+/**
+ * Service interface for tracking user actions and system events.
+ *
+ * Provides a unified contract for event tracking and analytics throughout the application.
+ * Implementations should be non-blocking and handle failures gracefully to avoid impacting
+ * user operations.
+ */
+export interface ITrackingService {
+    /**
+     * Tracks a named event with optional metadata.
+     *
+     * This method should be asynchronous and non-blocking. Implementations should log
+     * errors internally rather than throwing, to prevent tracking failures from disrupting
+     * user operations.
+     *
+     * @param eventName - The name of the event to track. Must be one of the predefined EventName values.
+     * @param properties - Optional metadata to attach to the event as key-value pairs. All values must be strings.
+     */
+    track(eventName: EventName, properties?: PropertyDict): Promise<void>;
+}

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

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

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

@@ -0,0 +1,14 @@
+import type { User } from '../domain/entities/user.js';
+/**
+ * Interface for user-related operations.
+ * Implementations can be HTTP-based (for production) or mock (for testing/development).
+ */
+export interface IUserService {
+    /**
+     * Fetches the current authenticated user's information.
+     * @param accessToken The OAuth access token for authentication
+     * @param sessionKey The session key for tracking the user session
+     * @returns A promise that resolves to the User entity
+     */
+    getCurrentUser: (accessToken: string, sessionKey: string) => Promise<User>;
+}

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

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

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

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

@@ -0,0 +1,46 @@
+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>;