byterover-cli 1.0.5 → 1.2.0

package/dist/core/domain/entities/agent.js

@@ -21,3 +21,81 @@ export const AGENT_VALUES = [
     'Windsurf',
     'Zed',
 ];
+/**
+ * Single source of truth for agent connector configuration.
+ * Defines which connectors each agent supports and which is the default.
+ */
+export const AGENT_CONNECTOR_CONFIG = {
+    Amp: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Augment Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Claude Code': {
+        default: 'hook',
+        supported: ['rules', 'hook', 'mcp'],
+    },
+    Cline: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Codex: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Cursor: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Gemini CLI': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Github Copilot': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Junie: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Kilo Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Kiro: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Qoder: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Qwen Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Roo Code': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    'Trae.ai': {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Warp: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Windsurf: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+    Zed: {
+        default: 'mcp',
+        supported: ['rules', 'mcp'],
+    },
+};

package/dist/core/domain/entities/connector-type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Array of all supported connector types.
+ * Each connector type represents a different method for integrating BRV with coding agents.
+ *
+ * - 'rules': Agent reads instructions from a rule file (e.g., CLAUDE.md)
+ * - 'hook': Instructions are injected on each prompt via agent hooks
+ * - 'mcp': Agent uses mcp tools to interact with brv
+ */
+export declare const CONNECTOR_TYPES: readonly ["rules", "hook", "mcp"];
+export type ConnectorType = (typeof CONNECTOR_TYPES)[number];

package/dist/core/domain/entities/connector-type.js

@@ -0,0 +1,9 @@
+/**
+ * Array of all supported connector types.
+ * Each connector type represents a different method for integrating BRV with coding agents.
+ *
+ * - 'rules': Agent reads instructions from a rule file (e.g., CLAUDE.md)
+ * - 'hook': Instructions are injected on each prompt via agent hooks
+ * - 'mcp': Agent uses mcp tools to interact with brv
+ */
+export const CONNECTOR_TYPES = ['rules', 'hook', 'mcp'];

package/dist/core/domain/entities/event.d.ts

@@ -1,7 +1,7 @@
 /**
  * Array of all supported Events.
  */
-export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "auth:token_invalid", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
+export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "auth:token_invalid", "space:init", "space:changed", "rule:generate", "connectors:configure", "connector:install", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
 export type EventName = (typeof EVENT_VALUES)[number];
 export interface PropertyDict {
     [key: string]: any;

package/dist/core/domain/entities/event.js

@@ -9,6 +9,8 @@ export const EVENT_VALUES = [
     'space:init',
     'space:changed',
     'rule:generate',
+    'connectors:configure',
+    'connector:install',
     'mem:status',
     'mem:curate',
     'mem:pull',

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

@@ -5,6 +5,7 @@
 export declare const TaskErrorCode: {
     readonly AGENT_DISCONNECTED: "ERR_AGENT_DISCONNECTED";
     readonly AGENT_NOT_AVAILABLE: "ERR_AGENT_NOT_AVAILABLE";
+    readonly AGENT_NOT_INITIALIZED: "ERR_AGENT_NOT_INITIALIZED";
     readonly LLM_ERROR: "ERR_LLM_ERROR";
     readonly LLM_RATE_LIMIT: "ERR_LLM_RATE_LIMIT";
     readonly NOT_AUTHENTICATED: "ERR_NOT_AUTHENTICATED";
@@ -50,6 +51,9 @@ export declare class AgentNotAvailableError extends TaskError {
 export declare class AgentDisconnectedError extends TaskError {
     constructor();
 }
+export declare class AgentNotInitializedError extends TaskError {
+    constructor(reason?: string);
+}
 export declare class ProcessorNotInitError extends TaskError {
     constructor();
 }

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

@@ -6,6 +6,7 @@ export const TaskErrorCode = {
     // Agent errors
     AGENT_DISCONNECTED: 'ERR_AGENT_DISCONNECTED',
     AGENT_NOT_AVAILABLE: 'ERR_AGENT_NOT_AVAILABLE',
+    AGENT_NOT_INITIALIZED: 'ERR_AGENT_NOT_INITIALIZED',
     // LLM errors
     LLM_ERROR: 'ERR_LLM_ERROR',
     LLM_RATE_LIMIT: 'ERR_LLM_RATE_LIMIT',
@@ -90,6 +91,12 @@ export class AgentDisconnectedError extends TaskError {
         this.name = 'AgentDisconnectedError';
     }
 }
+export class AgentNotInitializedError extends TaskError {
+    constructor(reason) {
+        super(reason ? `Agent not initialized: ${reason}` : 'Agent not initialized. Please complete login and setup first.', TaskErrorCode.AGENT_NOT_INITIALIZED);
+        this.name = 'AgentNotInitializedError';
+    }
+}
 export class ProcessorNotInitError extends TaskError {
     constructor() {
         super('TaskProcessor not initialized', TaskErrorCode.PROCESSOR_NOT_INIT);

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

@@ -1170,6 +1170,46 @@ export declare const AgentNewSessionResponseSchema: z.ZodObject<{
     error?: string | undefined;
     sessionId?: string | undefined;
 }>;
+/**
+ * Agent status event names.
+ */
+export declare const AgentStatusEventNames: {
+    /** Status changed broadcast */
+    readonly STATUS_CHANGED: "agent:status:changed";
+};
+/**
+ * Agent health status for monitoring.
+ * Used by Transport to check if CipherAgent is ready before forwarding tasks.
+ */
+export declare const AgentStatusSchema: z.ZodObject<{
+    /** Number of tasks currently processing */
+    activeTasks: z.ZodNumber;
+    /** Whether auth token is loaded and valid */
+    hasAuth: z.ZodBoolean;
+    /** Whether BrvConfig is loaded */
+    hasConfig: z.ZodBoolean;
+    /** Whether CipherAgent is initialized and ready */
+    isInitialized: z.ZodBoolean;
+    /** Last initialization error message */
+    lastError: z.ZodOptional<z.ZodString>;
+    /** Number of tasks waiting in queue */
+    queuedTasks: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    activeTasks: number;
+    hasAuth: boolean;
+    hasConfig: boolean;
+    isInitialized: boolean;
+    queuedTasks: number;
+    lastError?: string | undefined;
+}, {
+    activeTasks: number;
+    hasAuth: boolean;
+    hasConfig: boolean;
+    isInitialized: boolean;
+    queuedTasks: number;
+    lastError?: string | undefined;
+}>;
+export type AgentStatus = z.infer<typeof AgentStatusSchema>;
 export type TodoItem = z.infer<typeof TodoItemSchema>;
 export type ChunkPayload = z.infer<typeof ChunkPayloadSchema>;
 export type ResponsePayload = z.infer<typeof ResponsePayloadSchema>;

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

@@ -581,3 +581,31 @@ export const AgentNewSessionResponseSchema = z.object({
     /** Whether the new session was created successfully */
     success: z.boolean(),
 });
+// ============================================================================
+// Agent Status (health check)
+// ============================================================================
+/**
+ * Agent status event names.
+ */
+export const AgentStatusEventNames = {
+    /** Status changed broadcast */
+    STATUS_CHANGED: 'agent:status:changed',
+};
+/**
+ * Agent health status for monitoring.
+ * Used by Transport to check if CipherAgent is ready before forwarding tasks.
+ */
+export const AgentStatusSchema = z.object({
+    /** Number of tasks currently processing */
+    activeTasks: z.number().int().nonnegative(),
+    /** Whether auth token is loaded and valid */
+    hasAuth: z.boolean(),
+    /** Whether BrvConfig is loaded */
+    hasConfig: z.boolean(),
+    /** Whether CipherAgent is initialized and ready */
+    isInitialized: z.boolean(),
+    /** Last initialization error message */
+    lastError: z.string().optional(),
+    /** Number of tasks waiting in queue */
+    queuedTasks: z.number().int().nonnegative(),
+});

package/dist/core/interfaces/connectors/connector-types.d.ts

@@ -0,0 +1,70 @@
+import type { ConnectorType } from '../../domain/entities/connector-type.js';
+/**
+ * Instructions for manual MCP setup when automatic configuration is not possible.
+ */
+export type ManualInstallInstructions = {
+    /** The config content to copy (JSON or TOML formatted) */
+    configContent: string;
+    /** Guide URL or step-by-step instructions */
+    guide: string;
+};
+/**
+ * Result of a connector installation operation.
+ */
+export type ConnectorInstallResult = {
+    /** Whether the connector was already installed (no action taken) */
+    alreadyInstalled: boolean;
+    /** Path to the configuration/rule file */
+    configPath: string;
+    /** Instructions for manual setup (present when requiresManualSetup is true) */
+    manualInstructions?: ManualInstallInstructions;
+    /** Human-readable message describing the result */
+    message: string;
+    /** Whether this requires manual setup by the user */
+    requiresManualSetup?: boolean;
+    /** Whether the installation was successful */
+    success: boolean;
+};
+/**
+ * Result of a connector uninstallation operation.
+ */
+export type ConnectorUninstallResult = {
+    /** Path to the configuration/rule file */
+    configPath: string;
+    /** Human-readable message describing the result */
+    message: string;
+    /** Whether the uninstallation was successful */
+    success: boolean;
+    /** Whether the connector was installed before uninstall */
+    wasInstalled: boolean;
+};
+/**
+ * Status of a connector installation.
+ */
+export type ConnectorStatus = {
+    /** Whether the configuration/rule file exists */
+    configExists: boolean;
+    /** Path to the configuration/rule file */
+    configPath: string;
+    /** Error message if status check failed */
+    error?: string;
+    /** Whether the connector is currently installed */
+    installed: boolean;
+};
+/**
+ * Result of switching from one connector type to another.
+ */
+export type ConnectorSwitchResult = {
+    /** The connector type that was uninstalled (if any) */
+    fromType: ConnectorType | null;
+    /** Result of the installation operation */
+    installResult: ConnectorInstallResult;
+    /** Human-readable message describing the result */
+    message: string;
+    /** Whether the switch was successful */
+    success: boolean;
+    /** The connector type that was installed */
+    toType: ConnectorType;
+    /** Result of the uninstallation operation (if switching) */
+    uninstallResult?: ConnectorUninstallResult;
+};

package/dist/core/interfaces/connectors/i-connector-manager.d.ts

@@ -0,0 +1,72 @@
+import type { Agent } from '../../domain/entities/agent.js';
+import type { ConnectorType } from '../../domain/entities/connector-type.js';
+import type { ConnectorInstallResult, ConnectorStatus, ConnectorSwitchResult } from './connector-types.js';
+import type { IConnector } from './i-connector.js';
+/**
+ * Interface for managing connectors.
+ * Acts as a factory for creating connectors and orchestrates connector operations.
+ */
+export interface IConnectorManager {
+    /**
+     * Get all installed connectors across all agents.
+     * Iterates over all agents and checks which have connectors installed.
+     *
+     * @returns Map of agent to installed connector type (only includes agents with connectors)
+     */
+    getAllInstalledConnectors(): Promise<Map<Agent, ConnectorType>>;
+    /**
+     * Get a connector instance for the specified type.
+     *
+     * @param type - The connector type
+     * @returns The connector instance
+     * @throws Error if the connector type is not supported
+     */
+    getConnector(type: ConnectorType): IConnector;
+    /**
+     * Get the default connector type for the specified agent.
+     *
+     * @param agent - The agent to get the default connector for
+     * @returns The default connector type
+     */
+    getDefaultConnectorType(agent: Agent): ConnectorType;
+    /**
+     * Get the currently installed connector type for the specified agent.
+     * Checks all connector types and returns the first one that is installed.
+     *
+     * @param agent - The agent to check
+     * @returns The installed connector type, or null if none installed
+     */
+    getInstalledConnectorType(agent: Agent): Promise<ConnectorType | null>;
+    /**
+     * Get list of connector types that support the specified agent.
+     *
+     * @param agent - The agent to check
+     * @returns Array of supported connector types
+     */
+    getSupportedConnectorTypes(agent: Agent): ConnectorType[];
+    /**
+     * Install the default connector for the specified agent.
+     *
+     * @param agent - The agent to install for
+     * @returns Installation result
+     */
+    installDefault(agent: Agent): Promise<ConnectorInstallResult>;
+    /**
+     * Get the status of a specific connector type for an agent.
+     *
+     * @param type - The connector type
+     * @param agent - The agent to check
+     * @returns Connector status
+     */
+    status(type: ConnectorType, agent: Agent): Promise<ConnectorStatus>;
+    /**
+     * Switch from one connector type to another for the specified agent.
+     * Uninstalls the current connector (if any) and installs the new one.
+     * This ensures only one connector is active per agent.
+     *
+     * @param agent - The agent to switch connectors for
+     * @param toType - The connector type to switch to
+     * @returns Switch result with details of uninstall and install operations
+     */
+    switchConnector(agent: Agent, toType: ConnectorType): Promise<ConnectorSwitchResult>;
+}

package/dist/core/interfaces/connectors/i-connector-manager.js

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

package/dist/core/interfaces/connectors/i-connector.d.ts

@@ -0,0 +1,54 @@
+import type { Agent } from '../../domain/entities/agent.js';
+import type { ConnectorType } from '../../domain/entities/connector-type.js';
+import type { ConnectorInstallResult, ConnectorStatus, ConnectorUninstallResult } from './connector-types.js';
+/**
+ * Interface for a connector that integrates BRV with a coding agent.
+ * Each connector type (rules, hook, mcp) has its own implementation.
+ */
+export interface IConnector {
+    /**
+     * Get the path to the configuration/rule file for a specific agent.
+     *
+     * @param agent - The agent to get the config path for
+     * @returns The path relative to project root
+     */
+    getConfigPath(agent: Agent): string;
+    /**
+     * Get list of agents supported by this connector type.
+     *
+     * @returns Array of supported agent names
+     */
+    getSupportedAgents(): Agent[];
+    /**
+     * Install the connector for the specified agent.
+     * If already installed, returns alreadyInstalled: true.
+     *
+     * @param agent - The coding agent to install for
+     * @returns Installation result with success status and message
+     */
+    install(agent: Agent): Promise<ConnectorInstallResult>;
+    /**
+     * Check if this connector supports the specified agent.
+     *
+     * @param agent - The agent to check
+     * @returns True if the agent is supported
+     */
+    isSupported(agent: Agent): boolean;
+    /**
+     * Check the installation status for the specified agent.
+     *
+     * @param agent - The coding agent to check status for
+     * @returns Status including installed state and config file existence
+     */
+    status(agent: Agent): Promise<ConnectorStatus>;
+    /** The type of this connector */
+    readonly type: ConnectorType;
+    /**
+     * Uninstall the connector for the specified agent.
+     * Only removes BRV content, preserves user's other configurations.
+     *
+     * @param agent - The coding agent to uninstall from
+     * @returns Uninstallation result with success status and message
+     */
+    uninstall(agent: Agent): Promise<ConnectorUninstallResult>;
+}

package/dist/core/interfaces/connectors/i-connector.js

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

package/dist/core/interfaces/i-file-service.d.ts

@@ -15,6 +15,13 @@ export interface IFileService {
      * @returns A promise that resolves with the path to the backup file.
      */
     createBackup: (filePath: string) => Promise<string>;
+    /**
+     * Deletes a file at the specified path.
+     *
+     * @param filePath The path to the file to delete.
+     * @returns A promise that resolves when the file has been deleted.
+     */
+    delete: (filePath: string) => Promise<void>;
     /**
      * Checks if a file exists at the specified path.
      *

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

@@ -0,0 +1,40 @@
+import type { McpServerConfig } from '../../infra/connectors/mcp/mcp-connector-config.js';
+/**
+ * Result of checking if MCP config exists.
+ */
+export type McpConfigExistsResult = {
+    /** Whether the config file exists */
+    fileExists: boolean;
+    /** Whether the BRV MCP server entry exists in the config */
+    serverExists: boolean;
+};
+/**
+ * Interface for writing MCP server configurations to agent config files.
+ * Different implementations handle different file formats (JSON, TOML, etc.).
+ */
+export interface IMcpConfigWriter {
+    /**
+     * Check if the config file and BRV server entry exist.
+     *
+     * @param filePath - Absolute path to the config file
+     * @returns Object indicating file and server existence
+     */
+    exists(filePath: string): Promise<McpConfigExistsResult>;
+    /**
+     * Remove the BRV MCP server entry from the config file.
+     * Does not delete the file, only removes the server entry.
+     *
+     * @param filePath - Absolute path to the config file
+     * @returns True if the server was removed, false if it didn't exist
+     */
+    remove(filePath: string): Promise<boolean>;
+    /**
+     * Write the MCP server configuration to the config file.
+     * Creates the file if it doesn't exist.
+     * Preserves existing configuration.
+     *
+     * @param filePath - Absolute path to the config file
+     * @param serverConfig - The MCP server configuration to write
+     */
+    write(filePath: string, serverConfig: McpServerConfig): Promise<void>;
+}

package/dist/core/interfaces/i-mcp-config-writer.js

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

package/dist/core/interfaces/i-rule-template-service.d.ts

@@ -1,13 +1,15 @@
 import { Agent } from '../domain/entities/agent.js';
+import { ConnectorType } from '../domain/entities/connector-type.js';
 /**
  * Interface for rule template service operations.
  */
 export interface IRuleTemplateService {
     /**
-     * Generates rule content based on the provided agent.
+     * Generates rule content based on the provided agent and connector type.
      *
      * @param agent The agent for which to generate the rule content.
+     * @param type The connector type (rules or mcp). Defaults to 'rules'.
      * @returns Promise resolving to the generated rule content.
      */
-    generateRuleContent: (agent: Agent) => Promise<string>;
+    generateRuleContent: (agent: Agent, type: ConnectorType) => Promise<string>;
 }

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

@@ -54,6 +54,13 @@ export interface ITransportClient {
      * Returns the current connection state.
      */
     getState: () => ConnectionState;
+    /**
+     * Checks if the socket is actually connected and responsive.
+     * Verifies bidirectional communication by sending a ping and waiting for response.
+     * @param timeoutMs - Timeout in milliseconds (default: 2000)
+     * @returns true if socket is connected and responsive, false otherwise
+     */
+    isConnected: (timeoutMs?: number) => Promise<boolean>;
     /**
      * Joins a room for targeted broadcasts.
      * @param room - The room identifier to join

package/dist/core/interfaces/usecase/i-connectors-use-case.d.ts

@@ -0,0 +1,3 @@
+export interface IConnectorsUseCase {
+    run(): Promise<void>;
+}

package/dist/core/interfaces/usecase/i-connectors-use-case.js

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

package/dist/hooks/init/update-notifier.d.ts

@@ -27,6 +27,7 @@ export type UpdateNotifierDeps = {
     execSyncFn: (command: string, options: {
         stdio: 'inherit';
     }) => void;
+    exitFn: (code: number) => never;
     isTTY: boolean;
     log: (message: string) => void;
     notifier: NarrowedUpdateNotifier;

package/dist/hooks/init/update-notifier.js

@@ -9,11 +9,15 @@ export const UPDATE_CHECK_INTERVAL_MS = 1000 * 60 * 60 * 24;
  * Core update notification logic, extracted for testability
  */
 export async function handleUpdateNotification(deps) {
-    const { confirmPrompt, execSyncFn, isTTY, log, notifier } = deps;
+    const { confirmPrompt, execSyncFn, exitFn, isTTY, log, notifier } = deps;
     if (!notifier.update || !isTTY) {
         return;
     }
     const { current, latest } = notifier.update;
+    // Skip if already on latest version (handles stale cache after update)
+    if (current === latest) {
+        return;
+    }
     const shouldUpdate = await confirmPrompt({
         default: true,
         message: `Update available: ${current} → ${latest}. Would you like to update now?`,
@@ -22,7 +26,11 @@ export async function handleUpdateNotification(deps) {
         log('Updating byterover-cli...');
         try {
             execSyncFn('npm update -g byterover-cli', { stdio: 'inherit' });
+            log('');
             log(`✓ Successfully updated to ${latest}`);
+            log('');
+            log(`The update will take effect on next launch. Run 'brv' when ready.`);
+            exitFn(0);
         }
         catch {
             log('⚠️  Automatic update failed. Please run manually: npm update -g byterover-cli');
@@ -35,6 +43,7 @@ const hook = async function () {
     await handleUpdateNotification({
         confirmPrompt: confirm,
         execSyncFn: execSync,
+        exitFn: process.exit,
         isTTY: process.stdout.isTTY ?? false,
         log: this.log.bind(this),
         notifier,

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

@@ -158,6 +158,14 @@ export declare class CipherAgent extends BaseAgent implements ICipherAgent {
      * @returns AsyncIterator that yields StreamingEvent objects
      */
     stream(input: string, options?: StreamOptions): Promise<AsyncIterableIterator<StreamingEvent>>;
+    /**
+     * Switch the default session to a different session ID.
+     * The session must already exist (created via createSession).
+     *
+     * @param sessionId - The session ID to switch to
+     * @throws Error if session does not exist
+     */
+    switchDefaultSession(sessionId: string): void;
     private getHistoryStorageInternal;
     private getSessionIdInternal;
     private getSessionManagerInternal;

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

@@ -520,6 +520,22 @@ export class CipherAgent extends BaseAgent {
         };
         return iterator;
     }
+    /**
+     * Switch the default session to a different session ID.
+     * The session must already exist (created via createSession).
+     *
+     * @param sessionId - The session ID to switch to
+     * @throws Error if session does not exist
+     */
+    switchDefaultSession(sessionId) {
+        this.ensureStarted();
+        // Verify the session exists
+        const session = this.getSessionManagerInternal().getSession(sessionId);
+        if (!session) {
+            throw new Error(`Session ${sessionId} does not exist. Create it first with createSession().`);
+        }
+        this._sessionId = sessionId;
+    }
     // === Private Helpers (alphabetical order) ===
     getHistoryStorageInternal() {
         const storage = this.services?.historyStorage;