byterover-cli 1.7.2 → 2.0.0

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

@@ -0,0 +1,142 @@
+// ── Formatting helpers ────────────────────────────────────────────────────────
+function formatTimestamp(ms) {
+    return new Date(ms).toISOString().replace('T', ' ').slice(0, 19);
+}
+function formatSummary(summary) {
+    const parts = [];
+    if (summary.added > 0)
+        parts.push(`${summary.added} added`);
+    if (summary.updated > 0)
+        parts.push(`${summary.updated} updated`);
+    if (summary.merged > 0)
+        parts.push(`${summary.merged} merged`);
+    if (summary.deleted > 0)
+        parts.push(`${summary.deleted} deleted`);
+    if (summary.failed > 0)
+        parts.push(`${summary.failed} failed`);
+    return parts.length > 0 ? parts.join(', ') : '—';
+}
+function formatOperationLine(op) {
+    const icon = op.status === 'success' ? '✓' : '✗';
+    return `  ${icon} [${op.type}] ${op.path}${op.message ? ` — ${op.message}` : ''}`;
+}
+// ── CurateLogUseCase ──────────────────────────────────────────────────────────
+/**
+ * Use case for displaying curate log entries.
+ *
+ * Reads directly from FileCurateLogStore — no daemon connection required.
+ */
+export class CurateLogUseCase {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async run({ after, before, detail = false, format = 'text', id, limit = 10, status, }) {
+        await (id
+            ? this.showDetail(id, format)
+            : this.showList({ after, before, detail, format, limit, status }));
+    }
+    // ── Private methods ─────────────────────────────────────────────────────────
+    log(msg) {
+        this.deps.terminal.log(msg);
+    }
+    logJson(payload) {
+        this.log(JSON.stringify({ command: 'curate view', ...payload, retrievedAt: new Date().toISOString() }, null, 2));
+    }
+    async showDetail(id, format) {
+        const entry = await this.deps.curateLogStore.getById(id);
+        if (!entry) {
+            if (format === 'json') {
+                this.logJson({ data: { error: `Log entry not found: ${id}` }, success: false });
+            }
+            else {
+                this.log(`No curate log entry found with ID: ${id}`);
+            }
+            return;
+        }
+        if (format === 'json') {
+            this.logJson({ data: entry, success: true });
+            return;
+        }
+        // Text format
+        this.log(`ID:       ${entry.id}`);
+        this.log(`Status:   ${entry.status}`);
+        this.log(`Started:  ${formatTimestamp(entry.startedAt)}`);
+        if (entry.status !== 'processing') {
+            this.log(`Finished: ${formatTimestamp(entry.completedAt)}`);
+        }
+        this.log();
+        this.log('Input:');
+        if (entry.input.context)
+            this.log(`  Context: ${entry.input.context.slice(0, 200)}${entry.input.context.length > 200 ? '...' : ''}`);
+        if (entry.input.files?.length)
+            this.log(`  Files:   ${entry.input.files.join(', ')}`);
+        if (entry.input.folders?.length)
+            this.log(`  Folders: ${entry.input.folders.join(', ')}`);
+        if (entry.operations.length > 0) {
+            this.log();
+            this.log('Operations:');
+            for (const op of entry.operations) {
+                this.log(formatOperationLine(op));
+            }
+        }
+        this.log();
+        this.log(`Summary: ${formatSummary(entry.summary)}`);
+        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.slice(0, 500)}${entry.response.length > 500 ? '...' : ''}`);
+        }
+    }
+    async showList({ after, before, detail, format, limit, status }) {
+        const hasFilters = Boolean(after !== undefined || before !== undefined || status?.length);
+        const entries = await this.deps.curateLogStore.list({
+            ...(after === undefined ? {} : { after }),
+            ...(before === undefined ? {} : { before }),
+            limit,
+            ...(status?.length ? { status } : {}),
+        });
+        if (format === 'json') {
+            this.logJson({ data: entries, success: true });
+            return;
+        }
+        if (entries.length === 0) {
+            if (hasFilters) {
+                this.log('No curate log entries found matching your filters.');
+            }
+            else {
+                this.log('No curate log entries found.');
+                this.log('Run "brv curate" to add context — logs are recorded automatically.');
+            }
+            return;
+        }
+        // Table header
+        const idWidth = 22;
+        const statusWidth = 12;
+        const opsWidth = 20;
+        const timeWidth = 20;
+        const header = [
+            'ID'.padEnd(idWidth),
+            'Status'.padEnd(statusWidth),
+            'Operations'.padEnd(opsWidth),
+            'Timestamp',
+        ].join('  ');
+        this.log(header);
+        this.log('─'.repeat(idWidth + statusWidth + opsWidth + timeWidth + 6));
+        for (const entry of entries) {
+            const timestamp = entry.status === 'processing' ? '(processing...)' : formatTimestamp(entry.startedAt);
+            const ops = entry.status === 'processing' ? '—' : formatSummary(entry.summary);
+            const row = [entry.id.padEnd(idWidth), entry.status.padEnd(statusWidth), ops.padEnd(opsWidth), timestamp].join('  ');
+            this.log(row);
+            if (detail && entry.operations.length > 0) {
+                for (const op of entry.operations) {
+                    this.log(formatOperationLine(op));
+                }
+            }
+        }
+    }
+}

package/dist/server/templates/sections/brv-instructions.md

@@ -70,6 +70,13 @@ brv curate --folder src/auth/  # folder-only mode
 **BAD:** `brv curate "Fixed auth"` (too vague), `brv curate -f file.ts "text"` (wrong order)
 **BAD:** `brv curate -folder src/` (use `-d` or `--folder`, NOT `-folder`)
 
+**After curating**, verify what was stored using the logId printed on completion:
+```bash
+brv curate view <logId>       # Full detail: input, operations, summary
+brv curate view               # List recent curates with status
+brv curate view --help        # All filter options
+```
+
 **⚠️ CRITICAL - LONG CONVERSATIONS:**
 If you modify code 10 times in a conversation, curate 10 times. Do NOT batch or skip. Each code change = immediate curate before moving on.
 
@@ -102,3 +109,4 @@ Non-code task → Just respond normally
 > **⚠️ REMINDER: Don't forget!**
 > - `brv query` → BEFORE starting code task
 > - `brv curate` → AFTER each code change (don't batch!)
+> - `brv curate view` → verify what was stored (use logId printed on completion)

package/dist/server/templates/sections/command-reference.md

@@ -2,8 +2,11 @@
 
 ## Available Commands
 
-- `brv curate` - Curate context to the context tree
+- `brv curate` - Curate context to the context tree (returns a logId on completion)
+- `brv curate view` - List curate history (last 10 entries by default)
+- `brv curate view <logId>` - Full detail for a specific entry: all files and operations performed (logId returned by `brv curate`)
+- `brv curate view --detail` - List entries with their file operations visible (no logId needed)
 - `brv query` - Query and retrieve information from the context tree
 - `brv status` - Show CLI status and project information
 
-Run `brv query --help` for query instruction and `brv curate --help` for curation instruction.
+Run `brv query --help` for query instruction and `brv curate --help` / `brv curate view --help` for curation options.

package/dist/server/templates/sections/workflow.md

@@ -23,6 +23,8 @@ Use `brv curate` **after** you learn or create something valuable:
 - Made architectural/design decisions
 - Found a bug root cause or fix pattern
 
+After curating, use `brv curate view <logId>` to verify what was stored (logId printed on completion).
+
 ## Context Tree Guideline
 
 Good context is:

package/dist/server/templates/skill/SKILL.md

@@ -1,91 +1,170 @@
 ---
 name: byterover
-description: "Manages project knowledge using ByteRover context tree. Provides two operations: query (retrieve knowledge) and curate (store knowledge). Invoke when user requests information lookup, pattern discovery, or knowledge persistence."
+description: "You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations."
 ---
 
-# ByteRover Context Tree
+# ByteRover Knowledge Management
 
-A project-level knowledge repository that persists across sessions. Use it to avoid re-discovering patterns, conventions, and decisions.
+Use the `brv` CLI to manage your project's long-term memory.
+Install: `npm install -g byterover-cli`
+Knowledge is stored in `.brv/context-tree/` as human-readable Markdown files.
 
-## Why Use ByteRover
+**No authentication needed.** `brv query` and `brv curate` work out of the box. Login is only required for cloud sync (`push`/`pull`/`space`) — ignore those if you don't need cloud features.
 
-- **Query before working**: Get existing knowledge about patterns, conventions, and past decisions before implementing
-- **Curate after learning**: Capture insights, decisions, and bug fixes so future sessions start informed
+## Workflow
+1.  **Before Thinking:** Run `brv query` to understand existing patterns.
+2.  **After Implementing:** Run `brv curate` to save new patterns/decisions.
 
-## Quick Reference
+## Commands
 
-| Command | When | Example |
-|---------|------|---------|
-| `brv query "question"` | Before starting work | `brv query "How is auth implemented?"` |
-| `brv curate "context" -f file` | After completing work | `brv curate "JWT 24h expiry" -f auth.ts` |
-| `brv status` | To check prerequisites | `brv status` |
+### 1. Query Knowledge
+**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.
 
-## When to Use
+**Use this skill when:**
+- The user wants you to recall something
+- Your context does not contain information you need
+- You need to recall your capabilities or past actions
+- Before performing any action, to check for relevant rules, criteria, or preferences
 
-**Query** when you need to understand something:
-- "How does X work in this codebase?"
-- "What patterns exist for Y?"
-- "Are there conventions for Z?"
+**Do NOT use this skill when:**
+- The information is already present in your current context
+- The query is about general knowledge, not stored memory
 
-**Curate** when you learned or created something valuable:
-- Implemented a feature using specific patterns
-- Fixed a bug and found root cause
-- Made an architecture decision
+```bash
+brv query "How is authentication implemented?"
+```
+
+### 2. Curate Context
+**Overview**: Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.
 
-## Curate Quality
+**Use this skill when:**
+- The user wants you to remember something
+- The user intentionally curates memory or knowledge
+- There are meaningful memories from user interactions that should be persisted
+- There are important facts about what you do, what you know, or what decisions and actions you have taken
 
-Context must be **specific** and **actionable**:
+**Do NOT use this skill when:**
+- The information is already stored and unchanged
+- The information is transient or only relevant to the current task, or just general knowledge
 
 ```bash
-# Good - specific, explains where and why
-brv curate "Auth uses JWT 24h expiry, tokens in httpOnly cookies" -f src/auth.ts
+brv curate "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
+```
+
+**Include source files** (max 5, project-scoped only):
 
-# Bad - too vague
-brv curate "Fixed auth"
+```bash
+brv curate "Authentication middleware details" -f src/middleware/auth.ts
 ```
 
-**Note:** Context argument must come before `-f` flags. Max 5 files.
+**View curate history:** to check past curations
+- Show recent entries (last 10)
+```bash
+brv curate view
+```
+- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)
+```bash
+brv curate view cur-1739700001000
+```
+- List entries with file operations visible (no logId needed)
+```bash
+brv curate view detail
+```
+- Filter by time and status
+```bash
+brv curate view --since 1h --status completed
+```
+- For all filter options
+```bash
+brv curate view --help
+```
 
-## Best Practices
+### 3. LLM Provider Setup
+`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):
 
-1. **Break down large contexts** - Run multiple `brv curate` commands for complex topics rather than one massive context. Smaller chunks are easier to retrieve and update.
+```bash
+brv providers connect byterover
+```
 
-2. **Let ByteRover read files** - Don't read files yourself before curating. Use `-f` flags to let ByteRover read them directly:
-   ```bash
-   # Good - ByteRover reads the files
-   brv curate "Auth implementation details" -f src/auth.ts -f src/middleware/jwt.ts
+To use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:
 
-   # Wasteful - reading files twice
-   # [agent reads files] then brv curate "..." -f same-files
-   ```
+```bash
+brv providers list
+brv providers connect openai --api-key sk-xxx --model gpt-4.1
+```
 
-3. **Be specific in queries** - Queries block your workflow. Use precise questions to get faster, more relevant results:
-   ```bash
-   # Good - specific
-   brv query "What validation library is used for API request schemas?"
+### 4. Cloud Sync (Optional)
+**Overview:** Sync your local knowledge with a team via ByteRover's cloud service. Requires ByteRover authentication.
 
-   # Bad - vague, slow
-   brv query "How is validation done?"
-   ```
+**Setup steps:**
+1. Log in: Get an API key from your ByteRover account and authenticate:
+```bash
+brv login --api-key sample-key-string
+```
+2. List available spaces:
+```bash
+brv space list
+```
+Sample output:
+```
+brv space list
+1. human-resources-team (team)
+   - a-department (space)
+   - b-department (space)
+2. marketing-team (team)
+   - c-department (space)
+   - d-department (space)
+```
+3. Connect to a space:
+```bash
+brv space switch --team human-resources-team --name a-department
+```
 
-4. **Signal outdated context** - When curating updates that replace existing knowledge, explicitly tell ByteRover to clean up:
-   ```bash
-   brv curate "OUTDATED: Previous auth used sessions. NEW: Now uses JWT with refresh tokens. Clean up old session-based auth context." -f src/auth.ts
-   ```
+**Cloud sync commands:**
+Once connected, `brv push` and `brv pull` sync with that space.
+```bash
+# Pull team updates
+brv pull
 
-5. **Specify structure expectations** - Guide ByteRover on how to organize the knowledge:
-   ```bash
-   # Specify topics/domains
-   brv curate "Create separate topics for: 1) JWT validation, 2) refresh token flow, 3) logout handling" -f src/auth.ts
+# Push local changes
+brv push
+```
 
-   # Specify detail level
-   brv curate "Document the error handling patterns in detail (at least 30 lines covering all error types)" -f src/errors/
-   ```
+**Switching spaces:**
+- Push local changes first (`brv push`) — switching is blocked if unsaved changes exist.
+- Then switch:
+```bash
+brv space switch --team marketing-team --name d-department
+```
+- The switch automatically pulls context from the new space.
 
-## Prerequisites
+## Data Handling
 
-Run `brv status` first. If errors occur, the agent cannot fix them—instruct the user to take action in their brv terminal. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for details.
+**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.
 
----
+**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.
+
+**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv push`.
+
+**Cloud sync**: `brv push` and `brv pull` require authentication (`brv login`) and send knowledge to ByteRover's cloud service. All other commands operate without ByteRover authentication.
+
+## Error Handling
+**User Action Required:**
+You MUST show this troubleshooting guide to users when errors occur.
+
+"Not authenticated" | Run `brv login --help` for more details.
+"No provider connected" | Run `brv providers connect byterover` (free, no key needed).
+"Connection failed" / "Instance crashed" | User should kill brv process.
+"Token has expired" / "Token is invalid" | Run `brv login` again to re-authenticate.
+"Billing error" / "Rate limit exceeded" | User should check account credits or wait before retrying.
+
+**Agent-Fixable Errors:**
+You MUST handle these errors gracefully and retry the command after fixing.
+
+"Missing required argument(s)." | Run `brv <command> --help` to see usage instructions.
+"Maximum 5 files allowed" | Reduce to 5 or fewer `-f` flags per curate.
+"File does not exist" | Verify path with `ls`, use relative paths from project root.
+"File type not supported" | Only text, image, PDF, and office files are supported.
 
-**See also:** [WORKFLOWS.md](WORKFLOWS.md) for detailed patterns and examples, [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for error handling
+### Quick Diagnosis
+Run `brv status` to check authentication, project, and provider state.

package/dist/server/utils/config-xdg-sync.d.ts

@@ -0,0 +1,13 @@
+import type { BrvConfig } from '../core/domain/entities/brv-config.js';
+/**
+ * Clones a BrvConfig to the XDG project data directory.
+ * IDE plugins read the XDG path to discover project configs
+ * without needing to be inside the project directory.
+ *
+ * Best-effort: failures are silently ignored since XDG sync
+ * is a convenience feature that should never block the caller.
+ *
+ * @param config - The config to persist
+ * @param projectPath - The project's working directory (used to derive XDG path)
+ */
+export declare function syncConfigToXdg(config: BrvConfig, projectPath: string): Promise<void>;

package/dist/server/utils/config-xdg-sync.js

@@ -0,0 +1,25 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PROJECT_CONFIG_FILE } from '../constants.js';
+import { getProjectDataDir } from './path-utils.js';
+/**
+ * Clones a BrvConfig to the XDG project data directory.
+ * IDE plugins read the XDG path to discover project configs
+ * without needing to be inside the project directory.
+ *
+ * Best-effort: failures are silently ignored since XDG sync
+ * is a convenience feature that should never block the caller.
+ *
+ * @param config - The config to persist
+ * @param projectPath - The project's working directory (used to derive XDG path)
+ */
+export async function syncConfigToXdg(config, projectPath) {
+    try {
+        const xdgDir = getProjectDataDir(projectPath);
+        await mkdir(xdgDir, { recursive: true });
+        await writeFile(join(xdgDir, PROJECT_CONFIG_FILE), JSON.stringify(config.toJson(), undefined, 2), 'utf8');
+    }
+    catch {
+        // Best-effort — XDG sync failure should not block the caller
+    }
+}

package/dist/server/utils/curate-result-parser.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import type { CurateLogOperation } from '../core/domain/entities/curate-log-entry.js';
+import type { LlmToolResultEvent } from '../core/domain/transport/schemas.js';
+export declare const CurateOperationSchema: z.ZodObject<{
+    filePath: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    path: z.ZodString;
+    status: z.ZodEnum<["failed", "success"]>;
+    type: z.ZodEnum<["ADD", "DELETE", "MERGE", "UPDATE", "UPSERT"]>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "ADD" | "DELETE" | "MERGE" | "UPDATE" | "UPSERT";
+    status: "failed" | "success";
+    message?: string | undefined;
+    filePath?: string | undefined;
+}, {
+    path: string;
+    type: "ADD" | "DELETE" | "MERGE" | "UPDATE" | "UPSERT";
+    status: "failed" | "success";
+    message?: string | undefined;
+    filePath?: string | undefined;
+}>;
+export declare const CurateResultSchema: z.ZodObject<{
+    applied: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        filePath: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        status: z.ZodEnum<["failed", "success"]>;
+        type: z.ZodEnum<["ADD", "DELETE", "MERGE", "UPDATE", "UPSERT"]>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "ADD" | "DELETE" | "MERGE" | "UPDATE" | "UPSERT";
+        status: "failed" | "success";
+        message?: string | undefined;
+        filePath?: string | undefined;
+    }, {
+        path: string;
+        type: "ADD" | "DELETE" | "MERGE" | "UPDATE" | "UPSERT";
+        status: "failed" | "success";
+        message?: string | undefined;
+        filePath?: string | undefined;
+    }>, "many">>;
+    summary: z.ZodOptional<z.ZodObject<{
+        added: z.ZodOptional<z.ZodNumber>;
+        deleted: z.ZodOptional<z.ZodNumber>;
+        failed: z.ZodOptional<z.ZodNumber>;
+        merged: z.ZodOptional<z.ZodNumber>;
+        updated: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        failed?: number | undefined;
+        updated?: number | undefined;
+        deleted?: number | undefined;
+        added?: number | undefined;
+        merged?: number | undefined;
+    }, {
+        failed?: number | undefined;
+        updated?: number | undefined;
+        deleted?: number | undefined;
+        added?: number | undefined;
+        merged?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    summary?: {
+        failed?: number | undefined;
+        updated?: number | undefined;
+        deleted?: number | undefined;
+        added?: number | undefined;
+        merged?: number | undefined;
+    } | undefined;
+    applied?: {
+        path: string;
+        type: "ADD" | "DELETE" | "MERGE" | "UPDATE" | "UPSERT";
+        status: "failed" | "success";
+        message?: string | undefined;
+        filePath?: string | undefined;
+    }[] | undefined;
+}, {
+    summary?: {
+        failed?: number | undefined;
+        updated?: number | undefined;
+        deleted?: number | undefined;
+        added?: number | undefined;
+        merged?: number | undefined;
+    } | undefined;
+    applied?: {
+        path: string;
+        type: "ADD" | "DELETE" | "MERGE" | "UPDATE" | "UPSERT";
+        status: "failed" | "success";
+        message?: string | undefined;
+        filePath?: string | undefined;
+    }[] | undefined;
+}>;
+/**
+ * Extract a curate result from a code_exec sandbox result.
+ *
+ * Supports 4 patterns in order of priority:
+ *  0. `curateResults` — injected by SandboxService accumulator (most reliable)
+ *                       captures ALL tools.curate() calls regardless of how
+ *                       the LLM stores the result (const, var, return, etc.)
+ *  1. `returnValue`   — when the LLM code uses `return await tools.curate(...)`
+ *  2. `stdout`        — when the LLM code uses `console.log(JSON.stringify(...))`
+ *  3. `locals`        — when the LLM code uses `var r = await tools.curate(...)`
+ *                       (var declarations end up in locals; const/let do not)
+ *
+ * For the `locals` strategy, all local values are scanned and any arrays named
+ * `applied` are merged, supporting multiple curate() calls in a single code block.
+ */
+export declare function extractCurateResultFromCodeExec(resultData: Record<string, unknown>): unknown;
+/**
+ * Extract curate operations from an llmservice:toolResult event.
+ *
+ * Only processes `toolName === 'curate'` or `toolName === 'code_exec'`.
+ * Returns an empty array for all other tools.
+ *
+ * The `result` field is always a JSON string (ToolOutputProcessor stringifies all tool
+ * output before emitting the event). We JSON-parse it before extracting operations.
+ *
+ * @param payload - The tool result event payload
+ * @param filter - Optional predicate to filter individual operations (e.g. success-only)
+ */
+export declare function extractCurateOperations(payload: Pick<LlmToolResultEvent, 'result' | 'toolName'>, filter?: (op: CurateLogOperation) => boolean): CurateLogOperation[];