byterover-cli 1.4.0 → 1.6.0

package/dist/infra/storage/provider-keychain-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Provider Keychain Store
+ *
+ * Stores provider API keys securely in the system keychain.
+ * Uses keytar for cross-platform keychain access.
+ */
+import type { IProviderKeychainStore } from '../../core/interfaces/i-provider-keychain-store.js';
+/**
+ * Keychain-based storage for provider API keys.
+ * Uses the system keychain for secure storage:
+ * - macOS: Keychain
+ * - Linux: Secret Service (or encrypted file fallback)
+ * - Windows: Credential Manager
+ */
+export declare class ProviderKeychainStore implements IProviderKeychainStore {
+    /**
+     * Deletes the API key for a provider.
+     */
+    deleteApiKey(providerId: string): Promise<void>;
+    /**
+     * Gets the API key for a provider.
+     */
+    getApiKey(providerId: string): Promise<string | undefined>;
+    /**
+     * Checks if an API key exists for a provider.
+     */
+    hasApiKey(providerId: string): Promise<boolean>;
+    /**
+     * Sets the API key for a provider.
+     */
+    setApiKey(providerId: string, apiKey: string): Promise<void>;
+}
+/**
+ * Creates a provider keychain store instance.
+ * This factory function allows for future platform-specific implementations.
+ */
+export declare function createProviderKeychainStore(): IProviderKeychainStore;

package/dist/infra/storage/provider-keychain-store.js

@@ -0,0 +1,75 @@
+/**
+ * Provider Keychain Store
+ *
+ * Stores provider API keys securely in the system keychain.
+ * Uses keytar for cross-platform keychain access.
+ */
+import keytar from 'keytar';
+const SERVICE_NAME = 'byterover-cli-providers';
+/**
+ * Creates the account name for a provider.
+ * Format: provider:<providerId>
+ */
+function getAccountName(providerId) {
+    return `provider:${providerId}`;
+}
+/**
+ * Keychain-based storage for provider API keys.
+ * Uses the system keychain for secure storage:
+ * - macOS: Keychain
+ * - Linux: Secret Service (or encrypted file fallback)
+ * - Windows: Credential Manager
+ */
+export class ProviderKeychainStore {
+    /**
+     * Deletes the API key for a provider.
+     */
+    async deleteApiKey(providerId) {
+        try {
+            const accountName = getAccountName(providerId);
+            await keytar.deletePassword(SERVICE_NAME, accountName);
+        }
+        catch {
+            // Ignore errors (key may not exist, permissions, etc.)
+        }
+    }
+    /**
+     * Gets the API key for a provider.
+     */
+    async getApiKey(providerId) {
+        try {
+            const accountName = getAccountName(providerId);
+            const apiKey = await keytar.getPassword(SERVICE_NAME, accountName);
+            return apiKey ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Checks if an API key exists for a provider.
+     */
+    async hasApiKey(providerId) {
+        const apiKey = await this.getApiKey(providerId);
+        return apiKey !== undefined;
+    }
+    /**
+     * Sets the API key for a provider.
+     */
+    async setApiKey(providerId, apiKey) {
+        try {
+            const accountName = getAccountName(providerId);
+            await keytar.setPassword(SERVICE_NAME, accountName, apiKey);
+        }
+        catch (error) {
+            throw new Error(`Failed to save API key to keychain: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+/**
+ * Creates a provider keychain store instance.
+ * This factory function allows for future platform-specific implementations.
+ */
+export function createProviderKeychainStore() {
+    return new ProviderKeychainStore();
+}

package/dist/infra/storage/token-store.d.ts

@@ -3,8 +3,9 @@ import type { ITokenStore } from '../../core/interfaces/i-token-store.js';
  * Creates the appropriate token store for the current platform.
  *
  * - WSL: FileTokenStore (encrypted file-based, keychain not available)
- * - macOS/Linux/Windows: KeychainTokenStore (system keychain via keytar)
+ * - Headless Linux: FileTokenStore (no D-Bus/keyring daemon)
+ * - macOS/Windows/Linux with GUI: KeychainTokenStore (system keychain via keytar)
  *
- * @param isWslFn - Optional function to detect WSL (for testing)
+ * @param shouldUseFileFn - Optional function for environment detection (for testing)
  */
-export declare function createTokenStore(isWslFn?: () => boolean): ITokenStore;
+export declare function createTokenStore(shouldUseFileFn?: () => boolean): ITokenStore;

package/dist/infra/storage/token-store.js

@@ -1,14 +1,15 @@
-import { isWsl } from '../../utils/environment-detector.js';
+import { shouldUseFileTokenStore } from '../../utils/environment-detector.js';
 import { FileTokenStore } from './file-token-store.js';
 import { KeychainTokenStore } from './keychain-token-store.js';
 /**
  * Creates the appropriate token store for the current platform.
  *
  * - WSL: FileTokenStore (encrypted file-based, keychain not available)
- * - macOS/Linux/Windows: KeychainTokenStore (system keychain via keytar)
+ * - Headless Linux: FileTokenStore (no D-Bus/keyring daemon)
+ * - macOS/Windows/Linux with GUI: KeychainTokenStore (system keychain via keytar)
  *
- * @param isWslFn - Optional function to detect WSL (for testing)
+ * @param shouldUseFileFn - Optional function for environment detection (for testing)
  */
-export function createTokenStore(isWslFn = isWsl) {
-    return isWslFn() ? new FileTokenStore() : new KeychainTokenStore();
+export function createTokenStore(shouldUseFileFn = shouldUseFileTokenStore) {
+    return shouldUseFileFn() ? new FileTokenStore() : new KeychainTokenStore();
 }

package/dist/infra/team/http-team-service.d.ts

@@ -7,7 +7,7 @@ export type TeamServiceConfig = {
 export declare class HttpTeamService implements ITeamService {
     private readonly config;
     constructor(config: TeamServiceConfig);
-    getTeams(accessToken: string, sessionKey: string, option?: {
+    getTeams(sessionKey: string, option?: {
         fetchAll?: boolean;
         isActive?: boolean;
         limit?: number;

package/dist/infra/team/http-team-service.js

@@ -9,9 +9,9 @@ export class HttpTeamService {
             timeout: 10_000, // Default 10 seconds timeout
         };
     }
-    async getTeams(accessToken, sessionKey, option) {
+    async getTeams(sessionKey, option) {
         try {
-            const httpClient = new AuthenticatedHttpClient(accessToken, sessionKey);
+            const httpClient = new AuthenticatedHttpClient(sessionKey);
             // Scenario 1: Fetch all automatically via auto-pagination
             if (option?.fetchAll === true) {
                 return await this.fetchAllTeams(httpClient, option?.isActive);

package/dist/infra/terminal/headless-terminal.d.ts

@@ -0,0 +1,91 @@
+import type { ConfirmOptions, FileSelectorItem, FileSelectorOptions, InputOptions, ITerminal, SearchOptions, SelectOptions } from '../../core/interfaces/i-terminal.js';
+/**
+ * Output format for headless terminal.
+ * - 'text': Human-readable text output
+ * - 'json': NDJSON (newline-delimited JSON) for machine parsing
+ */
+export type HeadlessOutputFormat = 'json' | 'text';
+/**
+ * JSON message types for structured output.
+ */
+export type HeadlessMessageType = 'action_start' | 'action_stop' | 'error' | 'log' | 'result' | 'warning';
+/**
+ * Structured JSON output message.
+ */
+export interface HeadlessJsonMessage {
+    actionId?: string;
+    id: string;
+    message: string;
+    timestamp: string;
+    type: HeadlessMessageType;
+}
+/**
+ * Options for creating a HeadlessTerminal.
+ */
+export interface HeadlessTerminalOptions {
+    /**
+     * Stream for errors (defaults to process.stderr).
+     */
+    errorStream?: NodeJS.WritableStream;
+    /**
+     * If true, throw HeadlessPromptError when a prompt cannot be answered.
+     * If false, use sensible defaults (first choice, false for confirm, etc.)
+     * @default true
+     */
+    failOnPrompt?: boolean;
+    /**
+     * Output format: 'text' for human readable, 'json' for machine parsing.
+     * @default 'text'
+     */
+    outputFormat?: HeadlessOutputFormat;
+    /**
+     * Stream for output (defaults to process.stdout).
+     */
+    outputStream?: NodeJS.WritableStream;
+    /**
+     * Default values for prompts, keyed by prompt message or prompt type.
+     * Used to answer prompts automatically in headless mode.
+     */
+    promptDefaults?: Record<string, unknown>;
+}
+/**
+ * Terminal implementation for headless/non-interactive mode.
+ * Outputs to stdout/stderr and handles prompts via defaults or fails gracefully.
+ */
+export declare class HeadlessTerminal implements ITerminal {
+    private currentActionId;
+    private readonly errorOutput;
+    private readonly failOnPrompt;
+    private readonly output;
+    private readonly outputFormat;
+    private readonly promptDefaults;
+    constructor(options?: HeadlessTerminalOptions);
+    actionStart(message: string): void;
+    actionStop(message?: string): void;
+    confirm(options: ConfirmOptions): Promise<boolean>;
+    error(message: string): void;
+    fileSelector(options: FileSelectorOptions): Promise<FileSelectorItem | null>;
+    input(options: InputOptions): Promise<string>;
+    log(message?: string): void;
+    search<T>(options: SearchOptions<T>): Promise<T>;
+    select<T>(options: SelectOptions<T>): Promise<T>;
+    warn(message: string): void;
+    /**
+     * Write final response with success/error status.
+     */
+    writeFinalResponse(response: {
+        command: string;
+        data?: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
+        success: boolean;
+    }): void;
+    /**
+     * Write final result in JSON format (convenience method for commands).
+     */
+    writeResult(data: Record<string, unknown>): void;
+    private getDefault;
+    private writeJson;
+}

package/dist/infra/terminal/headless-terminal.js

@@ -0,0 +1,211 @@
+import { randomUUID } from 'node:crypto';
+import { HeadlessPromptError } from '../../core/domain/errors/headless-prompt-error.js';
+/**
+ * Terminal implementation for headless/non-interactive mode.
+ * Outputs to stdout/stderr and handles prompts via defaults or fails gracefully.
+ */
+export class HeadlessTerminal {
+    currentActionId = null;
+    errorOutput;
+    failOnPrompt;
+    output;
+    outputFormat;
+    promptDefaults;
+    constructor(options = {}) {
+        this.outputFormat = options.outputFormat ?? 'text';
+        this.promptDefaults = options.promptDefaults ?? {};
+        this.failOnPrompt = options.failOnPrompt ?? true;
+        this.output = options.outputStream ?? process.stdout;
+        this.errorOutput = options.errorStream ?? process.stderr;
+    }
+    // ==================== Output Methods ====================
+    actionStart(message) {
+        this.currentActionId = randomUUID();
+        if (this.outputFormat === 'json') {
+            this.writeJson({
+                actionId: this.currentActionId,
+                id: randomUUID(),
+                message,
+                timestamp: new Date().toISOString(),
+                type: 'action_start',
+            });
+        }
+        // In text mode, suppress action start for cleaner output
+    }
+    actionStop(message) {
+        if (this.outputFormat === 'json' && this.currentActionId) {
+            this.writeJson({
+                actionId: this.currentActionId,
+                id: randomUUID(),
+                message: message ?? '',
+                timestamp: new Date().toISOString(),
+                type: 'action_stop',
+            });
+        }
+        this.currentActionId = null;
+    }
+    async confirm(options) {
+        // Check for explicit default in promptDefaults
+        const defaultValue = this.getDefault('confirm', options.message);
+        if (defaultValue !== undefined) {
+            return Boolean(defaultValue);
+        }
+        // Use options.default if provided
+        if (options.default !== undefined) {
+            return options.default;
+        }
+        // Fail or return false
+        if (this.failOnPrompt) {
+            throw new HeadlessPromptError('confirm', options.message);
+        }
+        return false;
+    }
+    error(message) {
+        if (this.outputFormat === 'json') {
+            this.writeJson({
+                id: randomUUID(),
+                message,
+                timestamp: new Date().toISOString(),
+                type: 'error',
+            });
+        }
+        else {
+            this.errorOutput.write(`Error: ${message}\n`);
+        }
+    }
+    async fileSelector(options) {
+        // Check for explicit default in promptDefaults
+        const defaultValue = this.getDefault('file_selector', options.message);
+        if (defaultValue !== undefined && typeof defaultValue === 'string') {
+            return {
+                isDirectory: options.type === 'directory',
+                name: defaultValue.split('/').pop() ?? defaultValue,
+                path: defaultValue,
+            };
+        }
+        // Allow cancel if specified
+        if (options.allowCancel) {
+            return null;
+        }
+        // Fail
+        if (this.failOnPrompt) {
+            throw new HeadlessPromptError('file_selector', options.message);
+        }
+        return null;
+    }
+    // ==================== Input Methods ====================
+    async input(options) {
+        // Check for explicit default in promptDefaults
+        const defaultValue = this.getDefault('input', options.message);
+        if (defaultValue !== undefined) {
+            const value = String(defaultValue);
+            // Validate if validator is provided
+            if (options.validate) {
+                const validationResult = options.validate(value);
+                if (validationResult !== true) {
+                    const errorMsg = typeof validationResult === 'string' ? validationResult : 'Validation failed';
+                    throw new HeadlessPromptError('input', `${options.message} (validation error: ${errorMsg})`);
+                }
+            }
+            return value;
+        }
+        // Fail
+        if (this.failOnPrompt) {
+            throw new HeadlessPromptError('input', options.message);
+        }
+        return '';
+    }
+    log(message) {
+        if (this.outputFormat === 'json') {
+            this.writeJson({
+                id: randomUUID(),
+                message: message ?? '',
+                timestamp: new Date().toISOString(),
+                type: 'log',
+            });
+        }
+        else {
+            this.output.write((message ?? '') + '\n');
+        }
+    }
+    async search(options) {
+        // Search prompts require user interaction - always fail in headless mode
+        // unless a default is explicitly provided
+        const defaultValue = this.getDefault('search', options.message);
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        throw new HeadlessPromptError('search', options.message);
+    }
+    async select(options) {
+        // Check for explicit default in promptDefaults (by value or name)
+        const defaultValue = this.getDefault('select', options.message);
+        if (defaultValue !== undefined) {
+            const choice = options.choices.find((c) => c.value === defaultValue || c.name === defaultValue);
+            if (choice) {
+                return choice.value;
+            }
+        }
+        // Fail or return first choice
+        if (this.failOnPrompt) {
+            throw new HeadlessPromptError('select', options.message, options.choices.map((c) => c.name));
+        }
+        // Return first choice as fallback
+        if (options.choices.length > 0) {
+            return options.choices[0].value;
+        }
+        throw new HeadlessPromptError('select', options.message, []);
+    }
+    warn(message) {
+        if (this.outputFormat === 'json') {
+            this.writeJson({
+                id: randomUUID(),
+                message,
+                timestamp: new Date().toISOString(),
+                type: 'warning',
+            });
+        }
+        else {
+            this.errorOutput.write(`Warning: ${message}\n`);
+        }
+    }
+    // ==================== Helper Methods ====================
+    /**
+     * Write final response with success/error status.
+     */
+    writeFinalResponse(response) {
+        if (this.outputFormat === 'json') {
+            this.output.write(JSON.stringify({
+                ...response,
+                timestamp: new Date().toISOString(),
+            }) + '\n');
+        }
+    }
+    /**
+     * Write final result in JSON format (convenience method for commands).
+     */
+    writeResult(data) {
+        if (this.outputFormat === 'json') {
+            this.writeJson({
+                id: randomUUID(),
+                message: JSON.stringify(data),
+                timestamp: new Date().toISOString(),
+                type: 'result',
+            });
+        }
+    }
+    getDefault(promptType, promptMessage) {
+        // First check by exact message
+        if (this.promptDefaults[promptMessage] !== undefined) {
+            return this.promptDefaults[promptMessage];
+        }
+        // Then check by prompt type
+        if (this.promptDefaults[promptType] !== undefined) {
+            return this.promptDefaults[promptType];
+        }
+        return undefined;
+    }
+    writeJson(data) {
+        this.output.write(JSON.stringify(data) + '\n');
+    }
+}

package/dist/infra/transport/socket-io-transport-client.d.ts

@@ -11,6 +11,8 @@ import type { ConnectionState, ConnectionStateHandler, EventHandler, ITransportC
  * - Auto-rejoins rooms after reconnect
  */
 export declare class SocketIOTransportClient implements ITransportClient {
+    /** Buffer for events that arrive before handlers are registered */
+    private bufferedEvents;
     private readonly config;
     private eventHandlers;
     /** Track force reconnect attempt count for backoff calculation */
@@ -86,6 +88,12 @@ export declare class SocketIOTransportClient implements ITransportClient {
      * Re-triggers reconnection if not connected and force reconnect has given up.
      */
     private handleWakeFromSleep;
+    /**
+     * Register socket listeners for all events that should be buffered.
+     * Called on connect to ensure critical events can be captured even before
+     * handlers subscribe. This prevents race conditions in TUI initialization.
+     */
+    private registerBufferedEventListeners;
     /**
      * Register all pending event handlers on the socket.
      * Called after successful connection to handle handlers added before connect().
@@ -94,6 +102,10 @@ export declare class SocketIOTransportClient implements ITransportClient {
     /**
      * Register a socket listener for an event if not already registered.
      * Uses registeredSocketEvents set to prevent duplicates.
+     *
+     * For critical events (task lifecycle, LLM events), buffers incoming events
+     * if no handlers are registered yet. This prevents race conditions where
+     * broadcast-room events arrive before TUI components subscribe.
      */
     private registerSocketEventIfNeeded;
     /**
@@ -111,6 +123,14 @@ export declare class SocketIOTransportClient implements ITransportClient {
      * Remove socket listener for an event and clear tracking.
      */
     private removeSocketEventListener;
+    /**
+     * Replay buffered events for a specific event type to a handler.
+     * Called when a new handler subscribes, to deliver any events that arrived
+     * before the handler was registered.
+     *
+     * Removes replayed events from the buffer and cleans up stale events.
+     */
+    private replayBufferedEvents;
     /**
      * Schedule force reconnect with exponential backoff.
      * Called after Socket.IO's built-in reconnection gives up.

package/dist/infra/transport/socket-io-transport-client.js

@@ -8,6 +8,26 @@ import { processLog } from '../../utils/process-logger.js';
 function clientLog(message) {
     processLog(`[TransportClient] ${message}`);
 }
+/**
+ * Events to buffer when received before handlers are registered.
+ * These are critical task lifecycle events that must not be lost.
+ */
+const BUFFERED_EVENTS = new Set([
+    'llmservice:chunk',
+    'llmservice:response',
+    'llmservice:toolCall',
+    'llmservice:toolResult',
+    'task:cancelled',
+    'task:completed',
+    'task:created',
+    'task:error',
+    'task:started',
+]);
+/**
+ * Maximum age of buffered events in milliseconds.
+ * Events older than this are discarded to prevent memory leaks.
+ */
+const BUFFERED_EVENT_MAX_AGE_MS = 10_000;
 /**
  * Force reconnect delays after Socket.IO gives up (exponential backoff).
  * Used when all built-in reconnection attempts fail.
@@ -39,6 +59,8 @@ const WAKE_TIME_JUMP_THRESHOLD_MS = 10_000;
  * - Auto-rejoins rooms after reconnect
  */
 export class SocketIOTransportClient {
+    /** Buffer for events that arrive before handlers are registered */
+    bufferedEvents = [];
     config;
     eventHandlers = new Map();
     /** Track force reconnect attempt count for backoff calculation */
@@ -102,6 +124,9 @@ export class SocketIOTransportClient {
             const onConnect = () => {
                 this.setState('connected');
                 cleanup();
+                // Register socket listeners for critical events that should be buffered.
+                // This allows events to be captured even before handlers subscribe.
+                this.registerBufferedEventListeners();
                 // Register any handlers that were added before connect() was called.
                 // This fixes the issue where on() called before connect() would not
                 // actually register handlers on the socket.
@@ -149,6 +174,7 @@ export class SocketIOTransportClient {
                 // listener accumulation. Socket.IO preserves the Socket instance across
                 // internal reconnects, so old listeners remain attached if not removed.
                 this.clearSocketEventListeners();
+                this.registerBufferedEventListeners();
                 this.registerPendingEventHandlers();
                 // Auto-rejoin rooms after reconnect
                 // Use process.nextTick to ensure socket.connected is true
@@ -185,6 +211,7 @@ export class SocketIOTransportClient {
             this.eventHandlers.clear();
             this.registeredSocketEvents.clear();
             this.joinedRooms.clear();
+            this.bufferedEvents = [];
             resolve();
         });
     }
@@ -290,6 +317,9 @@ export class SocketIOTransportClient {
         const wrappedHandler = (data) => handler(data);
         const handlers = this.eventHandlers.get(event);
         handlers?.add(wrappedHandler);
+        // Replay any buffered events for this event type
+        // This handles the race condition where events arrive before handlers subscribe
+        this.replayBufferedEvents(event, wrappedHandler);
         // Return unsubscribe function that also cleans up socket listener if no handlers remain
         return () => {
             handlers?.delete(wrappedHandler);
@@ -447,6 +477,16 @@ export class SocketIOTransportClient {
             this.scheduleForceReconnect();
         }
     }
+    /**
+     * Register socket listeners for all events that should be buffered.
+     * Called on connect to ensure critical events can be captured even before
+     * handlers subscribe. This prevents race conditions in TUI initialization.
+     */
+    registerBufferedEventListeners() {
+        for (const event of BUFFERED_EVENTS) {
+            this.registerSocketEventIfNeeded(event);
+        }
+    }
     /**
      * Register all pending event handlers on the socket.
      * Called after successful connection to handle handlers added before connect().
@@ -459,6 +499,10 @@ export class SocketIOTransportClient {
     /**
      * Register a socket listener for an event if not already registered.
      * Uses registeredSocketEvents set to prevent duplicates.
+     *
+     * For critical events (task lifecycle, LLM events), buffers incoming events
+     * if no handlers are registered yet. This prevents race conditions where
+     * broadcast-room events arrive before TUI components subscribe.
      */
     registerSocketEventIfNeeded(event) {
         const { socket } = this;
@@ -468,11 +512,21 @@ export class SocketIOTransportClient {
         // Register the dispatch listener on socket
         socket.on(event, (data) => {
             const handlers = this.eventHandlers.get(event);
-            if (handlers) {
+            if (handlers && handlers.size > 0) {
                 for (const h of handlers) {
                     h(data);
                 }
             }
+            else if (BUFFERED_EVENTS.has(event)) {
+                // Buffer critical events when no handlers are registered
+                // This handles race condition where events arrive before TUI subscribes
+                this.bufferedEvents.push({
+                    data,
+                    event,
+                    timestamp: Date.now(),
+                });
+                clientLog(`Buffered event '${event}' (no handlers yet), buffer size: ${this.bufferedEvents.length}`);
+            }
         });
         this.registeredSocketEvents.add(event);
     }
@@ -532,6 +586,39 @@ export class SocketIOTransportClient {
             this.registeredSocketEvents.delete(event);
         }
     }
+    /**
+     * Replay buffered events for a specific event type to a handler.
+     * Called when a new handler subscribes, to deliver any events that arrived
+     * before the handler was registered.
+     *
+     * Removes replayed events from the buffer and cleans up stale events.
+     */
+    replayBufferedEvents(event, handler) {
+        const now = Date.now();
+        const toReplay = [];
+        const toKeep = [];
+        for (const buffered of this.bufferedEvents) {
+            // Discard stale events
+            if (now - buffered.timestamp > BUFFERED_EVENT_MAX_AGE_MS) {
+                continue;
+            }
+            if (buffered.event === event) {
+                toReplay.push(buffered);
+            }
+            else {
+                toKeep.push(buffered);
+            }
+        }
+        // Update buffer with remaining events
+        this.bufferedEvents = toKeep;
+        // Replay events in order
+        if (toReplay.length > 0) {
+            clientLog(`Replaying ${toReplay.length} buffered '${event}' events`);
+            for (const buffered of toReplay) {
+                handler(buffered.data);
+            }
+        }
+    }
     /**
      * Schedule force reconnect with exponential backoff.
      * Called after Socket.IO's built-in reconnection gives up.