byterover-cli 0.4.1 → 1.0.0

package/dist/core/domain/cipher/errors/system-prompt-error.js

@@ -0,0 +1,144 @@
+import { SystemPromptErrorCode } from './system-prompt-error-codes.js';
+/**
+ * Base error class for system prompt operations.
+ *
+ * All system prompt-specific errors use this class with factory methods.
+ */
+export class SystemPromptError extends Error {
+    code;
+    details;
+    suggestion;
+    /**
+     * Creates a new system prompt error.
+     *
+     * @param message - Error message describing what went wrong
+     * @param code - Error code for categorization
+     * @param details - Additional error context
+     * @param suggestion - Optional recovery suggestion
+     */
+    constructor(message, code, details, suggestion) {
+        super(message);
+        this.name = 'SystemPromptError';
+        this.code = code;
+        this.details = details;
+        this.suggestion = suggestion;
+    }
+    /**
+     * Factory method: Cache operation failed.
+     *
+     * @param operation - The cache operation that failed (get, set, invalidate)
+     * @param reason - Reason for the failure
+     * @returns SystemPromptError instance
+     */
+    static cacheOperationFailed(operation, reason) {
+        return new SystemPromptError(`Cache ${operation} operation failed: ${reason}`, SystemPromptErrorCode.CACHE_OPERATION_FAILED, { operation, reason }, 'Clear the cache and retry, or check file system permissions.');
+    }
+    /**
+     * Factory method: Prompt configuration is invalid.
+     *
+     * @param reason - Reason why configuration is invalid
+     * @param validationErrors - Optional validation error details
+     * @returns SystemPromptError instance
+     */
+    static configInvalid(reason, validationErrors) {
+        return new SystemPromptError(`Invalid prompt configuration: ${reason}`, SystemPromptErrorCode.CONFIG_INVALID, { reason, validationErrors }, 'Review the prompt YAML structure and fix any schema violations.');
+    }
+    /**
+     * Factory method: Required field missing from configuration.
+     *
+     * @param field - Name of the missing field
+     * @param filepath - Path to the config file
+     * @returns SystemPromptError instance
+     */
+    static configMissingField(field, filepath) {
+        return new SystemPromptError(`Missing required field '${field}' in ${filepath}`, SystemPromptErrorCode.CONFIG_MISSING_FIELD, { field, filepath }, `Add the '${field}' field to the prompt configuration.`);
+    }
+    /**
+     * Factory method: Contributor execution failed.
+     *
+     * @param contributorId - ID of the failing contributor
+     * @param reason - Reason for the failure
+     * @returns SystemPromptError instance
+     */
+    static contributorExecutionFailed(contributorId, reason) {
+        return new SystemPromptError(`Contributor '${contributorId}' execution failed: ${reason}`, SystemPromptErrorCode.CONTRIBUTOR_EXECUTION_FAILED, { contributorId, reason }, 'Check contributor implementation and its dependencies.');
+    }
+    /**
+     * Factory method: Invalid contributor configuration.
+     *
+     * @param config - The invalid configuration object
+     * @returns SystemPromptError instance
+     */
+    static contributorInvalidConfig(config) {
+        return new SystemPromptError('Invalid contributor configuration', SystemPromptErrorCode.CONTRIBUTOR_INVALID_CONFIG, { config }, 'Verify contributor type and ensure all required fields are present.');
+    }
+    /**
+     * Factory method: Contributor not found in registry.
+     *
+     * @param contributorId - ID of the missing contributor
+     * @returns SystemPromptError instance
+     */
+    static contributorNotFound(contributorId) {
+        return new SystemPromptError(`Contributor not found: ${contributorId}`, SystemPromptErrorCode.CONTRIBUTOR_NOT_FOUND, { contributorId }, 'Register the contributor before using it in the configuration.');
+    }
+    /**
+     * Factory method: Prompt file not found.
+     *
+     * @param filepath - Path to the missing file
+     * @returns SystemPromptError instance
+     */
+    static fileNotFound(filepath) {
+        return new SystemPromptError(`Prompt file not found: ${filepath}`, SystemPromptErrorCode.FILE_NOT_FOUND, { filepath }, 'Check that the prompt file exists at the expected path.');
+    }
+    /**
+     * Factory method: Failed to read prompt file.
+     *
+     * @param filepath - Path to the file
+     * @param reason - Reason for the failure
+     * @returns SystemPromptError instance
+     */
+    static fileReadFailed(filepath, reason) {
+        return new SystemPromptError(`Failed to read prompt file ${filepath}: ${reason}`, SystemPromptErrorCode.FILE_READ_FAILED, { filepath, reason }, 'Check file permissions and encoding (UTF-8 expected).');
+    }
+    /**
+     * Factory method: File exceeds maximum allowed size.
+     *
+     * @param filepath - Path to the file
+     * @param size - Actual file size in bytes
+     * @param maxSize - Maximum allowed size in bytes
+     * @returns SystemPromptError instance
+     */
+    static fileTooLarge(filepath, size, maxSize) {
+        return new SystemPromptError(`File ${filepath} exceeds maximum size (${size} > ${maxSize} bytes)`, SystemPromptErrorCode.FILE_TOO_LARGE, { filepath, maxSize, size }, `Reduce file size to under ${maxSize} bytes.`);
+    }
+    /**
+     * Factory method: Invalid file type for prompt loading.
+     *
+     * @param filepath - Path to the invalid file
+     * @param allowedExtensions - List of allowed file extensions
+     * @returns SystemPromptError instance
+     */
+    static invalidFileType(filepath, allowedExtensions) {
+        return new SystemPromptError(`Invalid file type for ${filepath}. Expected: ${allowedExtensions.join(', ')}`, SystemPromptErrorCode.FILE_INVALID_TYPE, { allowedExtensions, filepath }, `Use one of the supported file types: ${allowedExtensions.join(', ')}`);
+    }
+    /**
+     * Factory method: Template rendering failed.
+     *
+     * @param reason - Reason for the failure
+     * @param templatePreview - Preview of the template (first 100 chars)
+     * @returns SystemPromptError instance
+     */
+    static templateRenderFailed(reason, templatePreview) {
+        return new SystemPromptError(`Template render failed: ${reason}`, SystemPromptErrorCode.TEMPLATE_RENDER_FAILED, { reason, templatePreview }, 'Check template syntax and ensure all variable placeholders are valid.');
+    }
+    /**
+     * Factory method: Required template variable is missing.
+     *
+     * @param variable - Name of the missing variable
+     * @param template - Path or identifier of the template
+     * @returns SystemPromptError instance
+     */
+    static templateVariableMissing(variable, template) {
+        return new SystemPromptError(`Missing required template variable '${variable}' in ${template}`, SystemPromptErrorCode.TEMPLATE_VARIABLE_MISSING, { template, variable }, `Provide a value for the '${variable}' variable in the build context.`);
+    }
+}

package/dist/core/domain/cipher/file-system/types.d.ts

@@ -77,18 +77,73 @@ export interface SearchOptions {
     /** Maximum number of matches to return */
     maxResults?: number;
 }
+/**
+ * Options for listing directory contents.
+ */
+export interface ListDirectoryOptions {
+    /** Additional glob patterns to ignore (merged with defaults) */
+    ignore?: string[];
+    /** Maximum number of files to return (default: 100) */
+    maxResults?: number;
+}
+/**
+ * Entry in directory listing.
+ */
+export interface DirectoryEntry {
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Entry name (file or directory name, not full path) */
+    name: string;
+    /** Relative path from the listed directory */
+    path: string;
+}
+/**
+ * Result of a directory listing operation.
+ */
+export interface ListDirectoryResult {
+    /** Total number of entries found */
+    count: number;
+    /** Array of directory entries */
+    entries: DirectoryEntry[];
+    /** Formatted tree output string */
+    tree: string;
+    /** Whether results were truncated */
+    truncated: boolean;
+}
+/**
+ * Attachment data for binary files (images, PDFs).
+ * Used to return base64-encoded content for multimodal LLM consumption.
+ */
+export interface FileAttachment {
+    /** Base64-encoded file content */
+    base64: string;
+    /** Original file name */
+    fileName: string;
+    /** MIME type (e.g., 'image/png', 'application/pdf') */
+    mimeType: string;
+}
 /**
  * Result of a file read operation.
  */
 export interface FileContent {
+    /** Attachment data for binary files (images, PDFs) */
+    attachment?: FileAttachment;
     /** File content as string */
     content: string;
     /** Character encoding used */
     encoding: string;
+    /** Formatted content with line numbers (00001| content format) */
+    formattedContent: string;
     /** Total number of lines in the returned content */
     lines: number;
+    /** Human-readable message about file status (truncation info, etc.) */
+    message: string;
+    /** Preview of content (first 20 lines) for UI display */
+    preview?: string;
     /** File size in bytes */
     size: number;
+    /** Total lines in the entire file */
+    totalLines: number;
     /** Whether content was truncated due to size/line limits */
     truncated: boolean;
 }
@@ -161,6 +216,8 @@ export interface SearchMatch {
     line: string;
     /** Line number (1-based) */
     lineNumber: number;
+    /** File modification time in milliseconds (for sorting by recency) */
+    mtime?: number;
 }
 /**
  * Result of a content search operation.

package/dist/core/domain/cipher/llm/error-codes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LLM Error Codes
+ *
+ * Centralized error codes for LLM-related operations.
+ * Following Dexto's pattern for typed error handling.
+ */
+/**
+ * LLM-specific error codes.
+ */
+export declare const LLMErrorCode: {
+    readonly API_KEY_INVALID: "LLM_API_KEY_INVALID";
+    readonly API_KEY_MISSING: "LLM_API_KEY_MISSING";
+    readonly BASE_URL_INVALID: "LLM_BASE_URL_INVALID";
+    readonly BASE_URL_MISSING: "LLM_BASE_URL_MISSING";
+    readonly COMPRESSION_FAILED: "LLM_COMPRESSION_FAILED";
+    readonly CONTEXT_OVERFLOW: "LLM_CONTEXT_OVERFLOW";
+    readonly GENERATION_FAILED: "LLM_GENERATION_FAILED";
+    readonly INPUT_FILE_UNSUPPORTED: "LLM_INPUT_FILE_UNSUPPORTED";
+    readonly INPUT_IMAGE_UNSUPPORTED: "LLM_INPUT_IMAGE_UNSUPPORTED";
+    readonly INPUT_TEXT_INVALID: "LLM_INPUT_TEXT_INVALID";
+    readonly MODEL_INCOMPATIBLE: "LLM_MODEL_INCOMPATIBLE";
+    readonly MODEL_UNKNOWN: "LLM_MODEL_UNKNOWN";
+    readonly PROVIDER_UNSUPPORTED: "LLM_PROVIDER_UNSUPPORTED";
+    readonly RATE_LIMIT_EXCEEDED: "LLM_RATE_LIMIT_EXCEEDED";
+    readonly REQUEST_INVALID_SCHEMA: "LLM_REQUEST_INVALID_SCHEMA";
+    readonly SWITCH_FAILED: "LLM_SWITCH_FAILED";
+    readonly SWITCH_INPUT_MISSING: "LLM_SWITCH_INPUT_MISSING";
+    readonly TOKENS_EXCEEDED: "LLM_TOKENS_EXCEEDED";
+};
+/**
+ * Type for LLM error codes.
+ */
+export type LLMErrorCodeType = (typeof LLMErrorCode)[keyof typeof LLMErrorCode];
+/**
+ * Error scope for categorizing errors.
+ */
+export declare const ErrorScope: {
+    readonly CONFIG: "config";
+    readonly LLM: "llm";
+    readonly VALIDATION: "validation";
+};
+export type ErrorScopeType = (typeof ErrorScope)[keyof typeof ErrorScope];
+/**
+ * Error type for categorizing error severity.
+ */
+export declare const ErrorType: {
+    readonly SYSTEM: "system";
+    readonly TRANSIENT: "transient";
+    readonly USER: "user";
+};
+export type ErrorTypeValue = (typeof ErrorType)[keyof typeof ErrorType];

package/dist/core/domain/cipher/llm/error-codes.js

@@ -0,0 +1,51 @@
+/**
+ * LLM Error Codes
+ *
+ * Centralized error codes for LLM-related operations.
+ * Following Dexto's pattern for typed error handling.
+ */
+/**
+ * LLM-specific error codes.
+ */
+export const LLMErrorCode = {
+    // Configuration errors
+    API_KEY_INVALID: 'LLM_API_KEY_INVALID',
+    API_KEY_MISSING: 'LLM_API_KEY_MISSING',
+    BASE_URL_INVALID: 'LLM_BASE_URL_INVALID',
+    BASE_URL_MISSING: 'LLM_BASE_URL_MISSING',
+    // Context errors
+    COMPRESSION_FAILED: 'LLM_COMPRESSION_FAILED',
+    CONTEXT_OVERFLOW: 'LLM_CONTEXT_OVERFLOW',
+    // Operation errors
+    GENERATION_FAILED: 'LLM_GENERATION_FAILED',
+    // Input validation errors
+    INPUT_FILE_UNSUPPORTED: 'LLM_INPUT_FILE_UNSUPPORTED',
+    INPUT_IMAGE_UNSUPPORTED: 'LLM_INPUT_IMAGE_UNSUPPORTED',
+    INPUT_TEXT_INVALID: 'LLM_INPUT_TEXT_INVALID',
+    // Model errors
+    MODEL_INCOMPATIBLE: 'LLM_MODEL_INCOMPATIBLE',
+    MODEL_UNKNOWN: 'LLM_MODEL_UNKNOWN',
+    PROVIDER_UNSUPPORTED: 'LLM_PROVIDER_UNSUPPORTED',
+    // Limit errors
+    RATE_LIMIT_EXCEEDED: 'LLM_RATE_LIMIT_EXCEEDED',
+    REQUEST_INVALID_SCHEMA: 'LLM_REQUEST_INVALID_SCHEMA',
+    SWITCH_FAILED: 'LLM_SWITCH_FAILED',
+    SWITCH_INPUT_MISSING: 'LLM_SWITCH_INPUT_MISSING',
+    TOKENS_EXCEEDED: 'LLM_TOKENS_EXCEEDED',
+};
+/**
+ * Error scope for categorizing errors.
+ */
+export const ErrorScope = {
+    CONFIG: 'config',
+    LLM: 'llm',
+    VALIDATION: 'validation',
+};
+/**
+ * Error type for categorizing error severity.
+ */
+export const ErrorType = {
+    SYSTEM: 'system', // System/infrastructure error
+    TRANSIENT: 'transient', // Temporary error (retry may help)
+    USER: 'user', // User-correctable error
+};

package/dist/core/domain/cipher/llm/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * LLM Domain Module
+ *
+ * Exports types, registry, and utilities for LLM provider abstraction.
+ */
+export { ErrorScope, type ErrorScopeType, ErrorType, type ErrorTypeValue, LLMErrorCode, type LLMErrorCodeType, } from './error-codes.js';
+export { acceptsAnyModel, DEFAULT_CHARS_PER_TOKEN, DEFAULT_MAX_INPUT_TOKENS, getCharsPerToken, getDefaultModelForProvider, getEffectiveMaxInputTokens, getMaxInputTokensForModel, getModelCapabilities, getModelInfo, getModelInfoWithFallback, getProviderFromModel, getSupportedFileTypesForModel, getSupportedModels, isValidProviderModel, LLM_REGISTRY, modelSupportsFileType, } from './registry.js';
+export { type LLMConfig, LLMConfigBaseSchema, LLMConfigSchema, type LLMUpdates, LLMUpdatesSchema, safeParseLLMConfig, type ValidatedLLMConfig, validateLLMConfig, validateLLMUpdates, } from './schemas.js';
+export { getAllowedMimeTypes, getFileTypeFromMimeType, isSupportedMimeType, LLM_PROVIDERS, type LLMContext, type LLMProvider, type LLMTokenUsage, MIME_TYPE_TO_FILE_TYPE, type ModelCapabilities, type ModelInfo, type ProviderInfo, SUPPORTED_FILE_TYPES, type SupportedFileType, } from './types.js';

package/dist/core/domain/cipher/llm/index.js

@@ -0,0 +1,13 @@
+/**
+ * LLM Domain Module
+ *
+ * Exports types, registry, and utilities for LLM provider abstraction.
+ */
+// Error Codes
+export { ErrorScope, ErrorType, LLMErrorCode, } from './error-codes.js';
+// Registry
+export { acceptsAnyModel, DEFAULT_CHARS_PER_TOKEN, DEFAULT_MAX_INPUT_TOKENS, getCharsPerToken, getDefaultModelForProvider, getEffectiveMaxInputTokens, getMaxInputTokensForModel, getModelCapabilities, getModelInfo, getModelInfoWithFallback, getProviderFromModel, getSupportedFileTypesForModel, getSupportedModels, isValidProviderModel, LLM_REGISTRY, modelSupportsFileType, } from './registry.js';
+// Schemas
+export { LLMConfigBaseSchema, LLMConfigSchema, LLMUpdatesSchema, safeParseLLMConfig, validateLLMConfig, validateLLMUpdates, } from './schemas.js';
+// Types
+export { getAllowedMimeTypes, getFileTypeFromMimeType, isSupportedMimeType, LLM_PROVIDERS, MIME_TYPE_TO_FILE_TYPE, SUPPORTED_FILE_TYPES, } from './types.js';

package/dist/core/domain/cipher/llm/registry.d.ts

@@ -0,0 +1,113 @@
+/**
+ * LLM Model Registry - Single Source of Truth for Model Metadata.
+ *
+ * This registry provides centralized model information including:
+ * - Context window sizes (maxInputTokens)
+ * - Character-per-token ratios for estimation
+ * - Supported file types for multimodal input
+ * - Model capabilities
+ *
+ * Following patterns from Dexto's LLM registry.
+ */
+import { type LLMProvider, type ModelCapabilities, type ModelInfo, type ProviderInfo, type SupportedFileType } from './types.js';
+/** Default fallback for unknown models */
+export declare const DEFAULT_MAX_INPUT_TOKENS = 128000;
+export declare const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * LLM Model Registry
+ *
+ * IMPORTANT: supportedFileTypes is the SINGLE SOURCE OF TRUTH for file upload capabilities:
+ * - Empty array [] = Model does NOT support file uploads
+ * - Specific types ['image', 'pdf'] = Model supports ONLY those file types
+ */
+export declare const LLM_REGISTRY: Record<LLMProvider, ProviderInfo>;
+/**
+ * Get model information from the registry.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns ModelInfo or undefined if not found
+ */
+export declare function getModelInfo(provider: LLMProvider, model: string): ModelInfo | undefined;
+/**
+ * Get model info with fallback for unknown models.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns ModelInfo (falls back to default values for unknown models)
+ */
+export declare function getModelInfoWithFallback(provider: LLMProvider, model: string): ModelInfo;
+/**
+ * Get characters per token ratio for a model.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns Characters per token ratio
+ */
+export declare function getCharsPerToken(provider: LLMProvider, model: string): number;
+/**
+ * Get maximum input tokens for a model.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns Maximum input tokens
+ */
+export declare function getMaxInputTokensForModel(provider: LLMProvider, model: string): number;
+/**
+ * Check if a model is valid for a provider.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns true if the model is in the registry
+ */
+export declare function isValidProviderModel(provider: LLMProvider, model: string): boolean;
+/**
+ * Get supported models for a provider.
+ * @param provider - LLM provider
+ * @returns Array of model names
+ */
+export declare function getSupportedModels(provider: LLMProvider): string[];
+/**
+ * Get the default model for a provider.
+ * @param provider - LLM provider
+ * @returns Default model name
+ */
+export declare function getDefaultModelForProvider(provider: LLMProvider): string;
+/**
+ * Infer provider from model name.
+ * @param model - Model name
+ * @returns LLMProvider or undefined if not found
+ */
+export declare function getProviderFromModel(model: string): LLMProvider | undefined;
+/**
+ * Get supported file types for a model.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns Array of supported file types
+ */
+export declare function getSupportedFileTypesForModel(provider: LLMProvider, model: string): SupportedFileType[];
+/**
+ * Check if a model supports a specific file type.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @param fileType - File type to check
+ * @returns true if the model supports the file type
+ */
+export declare function modelSupportsFileType(provider: LLMProvider, model: string, fileType: SupportedFileType): boolean;
+/**
+ * Get model capabilities.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @returns ModelCapabilities
+ */
+export declare function getModelCapabilities(provider: LLMProvider, model: string): ModelCapabilities;
+/**
+ * Get effective max input tokens considering config override.
+ * @param provider - LLM provider
+ * @param model - Model name
+ * @param configuredMax - Optional configured max from user
+ * @returns Effective max input tokens (min of model limit and configured limit)
+ */
+export declare function getEffectiveMaxInputTokens(provider: LLMProvider, model: string, configuredMax?: number): number;
+/**
+ * Check if OpenRouter accepts any model (custom models).
+ * OpenRouter can route to many models not in our registry.
+ * @param provider - LLM provider
+ * @returns true if provider accepts arbitrary models
+ */
+export declare function acceptsAnyModel(provider: LLMProvider): boolean;