@dollhousemcp/mcp-server/dist/config/sourcePriority.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Element source priority configuration
 *
 * This module defines the centralized configuration for element sourcing priority,
 * determining the order in which element sources (local, GitHub, collection) are
 * checked when searching for or installing elements.
 *
 * @module config/sourcePriority
 */
/**
 * Enumeration of available element sources
 *
 * @example
 * // Using ElementSource in configuration
 * const priority = [ElementSource.LOCAL, ElementSource.GITHUB, ElementSource.COLLECTION];
 */
export declare enum ElementSource {
    /** Local portfolio (~/.dollhouse/portfolio/) */
    LOCAL = "local",
    /** User's GitHub portfolio repository */
    GITHUB = "github",
    /** DollhouseMCP community collection */
    COLLECTION = "collection"
}
/**
 * Configuration for element source priority
 *
 * @interface SourcePriorityConfig
 * @property {ElementSource[]} priority - Ordered list of sources to check (first = highest priority)
 * @property {boolean} stopOnFirst - Whether to stop searching after finding element in first source
 * @property {boolean} checkAllForUpdates - Whether to check all sources for version comparison
 * @property {boolean} fallbackOnError - Whether to try next source when current source fails
 *
 * @example
 * // Default configuration (local → GitHub → collection)
 * const config: SourcePriorityConfig = {
 *   priority: [ElementSource.LOCAL, ElementSource.GITHUB, ElementSource.COLLECTION],
 *   stopOnFirst: true,
 *   checkAllForUpdates: false,
 *   fallbackOnError: true
 * };
 *
 * @example
 * // Custom configuration (collection-first for discovery)
 * const config: SourcePriorityConfig = {
 *   priority: [ElementSource.COLLECTION, ElementSource.LOCAL, ElementSource.GITHUB],
 *   stopOnFirst: false,
 *   checkAllForUpdates: true,
 *   fallbackOnError: true
 * };
 */
export interface SourcePriorityConfig {
    /**
     * Ordered list of sources to check (first = highest priority)
     *
     * The system will check sources in this order, stopping early if
     * stopOnFirst is true and an element is found.
     */
    priority: ElementSource[];
    /**
     * Whether to stop searching after finding element in first source
     *
     * When true, the search terminates as soon as an element is found in
     * any source. When false, all enabled sources are searched.
     *
     * @default true
     */
    stopOnFirst: boolean;
    /**
     * Whether to check all sources for version comparison
     *
     * When true, all sources are checked to find the latest version,
     * even if stopOnFirst is true. Useful for detecting updates.
     *
     * @default false
     */
    checkAllForUpdates: boolean;
    /**
     * Whether to try next source when current source fails
     *
     * When true, errors in one source won't prevent searching other sources.
     * When false, any source error will halt the search and return the error.
     *
     * @default true
     */
    fallbackOnError: boolean;
}
/**
 * Default source priority configuration
 *
 * Priority order: Local → GitHub → Collection
 * This ensures users' local customizations take precedence over remote sources.
 *
 * @example
 * // Using the default configuration
 * import { DEFAULT_SOURCE_PRIORITY } from './sourcePriority.js';
 *
 * const config = DEFAULT_SOURCE_PRIORITY;
 * console.log(config.priority); // [ElementSource.LOCAL, ElementSource.GITHUB, ElementSource.COLLECTION]
 */
export declare const DEFAULT_SOURCE_PRIORITY: SourcePriorityConfig;
/**
 * Get current source priority configuration
 *
 * Priority order for configuration sources:
 * 1. User configuration (from config file)
 * 2. Environment variables (for testing)
 * 3. Default configuration
 *
 * @returns {SourcePriorityConfig} The current source priority configuration
 *
 * @example
 * // Get the current configuration
 * import { getSourcePriorityConfig } from './sourcePriority.js';
 *
 * const config = getSourcePriorityConfig();
 * console.log(config.priority); // [ElementSource.LOCAL, ElementSource.GITHUB, ElementSource.COLLECTION]
 *
 * @example
 * // Use in a search operation
 * const config = getSourcePriorityConfig();
 * for (const source of config.priority) {
 *   const results = await searchSource(source);
 *   if (results.length > 0 && config.stopOnFirst) {
 *     break;
 *   }
 * }
 */
export declare function getSourcePriorityConfig(): SourcePriorityConfig;
/**
 * Validation result for source priority configuration
 *
 * @interface ValidationResult
 * @property {boolean} isValid - Whether the configuration is valid
 * @property {string[]} errors - List of validation error messages (empty if valid)
 */
export interface ValidationResult {
    isValid: boolean;
    errors: string[];
}
/**
 * Validate source priority configuration
 *
 * Checks for:
 * - Empty priority list
 * - Duplicate sources
 * - Unknown/invalid sources
 *
 * @param {SourcePriorityConfig} config - The configuration to validate
 * @returns {ValidationResult} Validation result with error messages
 *
 * @example
 * // Validate a valid configuration
 * const config = {
 *   priority: [ElementSource.LOCAL, ElementSource.GITHUB],
 *   stopOnFirst: true,
 *   checkAllForUpdates: false,
 *   fallbackOnError: true
 * };
 * const result = validateSourcePriority(config);
 * console.log(result.isValid); // true
 * console.log(result.errors); // []
 *
 * @example
 * // Validate an invalid configuration (duplicate sources)
 * const config = {
 *   priority: [ElementSource.LOCAL, ElementSource.LOCAL],
 *   stopOnFirst: true,
 *   checkAllForUpdates: false,
 *   fallbackOnError: true
 * };
 * const result = validateSourcePriority(config);
 * console.log(result.isValid); // false
 * console.log(result.errors); // ['Duplicate sources in priority list']
 *
 * @example
 * // Validate an invalid configuration (empty priority)
 * const config = {
 *   priority: [],
 *   stopOnFirst: true,
 *   checkAllForUpdates: false,
 *   fallbackOnError: true
 * };
 * const result = validateSourcePriority(config);
 * console.log(result.isValid); // false
 * console.log(result.errors); // ['Priority list cannot be empty']
 */
export declare function validateSourcePriority(config: SourcePriorityConfig): ValidationResult;
/**
 * Save source priority configuration to config file
 *
 * Validates the configuration before saving and persists it via ConfigManager.
 * The configuration will be saved to ~/.dollhouse/config.yml under the
 * source_priority key.
 *
 * @param {SourcePriorityConfig} config - The source priority configuration to save
 * @returns {Promise<void>}
 * @throws {Error} If configuration is invalid or save fails
 *
 * @example
 * // Save a custom configuration
 * await saveSourcePriorityConfig({
 *   priority: [ElementSource.GITHUB, ElementSource.LOCAL, ElementSource.COLLECTION],
 *   stopOnFirst: false,
 *   checkAllForUpdates: true,
 *   fallbackOnError: true
 * });
 *
 * @example
 * // Validate before saving
 * const config = {
 *   priority: [ElementSource.LOCAL, ElementSource.GITHUB],
 *   stopOnFirst: true,
 *   checkAllForUpdates: false,
 *   fallbackOnError: true
 * };
 * const validation = validateSourcePriority(config);
 * if (validation.isValid) {
 *   await saveSourcePriorityConfig(config);
 * }
 */
export declare function saveSourcePriorityConfig(config: SourcePriorityConfig): Promise<void>;
/**
 * Get user-friendly display name for an element source
 *
 * Maps ElementSource enum values to human-readable names suitable for
 * user-facing messages, logs, and documentation.
 *
 * @param {ElementSource} source - The source to get display name for
 * @returns {string} User-friendly display name
 * @throws {Error} If source is not a valid ElementSource value
 *
 * @example
 * // Get display names for all sources
 * console.log(getSourceDisplayName(ElementSource.LOCAL)); // "Local Portfolio"
 * console.log(getSourceDisplayName(ElementSource.GITHUB)); // "GitHub Portfolio"
 * console.log(getSourceDisplayName(ElementSource.COLLECTION)); // "Community Collection"
 *
 * @example
 * // Use in a log message
 * const source = ElementSource.LOCAL;
 * console.log(`Found element in ${getSourceDisplayName(source)}`);
 * // Output: "Found element in Local Portfolio"
 *
 * @example
 * // Generate a source list for user display
 * const config = getSourcePriorityConfig();
 * const sourceNames = config.priority.map(s => getSourceDisplayName(s)).join(' → ');
 * console.log(`Search order: ${sourceNames}`);
 * // Output: "Search order: Local Portfolio → GitHub Portfolio → Community Collection"
 */
export declare function getSourceDisplayName(source: ElementSource): string;
/**
 * Parse source priority order from various input formats
 *
 * Accepts arrays of ElementSource values or string source names and
 * normalizes them to an array of ElementSource enum values.
 *
 * @param {unknown} value - The value to parse (array of sources or JSON string)
 * @returns {ElementSource[]} Parsed array of element sources
 * @throws {Error} If value cannot be parsed or contains invalid sources
 *
 * @example
 * // Parse from array of strings
 * const order = parseSourcePriorityOrder(['local', 'github', 'collection']);
 * // Returns: [ElementSource.LOCAL, ElementSource.GITHUB, ElementSource.COLLECTION]
 *
 * @example
 * // Parse from JSON string
 * const order = parseSourcePriorityOrder('["github", "local"]');
 * // Returns: [ElementSource.GITHUB, ElementSource.LOCAL]
 *
 * @example
 * // Parse from ElementSource values
 * const order = parseSourcePriorityOrder([ElementSource.LOCAL, ElementSource.GITHUB]);
 * // Returns: [ElementSource.LOCAL, ElementSource.GITHUB]
 */
export declare function parseSourcePriorityOrder(value: unknown): ElementSource[];
//# sourceMappingURL=sourcePriority.d.ts.map