byterover-cli 3.2.0 → 3.4.0

package/dist/agent/infra/swarm/adapters/obsidian-adapter.js

@@ -0,0 +1,201 @@
+import MiniSearch from 'minisearch';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { ADAPTER_CONTENT_LIMIT, applyGapRatio, POST_EXPANSION_GAP_RATIO, searchWithPrecision } from '../search-precision.js';
+/** Wikilink decay factor for graph-expanded results */
+const WIKILINK_DECAY = 0.7;
+/** Default patterns to ignore when scanning the vault */
+const DEFAULT_IGNORE = new Set(['.git', '.obsidian', '.trash', 'templates']);
+/**
+ * Extract `[[target]]` and `[[target|alias]]` wikilinks from markdown content.
+ */
+function extractWikilinks(content) {
+    const links = [];
+    const regex = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        links.push(match[1].trim());
+    }
+    return links;
+}
+function findMarkdownFiles(dirPath, basePath, ignoreSet) {
+    const results = [];
+    try {
+        const entries = readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (ignoreSet.has(entry.name))
+                continue;
+            const fullPath = join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...findMarkdownFiles(fullPath, basePath, ignoreSet));
+            }
+            else if (entry.name.endsWith('.md')) {
+                const stats = statSync(fullPath);
+                results.push({
+                    fullPath,
+                    relativePath: relative(basePath, fullPath),
+                    signature: `${stats.mtimeMs}:${stats.size}`,
+                });
+            }
+        }
+    }
+    catch {
+        // Skip inaccessible directories
+    }
+    return results;
+}
+function buildIndexSignature(files) {
+    return files
+        .map((file) => `${file.relativePath}:${file.signature}`)
+        .sort()
+        .join('|');
+}
+/**
+ * Obsidian vault adapter — indexes .md files via MiniSearch,
+ * follows [[wikilinks]] one hop for graph expansion.
+ *
+ * Read-only by default (does not modify the user's vault).
+ */
+export class ObsidianAdapter {
+    vaultPath;
+    capabilities = {
+        avgLatencyMs: 100,
+        graphTraversal: true,
+        keywordSearch: true,
+        localOnly: true,
+        maxTokensPerQuery: 8000,
+        semanticSearch: false,
+        temporalQuery: false,
+        userModeling: false,
+        writeSupported: false,
+    };
+    id = 'obsidian';
+    type = 'obsidian';
+    documents = [];
+    ignoreSet;
+    index;
+    indexSignature;
+    pathToDoc = new Map();
+    watchForChanges;
+    constructor(vaultPath, options) {
+        this.vaultPath = vaultPath;
+        this.ignoreSet = new Set([...(options?.ignorePatterns ?? []), ...DEFAULT_IGNORE]);
+        this.watchForChanges = options?.watchForChanges ?? true;
+    }
+    async delete(_id) {
+        throw new Error('Obsidian vault is read-only.');
+    }
+    estimateCost(_request) {
+        return {
+            estimatedCostCents: 0,
+            estimatedLatencyMs: this.capabilities.avgLatencyMs,
+            estimatedTokens: 0,
+        };
+    }
+    async healthCheck() {
+        return { available: existsSync(this.vaultPath) };
+    }
+    async query(request) {
+        this.ensureIndex();
+        const maxResults = request.maxResults ?? 10;
+        if (!this.index)
+            return [];
+        // T1/T2/T3: Precision-filtered search (stop words, AND-first, score floor, gap ratio)
+        const precisionResults = searchWithPrecision(this.index, request.query, { maxResults });
+        if (precisionResults.length === 0)
+            return [];
+        // Collect direct matches
+        const resultMap = new Map();
+        for (const pr of precisionResults) {
+            const doc = this.documents[pr.id];
+            if (!doc)
+                continue;
+            resultMap.set(doc.path, { doc, matchType: 'keyword', score: pr.normalizedScore });
+        }
+        // Expand wikilinks one hop from direct matches
+        for (const [, entry] of resultMap) {
+            for (const linkTarget of entry.doc.wikilinks) {
+                const candidates = [
+                    `${linkTarget}.md`,
+                    linkTarget,
+                    ...[...this.pathToDoc.keys()].filter((p) => p.toLowerCase().endsWith(`${linkTarget.toLowerCase()}.md`) ||
+                        p.toLowerCase() === linkTarget.toLowerCase()),
+                ];
+                for (const candidate of candidates) {
+                    const linkedDoc = this.pathToDoc.get(candidate);
+                    if (linkedDoc && !resultMap.has(linkedDoc.path)) {
+                        resultMap.set(linkedDoc.path, {
+                            doc: linkedDoc,
+                            matchType: 'graph',
+                            score: entry.score * WIKILINK_DECAY,
+                        });
+                        break;
+                    }
+                }
+            }
+        }
+        // Second gap-ratio pass on combined direct + expanded results (T3 only)
+        const combined = [...resultMap.entries()].map(([path, entry]) => ({
+            doc: entry.doc,
+            matchType: entry.matchType,
+            normalizedScore: entry.score,
+            path,
+        }));
+        const gapFiltered = applyGapRatio(combined.map((c) => ({ id: c.path, normalizedScore: c.normalizedScore, queryTerms: [], rawScore: 0 })), POST_EXPANSION_GAP_RATIO);
+        const keptPaths = new Set(gapFiltered.map((r) => r.id));
+        const sorted = combined
+            .filter((c) => keptPaths.has(c.path))
+            .sort((a, b) => b.normalizedScore - a.normalizedScore)
+            .slice(0, maxResults);
+        return sorted.map((entry, index) => ({
+            content: entry.doc.content.slice(0, ADAPTER_CONTENT_LIMIT),
+            id: `obsidian-${index}`,
+            metadata: {
+                matchType: entry.matchType,
+                path: entry.path,
+                source: entry.path,
+            },
+            provider: 'obsidian',
+            providerType: 'obsidian',
+            score: entry.normalizedScore,
+        }));
+    }
+    async store(_entry) {
+        throw new Error('Obsidian vault is read-only.');
+    }
+    async update(_id, _entry) {
+        throw new Error('Obsidian vault is read-only.');
+    }
+    ensureIndex() {
+        // When watchForChanges is false, reuse the existing index after initial build
+        if (this.index && !this.watchForChanges) {
+            return;
+        }
+        const files = findMarkdownFiles(this.vaultPath, this.vaultPath, this.ignoreSet);
+        const nextSignature = buildIndexSignature(files);
+        if (this.index && this.indexSignature === nextSignature) {
+            return;
+        }
+        this.documents = files.map((file, index) => {
+            const content = readFileSync(file.fullPath, 'utf8');
+            const titleMatch = content.match(/^#\s+(.+)$/m);
+            return {
+                content,
+                id: index,
+                path: file.relativePath,
+                title: titleMatch?.[1] ?? file.relativePath,
+                wikilinks: extractWikilinks(content),
+            };
+        });
+        this.index = new MiniSearch({
+            fields: ['title', 'content'],
+            storeFields: ['title', 'path'],
+        });
+        this.index.addAll(this.documents);
+        this.pathToDoc.clear();
+        for (const doc of this.documents) {
+            this.pathToDoc.set(doc.path, doc);
+        }
+        this.indexSignature = nextSignature;
+    }
+}

package/dist/agent/infra/swarm/cli/query-renderer.d.ts

@@ -0,0 +1,15 @@
+import type { ProviderType } from '../../../core/domain/swarm/types.js';
+import type { SwarmQueryResult } from '../../../core/interfaces/i-swarm-coordinator.js';
+export declare function providerTypeToLabel(type: ProviderType, id: string): string;
+/**
+ * Format swarm query results for terminal display.
+ */
+export declare function formatQueryResults(result: SwarmQueryResult, query: string): string;
+/**
+ * Format swarm query results with detailed explain output.
+ */
+export declare function formatQueryResultsExplain(result: SwarmQueryResult, query: string): string;
+/**
+ * Format swarm query results as JSON.
+ */
+export declare function formatQueryResultsJson(result: SwarmQueryResult): string;

package/dist/agent/infra/swarm/cli/query-renderer.js

@@ -0,0 +1,126 @@
+import chalk from 'chalk';
+const DISPLAY_CONTENT_LIMIT = 2000;
+export function providerTypeToLabel(type, id) {
+    switch (type) {
+        case 'byterover': {
+            return 'context-tree';
+        }
+        case 'gbrain': {
+            return 'gbrain';
+        }
+        case 'hindsight': {
+            return 'hindsight';
+        }
+        case 'honcho': {
+            return 'honcho';
+        }
+        case 'local-markdown': {
+            const name = id.split(':')[1] ?? 'files';
+            return `notes:${name}`;
+        }
+        case 'memory-wiki': {
+            return 'memory-wiki';
+        }
+        case 'obsidian': {
+            return 'obsidian';
+        }
+    }
+}
+const LABEL_COLORS = {
+    byterover: chalk.cyan,
+    gbrain: chalk.yellow,
+    hindsight: chalk.blueBright,
+    honcho: chalk.blue,
+    'local-markdown': chalk.green,
+    'memory-wiki': chalk.whiteBright,
+    obsidian: chalk.magenta,
+};
+function colorLabel(providerType, provider) {
+    const label = providerTypeToLabel(providerType, provider);
+    const colorFn = LABEL_COLORS[providerType];
+    return colorFn(`[${label}]`);
+}
+/**
+ * Format swarm query results for terminal display.
+ */
+export function formatQueryResults(result, query) {
+    const providerEntries = Object.entries(result.meta.providers);
+    const queriedCount = providerEntries.filter(([, meta]) => meta.selected !== false).length;
+    const lines = [
+        chalk.bold(`\nSwarm Query: "${query}"`),
+        `Type: ${chalk.cyan(result.meta.queryType)} | Providers: ${chalk.yellow(`${queriedCount} queried`)} | Latency: ${chalk.yellow(`${result.meta.totalLatencyMs}ms`)}`,
+        '─'.repeat(50),
+    ];
+    if (result.results.length === 0) {
+        lines.push(chalk.dim('No results found.'));
+        return lines.join('\n');
+    }
+    for (const [i, r] of result.results.entries()) {
+        const scoreStr = chalk.green(r.score.toFixed(4));
+        const sourceStr = chalk.dim(r.metadata.source);
+        const matchStr = chalk.dim(`[${r.metadata.matchType}]`);
+        const label = r.providerType ? colorLabel(r.providerType, r.provider) : '';
+        const content = r.content.length > DISPLAY_CONTENT_LIMIT ? `${r.content.slice(0, DISPLAY_CONTENT_LIMIT)}…` : r.content;
+        lines.push(`${chalk.bold(`${i + 1}.`)} ${label} ${sourceStr}    score: ${scoreStr}  ${matchStr}`, `   ${content}`, '');
+    }
+    if (result.meta.costCents > 0) {
+        lines.push(chalk.dim(`Cost: $${(result.meta.costCents / 100).toFixed(4)}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Format swarm query results with detailed explain output.
+ */
+export function formatQueryResultsExplain(result, query) {
+    const providerEntries = Object.entries(result.meta.providers);
+    const selected = providerEntries.filter(([, m]) => m.selected !== false);
+    const excluded = providerEntries.filter(([, m]) => m.selected === false);
+    const lines = [
+        chalk.bold(`\nSwarm Query: "${query}"`),
+        `Classification: ${chalk.cyan(result.meta.queryType)}`,
+        `Provider selection: ${selected.length} of ${providerEntries.length} available`,
+    ];
+    for (const [id, meta] of selected) {
+        lines.push(`  ${chalk.green('✓')} ${id}    (healthy, selected, ${meta.resultCount} results, ${meta.latencyMs}ms)`);
+    }
+    for (const [id, meta] of excluded) {
+        lines.push(`  ${chalk.red('✗')} ${id}    (excluded — ${meta.excludeReason ?? 'unknown'})`);
+    }
+    // Enrichment
+    const enriched = providerEntries.filter(([, m]) => m.enrichedBy);
+    if (enriched.length > 0) {
+        lines.push('Enrichment:');
+        for (const [id, meta] of enriched) {
+            const excerpts = meta.enrichmentExcerpts?.length
+                ? ` (context: ${meta.enrichmentExcerpts.map((k) => `"${k.slice(0, 30)}"`).join(', ')})`
+                : '';
+            lines.push(`  ${meta.enrichedBy} → ${id}${excerpts}`);
+        }
+    }
+    // Result count
+    const totalRaw = providerEntries.reduce((sum, [, m]) => sum + m.resultCount, 0);
+    lines.push(`Results: ${totalRaw} raw → ${result.results.length} after RRF fusion + precision filtering`, '─'.repeat(50));
+    if (result.results.length === 0) {
+        lines.push(chalk.dim('No results found.'));
+        return lines.join('\n');
+    }
+    for (const [i, r] of result.results.entries()) {
+        const scoreStr = chalk.green(r.score.toFixed(4));
+        const sourceStr = chalk.dim(r.metadata.source);
+        const matchStr = chalk.dim(`[${r.metadata.matchType}]`);
+        const label = r.providerType ? colorLabel(r.providerType, r.provider) : '';
+        const content = r.content.length > DISPLAY_CONTENT_LIMIT ? `${r.content.slice(0, DISPLAY_CONTENT_LIMIT)}…` : r.content;
+        lines.push(`${chalk.bold(`${i + 1}.`)} ${label} ${sourceStr}    score: ${scoreStr}  ${matchStr}`, `   ${content}`, '');
+    }
+    if (result.meta.costCents > 0) {
+        lines.push(chalk.dim(`Cost: $${(result.meta.costCents / 100).toFixed(4)}`));
+    }
+    lines.push(`Latency: ${result.meta.totalLatencyMs}ms`);
+    return lines.join('\n');
+}
+/**
+ * Format swarm query results as JSON.
+ */
+export function formatQueryResultsJson(result) {
+    return JSON.stringify(result, undefined, 2);
+}

package/dist/agent/infra/swarm/config/swarm-config-loader.d.ts

@@ -0,0 +1,14 @@
+import { type SwarmConfig } from './swarm-config-schema.js';
+/**
+ * Load swarm config from `.brv/swarm/config.yaml`.
+ *
+ * 1. Read YAML file
+ * 2. Resolve `${VAR}` env var references
+ * 3. Parse and validate through Zod schema
+ *
+ * @param projectRoot - Project root directory containing `.brv/`
+ * @param env - Environment variables (defaults to `process.env`)
+ * @returns Validated swarm config
+ * @throws Error if file not found, YAML invalid, or schema validation fails
+ */
+export declare function loadSwarmConfig(projectRoot: string, env?: Record<string, string | undefined>): Promise<SwarmConfig>;

package/dist/agent/infra/swarm/config/swarm-config-loader.js

@@ -0,0 +1,82 @@
+import { load } from 'js-yaml';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ZodError } from 'zod';
+import { resolveEnvVars, validateSwarmConfig } from './swarm-config-schema.js';
+/**
+ * Default path to the swarm config file relative to project root.
+ */
+const CONFIG_PATH = join('.brv', 'swarm', 'config.yaml');
+/**
+ * Expand a leading `~` to the user's home directory.
+ * Handles both Unix (`~/`) and Windows (`~\\`) separators.
+ * Node's fs APIs do not expand tilde, so we must do it ourselves.
+ */
+function expandTilde(value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/') || value.startsWith('~\\'))
+        return join(homedir(), value.slice(2));
+    return value;
+}
+/**
+ * Recursively resolve `${VAR}` env vars and expand `~/` in all string values.
+ */
+function resolveStringsDeep(obj, env) {
+    if (typeof obj === 'string') {
+        return expandTilde(resolveEnvVars(obj, env));
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => resolveStringsDeep(item, env));
+    }
+    if (typeof obj === 'object' && obj !== null) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = resolveStringsDeep(value, env);
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Load swarm config from `.brv/swarm/config.yaml`.
+ *
+ * 1. Read YAML file
+ * 2. Resolve `${VAR}` env var references
+ * 3. Parse and validate through Zod schema
+ *
+ * @param projectRoot - Project root directory containing `.brv/`
+ * @param env - Environment variables (defaults to `process.env`)
+ * @returns Validated swarm config
+ * @throws Error if file not found, YAML invalid, or schema validation fails
+ */
+export async function loadSwarmConfig(projectRoot, env) {
+    const configPath = join(projectRoot, CONFIG_PATH);
+    let rawYaml;
+    try {
+        rawYaml = readFileSync(configPath, 'utf8');
+    }
+    catch {
+        throw new Error(`Swarm config not found at ${configPath}. Run \`brv swarm onboard\` to create one.`);
+    }
+    let parsed;
+    try {
+        parsed = load(rawYaml);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to parse ${configPath}: ${detail}`);
+    }
+    const resolved = resolveStringsDeep(parsed, env ?? process.env);
+    try {
+        return validateSwarmConfig(resolved);
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            const issues = error.issues.map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`).join('\n');
+            throw new Error(`Invalid swarm config in ${configPath}:\n${issues}`);
+        }
+        throw error;
+    }
+}