byterover-cli 3.1.0 → 3.3.0

package/dist/server/infra/project/resolve-project.js

@@ -0,0 +1,473 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { BRV_DIR, PROJECT_CONFIG_FILE, WORKTREE_LINK_METADATA, WORKTREES_DIR } from '../../constants.js';
+import { WorktreeLinkMetadataSchema, WorktreePointerSchema } from '../../core/domain/project/worktrees-schema.js';
+import { resolvePath } from '../../utils/path-utils.js';
+// ============================================================================
+// Errors
+// ============================================================================
+/**
+ * Error thrown when a .brv pointer file points to a project root that no longer has .brv/.
+ */
+export class BrokenWorktreePointerError extends Error {
+    pointerDir;
+    targetProjectRoot;
+    constructor(pointerDir, targetProjectRoot) {
+        super(`Worktree pointer broken: "${targetProjectRoot}" no longer has ${BRV_DIR}/${PROJECT_CONFIG_FILE}. ` +
+            `Run 'brv worktree remove' to remove the pointer.`);
+        this.pointerDir = pointerDir;
+        this.targetProjectRoot = targetProjectRoot;
+        this.name = 'BrokenWorktreePointerError';
+    }
+}
+/**
+ * Error thrown when a .brv file (pointer) exists but contains malformed/invalid content.
+ */
+export class MalformedWorktreePointerError extends Error {
+    pointerDir;
+    reason;
+    constructor(pointerDir, reason) {
+        super(`Worktree pointer in "${pointerDir}" is malformed: ${reason}. ` +
+            `Fix the .brv file or run 'brv worktree remove' to remove it.`);
+        this.pointerDir = pointerDir;
+        this.reason = reason;
+        this.name = 'MalformedWorktreePointerError';
+    }
+}
+// ============================================================================
+// Core helpers
+// ============================================================================
+export function hasBrvConfig(dir) {
+    return existsSync(join(dir, BRV_DIR, PROJECT_CONFIG_FILE));
+}
+/**
+ * Checks if a directory is a git root (.git directory or .git file for worktrees/submodules).
+ */
+export function isGitRoot(dir) {
+    const gitPath = join(dir, '.git');
+    try {
+        const stat = lstatSync(gitPath);
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks if .brv in the given directory is a FILE (pointer), not a directory.
+ */
+export function isWorktreePointer(dir) {
+    const brvPath = join(dir, BRV_DIR);
+    try {
+        return lstatSync(brvPath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads and validates a .brv pointer file.
+ * @throws MalformedWorktreePointerError if the file has invalid content
+ */
+export function readWorktreePointer(dir) {
+    const brvPath = join(dir, BRV_DIR);
+    let raw;
+    try {
+        raw = readFileSync(brvPath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MalformedWorktreePointerError(dir, `cannot read .brv file: ${message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new MalformedWorktreePointerError(dir, 'invalid JSON');
+    }
+    const result = WorktreePointerSchema.safeParse(json);
+    if (!result.success) {
+        throw new MalformedWorktreePointerError(dir, 'missing or invalid "projectRoot" field');
+    }
+    return result.data.projectRoot;
+}
+/**
+ * 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 function resolveProject(options) {
+    const cwd = options?.cwd ?? process.cwd();
+    // Step 1: Explicit --project-root flag — fail loudly if invalid
+    if (options?.projectRootFlag) {
+        const flagRoot = resolve(options.projectRootFlag);
+        if (!hasBrvConfig(flagRoot)) {
+            throw new Error(`--project-root "${flagRoot}" is not a ByteRover project (no ${BRV_DIR}/${PROJECT_CONFIG_FILE}).`);
+        }
+        const canonical = resolvePath(flagRoot);
+        return {
+            projectRoot: canonical,
+            source: 'flag',
+            worktreeRoot: canonical,
+        };
+    }
+    let startDir;
+    try {
+        startDir = resolvePath(cwd);
+    }
+    catch {
+        return null;
+    }
+    // Step 2: Walk up from cwd looking for .brv (file or directory)
+    let current = startDir;
+    const root = resolve('/');
+    while (current !== root) {
+        const result = resolveAtDir(current);
+        if (result !== undefined) {
+            return result;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // Also check root
+    if (current !== startDir) {
+        const result = resolveAtDir(current);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    // Step 3: No .brv found anywhere
+    return null;
+}
+/**
+ * Check a single directory for .brv and resolve it.
+ * Returns ProjectResolution, null (invalid .brv), or undefined (no .brv here, keep walking).
+ */
+function resolveAtDir(dir) {
+    const brvPath = join(dir, BRV_DIR);
+    let stat;
+    try {
+        stat = lstatSync(brvPath);
+    }
+    catch {
+        // .brv doesn't exist here — keep walking
+        return undefined;
+    }
+    // .brv is a directory → real project
+    if (stat.isDirectory()) {
+        if (existsSync(join(brvPath, PROJECT_CONFIG_FILE))) {
+            return {
+                projectRoot: dir,
+                source: 'direct',
+                worktreeRoot: dir,
+            };
+        }
+        // .brv/ exists but no config.json — stop here (don't walk past it)
+        return null;
+    }
+    // .brv is a file → pointer to parent project
+    if (stat.isFile()) {
+        const targetRoot = readWorktreePointer(dir);
+        let canonicalTarget;
+        try {
+            canonicalTarget = resolvePath(targetRoot);
+        }
+        catch {
+            throw new BrokenWorktreePointerError(dir, targetRoot);
+        }
+        if (!hasBrvConfig(canonicalTarget)) {
+            throw new BrokenWorktreePointerError(dir, canonicalTarget);
+        }
+        return {
+            projectRoot: canonicalTarget,
+            source: 'linked',
+            worktreeRoot: dir,
+        };
+    }
+    // .brv is something else — stop here
+    return null;
+}
+// ============================================================================
+// Worktree CRUD operations
+// ============================================================================
+/**
+ * Sanitize a path into a safe directory name for the worktrees registry.
+ * Replaces path separators and special chars with dashes, then appends
+ * a numeric suffix if the name already exists in .brv/worktrees/.
+ */
+function sanitizeWorktreeName(worktreePath, projectRoot) {
+    // Try to use relative path for readability, fall back to basename
+    const name = worktreePath.startsWith(projectRoot + sep) || worktreePath.startsWith(projectRoot + '/') ? worktreePath.slice(projectRoot.length + 1) : basename(worktreePath);
+    const baseName = name.replaceAll(/[/\\]/g, '-').replaceAll(/[^a-zA-Z0-9._-]/g, '-');
+    // Check for collisions in existing registry entries
+    const worktreesDir = join(projectRoot, BRV_DIR, WORKTREES_DIR);
+    if (!existsSync(worktreesDir)) {
+        return baseName;
+    }
+    const existing = new Set();
+    try {
+        for (const entry of readdirSync(worktreesDir)) {
+            existing.add(entry);
+        }
+    }
+    catch {
+        return baseName;
+    }
+    if (!existing.has(baseName)) {
+        return baseName;
+    }
+    let counter = 2;
+    while (existing.has(`${baseName}-${counter}`)) {
+        counter++;
+    }
+    return `${baseName}-${counter}`;
+}
+/**
+ * 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 function addWorktree(projectRoot, worktreePath, options) {
+    // Validate parent has .brv/config.json
+    if (!hasBrvConfig(projectRoot)) {
+        return { message: `"${projectRoot}" is not a ByteRover project (no .brv/config.json).`, success: false };
+    }
+    // Validate target directory exists
+    if (!existsSync(worktreePath)) {
+        return { message: `Target directory does not exist: ${worktreePath}`, success: false };
+    }
+    // Cannot add self
+    if (worktreePath === projectRoot) {
+        return { message: 'Cannot add the project root as its own worktree.', success: false };
+    }
+    const targetBrvPath = join(worktreePath, BRV_DIR);
+    let backedUp = false;
+    try {
+        const stat = lstatSync(targetBrvPath);
+        if (stat.isFile()) {
+            // Already a pointer — check if it points to the same parent
+            try {
+                const existingTarget = readWorktreePointer(worktreePath);
+                const canonicalExisting = resolvePath(existingTarget);
+                const canonicalProject = resolvePath(projectRoot);
+                if (canonicalExisting === canonicalProject) {
+                    return { message: `Already registered as worktree of "${projectRoot}".`, success: true };
+                }
+                return {
+                    message: `"${worktreePath}" is already a worktree of "${canonicalExisting}". Remove it first with 'brv worktree remove'.`,
+                    success: false,
+                };
+            }
+            catch {
+                // Malformed pointer — overwrite below
+            }
+        }
+        if (stat.isDirectory()) {
+            // Existing .brv/ directory — back up and replace
+            if (!options?.force) {
+                return {
+                    message: `"${worktreePath}" has its own .brv/ project. Use --force to replace it with a worktree pointer. ` +
+                        'The existing .brv/ will be moved to .brv-backup/.',
+                    success: false,
+                };
+            }
+            const backupPath = join(worktreePath, '.brv-backup');
+            if (existsSync(backupPath)) {
+                rmSync(backupPath, { force: true, recursive: true });
+            }
+            renameSync(targetBrvPath, backupPath);
+            backedUp = true;
+        }
+    }
+    catch {
+        // .brv doesn't exist — proceed
+    }
+    // Write .brv pointer file
+    const pointerContent = JSON.stringify({ projectRoot: resolvePath(projectRoot) }, null, 2) + '\n';
+    writeFileSync(targetBrvPath, pointerContent, 'utf8');
+    // Create registry entry in parent
+    const name = sanitizeWorktreeName(worktreePath, projectRoot);
+    const worktreeDir = join(projectRoot, BRV_DIR, WORKTREES_DIR, name);
+    mkdirSync(worktreeDir, { recursive: true });
+    const metadata = {
+        addedAt: new Date().toISOString(),
+        worktreePath: resolvePath(worktreePath),
+    };
+    writeFileSync(join(worktreeDir, WORKTREE_LINK_METADATA), JSON.stringify(metadata, null, 2) + '\n', 'utf8');
+    const msg = backedUp
+        ? `Added worktree "${worktreePath}" (existing .brv/ backed up to .brv-backup/).`
+        : `Added worktree "${worktreePath}".`;
+    return { backedUp, message: msg, success: true };
+}
+/**
+ * Remove a worktree: deletes the .brv pointer file and cleans up the registry entry.
+ * If a .brv-backup/ exists, restores it.
+ */
+export function removeWorktree(worktreePath) {
+    const brvPath = join(worktreePath, BRV_DIR);
+    // Verify .brv is a pointer file
+    try {
+        const stat = lstatSync(brvPath);
+        if (!stat.isFile()) {
+            return { message: `"${worktreePath}" is not a worktree (has .brv/ directory, not pointer file).`, success: false };
+        }
+    }
+    catch {
+        return { message: `No .brv found in "${worktreePath}".`, success: false };
+    }
+    // Read pointer to find parent
+    let projectRoot;
+    try {
+        projectRoot = readWorktreePointer(worktreePath);
+        projectRoot = resolvePath(projectRoot);
+    }
+    catch {
+        // Can't read pointer — just delete the file
+        unlinkSync(brvPath);
+        return { message: `Removed worktree pointer (parent project unknown).`, success: true };
+    }
+    // Delete pointer file
+    unlinkSync(brvPath);
+    // Restore backup if exists
+    const backupPath = join(worktreePath, '.brv-backup');
+    if (existsSync(backupPath)) {
+        renameSync(backupPath, brvPath);
+    }
+    // Clean up registry entry in parent
+    const worktreesDir = join(projectRoot, BRV_DIR, WORKTREES_DIR);
+    if (existsSync(worktreesDir)) {
+        try {
+            const entries = readdirSync(worktreesDir, { withFileTypes: true });
+            const canonicalWorktree = resolvePath(worktreePath);
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const metaPath = join(worktreesDir, entry.name, WORKTREE_LINK_METADATA);
+                if (!existsSync(metaPath))
+                    continue;
+                try {
+                    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+                    const parsed = WorktreeLinkMetadataSchema.safeParse(meta);
+                    if (parsed.success && resolvePath(parsed.data.worktreePath) === canonicalWorktree) {
+                        rmSync(join(worktreesDir, entry.name), { force: true, recursive: true });
+                        break;
+                    }
+                }
+                catch {
+                    // Malformed metadata — skip
+                }
+            }
+        }
+        catch {
+            // Registry cleanup is best-effort
+        }
+    }
+    return { message: `Removed worktree "${worktreePath}".`, success: true };
+}
+/**
+ * List all registered worktrees for a project by scanning .brv/worktrees/ entries.
+ */
+export function listWorktrees(projectRoot) {
+    const worktreesDir = join(projectRoot, BRV_DIR, WORKTREES_DIR);
+    if (!existsSync(worktreesDir)) {
+        return [];
+    }
+    const result = [];
+    try {
+        const entries = readdirSync(worktreesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const metaPath = join(worktreesDir, entry.name, WORKTREE_LINK_METADATA);
+            if (!existsSync(metaPath))
+                continue;
+            try {
+                const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+                const parsed = WorktreeLinkMetadataSchema.safeParse(meta);
+                if (parsed.success) {
+                    result.push({
+                        name: entry.name,
+                        worktreePath: parsed.data.worktreePath,
+                    });
+                }
+            }
+            catch {
+                // Skip malformed entries
+            }
+        }
+    }
+    catch {
+        // Directory unreadable
+    }
+    return result;
+}
+/**
+ * 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 function findParentProject(startDir) {
+    let current;
+    try {
+        current = resolvePath(startDir);
+    }
+    catch {
+        return undefined;
+    }
+    // Skip cwd itself — we're looking for a PARENT
+    current = dirname(current);
+    const root = resolve('/');
+    while (current !== root) {
+        const brvPath = join(current, BRV_DIR);
+        try {
+            const stat = lstatSync(brvPath);
+            if (stat.isDirectory() && existsSync(join(brvPath, PROJECT_CONFIG_FILE))) {
+                return current;
+            }
+        }
+        catch {
+            // .brv doesn't exist here
+        }
+        if (isGitRoot(current)) {
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // Check the boundary directory itself
+    if (current !== startDir) {
+        const brvPath = join(current, BRV_DIR);
+        try {
+            const stat = lstatSync(brvPath);
+            if (stat.isDirectory() && existsSync(join(brvPath, PROJECT_CONFIG_FILE))) {
+                return current;
+            }
+        }
+        catch {
+            // Not found
+        }
+    }
+    return undefined;
+}

package/dist/server/infra/transport/handlers/index.d.ts

@@ -24,9 +24,13 @@ export { ResetHandler } from './reset-handler.js';
 export type { ResetHandlerDeps } from './reset-handler.js';
 export { ReviewHandler } from './review-handler.js';
 export type { ReviewHandlerDeps } from './review-handler.js';
+export { SourceHandler } from './source-handler.js';
+export type { SourceHandlerDeps } from './source-handler.js';
 export { SpaceHandler } from './space-handler.js';
 export type { SpaceHandlerDeps } from './space-handler.js';
 export { StatusHandler } from './status-handler.js';
 export type { StatusHandlerDeps } from './status-handler.js';
 export { VcHandler } from './vc-handler.js';
 export type { IVcHandlerDeps } from './vc-handler.js';
+export { WorktreeHandler } from './worktree-handler.js';
+export type { WorktreeHandlerDeps } from './worktree-handler.js';

package/dist/server/infra/transport/handlers/index.js

@@ -11,6 +11,8 @@ export { PullHandler } from './pull-handler.js';
 export { PushHandler } from './push-handler.js';
 export { ResetHandler } from './reset-handler.js';
 export { ReviewHandler } from './review-handler.js';
+export { SourceHandler } from './source-handler.js';
 export { SpaceHandler } from './space-handler.js';
 export { StatusHandler } from './status-handler.js';
 export { VcHandler } from './vc-handler.js';
+export { WorktreeHandler } from './worktree-handler.js';

package/dist/server/infra/transport/handlers/pull-handler.js

@@ -1,5 +1,5 @@
 import { PullEvents, } from '../../../../shared/transport/events/pull-events.js';
-import { LocalChangesExistError, NotAuthenticatedError, ProjectNotInitError, SpaceNotConfiguredError, } from '../../../core/domain/errors/task-error.js';
+import { LegacySyncUnavailableError, LocalChangesExistError, NotAuthenticatedError, ProjectNotInitError, } from '../../../core/domain/errors/task-error.js';
 import { guardAgainstGitVc, hasAnyChanges, resolveRequiredProjectPath, } from './handler-types.js';
 /**
  * Handles pull:* events.
@@ -42,7 +42,7 @@ export class PullHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         // Check for local changes that would be overwritten
         const changes = await this.contextTreeSnapshotService.getChanges(projectPath);
@@ -79,7 +79,7 @@ export class PullHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         const changes = await this.contextTreeSnapshotService.getChanges(projectPath);
         const hasLocalChanges = hasAnyChanges(changes);

package/dist/server/infra/transport/handlers/push-handler.js

@@ -1,6 +1,6 @@
 import { join, relative } from 'node:path';
 import { PushEvents, } from '../../../../shared/transport/events/push-events.js';
-import { NotAuthenticatedError, ProjectNotInitError, SpaceNotConfiguredError, } from '../../../core/domain/errors/task-error.js';
+import { LegacySyncUnavailableError, NotAuthenticatedError, ProjectNotInitError, } from '../../../core/domain/errors/task-error.js';
 import { mapToPushContexts } from '../../cogit/context-tree-to-push-context-mapper.js';
 import { guardAgainstGitVc, resolveRequiredProjectPath, } from './handler-types.js';
 /** Path prefix of the context tree relative to the project root. */
@@ -88,7 +88,7 @@ export class PushHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         this.broadcastToProject(projectPath, PushEvents.PROGRESS, { message: 'Reading context files...', step: 'reading' });
         const changes = await this.contextTreeSnapshotService.getChanges(projectPath);
@@ -163,7 +163,7 @@ export class PushHandler {
             throw new ProjectNotInitError();
         }
         if (!config.teamId || !config.spaceId) {
-            throw new SpaceNotConfiguredError();
+            throw new LegacySyncUnavailableError();
         }
         const hasSnapshot = await this.contextTreeSnapshotService.hasSnapshot(projectPath);
         if (!hasSnapshot) {

package/dist/server/infra/transport/handlers/source-handler.d.ts

@@ -0,0 +1,12 @@
+import type { ITransportServer } from '../../../core/interfaces/transport/i-transport-server.js';
+import { type ProjectPathResolver } from './handler-types.js';
+export interface SourceHandlerDeps {
+    resolveProjectPath: ProjectPathResolver;
+    transport: ITransportServer;
+}
+export declare class SourceHandler {
+    private readonly resolveProjectPath;
+    private readonly transport;
+    constructor(deps: SourceHandlerDeps);
+    setup(): void;
+}

package/dist/server/infra/transport/handlers/source-handler.js

@@ -0,0 +1,37 @@
+import { SourceEvents, } from '../../../../shared/transport/events/source-events.js';
+import { addSource, listSourceStatuses, removeSource } from '../../../core/domain/source/source-operations.js';
+import { resolveRequiredProjectPath } from './handler-types.js';
+export class SourceHandler {
+    resolveProjectPath;
+    transport;
+    constructor(deps) {
+        this.resolveProjectPath = deps.resolveProjectPath;
+        this.transport = deps.transport;
+    }
+    setup() {
+        this.transport.onRequest(SourceEvents.ADD, async (data, clientId) => {
+            const projectPath = resolveRequiredProjectPath(this.resolveProjectPath, clientId);
+            const result = addSource(projectPath, data.targetPath, data.alias);
+            return {
+                message: result.message,
+                success: result.success,
+            };
+        });
+        this.transport.onRequest(SourceEvents.REMOVE, async (data, clientId) => {
+            const projectPath = resolveRequiredProjectPath(this.resolveProjectPath, clientId);
+            const result = removeSource(projectPath, data.aliasOrPath);
+            return {
+                message: result.message,
+                success: result.success,
+            };
+        });
+        this.transport.onRequest(SourceEvents.LIST, async (_data, clientId) => {
+            const projectPath = resolveRequiredProjectPath(this.resolveProjectPath, clientId);
+            const result = listSourceStatuses(projectPath);
+            return {
+                error: result.error,
+                statuses: result.statuses,
+            };
+        });
+    }
+}