byterover-cli 1.8.0 → 2.1.0

package/dist/server/core/interfaces/project/i-project-registry.d.ts

@@ -0,0 +1,46 @@
+import type { ProjectInfo } from '../../domain/project/project-info.js';
+/**
+ * Registry for mapping project paths to their XDG storage locations.
+ *
+ * Manages the lifecycle of project registrations: creating per-project
+ * directories, persisting the mapping to disk, and providing lookups.
+ *
+ * Consumed by transport-handlers (T3/T4) during client registration.
+ */
+export interface IProjectRegistry {
+    /**
+     * Get a registered project by its path.
+     * The path is resolved to its canonical form before lookup.
+     *
+     * @param projectPath - Absolute path to the project
+     * @returns ProjectInfo if registered, undefined otherwise
+     */
+    get(projectPath: string): ProjectInfo | undefined;
+    /**
+     * Get all registered projects.
+     *
+     * @returns Read-only map of resolved projectPath → ProjectInfo
+     */
+    getAll(): ReadonlyMap<string, ProjectInfo>;
+    /**
+     * Register a project. Idempotent — returns existing ProjectInfo
+     * if the project is already registered.
+     *
+     * On first registration:
+     * - Resolves symlinks in the project path
+     * - Creates per-project XDG directories (sessions/, etc.)
+     * - Persists the mapping to registry.json
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns ProjectInfo with the storage path mapping
+     */
+    register(projectPath: string): ProjectInfo;
+    /**
+     * Remove a project from the registry.
+     * Does NOT delete the project's XDG directories (data preservation).
+     *
+     * @param projectPath - Absolute path to the project
+     * @returns true if the project was registered and removed, false if not found
+     */
+    unregister(projectPath: string): boolean;
+}

package/dist/server/core/interfaces/project/i-project-registry.js

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

package/dist/server/core/interfaces/routing/i-project-router.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Project-scoped event routing.
+ *
+ * Wraps transport room operations with project-specific room naming,
+ * providing a clean API for broadcasting events to project members.
+ *
+ * Room naming convention: project:<sanitizedPath>:broadcast
+ *
+ * Consumed by TransportHandlers (T3) and ClientManager (T4) for
+ * project-scoped event delivery.
+ */
+export interface IProjectRouter {
+    /**
+     * Add a client to a project's broadcast room.
+     * Uses the project's sanitizedPath to derive the Socket.IO room name.
+     *
+     * @param clientId - The Socket.IO client ID
+     * @param sanitizedPath - The sanitized project path (from ProjectInfo)
+     */
+    addToProjectRoom(clientId: string, sanitizedPath: string): void;
+    /**
+     * Broadcast an event to all clients in a project's broadcast room.
+     *
+     * @param sanitizedPath - The sanitized project path
+     * @param event - The event name
+     * @param data - The event payload
+     * @param except - Optional client ID to exclude from the broadcast
+     */
+    broadcastToProject<T = unknown>(sanitizedPath: string, event: string, data: T, except?: string): void;
+    /**
+     * Get the list of client IDs currently in a project's broadcast room.
+     * Returns an empty array if no clients are in the room.
+     *
+     * @param sanitizedPath - The sanitized project path
+     * @returns Array of client IDs in the project room
+     */
+    getProjectMembers(sanitizedPath: string): string[];
+    /**
+     * Remove a client from a project's broadcast room.
+     *
+     * @param clientId - The Socket.IO client ID
+     * @param sanitizedPath - The sanitized project path
+     */
+    removeFromProjectRoom(clientId: string, sanitizedPath: string): void;
+}

package/dist/server/core/interfaces/routing/i-project-router.js

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

package/dist/server/core/interfaces/routing/index.d.ts

@@ -0,0 +1 @@
+export type { IProjectRouter } from './i-project-router.js';

package/dist/server/core/interfaces/routing/index.js

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

package/dist/server/core/interfaces/session/i-session-reader.d.ts

@@ -0,0 +1,13 @@
+import type { SessionInfo } from '../../../../agent/core/domain/session/session-metadata.js';
+/**
+ * Interface for reading session metadata.
+ * Minimal read-only interface for server-side session discovery.
+ */
+export interface ISessionReader {
+    /**
+     * List all session metadata files.
+     *
+     * @returns Array of session info sorted by lastUpdated (newest first)
+     */
+    listSessions(): Promise<SessionInfo[]>;
+}

package/dist/server/core/interfaces/session/i-session-reader.js

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

package/dist/server/core/interfaces/state/i-auth-state-store.d.ts

@@ -0,0 +1,68 @@
+import type { AuthToken } from '../../domain/entities/auth-token.js';
+/**
+ * Callback fired when auth state changes (login, refresh, logout).
+ *
+ * @param token - The new auth token, or undefined if logged out
+ */
+export type AuthChangedCallback = (token: AuthToken | undefined) => void;
+/**
+ * Callback fired when auth token has expired.
+ * Separate from AuthChanged because an expired token is still "present" —
+ * it signals the need for refresh, not that the user logged out.
+ */
+export type AuthExpiredCallback = (token: AuthToken) => void;
+/**
+ * Global auth state store shared across all projects.
+ *
+ * Polls the underlying token store to detect external changes
+ * (login, token refresh, logout) and notifies listeners via callbacks.
+ *
+ * The daemon is the centralized auth state owner and broadcasts
+ * auth:updated / auth:expired events to all connected clients.
+ *
+ * Consumed by brv-server.ts wiring.
+ */
+export interface IAuthStateStore {
+    /**
+     * Get the current cached auth token.
+     * Returns undefined if not loaded yet or user is logged out.
+     */
+    getToken(): AuthToken | undefined;
+    /**
+     * Force a reload from the underlying token store.
+     * Useful on daemon startup to populate the initial cache,
+     * or when a client signals that auth state has changed.
+     *
+     * @returns The loaded token, or undefined if not found
+     */
+    loadToken(): Promise<AuthToken | undefined>;
+    /**
+     * Register a callback for auth state changes.
+     * Fired when: login (new token), token refresh (changed token), logout (undefined).
+     *
+     * Only one callback supported — subsequent calls overwrite previous.
+     *
+     * @param callback - Function called with the new token (or undefined on logout)
+     */
+    onAuthChanged(callback: AuthChangedCallback): void;
+    /**
+     * Register a callback for token expiry.
+     * Fired when a token that was valid transitions to expired.
+     * Only fires once per expiry (not on every poll cycle).
+     *
+     * Only one callback supported — subsequent calls overwrite previous.
+     *
+     * @param callback - Function called with the expired token
+     */
+    onAuthExpired(callback: AuthExpiredCallback): void;
+    /**
+     * Start polling the token store for changes.
+     * Must be called after construction to begin monitoring.
+     */
+    startPolling(): void;
+    /**
+     * Stop polling and clean up resources.
+     * Must be called during shutdown.
+     */
+    stopPolling(): void;
+}

package/dist/server/core/interfaces/state/i-auth-state-store.js

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

package/dist/server/core/interfaces/state/i-project-state-loader.d.ts

@@ -0,0 +1,110 @@
+import type { SessionInfo } from '../../../../agent/core/domain/session/session-metadata.js';
+import type { BrvConfig } from '../../domain/entities/brv-config.js';
+/**
+ * Loaded state for a single project.
+ * Contains config (from .brv/config.json) and sessions (from XDG sessions dir).
+ */
+export type ProjectState = {
+    /** BrvConfig from <projectPath>/.brv/config.json, or undefined if not found/invalid */
+    readonly config: BrvConfig | undefined;
+    /** Timestamp when this state was loaded from disk */
+    readonly loadedAt: number;
+    /** Session list from XDG sessions dir, empty array if none */
+    readonly sessions: readonly SessionInfo[];
+};
+/**
+ * Error context for a failed project state load.
+ */
+export type ProjectStateError = {
+    /** The error that occurred */
+    readonly error: Error;
+    /** The project path that failed */
+    readonly projectPath: string;
+};
+/**
+ * Result type for project state loading.
+ * Uses discriminated union (ok field) instead of thrown errors
+ * to prevent server crash on individual project load failures.
+ */
+export type ProjectStateResult = {
+    error: ProjectStateError;
+    ok: false;
+} | {
+    ok: true;
+    state: ProjectState;
+};
+/**
+ * Lazy-loading per-project state provider with promise deduplication.
+ *
+ * When multiple concurrent requests arrive for the same project,
+ * only one disk read occurs. All callers receive the same result.
+ *
+ * Promise dedup flow:
+ *   10 concurrent requests for project-a state:
+ *   -> Request 1: starts loading, stores Promise in cache
+ *   -> Requests 2-10: find Promise in cache, await same Promise
+ *   -> All 10 get same result, only 1 disk read
+ *
+ * Consumed by brv-server.ts to provide project state to clients
+ * and agent child processes on demand.
+ */
+export interface IProjectStateLoader {
+    /**
+     * Get cached project config synchronously.
+     * Returns undefined if not yet loaded — does NOT trigger a disk read.
+     * Used by lazy providers (spaceIdProvider, teamIdProvider) that need
+     * synchronous access to already-loaded config values per HTTP request.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns The cached config or undefined if not loaded yet
+     */
+    getCachedProjectConfig(projectPath: string): BrvConfig | undefined;
+    /**
+     * Get project config from <projectPath>/.brv/config.json.
+     * Uses cached state if available, otherwise loads from disk.
+     * Concurrent calls for the same project share one load.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns The config or undefined if not found/invalid
+     */
+    getProjectConfig(projectPath: string): Promise<BrvConfig | undefined>;
+    /**
+     * Get project sessions from XDG sessions directory.
+     * Uses cached state if available, otherwise loads from disk.
+     * Concurrent calls for the same project share one load.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns Array of session info, empty if none
+     */
+    getProjectSessions(projectPath: string): Promise<readonly SessionInfo[]>;
+    /**
+     * Get the full project state (config + sessions).
+     * Uses cached state if available, otherwise loads from disk.
+     * Concurrent calls for the same project share one load.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns Result object: ok:true with state, or ok:false with error
+     */
+    getProjectState(projectPath: string): Promise<ProjectStateResult>;
+    /**
+     * Invalidate cached state for a project.
+     * Next call to getProject* will reload from disk.
+     * Use after config:updated or session:created events.
+     *
+     * @param projectPath - Absolute path to the project root
+     */
+    invalidate(projectPath: string): void;
+    /**
+     * Invalidate all cached project states.
+     * Use during shutdown or major state reset.
+     */
+    invalidateAll(): void;
+    /**
+     * Check if the cached config for a project needs invalidation.
+     * Compares file modification time with cache timestamp.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @returns True if cache should be invalidated (file was modified), false otherwise
+     */
+    shouldInvalidate(projectPath: string): Promise<boolean>;
+}

package/dist/server/core/interfaces/state/i-project-state-loader.js

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

package/dist/server/core/interfaces/storage/i-curate-log-store.d.ts

@@ -0,0 +1,20 @@
+import type { CurateLogEntry } from '../../domain/entities/curate-log-entry.js';
+export type CurateLogStatus = 'cancelled' | 'completed' | 'error' | 'processing';
+export interface ICurateLogStore {
+    /** Retrieve an entry by ID. Returns null if not found or if the file is corrupt. */
+    getById(id: string): Promise<CurateLogEntry | null>;
+    /** Generate the next monotonic log entry ID. */
+    getNextId(): Promise<string>;
+    /** List entries sorted newest-first. Filters are applied before limit. */
+    list(options?: {
+        /** Include only entries with startedAt >= after (ms timestamp). */
+        after?: number;
+        /** Include only entries with startedAt <= before (ms timestamp). */
+        before?: number;
+        limit?: number;
+        /** Include only entries matching these statuses. */
+        status?: CurateLogStatus[];
+    }): Promise<CurateLogEntry[]>;
+    /** Persist (create or overwrite) a log entry. Best-effort — callers should handle errors. */
+    save(entry: CurateLogEntry): Promise<void>;
+}

package/dist/server/core/interfaces/storage/i-curate-log-store.js

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

package/dist/server/core/interfaces/storage/i-global-config-store.d.ts

@@ -1,29 +1,15 @@
 import type { GlobalConfig } from '../../domain/entities/global-config.js';
 /**
  * Interface for storing and retrieving global ByteRover CLI configuration.
- * Implementations handle persistence of user-level config (e.g., ~/.config/brv/config.json).
+ * Implementations handle persistence of user-level config (e.g., <global-config-dir>/config.json).
  */
 export interface IGlobalConfigStore {
-    /**
-     * Gets the existing device ID or creates a new one if not present.
-     * This is the primary method for obtaining the device ID for tracking.
-     *
-     * @returns The device ID (existing or newly generated)
-     */
-    getOrCreateDeviceId: () => Promise<string>;
     /**
      * Reads the global configuration from the user's config directory.
      *
      * @returns The configuration if found and valid, undefined otherwise
      */
     read: () => Promise<GlobalConfig | undefined>;
-    /**
-     * Regenerates the device ID by creating a new UUID v4 and persisting it.
-     * Called when leaving authenticated state to break tracking continuity.
-     *
-     * @returns The newly generated device ID
-     */
-    regenerateDeviceId: () => Promise<string>;
     /**
      * Writes the global configuration to the user's config directory.
      * Creates the directory if it doesn't exist.

package/dist/server/core/interfaces/storage/i-mcp-config-writer.d.ts

@@ -1,4 +1,8 @@
-import type { McpServerConfig } from '../../../infra/connectors/mcp/mcp-connector-config.js';
+/**
+ * MCP server configuration that gets injected into agent config files.
+ * Uses Record to allow agent-specific fields (e.g., env, cwd, disabled).
+ */
+export type McpServerConfig = Record<string, unknown>;
 /**
  * Result of checking if MCP config exists.
  */

package/dist/server/core/interfaces/storage/i-project-config-store.d.ts

@@ -10,6 +10,12 @@ export interface IProjectConfigStore {
      * @returns True if .brv/config.json exists, false otherwise.
      */
     exists: (directory?: string) => Promise<boolean>;
+    /**
+     * Gets the last modification time of the configuration file.
+     * @param directory The project directory containing .brv folder (defaults to current working directory)
+     * @returns The modification timestamp in milliseconds, or undefined if file doesn't exist
+     */
+    getModifiedTime: (directory?: string) => Promise<number | undefined>;
     /**
      * Reads the configuration from the .brv directory.
      * @param directory The project directory containing .brv folder (defaults to current working directory)
@@ -20,7 +26,6 @@ export interface IProjectConfigStore {
      * Writes the configuration to the .brv directory.
      * @param config The configuration to write.
      * @param directory The project directory to create .brv folder in (defaults to current working directory)
-     * @returns
      */
     write: (config: BrvConfig, directory?: string) => Promise<void>;
 }

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

@@ -5,11 +5,20 @@
  * @returns Response data or void for fire-and-forget events
  */
 export type RequestHandler<TRequest = unknown, TResponse = unknown> = (data: TRequest, clientId: string) => Promise<TResponse> | TResponse;
+/**
+ * Metadata passed with connection events.
+ * Extracted from the transport handshake by the implementation.
+ */
+export type ConnectionMetadata = {
+    /** Client's working directory, sent during connection handshake */
+    readonly cwd?: string;
+};
 /**
  * Connection event handler.
  * @param clientId - Unique identifier of the connected/disconnected client
+ * @param metadata - Connection metadata (populated on connect, empty on disconnect)
  */
-export type ConnectionHandler = (clientId: string) => void;
+export type ConnectionHandler = (clientId: string, metadata: ConnectionMetadata) => void;
 /**
  * Interface for transport server operations.
  * Provides abstraction over real-time communication protocols (Socket.IO, WebSocket, etc.)
@@ -38,8 +47,9 @@ export interface ITransportServer {
      * @param room - The room identifier
      * @param event - The event name
      * @param data - The data to send
+     * @param except - Optional client ID to exclude from the broadcast
      */
-    broadcastTo: <T = unknown>(room: string, event: string, data: T) => void;
+    broadcastTo: <T = unknown>(room: string, event: string, data: T, except?: string) => void;
     /**
      * Returns the port the server is listening on.
      * Returns undefined if server is not started.

package/dist/server/core/interfaces/usecase/i-curate-log-use-case.d.ts

@@ -0,0 +1,12 @@
+import type { CurateLogStatus } from '../storage/i-curate-log-store.js';
+export interface ICurateLogUseCase {
+    run(options: {
+        after?: number;
+        before?: number;
+        detail?: boolean;
+        format?: 'json' | 'text';
+        id?: string;
+        limit?: number;
+        status?: CurateLogStatus[];
+    }): Promise<void>;
+}

package/dist/server/core/interfaces/usecase/i-curate-log-use-case.js

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

package/dist/server/infra/client/client-manager.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ClientManager — Tracks connected clients and project membership.
+ *
+ * Pure data structure with no external dependencies.
+ * TransportHandlers coordinates between ClientManager and ProjectRouter
+ * for Socket.IO room management.
+ *
+ * Key behaviors:
+ * - Tracks all connected clients (tui, mcp, agent)
+ * - Maintains a projectPath → clientIds index for fast lookup
+ * - Fires onProjectEmpty when last external client leaves a project
+ * - Agent clients don't count toward project membership (workers, not users)
+ * - Global-scope MCP clients start without a project and get associated later
+ */
+import type { ClientType } from '../../core/domain/client/client-info.js';
+import type { IClientManager, ProjectEmptyCallback } from '../../core/interfaces/client/i-client-manager.js';
+import { ClientInfo } from '../../core/domain/client/client-info.js';
+export declare class ClientManager implements IClientManager {
+    /** Callback for when a client registers */
+    private clientConnectedCallback?;
+    /** Callback for when a client unregisters */
+    private clientDisconnectedCallback?;
+    /** All registered clients: clientId → ClientInfo */
+    private readonly clients;
+    /** Project membership index: projectPath → Set of clientIds */
+    private readonly projectClients;
+    /** Callback for when a project has no external clients */
+    private projectEmptyCallback;
+    associateProject(clientId: string, projectPath: string): void;
+    getActiveProjects(): string[];
+    /**
+     * Returns all registered clients for debugging.
+     * Used by daemon:getState handler in brv-server.ts.
+     */
+    getAllClients(): ClientInfo[];
+    getClient(clientId: string): ClientInfo | undefined;
+    getClientsByProject(projectPath: string): ClientInfo[];
+    onClientConnected(callback: () => void): void;
+    onClientDisconnected(callback: () => void): void;
+    onProjectEmpty(callback: ProjectEmptyCallback): void;
+    register(clientId: string, type: ClientType, projectPath?: string): void;
+    setAgentName(clientId: string, agentName: string): void;
+    unregister(clientId: string): void;
+    private addToProjectIndex;
+    /**
+     * Check if a project has no remaining external clients.
+     * Fires the onProjectEmpty callback if so.
+     */
+    private checkProjectEmpty;
+    private removeFromProjectIndex;
+}

package/dist/server/infra/client/client-manager.js

@@ -0,0 +1,144 @@
+/**
+ * ClientManager — Tracks connected clients and project membership.
+ *
+ * Pure data structure with no external dependencies.
+ * TransportHandlers coordinates between ClientManager and ProjectRouter
+ * for Socket.IO room management.
+ *
+ * Key behaviors:
+ * - Tracks all connected clients (tui, mcp, agent)
+ * - Maintains a projectPath → clientIds index for fast lookup
+ * - Fires onProjectEmpty when last external client leaves a project
+ * - Agent clients don't count toward project membership (workers, not users)
+ * - Global-scope MCP clients start without a project and get associated later
+ */
+import { ClientInfo } from '../../core/domain/client/client-info.js';
+export class ClientManager {
+    /** Callback for when a client registers */
+    clientConnectedCallback;
+    /** Callback for when a client unregisters */
+    clientDisconnectedCallback;
+    /** All registered clients: clientId → ClientInfo */
+    clients = new Map();
+    /** Project membership index: projectPath → Set of clientIds */
+    projectClients = new Map();
+    /** Callback for when a project has no external clients */
+    projectEmptyCallback;
+    associateProject(clientId, projectPath) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return;
+        if (client.hasProject)
+            return;
+        client.associateProject(projectPath);
+        this.addToProjectIndex(clientId, projectPath);
+    }
+    getActiveProjects() {
+        return [...this.projectClients.keys()];
+    }
+    /**
+     * Returns all registered clients for debugging.
+     * Used by daemon:getState handler in brv-server.ts.
+     */
+    getAllClients() {
+        return [...this.clients.values()];
+    }
+    getClient(clientId) {
+        return this.clients.get(clientId);
+    }
+    getClientsByProject(projectPath) {
+        const clientIds = this.projectClients.get(projectPath);
+        if (!clientIds)
+            return [];
+        const clients = [];
+        for (const id of clientIds) {
+            const client = this.clients.get(id);
+            if (client)
+                clients.push(client);
+        }
+        return clients;
+    }
+    onClientConnected(callback) {
+        this.clientConnectedCallback = callback;
+    }
+    onClientDisconnected(callback) {
+        this.clientDisconnectedCallback = callback;
+    }
+    onProjectEmpty(callback) {
+        this.projectEmptyCallback = callback;
+    }
+    register(clientId, type, projectPath) {
+        // Cleanup old project index if clientId already registered (reconnect scenario)
+        const existing = this.clients.get(clientId);
+        if (existing?.projectPath) {
+            this.removeFromProjectIndex(clientId, existing.projectPath);
+        }
+        const client = new ClientInfo({
+            connectedAt: Date.now(),
+            id: clientId,
+            projectPath,
+            type,
+        });
+        this.clients.set(clientId, client);
+        if (projectPath) {
+            this.addToProjectIndex(clientId, projectPath);
+        }
+        // Only notify idle timeout policy for new clients, not re-registrations.
+        // Re-registrations replace the existing entry without unregister, so firing
+        // clientConnectedCallback again would desync IdleTimeoutPolicy.clientCount.
+        if (!existing) {
+            this.clientConnectedCallback?.();
+        }
+    }
+    setAgentName(clientId, agentName) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return;
+        client.setAgentName(agentName);
+    }
+    unregister(clientId) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return;
+        this.clients.delete(clientId);
+        if (client.projectPath) {
+            this.removeFromProjectIndex(clientId, client.projectPath);
+            // Check if project now has 0 external clients
+            if (client.isExternalClient) {
+                this.checkProjectEmpty(client.projectPath);
+            }
+        }
+        // Notify idle timeout policy
+        this.clientDisconnectedCallback?.();
+    }
+    addToProjectIndex(clientId, projectPath) {
+        let members = this.projectClients.get(projectPath);
+        if (!members) {
+            members = new Set();
+            this.projectClients.set(projectPath, members);
+        }
+        members.add(clientId);
+    }
+    /**
+     * Check if a project has no remaining external clients.
+     * Fires the onProjectEmpty callback if so.
+     */
+    checkProjectEmpty(projectPath) {
+        if (!this.projectEmptyCallback)
+            return;
+        const clients = this.getClientsByProject(projectPath);
+        const hasExternalClients = clients.some((c) => c.isExternalClient);
+        if (!hasExternalClients) {
+            this.projectEmptyCallback(projectPath);
+        }
+    }
+    removeFromProjectIndex(clientId, projectPath) {
+        const members = this.projectClients.get(projectPath);
+        if (!members)
+            return;
+        members.delete(clientId);
+        if (members.size === 0) {
+            this.projectClients.delete(projectPath);
+        }
+    }
+}