byterover-cli 0.4.0 → 1.0.0

package/dist/core/interfaces/instance/i-instance-manager.d.ts

@@ -0,0 +1,58 @@
+import type { InstanceInfo } from '../../domain/instance/types.js';
+/**
+ * Result of attempting to acquire an instance lock.
+ */
+export type AcquireResult = {
+    acquired: false;
+    existingInstance: InstanceInfo;
+    reason: 'already_running';
+} | {
+    acquired: true;
+    instance: InstanceInfo;
+};
+/**
+ * Interface for managing instance lifecycle.
+ *
+ * Architecture notes (Section 6 - Instance Lock):
+ * - 1 FOLDER = 1 TRANSPORT SERVER
+ * - Handles acquire/release semantics for instance.json
+ * - Verifies PID to detect crashed instances (no status field needed)
+ */
+export interface IInstanceManager {
+    /**
+     * Attempts to acquire an instance lock for the given project root.
+     *
+     * Flow:
+     * 1. Check if instance.json exists
+     * 2. If exists and pid alive → return already_running
+     * 3. If exists but stale (pid dead) → overwrite
+     * 4. Create new instance.json
+     *
+     * @param projectRoot - Root directory containing .brv/
+     * @param port - Port the transport server will use
+     * @returns AcquireResult indicating success or existing instance
+     */
+    acquire: (projectRoot: string, port: number) => Promise<AcquireResult>;
+    /**
+     * Reads instance info from the project root.
+     * Returns undefined if instance.json doesn't exist.
+     *
+     * @param projectRoot - Root directory containing .brv/
+     */
+    load: (projectRoot: string) => Promise<InstanceInfo | undefined>;
+    /**
+     * Releases the instance lock by deleting instance.json.
+     *
+     * Called during graceful shutdown.
+     *
+     * @param projectRoot - Root directory containing .brv/
+     */
+    release: (projectRoot: string) => Promise<void>;
+    /**
+     * Updates the current session ID in instance.json.
+     *
+     * @param projectRoot - Root directory containing .brv/
+     * @param sessionId - New session ID to set
+     */
+    updateSessionId: (projectRoot: string, sessionId: string) => Promise<void>;
+}

package/dist/core/interfaces/instance/i-instance-manager.js

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

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

@@ -0,0 +1,2 @@
+export * from './i-instance-discovery.js';
+export * from './i-instance-manager.js';

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

@@ -0,0 +1,2 @@
+export * from './i-instance-discovery.js';
+export * from './i-instance-manager.js';

package/dist/core/interfaces/noop-implementations.d.ts

@@ -0,0 +1,53 @@
+/**
+ * NoOp Implementations for Core Interfaces
+ *
+ * These are used by CoreProcess when creating UseCases for Transport mode.
+ * Transport mode receives auth/config directly and doesn't use these stores,
+ * so NoOp implementations are sufficient.
+ */
+import type { AuthToken } from '../domain/entities/auth-token.js';
+import type { BrvConfig } from '../domain/entities/brv-config.js';
+import type { EventName, PropertyDict } from '../domain/entities/event.js';
+import type { IProjectConfigStore } from './i-project-config-store.js';
+import type { ConfirmOptions, FileSelectorItem, FileSelectorOptions, InputOptions, ITerminal, SearchOptions, SelectOptions } from './i-terminal.js';
+import type { ITokenStore } from './i-token-store.js';
+import type { ITrackingService } from './i-tracking-service.js';
+/**
+ * NoOp Terminal - Does nothing, used for headless Transport mode.
+ */
+export declare class NoOpTerminal implements ITerminal {
+    actionStart(_message: string): void;
+    actionStop(_message?: string): void;
+    confirm(_options: ConfirmOptions): Promise<boolean>;
+    error(_message: string): void;
+    fileSelector(_options: FileSelectorOptions): Promise<FileSelectorItem | null>;
+    input(_options: InputOptions): Promise<string>;
+    log(_message?: string): void;
+    search<T>(_options: SearchOptions<T>): Promise<T>;
+    select<T>(_options: SelectOptions<T>): Promise<T>;
+    warn(_message: string): void;
+}
+/**
+ * NoOp Tracking Service - Does nothing, used for headless Transport mode.
+ */
+export declare class NoOpTrackingService implements ITrackingService {
+    track(_eventName: EventName, _properties?: PropertyDict): Promise<void>;
+}
+/**
+ * NoOp Token Store - Always returns undefined, used when Core loads auth separately.
+ * In Transport mode, auth is passed directly to UseCases.
+ */
+export declare class NoOpTokenStore implements ITokenStore {
+    clear(): Promise<void>;
+    load(): Promise<AuthToken | undefined>;
+    save(_token: AuthToken): Promise<void>;
+}
+/**
+ * NoOp Project Config Store - Always returns undefined, used when Core loads config separately.
+ * In Transport mode, brvConfig is passed directly to UseCases.
+ */
+export declare class NoOpProjectConfigStore implements IProjectConfigStore {
+    exists(_directory?: string): Promise<boolean>;
+    read(_directory?: string): Promise<BrvConfig | undefined>;
+    write(_config: BrvConfig, _directory?: string): Promise<void>;
+}

package/dist/core/interfaces/noop-implementations.js

@@ -0,0 +1,62 @@
+/**
+ * NoOp Implementations for Core Interfaces
+ *
+ * These are used by CoreProcess when creating UseCases for Transport mode.
+ * Transport mode receives auth/config directly and doesn't use these stores,
+ * so NoOp implementations are sufficient.
+ */
+/**
+ * NoOp Terminal - Does nothing, used for headless Transport mode.
+ */
+export class NoOpTerminal {
+    actionStart(_message) { }
+    actionStop(_message) { }
+    async confirm(_options) {
+        return false;
+    }
+    error(_message) { }
+    async fileSelector(_options) {
+        return null;
+    }
+    async input(_options) {
+        return '';
+    }
+    log(_message) { }
+    async search(_options) {
+        throw new Error('NoOpTerminal: search not supported in headless mode');
+    }
+    async select(_options) {
+        throw new Error('NoOpTerminal: select not supported in headless mode');
+    }
+    warn(_message) { }
+}
+/**
+ * NoOp Tracking Service - Does nothing, used for headless Transport mode.
+ */
+export class NoOpTrackingService {
+    async track(_eventName, _properties) { }
+}
+/**
+ * NoOp Token Store - Always returns undefined, used when Core loads auth separately.
+ * In Transport mode, auth is passed directly to UseCases.
+ */
+export class NoOpTokenStore {
+    async clear() { }
+    async load() {
+        return undefined;
+    }
+    async save(_token) { }
+}
+/**
+ * NoOp Project Config Store - Always returns undefined, used when Core loads config separately.
+ * In Transport mode, brvConfig is passed directly to UseCases.
+ */
+export class NoOpProjectConfigStore {
+    async exists(_directory) {
+        return false;
+    }
+    async read(_directory) {
+        return undefined;
+    }
+    async write(_config, _directory) { }
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Handler for server-broadcasted events.
+ * @param data - The event payload from server
+ */
+export type EventHandler<T = unknown> = (data: T) => void;
+/**
+ * Connection state of the transport client.
+ */
+export type ConnectionState = 'connected' | 'connecting' | 'disconnected' | 'reconnecting';
+/**
+ * Handler for connection state changes.
+ * @param state - The new connection state
+ */
+export type ConnectionStateHandler = (state: ConnectionState) => void;
+/**
+ * Options for client requests.
+ */
+export type RequestOptions = {
+    /**
+     * Timeout in milliseconds for the request.
+     * If not specified, uses the default timeout.
+     */
+    timeout?: number;
+};
+/**
+ * Interface for transport client operations.
+ * Provides abstraction over real-time communication protocols (Socket.IO, WebSocket, etc.)
+ * following Clean Architecture principles.
+ *
+ * The client:
+ * - Connects to a transport server
+ * - Sends requests and receives responses
+ * - Listens for broadcast events
+ * - Joins rooms for targeted broadcasts
+ */
+export interface ITransportClient {
+    /**
+     * Connects to the transport server at the specified URL.
+     * @param url - The server URL to connect to (e.g., "http://localhost:9847")
+     * @throws Error if connection fails
+     */
+    connect: (url: string) => Promise<void>;
+    /**
+     * Disconnects from the transport server.
+     * Cleans up resources and stops reconnection attempts.
+     */
+    disconnect: () => Promise<void>;
+    /**
+     * Returns the unique client ID assigned by the server.
+     * Returns undefined if not connected.
+     */
+    getClientId: () => string | undefined;
+    /**
+     * Returns the current connection state.
+     */
+    getState: () => ConnectionState;
+    /**
+     * Joins a room for targeted broadcasts.
+     * @param room - The room identifier to join
+     */
+    joinRoom: (room: string) => Promise<void>;
+    /**
+     * Leaves a room.
+     * @param room - The room identifier to leave
+     */
+    leaveRoom: (room: string) => Promise<void>;
+    /**
+     * Registers a handler for a specific event from the server.
+     * Multiple handlers can be registered for the same event.
+     * @param event - The event name to listen for
+     * @param handler - The function to handle incoming events
+     * @returns A function to unsubscribe the handler
+     */
+    on: <T = unknown>(event: string, handler: EventHandler<T>) => () => void;
+    /**
+     * Registers a one-time handler for a specific event.
+     * The handler will be automatically removed after first invocation.
+     * @param event - The event name to listen for
+     * @param handler - The function to handle the event
+     */
+    once: <T = unknown>(event: string, handler: EventHandler<T>) => void;
+    /**
+     * Registers a handler for connection state changes.
+     * @param handler - Called when connection state changes
+     * @returns A function to unsubscribe the handler
+     */
+    onStateChange: (handler: ConnectionStateHandler) => () => void;
+    /**
+     * Sends a request to the server and waits for a response.
+     * @param event - The event name
+     * @param data - The request payload
+     * @param options - Optional request configuration
+     * @returns The server's response
+     * @throws Error if request times out or server returns an error
+     */
+    request: <TResponse = unknown, TRequest = unknown>(event: string, data?: TRequest, options?: RequestOptions) => Promise<TResponse>;
+}

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

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

package/dist/core/interfaces/transport/i-transport-server.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Handler for incoming client requests.
+ * @param data - The request payload from client
+ * @param clientId - Unique identifier of the requesting client
+ * @returns Response data or void for fire-and-forget events
+ */
+export type RequestHandler<TRequest = unknown, TResponse = unknown> = (data: TRequest, clientId: string) => Promise<TResponse> | TResponse;
+/**
+ * Connection event handler.
+ * @param clientId - Unique identifier of the connected/disconnected client
+ */
+export type ConnectionHandler = (clientId: string) => void;
+/**
+ * Interface for transport server operations.
+ * Provides abstraction over real-time communication protocols (Socket.IO, WebSocket, etc.)
+ * following Clean Architecture principles.
+ *
+ * The server acts as a hub that:
+ * - Accepts client connections
+ * - Routes requests to handlers
+ * - Broadcasts events to connected clients
+ */
+export interface ITransportServer {
+    /**
+     * Adds a client to a room for targeted broadcasts.
+     * @param clientId - The client to add
+     * @param room - The room to join
+     */
+    addToRoom: (clientId: string, room: string) => void;
+    /**
+     * Broadcasts an event to all connected clients.
+     * @param event - The event name
+     * @param data - The data to send
+     */
+    broadcast: <T = unknown>(event: string, data: T) => void;
+    /**
+     * Broadcasts an event to clients in a specific room.
+     * @param room - The room identifier
+     * @param event - The event name
+     * @param data - The data to send
+     */
+    broadcastTo: <T = unknown>(room: string, event: string, data: T) => void;
+    /**
+     * Returns the port the server is listening on.
+     * Returns undefined if server is not started.
+     */
+    getPort: () => number | undefined;
+    /**
+     * Returns whether the server is currently running.
+     */
+    isRunning: () => boolean;
+    /**
+     * Registers a handler for client connection events.
+     * @param handler - Called when a client connects
+     */
+    onConnection: (handler: ConnectionHandler) => void;
+    /**
+     * Registers a handler for client disconnection events.
+     * @param handler - Called when a client disconnects
+     */
+    onDisconnection: (handler: ConnectionHandler) => void;
+    /**
+     * Registers a handler for a specific event type.
+     * The handler will be called when any client emits that event.
+     * @param event - The event name to listen for
+     * @param handler - The function to handle incoming requests
+     */
+    onRequest: <TRequest = unknown, TResponse = unknown>(event: string, handler: RequestHandler<TRequest, TResponse>) => void;
+    /**
+     * Removes a client from a room.
+     * @param clientId - The client to remove
+     * @param room - The room to leave
+     */
+    removeFromRoom: (clientId: string, room: string) => void;
+    /**
+     * Sends an event directly to a specific client.
+     * @param clientId - The target client ID
+     * @param event - The event name
+     * @param data - The data to send
+     */
+    sendTo: <T = unknown>(clientId: string, event: string, data: T) => void;
+    /**
+     * Starts the transport server on the specified port.
+     * @param port - The port number to listen on
+     * @throws Error if server fails to start (e.g., port in use)
+     */
+    start: (port: number) => Promise<void>;
+    /**
+     * Gracefully stops the transport server.
+     * Closes all client connections and releases resources.
+     */
+    stop: () => Promise<void>;
+}

package/dist/core/interfaces/transport/i-transport-server.js

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

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

@@ -0,0 +1,2 @@
+export * from './i-transport-client.js';
+export * from './i-transport-server.js';

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

@@ -0,0 +1,2 @@
+export * from './i-transport-client.js';
+export * from './i-transport-server.js';

package/dist/hooks/init/welcome.js

@@ -16,11 +16,11 @@ function checkNodeVersion() {
     const [, major, minor] = versionMatch;
     const majorVersion = Number.parseInt(major, 10);
     const minorVersion = Number.parseInt(minor, 10);
-    // Minimum supported version: Node 18
-    if (majorVersion < 18) {
+    // Minimum supported version: Node 20
+    if (majorVersion < 20) {
         return {
             message: `Node.js ${majorVersion}.${minorVersion} is not supported.\n` +
-                'ByteRover CLI requires Node.js 18 or higher.\n' +
+                'ByteRover CLI requires Node.js 20 or higher.\n' +
                 `Current version: ${nodeVersion}\n\n` +
                 'Please upgrade Node.js:\n' +
                 '  - Using nvm: nvm install 22 && nvm use 22\n' +
@@ -28,21 +28,21 @@ function checkNodeVersion() {
             type: 'error',
         };
     }
-    // Recommended versions: Node 18, 20, 22
-    // Node 24+ may have compatibility issues with native modules (better-sqlite3, grpc)
+    // Recommended versions: Node 20, 22
+    // Node 24+ may have compatibility issues with native modules
     if (majorVersion >= 24) {
         return {
             message: `Node.js ${majorVersion}.${minorVersion} has not been fully tested with ByteRover CLI.\n` +
                 `Current version: ${nodeVersion}\n` +
-                'Recommended versions: Node.js 18.x, 20.x, or 22.x (LTS)\n\n' +
-                'Some native dependencies (sqlite, grpc) may not work correctly.\n' +
+                'Recommended versions: Node.js 20.x or 22.x\n\n' +
+                'Some native dependencies may not work correctly.\n' +
                 'If you encounter errors, please switch to a recommended version:\n' +
                 '  - Using nvm: nvm install 22 && nvm use 22',
             type: 'warning',
         };
     }
     // All checks passed
-    return null;
+    return undefined;
 }
 const hook = async function (options) {
     // Check Node.js version compatibility first
@@ -79,23 +79,8 @@ const hook = async function (options) {
             chalk.cyan(String.raw ` |____/ \__, |\__\___|_| \_\___/ \_/ \___|_|    `),
             chalk.cyan('        |___/                                  '),
         ].join('\n');
-        const onboardingText = [
-            'ByteRover CLI quick start:',
-            '',
-            '  1. Authenticate with ByteRover:',
-            '     brv login',
-            '  2. Link your workspace:',
-            '     brv init',
-            '',
-            'After setup, run `brv status` to confirm your connection.',
-            '',
-            '  Explore commands:',
-            '    • `brv curate` - Organize and curate your context tree',
-            '    • `brv query` - Search and query your context tree',
-            '    • `brv push` - Push your context tree to ByteRover',
-        ].join('\n');
         const docsLink = `For more information, run 'brv --help', 'brv [command] --help' or visit ${DOCS_URL}`;
-        this.log(`\n${logo}\n\n${onboardingText}\n\n${docsLink}\n\n`);
+        this.log(`\n${logo}\n\n${docsLink}\n\n`);
     }
 };
 export default hook;

package/dist/infra/cipher/agent/agent-error-codes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Agent-specific error codes.
+ * Follows DextoAgent pattern for typed error identification.
+ */
+export declare enum AgentErrorCode {
+    ALREADY_STARTED = "agent_already_started",
+    EXECUTION_FAILED = "agent_execution_failed",
+    INITIALIZATION_FAILED = "agent_initialization_failed",
+    INVALID_CONFIG = "agent_invalid_config",
+    MISSING_REQUIRED_SERVICE = "agent_missing_required_service",
+    NOT_STARTED = "agent_not_started",
+    SERVICE_NOT_INITIALIZED = "agent_service_not_initialized",
+    SESSION_LIMIT_EXCEEDED = "agent_session_limit_exceeded",
+    SESSION_NOT_FOUND = "agent_session_not_found",
+    STOPPED = "agent_stopped"
+}

package/dist/infra/cipher/agent/agent-error-codes.js

@@ -0,0 +1,17 @@
+/**
+ * Agent-specific error codes.
+ * Follows DextoAgent pattern for typed error identification.
+ */
+export var AgentErrorCode;
+(function (AgentErrorCode) {
+    AgentErrorCode["ALREADY_STARTED"] = "agent_already_started";
+    AgentErrorCode["EXECUTION_FAILED"] = "agent_execution_failed";
+    AgentErrorCode["INITIALIZATION_FAILED"] = "agent_initialization_failed";
+    AgentErrorCode["INVALID_CONFIG"] = "agent_invalid_config";
+    AgentErrorCode["MISSING_REQUIRED_SERVICE"] = "agent_missing_required_service";
+    AgentErrorCode["NOT_STARTED"] = "agent_not_started";
+    AgentErrorCode["SERVICE_NOT_INITIALIZED"] = "agent_service_not_initialized";
+    AgentErrorCode["SESSION_LIMIT_EXCEEDED"] = "agent_session_limit_exceeded";
+    AgentErrorCode["SESSION_NOT_FOUND"] = "agent_session_not_found";
+    AgentErrorCode["STOPPED"] = "agent_stopped";
+})(AgentErrorCode || (AgentErrorCode = {}));

package/dist/infra/cipher/agent/agent-error.d.ts

@@ -0,0 +1,54 @@
+import { ExitCode, ExitError } from '../exit-codes.js';
+import { AgentErrorCode } from './agent-error-codes.js';
+/**
+ * Agent-specific error with typed error codes.
+ * Extends ExitError for oclif CLI integration.
+ *
+ * Follows DextoAgent pattern with static factory methods
+ * for creating well-typed errors.
+ */
+export declare class AgentError extends ExitError {
+    readonly agentErrorCode: AgentErrorCode;
+    readonly details?: unknown;
+    constructor(agentErrorCode: AgentErrorCode, exitCode: ExitCode, message: string, details?: unknown);
+    /**
+     * Agent is already started and cannot be started again.
+     */
+    static alreadyStarted(): AgentError;
+    /**
+     * Agent execution failed.
+     */
+    static executionFailed(reason: string, details?: unknown): AgentError;
+    /**
+     * Agent initialization failed.
+     */
+    static initializationFailed(reason: string, details?: unknown): AgentError;
+    /**
+     * Invalid agent configuration.
+     */
+    static invalidConfig(reason: string, details?: unknown): AgentError;
+    /**
+     * Required service is missing during agent start.
+     */
+    static missingRequiredService(serviceName: string): AgentError;
+    /**
+     * Agent must be started before performing operations.
+     */
+    static notStarted(): AgentError;
+    /**
+     * Service not initialized (internal bug).
+     */
+    static serviceNotInitialized(serviceName: string): AgentError;
+    /**
+     * Maximum session limit exceeded.
+     */
+    static sessionLimitExceeded(limit: number): AgentError;
+    /**
+     * Session not found.
+     */
+    static sessionNotFound(sessionId: string): AgentError;
+    /**
+     * Agent has been stopped and cannot be used.
+     */
+    static stopped(): AgentError;
+}

package/dist/infra/cipher/agent/agent-error.js

@@ -0,0 +1,79 @@
+import { ExitCode, ExitError } from '../exit-codes.js';
+import { AgentErrorCode } from './agent-error-codes.js';
+/**
+ * Agent-specific error with typed error codes.
+ * Extends ExitError for oclif CLI integration.
+ *
+ * Follows DextoAgent pattern with static factory methods
+ * for creating well-typed errors.
+ */
+export class AgentError extends ExitError {
+    agentErrorCode;
+    details;
+    constructor(agentErrorCode, exitCode, message, details) {
+        super(exitCode, message);
+        this.name = 'AgentError';
+        this.agentErrorCode = agentErrorCode;
+        this.details = details;
+    }
+    /**
+     * Agent is already started and cannot be started again.
+     */
+    static alreadyStarted() {
+        return new AgentError(AgentErrorCode.ALREADY_STARTED, ExitCode.RUNTIME_ERROR, 'Agent is already started. Call stop() before restarting.');
+    }
+    /**
+     * Agent execution failed.
+     */
+    static executionFailed(reason, details) {
+        return new AgentError(AgentErrorCode.EXECUTION_FAILED, ExitCode.RUNTIME_ERROR, `Agent execution failed: ${reason}`, details);
+    }
+    /**
+     * Agent initialization failed.
+     */
+    static initializationFailed(reason, details) {
+        return new AgentError(AgentErrorCode.INITIALIZATION_FAILED, ExitCode.RUNTIME_ERROR, `Agent initialization failed: ${reason}`, details);
+    }
+    /**
+     * Invalid agent configuration.
+     */
+    static invalidConfig(reason, details) {
+        return new AgentError(AgentErrorCode.INVALID_CONFIG, ExitCode.CONFIG_ERROR, `Invalid agent configuration: ${reason}`, details);
+    }
+    /**
+     * Required service is missing during agent start.
+     */
+    static missingRequiredService(serviceName) {
+        return new AgentError(AgentErrorCode.MISSING_REQUIRED_SERVICE, ExitCode.RUNTIME_ERROR, `Required service '${serviceName}' is missing during agent start.`);
+    }
+    /**
+     * Agent must be started before performing operations.
+     */
+    static notStarted() {
+        return new AgentError(AgentErrorCode.NOT_STARTED, ExitCode.RUNTIME_ERROR, 'Agent must be started before use. Call start() first.');
+    }
+    /**
+     * Service not initialized (internal bug).
+     */
+    static serviceNotInitialized(serviceName) {
+        return new AgentError(AgentErrorCode.SERVICE_NOT_INITIALIZED, ExitCode.RUNTIME_ERROR, `Service '${serviceName}' not initialized. This is a bug.`);
+    }
+    /**
+     * Maximum session limit exceeded.
+     */
+    static sessionLimitExceeded(limit) {
+        return new AgentError(AgentErrorCode.SESSION_LIMIT_EXCEEDED, ExitCode.RUNTIME_ERROR, `Maximum sessions (${limit}) reached. Delete unused sessions or increase limit.`);
+    }
+    /**
+     * Session not found.
+     */
+    static sessionNotFound(sessionId) {
+        return new AgentError(AgentErrorCode.SESSION_NOT_FOUND, ExitCode.VALIDATION_ERROR, `Session '${sessionId}' not found.`);
+    }
+    /**
+     * Agent has been stopped and cannot be used.
+     */
+    static stopped() {
+        return new AgentError(AgentErrorCode.STOPPED, ExitCode.RUNTIME_ERROR, 'Agent has been stopped and cannot be used. Create a new instance or call start() again.');
+    }
+}