byterover-cli 1.7.0 → 1.7.2

package/node_modules/@campfirein/brv-transport-client/dist/infra/connection-state-manager.js

@@ -0,0 +1,142 @@
+import { InvalidStateTransitionError } from '../core/domain/errors/transport-error.js';
+import { NoOpClientLogger } from './no-op-client-logger.js';
+/**
+ * Valid state transitions for the connection state machine.
+ * Each state can only transition to specific next states.
+ */
+const VALID_TRANSITIONS = {
+    disconnected: ['connecting'],
+    connecting: ['connected', 'disconnected'],
+    connected: ['reconnecting', 'disconnected'],
+    reconnecting: ['connected', 'disconnected'],
+};
+/**
+ * Manages connection state and notifies subscribers of state changes.
+ * Implements Observer Pattern for state change notifications.
+ *
+ * @remarks
+ * - State handlers persist across state changes until explicitly unsubscribed
+ * - Each handler receives the new state when it changes
+ * - Handlers are called synchronously in registration order
+ *
+ * @example
+ * ```typescript
+ * const stateManager = new ConnectionStateManager()
+ *
+ * const unsubscribe = stateManager.onStateChange((state) => {
+ *   console.log('State changed to:', state)
+ * })
+ *
+ * stateManager.setState('connecting') // Logs: "State changed to: connecting"
+ * stateManager.setState('connected')   // Logs: "State changed to: connected"
+ *
+ * unsubscribe()
+ * stateManager.setState('disconnected') // No log (unsubscribed)
+ * ```
+ */
+export class ConnectionStateManager {
+    #handlers = new Set();
+    #logger;
+    #state;
+    constructor(config) {
+        this.#state = config?.initialState ?? 'disconnected';
+        this.#logger = config?.logger ?? new NoOpClientLogger();
+    }
+    /**
+     * Gets the current connection state.
+     * @returns Current connection state
+     */
+    getState() {
+        return this.#state;
+    }
+    /**
+     * Updates the connection state and notifies handlers.
+     * Only notifies if the state actually changed.
+     * @throws {InvalidStateTransitionError} If the transition is not allowed
+     */
+    setState(newState) {
+        if (this.#state === newState) {
+            return;
+        }
+        // Validate transition
+        const validNext = VALID_TRANSITIONS[this.#state];
+        if (!validNext.includes(newState)) {
+            const error = new InvalidStateTransitionError(this.#state, newState);
+            this.#logger.error(`[ConnectionStateManager] Invalid transition: ${this.#state} -> ${newState}`);
+            throw error;
+        }
+        const previousState = this.#state;
+        this.#state = newState;
+        this.#logger.debug(`[ConnectionStateManager] State change: ${previousState} -> ${newState}`);
+        this.notifyHandlers(newState);
+    }
+    /**
+     * Registers a handler for connection state changes.
+     * @returns Unsubscribe function
+     */
+    onStateChange(handler) {
+        this.#handlers.add(handler);
+        return () => {
+            this.#handlers.delete(handler);
+        };
+    }
+    /**
+     * Clears all state handlers.
+     */
+    clearHandlers() {
+        this.#handlers.clear();
+    }
+    /**
+     * Checks if transition to a new state is valid from current state.
+     * @param newState - The target state
+     * @returns True if transition is allowed
+     */
+    canTransitionTo(newState) {
+        const validNext = VALID_TRANSITIONS[this.#state];
+        return validNext.includes(newState);
+    }
+    /**
+     * Checks if currently connected.
+     * @returns True if state is 'connected'
+     */
+    isConnected() {
+        return this.#state === 'connected';
+    }
+    /**
+     * Checks if currently connecting.
+     * @returns True if state is 'connecting'
+     */
+    isConnecting() {
+        return this.#state === 'connecting';
+    }
+    /**
+     * Checks if currently disconnected.
+     * @returns True if state is 'disconnected'
+     */
+    isDisconnected() {
+        return this.#state === 'disconnected';
+    }
+    /**
+     * Checks if currently reconnecting.
+     * @returns True if state is 'reconnecting'
+     */
+    isReconnecting() {
+        return this.#state === 'reconnecting';
+    }
+    /**
+     * Notifies all handlers of the state change.
+     */
+    notifyHandlers(newState) {
+        for (const handler of this.#handlers) {
+            try {
+                handler(newState);
+            }
+            catch (error) {
+                // Log but don't throw - one handler failing shouldn't break others
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                this.#logger.debug(`[ConnectionStateManager] Handler error: ${errorMsg}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=connection-state-manager.js.map

package/node_modules/@campfirein/brv-transport-client/dist/infra/connection-state-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-state-manager.js","sourceRoot":"","sources":["../../infra/connection-state-manager.ts"],"names":[],"mappings":"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"}

package/node_modules/@campfirein/brv-transport-client/dist/infra/event-dispatcher.d.ts

@@ -0,0 +1,168 @@
+import type { EventHandler, IEventDispatcher } from '../core/interfaces/i-event-dispatcher.js';
+import type { IClientLogger } from '../core/interfaces/i-client-logger.js';
+import type { ISocketProvider } from '../core/interfaces/i-socket-provider.js';
+/**
+ * Callback for handler errors.
+ * Called when an event handler throws an exception.
+ */
+export type HandlerErrorCallback = (event: string, error: Error, data: unknown) => void;
+/**
+ * Callback for callback errors (meta-error handler).
+ * Called when onHandlerError callback itself throws an exception.
+ */
+export type CallbackErrorCallback = (callbackError: Error, originalEvent: string, originalError: Error) => void;
+/**
+ * Configuration for EventDispatcher.
+ */
+export type EventDispatcherConfig = {
+    /** Logger for debugging (default: NoOpClientLogger) */
+    readonly logger?: IClientLogger;
+    /** Socket provider for accessing the socket instance (required) */
+    readonly socketProvider: ISocketProvider;
+    /**
+     * Callback for handler errors.
+     * Called when an event handler throws an exception, providing observability
+     * for production debugging. Errors are still logged but this callback
+     * allows custom error handling (e.g., reporting to error tracking service).
+     */
+    readonly onHandlerError?: HandlerErrorCallback;
+    /**
+     * Callback for callback errors (meta-error handler).
+     * Called when onHandlerError callback itself throws an exception.
+     * Provides visibility into error tracking service failures.
+     */
+    readonly onCallbackError?: CallbackErrorCallback;
+    /**
+     * Maximum number of pending once handlers to queue before connection.
+     * Prevents memory leaks when connection never succeeds.
+     * Default: 100
+     */
+    readonly maxPendingOnceHandlers?: number;
+};
+/**
+ * Manages event subscriptions and dispatching.
+ * Implements Observer Pattern with support for persistent and one-time handlers.
+ *
+ * @remarks
+ * - Handlers can be registered before socket connection is established
+ * - Pending handlers are queued and registered when setSocket() is called
+ * - Persistent handlers survive reconnects until explicitly unsubscribed
+ * - One-time handlers are removed after first invocation
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = new EventDispatcher()
+ *
+ * // Register handler before connection
+ * const unsubscribe = dispatcher.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * // Later, after connection established
+ * dispatcher.setSocket(socket)
+ * dispatcher.registerPendingHandlers()
+ *
+ * // Cleanup
+ * unsubscribe()
+ * ```
+ */
+export declare class EventDispatcher implements IEventDispatcher {
+    #private;
+    private static readonly DEFAULT_MAX_PENDING_ONCE_HANDLERS;
+    constructor(config: EventDispatcherConfig);
+    /**
+     * Gets the current socket from the provider.
+     * @returns Socket instance or undefined if not connected
+     */
+    private get socket();
+    /**
+     * Gets the count of registered event types.
+     * @returns Number of registered event types
+     */
+    getEventCount(): number;
+    /**
+     * Registers a persistent event handler.
+     * Handler persists until explicitly unsubscribed.
+     *
+     * @param event - Event name to listen for
+     * @param handler - Function to call when event is received
+     * @returns Unsubscribe function
+     * @throws InvalidEventNameError if event name is invalid
+     *
+     * @remarks
+     * BOUNDARY CAST: Socket.IO delivers unknown data; caller specifies T via generic.
+     * Type guard not possible for generic T at runtime.
+     */
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * Registers a one-time event handler.
+     * Handler is removed after first invocation.
+     *
+     * @param event - Event name to listen for
+     * @param handler - Function to call when event is received
+     * @throws InvalidEventNameError if event name is invalid
+     */
+    once<T = unknown>(event: string, handler: EventHandler<T>): void;
+    /**
+     * Registers all pending handlers on the socket.
+     * Called after successful connection.
+     */
+    registerPendingHandlers(): void;
+    /**
+     * Clears all socket event listeners.
+     * Used before re-registering to prevent listener accumulation.
+     */
+    clearSocketListeners(): void;
+    /**
+     * Clears all handlers and pending handlers.
+     * Used during disconnect cleanup.
+     */
+    clearAllHandlers(): void;
+    /**
+     * Clears only pending once handlers.
+     * Useful for explicit cleanup when connection attempts fail repeatedly.
+     */
+    clearPendingOnceHandlers(): void;
+    /**
+     * Gets the count of pending once handlers.
+     */
+    get pendingOnceHandlerCount(): number;
+    /**
+     * Registers a socket listener for an event if not already registered.
+     */
+    private registerSocketEventIfNeeded;
+    /**
+     * Wraps a handler with error handling.
+     * Centralized wrapper to ensure consistent error handling across all handler types.
+     *
+     * @param event - Event name for error reporting
+     * @param handler - Original handler to wrap
+     * @param handlerType - Type of handler for error reporting
+     * @returns Wrapped handler with try/catch error handling
+     */
+    private wrapHandlerWithErrorHandling;
+    /**
+     * Creates a wrapped once handler with error handling.
+     * Ensures consistent error handling behavior between on() and once() handlers.
+     *
+     * @param event - Event name for error reporting
+     * @param handler - Original handler to wrap
+     * @returns Wrapped handler with try/catch error handling
+     */
+    private createWrappedOnceHandler;
+    /**
+     * Handles errors thrown by event handlers.
+     * Centralizes error handling logic for both persistent and once handlers.
+     *
+     * @param event - Event name for error reporting
+     * @param error - The error thrown by the handler
+     * @param data - The event data that was passed to the handler
+     * @param handlerType - Type of handler ('persistent' or 'once') for logging
+     */
+    private handleHandlerError;
+    /**
+     * Removes socket listener for an event.
+     */
+    private removeSocketEventListener;
+}
+//# sourceMappingURL=event-dispatcher.d.ts.map

package/node_modules/@campfirein/brv-transport-client/dist/infra/event-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-dispatcher.d.ts","sourceRoot":"","sources":["../../infra/event-dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,0CAA0C,CAAA;AAC5F,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uCAAuC,CAAA;AACxE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,yCAAyC,CAAA;AAkB5E;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;AAEvF;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,KAAK,IAAI,CAAA;AAE/G;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAA;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAA;IAChD;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAA;CACzC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iCAAiC,CAAM;gBAWnD,MAAM,EAAE,qBAAqB;IAQzC;;;OAGG;IACH,OAAO,KAAK,MAAM,GAEjB;IAED;;;OAGG;IACI,aAAa,IAAI,MAAM;IAI9B;;;;;;;;;;;;OAYG;IACI,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IA2B3E;;;;;;;OAOG;IACI,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAiBvE;;;OAGG;IACI,uBAAuB,IAAI,IAAI;IAetC;;;OAGG;IACI,oBAAoB,IAAI,IAAI;IAUnC;;;OAGG;IACI,gBAAgB,IAAI,IAAI;IAM/B;;;OAGG;IACI,wBAAwB,IAAI,IAAI;IAIvC;;OAEG;IACH,IAAW,uBAAuB,IAAI,MAAM,CAE3C;IAED;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAoBnC;;;;;;;;OAQG;IACH,OAAO,CAAC,4BAA4B;IAcpC;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAIhC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;OAEG;IACH,OAAO,CAAC,yBAAyB;CAMlC"}

package/node_modules/@campfirein/brv-transport-client/dist/infra/event-dispatcher.js

@@ -0,0 +1,265 @@
+import { NoOpClientLogger } from './no-op-client-logger.js';
+import { MaxPendingOnceHandlersExceededError } from '../core/domain/errors/transport-error.js';
+import { validateEventName } from '../core/domain/validators/index.js';
+/**
+ * Manages event subscriptions and dispatching.
+ * Implements Observer Pattern with support for persistent and one-time handlers.
+ *
+ * @remarks
+ * - Handlers can be registered before socket connection is established
+ * - Pending handlers are queued and registered when setSocket() is called
+ * - Persistent handlers survive reconnects until explicitly unsubscribed
+ * - One-time handlers are removed after first invocation
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = new EventDispatcher()
+ *
+ * // Register handler before connection
+ * const unsubscribe = dispatcher.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * // Later, after connection established
+ * dispatcher.setSocket(socket)
+ * dispatcher.registerPendingHandlers()
+ *
+ * // Cleanup
+ * unsubscribe()
+ * ```
+ */
+export class EventDispatcher {
+    static DEFAULT_MAX_PENDING_ONCE_HANDLERS = 100;
+    #logger;
+    #socketProvider;
+    #onHandlerError;
+    #onCallbackError;
+    #maxPendingOnceHandlers;
+    #eventHandlers = new Map();
+    #registeredSocketEvents = new Set();
+    #pendingOnceHandlers = [];
+    constructor(config) {
+        this.#logger = config.logger ?? new NoOpClientLogger();
+        this.#socketProvider = config.socketProvider;
+        this.#onHandlerError = config.onHandlerError;
+        this.#onCallbackError = config.onCallbackError;
+        this.#maxPendingOnceHandlers = config.maxPendingOnceHandlers ?? EventDispatcher.DEFAULT_MAX_PENDING_ONCE_HANDLERS;
+    }
+    /**
+     * Gets the current socket from the provider.
+     * @returns Socket instance or undefined if not connected
+     */
+    get socket() {
+        return this.#socketProvider.getSocket();
+    }
+    /**
+     * Gets the count of registered event types.
+     * @returns Number of registered event types
+     */
+    getEventCount() {
+        return this.#eventHandlers.size;
+    }
+    /**
+     * Registers a persistent event handler.
+     * Handler persists until explicitly unsubscribed.
+     *
+     * @param event - Event name to listen for
+     * @param handler - Function to call when event is received
+     * @returns Unsubscribe function
+     * @throws InvalidEventNameError if event name is invalid
+     *
+     * @remarks
+     * BOUNDARY CAST: Socket.IO delivers unknown data; caller specifies T via generic.
+     * Type guard not possible for generic T at runtime.
+     */
+    on(event, handler) {
+        validateEventName(event);
+        // Get or create handler set for this event
+        if (!this.#eventHandlers.has(event)) {
+            this.#eventHandlers.set(event, new Set());
+        }
+        // Wrap handler to match StoredEventHandler signature
+        const wrappedHandler = (data) => handler(data);
+        const handlers = this.#eventHandlers.get(event);
+        handlers.add(wrappedHandler);
+        // Register socket listener if connected and not already registered
+        this.registerSocketEventIfNeeded(event);
+        // Return unsubscribe function
+        return () => {
+            handlers.delete(wrappedHandler);
+            // Clean up if no handlers remain for this event
+            if (handlers.size === 0) {
+                this.#eventHandlers.delete(event);
+                this.removeSocketEventListener(event);
+            }
+        };
+    }
+    /**
+     * Registers a one-time event handler.
+     * Handler is removed after first invocation.
+     *
+     * @param event - Event name to listen for
+     * @param handler - Function to call when event is received
+     * @throws InvalidEventNameError if event name is invalid
+     */
+    once(event, handler) {
+        validateEventName(event);
+        const wrappedHandler = (data) => handler(data);
+        if (!this.socket?.connected) {
+            // Queue for registration after connect, respecting max limit to prevent memory leaks
+            if (this.#pendingOnceHandlers.length >= this.#maxPendingOnceHandlers) {
+                throw new MaxPendingOnceHandlersExceededError(event, this.#maxPendingOnceHandlers);
+            }
+            this.#pendingOnceHandlers.push({ event, handler: wrappedHandler });
+            return;
+        }
+        this.socket.once(event, this.createWrappedOnceHandler(event, wrappedHandler));
+    }
+    /**
+     * Registers all pending handlers on the socket.
+     * Called after successful connection.
+     */
+    registerPendingHandlers() {
+        // Register persistent handlers
+        for (const event of this.#eventHandlers.keys()) {
+            this.registerSocketEventIfNeeded(event);
+        }
+        // Register and clear once handlers
+        if (this.socket && this.#pendingOnceHandlers.length > 0) {
+            for (const { event, handler } of this.#pendingOnceHandlers) {
+                this.socket.once(event, this.createWrappedOnceHandler(event, handler));
+            }
+            this.#pendingOnceHandlers.length = 0;
+        }
+    }
+    /**
+     * Clears all socket event listeners.
+     * Used before re-registering to prevent listener accumulation.
+     */
+    clearSocketListeners() {
+        if (!this.socket)
+            return;
+        for (const event of this.#registeredSocketEvents) {
+            this.socket.off(event);
+        }
+        this.#registeredSocketEvents.clear();
+    }
+    /**
+     * Clears all handlers and pending handlers.
+     * Used during disconnect cleanup.
+     */
+    clearAllHandlers() {
+        this.#eventHandlers.clear();
+        this.#pendingOnceHandlers.length = 0;
+        this.#registeredSocketEvents.clear();
+    }
+    /**
+     * Clears only pending once handlers.
+     * Useful for explicit cleanup when connection attempts fail repeatedly.
+     */
+    clearPendingOnceHandlers() {
+        this.#pendingOnceHandlers.length = 0;
+    }
+    /**
+     * Gets the count of pending once handlers.
+     */
+    get pendingOnceHandlerCount() {
+        return this.#pendingOnceHandlers.length;
+    }
+    /**
+     * Registers a socket listener for an event if not already registered.
+     */
+    registerSocketEventIfNeeded(event) {
+        if (!this.socket || this.#registeredSocketEvents.has(event)) {
+            return;
+        }
+        // Register dispatch listener on socket
+        this.socket.on(event, (data) => {
+            const handlers = this.#eventHandlers.get(event);
+            if (handlers) {
+                // Execute all persistent handlers with consistent error handling
+                for (const h of handlers) {
+                    // Use centralized error handling wrapper for consistency
+                    this.wrapHandlerWithErrorHandling(event, h, 'persistent')(data);
+                }
+            }
+        });
+        this.#registeredSocketEvents.add(event);
+    }
+    /**
+     * Wraps a handler with error handling.
+     * Centralized wrapper to ensure consistent error handling across all handler types.
+     *
+     * @param event - Event name for error reporting
+     * @param handler - Original handler to wrap
+     * @param handlerType - Type of handler for error reporting
+     * @returns Wrapped handler with try/catch error handling
+     */
+    wrapHandlerWithErrorHandling(event, handler, handlerType) {
+        return (data) => {
+            try {
+                handler(data);
+            }
+            catch (error) {
+                this.handleHandlerError(event, error, data, handlerType);
+            }
+        };
+    }
+    /**
+     * Creates a wrapped once handler with error handling.
+     * Ensures consistent error handling behavior between on() and once() handlers.
+     *
+     * @param event - Event name for error reporting
+     * @param handler - Original handler to wrap
+     * @returns Wrapped handler with try/catch error handling
+     */
+    createWrappedOnceHandler(event, handler) {
+        return this.wrapHandlerWithErrorHandling(event, handler, 'once');
+    }
+    /**
+     * Handles errors thrown by event handlers.
+     * Centralizes error handling logic for both persistent and once handlers.
+     *
+     * @param event - Event name for error reporting
+     * @param error - The error thrown by the handler
+     * @param data - The event data that was passed to the handler
+     * @param handlerType - Type of handler ('persistent' or 'once') for logging
+     */
+    handleHandlerError(event, error, data, handlerType) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const typeLabel = handlerType === 'once' ? 'Once handler' : 'Handler';
+        this.#logger.debug(`[EventDispatcher] ${typeLabel} error for '${event}': ${err.message}`);
+        // Call error callback if provided (for observability/error tracking)
+        if (this.#onHandlerError) {
+            try {
+                this.#onHandlerError(event, err, data);
+            }
+            catch (callbackError) {
+                // Prevent callback errors from breaking the event loop
+                const callbackErr = callbackError instanceof Error ? callbackError : new Error(String(callbackError));
+                this.#logger.warn(`[EventDispatcher] onHandlerError callback threw: ${callbackErr.message}`);
+                // Notify via meta-callback for visibility into callback failures
+                if (this.#onCallbackError) {
+                    try {
+                        this.#onCallbackError(callbackErr, event, err);
+                    }
+                    catch (metaCallbackError) {
+                        // Last resort - log the error so it's not completely silent
+                        const metaErr = metaCallbackError instanceof Error ? metaCallbackError : new Error(String(metaCallbackError));
+                        this.#logger.warn(`[EventDispatcher] onCallbackError callback also threw: ${metaErr.message}`);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Removes socket listener for an event.
+     */
+    removeSocketEventListener(event) {
+        if (this.socket && this.#registeredSocketEvents.has(event)) {
+            this.socket.off(event);
+            this.#registeredSocketEvents.delete(event);
+        }
+    }
+}
+//# sourceMappingURL=event-dispatcher.js.map

package/node_modules/@campfirein/brv-transport-client/dist/infra/event-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-dispatcher.js","sourceRoot":"","sources":["../../infra/event-dispatcher.ts"],"names":[],"mappings":"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"}

package/node_modules/@campfirein/brv-transport-client/dist/infra/file-instance-discovery.d.ts

@@ -0,0 +1,32 @@
+import type { DiscoveryResult, IInstanceDiscovery } from '../core/interfaces/i-instance-discovery.js';
+import type { IInstanceReader } from '../core/interfaces/i-instance-reader.js';
+/**
+ * File-based implementation of IInstanceDiscovery.
+ *
+ * Implements walk-up directory tree algorithm to find running instances.
+ */
+export declare class FileInstanceDiscovery implements IInstanceDiscovery {
+    #private;
+    constructor(instanceReader?: IInstanceReader);
+    /**
+     * Discovers a running instance starting from the given directory.
+     *
+     * Walk-up algorithm:
+     * 1. Start from `fromDir`
+     * 2. Check if .brv/instance.json exists
+     * 3. If yes, verify pid is alive
+     * 4. If no, walk up to parent directory
+     * 5. Repeat until root or found
+     */
+    discover(fromDir: string): Promise<DiscoveryResult>;
+    /**
+     * Finds the project root by walking up from a directory.
+     * Returns the directory containing .brv/ or undefined if not found.
+     */
+    findProjectRoot(fromDir: string): Promise<string | undefined>;
+    /**
+     * Checks if a directory exists.
+     */
+    private directoryExists;
+}
+//# sourceMappingURL=file-instance-discovery.d.ts.map

package/node_modules/@campfirein/brv-transport-client/dist/infra/file-instance-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-instance-discovery.d.ts","sourceRoot":"","sources":["../../infra/file-instance-discovery.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,eAAe,EAAE,kBAAkB,EAAC,MAAM,4CAA4C,CAAA;AACnG,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,yCAAyC,CAAA;AAM5E;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;;gBAGlD,cAAc,CAAC,EAAE,eAAe;IAI5C;;;;;;;;;OASG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAyBzD;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IA8BnE;;OAEG;YACW,eAAe;CAQ9B"}