byterover-cli 3.5.1 → 3.6.1

package/dist/server/infra/usecase/query-log-summary-use-case.js

@@ -0,0 +1,217 @@
+import { CACHE_TIERS, emptyByTier, QUERY_LOG_TIER_SHORT_LABELS, QUERY_LOG_TIERS, } from '../../core/domain/entities/query-log-entry.js';
+import { describePeriod, formatDurationMs, formatQueryLogSummaryNarrative } from './query-log-summary-narrative-formatter.js';
+const TOP_LIMIT = 10;
+const MAX_EXAMPLE_QUERIES = 3;
+const MIN_KEYWORD_LENGTH = 3;
+const STOPWORDS = new Set([
+    'about',
+    'all',
+    'and',
+    'any',
+    'are',
+    'but',
+    'can',
+    'did',
+    'does',
+    'for',
+    'from',
+    'get',
+    'had',
+    'has',
+    'have',
+    'how',
+    'into',
+    'just',
+    'like',
+    'not',
+    'our',
+    'set',
+    'that',
+    'the',
+    'this',
+    'use',
+    'using',
+    'was',
+    'were',
+    'what',
+    'when',
+    'where',
+    'which',
+    'who',
+    'why',
+    'with',
+    'you',
+    'your',
+]);
+export class QueryLogSummaryUseCase {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run(options) {
+        const entries = await this.deps.queryLogStore.list({ after: options.after, before: options.before });
+        const summary = computeSummary(entries, { after: options.after, before: options.before });
+        const format = options.format ?? 'text';
+        if (format === 'narrative') {
+            this.deps.terminal.log(formatQueryLogSummaryNarrative(summary));
+            return;
+        }
+        if (format === 'json') {
+            this.deps.terminal.log(JSON.stringify(summary, null, 2));
+            return;
+        }
+        this.deps.terminal.log(formatSummaryText(summary));
+    }
+}
+// ── Aggregation ─────────────────────────────────────────────────────────────
+function computeSummary(entries, range) {
+    const summary = {
+        byStatus: { cancelled: 0, completed: 0, error: 0 },
+        byTier: emptyByTier(),
+        cacheHitRate: 0,
+        coverageRate: 0,
+        knowledgeGaps: [],
+        period: { from: range.after ?? 0, to: range.before ?? 0 },
+        queriesWithoutMatches: 0,
+        responseTime: { avgMs: 0, p50Ms: 0, p95Ms: 0 },
+        topRecalledDocs: [],
+        topTopics: [],
+        totalMatchedDocs: 0,
+        totalQueries: 0,
+    };
+    if (entries.length === 0) {
+        return summary;
+    }
+    const durations = [];
+    const topicCounts = new Map();
+    const docCounts = new Map();
+    const gapBuckets = new Map();
+    let completedWithMatches = 0;
+    for (const entry of entries) {
+        if (entry.status === 'processing')
+            continue;
+        summary.totalQueries += 1;
+        summary.byStatus[entry.status] += 1;
+        if (entry.status !== 'completed')
+            continue;
+        // ── completed-only aggregations ──
+        if (entry.timing) {
+            durations.push(entry.timing.durationMs);
+        }
+        if (entry.tier === undefined) {
+            summary.byTier.unknown += 1;
+        }
+        else {
+            summary.byTier[`tier${entry.tier}`] += 1;
+        }
+        summary.totalMatchedDocs += entry.matchedDocs.length;
+        if (entry.matchedDocs.length > 0) {
+            completedWithMatches += 1;
+            for (const doc of entry.matchedDocs) {
+                const topic = doc.path.split('/')[0];
+                topicCounts.set(topic, (topicCounts.get(topic) ?? 0) + 1);
+                docCounts.set(doc.path, (docCounts.get(doc.path) ?? 0) + 1);
+            }
+        }
+        else {
+            collectGapKeywords(entry.query, gapBuckets);
+        }
+    }
+    if (summary.byStatus.completed > 0) {
+        const cacheHits = CACHE_TIERS.reduce((sum, t) => sum + summary.byTier[`tier${t}`], 0);
+        summary.cacheHitRate = cacheHits / summary.byStatus.completed;
+        summary.coverageRate = completedWithMatches / summary.byStatus.completed;
+        summary.queriesWithoutMatches = summary.byStatus.completed - completedWithMatches;
+    }
+    summary.responseTime = computeResponseTime(durations);
+    summary.topTopics = sortAndLimitCounts(topicCounts, 'topic');
+    summary.topRecalledDocs = sortAndLimitCounts(docCounts, 'path');
+    summary.knowledgeGaps = sortAndLimitGaps(gapBuckets);
+    return summary;
+}
+function computeResponseTime(durations) {
+    if (durations.length === 0) {
+        return { avgMs: 0, p50Ms: 0, p95Ms: 0 };
+    }
+    const sorted = [...durations].sort((a, b) => a - b);
+    const sum = sorted.reduce((acc, v) => acc + v, 0);
+    return {
+        avgMs: Math.round(sum / sorted.length),
+        p50Ms: sorted[Math.ceil(sorted.length * 0.5) - 1],
+        p95Ms: sorted[Math.ceil(sorted.length * 0.95) - 1],
+    };
+}
+function sortAndLimitCounts(counts, key) {
+    return [...counts.entries()]
+        .map(([value, count]) => ({ count, [key]: value }))
+        .sort((a, b) => b.count - a.count || a[key].localeCompare(b[key]))
+        .slice(0, TOP_LIMIT);
+}
+function sortAndLimitGaps(buckets) {
+    return [...buckets.entries()]
+        .map(([topic, { count, exampleQueries }]) => ({ count, exampleQueries, topic }))
+        .sort((a, b) => b.count - a.count || a.topic.localeCompare(b.topic))
+        .slice(0, TOP_LIMIT);
+}
+function collectGapKeywords(query, buckets) {
+    const seen = new Set();
+    for (const token of query.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (token.length < MIN_KEYWORD_LENGTH || STOPWORDS.has(token) || seen.has(token))
+            continue;
+        seen.add(token);
+        const bucket = buckets.get(token) ?? { count: 0, exampleQueries: [] };
+        bucket.count += 1;
+        if (bucket.exampleQueries.length < MAX_EXAMPLE_QUERIES) {
+            bucket.exampleQueries.push(query);
+        }
+        buckets.set(token, bucket);
+    }
+}
+// ── Text formatting ─────────────────────────────────────────────────────────
+function formatSummaryText(summary) {
+    const periodLabel = describePeriod(summary.period, 'short');
+    const header = periodLabel ? `Query Recall Summary (${periodLabel})` : 'Query Recall Summary';
+    if (summary.totalQueries === 0) {
+        return `${header}\n(no entries yet)`;
+    }
+    const cacheHits = CACHE_TIERS.reduce((sum, t) => sum + summary.byTier[`tier${t}`], 0);
+    const cachePct = Math.round(summary.cacheHitRate * 100);
+    const coveragePct = Math.round(summary.coverageRate * 100);
+    const matchedCount = summary.byStatus.completed - summary.queriesWithoutMatches;
+    const lines = [
+        header,
+        '='.repeat(header.length),
+        `Total queries:        ${summary.totalQueries}`,
+        `  Completed:          ${summary.byStatus.completed}`,
+        `  Failed:             ${summary.byStatus.error}`,
+        `  Cancelled:          ${summary.byStatus.cancelled}`,
+        '',
+        `Cache hit rate:       ${cachePct}% (${cacheHits}/${summary.byStatus.completed})`,
+    ];
+    const maxTierLen = Math.max(...QUERY_LOG_TIERS.map((t) => `Tier ${t} (${QUERY_LOG_TIER_SHORT_LABELS[t]}):`.length));
+    for (const t of QUERY_LOG_TIERS) {
+        const label = `Tier ${t} (${QUERY_LOG_TIER_SHORT_LABELS[t]}):`;
+        lines.push(`  ${label.padEnd(maxTierLen)}  ${summary.byTier[`tier${t}`]}`);
+    }
+    lines.push('', 'Response time:', `  Average:            ${formatDurationMs(summary.responseTime.avgMs)}`, `  p50:                ${formatDurationMs(summary.responseTime.p50Ms)}`, `  p95:                ${formatDurationMs(summary.responseTime.p95Ms)}`, '', `Knowledge coverage:   ${coveragePct}% (${matchedCount}/${summary.byStatus.completed} queries had relevant results)`);
+    if (summary.topTopics.length > 0) {
+        lines.push('', 'Top queried topics:');
+        for (const [i, t] of summary.topTopics.entries()) {
+            lines.push(`  ${i + 1}. ${t.topic} — ${t.count} queries`);
+        }
+    }
+    if (summary.topRecalledDocs.length > 0) {
+        lines.push('', 'Top recalled documents:');
+        for (const [i, d] of summary.topRecalledDocs.entries()) {
+            lines.push(`  ${i + 1}. ${d.path} — ${d.count} queries`);
+        }
+    }
+    if (summary.knowledgeGaps.length > 0) {
+        lines.push('', 'Knowledge gaps (asked but unanswered):');
+        for (const [i, g] of summary.knowledgeGaps.entries()) {
+            lines.push(`  ${i + 1}. "${g.topic}" — ${g.count} unanswered queries`);
+        }
+        lines.push("  → Run 'brv curate' on these topics to close the gap");
+    }
+    return lines.join('\n');
+}

package/dist/server/infra/usecase/query-log-use-case.d.ts

@@ -0,0 +1,31 @@
+import type { ITerminal } from '../../core/interfaces/i-terminal.js';
+import type { IQueryLogStore, QueryLogStatus, QueryLogTier } from '../../core/interfaces/storage/i-query-log-store.js';
+import type { IQueryLogUseCase } from '../../core/interfaces/usecase/i-query-log-use-case.js';
+type QueryLogUseCaseDeps = {
+    queryLogStore: IQueryLogStore;
+    terminal: ITerminal;
+};
+/**
+ * Use case for displaying query log entries.
+ *
+ * Reads directly from FileQueryLogStore — no daemon connection required.
+ */
+export declare class QueryLogUseCase implements IQueryLogUseCase {
+    private readonly deps;
+    constructor(deps: QueryLogUseCaseDeps);
+    run({ after, before, detail, format, id, limit, status, tier, }: {
+        after?: number;
+        before?: number;
+        detail?: boolean;
+        format?: 'json' | 'text';
+        id?: string;
+        limit?: number;
+        status?: QueryLogStatus[];
+        tier?: QueryLogTier[];
+    }): Promise<void>;
+    private log;
+    private logJson;
+    private showDetail;
+    private showList;
+}
+export {};

package/dist/server/infra/usecase/query-log-use-case.js

@@ -0,0 +1,128 @@
+import { QUERY_LOG_TIER_LABELS } from '../../core/domain/entities/query-log-entry.js';
+import { formatEntryDuration, formatTimestamp, truncate } from '../../utils/log-format-utils.js';
+/**
+ * Use case for displaying query log entries.
+ *
+ * Reads directly from FileQueryLogStore — no daemon connection required.
+ */
+export class QueryLogUseCase {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run({ after, before, detail = false, format = 'text', id, limit = 10, status, tier, }) {
+        await (id ? this.showDetail(id, format) : this.showList({ after, before, detail, format, limit, status, tier }));
+    }
+    log(msg) {
+        this.deps.terminal.log(msg);
+    }
+    logJson(payload) {
+        this.log(JSON.stringify({ command: 'query view', ...payload, retrievedAt: new Date().toISOString() }, null, 2));
+    }
+    async showDetail(id, format) {
+        const entry = await this.deps.queryLogStore.getById(id);
+        if (!entry) {
+            if (format === 'json') {
+                this.logJson({ data: { error: `Log entry not found: ${id}` }, success: false });
+            }
+            else {
+                this.log(`No query log entry found with ID: ${id}`);
+            }
+            return;
+        }
+        if (format === 'json') {
+            this.logJson({ data: entry, success: true });
+            return;
+        }
+        this.log(`ID:       ${entry.id}`);
+        this.log(`Status:   ${entry.status}`);
+        this.log(`Tier:     ${entry.tier === undefined ? '—' : `${entry.tier} (${QUERY_LOG_TIER_LABELS[entry.tier]})`}`);
+        this.log(`Started:  ${formatTimestamp(entry.startedAt)}`);
+        if (entry.status !== 'processing') {
+            this.log(`Finished: ${formatTimestamp(entry.completedAt)}`);
+            this.log(`Duration: ${formatEntryDuration(entry)}`);
+        }
+        this.log();
+        this.log(`Query: ${entry.query}`);
+        if (entry.matchedDocs.length > 0) {
+            this.log();
+            this.log('Matched Documents:');
+            for (const doc of entry.matchedDocs) {
+                this.log(`  [${doc.score.toFixed(2)}] ${doc.path}`);
+            }
+        }
+        if (entry.searchMetadata) {
+            this.log();
+            this.log('Search Metadata:');
+            this.log(`  Results: ${entry.searchMetadata.resultCount} of ${entry.searchMetadata.totalFound} found`);
+            this.log(`  Top Score: ${entry.searchMetadata.topScore}`);
+            if (entry.searchMetadata.cacheFingerprint) {
+                this.log(`  Cache Fingerprint: ${entry.searchMetadata.cacheFingerprint}`);
+            }
+        }
+        if (entry.status === 'error') {
+            this.log();
+            this.log(`Error: ${entry.error}`);
+        }
+        if (entry.status === 'completed' && entry.response) {
+            this.log();
+            this.log('Response:');
+            this.log(entry.response.split('\n').map((line) => `  ${line}`).join('\n'));
+        }
+    }
+    async showList({ after, before, detail, format, limit, status, tier }) {
+        const hasFilters = Boolean(after !== undefined || before !== undefined || status?.length || tier?.length);
+        const entries = await this.deps.queryLogStore.list({
+            ...(after === undefined ? {} : { after }),
+            ...(before === undefined ? {} : { before }),
+            limit,
+            ...(status?.length ? { status } : {}),
+            ...(tier?.length ? { tier } : {}),
+        });
+        if (format === 'json') {
+            this.logJson({ data: entries, success: true });
+            return;
+        }
+        if (entries.length === 0) {
+            if (hasFilters) {
+                this.log('No query log entries found matching your filters.');
+            }
+            else {
+                this.log('No query log entries found.');
+            }
+            return;
+        }
+        const idWidth = 22;
+        const tierWidth = 6;
+        const statusWidth = 12;
+        const timeWidth = 8;
+        const queryWidth = 40;
+        const header = [
+            'ID'.padEnd(idWidth),
+            'Tier'.padEnd(tierWidth),
+            'Status'.padEnd(statusWidth),
+            'Time'.padEnd(timeWidth),
+            'Query',
+        ].join('  ');
+        this.log(header);
+        this.log('-'.repeat(idWidth + tierWidth + statusWidth + timeWidth + queryWidth + 8));
+        for (const entry of entries) {
+            const duration = formatEntryDuration(entry);
+            const tierBadge = entry.tier === undefined ? '—' : `T${entry.tier}`;
+            const query = truncate(entry.query, queryWidth);
+            const row = [
+                entry.id.padEnd(idWidth),
+                tierBadge.padEnd(tierWidth),
+                entry.status.padEnd(statusWidth),
+                duration.padEnd(timeWidth),
+                query,
+            ].join('  ');
+            this.log(row);
+            if (detail && entry.matchedDocs.length > 0) {
+                for (const doc of entry.matchedDocs) {
+                    this.log(`  [${doc.score.toFixed(2)}] ${doc.path}`);
+                }
+            }
+        }
+    }
+}

package/dist/server/utils/log-format-utils.d.ts

@@ -0,0 +1,5 @@
+import type { QueryLogEntry } from '../core/domain/entities/query-log-entry.js';
+export declare function formatDuration(startedAt: number, completedAt?: number): string;
+export declare function formatEntryDuration(entry: QueryLogEntry): string;
+export declare function formatTimestamp(ms: number): string;
+export declare function truncate(text: string, max: number): string;

package/dist/server/utils/log-format-utils.js

@@ -0,0 +1,23 @@
+export function formatDuration(startedAt, completedAt) {
+    if (completedAt === undefined)
+        return '—';
+    const delta = completedAt - startedAt;
+    if (delta < 1000)
+        return `${delta}ms`;
+    return `${(delta / 1000).toFixed(1)}s`;
+}
+export function formatEntryDuration(entry) {
+    if (entry.status === 'processing')
+        return '—';
+    if (entry.timing)
+        return formatDuration(0, entry.timing.durationMs);
+    return formatDuration(entry.startedAt, entry.completedAt);
+}
+export function formatTimestamp(ms) {
+    return new Date(ms).toISOString().replace('T', ' ').slice(0, 19);
+}
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return text.slice(0, max) + '...';
+}

package/dist/shared/transport/events/config-events.d.ts

@@ -5,7 +5,7 @@ export declare const ConfigEvents: {
     readonly PROJECT_CHANGED: "config:projectChanged";
 };
 export interface ConfigGetEnvironmentResponse {
-    apiBaseUrl: string;
+    iamBaseUrl: string;
     isDevelopment: boolean;
     webAppUrl: string;
 }