byterover-cli 3.1.0 → 3.2.0

package/dist/oclif/commands/worktree/list.js

@@ -0,0 +1,28 @@
+import { Command } from '@oclif/core';
+import { WorktreeEvents } from '../../../shared/transport/events/worktree-events.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+export default class WorktreeList extends Command {
+    static description = 'Show the current worktree link and list all registered worktrees';
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    async run() {
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(WorktreeEvents.LIST), { projectPath: process.cwd() });
+            if (result.source === 'linked') {
+                this.log(`Worktree: ${result.worktreeRoot}`);
+                this.log(`Linked to: ${result.projectRoot}`);
+            }
+            else {
+                this.log(`Project: ${result.projectRoot}`);
+            }
+            if (result.worktrees.length > 0) {
+                this.log('\nRegistered worktrees:');
+                for (const wt of result.worktrees) {
+                    this.log(`   ${wt.name} → ${wt.worktreePath}`);
+                }
+            }
+        }
+        catch (error) {
+            this.error(formatConnectionError(error), { exit: 1 });
+        }
+    }
+}

package/dist/oclif/commands/worktree/remove.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class WorktreeRemove extends Command {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/oclif/commands/worktree/remove.js

@@ -0,0 +1,35 @@
+import { Args, Command } from '@oclif/core';
+import { resolve } from 'node:path';
+import { WorktreeEvents } from '../../../shared/transport/events/worktree-events.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+export default class WorktreeRemove extends Command {
+    static args = {
+        path: Args.string({
+            description: 'Path to the worktree to remove (defaults to cwd)',
+            required: false,
+        }),
+    };
+    static description = 'Remove a worktree registration and its .brv pointer';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>  (remove cwd as worktree)',
+        '<%= config.bin %> <%= command.id %> packages/api  (remove from parent)',
+    ];
+    async run() {
+        const { args } = await this.parse(WorktreeRemove);
+        const targetPath = args.path ? resolve(args.path) : resolve(process.cwd());
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(WorktreeEvents.REMOVE, {
+                worktreePath: targetPath,
+            }), { projectPath: process.cwd() });
+            if (result.success) {
+                this.log(result.message);
+            }
+            else {
+                this.error(result.message, { exit: 1 });
+            }
+        }
+        catch (error) {
+            this.error(formatConnectionError(error), { exit: 1 });
+        }
+    }
+}

package/dist/oclif/hooks/init/validate-brv-config.js

@@ -2,6 +2,7 @@ import { BRV_CONFIG_VERSION } from '../../../server/constants.js';
 import { ensureProjectInitialized } from '../../../server/infra/config/auto-init.js';
 import { ProjectConfigStore } from '../../../server/infra/config/file-config-store.js';
 import { FileContextTreeService } from '../../../server/infra/context-tree/file-context-tree-service.js';
+import { isWorktreePointer } from '../../../server/infra/project/resolve-project.js';
 import { syncConfigToXdg } from '../../../server/utils/config-xdg-sync.js';
 /**
  * Commands that should skip auto-init and config version validation.
@@ -22,6 +23,9 @@ const HELP_FLAGS = new Set(['--h', '--help', '-h', '-help']);
 export const validateBrvConfigVersion = async (commandId, configStore, argv = [], autoInitDeps) => {
     if (argv.some((arg) => HELP_FLAGS.has(arg)))
         return;
+    // Skip auto-init if .brv is a pointer file (worktree) — the project lives elsewhere
+    if (isWorktreePointer(process.cwd()))
+        return;
     const exists = await configStore.exists();
     if (!exists && COMMANDS_NEED_AUTO_INIT.has(commandId)) {
         const deps = autoInitDeps ?? {

package/dist/oclif/lib/daemon-client.d.ts

@@ -5,6 +5,8 @@ export interface DaemonClientOptions {
     maxRetries?: number;
     /** Explicit project path — bypasses walk-up discovery. Use for `init` where .brv/ doesn't exist yet. */
     projectPath?: string;
+    /** Explicit --project-root flag value to override auto-detection */
+    projectRootFlag?: string;
     /** Delay between retries in ms. Default: 2000. Set to 0 in tests. */
     retryDelayMs?: number;
     /** Optional transport connector for DI/testing */
@@ -13,14 +15,14 @@ export interface DaemonClientOptions {
 /**
  * Connects to the daemon, auto-starting it if needed.
  */
-export declare function connectToDaemonClient(options?: Pick<DaemonClientOptions, 'transportConnector'>): Promise<ConnectionResult>;
+export declare function connectToDaemonClient(options?: Pick<DaemonClientOptions, 'projectRootFlag' | 'transportConnector'>): Promise<ConnectionResult>;
 /**
  * Executes an operation against the daemon with retry logic.
  *
  * Retries on infrastructure failures (daemon spawn timeout, connection dropped,
  * agent disconnected). Does NOT retry on business errors (auth, validation, etc.).
  */
-export declare function withDaemonRetry<T>(fn: (client: ITransportClient, projectRoot?: string) => Promise<T>, options?: DaemonClientOptions & {
+export declare function withDaemonRetry<T>(fn: (client: ITransportClient, projectRoot?: string, worktreeRoot?: string) => Promise<T>, options?: DaemonClientOptions & {
     /** Called before each retry with attempt number (1-indexed) */
     onRetry?: (attempt: number, maxRetries: number) => void;
 }): Promise<T>;

package/dist/oclif/lib/daemon-client.js

@@ -1,5 +1,6 @@
 import { ConnectionError, ConnectionFailedError, DaemonSpawnError, InstanceCrashedError, NoInstanceRunningError, TransportRequestError, TransportRequestTimeoutError, } from '@campfirein/brv-transport-client';
 import { TaskErrorCode } from '../../server/core/domain/errors/task-error.js';
+import { resolveProject } from '../../server/infra/project/resolve-project.js';
 import { createDaemonAwareConnector } from '../../server/infra/transport/transport-connector.js';
 import { getSandboxEnvironmentName, isSandboxEnvironment, isSandboxNetworkError, } from '../../server/utils/sandbox-detector.js';
 import { VcErrorCode } from '../../shared/transport/events/vc-events.js';
@@ -34,12 +35,22 @@ const USER_FRIENDLY_MESSAGES = {
     // UNCOMMITTED_CHANGES intentionally omitted: fall through to server's detailed message with file paths
     // USER_NOT_CONFIGURED intentionally omitted: fall through to server's specific hint with actual values
 };
+function resolveRequiredProjectPath(projectRootFlag) {
+    const resolution = resolveProject({ projectRootFlag });
+    if (!resolution) {
+        // No .brv found at cwd — fall back to cwd. The daemon will auto-init .brv/ on first connection.
+        const cwd = process.cwd();
+        return { projectRoot: cwd, worktreeRoot: cwd };
+    }
+    return resolution;
+}
 /**
  * Connects to the daemon, auto-starting it if needed.
  */
 export async function connectToDaemonClient(options) {
     const connector = options?.transportConnector ?? createDaemonAwareConnector();
-    return connector();
+    const resolution = resolveRequiredProjectPath(options?.projectRootFlag);
+    return connector(undefined, resolution.projectRoot);
 }
 /**
  * Executes an operation against the daemon with retry logic.
@@ -51,14 +62,19 @@ export async function withDaemonRetry(fn, options) {
     const maxRetries = options?.maxRetries ?? MAX_RETRIES;
     const retryDelayMs = options?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
     const connector = options?.transportConnector ?? createDaemonAwareConnector(options?.projectPath);
+    // Pre-resolve project (workspace-link-aware) so the connector registers
+    // with the correct projectPath and callers get the resolved worktreeRoot.
+    const resolution = resolveRequiredProjectPath(options?.projectRootFlag);
+    const resolvedProjectPath = resolution.projectRoot;
+    const resolvedWorkspaceRoot = resolution.worktreeRoot;
     let lastError;
     /* eslint-disable no-await-in-loop -- intentional sequential retry loop */
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
         let client;
         try {
-            const { client: connectedClient, projectRoot } = await connector();
+            const { client: connectedClient, projectRoot } = await connector(undefined, resolvedProjectPath);
             client = connectedClient;
-            const value = await fn(client, projectRoot);
+            const value = await fn(client, projectRoot ?? resolvedProjectPath, resolvedWorkspaceRoot);
             await client.disconnect().catch(() => { });
             return value;
         }

package/dist/server/constants.d.ts

@@ -1,6 +1,12 @@
 export declare const BRV_DIR = ".brv";
 export declare const PROJECT_CONFIG_FILE = "config.json";
 export declare const BRV_CONFIG_VERSION = "0.0.1";
+export declare const WORKTREES_DIR = "worktrees";
+export declare const WORKTREE_LINK_METADATA = "link.json";
+export declare const SOURCES_FILE = "sources.json";
+export declare const SHARED_SOURCE_LOCAL_SCORE_BOOST = 0.1;
+export declare const MCP_ASSOCIATE_PROJECT_TIMEOUT_MS = 3000;
+export declare const MCP_ASSOCIATE_PROJECT_MAX_ATTEMPTS = 2;
 export declare const GLOBAL_CONFIG_DIR = "brv";
 export declare const GLOBAL_CONFIG_FILE = "config.json";
 export declare const GLOBAL_CONFIG_VERSION = "0.0.1";

package/dist/server/constants.js

@@ -1,6 +1,14 @@
 export const BRV_DIR = '.brv';
 export const PROJECT_CONFIG_FILE = 'config.json';
 export const BRV_CONFIG_VERSION = '0.0.1';
+// Worktree linking (git-style: .brv is a file pointing to parent project)
+export const WORKTREES_DIR = 'worktrees';
+export const WORKTREE_LINK_METADATA = 'link.json';
+// Knowledge sources (read-only references to other projects)
+export const SOURCES_FILE = 'sources.json';
+export const SHARED_SOURCE_LOCAL_SCORE_BOOST = 0.1;
+export const MCP_ASSOCIATE_PROJECT_TIMEOUT_MS = 3000;
+export const MCP_ASSOCIATE_PROJECT_MAX_ATTEMPTS = 2;
 // Global config constants (user-level, stored in XDG config directory)
 export const GLOBAL_CONFIG_DIR = 'brv';
 export const GLOBAL_CONFIG_FILE = 'config.json';

package/dist/server/core/domain/client/client-info.d.ts

@@ -78,5 +78,12 @@ export declare class ClientInfo {
      * Called after MCP initialize handshake provides clientInfo.
      */
     setAgentName(agentName: string): void;
+    /**
+     * Update this client's project path, even if already associated.
+     * Used for reassociation after worktree add/remove operations.
+     *
+     * @returns The previous project path (undefined if not previously associated)
+     */
+    updateProjectPath(projectPath: string): string | undefined;
 }
 export {};

package/dist/server/core/domain/client/client-info.js

@@ -84,4 +84,15 @@ export class ClientInfo {
     setAgentName(agentName) {
         this._agentName = agentName;
     }
+    /**
+     * Update this client's project path, even if already associated.
+     * Used for reassociation after worktree add/remove operations.
+     *
+     * @returns The previous project path (undefined if not previously associated)
+     */
+    updateProjectPath(projectPath) {
+        const oldPath = this._projectPath;
+        this._projectPath = projectPath;
+        return oldPath;
+    }
 }

package/dist/server/core/domain/project/worktrees-schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Schema for the `.brv` pointer file (when .brv is a FILE, not a directory).
+ * Like git's `.git` file in worktrees: contains a single `projectRoot` field
+ * pointing to the parent project's absolute path.
+ */
+export declare const WorktreePointerSchema: z.ZodObject<{
+    projectRoot: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    projectRoot: string;
+}, {
+    projectRoot: string;
+}>;
+export type WorktreePointer = z.infer<typeof WorktreePointerSchema>;
+/**
+ * Schema for `.brv/worktrees/<name>/link.json` — metadata about a registered worktree.
+ * Stored in the parent project's `.brv/worktrees/` directory (like `.git/worktrees/`).
+ */
+export declare const WorktreeLinkMetadataSchema: z.ZodObject<{
+    addedAt: z.ZodOptional<z.ZodString>;
+    worktreePath: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    worktreePath: string;
+    addedAt?: string | undefined;
+}, {
+    worktreePath: string;
+    addedAt?: string | undefined;
+}>;
+export type WorktreeLinkMetadata = z.infer<typeof WorktreeLinkMetadataSchema>;

package/dist/server/core/domain/project/worktrees-schema.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * Schema for the `.brv` pointer file (when .brv is a FILE, not a directory).
+ * Like git's `.git` file in worktrees: contains a single `projectRoot` field
+ * pointing to the parent project's absolute path.
+ */
+export const WorktreePointerSchema = z.object({
+    projectRoot: z.string().min(1),
+});
+/**
+ * Schema for `.brv/worktrees/<name>/link.json` — metadata about a registered worktree.
+ * Stored in the parent project's `.brv/worktrees/` directory (like `.git/worktrees/`).
+ */
+export const WorktreeLinkMetadataSchema = z.object({
+    addedAt: z.string().optional(),
+    worktreePath: z.string().min(1),
+});

package/dist/server/core/domain/source/source-operations.d.ts

@@ -0,0 +1,31 @@
+import { type SourceStatus } from './source-schema.js';
+export interface OperationResult {
+    message: string;
+    success: boolean;
+}
+/**
+ * Adds a read-only knowledge source from another project's context tree.
+ *
+ * Validates: target is a brv project, not self, not duplicate, not circular.
+ * Writes to `.brv/sources.json`.
+ */
+export declare function addSource(projectRoot: string, targetPath: string, alias?: string): OperationResult;
+/**
+ * Removes a knowledge source by alias or path.
+ */
+export declare function removeSource(projectRoot: string, aliasOrPath: string): OperationResult;
+export interface ListSourcesResult {
+    error?: string;
+    statuses: SourceStatus[];
+}
+/**
+ * Returns status for all sources in the project.
+ * Surfaces malformed file errors instead of silently returning empty.
+ */
+export declare function listSourceStatuses(projectRoot: string): ListSourcesResult;
+/**
+ * Checks if adding projectRoot → targetRoot would create a circular dependency.
+ * A circular reference exists if the target project already has a source pointing
+ * back to the current project (direct cycle only — no transitive check in v1).
+ */
+export declare function detectCircularSource(projectRoot: string, targetRoot: string): boolean;

package/dist/server/core/domain/source/source-operations.js

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { BRV_DIR, PROJECT_CONFIG_FILE, SOURCES_FILE } from '../../../constants.js';
+import { getSourceStatuses, loadSources, SourcesFileSchema, } from './source-schema.js';
+// ============================================================================
+// Add source
+// ============================================================================
+/**
+ * Adds a read-only knowledge source from another project's context tree.
+ *
+ * Validates: target is a brv project, not self, not duplicate, not circular.
+ * Writes to `.brv/sources.json`.
+ */
+export function addSource(projectRoot, targetPath, alias) {
+    // 1. Local project must have .brv/
+    const localConfigPath = join(projectRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+    if (!existsSync(localConfigPath)) {
+        return { message: `Current project has no .brv/ — run 'brv' first to initialize.`, success: false };
+    }
+    // 2. Resolve target to canonical path
+    let targetRoot;
+    try {
+        targetRoot = realpathSync(targetPath);
+    }
+    catch {
+        return { message: `Target path does not exist: ${targetPath}`, success: false };
+    }
+    // 3. Target must be a brv project
+    const targetConfigPath = join(targetRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+    if (!existsSync(targetConfigPath)) {
+        return { message: `Target "${targetRoot}" is not a ByteRover project (no .brv/config.json).`, success: false };
+    }
+    // 4. Not self
+    let canonicalProjectRoot;
+    try {
+        canonicalProjectRoot = realpathSync(projectRoot);
+    }
+    catch {
+        canonicalProjectRoot = projectRoot;
+    }
+    if (targetRoot === canonicalProjectRoot) {
+        return { message: 'Cannot add a source pointing to the current project.', success: false };
+    }
+    // 5. Read existing file — refuse to mutate if malformed
+    const existing = readSourcesFile(projectRoot);
+    if (existing.error) {
+        return { message: existing.error, success: false };
+    }
+    // 6. Not duplicate
+    const isDuplicate = existing.data.sources.some((source) => {
+        try {
+            return realpathSync(source.projectRoot) === targetRoot;
+        }
+        catch {
+            return source.projectRoot === targetRoot;
+        }
+    });
+    if (isDuplicate) {
+        return { message: `Source "${targetRoot}" already added.`, success: false };
+    }
+    // 7. Not circular
+    if (detectCircularSource(canonicalProjectRoot, targetRoot)) {
+        return {
+            message: `Circular source detected: "${basename(targetRoot)}" already references this project as a source.`,
+            success: false,
+        };
+    }
+    // 8. Derive alias — reject empty/whitespace-only
+    if (alias !== undefined && alias.trim() === '') {
+        return { message: 'Alias must not be empty.', success: false };
+    }
+    const derivedAlias = alias ?? basename(targetRoot);
+    // 9. Ensure alias uniqueness — append suffix if collision
+    const finalAlias = ensureUniqueAlias(derivedAlias, existing.data.sources);
+    // 10. Append and write
+    const newSource = {
+        addedAt: new Date().toISOString(),
+        alias: finalAlias,
+        projectRoot: targetRoot,
+        readOnly: true,
+    };
+    existing.data.sources.push(newSource);
+    writeSourcesFile(projectRoot, existing.data);
+    return { message: `Added source "${targetRoot}" as "${finalAlias}".`, success: true };
+}
+// ============================================================================
+// Remove source
+// ============================================================================
+/**
+ * Removes a knowledge source by alias or path.
+ */
+export function removeSource(projectRoot, aliasOrPath) {
+    const existing = readSourcesFile(projectRoot);
+    if (existing.error) {
+        return { message: existing.error, success: false };
+    }
+    if (existing.data.sources.length === 0) {
+        return { message: 'No knowledge sources configured.', success: false };
+    }
+    // Try match by alias first, then by canonical path
+    let matchIndex = existing.data.sources.findIndex((source) => source.alias === aliasOrPath);
+    if (matchIndex === -1) {
+        // Try matching by path
+        let canonicalTarget;
+        try {
+            canonicalTarget = realpathSync(aliasOrPath);
+        }
+        catch {
+            canonicalTarget = aliasOrPath;
+        }
+        matchIndex = existing.data.sources.findIndex((source) => {
+            try {
+                return realpathSync(source.projectRoot) === canonicalTarget;
+            }
+            catch {
+                return source.projectRoot === canonicalTarget;
+            }
+        });
+    }
+    if (matchIndex === -1) {
+        return { message: `No source found matching "${aliasOrPath}".`, success: false };
+    }
+    const removed = existing.data.sources.splice(matchIndex, 1)[0];
+    writeSourcesFile(projectRoot, existing.data);
+    return { message: `Removed source "${removed.alias}" (${removed.projectRoot}).`, success: true };
+}
+/**
+ * Returns status for all sources in the project.
+ * Surfaces malformed file errors instead of silently returning empty.
+ */
+export function listSourceStatuses(projectRoot) {
+    const existing = readSourcesFile(projectRoot);
+    if (existing.error) {
+        return { error: existing.error, statuses: [] };
+    }
+    if (existing.data.sources.length === 0) {
+        return { statuses: [] };
+    }
+    return { statuses: getSourceStatuses(existing.data.sources) };
+}
+// ============================================================================
+// Circular source detection
+// ============================================================================
+/**
+ * Checks if adding projectRoot → targetRoot would create a circular dependency.
+ * A circular reference exists if the target project already has a source pointing
+ * back to the current project (direct cycle only — no transitive check in v1).
+ */
+export function detectCircularSource(projectRoot, targetRoot) {
+    const targetSources = loadSources(targetRoot);
+    if (!targetSources) {
+        return false;
+    }
+    return targetSources.sources.some((source) => {
+        try {
+            return realpathSync(source.projectRoot) === projectRoot;
+        }
+        catch {
+            return source.projectRoot === projectRoot;
+        }
+    });
+}
+function readSourcesFile(projectRoot) {
+    const filePath = join(projectRoot, BRV_DIR, SOURCES_FILE);
+    if (!existsSync(filePath)) {
+        return { data: { sources: [], version: 1 } };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return {
+            data: { sources: [], version: 1 },
+            error: `Malformed ${SOURCES_FILE}: file is not valid JSON. Back up or delete the file to recover.`,
+        };
+    }
+    const result = SourcesFileSchema.safeParse(raw);
+    if (!result.success) {
+        return {
+            data: { sources: [], version: 1 },
+            error: `Malformed ${SOURCES_FILE}: schema validation failed. Back up or delete the file to recover.`,
+        };
+    }
+    return { data: result.data };
+}
+function writeSourcesFile(projectRoot, data) {
+    const filePath = join(projectRoot, BRV_DIR, SOURCES_FILE);
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+function ensureUniqueAlias(baseAlias, existingSources) {
+    const existingAliases = new Set(existingSources.map((source) => source.alias));
+    if (!existingAliases.has(baseAlias)) {
+        return baseAlias;
+    }
+    let counter = 2;
+    while (existingAliases.has(`${baseAlias}-${counter}`)) {
+        counter++;
+    }
+    return `${baseAlias}-${counter}`;
+}

package/dist/server/core/domain/source/source-schema.d.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+export declare const SourceSchema: z.ZodObject<{
+    addedAt: z.ZodString;
+    alias: z.ZodString;
+    projectRoot: z.ZodString;
+    readOnly: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    addedAt: string;
+    alias: string;
+    projectRoot: string;
+    readOnly: true;
+}, {
+    addedAt: string;
+    alias: string;
+    projectRoot: string;
+    readOnly: true;
+}>;
+export declare const SourcesFileSchema: z.ZodObject<{
+    sources: z.ZodArray<z.ZodObject<{
+        addedAt: z.ZodString;
+        alias: z.ZodString;
+        projectRoot: z.ZodString;
+        readOnly: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }, {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }>, "many">;
+    version: z.ZodLiteral<1>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    sources: {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }[];
+}, {
+    version: 1;
+    sources: {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }[];
+}>;
+export type Source = z.infer<typeof SourceSchema>;
+export type SourcesFile = z.infer<typeof SourcesFileSchema>;
+export interface SearchOrigin {
+    alias?: string;
+    contextTreeRoot: string;
+    origin: 'local' | 'shared';
+    originKey: string;
+}
+/**
+ * Derives a stable, short origin key from a canonical path.
+ * Uses first 12 hex chars of SHA-256 to avoid alias-based collisions.
+ */
+export declare function deriveOriginKey(canonicalPath: string): string;
+export interface LoadedSources {
+    mtime: number;
+    /** Search origins derived from valid sources (callers can search them) */
+    origins: SearchOrigin[];
+    /** All configured sources (including broken ones — for status display) */
+    sources: Source[];
+}
+/**
+ * Loads and validates `.brv/sources.json` from a project root.
+ *
+ * Returns null if the file does not exist.
+ * Broken sources (target `.brv/` missing) are included in `sources` but excluded
+ * from `origins` — callers decide how to surface them (status vs search).
+ */
+export declare function loadSources(projectRoot: string): LoadedSources | null;
+export interface SourceStatus {
+    alias: string;
+    contextTreeSize?: number;
+    projectRoot: string;
+    valid: boolean;
+}
+/**
+ * Validates each source and returns status for display.
+ *
+ * A source is valid only when both `.brv/config.json` AND `.brv/context-tree/`
+ * exist — matching what loadSources() requires before including a source in
+ * search origins. When valid, `contextTreeSize` counts `.md` files.
+ */
+export declare function getSourceStatuses(sources: Source[]): SourceStatus[];