byterover-cli 0.1.0

package/dist/infra/http/authenticated-http-client.js

@@ -0,0 +1,99 @@
+import axios, { isAxiosError } from 'axios';
+/**
+ * HTTP client implementation that automatically adds authentication headers to all requests.
+ *
+ * This client wraps axios and automatically includes:
+ * - Authorization: Bearer {accessToken}
+ * - x-byterover-session-id: {sessionKey}
+ *
+ * Usage:
+ * ```typescript
+ * const client = new AuthenticatedHttpClient(accessToken, sessionKey)
+ * const data = await client.get<ResponseType>('https://api.example.com/endpoint')
+ * ```
+ */
+export class AuthenticatedHttpClient {
+    accessToken;
+    sessionKey;
+    constructor(accessToken, sessionKey) {
+        this.accessToken = accessToken;
+        this.sessionKey = sessionKey;
+    }
+    /**
+     * Performs an HTTP GET request with authentication headers.
+     * @param url The URL to request
+     * @param config Optional request configuration (headers, timeout)
+     * @returns A promise that resolves to the response data
+     * @throws Error if the request fails
+     */
+    async get(url, config) {
+        try {
+            const axiosConfig = {
+                headers: this.buildHeaders(config?.headers),
+                timeout: config?.timeout,
+            };
+            const response = await axios.get(url, axiosConfig);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    /**
+     * Performs an HTTP POST request with authentication headers.
+     * @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
+     * @throws Error if the request fails
+     */
+    async post(url, data, config) {
+        try {
+            const axiosConfig = {
+                headers: this.buildHeaders(config?.headers),
+                timeout: config?.timeout,
+            };
+            const response = await axios.post(url, data, axiosConfig);
+            return response.data;
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    /**
+     * Builds request headers by merging authentication headers with custom headers.
+     * Custom headers take precedence over default headers.
+     */
+    buildHeaders(customHeaders) {
+        return {
+            Authorization: `Bearer ${this.accessToken}`,
+            'x-byterover-session-id': this.sessionKey,
+            ...customHeaders,
+        };
+    }
+    /**
+     * Transforms axios errors into generic Error instances.
+     * Preserves error information while abstracting axios-specific details.
+     */
+    handleError(error) {
+        if (isAxiosError(error)) {
+            if (error.response) {
+                // Server responded with error status
+                return new Error(`HTTP ${error.response.status}: ${error.response.statusText}`);
+            }
+            if (error.code === 'ECONNABORTED' || error.message.includes('timeout')) {
+                // Request timeout
+                return new Error(`Request timeout: ${error.message}`);
+            }
+            if (error.request) {
+                // Request was made but no response received
+                return new Error('Network error: No response received from server');
+            }
+        }
+        // Generic error
+        if (error instanceof Error) {
+            return error;
+        }
+        return new Error('Unknown error occurred');
+    }
+}

package/dist/infra/http/callback-handler.d.ts

@@ -0,0 +1,13 @@
+import type { CallbackResult, ICallbackHandler } from '../../core/interfaces/i-callback-handler.js';
+/**
+ * Adapter implementation of ICallbackHandler that wraps CallbackServer.
+ * Provides OAuth callback handling functionality through a local HTTP server.
+ */
+export declare class CallbackHandler implements ICallbackHandler {
+    private readonly server;
+    constructor();
+    getPort(): number | undefined;
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    waitForCallback(expectedState: string, timeoutMs: number): Promise<CallbackResult>;
+}

package/dist/infra/http/callback-handler.js

@@ -0,0 +1,24 @@
+import { CallbackServer } from './callback-server.js';
+/**
+ * Adapter implementation of ICallbackHandler that wraps CallbackServer.
+ * Provides OAuth callback handling functionality through a local HTTP server.
+ */
+export class CallbackHandler {
+    server;
+    constructor() {
+        this.server = new CallbackServer();
+    }
+    getPort() {
+        const address = this.server.getAddress();
+        return address?.port;
+    }
+    async start() {
+        return this.server.start();
+    }
+    async stop() {
+        return this.server.stop();
+    }
+    async waitForCallback(expectedState, timeoutMs) {
+        return this.server.waitForCallback(expectedState, timeoutMs);
+    }
+}

package/dist/infra/http/callback-server.d.ts

@@ -0,0 +1,18 @@
+type CallbackResult = {
+    code: string;
+    state: string;
+};
+export declare class CallbackServer {
+    private app;
+    private connections;
+    private server;
+    constructor();
+    getAddress(): undefined | {
+        port: number;
+    };
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    waitForCallback(expectedState: string, timeoutMs: number): Promise<CallbackResult>;
+    private setupRoutes;
+}
+export {};

package/dist/infra/http/callback-server.js

@@ -0,0 +1,93 @@
+import express from 'express';
+import { AuthenticationError } from '../../core/domain/errors/auth-error.js';
+export class CallbackServer {
+    app = express();
+    connections = new Set();
+    server = undefined;
+    constructor() {
+        this.setupRoutes();
+    }
+    getAddress() {
+        const address = this.server?.address();
+        if (address !== null && address !== undefined && typeof address !== 'string') {
+            return { port: address.port };
+        }
+        return undefined;
+    }
+    async start() {
+        return new Promise((resolve, reject) => {
+            // Listen on port 0 to get a random available port
+            this.server = this.app.listen(0, () => {
+                const address = this.server?.address();
+                if (address !== null && address !== undefined && typeof address !== 'string') {
+                    resolve(address.port);
+                }
+                else {
+                    reject(new Error('Failed to start server'));
+                }
+            });
+            // Track connections to allow force-closing during shutdown
+            this.server.on('connection', (conn) => {
+                this.connections.add(conn);
+                conn.on('close', () => {
+                    this.connections.delete(conn);
+                });
+            });
+        });
+    }
+    async stop() {
+        return new Promise((resolve) => {
+            if (this.server === undefined) {
+                resolve();
+            }
+            else {
+                // Force close all active connections to prevent delays
+                for (const conn of this.connections) {
+                    conn.destroy();
+                }
+                this.connections.clear();
+                this.server.close(() => {
+                    this.server = undefined;
+                    resolve();
+                });
+            }
+        });
+    }
+    waitForCallback(expectedState, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new AuthenticationError('Authentication timeout - no callback received'));
+            }, timeoutMs);
+            this.app.locals.onCallback = (code, state) => {
+                clearTimeout(timeout);
+                if (state !== expectedState) {
+                    reject(new AuthenticationError('State mismatch - possible CSRF attack'));
+                    return;
+                }
+                resolve({ code, state });
+            };
+            this.app.locals.onError = (error) => {
+                clearTimeout(timeout);
+                reject(new AuthenticationError(error));
+            };
+        });
+    }
+    setupRoutes() {
+        this.app.get('/callback', (req, res) => {
+            const { code, error, error_description, state } = req.query;
+            if (error !== undefined) {
+                const errorMessage = error_description ?? error;
+                this.app.locals.onError?.(String(errorMessage));
+                res.status(400).send(`Authentication failed: ${String(errorMessage)}`);
+                return;
+            }
+            if (code === undefined || state === undefined) {
+                this.app.locals.onError?.('Missing code or state parameter');
+                res.status(400).send('Authentication failed: Missing required parameters');
+                return;
+            }
+            this.app.locals.onCallback?.(String(code), String(state));
+            res.status(200).send('Authentication successful. You can close this window.');
+        });
+    }
+}

package/dist/infra/memory/http-memory-retrieval-service.d.ts

@@ -0,0 +1,18 @@
+import type { IMemoryRetrievalService, RetrieveParams } from '../../core/interfaces/i-memory-retrieval-service.js';
+import { RetrieveResult } from '../../core/domain/entities/retrieve-result.js';
+export type MemoryRetrievalServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+/**
+ * HTTP implementation of IMemoryRetrievalService for ByteRover Memora service.
+ * Handles retrieval of memories based on search queries.
+ */
+export declare class HttpMemoryRetrievalService implements IMemoryRetrievalService {
+    private readonly config;
+    constructor(config: MemoryRetrievalServiceConfig);
+    retrieve(params: RetrieveParams): Promise<RetrieveResult>;
+    private buildQueryParams;
+    private mapToMemory;
+    private mapToRetrieveResult;
+}

package/dist/infra/memory/http-memory-retrieval-service.js

@@ -0,0 +1,63 @@
+import { Memory } from '../../core/domain/entities/memory.js';
+import { RetrieveResult } from '../../core/domain/entities/retrieve-result.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+/**
+ * HTTP implementation of IMemoryRetrievalService for ByteRover Memora service.
+ * Handles retrieval of memories based on search queries.
+ */
+export class HttpMemoryRetrievalService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 30_000, // Default 30 seconds timeout (memory retrieval may be slower)
+        };
+    }
+    async retrieve(params) {
+        try {
+            const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+            // Build query parameters
+            const queryParams = this.buildQueryParams(params);
+            const response = await httpClient.get(`${this.config.apiBaseUrl}/retrieve?${queryParams}`, {
+                timeout: this.config.timeout,
+            });
+            return this.mapToRetrieveResult(response);
+        }
+        catch (error) {
+            throw new Error(`Failed to retrieve memories: ${error.message}`);
+        }
+    }
+    buildQueryParams(params) {
+        const queryParams = new URLSearchParams({
+            project_id: params.spaceId,
+            query: params.query,
+        });
+        // Add node_keys only if provided
+        if (params.nodeKeys !== undefined && params.nodeKeys.length > 0) {
+            queryParams.set('node_keys', params.nodeKeys.join(','));
+        }
+        return queryParams.toString();
+    }
+    mapToMemory(apiMemory) {
+        return new Memory({
+            bulletId: apiMemory.bullet_id,
+            childrenIds: apiMemory.children_ids,
+            content: apiMemory.content,
+            id: apiMemory.id,
+            metadataType: apiMemory.metadata_type,
+            nodeKeys: apiMemory.node_keys,
+            parentIds: apiMemory.parent_ids,
+            score: apiMemory.score,
+            section: apiMemory.section,
+            tags: apiMemory.tags,
+            timestamp: apiMemory.timestamp,
+            title: apiMemory.title,
+        });
+    }
+    mapToRetrieveResult(response) {
+        return new RetrieveResult({
+            memories: response.memories.map((m) => this.mapToMemory(m)),
+            relatedMemories: response.related_memories.map((m) => this.mapToMemory(m)),
+        });
+    }
+}

package/dist/infra/memory/http-memory-storage-service.d.ts

@@ -0,0 +1,18 @@
+import type { ConfirmUploadParams, GetPresignedUrlsParams, IMemoryStorageService } from '../../core/interfaces/i-memory-storage-service.js';
+import { PresignedUrlsResponse } from '../../core/domain/entities/presigned-urls-response.js';
+export type MemoryStorageServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+/**
+ * HTTP implementation of IMemoryStorageService for ByteRover CoGit service.
+ * Handles uploading playbooks to blob storage.
+ */
+export declare class HttpMemoryStorageService implements IMemoryStorageService {
+    private readonly config;
+    constructor(config: MemoryStorageServiceConfig);
+    confirmUpload(params: ConfirmUploadParams): Promise<void>;
+    getPresignedUrls(params: GetPresignedUrlsParams): Promise<PresignedUrlsResponse>;
+    uploadFile(uploadUrl: string, content: string): Promise<void>;
+    private mapToPresignedUrls;
+}

package/dist/infra/memory/http-memory-storage-service.js

@@ -0,0 +1,67 @@
+/* eslint-disable camelcase */
+import axios from 'axios';
+import { PresignedUrl } from '../../core/domain/entities/presigned-url.js';
+import { PresignedUrlsResponse } from '../../core/domain/entities/presigned-urls-response.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+/**
+ * HTTP implementation of IMemoryStorageService for ByteRover CoGit service.
+ * Handles uploading playbooks to blob storage.
+ */
+export class HttpMemoryStorageService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 30_000, // Default 30 seconds timeout
+        };
+    }
+    async confirmUpload(params) {
+        try {
+            const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+            const url = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/memory-processing/confirm-upload`;
+            const requestBody = {
+                request_id: params.requestId,
+            };
+            await httpClient.post(url, requestBody, {
+                timeout: this.config.timeout,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to confirm upload: ${error.message}`);
+        }
+    }
+    async getPresignedUrls(params) {
+        try {
+            const httpClient = new AuthenticatedHttpClient(params.accessToken, params.sessionKey);
+            const url = `${this.config.apiBaseUrl}/organizations/${params.teamId}/projects/${params.spaceId}/memory-processing/presigned-urls`;
+            const requestBody = {
+                branch: params.branch,
+                file_names: params.fileNames,
+            };
+            const response = await httpClient.post(url, requestBody, {
+                timeout: this.config.timeout,
+            });
+            const presignedUrls = response.data.presigned_urls.map((presignedUrlData) => this.mapToPresignedUrls(presignedUrlData));
+            return new PresignedUrlsResponse(presignedUrls, response.data.request_id);
+        }
+        catch (error) {
+            throw new Error(`Failed to get presigned URLs: ${error.message}`);
+        }
+    }
+    async uploadFile(uploadUrl, content) {
+        try {
+            await axios.put(uploadUrl, content, {
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                timeout: this.config.timeout,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to upload file: ${error.message}`);
+        }
+    }
+    mapToPresignedUrls(presignedUrlData) {
+        return new PresignedUrl(presignedUrlData.file_name, presignedUrlData.presigned_url);
+    }
+}

package/dist/infra/memory/memory-to-playbook-mapper.d.ts

@@ -0,0 +1,33 @@
+import type { Memory } from '../../core/domain/entities/memory.js';
+import type { RetrieveResult } from '../../core/domain/entities/retrieve-result.js';
+import { Bullet } from '../../core/domain/entities/bullet.js';
+import { Playbook } from '../../core/domain/entities/playbook.js';
+/**
+ * Transforms a Memory entity into a Bullet entity for playbook storage.
+ *
+ * Mapping:
+ * - memory.bulletId -> bullet.id
+ * - memory.section -> bullet.section
+ * - memory.content -> bullet.content
+ * - memory.tags -> bullet.metadata.tags
+ * - memory.nodeKeys -> bullet.metadata.relatedFiles
+ * - memory.timestamp -> bullet.metadata.timestamp
+ * - memory.id -> bullet.memoryId
+ *
+ * @param memory The Memory entity to transform
+ * @returns A Bullet entity
+ */
+export declare const transformMemoryToBullet: (memory: Memory) => Bullet;
+/**
+ * Transforms a RetrieveResult into a Playbook.
+ *
+ * This function:
+ * 1. Combines both memories and relatedMemories from the result
+ * 2. Transforms each Memory into a Bullet
+ * 3. Organizes bullets by section
+ * 4. Creates a new Playbook with nextId set to 1 (reset value)
+ *
+ * @param result The RetrieveResult containing memories from Memora service
+ * @returns A Playbook containing all retrieved memories as bullets
+ */
+export declare const transformRetrieveResultToPlaybook: (result: RetrieveResult) => Playbook;

package/dist/infra/memory/memory-to-playbook-mapper.js

@@ -0,0 +1,51 @@
+import { Bullet } from '../../core/domain/entities/bullet.js';
+import { Playbook } from '../../core/domain/entities/playbook.js';
+/**
+ * Transforms a Memory entity into a Bullet entity for playbook storage.
+ *
+ * Mapping:
+ * - memory.bulletId -> bullet.id
+ * - memory.section -> bullet.section
+ * - memory.content -> bullet.content
+ * - memory.tags -> bullet.metadata.tags
+ * - memory.nodeKeys -> bullet.metadata.relatedFiles
+ * - memory.timestamp -> bullet.metadata.timestamp
+ * - memory.id -> bullet.memoryId
+ *
+ * @param memory The Memory entity to transform
+ * @returns A Bullet entity
+ */
+export const transformMemoryToBullet = (memory) => {
+    const metadata = {
+        relatedFiles: [...memory.nodeKeys],
+        tags: [...memory.tags],
+        timestamp: memory.timestamp,
+    };
+    return new Bullet(memory.bulletId, memory.section, memory.content, metadata, memory.id);
+};
+/**
+ * Transforms a RetrieveResult into a Playbook.
+ *
+ * This function:
+ * 1. Combines both memories and relatedMemories from the result
+ * 2. Transforms each Memory into a Bullet
+ * 3. Organizes bullets by section
+ * 4. Creates a new Playbook with nextId set to 1 (reset value)
+ *
+ * @param result The RetrieveResult containing memories from Memora service
+ * @returns A Playbook containing all retrieved memories as bullets
+ */
+export const transformRetrieveResultToPlaybook = (result) => {
+    const bulletsMap = new Map();
+    const sectionsMap = new Map();
+    const allMemories = [...result.memories, ...result.relatedMemories];
+    for (const memory of allMemories) {
+        const bullet = transformMemoryToBullet(memory);
+        bulletsMap.set(bullet.id, bullet);
+        if (!sectionsMap.has(bullet.section)) {
+            sectionsMap.set(bullet.section, []);
+        }
+        sectionsMap.get(bullet.section).push(bullet.id);
+    }
+    return new Playbook(bulletsMap, sectionsMap, bulletsMap.size + 1);
+};

package/dist/infra/playbook/file-playbook-service.d.ts

@@ -0,0 +1,43 @@
+import type { Bullet, BulletMetadata } from '../../core/domain/entities/bullet.js';
+import type { DeltaBatch } from '../../core/domain/entities/delta-batch.js';
+import type { ReflectorOutput } from '../../core/domain/entities/reflector-output.js';
+import type { IPlaybookService } from '../../core/interfaces/i-playbook-service.js';
+import type { IPlaybookStore } from '../../core/interfaces/i-playbook-store.js';
+import { Playbook } from '../../core/domain/entities/playbook.js';
+export type PlaybookServiceConfig = {
+    baseDirectory?: string;
+};
+/**
+ * File-based implementation of IPlaybookService.
+ * Provides high-level playbook operations including initialization,
+ * bullet management, delta application, and reflection tag processing.
+ */
+export declare class FilePlaybookService implements IPlaybookService {
+    private static readonly BULLETS_DIR;
+    private static readonly SUBDIRS;
+    private readonly config;
+    private readonly playbookStore;
+    constructor(config?: PlaybookServiceConfig, playbookStore?: IPlaybookStore);
+    addOrUpdateBullet(params: {
+        bulletId?: string;
+        content: string;
+        directory?: string;
+        metadata?: BulletMetadata;
+        section: string;
+    }): Promise<Bullet>;
+    applyDelta(params: {
+        delta: DeltaBatch;
+        directory?: string;
+    }): Promise<{
+        operationsApplied: number;
+        playbook: Playbook;
+    }>;
+    applyReflectionTags(params: {
+        directory?: string;
+        reflection: ReflectorOutput;
+    }): Promise<{
+        playbook: Playbook;
+        tagsApplied: number;
+    }>;
+    initialize(directory?: string): Promise<string>;
+}