byterover-cli 0.2.1 → 0.3.0

package/dist/infra/cipher/blob/migrations.d.ts

@@ -0,0 +1,63 @@
+import type Database from 'better-sqlite3';
+import type { BlobLogger } from '../../../core/domain/cipher/blob/types.js';
+/**
+ * Migration definition type
+ */
+export type Migration = {
+    /**
+     * Description of what this migration does
+     */
+    description: string;
+    /**
+     * Optional backward migration (downgrade)
+     * Only needed for critical rollback scenarios
+     * @param db - SQLite database instance
+     */
+    down?(db: Database.Database): void;
+    /**
+     * Forward migration (upgrade)
+     * @param db - SQLite database instance
+     */
+    up(db: Database.Database): void;
+    /**
+     * Migration version number (must be sequential)
+     */
+    version: number;
+};
+/**
+ * SQLite Blob Storage Migrations
+ *
+ * IMPORTANT RULES:
+ * 1. NEVER modify existing migrations - always add new ones
+ * 2. Version numbers must be sequential (1, 2, 3, ...)
+ * 3. Always use IF NOT EXISTS for safety
+ * 4. Test migrations thoroughly before releasing
+ * 5. Consider adding 'down' for complex changes
+ */
+export declare const MIGRATIONS: Migration[];
+/**
+ * Get the current schema version from the database
+ */
+export declare function getCurrentVersion(db: Database.Database): number;
+/**
+ * Set the schema version in the database
+ */
+export declare function setVersion(db: Database.Database, version: number): void;
+/**
+ * Run all pending migrations
+ *
+ * @param db - SQLite database instance
+ * @param logger - Optional logger for migration output (defaults to console)
+ * @returns Number of migrations applied
+ * @throws Error if migration fails
+ */
+export declare function runMigrations(db: Database.Database, logger?: BlobLogger): number;
+/**
+ * Rollback to a specific version (use with extreme caution!)
+ *
+ * @param db - SQLite database instance
+ * @param targetVersion - Version to rollback to
+ * @param logger - Optional logger for rollback output (defaults to console)
+ * @throws Error if rollback fails or migrations don't have 'down' methods
+ */
+export declare function rollbackToVersion(db: Database.Database, targetVersion: number, logger?: BlobLogger): void;

package/dist/infra/cipher/blob/migrations.js

@@ -0,0 +1,148 @@
+/**
+ * Default logger that uses console (fallback when no logger provided)
+ */
+const defaultLogger = {
+    error: (message) => console.error(message),
+    info: (message) => console.log(message),
+};
+/**
+ * SQLite Blob Storage Migrations
+ *
+ * IMPORTANT RULES:
+ * 1. NEVER modify existing migrations - always add new ones
+ * 2. Version numbers must be sequential (1, 2, 3, ...)
+ * 3. Always use IF NOT EXISTS for safety
+ * 4. Test migrations thoroughly before releasing
+ * 5. Consider adding 'down' for complex changes
+ */
+export const MIGRATIONS = [
+    {
+        description: 'Initial schema: blobs table with comprehensive indexes',
+        down(db) {
+            // Rollback: drop all indexes and table
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_size_created`);
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_type_updated`);
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_created_at`);
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_updated_at`);
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_size`);
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_original_name`);
+            db.exec(`DROP INDEX IF EXISTS idx_blobs_content_type`);
+            db.exec(`DROP TABLE IF EXISTS blobs`);
+        },
+        up(db) {
+            // Create main table
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS blobs (
+          key TEXT PRIMARY KEY,
+          content BLOB NOT NULL,
+          content_type TEXT,
+          original_name TEXT,
+          size INTEGER NOT NULL,
+          tags TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `);
+            // Single-column indexes
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_content_type ON blobs(content_type)`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_original_name ON blobs(original_name)`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_size ON blobs(size)`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_updated_at ON blobs(updated_at DESC)`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_created_at ON blobs(created_at DESC)`);
+            // Composite indexes
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_type_updated ON blobs(content_type, updated_at DESC)`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_size_created ON blobs(size, created_at DESC)`);
+        },
+        version: 1,
+    },
+    // Example future migration (commented out):
+    // {
+    //   version: 2,
+    //   description: 'Add checksum column for data integrity verification',
+    //   up(db) {
+    //     db.exec(`ALTER TABLE blobs ADD COLUMN checksum TEXT`);
+    //     db.exec(`CREATE INDEX IF NOT EXISTS idx_blobs_checksum ON blobs(checksum)`);
+    //   },
+    //   down(db) {
+    //     // Note: SQLite doesn't support DROP COLUMN easily
+    //     // Would need to recreate table without the column
+    //     db.exec(`DROP INDEX IF EXISTS idx_blobs_checksum`);
+    //   },
+    // },
+];
+/**
+ * Get the current schema version from the database
+ */
+export function getCurrentVersion(db) {
+    const result = db.pragma('user_version', { simple: true });
+    return result;
+}
+/**
+ * Set the schema version in the database
+ */
+export function setVersion(db, version) {
+    db.pragma(`user_version = ${version}`);
+}
+/**
+ * Run all pending migrations
+ *
+ * @param db - SQLite database instance
+ * @param logger - Optional logger for migration output (defaults to console)
+ * @returns Number of migrations applied
+ * @throws Error if migration fails
+ */
+export function runMigrations(db, logger = defaultLogger) {
+    const currentVersion = getCurrentVersion(db);
+    const pendingMigrations = MIGRATIONS.filter((m) => m.version > currentVersion);
+    if (pendingMigrations.length === 0) {
+        return 0;
+    }
+    let appliedCount = 0;
+    // Use transaction for atomic migrations
+    const runMigrationsInTransaction = db.transaction(() => {
+        for (const migration of pendingMigrations) {
+            try {
+                // Run the migration (no verbose logging during execution)
+                migration.up(db);
+                // Update version
+                setVersion(db, migration.version);
+                appliedCount++;
+            }
+            catch (error) {
+                const errorMsg = `Database migration failed: ${error instanceof Error ? error.message : String(error)}`;
+                logger.error(errorMsg);
+                throw new Error(errorMsg);
+            }
+        }
+    });
+    // Execute all migrations atomically
+    runMigrationsInTransaction();
+    return appliedCount;
+}
+/**
+ * Rollback to a specific version (use with extreme caution!)
+ *
+ * @param db - SQLite database instance
+ * @param targetVersion - Version to rollback to
+ * @param logger - Optional logger for rollback output (defaults to console)
+ * @throws Error if rollback fails or migrations don't have 'down' methods
+ */
+export function rollbackToVersion(db, targetVersion, logger = defaultLogger) {
+    const currentVersion = getCurrentVersion(db);
+    if (targetVersion >= currentVersion) {
+        throw new Error(`Cannot rollback: target version ${targetVersion} is not older than current ${currentVersion}`);
+    }
+    const migrationsToRollback = MIGRATIONS.filter((m) => m.version > targetVersion && m.version <= currentVersion).reverse(); // Rollback in reverse order
+    const rollbackInTransaction = db.transaction(() => {
+        for (const migration of migrationsToRollback) {
+            if (!migration.down) {
+                throw new Error(`Migration v${migration.version} does not support rollback (no 'down' method)`);
+            }
+            logger.info(`[Migration] Rolling back v${migration.version}: ${migration.description}`);
+            migration.down(db);
+        }
+        setVersion(db, targetVersion);
+    });
+    rollbackInTransaction();
+    logger.info(`[Migration] Rolled back to v${targetVersion}`);
+}

package/dist/infra/cipher/blob/sqlite-blob-storage.d.ts

@@ -0,0 +1,82 @@
+import type { BlobMetadata, BlobStats, BlobStorageConfig, StoredBlob } from '../../../core/domain/cipher/blob/types.js';
+import type { IBlobStorage } from '../../../core/interfaces/cipher/i-blob-storage.js';
+/**
+ * SQLite-based blob storage implementation
+ *
+ * Stores all blobs in a single SQLite database file:
+ * - .brv/storage.db
+ *
+ * Schema:
+ * - blobs: key, content, content_type, original_name, size, tags, created_at, updated_at
+ *
+ * Benefits over file-based storage:
+ * - O(1) lookup for exists/retrieve
+ * - Fast listing and filtering
+ * - ACID transactions for data integrity
+ * - Single file for easy backup/migration
+ */
+export declare class SqliteBlobStorage implements IBlobStorage {
+    private db;
+    private readonly dbPath;
+    private initialized;
+    private readonly inMemory;
+    private readonly logger;
+    private readonly maxBlobSize;
+    private readonly maxTotalSize;
+    private readonly storageDir;
+    constructor(config?: Partial<BlobStorageConfig>);
+    /**
+     * Clear all blobs from storage
+     * WARNING: This is a destructive operation
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Delete a blob by its key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Check if a blob exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get metadata for a blob without retrieving its content
+     */
+    getMetadata(key: string): Promise<BlobMetadata | undefined>;
+    /**
+     * Get storage statistics
+     */
+    getStats(): Promise<BlobStats>;
+    /**
+     * Initialize storage by creating the database and running migrations
+     */
+    initialize(): Promise<void>;
+    /**
+     * List all blob keys, optionally filtered by prefix
+     */
+    list(prefix?: string): Promise<string[]>;
+    /**
+     * Retrieve a blob by its key
+     */
+    retrieve(key: string): Promise<StoredBlob | undefined>;
+    /**
+     * Store a blob with optional metadata
+     */
+    store(key: string, content: Buffer | string, metadata?: Partial<BlobMetadata>): Promise<StoredBlob>;
+    /**
+     * Ensure storage has been initialized
+     */
+    private ensureInitialized;
+    /**
+     * Convert database row to BlobMetadata
+     */
+    private rowToMetadata;
+    /**
+     * Validate blob key
+     * Keys must be alphanumeric with hyphens and underscores only
+     */
+    private validateKey;
+}

package/dist/infra/cipher/blob/sqlite-blob-storage.js

@@ -0,0 +1,307 @@
+import Database from 'better-sqlite3';
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { BlobError } from '../../../core/domain/cipher/errors/blob-error.js';
+/**
+ * SQLite-based blob storage implementation
+ *
+ * Stores all blobs in a single SQLite database file:
+ * - .brv/storage.db
+ *
+ * Schema:
+ * - blobs: key, content, content_type, original_name, size, tags, created_at, updated_at
+ *
+ * Benefits over file-based storage:
+ * - O(1) lookup for exists/retrieve
+ * - Fast listing and filtering
+ * - ACID transactions for data integrity
+ * - Single file for easy backup/migration
+ */
+export class SqliteBlobStorage {
+    db = null;
+    dbPath;
+    initialized = false;
+    inMemory;
+    logger;
+    maxBlobSize;
+    maxTotalSize;
+    storageDir;
+    constructor(config) {
+        this.inMemory = config?.inMemory ?? false;
+        this.storageDir = config?.storageDir || join(process.cwd(), '.brv');
+        this.dbPath = this.inMemory ? ':memory:' : join(this.storageDir, 'storage.db');
+        this.maxBlobSize = config?.maxBlobSize ?? 100 * 1024 * 1024; // 100MB default
+        this.maxTotalSize = config?.maxTotalSize ?? 1024 * 1024 * 1024; // 1GB default
+        this.logger = config?.logger ?? {
+            error: (message) => console.error(message),
+            info: (message) => console.log(message),
+        };
+    }
+    /**
+     * Clear all blobs from storage
+     * WARNING: This is a destructive operation
+     */
+    async clear() {
+        this.ensureInitialized();
+        try {
+            this.db.exec('DELETE FROM blobs');
+        }
+        catch (error) {
+            throw BlobError.deleteError(`Failed to clear storage: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Close the database connection
+     */
+    close() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+            this.initialized = false;
+        }
+    }
+    /**
+     * Delete a blob by its key
+     */
+    async delete(key) {
+        this.ensureInitialized();
+        this.validateKey(key);
+        try {
+            const stmt = this.db.prepare('DELETE FROM blobs WHERE key = ?');
+            const result = stmt.run(key);
+            if (result.changes === 0) {
+                throw BlobError.notFound(key);
+            }
+        }
+        catch (error) {
+            if (error instanceof BlobError) {
+                throw error;
+            }
+            throw BlobError.deleteError(`Failed to delete blob ${key}: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Check if a blob exists
+     */
+    async exists(key) {
+        this.ensureInitialized();
+        this.validateKey(key);
+        const stmt = this.db.prepare('SELECT 1 FROM blobs WHERE key = ?');
+        const row = stmt.get(key);
+        return row !== undefined;
+    }
+    /**
+     * Get metadata for a blob without retrieving its content
+     */
+    async getMetadata(key) {
+        this.ensureInitialized();
+        this.validateKey(key);
+        try {
+            const stmt = this.db.prepare(`
+        SELECT content_type, original_name, size, tags, created_at, updated_at
+        FROM blobs WHERE key = ?
+      `);
+            const row = stmt.get(key);
+            if (!row) {
+                return undefined;
+            }
+            return this.rowToMetadata(row);
+        }
+        catch (error) {
+            throw BlobError.retrievalError(`Failed to read metadata for blob ${key}: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Get storage statistics
+     */
+    async getStats() {
+        this.ensureInitialized();
+        try {
+            const stmt = this.db.prepare(`
+        SELECT COUNT(*) as count, COALESCE(SUM(size), 0) as total_size
+        FROM blobs
+      `);
+            const row = stmt.get();
+            return {
+                lastUpdated: Date.now(),
+                totalBlobs: row.count,
+                totalSize: row.total_size,
+            };
+        }
+        catch (error) {
+            throw BlobError.retrievalError(`Failed to get storage stats: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Initialize storage by creating the database and running migrations
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            // Ensure storage directory exists (skip for in-memory)
+            if (!this.inMemory) {
+                await fs.mkdir(this.storageDir, { recursive: true });
+            }
+            // Open/create database (':memory:' for in-memory mode)
+            this.db = new Database(this.dbPath);
+            // Enable WAL mode for better concurrent performance
+            this.db.pragma('journal_mode = WAL');
+            // Run migrations to ensure schema is up-to-date
+            const { runMigrations } = await import('./migrations.js');
+            const appliedCount = runMigrations(this.db, this.logger);
+            if (appliedCount > 0) {
+                this.logger.info(`💾 Initializing storage...`);
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            throw BlobError.initializationError(`Failed to initialize SQLite storage: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * List all blob keys, optionally filtered by prefix
+     */
+    async list(prefix) {
+        this.ensureInitialized();
+        try {
+            let stmt;
+            let rows;
+            if (prefix) {
+                stmt = this.db.prepare('SELECT key FROM blobs WHERE key LIKE ? ORDER BY key');
+                rows = stmt.all(`${prefix}%`);
+            }
+            else {
+                stmt = this.db.prepare('SELECT key FROM blobs ORDER BY key');
+                rows = stmt.all();
+            }
+            return rows.map((row) => row.key);
+        }
+        catch (error) {
+            throw BlobError.retrievalError(`Failed to list blobs: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Retrieve a blob by its key
+     */
+    async retrieve(key) {
+        this.ensureInitialized();
+        this.validateKey(key);
+        try {
+            const stmt = this.db.prepare('SELECT * FROM blobs WHERE key = ?');
+            const row = stmt.get(key);
+            if (!row) {
+                return undefined;
+            }
+            return {
+                content: row.content,
+                key: row.key,
+                metadata: this.rowToMetadata(row),
+            };
+        }
+        catch (error) {
+            throw BlobError.retrievalError(`Failed to retrieve blob ${key}: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Store a blob with optional metadata
+     */
+    async store(key, content, metadata) {
+        this.ensureInitialized();
+        this.validateKey(key);
+        // Convert content to Buffer
+        const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+        // Check individual blob size
+        if (buffer.length > this.maxBlobSize) {
+            throw BlobError.tooLarge(buffer.length, this.maxBlobSize);
+        }
+        // Check total storage size
+        const stats = await this.getStats();
+        const existingBlob = await this.retrieve(key);
+        const existingSize = existingBlob?.metadata.size ?? 0;
+        const newTotalSize = stats.totalSize - existingSize + buffer.length;
+        if (newTotalSize > this.maxTotalSize) {
+            throw BlobError.totalSizeExceeded(stats.totalSize - existingSize, buffer.length, this.maxTotalSize);
+        }
+        const now = Date.now();
+        const fullMetadata = {
+            createdAt: existingBlob?.metadata.createdAt ?? now,
+            size: buffer.length,
+            updatedAt: now,
+            ...metadata,
+        };
+        try {
+            const stmt = this.db.prepare(`
+        INSERT INTO blobs (key, content, content_type, original_name, size, tags, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(key) DO UPDATE SET
+          content = excluded.content,
+          content_type = excluded.content_type,
+          original_name = excluded.original_name,
+          size = excluded.size,
+          tags = excluded.tags,
+          updated_at = excluded.updated_at
+      `);
+            stmt.run(key, buffer, fullMetadata.contentType ?? null, fullMetadata.originalName ?? null, buffer.length, fullMetadata.tags ? JSON.stringify(fullMetadata.tags) : null, fullMetadata.createdAt, fullMetadata.updatedAt);
+            return {
+                content: buffer,
+                key,
+                metadata: fullMetadata,
+            };
+        }
+        catch (error) {
+            throw BlobError.storageError(`Failed to store blob ${key}: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Ensure storage has been initialized
+     */
+    ensureInitialized() {
+        if (!this.initialized || !this.db) {
+            throw BlobError.notInitialized();
+        }
+    }
+    /**
+     * Convert database row to BlobMetadata
+     */
+    rowToMetadata(row) {
+        const metadata = {
+            createdAt: row.created_at,
+            size: row.size,
+            updatedAt: row.updated_at,
+        };
+        if (row.content_type) {
+            metadata.contentType = row.content_type;
+        }
+        if (row.original_name) {
+            metadata.originalName = row.original_name;
+        }
+        if (row.tags) {
+            try {
+                metadata.tags = JSON.parse(row.tags);
+            }
+            catch {
+                // Ignore invalid JSON
+            }
+        }
+        return metadata;
+    }
+    /**
+     * Validate blob key
+     * Keys must be alphanumeric with hyphens and underscores only
+     */
+    validateKey(key) {
+        if (!key || typeof key !== 'string') {
+            throw BlobError.invalidKey(String(key), 'Key must be a non-empty string');
+        }
+        if (key.length === 0) {
+            throw BlobError.invalidKey(key, 'Key cannot be empty');
+        }
+        // Allow alphanumeric, hyphens, and underscores only
+        const validKeyRegex = /^[a-zA-Z0-9_-]+$/;
+        if (!validKeyRegex.test(key)) {
+            throw BlobError.invalidKey(key, 'Key must contain only alphanumeric characters, hyphens, and underscores');
+        }
+    }
+}

package/dist/infra/cipher/cipher-agent-state-manager.d.ts

@@ -0,0 +1,63 @@
+import type { TerminationReason } from '../../core/domain/cipher/agent/agent-state.js';
+import type { AgentExecutionState, AgentState } from '../../core/interfaces/cipher/i-cipher-agent.js';
+/**
+ * Manages the runtime state of the CipherAgent.
+ *
+ * Enhanced to track execution state, termination reasons, timing,
+ * and tool metrics following gemini-cli patterns. Maintains backward
+ * compatibility with legacy fields (executionHistory).
+ */
+export declare class CipherAgentStateManager {
+    private currentIteration;
+    private durationMs?;
+    private endTime?;
+    private executionHistory;
+    private executionState;
+    private startTime?;
+    private terminationReason?;
+    private toolCallsExecuted;
+    /**
+     * Add an execution record to history (legacy method).
+     * @param record - Execution record to add
+     */
+    addExecutionRecord(record: string): void;
+    /**
+     * Mark execution as complete with reason.
+     * @param reason - Why execution terminated
+     */
+    complete(reason: TerminationReason): void;
+    /**
+     * Mark execution as errored.
+     * @param reason - Error termination reason
+     */
+    fail(reason: TerminationReason): void;
+    /**
+     * Get the current state.
+     * @returns Current agent state with all enhanced fields
+     */
+    getState(): AgentState;
+    /**
+     * Increment the iteration counter.
+     * @returns The new iteration count
+     */
+    incrementIteration(): number;
+    /**
+     * Increment the tool calls counter.
+     * @returns The new tool calls count
+     */
+    incrementToolCalls(): number;
+    /**
+     * Reset the state to initial values.
+     */
+    reset(): void;
+    /**
+     * Set the current execution state.
+     * @param state - New execution state
+     */
+    setExecutionState(state: AgentExecutionState): void;
+    /**
+     * Start execution tracking.
+     * Sets startTime and transitions to executing state.
+     */
+    startExecution(): void;
+}