byterover-cli 0.4.1 → 1.0.0

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

@@ -0,0 +1,27 @@
+/**
+ * Base error for Core process failures.
+ */
+export declare class CoreProcessError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when Core process is already running.
+ */
+export declare class CoreProcessAlreadyRunningError extends CoreProcessError {
+    constructor();
+}
+/**
+ * Error thrown when instance lock cannot be acquired.
+ */
+export declare class InstanceLockError extends CoreProcessError {
+    readonly existingPid?: number;
+    readonly existingPort?: number;
+    constructor(existingPid?: number, existingPort?: number);
+}
+/**
+ * Error thrown when instance lock acquisition fails for unknown reason.
+ */
+export declare class InstanceLockAcquisitionError extends CoreProcessError {
+    readonly reason?: string;
+    constructor(reason?: string);
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Base error for Core process failures.
+ */
+export class CoreProcessError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CoreProcessError';
+    }
+}
+/**
+ * Error thrown when Core process is already running.
+ */
+export class CoreProcessAlreadyRunningError extends CoreProcessError {
+    constructor() {
+        super('Core process is already running');
+        this.name = 'CoreProcessAlreadyRunningError';
+    }
+}
+/**
+ * Error thrown when instance lock cannot be acquired.
+ */
+export class InstanceLockError extends CoreProcessError {
+    existingPid;
+    existingPort;
+    constructor(existingPid, existingPort) {
+        const details = existingPid && existingPort ? ` (pid: ${existingPid}, port: ${existingPort})` : '';
+        super(`Failed to acquire instance lock. Another instance is already running${details}`);
+        this.name = 'InstanceLockError';
+        this.existingPid = existingPid;
+        this.existingPort = existingPort;
+    }
+}
+/**
+ * Error thrown when instance lock acquisition fails for unknown reason.
+ */
+export class InstanceLockAcquisitionError extends CoreProcessError {
+    reason;
+    constructor(reason) {
+        super(`Failed to acquire instance lock${reason ? `: ${reason}` : ''}`);
+        this.name = 'InstanceLockAcquisitionError';
+        this.reason = reason;
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Task Error Codes
+ * Used for structured error handling in task execution.
+ */
+export declare const TaskErrorCode: {
+    readonly AGENT_DISCONNECTED: "ERR_AGENT_DISCONNECTED";
+    readonly AGENT_NOT_AVAILABLE: "ERR_AGENT_NOT_AVAILABLE";
+    readonly LLM_ERROR: "ERR_LLM_ERROR";
+    readonly LLM_RATE_LIMIT: "ERR_LLM_RATE_LIMIT";
+    readonly NOT_AUTHENTICATED: "ERR_NOT_AUTHENTICATED";
+    readonly PROCESSOR_NOT_INIT: "ERR_PROCESSOR_NOT_INIT";
+    readonly PROJECT_NOT_INIT: "ERR_PROJECT_NOT_INIT";
+    readonly TASK_CANCELLED: "ERR_TASK_CANCELLED";
+    readonly TASK_EXECUTION: "ERR_TASK_EXECUTION";
+    readonly TASK_TIMEOUT: "ERR_TASK_TIMEOUT";
+    readonly UNKNOWN: "ERR_UNKNOWN";
+};
+export type TaskErrorCodeType = (typeof TaskErrorCode)[keyof typeof TaskErrorCode];
+/**
+ * Structured error object for transport.
+ * All task errors should conform to this shape.
+ */
+export interface TaskErrorData {
+    code?: TaskErrorCodeType;
+    details?: Record<string, unknown>;
+    message: string;
+    name: string;
+}
+/**
+ * Base error class for task-related errors.
+ */
+export declare class TaskError extends Error {
+    readonly code: TaskErrorCodeType;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: TaskErrorCodeType, details?: Record<string, unknown>);
+    /**
+     * Serialize error for transport.
+     */
+    toJSON(): TaskErrorData;
+}
+/**
+ * Serialize any error to TaskErrorData.
+ * Use this when catching errors to send via transport.
+ * Preserves original error properties - only adds code if error already has one or has known mapping.
+ */
+export declare function serializeTaskError(error: unknown): TaskErrorData;
+export declare class AgentNotAvailableError extends TaskError {
+    constructor();
+}
+export declare class AgentDisconnectedError extends TaskError {
+    constructor();
+}
+export declare class ProcessorNotInitError extends TaskError {
+    constructor();
+}
+export declare class NotAuthenticatedError extends TaskError {
+    constructor();
+}
+export declare class ProjectNotInitError extends TaskError {
+    constructor();
+}
+export declare class FileValidationError extends Error {
+    constructor(message?: string);
+}

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

@@ -0,0 +1,116 @@
+/**
+ * Task Error Codes
+ * Used for structured error handling in task execution.
+ */
+export const TaskErrorCode = {
+    // Agent errors
+    AGENT_DISCONNECTED: 'ERR_AGENT_DISCONNECTED',
+    AGENT_NOT_AVAILABLE: 'ERR_AGENT_NOT_AVAILABLE',
+    // LLM errors
+    LLM_ERROR: 'ERR_LLM_ERROR',
+    LLM_RATE_LIMIT: 'ERR_LLM_RATE_LIMIT',
+    // Auth/Init errors
+    NOT_AUTHENTICATED: 'ERR_NOT_AUTHENTICATED',
+    // Execution errors
+    PROCESSOR_NOT_INIT: 'ERR_PROCESSOR_NOT_INIT',
+    PROJECT_NOT_INIT: 'ERR_PROJECT_NOT_INIT',
+    TASK_CANCELLED: 'ERR_TASK_CANCELLED',
+    TASK_EXECUTION: 'ERR_TASK_EXECUTION',
+    TASK_TIMEOUT: 'ERR_TASK_TIMEOUT',
+    // Unknown
+    UNKNOWN: 'ERR_UNKNOWN',
+};
+/**
+ * Base error class for task-related errors.
+ */
+export class TaskError extends Error {
+    code;
+    details;
+    constructor(message, code = TaskErrorCode.UNKNOWN, details) {
+        super(message);
+        this.name = 'TaskError';
+        this.code = code;
+        this.details = details;
+    }
+    /**
+     * Serialize error for transport.
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            ...(this.details ? { details: this.details } : {}),
+            message: this.message,
+            name: this.name,
+        };
+    }
+}
+/**
+ * Serialize any error to TaskErrorData.
+ * Use this when catching errors to send via transport.
+ * Preserves original error properties - only adds code if error already has one or has known mapping.
+ */
+export function serializeTaskError(error) {
+    // Already a TaskError - has code
+    if (error instanceof TaskError) {
+        return error.toJSON();
+    }
+    // Standard Error with name
+    if (error instanceof Error) {
+        // Check for known error names and map to codes
+        const codeMap = {
+            AuthError: TaskErrorCode.NOT_AUTHENTICATED,
+            RateLimitError: TaskErrorCode.LLM_RATE_LIMIT,
+            TaskCancelledError: TaskErrorCode.TASK_CANCELLED,
+            TimeoutError: TaskErrorCode.TASK_TIMEOUT,
+            WorkspaceNotInitializedError: TaskErrorCode.PROJECT_NOT_INIT,
+        };
+        const code = codeMap[error.name];
+        return {
+            ...(code ? { code } : {}),
+            message: error.message,
+            name: error.name,
+        };
+    }
+    // Unknown error type
+    return {
+        message: String(error),
+        name: 'Error',
+    };
+}
+// Specific error classes for common cases
+export class AgentNotAvailableError extends TaskError {
+    constructor() {
+        super('Agent not available. Please wait for Agent to connect.', TaskErrorCode.AGENT_NOT_AVAILABLE);
+        this.name = 'AgentNotAvailableError';
+    }
+}
+export class AgentDisconnectedError extends TaskError {
+    constructor() {
+        super('Agent disconnected', TaskErrorCode.AGENT_DISCONNECTED);
+        this.name = 'AgentDisconnectedError';
+    }
+}
+export class ProcessorNotInitError extends TaskError {
+    constructor() {
+        super('TaskProcessor not initialized', TaskErrorCode.PROCESSOR_NOT_INIT);
+        this.name = 'ProcessorNotInitError';
+    }
+}
+export class NotAuthenticatedError extends TaskError {
+    constructor() {
+        super('Not authenticated. Please run "brv login" first.', TaskErrorCode.NOT_AUTHENTICATED);
+        this.name = 'NotAuthenticatedError';
+    }
+}
+export class ProjectNotInitError extends TaskError {
+    constructor() {
+        super('Project not initialized. Please run "brv init" first.', TaskErrorCode.PROJECT_NOT_INIT);
+        this.name = 'ProjectNotInitError';
+    }
+}
+export class FileValidationError extends Error {
+    constructor(message = 'File validation failed. Please check file paths.') {
+        super(message);
+        this.name = 'FileValidationError';
+    }
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Base error for transport layer failures.
+ */
+export declare class TransportError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when connection to server fails.
+ */
+export declare class TransportConnectionError extends TransportError {
+    readonly originalError?: Error;
+    readonly url: string;
+    constructor(url: string, originalError?: Error);
+}
+/**
+ * Error thrown when client is not connected to server.
+ */
+export declare class TransportNotConnectedError extends TransportError {
+    constructor(operation?: string);
+}
+/**
+ * Error thrown when server is not started.
+ */
+export declare class TransportServerNotStartedError extends TransportError {
+    constructor(operation?: string);
+}
+/**
+ * Error thrown when server is already running.
+ */
+export declare class TransportServerAlreadyRunningError extends TransportError {
+    readonly port: number;
+    constructor(port: number);
+}
+/**
+ * Error thrown when port is already in use.
+ */
+export declare class TransportPortInUseError extends TransportError {
+    readonly port: number;
+    constructor(port: number);
+}
+/**
+ * Error thrown when a request times out.
+ */
+export declare class TransportRequestTimeoutError extends TransportError {
+    readonly event: string;
+    readonly timeoutMs: number;
+    constructor(event: string, timeoutMs: number);
+}
+/**
+ * Error thrown when a request fails with server error.
+ */
+export declare class TransportRequestError extends TransportError {
+    readonly event: string;
+    constructor(event: string, message?: string);
+}
+/**
+ * Error thrown when room operations fail.
+ */
+export declare class TransportRoomError extends TransportError {
+    readonly operation: 'join' | 'leave';
+    readonly room: string;
+    constructor(room: string, operation: 'join' | 'leave');
+}
+/**
+ * Error thrown when room operation times out.
+ */
+export declare class TransportRoomTimeoutError extends TransportError {
+    readonly operation: 'join' | 'leave';
+    readonly room: string;
+    readonly timeoutMs: number;
+    constructor(room: string, operation: 'join' | 'leave', timeoutMs: number);
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Base error for transport layer failures.
+ */
+export class TransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransportError';
+    }
+}
+/**
+ * Error thrown when connection to server fails.
+ */
+export class TransportConnectionError extends TransportError {
+    originalError;
+    url;
+    constructor(url, originalError) {
+        super(`Connection failed to ${url}${originalError ? `: ${originalError.message}` : ''}`);
+        this.name = 'TransportConnectionError';
+        this.url = url;
+        this.originalError = originalError;
+    }
+}
+/**
+ * Error thrown when client is not connected to server.
+ */
+export class TransportNotConnectedError extends TransportError {
+    constructor(operation = 'operation') {
+        super(`Not connected to server. Cannot perform: ${operation}`);
+        this.name = 'TransportNotConnectedError';
+    }
+}
+/**
+ * Error thrown when server is not started.
+ */
+export class TransportServerNotStartedError extends TransportError {
+    constructor(operation = 'operation') {
+        super(`Server not started. Cannot perform: ${operation}`);
+        this.name = 'TransportServerNotStartedError';
+    }
+}
+/**
+ * Error thrown when server is already running.
+ */
+export class TransportServerAlreadyRunningError extends TransportError {
+    port;
+    constructor(port) {
+        super(`Server is already running on port ${port}`);
+        this.name = 'TransportServerAlreadyRunningError';
+        this.port = port;
+    }
+}
+/**
+ * Error thrown when port is already in use.
+ */
+export class TransportPortInUseError extends TransportError {
+    port;
+    constructor(port) {
+        super(`Port ${port} is already in use`);
+        this.name = 'TransportPortInUseError';
+        this.port = port;
+    }
+}
+/**
+ * Error thrown when a request times out.
+ */
+export class TransportRequestTimeoutError extends TransportError {
+    event;
+    timeoutMs;
+    constructor(event, timeoutMs) {
+        super(`Request timeout for event '${event}' after ${timeoutMs}ms`);
+        this.name = 'TransportRequestTimeoutError';
+        this.event = event;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Error thrown when a request fails with server error.
+ */
+export class TransportRequestError extends TransportError {
+    event;
+    constructor(event, message = 'Request failed') {
+        super(`${message} for event '${event}'`);
+        this.name = 'TransportRequestError';
+        this.event = event;
+    }
+}
+/**
+ * Error thrown when room operations fail.
+ */
+export class TransportRoomError extends TransportError {
+    operation;
+    room;
+    constructor(room, operation) {
+        super(`Failed to ${operation} room '${room}'`);
+        this.name = 'TransportRoomError';
+        this.room = room;
+        this.operation = operation;
+    }
+}
+/**
+ * Error thrown when room operation times out.
+ */
+export class TransportRoomTimeoutError extends TransportError {
+    operation;
+    room;
+    timeoutMs;
+    constructor(room, operation, timeoutMs) {
+        super(`${operation === 'join' ? 'Join' : 'Leave'} room '${room}' timed out after ${timeoutMs}ms`);
+        this.name = 'TransportRoomTimeoutError';
+        this.room = room;
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+    }
+}

package/dist/core/domain/instance/index.d.ts

@@ -0,0 +1 @@
+export * from './types.js';

package/dist/core/domain/instance/index.js

@@ -0,0 +1 @@
+export * from './types.js';

package/dist/core/domain/instance/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Raw instance data as stored in instance.json.
+ * Used for serialization/deserialization.
+ *
+ * NOTE: We don't store "status" - we check pid alive at runtime instead.
+ * This avoids stale status when process crashes.
+ */
+export type InstanceInfoJson = {
+    /** Current active session ID (for quick lookup without DB query) */
+    currentSessionId: null | string;
+    /** Process ID of the Core process */
+    pid: number;
+    /** Port the transport server is listening on */
+    port: number;
+    /** Timestamp when instance started (ms since epoch) */
+    startedAt: number;
+};
+/**
+ * Instance information representing a BRV Core process.
+ *
+ * Architecture note (Section 7):
+ * - File exists + pid alive  → instance đang chạy
+ * - File exists + pid dead   → stale (crash), có thể overwrite
+ * - File không có            → không có instance nào
+ */
+export declare class InstanceInfo {
+    readonly currentSessionId: null | string;
+    readonly pid: number;
+    readonly port: number;
+    readonly startedAt: Date;
+    private constructor();
+    /**
+     * Creates a new instance info.
+     */
+    static create(data: {
+        currentSessionId?: null | string;
+        pid: number;
+        port: number;
+    }): InstanceInfo;
+    /**
+     * Creates instance info from JSON data (from instance.json file).
+     */
+    static fromJson(json: InstanceInfoJson): InstanceInfo;
+    /**
+     * Returns the transport URL for connecting to this instance.
+     * Uses 'localhost' instead of '127.0.0.1' for better sandbox compatibility.
+     */
+    getTransportUrl(): string;
+    /**
+     * Converts instance info to JSON for persistence.
+     */
+    toJson(): InstanceInfoJson;
+    /**
+     * Creates a new instance info with updated session ID.
+     */
+    withSessionId(sessionId: string): InstanceInfo;
+}

package/dist/core/domain/instance/types.js

@@ -0,0 +1,72 @@
+import { TRANSPORT_HOST } from '../../../constants.js';
+/**
+ * Instance information representing a BRV Core process.
+ *
+ * Architecture note (Section 7):
+ * - File exists + pid alive  → instance đang chạy
+ * - File exists + pid dead   → stale (crash), có thể overwrite
+ * - File không có            → không có instance nào
+ */
+export class InstanceInfo {
+    currentSessionId;
+    pid;
+    port;
+    startedAt;
+    constructor(data) {
+        this.currentSessionId = data.currentSessionId;
+        this.pid = data.pid;
+        this.port = data.port;
+        this.startedAt = data.startedAt;
+    }
+    /**
+     * Creates a new instance info.
+     */
+    static create(data) {
+        return new InstanceInfo({
+            currentSessionId: data.currentSessionId ?? null,
+            pid: data.pid,
+            port: data.port,
+            startedAt: new Date(),
+        });
+    }
+    /**
+     * Creates instance info from JSON data (from instance.json file).
+     */
+    static fromJson(json) {
+        return new InstanceInfo({
+            currentSessionId: json.currentSessionId,
+            pid: json.pid,
+            port: json.port,
+            startedAt: new Date(json.startedAt),
+        });
+    }
+    /**
+     * Returns the transport URL for connecting to this instance.
+     * Uses 'localhost' instead of '127.0.0.1' for better sandbox compatibility.
+     */
+    getTransportUrl() {
+        return `http://${TRANSPORT_HOST}:${this.port}`;
+    }
+    /**
+     * Converts instance info to JSON for persistence.
+     */
+    toJson() {
+        return {
+            currentSessionId: this.currentSessionId,
+            pid: this.pid,
+            port: this.port,
+            startedAt: this.startedAt.getTime(),
+        };
+    }
+    /**
+     * Creates a new instance info with updated session ID.
+     */
+    withSessionId(sessionId) {
+        return new InstanceInfo({
+            currentSessionId: sessionId,
+            pid: this.pid,
+            port: this.port,
+            startedAt: this.startedAt,
+        });
+    }
+}

package/dist/core/domain/knowledge/directory-manager.d.ts

@@ -34,6 +34,15 @@ export declare const DirectoryManager: {
      * @returns Whether topic was created, updated, or skipped
      */
     createOrUpdateTopic(topicPath: string): Promise<CreateOrUpdateResult>;
+    /**
+     * Delete a single file.
+     *
+     * @param filePath - Path to file to delete
+     * @returns Whether the file was deleted
+     */
+    deleteFile(filePath: string): Promise<{
+        deleted: boolean;
+    }>;
     /**
      * Delete a topic/subtopic folder recursively.
      * Removes the folder and all its contents.
@@ -65,6 +74,13 @@ export declare const DirectoryManager: {
      * @returns true if file exists, false otherwise
      */
     fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Check if a folder exists.
+     *
+     * @param folderPath - Path to folder
+     * @returns true if folder exists and is a directory, false otherwise
+     */
+    folderExists(folderPath: string): Promise<boolean>;
     /**
      * List all markdown files recursively in a directory.
      *

package/dist/core/domain/knowledge/directory-manager.js

@@ -43,6 +43,22 @@ export const DirectoryManager = {
             return { created: true, skipped: false, updated: false };
         }
     },
+    /**
+     * Delete a single file.
+     *
+     * @param filePath - Path to file to delete
+     * @returns Whether the file was deleted
+     */
+    async deleteFile(filePath) {
+        try {
+            await fs.access(filePath);
+            await fs.unlink(filePath);
+            return { deleted: true };
+        }
+        catch {
+            return { deleted: false };
+        }
+    },
     /**
      * Delete a topic/subtopic folder recursively.
      * Removes the folder and all its contents.
@@ -108,6 +124,21 @@ export const DirectoryManager = {
             return false;
         }
     },
+    /**
+     * Check if a folder exists.
+     *
+     * @param folderPath - Path to folder
+     * @returns true if folder exists and is a directory, false otherwise
+     */
+    async folderExists(folderPath) {
+        try {
+            const stat = await fs.stat(folderPath);
+            return stat.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
     /**
      * List all markdown files recursively in a directory.
      *

package/dist/core/domain/transport/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schemas.js';
+export * from './types.js';

package/dist/core/domain/transport/index.js

@@ -0,0 +1,2 @@
+export * from './schemas.js';
+export * from './types.js';