byterover-cli 0.1.0

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

@@ -0,0 +1,97 @@
+import type { IBulletContentStore } from '../../interfaces/i-bullet-content-store.js';
+import type { DeltaBatch } from './delta-batch.js';
+import { Bullet, type BulletJson, type BulletMetadata } from './bullet.js';
+export interface PlaybookJson {
+    bullets: Record<string, BulletJson>;
+    nextId: number;
+    sections: Record<string, string[]>;
+}
+export interface PlaybookStats {
+    bullets: number;
+    sections: number;
+    tags: string[];
+}
+/**
+ * The central knowledge repository that stores and manages bullets.
+ * Playbooks are organized into sections and support delta operations.
+ * Playbooks are used as an temporary notes then will be pushed to byterover for usage
+ */
+export declare class Playbook {
+    private readonly bullets;
+    private nextId;
+    private readonly sections;
+    constructor(bullets?: Map<string, Bullet>, sections?: Map<string, string[]>, nextId?: number);
+    /**
+     * Creates a Playbook instance from a JSON object
+     * @param json The playbook JSON data
+     * @param contentStore Optional content store for loading bullet content from files
+     * @param directory Optional directory for loading content files
+     */
+    static fromJson(json: PlaybookJson, contentStore: IBulletContentStore, directory?: string): Promise<Playbook>;
+    /**
+     * Deserializes from JSON string
+     * @param data The JSON string
+     * @param contentStore Optional content store for loading bullet content from files
+     * @param directory Optional directory for loading content files
+     */
+    static loads(data: string, contentStore: IBulletContentStore, directory?: string): Promise<Playbook>;
+    /**
+     * Adds a new bullet to the playbook
+     */
+    addBullet(section: string, content: string, bulletId?: string, metadata?: BulletMetadata): Bullet;
+    /**
+     * Adds a tag to a bullet
+     */
+    addTagToBullet(bulletId: string, tag: string): Bullet | undefined;
+    /**
+     * Applies a batch of delta operations to the playbook
+     */
+    applyDelta(delta: DeltaBatch): void;
+    /**
+     * Converts playbook to markdown format for LLM prompts
+     */
+    asPrompt(): string;
+    /**
+     * Serializes to JSON string (pretty-printed)
+     * @param includeContent If false, content field is omitted from bullets (for file-based storage)
+     */
+    dumps(includeContent?: boolean): string;
+    /**
+     * Retrieves a single bullet by ID
+     */
+    getBullet(bulletId: string): Bullet | undefined;
+    /**
+     * Returns all bullets as an array
+     */
+    getBullets(): Bullet[];
+    /**
+     * Returns bullets in a specific section
+     */
+    getBulletsInSection(section: string): Bullet[];
+    /**
+     * Returns all section names
+     */
+    getSections(): string[];
+    /**
+     * Removes a bullet from the playbook
+     */
+    removeBullet(bulletId: string): void;
+    /**
+     * Removes a tag from a bullet
+     */
+    removeTagFromBullet(bulletId: string, tag: string): Bullet | undefined;
+    /**
+     * Returns playbook statistics
+     */
+    stats(): PlaybookStats;
+    toJson(includeContent?: boolean): PlaybookJson;
+    /**
+     * Updates an existing bullet's content and/or metadata
+     */
+    updateBullet(bulletId: string, options: {
+        content?: string;
+        metadata?: BulletMetadata;
+    }): Bullet | undefined;
+    private _applyOperation;
+    private _generateId;
+}

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

@@ -0,0 +1,275 @@
+import { Bullet } from './bullet.js';
+/**
+ * The central knowledge repository that stores and manages bullets.
+ * Playbooks are organized into sections and support delta operations.
+ * Playbooks are used as an temporary notes then will be pushed to byterover for usage
+ */
+export class Playbook {
+    bullets;
+    nextId;
+    sections;
+    constructor(bullets = new Map(), sections = new Map(), nextId = 1) {
+        this.bullets = new Map(bullets);
+        this.sections = new Map(sections);
+        this.nextId = nextId;
+    }
+    // ===== Static Factory Methods =====
+    /**
+     * Creates a Playbook instance from a JSON object
+     * @param json The playbook JSON data
+     * @param contentStore Optional content store for loading bullet content from files
+     * @param directory Optional directory for loading content files
+     */
+    static async fromJson(json, contentStore, directory) {
+        const bullets = new Map();
+        const sections = new Map();
+        // Deserialize bullets
+        const bulletEntries = Object.entries(json.bullets ?? {});
+        // Load all content in parallel if needed
+        const contentPromises = bulletEntries.map(async ([id, bulletData]) => {
+            if (bulletData.content) {
+                return bulletData.content;
+            }
+            return contentStore.load(id, directory);
+        });
+        const contents = await Promise.all(contentPromises);
+        // Create bullets with loaded content
+        for (const [index, [id, bulletData]] of bulletEntries.entries()) {
+            bullets.set(id, Bullet.fromJson(bulletData, contents[index]));
+        }
+        // Deserialize sections
+        for (const [section, bulletIds] of Object.entries(json.sections ?? {})) {
+            sections.set(section, bulletIds);
+        }
+        return new Playbook(bullets, sections, json.nextId ?? 1);
+    }
+    /**
+     * Deserializes from JSON string
+     * @param data The JSON string
+     * @param contentStore Optional content store for loading bullet content from files
+     * @param directory Optional directory for loading content files
+     */
+    static async loads(data, contentStore, directory) {
+        const json = JSON.parse(data);
+        return Playbook.fromJson(json, contentStore, directory);
+    }
+    // ===== CRUD Operations =====
+    /**
+     * Adds a new bullet to the playbook
+     */
+    addBullet(section, content, bulletId, metadata) {
+        const id = bulletId ?? this._generateId(section);
+        const now = new Date().toISOString();
+        // Create metadata with defaults if not provided
+        const bulletMetadata = metadata ?? {
+            relatedFiles: [],
+            tags: [],
+            timestamp: now,
+        };
+        const bullet = new Bullet(id, section, content, bulletMetadata, undefined);
+        // Add to bullets map
+        this.bullets.set(id, bullet);
+        // Add to sections map
+        if (!this.sections.has(section)) {
+            this.sections.set(section, []);
+        }
+        this.sections.get(section).push(id);
+        return bullet;
+    }
+    /**
+     * Adds a tag to a bullet
+     */
+    addTagToBullet(bulletId, tag) {
+        const bullet = this.bullets.get(bulletId);
+        if (!bullet)
+            return undefined;
+        // Check if tag already exists
+        if (bullet.metadata.tags.includes(tag)) {
+            return bullet;
+        }
+        const updatedMetadata = {
+            ...bullet.metadata,
+            tags: [...bullet.metadata.tags, tag],
+            timestamp: new Date().toISOString(),
+        };
+        const updatedBullet = new Bullet(bullet.id, bullet.section, bullet.content, updatedMetadata, bullet.memoryId);
+        this.bullets.set(bulletId, updatedBullet);
+        return updatedBullet;
+    }
+    /**
+     * Applies a batch of delta operations to the playbook
+     */
+    applyDelta(delta) {
+        for (const operation of delta.operations) {
+            this._applyOperation(operation);
+        }
+    }
+    /**
+     * Converts playbook to markdown format for LLM prompts
+     */
+    asPrompt() {
+        const sections = this.getSections();
+        if (sections.length === 0) {
+            return '(Empty playbook)';
+        }
+        const lines = [];
+        for (const section of sections) {
+            lines.push(`## ${section}`);
+            const bullets = this.getBulletsInSection(section);
+            for (const bullet of bullets) {
+                lines.push(bullet.toDisplayString());
+            }
+            lines.push(''); // Empty line between sections
+        }
+        return lines.join('\n').trim();
+    }
+    /**
+     * Serializes to JSON string (pretty-printed)
+     * @param includeContent If false, content field is omitted from bullets (for file-based storage)
+     */
+    dumps(includeContent = true) {
+        return JSON.stringify(this.toJson(includeContent), null, 2);
+    }
+    /**
+     * Retrieves a single bullet by ID
+     */
+    getBullet(bulletId) {
+        return this.bullets.get(bulletId);
+    }
+    /**
+     * Returns all bullets as an array
+     */
+    getBullets() {
+        return [...this.bullets.values()];
+    }
+    /**
+     * Returns bullets in a specific section
+     */
+    getBulletsInSection(section) {
+        const bulletIds = this.sections.get(section) ?? [];
+        return bulletIds.map((id) => this.bullets.get(id)).filter((b) => b !== undefined);
+    }
+    /**
+     * Returns all section names
+     */
+    getSections() {
+        return [...this.sections.keys()].sort();
+    }
+    // ===== Delta Operations =====
+    /**
+     * Removes a bullet from the playbook
+     */
+    removeBullet(bulletId) {
+        const bullet = this.bullets.get(bulletId);
+        if (!bullet)
+            return;
+        // Remove from bullets map
+        this.bullets.delete(bulletId);
+        // Remove from sections map
+        const sectionBullets = this.sections.get(bullet.section);
+        if (sectionBullets) {
+            const index = sectionBullets.indexOf(bulletId);
+            if (index !== -1) {
+                sectionBullets.splice(index, 1);
+            }
+            // Clean up empty sections
+            if (sectionBullets.length === 0) {
+                this.sections.delete(bullet.section);
+            }
+        }
+    }
+    /**
+     * Removes a tag from a bullet
+     */
+    removeTagFromBullet(bulletId, tag) {
+        const bullet = this.bullets.get(bulletId);
+        if (!bullet)
+            return undefined;
+        const updatedMetadata = {
+            ...bullet.metadata,
+            tags: bullet.metadata.tags.filter((t) => t !== tag),
+            timestamp: new Date().toISOString(),
+        };
+        const updatedBullet = new Bullet(bullet.id, bullet.section, bullet.content, updatedMetadata, bullet.memoryId);
+        this.bullets.set(bulletId, updatedBullet);
+        return updatedBullet;
+    }
+    // ===== Presentation =====
+    /**
+     * Returns playbook statistics
+     */
+    stats() {
+        const tagsSet = new Set();
+        for (const bullet of this.bullets.values()) {
+            for (const tag of bullet.metadata.tags) {
+                tagsSet.add(tag);
+            }
+        }
+        return {
+            bullets: this.bullets.size,
+            sections: this.sections.size,
+            tags: [...tagsSet].sort(),
+        };
+    }
+    toJson(includeContent = true) {
+        const bulletsObj = {};
+        for (const [id, bullet] of this.bullets) {
+            bulletsObj[id] = bullet.toJson(includeContent);
+        }
+        const sectionsObj = {};
+        for (const [section, bulletIds] of this.sections) {
+            sectionsObj[section] = [...bulletIds];
+        }
+        return {
+            bullets: bulletsObj,
+            nextId: this.nextId,
+            sections: sectionsObj,
+        };
+    }
+    // ===== Serialization =====
+    /**
+     * Updates an existing bullet's content and/or metadata
+     */
+    updateBullet(bulletId, options) {
+        const bullet = this.bullets.get(bulletId);
+        if (!bullet)
+            return undefined;
+        const updatedMetadata = options.metadata ?? {
+            ...bullet.metadata,
+            timestamp: new Date().toISOString(),
+        };
+        const updatedBullet = new Bullet(bullet.id, bullet.section, options.content ?? bullet.content, updatedMetadata, bullet.memoryId);
+        this.bullets.set(bulletId, updatedBullet);
+        return updatedBullet;
+    }
+    _applyOperation(operation) {
+        switch (operation.type) {
+            case 'ADD': {
+                this.addBullet(operation.section, operation.content, operation.bulletId, operation.metadata);
+                break;
+            }
+            case 'REMOVE': {
+                this.removeBullet(operation.bulletId);
+                break;
+            }
+            case 'UPDATE': {
+                this.updateBullet(operation.bulletId, {
+                    content: operation.content,
+                    metadata: operation.metadata,
+                });
+                break;
+            }
+        }
+    }
+    // ===== Private Helpers =====
+    _generateId(section) {
+        // Convert section to prefix: "Common Errors" -> "common"
+        const prefix = section
+            .toLowerCase()
+            .split(' ')[0]
+            .replaceAll(/[^a-z0-9]/g, '');
+        const id = `${prefix}-${String(this.nextId).padStart(5, '0')}`;
+        this.nextId++;
+        return id;
+    }
+}

package/dist/core/domain/entities/presigned-url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents a presigned URL for uploading files to cloud storage.
+ * Contains the file name and the temporary upload URL with embedded credentials.
+ */
+export declare class PresignedUrl {
+    readonly fileName: string;
+    readonly uploadUrl: string;
+    constructor(fileName: string, uploadUrl: string);
+}

package/dist/core/domain/entities/presigned-url.js

@@ -0,0 +1,18 @@
+/**
+ * Represents a presigned URL for uploading files to cloud storage.
+ * Contains the file name and the temporary upload URL with embedded credentials.
+ */
+export class PresignedUrl {
+    fileName;
+    uploadUrl;
+    constructor(fileName, uploadUrl) {
+        if (fileName.trim().length === 0) {
+            throw new Error('File name cannot be empty');
+        }
+        if (uploadUrl.trim().length === 0) {
+            throw new Error('Upload URL cannot be empty');
+        }
+        this.fileName = fileName;
+        this.uploadUrl = uploadUrl;
+    }
+}

package/dist/core/domain/entities/presigned-urls-response.d.ts

@@ -0,0 +1,10 @@
+import type { PresignedUrl } from './presigned-url.js';
+/**
+ * Represents the response from requesting presigned URLs.
+ * Contains both the presigned URLs for file upload and the request ID for confirmation.
+ */
+export declare class PresignedUrlsResponse {
+    readonly presignedUrls: ReadonlyArray<PresignedUrl>;
+    readonly requestId: string;
+    constructor(presignedUrls: PresignedUrl[], requestId: string);
+}

package/dist/core/domain/entities/presigned-urls-response.js

@@ -0,0 +1,18 @@
+/**
+ * Represents the response from requesting presigned URLs.
+ * Contains both the presigned URLs for file upload and the request ID for confirmation.
+ */
+export class PresignedUrlsResponse {
+    presignedUrls;
+    requestId;
+    constructor(presignedUrls, requestId) {
+        if (presignedUrls.length === 0) {
+            throw new Error('Presigned URLs array cannot be empty');
+        }
+        if (requestId.trim().length === 0) {
+            throw new Error('Request ID cannot be empty');
+        }
+        this.presignedUrls = Object.freeze([...presignedUrls]);
+        this.requestId = requestId;
+    }
+}

package/dist/core/domain/entities/reflector-output.d.ts

@@ -0,0 +1,38 @@
+export interface BulletTag {
+    id: string;
+    tag: string;
+}
+export interface ReflectorOutputInput {
+    bulletTags: BulletTag[];
+    correctApproach: string;
+    errorIdentification: string;
+    hint: string;
+    keyInsight: string;
+    reasoning: string;
+    rootCauseAnalysis: string;
+}
+export interface ReflectorOutputJson {
+    bulletTags: BulletTag[];
+    correctApproach: string;
+    errorIdentification: string;
+    hint: string;
+    keyInsight: string;
+    reasoning: string;
+    rootCauseAnalysis: string;
+}
+/**
+ * Output from the reflector phase.
+ * Contains error analysis and bullet tagging.
+ */
+export declare class ReflectorOutput {
+    readonly bulletTags: BulletTag[];
+    readonly correctApproach: string;
+    readonly errorIdentification: string;
+    readonly hint: string;
+    readonly keyInsight: string;
+    readonly reasoning: string;
+    readonly rootCauseAnalysis: string;
+    constructor(input: ReflectorOutputInput);
+    static fromJson(json: ReflectorOutputJson): ReflectorOutput;
+    toJson(): ReflectorOutputJson;
+}

package/dist/core/domain/entities/reflector-output.js

@@ -0,0 +1,44 @@
+/**
+ * Output from the reflector phase.
+ * Contains error analysis and bullet tagging.
+ */
+export class ReflectorOutput {
+    bulletTags;
+    correctApproach;
+    errorIdentification;
+    hint;
+    keyInsight;
+    reasoning;
+    rootCauseAnalysis;
+    constructor(input) {
+        this.reasoning = input.reasoning;
+        this.errorIdentification = input.errorIdentification;
+        this.rootCauseAnalysis = input.rootCauseAnalysis;
+        this.correctApproach = input.correctApproach;
+        this.keyInsight = input.keyInsight;
+        this.hint = input.hint;
+        this.bulletTags = [...input.bulletTags];
+    }
+    static fromJson(json) {
+        return new ReflectorOutput({
+            bulletTags: json.bulletTags,
+            correctApproach: json.correctApproach,
+            errorIdentification: json.errorIdentification,
+            hint: json.hint || '',
+            keyInsight: json.keyInsight,
+            reasoning: json.reasoning,
+            rootCauseAnalysis: json.rootCauseAnalysis,
+        });
+    }
+    toJson() {
+        return {
+            bulletTags: this.bulletTags,
+            correctApproach: this.correctApproach,
+            errorIdentification: this.errorIdentification,
+            hint: this.hint,
+            keyInsight: this.keyInsight,
+            reasoning: this.reasoning,
+            rootCauseAnalysis: this.rootCauseAnalysis,
+        };
+    }
+}

package/dist/core/domain/entities/retrieve-result.d.ts

@@ -0,0 +1,35 @@
+import { Memory, MemoryParams } from './memory.js';
+/**
+ * Parameters for creating a RetrieveResult instance.
+ */
+export type RetrieveResultParams = {
+    memories: Memory[];
+    relatedMemories: Memory[];
+};
+/**
+ * JSON representation of a RetrieveResult.
+ */
+export type RetrieveResultJson = {
+    memories: MemoryParams[];
+    relatedMemories: MemoryParams[];
+};
+/**
+ * Represents the result of a memory retrieval operation from the ByteRover Memora service.
+ * Contains both directly matching memories and related memories.
+ */
+export declare class RetrieveResult {
+    readonly memories: readonly Memory[];
+    readonly relatedMemories: readonly Memory[];
+    constructor(params: RetrieveResultParams);
+    /**
+     * Creates a RetrieveResult instance from a JSON object.
+     * @param json JSON object representing the RetrieveResult
+     * @returns An instance of RetrieveResult
+     */
+    static fromJson(json: RetrieveResultJson): RetrieveResult;
+    /**
+     * Converts the RetrieveResult instance to a JSON object.
+     * @returns A JSON object representing the RetrieveResult
+     */
+    toJson(): RetrieveResultJson;
+}

package/dist/core/domain/entities/retrieve-result.js

@@ -0,0 +1,35 @@
+import { Memory } from './memory.js';
+/**
+ * Represents the result of a memory retrieval operation from the ByteRover Memora service.
+ * Contains both directly matching memories and related memories.
+ */
+export class RetrieveResult {
+    memories;
+    relatedMemories;
+    constructor(params) {
+        // Defensive copy to prevent external mutation
+        this.memories = [...params.memories];
+        this.relatedMemories = [...params.relatedMemories];
+    }
+    /**
+     * Creates a RetrieveResult instance from a JSON object.
+     * @param json JSON object representing the RetrieveResult
+     * @returns An instance of RetrieveResult
+     */
+    static fromJson(json) {
+        return new RetrieveResult({
+            memories: json.memories.map((m) => Memory.fromJson(m)),
+            relatedMemories: json.relatedMemories.map((m) => Memory.fromJson(m)),
+        });
+    }
+    /**
+     * Converts the RetrieveResult instance to a JSON object.
+     * @returns A JSON object representing the RetrieveResult
+     */
+    toJson() {
+        return {
+            memories: this.memories.map((m) => m.toJson()),
+            relatedMemories: this.relatedMemories.map((m) => m.toJson()),
+        };
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Represents a ByteRover space that belongs to a team.
+ * A space corresponds to a user's codebase and contains memories for that codebase.
+ */
+export declare class Space {
+    readonly id: string;
+    readonly name: string;
+    readonly teamId: string;
+    readonly teamName: string;
+    constructor(id: string, name: string, teamId: string, teamName: string);
+    /**
+     * Deserializes a space from JSON format
+     */
+    static fromJson(json: Record<string, string>): Space;
+    /**
+     * Returns the display name in the format: teamName/spaceName
+     * Example: "acme-corp/frontend-app"
+     */
+    getDisplayName(): string;
+    /**
+     * Serializes the space to JSON format
+     */
+    toJson(): Record<string, string>;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Represents a ByteRover space that belongs to a team.
+ * A space corresponds to a user's codebase and contains memories for that codebase.
+ */
+export class Space {
+    id;
+    name;
+    teamId;
+    teamName;
+    constructor(id, name, teamId, teamName) {
+        if (id.trim().length === 0) {
+            throw new Error('Space ID cannot be empty');
+        }
+        if (name.trim().length === 0) {
+            throw new Error('Space name cannot be empty');
+        }
+        if (teamId.trim().length === 0) {
+            throw new Error('Team ID cannot be empty');
+        }
+        if (teamName.trim().length === 0) {
+            throw new Error('Team name cannot be empty');
+        }
+        this.id = id;
+        this.name = name;
+        this.teamId = teamId;
+        this.teamName = teamName;
+    }
+    /**
+     * Deserializes a space from JSON format
+     */
+    static fromJson(json) {
+        return new Space(json.id, json.name, json.teamId, json.teamName);
+    }
+    /**
+     * Returns the display name in the format: teamName/spaceName
+     * Example: "acme-corp/frontend-app"
+     */
+    getDisplayName() {
+        return `${this.teamName}/${this.name}`;
+    }
+    /**
+     * Serializes the space to JSON format
+     */
+    toJson() {
+        return {
+            id: this.id,
+            name: this.name,
+            teamId: this.teamId,
+            teamName: this.teamName,
+        };
+    }
+}