byterover-cli 3.8.2 → 3.8.3

package/README.md

@@ -30,6 +30,7 @@ Or download our self-hosted PDF version of the paper [here](https://byterover.de
 
 **Key Features:**
 
+- 🌐 Web dashboard for curating and querying context (`brv webui`)
 - 🖥️ Interactive TUI with REPL interface (React/Ink)
 - 🧠 Context tree and knowledge storage management
 - 🔀 Git-like version control for the context tree (branch, commit, merge, push/pull)
@@ -101,35 +102,6 @@ The REPL auto-configures on first run - no setup needed. Type `/` to discover al
 /query How is authentication implemented?
 ```
 
-## Web UI Development
-
-The web UI supports a local-first development flow for the shared component library.
-
-`npm run dev:ui` uses the git submodule at `packages/byterover-packages/ui` so edits to shared UI components hot-reload immediately in Vite.
-
-```bash
-# Clone with submodules, or initialize them after clone
-git clone --recurse-submodules <repo-url>
-# or
-git submodule update --init --recursive
-
-# Install dependencies
-npm ci
-
-# Start or restart the daemon
-./bin/dev.js restart
-
-# Start the web UI in local development mode
-npm run dev:ui
-```
-
-Notes:
-
-- Edit shared components in `packages/byterover-packages/ui/src`.
-- `npm run dev:ui` uses the submodule source.
-- `npm run build:ui` uses the installed package path.
-- If `/api/ui/config` or transport bootstrap fails, restart the Vite dev server after restarting the daemon.
-
 ## ByteRover Cloud
 
 ByteRover Cloud is a hosted platform for teams to sync, share, and manage context knowledge across projects and machines.
@@ -139,12 +111,12 @@ Everything works locally by default - Cloud adds collaboration and persistence w
 <a href="https://app.byterover.dev"><img src="https://img.shields.io/badge/Try%20ByteRover%20Cloud-Free-blue?style=for-the-badge" alt="Try ByteRover Cloud" /></a>
 </p>
 
-Sign in with your ByteRover account via `/login` (TUI) or
-an [API key](https://app.byterover.dev/settings/keys) (`brv login`) to get started.
+Sign in from the dashboard, or run `brv login` with an [API key](https://app.byterover.dev/settings/keys).
 
 - 🔄 **Team context sync** — push and pull shared knowledge across teammates
 - 📂 **Shared spaces** — organize context across multiple projects and teams
 - 💻 **Multi-machine access** — sync your context tree across devices with cloud backup
+- 💻 **Multi-machine access** — sync your context tree across devices
 - 🧠 **Built-in hosted LLM** — start immediately with limited free usage
 - 👥 **Team management** — manage members, spaces, and permissions via the web app
 - 📊 **Usage analytics** — track seat allocation and monthly credit consumption
@@ -153,10 +125,13 @@ an [API key](https://app.byterover.dev/settings/keys) (`brv login`) to get start
 <details>
 <summary><h2>CLI Usage</h2></summary>
 
+Most users only need `brv webui`. The commands below are for advanced users and automation. Run `brv --help` for the full, up-to-date reference.
+
 ### Core Workflow
 
 ```bash
 brv                  # Start interactive REPL
+brv webui            # Open the ByteRover dashboard (primary UI)
 brv status           # Show project and daemon status
 brv curate           # Add context to knowledge storage
 brv curate view      # View curate history
@@ -245,7 +220,7 @@ Run `brv --help` for the full command reference.
 <details>
 <summary><h2>Supported LLM Providers</h2></summary>
 
-ByteRover CLI supports 18 LLM providers out of the box. Use `brv providers connect` to set up a provider and `brv providers switch` to change the active one.
+ByteRover CLI supports 18 LLM providers out of the box. Connect and switch providers from the dashboard, or use `brv providers connect` / `brv providers switch`.
 
 | Provider | Description |
 |----------|-------------|
@@ -310,13 +285,12 @@ We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for deve
 ByteRover CLI is built and maintained by the [ByteRover team](https://byterover.dev/).
 
 - Join our [Discord](https://discord.com/invite/UMRrpNjh5W) to share projects, ask questions, or just say hi
-- [Report issues](https://github.com/campfirein/byterover-cli/issues) <!-- TODO: ENG-1575 --> on GitHub
+- [Report issues](https://github.com/campfirein/byterover-cli/issues) on GitHub
 - If you enjoy ByteRover CLI, please give us a star on GitHub — it helps a lot!
 - Follow [@kevinnguyendn](https://x.com/kevinnguyendn) on X
 
 ## Contributors
 
-<!-- TODO: ENG-1575 -->
 [![Contributors](https://contrib.rocks/image?repo=campfirein/byterover-cli&max=40&columns=10)](https://github.com/campfirein/byterover-cli/graphs/contributors)
 
 ## Star History

package/dist/oclif/commands/login.d.ts

@@ -1,13 +1,26 @@
 import { Command } from '@oclif/core';
-import { type AuthLoginWithApiKeyResponse } from '../../shared/transport/events/auth-events.js';
+import { type AuthLoginCompletedEvent, type AuthLoginWithApiKeyResponse } from '../../shared/transport/events/auth-events.js';
 import { type DaemonClientOptions } from '../lib/daemon-client.js';
+export interface LoginOAuthOptions extends DaemonClientOptions {
+    /** Max time to wait for LOGIN_COMPLETED after the browser opens. */
+    oauthTimeoutMs?: number;
+    /** Invoked with the auth URL once the daemon has started the flow. */
+    onAuthUrl?: (authUrl: string) => void;
+}
 export default class Login extends Command {
     static description: string;
     static examples: string[];
     static flags: {
-        'api-key': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
+    /** Gates the OAuth flow. DISPLAY/WAYLAND_DISPLAY deliberately not checked — unset on macOS/Windows, would false-positive. */
+    protected canOpenBrowser(): boolean;
     protected loginWithApiKey(apiKey: string, options?: DaemonClientOptions): Promise<AuthLoginWithApiKeyResponse>;
+    protected loginWithOAuth(options?: LoginOAuthOptions): Promise<AuthLoginCompletedEvent>;
     run(): Promise<void>;
+    private emitError;
+    private emitSuccess;
+    private runApiKey;
+    private runOAuth;
 }

package/dist/oclif/commands/login.js

@@ -1,20 +1,24 @@
 import { Command, Flags } from '@oclif/core';
-import { AuthEvents } from '../../shared/transport/events/auth-events.js';
+import { AuthEvents, } from '../../shared/transport/events/auth-events.js';
 import { formatConnectionError, withDaemonRetry } from '../lib/daemon-client.js';
 import { writeJsonResponse } from '../lib/json-response.js';
+const DEFAULT_OAUTH_TIMEOUT_MS = 5 * 60 * 1000;
 export default class Login extends Command {
     static description = 'Authenticate with ByteRover for cloud sync features (optional for local usage)';
     static examples = [
+        '# Browser OAuth (default)',
+        '<%= config.bin %> <%= command.id %>',
+        '',
+        '# API key (for CI / headless environments)',
         '<%= config.bin %> <%= command.id %> --api-key <key>',
         '',
         '# JSON output (for automation)',
-        '<%= config.bin %> <%= command.id %> --api-key <key> --format json',
+        '<%= config.bin %> <%= command.id %> --format json',
     ];
     static flags = {
         'api-key': Flags.string({
             char: 'k',
-            description: 'API key for authentication (get yours at https://app.byterover.dev/settings/keys)',
-            required: true,
+            description: 'API key for headless/CI login (get yours at https://app.byterover.dev/settings/keys). Omit to use the browser OAuth flow.',
         }),
         format: Flags.string({
             default: 'text',
@@ -22,44 +26,117 @@ export default class Login extends Command {
             options: ['text', 'json'],
         }),
     };
+    /** Gates the OAuth flow. DISPLAY/WAYLAND_DISPLAY deliberately not checked — unset on macOS/Windows, would false-positive. */
+    canOpenBrowser() {
+        // Either stream not a TTY means piped/scripted/CI — no interactive user to complete OAuth.
+        if (process.stdout.isTTY !== true || process.stdin.isTTY !== true)
+            return false;
+        // SSH has a TTY but can't reach the user's local browser.
+        if (process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY)
+            return false;
+        return true;
+    }
     async loginWithApiKey(apiKey, options) {
         return withDaemonRetry(async (client) => client.requestWithAck(AuthEvents.LOGIN_WITH_API_KEY, { apiKey }), options);
     }
+    async loginWithOAuth(options) {
+        const timeoutMs = options?.oauthTimeoutMs ?? DEFAULT_OAUTH_TIMEOUT_MS;
+        return withDaemonRetry(async (client) => {
+            // Subscribe *before* initiating, so a fast callback cannot race past us.
+            let unsubscribe;
+            let timer;
+            const completion = new Promise((resolve, reject) => {
+                timer = setTimeout(() => {
+                    unsubscribe?.();
+                    timer = undefined;
+                    reject(new Error(`Login timed out after ${Math.round(timeoutMs / 1000)}s`));
+                }, timeoutMs);
+                unsubscribe = client.on(AuthEvents.LOGIN_COMPLETED, (data) => {
+                    if (timer) {
+                        clearTimeout(timer);
+                        timer = undefined;
+                    }
+                    unsubscribe?.();
+                    resolve(data);
+                });
+            });
+            try {
+                const startResponse = await client.requestWithAck(AuthEvents.START_LOGIN);
+                options?.onAuthUrl?.(startResponse.authUrl);
+                return await completion;
+            }
+            catch (error) {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                unsubscribe?.();
+                throw error;
+            }
+        }, options);
+    }
     async run() {
         const { flags } = await this.parse(Login);
         const apiKey = flags['api-key'];
-        const format = (flags.format ?? 'text');
+        const format = flags.format === 'json' ? 'json' : 'text';
+        if (!apiKey && !this.canOpenBrowser()) {
+            this.emitError(format, 'Cannot open a local browser here (non-interactive shell or SSH session). Use --api-key for headless login (get yours at https://app.byterover.dev/settings/keys).');
+            return;
+        }
         try {
-            if (format === 'text') {
-                this.log('Logging in...');
-            }
-            const response = await this.loginWithApiKey(apiKey);
-            if (response.success) {
-                if (format === 'json') {
-                    writeJsonResponse({ command: 'login', data: { userEmail: response.userEmail }, success: true });
-                }
-                else {
-                    this.log(`Logged in as ${response.userEmail}`);
-                }
-            }
-            else {
-                const errorMessage = response.error ?? 'Authentication failed';
-                if (format === 'json') {
-                    writeJsonResponse({ command: 'login', data: { error: errorMessage }, success: false });
-                }
-                else {
-                    this.log(errorMessage);
-                }
-            }
+            await (apiKey ? this.runApiKey(apiKey, format) : this.runOAuth(format));
         }
         catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Login failed';
+            const message = formatConnectionError(error);
             if (format === 'json') {
-                writeJsonResponse({ command: 'login', data: { error: errorMessage }, success: false });
+                this.emitError(format, message);
             }
             else {
-                this.log(formatConnectionError(error));
+                this.log(message);
             }
         }
     }
+    emitError(format, message) {
+        if (format === 'json') {
+            writeJsonResponse({ command: 'login', data: { error: message }, success: false });
+        }
+        else {
+            this.log(message);
+        }
+    }
+    emitSuccess(format, userEmail) {
+        if (format === 'json') {
+            writeJsonResponse({ command: 'login', data: { userEmail }, success: true });
+        }
+        else {
+            this.log(userEmail ? `Logged in as ${userEmail}` : 'Logged in successfully');
+        }
+    }
+    async runApiKey(apiKey, format) {
+        if (format === 'text') {
+            this.log('Logging in...');
+        }
+        const response = await this.loginWithApiKey(apiKey);
+        if (response.success) {
+            this.emitSuccess(format, response.userEmail);
+        }
+        else {
+            this.emitError(format, response.error ?? 'Authentication failed');
+        }
+    }
+    async runOAuth(format) {
+        const onAuthUrl = (authUrl) => {
+            if (format === 'text') {
+                this.log('Opening browser for authentication...');
+                this.log(`If the browser did not open, visit: ${authUrl}`);
+            }
+        };
+        const result = await this.loginWithOAuth({ onAuthUrl });
+        if (result.success) {
+            this.emitSuccess(format, result.user?.email);
+        }
+        else {
+            this.emitError(format, result.error ?? 'Authentication failed');
+        }
+    }
 }

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

@@ -29,6 +29,9 @@ export default class ProviderList extends Command {
                 const status = p.isCurrent ? chalk.green('(current)') : p.isConnected ? chalk.yellow('(connected)') : '';
                 const authBadge = p.authMethod === 'oauth' ? chalk.cyan('[OAuth]') : p.authMethod === 'api-key' ? chalk.dim('[API Key]') : '';
                 this.log(`  ${p.name} [${p.id}] ${status} ${authBadge}`.trimEnd());
+                if (p.description) {
+                    this.log(`    ${chalk.dim(p.description)}`);
+                }
             }
         }
         catch (error) {

package/dist/server/core/domain/entities/provider-registry.js

@@ -26,7 +26,7 @@ export const PROVIDER_REGISTRY = {
     byterover: {
         baseUrl: '',
         category: 'popular',
-        description: 'Built-in LLM, logged-in ByteRover account required. Limited free usage.',
+        description: 'Built-in LLM, ByteRover account required. Limited free usage.',
         headers: {},
         id: 'byterover',
         modelsEndpoint: '',
@@ -187,7 +187,7 @@ export const PROVIDER_REGISTRY = {
         baseUrl: '',
         category: 'other',
         defaultModel: 'llama3',
-        description: 'Connect any OpenAI-compatible endpoint (Ollama, LM Studio, etc.)',
+        description: 'OpenAI-compatible endpoint (Ollama, LM Studio, etc.)',
         envVars: ['OPENAI_COMPATIBLE_API_KEY'],
         headers: {},
         id: 'openai-compatible',

package/dist/server/infra/webui/webui-middleware.js

@@ -1,6 +1,5 @@
 import express from 'express';
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
 /**
  * Creates an Express app that serves the web UI and config endpoint.
  *
@@ -36,9 +35,11 @@ export function createWebUiMiddleware({ getConfig, webuiDistDir }) {
     // Serve static files from dist/webui/
     if (existsSync(webuiDistDir)) {
         app.use(express.static(webuiDistDir));
-        // SPA fallback: serve index.html for unmatched routes
+        // SPA fallback. `root` scopes send's dotfile check to the relative
+        // path; without it, a dotfile anywhere in the absolute install path
+        // (e.g. ~/.nvm/...) triggers a 404.
         app.get('*splat', (_req, res) => {
-            res.sendFile(join(webuiDistDir, 'index.html'));
+            res.sendFile('index.html', { root: webuiDistDir });
         });
     }
     return app;