byterover-cli 3.1.0 → 3.3.0

package/dist/server/infra/process/connection-coordinator.js

@@ -154,6 +154,17 @@ export class ConnectionCoordinator {
             return { error: 'Client not registered', success: false };
         }
         if (client.hasProject) {
+            // Idempotent: same path → no-op
+            if (client.projectPath === data.projectPath) {
+                return { success: true };
+            }
+            // Reassociation: path changed (e.g. after worktree add/remove)
+            const oldPath = this.clientManager.updateProjectPath(clientId, data.projectPath);
+            transportLog(`Client ${clientId} reassociated: ${oldPath} → ${data.projectPath}`);
+            if (oldPath) {
+                this.removeFromProjectRoom(clientId, oldPath);
+            }
+            this.addToProjectRoom(clientId, data.projectPath);
             return { success: true };
         }
         this.clientManager.associateProject(clientId, data.projectPath);

package/dist/server/infra/process/feature-handlers.js

@@ -36,7 +36,7 @@ import { FileReviewBackupStore } from '../storage/file-review-backup-store.js';
 import { createTokenStore } from '../storage/token-store.js';
 import { HttpTeamService } from '../team/http-team-service.js';
 import { FsTemplateLoader } from '../template/fs-template-loader.js';
-import { AuthHandler, ConfigHandler, ConnectorsHandler, HubHandler, InitHandler, LocationsHandler, ModelHandler, ProviderHandler, PullHandler, PushHandler, ResetHandler, ReviewHandler, SpaceHandler, StatusHandler, VcHandler, } from '../transport/handlers/index.js';
+import { AuthHandler, ConfigHandler, ConnectorsHandler, HubHandler, InitHandler, LocationsHandler, ModelHandler, ProviderHandler, PullHandler, PushHandler, ResetHandler, ReviewHandler, SourceHandler, SpaceHandler, StatusHandler, VcHandler, WorktreeHandler, } from '../transport/handlers/index.js';
 import { HttpUserService } from '../user/http-user-service.js';
 import { FileVcGitConfigStore } from '../vc/file-vc-git-config-store.js';
 /**
@@ -211,5 +211,8 @@ export async function setupFeatureHandlers({ authStateStore, broadcastToProject,
         vcGitConfigStore: new FileVcGitConfigStore(),
         webAppUrl: envConfig.webAppUrl,
     }).setup();
+    // Worktree & source handlers
+    new WorktreeHandler({ resolveProjectPath, transport }).setup();
+    new SourceHandler({ resolveProjectPath, transport }).setup();
     log('Feature handlers registered');
 }

package/dist/server/infra/process/task-router.d.ts

@@ -124,6 +124,7 @@ export declare class TaskRouter {
      */
     private notifyHooksError;
     private registerLlmEvent;
+    private resolveTaskContext;
     /**
      * Generic handler for routing LLM events from Agent to clients.
      * Checks both active and recently completed tasks (within grace period).

package/dist/server/infra/process/task-router.js

@@ -16,8 +16,10 @@
  */
 import { AgentNotAvailableError, serializeTaskError } from '../../core/domain/errors/task-error.js';
 import { LlmEventNames, TransportLlmEventList, TransportTaskEventNames } from '../../core/domain/transport/schemas.js';
+import { isDescendantOf } from '../../utils/path-utils.js';
 import { transportLog } from '../../utils/process-logger.js';
 import { isValidTaskType } from '../../utils/type-guards.js';
+import { resolveProject } from '../project/resolve-project.js';
 import { broadcastToProjectRoom } from './broadcast-utils.js';
 /**
  * Grace period (in ms) to keep completed tasks in memory for late-arriving events.
@@ -245,11 +247,27 @@ export class TaskRouter {
             broadcastToProjectRoom(this.projectRegistry, this.projectRouter, projectPath, TransportTaskEventNames.ERROR, { error, taskId }, clientId);
             return { taskId };
         }
-        // ── Resolve projectPath & store task synchronously ────────────────────────
-        // Resolve projectPath: explicit field > client's registered projectPath > clientCwd.
-        // Client's registered projectPath is the walked-up project root (where .brv/ lives),
-        // while clientCwd is the raw working directory (may be a subdirectory).
-        const projectPath = data.projectPath ?? this.resolveClientProjectPath?.(clientId) ?? data.clientCwd;
+        // ── Resolve projectPath & worktreeRoot, store task synchronously ─────────
+        let projectPath;
+        let worktreeRoot;
+        try {
+            const taskContext = this.resolveTaskContext(data, clientId);
+            if (taskContext.error) {
+                const error = serializeTaskError(new Error(taskContext.error));
+                this.transport.sendTo(clientId, TransportTaskEventNames.ERROR, { error, taskId });
+                broadcastToProjectRoom(this.projectRegistry, this.projectRouter, taskContext.projectPath, TransportTaskEventNames.ERROR, { error, taskId }, clientId);
+                return { taskId };
+            }
+            projectPath = taskContext.projectPath;
+            worktreeRoot = taskContext.worktreeRoot;
+        }
+        catch (error_) {
+            const error = serializeTaskError(error_ instanceof Error ? error_ : new Error(String(error_)));
+            const fallbackProjectPath = data.projectPath ?? this.resolveClientProjectPath?.(clientId) ?? data.clientCwd;
+            this.transport.sendTo(clientId, TransportTaskEventNames.ERROR, { error, taskId });
+            broadcastToProjectRoom(this.projectRegistry, this.projectRouter, fallbackProjectPath, TransportTaskEventNames.ERROR, { error, taskId }, clientId);
+            return { taskId };
+        }
         transportLog(`Task accepted: ${taskId} (type=${data.type}, client=${clientId})`);
         this.tasks.set(taskId, {
             clientId,
@@ -261,6 +279,7 @@ export class TaskRouter {
             ...(projectPath ? { projectPath } : {}),
             taskId,
             type: data.type,
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         });
         // ── Send task:created synchronously (before any await) ────────────────────
         const createdPayload = {
@@ -294,6 +313,7 @@ export class TaskRouter {
             ...(projectPath ? { projectPath } : {}),
             taskId,
             type: data.type,
+            ...(worktreeRoot ? { worktreeRoot } : {}),
         };
         // eslint-disable-next-line no-void
         void this.agentPool
@@ -467,6 +487,41 @@ export class TaskRouter {
             this.routeLlmEvent(eventName, data);
         });
     }
+    resolveTaskContext(data, clientId) {
+        // When both projectPath and worktreeRoot are explicitly provided,
+        // skip the resolver entirely — a broken link under clientCwd must not
+        // reject an otherwise valid explicit payload.
+        if (data.projectPath && data.worktreeRoot) {
+            if (!isDescendantOf(data.worktreeRoot, data.projectPath)) {
+                return {
+                    error: `worktreeRoot "${data.worktreeRoot}" must be equal to or within projectPath "${data.projectPath}".`,
+                    projectPath: data.projectPath,
+                };
+            }
+            return { projectPath: data.projectPath, worktreeRoot: data.worktreeRoot };
+        }
+        // Resolve from clientCwd (fresh, workspace-link-aware) when needed.
+        let resolvedProjectPath;
+        let resolvedWorkspaceRoot;
+        if (data.clientCwd) {
+            const resolution = resolveProject({ cwd: data.clientCwd });
+            resolvedProjectPath = resolution?.projectRoot;
+            resolvedWorkspaceRoot = resolution?.worktreeRoot;
+        }
+        // Fallback order: explicit > fresh cwd resolution > stale registration > raw clientCwd.
+        // Fresh resolution is preferred over registered path because the registered path
+        // may be stale (e.g. in-flight reassociation after worktree add/remove).
+        const registeredProjectPath = this.resolveClientProjectPath?.(clientId);
+        const projectPath = data.projectPath ?? resolvedProjectPath ?? registeredProjectPath ?? data.clientCwd;
+        const worktreeRoot = data.worktreeRoot ?? resolvedWorkspaceRoot ?? projectPath;
+        if (projectPath && worktreeRoot && !isDescendantOf(worktreeRoot, projectPath)) {
+            return {
+                error: `worktreeRoot "${worktreeRoot}" must be equal to or within projectPath "${projectPath}".`,
+                projectPath,
+            };
+        }
+        return { projectPath, worktreeRoot };
+    }
     /**
      * Generic handler for routing LLM events from Agent to clients.
      * Checks both active and recently completed tasks (within grace period).

package/dist/server/infra/project/resolve-project.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Result of canonical project resolution.
+ */
+export interface ProjectResolution {
+    /** Directory containing .brv/config.json */
+    projectRoot: string;
+    /** How the project root was discovered */
+    source: 'direct' | 'flag' | 'linked';
+    /** Worktree root (equals projectRoot when direct, equals cwd when linked) */
+    worktreeRoot: string;
+}
+/**
+ * Error thrown when a .brv pointer file points to a project root that no longer has .brv/.
+ */
+export declare class BrokenWorktreePointerError extends Error {
+    readonly pointerDir: string;
+    readonly targetProjectRoot: string;
+    constructor(pointerDir: string, targetProjectRoot: string);
+}
+/**
+ * Error thrown when a .brv file (pointer) exists but contains malformed/invalid content.
+ */
+export declare class MalformedWorktreePointerError extends Error {
+    readonly pointerDir: string;
+    readonly reason: string;
+    constructor(pointerDir: string, reason: string);
+}
+export declare function hasBrvConfig(dir: string): boolean;
+/**
+ * Checks if a directory is a git root (.git directory or .git file for worktrees/submodules).
+ */
+export declare function isGitRoot(dir: string): boolean;
+/**
+ * Checks if .brv in the given directory is a FILE (pointer), not a directory.
+ */
+export declare function isWorktreePointer(dir: string): boolean;
+/**
+ * Reads and validates a .brv pointer file.
+ * @throws MalformedWorktreePointerError if the file has invalid content
+ */
+export declare function readWorktreePointer(dir: string): string;
+export interface ResolveProjectOptions {
+    /** Override cwd (defaults to process.cwd()) */
+    cwd?: string;
+    /** Explicit --project-root flag value */
+    projectRootFlag?: string;
+}
+/**
+ * Canonical project resolver — single source of truth for discovering
+ * which .brv/ project a given working directory belongs to.
+ *
+ * Git-style resolution: walks up from cwd to find the nearest `.brv`
+ * (file or directory), just like git walks up to find `.git`.
+ *
+ * 1. --project-root flag
+ * 2. Walk up from cwd looking for .brv:
+ *    a. .brv is a directory with config.json → source: 'direct'
+ *    b. .brv is a file (pointer) → follow to parent → source: 'linked'
+ * 3. null (no .brv found at cwd or any ancestor)
+ *
+ * The walk-up stops at the **first** .brv found — it does NOT skip past
+ * a .brv to find a "better" one higher up. This prevents accidental
+ * inheritance from stale .brv/ directories in ancestor directories.
+ *
+ * @throws BrokenWorktreePointerError if .brv file points to a missing project
+ * @throws MalformedWorktreePointerError if .brv file has invalid content
+ */
+export declare function resolveProject(options?: ResolveProjectOptions): null | ProjectResolution;
+export interface AddWorktreeResult {
+    backedUp?: boolean;
+    message: string;
+    success: boolean;
+}
+/**
+ * Register a worktree: writes .brv pointer file in the target directory
+ * and creates a registry entry in the parent's .brv/worktrees/.
+ *
+ * If the target already has a .brv/ directory (e.g., auto-init'd), it is
+ * backed up to .brv-backup/ and replaced with a pointer file.
+ */
+export declare function addWorktree(projectRoot: string, worktreePath: string, options?: {
+    force?: boolean;
+}): AddWorktreeResult;
+export interface RemoveWorktreeResult {
+    message: string;
+    success: boolean;
+}
+/**
+ * Remove a worktree: deletes the .brv pointer file and cleans up the registry entry.
+ * If a .brv-backup/ exists, restores it.
+ */
+export declare function removeWorktree(worktreePath: string): RemoveWorktreeResult;
+export interface WorktreeInfo {
+    name: string;
+    worktreePath: string;
+}
+/**
+ * List all registered worktrees for a project by scanning .brv/worktrees/ entries.
+ */
+export declare function listWorktrees(projectRoot: string): WorktreeInfo[];
+/**
+ * Walk up from startDir looking for the nearest directory with .brv/ DIRECTORY
+ * (not a .brv file). Used only by `brv worktree add` auto-detect mode.
+ * NOT used by the resolver.
+ */
+export declare function findParentProject(startDir: string): string | undefined;