byterover-cli 0.4.0 → 1.0.0

package/dist/infra/transport/socket-io-transport-server.js

@@ -0,0 +1,207 @@
+import { instrument } from '@socket.io/admin-ui';
+import { createServer } from 'node:http';
+import { Server } from 'socket.io';
+import { isDevelopment } from '../../config/environment.js';
+import { TRANSPORT_PING_INTERVAL_MS, TRANSPORT_PING_TIMEOUT_MS } from '../../constants.js';
+import { TransportPortInUseError, TransportServerAlreadyRunningError, TransportServerNotStartedError, } from '../../core/domain/errors/transport-error.js';
+import { transportLog } from '../../utils/process-logger.js';
+/**
+ * Internal protocol constants for request/response pattern.
+ */
+const RESPONSE_EVENT_SUFFIX = ':response';
+const ERROR_EVENT_SUFFIX = ':error';
+/**
+ * Socket.IO implementation of ITransportServer.
+ *
+ * Architecture notes:
+ * - Uses an HTTP server internally for Socket.IO
+ * - Request/response pattern: client emits "event", server emits "event:response" or "event:error"
+ * - Rooms are used for targeted broadcasts (e.g., per-task events)
+ */
+export class SocketIOTransportServer {
+    config;
+    connectionHandlers = [];
+    disconnectionHandlers = [];
+    httpServer;
+    io;
+    port;
+    requestHandlers = new Map();
+    running = false;
+    sockets = new Map();
+    constructor(config) {
+        this.config = {
+            corsOrigin: config?.corsOrigin ?? '*',
+            pingIntervalMs: config?.pingIntervalMs ?? TRANSPORT_PING_INTERVAL_MS,
+            pingTimeoutMs: config?.pingTimeoutMs ?? TRANSPORT_PING_TIMEOUT_MS,
+        };
+    }
+    addToRoom(clientId, room) {
+        const socket = this.sockets.get(clientId);
+        if (socket) {
+            socket.join(room);
+        }
+    }
+    broadcast(event, data) {
+        const { io } = this;
+        if (!io) {
+            throw new TransportServerNotStartedError('broadcast');
+        }
+        io.emit(event, data);
+    }
+    broadcastTo(room, event, data) {
+        const { io } = this;
+        if (!io) {
+            throw new TransportServerNotStartedError('broadcastTo');
+        }
+        io.to(room).emit(event, data);
+    }
+    getPort() {
+        return this.port;
+    }
+    isRunning() {
+        return this.running;
+    }
+    onConnection(handler) {
+        this.connectionHandlers.push(handler);
+    }
+    onDisconnection(handler) {
+        this.disconnectionHandlers.push(handler);
+    }
+    onRequest(event, handler) {
+        const { io } = this;
+        if (!io) {
+            throw new TransportServerNotStartedError('onRequest');
+        }
+        // Store handler wrapped to accept unknown types (avoids type assertion)
+        const wrappedHandler = (data, clientId) => handler(data, clientId);
+        this.requestHandlers.set(event, wrappedHandler);
+        // Apply handler to all existing sockets
+        for (const socket of this.sockets.values()) {
+            this.registerEventHandler(socket, event, wrappedHandler);
+        }
+    }
+    removeFromRoom(clientId, room) {
+        const socket = this.sockets.get(clientId);
+        if (socket) {
+            socket.leave(room);
+        }
+    }
+    sendTo(clientId, event, data) {
+        const socket = this.sockets.get(clientId);
+        if (socket) {
+            socket.emit(event, data);
+        }
+    }
+    async start(port) {
+        if (this.running) {
+            throw new TransportServerAlreadyRunningError(this.port ?? port);
+        }
+        return new Promise((resolve, reject) => {
+            this.httpServer = createServer();
+            // In development mode, allow admin.socket.io for debugging
+            const corsOrigin = isDevelopment() ? [this.config.corsOrigin, 'https://admin.socket.io'] : this.config.corsOrigin;
+            this.io = new Server(this.httpServer, {
+                cors: {
+                    credentials: isDevelopment(), // Required for admin UI authentication
+                    origin: corsOrigin,
+                },
+                // Aggressive ping for faster disconnect detection (real-time)
+                pingInterval: this.config.pingIntervalMs,
+                pingTimeout: this.config.pingTimeoutMs,
+            });
+            // Enable Socket.IO Admin UI in development mode only
+            if (isDevelopment()) {
+                instrument(this.io, {
+                    auth: false, // No authentication for local dev
+                    mode: 'development',
+                });
+                transportLog('Socket.IO Admin UI enabled - connect at https://admin.socket.io');
+            }
+            this.io.on('connection', (socket) => {
+                const clientId = socket.id;
+                this.sockets.set(clientId, socket);
+                // Apply all registered request handlers to new socket
+                for (const [event, handler] of this.requestHandlers) {
+                    this.registerEventHandler(socket, event, handler);
+                }
+                // Notify connection handlers
+                for (const handler of this.connectionHandlers) {
+                    handler(clientId);
+                }
+                socket.on('disconnect', () => {
+                    this.sockets.delete(clientId);
+                    // Notify disconnection handlers
+                    for (const handler of this.disconnectionHandlers) {
+                        handler(clientId);
+                    }
+                });
+                // Handle room join requests
+                socket.on('room:join', (room, callback) => {
+                    socket.join(room);
+                    callback?.({ success: true });
+                });
+                // Handle room leave requests
+                socket.on('room:leave', (room, callback) => {
+                    socket.leave(room);
+                    callback?.({ success: true });
+                });
+            });
+            this.httpServer.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    reject(new TransportPortInUseError(port));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            this.httpServer.listen(port, () => {
+                this.port = port;
+                this.running = true;
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        const { httpServer, io } = this;
+        if (!this.running || !io || !httpServer) {
+            return;
+        }
+        return new Promise((resolve) => {
+            // Disconnect all sockets
+            io.disconnectSockets(true);
+            // Close Socket.IO server
+            io.close(() => {
+                // Close HTTP server
+                httpServer.close(() => {
+                    this.running = false;
+                    this.port = undefined;
+                    this.sockets.clear();
+                    resolve();
+                });
+            });
+        });
+    }
+    registerEventHandler(socket, event, handler) {
+        socket.on(event, async (data, callback) => {
+            try {
+                const result = await handler(data, socket.id);
+                // Support both callback style and event-based response
+                if (callback) {
+                    callback({ data: result, success: true });
+                }
+                else {
+                    socket.emit(`${event}${RESPONSE_EVENT_SUFFIX}`, { data: result, success: true });
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                if (callback) {
+                    callback({ error: errorMessage, success: false });
+                }
+                else {
+                    socket.emit(`${event}${ERROR_EVENT_SUFFIX}`, { error: errorMessage, success: false });
+                }
+            }
+        });
+    }
+}

package/dist/infra/transport/transport-client-factory.d.ts

@@ -0,0 +1,76 @@
+import type { ILogger } from '../../core/interfaces/cipher/i-logger.js';
+import type { IInstanceDiscovery } from '../../core/interfaces/instance/i-instance-discovery.js';
+import type { ITransportClient } from '../../core/interfaces/transport/i-transport-client.js';
+/**
+ * Result of connection attempt.
+ */
+export type ConnectionResult = {
+    /** The connected transport client */
+    client: ITransportClient;
+    /** Project root where instance was found */
+    projectRoot: string;
+};
+/**
+ * Configuration for TransportClientFactory.
+ */
+export type TransportClientFactoryConfig = {
+    /** Instance discovery service */
+    discovery?: IInstanceDiscovery;
+    /** Logger instance */
+    logger?: ILogger;
+    /** Maximum retry attempts (default: 8 for sandbox environments) */
+    maxRetries?: number;
+    /** Delay between retries in ms (default: 150 for faster sandbox warm-up) */
+    retryDelayMs?: number;
+};
+/**
+ * Factory for creating connected transport clients.
+ *
+ * Handles:
+ * - Instance discovery (walk-up directory tree)
+ * - Connection establishment
+ * - Retry logic
+ * - Error translation to user-friendly messages
+ */
+export declare class TransportClientFactory {
+    private readonly discovery;
+    private readonly logger;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    constructor(config?: TransportClientFactoryConfig);
+    /**
+     * Discovers a running instance and connects to it.
+     *
+     * @param fromDir - Directory to start discovery from (default: cwd)
+     * @returns Connected client and project root
+     * @throws NoInstanceRunningError - No .brv directory found
+     * @throws InstanceCrashedError - Instance found but process dead
+     * @throws ConnectionFailedError - Instance found but connection failed
+     */
+    connect(fromDir?: string): Promise<ConnectionResult>;
+    /**
+     * Connects to the instance with retry logic.
+     * Includes HTTP warm-up to trigger sandbox permission requests.
+     *
+     * Sandbox environments (like Cursor IDE terminals) block network access initially.
+     * The first connection attempt triggers the permission request, subsequent attempts succeed.
+     */
+    private connectWithRetry;
+    /**
+     * Delay helper.
+     */
+    private delay;
+    /**
+     * Attempts an HTTP warm-up request to trigger sandbox network permission.
+     * This uses native fetch() which might be handled differently by sandboxes than WebSocket.
+     */
+    private httpWarmUp;
+}
+/**
+ * Gets or creates the singleton factory.
+ */
+export declare function getTransportClientFactory(config?: TransportClientFactoryConfig): TransportClientFactory;
+/**
+ * Creates a new factory instance.
+ */
+export declare function createTransportClientFactory(config?: TransportClientFactoryConfig): TransportClientFactory;

package/dist/infra/transport/transport-client-factory.js

@@ -0,0 +1,168 @@
+import { ConnectionFailedError, InstanceCrashedError, NoInstanceRunningError, } from '../../core/domain/errors/connection-error.js';
+import { NoOpLogger } from '../../core/interfaces/cipher/i-logger.js';
+import { FileInstanceDiscovery } from '../instance/file-instance-discovery.js';
+import { SocketIOTransportClient } from './socket-io-transport-client.js';
+/**
+ * Factory for creating connected transport clients.
+ *
+ * Handles:
+ * - Instance discovery (walk-up directory tree)
+ * - Connection establishment
+ * - Retry logic
+ * - Error translation to user-friendly messages
+ */
+export class TransportClientFactory {
+    discovery;
+    logger;
+    maxRetries;
+    retryDelayMs;
+    constructor(config) {
+        this.discovery = config?.discovery ?? new FileInstanceDiscovery();
+        this.logger = config?.logger ?? new NoOpLogger();
+        // Increased retries for sandbox warm-up scenarios (IDE terminals like Cursor)
+        // First connection often fails, subsequent ones succeed after sandbox "warms up"
+        this.maxRetries = config?.maxRetries ?? 8;
+        // Shorter delay to retry faster after sandbox warm-up
+        this.retryDelayMs = config?.retryDelayMs ?? 150;
+    }
+    /**
+     * Discovers a running instance and connects to it.
+     *
+     * @param fromDir - Directory to start discovery from (default: cwd)
+     * @returns Connected client and project root
+     * @throws NoInstanceRunningError - No .brv directory found
+     * @throws InstanceCrashedError - Instance found but process dead
+     * @throws ConnectionFailedError - Instance found but connection failed
+     */
+    async connect(fromDir = process.cwd()) {
+        // Discover running instance
+        this.logger.debug('Discovering instance', { fromDir });
+        const result = await this.discovery.discover(fromDir);
+        if (!result.found) {
+            if (result.reason === 'instance_crashed') {
+                throw new InstanceCrashedError();
+            }
+            throw new NoInstanceRunningError();
+        }
+        const { instance, projectRoot } = result;
+        const url = instance.getTransportUrl();
+        this.logger.info('Instance discovered', { pid: instance.pid, port: instance.port, projectRoot });
+        // Connect with retry
+        const client = await this.connectWithRetry(url, instance.port);
+        return { client, projectRoot };
+    }
+    /**
+     * Connects to the instance with retry logic.
+     * Includes HTTP warm-up to trigger sandbox permission requests.
+     *
+     * Sandbox environments (like Cursor IDE terminals) block network access initially.
+     * The first connection attempt triggers the permission request, subsequent attempts succeed.
+     */
+    async connectWithRetry(url, port) {
+        let lastError;
+        // HTTP warm-up: Try a simple HTTP request first to trigger sandbox permission
+        // This is simpler than WebSocket and might trigger sandbox permission differently
+        this.logger.debug('Attempting HTTP warm-up', { url });
+        await this.httpWarmUp(url);
+        // Small delay after HTTP warm-up
+        await this.delay(100);
+        // Now retry with proper connection attempts
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            const client = new SocketIOTransportClient();
+            try {
+                this.logger.debug('Connection attempt', { attempt, maxRetries: this.maxRetries, url });
+                // eslint-disable-next-line no-await-in-loop
+                await client.connect(url);
+                this.logger.info('Connected to instance', { clientId: client.getClientId(), url });
+                return client;
+            }
+            catch (error) {
+                // Safety cleanup: ensure client is disconnected even if connect() throws
+                // for reasons other than connect_error (edge cases).
+                // Note: SocketIOTransportClient.connect() now handles cleanup on connect_error,
+                // but this provides defense-in-depth for unexpected exceptions.
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    await client.disconnect();
+                }
+                catch {
+                    // Ignore disconnect errors during cleanup
+                }
+                lastError = error instanceof Error ? error : new Error(String(error));
+                const errorMessage = lastError.message.toLowerCase();
+                const isSandboxError = errorMessage.includes('websocket error') ||
+                    errorMessage.includes('network') ||
+                    errorMessage.includes('connection failed') ||
+                    errorMessage.includes('econnrefused');
+                this.logger.warn('Connection attempt failed', {
+                    attempt,
+                    error: lastError.message,
+                    isSandboxError,
+                });
+                // Don't retry on the last attempt
+                if (attempt < this.maxRetries) {
+                    // For sandbox errors, use longer delays to allow network permissions to be granted
+                    // First retry: 300ms (if sandbox), 150ms (otherwise)
+                    // Second retry: 600ms (if sandbox), 300ms (otherwise)
+                    const baseDelay = isSandboxError ? 300 : this.retryDelayMs;
+                    const delayMs = baseDelay * attempt;
+                    // eslint-disable-next-line no-await-in-loop
+                    await this.delay(delayMs);
+                }
+            }
+        }
+        throw new ConnectionFailedError(port, lastError);
+    }
+    /**
+     * Delay helper.
+     */
+    delay(ms) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        });
+    }
+    /**
+     * Attempts an HTTP warm-up request to trigger sandbox network permission.
+     * This uses native fetch() which might be handled differently by sandboxes than WebSocket.
+     */
+    async httpWarmUp(url) {
+        try {
+            // Try to hit the Socket.IO endpoint with a simple HTTP GET
+            // This might trigger sandbox permission without the WebSocket complexity
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 1000);
+            // eslint-disable-next-line n/no-unsupported-features/node-builtins -- fetch available in Node 18+
+            await fetch(`${url}/socket.io/?EIO=4&transport=polling`, {
+                method: 'GET',
+                signal: controller.signal,
+            }).catch(() => {
+                // Ignore errors - we just want to trigger the network request
+            });
+            clearTimeout(timeoutId);
+            return true;
+        }
+        catch {
+            // HTTP warm-up failed - not critical, continue with WebSocket
+            return false;
+        }
+    }
+}
+/**
+ * Singleton factory instance for convenience.
+ */
+let factoryInstance;
+/**
+ * Gets or creates the singleton factory.
+ */
+export function getTransportClientFactory(config) {
+    if (!factoryInstance) {
+        factoryInstance = new TransportClientFactory(config);
+    }
+    return factoryInstance;
+}
+/**
+ * Creates a new factory instance.
+ */
+export function createTransportClientFactory(config) {
+    return new TransportClientFactory(config);
+}

package/dist/infra/transport/transport-factory.d.ts

@@ -0,0 +1,33 @@
+import type { TransportClientConfig, TransportServerConfig } from '../../core/domain/transport/types.js';
+import type { ITransportClient } from '../../core/interfaces/transport/i-transport-client.js';
+import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
+/**
+ * Creates a transport server instance.
+ *
+ * @param config - Optional server configuration, defaults to constants
+ * @returns Transport server implementation
+ *
+ * @example
+ * // Use defaults
+ * const server = createTransportServer();
+ *
+ * @example
+ * // Custom config
+ * const server = createTransportServer({ pingIntervalMs: 2000 });
+ */
+export declare function createTransportServer(config?: TransportServerConfig): ITransportServer;
+/**
+ * Creates a transport client instance.
+ *
+ * @param config - Optional client configuration, defaults to constants
+ * @returns Transport client implementation
+ *
+ * @example
+ * // Use defaults
+ * const client = createTransportClient();
+ *
+ * @example
+ * // Custom config for tests
+ * const client = createTransportClient({ connectTimeoutMs: 1000 });
+ */
+export declare function createTransportClient(config?: TransportClientConfig): ITransportClient;

package/dist/infra/transport/transport-factory.js

@@ -0,0 +1,59 @@
+import { TRANSPORT_CONNECT_TIMEOUT_MS, TRANSPORT_DEFAULT_TRANSPORTS, TRANSPORT_PING_INTERVAL_MS, TRANSPORT_PING_TIMEOUT_MS, TRANSPORT_RECONNECTION_ATTEMPTS, TRANSPORT_RECONNECTION_DELAY_MAX_MS, TRANSPORT_RECONNECTION_DELAY_MS, TRANSPORT_REQUEST_TIMEOUT_MS, TRANSPORT_ROOM_TIMEOUT_MS, } from '../../constants.js';
+import { SocketIOTransportClient } from './socket-io-transport-client.js';
+import { SocketIOTransportServer } from './socket-io-transport-server.js';
+/**
+ * Default server configuration using constants.
+ */
+const DEFAULT_SERVER_CONFIG = {
+    corsOrigin: '*',
+    pingIntervalMs: TRANSPORT_PING_INTERVAL_MS,
+    pingTimeoutMs: TRANSPORT_PING_TIMEOUT_MS,
+};
+/**
+ * Default client configuration using constants.
+ */
+const DEFAULT_CLIENT_CONFIG = {
+    connectTimeoutMs: TRANSPORT_CONNECT_TIMEOUT_MS,
+    reconnectionAttempts: TRANSPORT_RECONNECTION_ATTEMPTS,
+    reconnectionDelayMaxMs: TRANSPORT_RECONNECTION_DELAY_MAX_MS,
+    reconnectionDelayMs: TRANSPORT_RECONNECTION_DELAY_MS,
+    requestTimeoutMs: TRANSPORT_REQUEST_TIMEOUT_MS,
+    roomTimeoutMs: TRANSPORT_ROOM_TIMEOUT_MS,
+    transports: TRANSPORT_DEFAULT_TRANSPORTS,
+};
+/**
+ * Creates a transport server instance.
+ *
+ * @param config - Optional server configuration, defaults to constants
+ * @returns Transport server implementation
+ *
+ * @example
+ * // Use defaults
+ * const server = createTransportServer();
+ *
+ * @example
+ * // Custom config
+ * const server = createTransportServer({ pingIntervalMs: 2000 });
+ */
+export function createTransportServer(config) {
+    const mergedConfig = { ...DEFAULT_SERVER_CONFIG, ...config };
+    return new SocketIOTransportServer(mergedConfig);
+}
+/**
+ * Creates a transport client instance.
+ *
+ * @param config - Optional client configuration, defaults to constants
+ * @returns Transport client implementation
+ *
+ * @example
+ * // Use defaults
+ * const client = createTransportClient();
+ *
+ * @example
+ * // Custom config for tests
+ * const client = createTransportClient({ connectTimeoutMs: 1000 });
+ */
+export function createTransportClient(config) {
+    const mergedConfig = { ...DEFAULT_CLIENT_CONFIG, ...config };
+    return new SocketIOTransportClient(mergedConfig);
+}

package/dist/infra/usecase/curate-use-case.d.ts

@@ -1,66 +1,19 @@
-import type { IProjectConfigStore } from '../../core/interfaces/i-project-config-store.js';
 import type { ITerminal } from '../../core/interfaces/i-terminal.js';
-import type { ITokenStore } from '../../core/interfaces/i-token-store.js';
-import type { ITrackingService } from '../../core/interfaces/i-tracking-service.js';
 import type { CurateUseCaseRunOptions, ICurateUseCase } from '../../core/interfaces/usecase/i-curate-use-case.js';
+import { ITrackingService } from '../../core/interfaces/i-tracking-service.js';
+import { type TransportClientFactory } from '../transport/transport-client-factory.js';
+export type TransportClientFactoryCreator = () => TransportClientFactory;
 export interface CurateUseCaseOptions {
-    projectConfigStore: IProjectConfigStore;
     terminal: ITerminal;
-    tokenStore: ITokenStore;
     trackingService: ITrackingService;
+    /** Optional factory creator for dependency injection (defaults to createTransportClientFactory) */
+    transportClientFactoryCreator?: TransportClientFactoryCreator;
 }
 export declare class CurateUseCase implements ICurateUseCase {
-    private readonly projectConfigStore;
     private readonly terminal;
-    private readonly tokenStore;
     private readonly trackingService;
+    private readonly transportClientFactoryCreator;
     constructor(options: CurateUseCaseOptions);
-    /**
-     * Create topic folder with context.md file
-     * @param targetPath - The parent path where the topic folder will be created
-     * @param topicName - The name of the topic folder to create
-     * @returns The path to the created context.md file
-     */
-    protected createTopicWithContextFile(targetPath: string, topicName: string): string;
-    /**
-     * Generate a unique session ID for the autonomous agent.
-     * Uses crypto.randomUUID() for guaranteed uniqueness (122 bits of entropy).
-     */
-    protected generateSessionId(): string;
-    /**
-     * Navigate through the context tree using file selector
-     * Returns the selected path relative to context-tree root
-     */
-    protected navigateContextTree(): Promise<null | string>;
-    /**
-     * Open a file in the default editor
-     * @param filePath - The path to the file to open
-     */
-    protected openFile(filePath: string): Promise<void>;
-    /**
-     * Prompt user to enter topic name with validation
-     * @param targetPath - The path where the topic folder will be created
-     * @returns The topic name or null if cancelled
-     */
-    protected promptForTopicName(targetPath: string): Promise<null | string>;
-    run(options: CurateUseCaseRunOptions): Promise<void>;
-    /**
-     * Handle workspace not initialized error
-     */
-    private handleWorkspaceError;
-    /**
-     * Process file paths from --files flag
-     * @param filePaths - Array of file paths (relative or absolute)
-     * @returns Formatted instructions for the agent to read the specified files, or undefined if validation fails
-     */
-    private processFileReferences;
-    /**
-     * Run in autonomous mode - push to queue for background processing
-     */
-    private runAutonomous;
-    /**
-     * Run in interactive mode with manual prompts
-     */
-    private runInteractive;
-    private validateTopicName;
+    run({ context, files, verbose }: CurateUseCaseRunOptions): Promise<void>;
+    private handleConnectionError;
 }