@invisiblecities/sidequest-cqo/dist/services/preferences-manager.d.ts

Configuration-agnostic TypeScript and ESLint orchestrator with real-time watch mode, SQLite persistence, and intelligent terminal detection

/**
 * @fileoverview User Preferences Manager - Configuration-Agnostic User Settings
 *
 * Manages persistent user preferences and educational prompts for the Code Quality Orchestrator.
 * This system respects user choices while providing gentle guidance toward best practices.
 *
 * Key Features:
 * - Singleton pattern for consistent preferences across sessions
 * - Schema migration for forward compatibility
 * - Educational warnings (TypeScript/ESLint separation) with user control
 * - Configuration-agnostic defaults that don't impose opinions
 * - Project-scoped or global preference storage options
 *
 * Architecture:
 * The preferences system operates on three levels:
 * 1. **Default Preferences**: Conservative, non-opinionated defaults
 * 2. **User Overrides**: Saved choices that persist across sessions
 * 3. **Runtime Configuration**: CLI flags that override preferences
 *
 * Educational Philosophy:
 * - Suggest best practices but never force them
 * - One-time educational prompts with "don't show again" options
 * - Respect user expertise level and preference for guidance
 *
 * @example Basic Usage
 * ```typescript
 * const prefs = PreferencesManager.getInstance('./project-data');
 *
 * // Check if user wants separation guidance
 * if (prefs.shouldShowTscEslintWarning()) {
 *   const choice = await prefs.showTscEslintSeparationWarning();
 *   console.log('User chose:', choice);
 * }
 *
 * // Get user's analysis preferences
 * const mode = prefs.getAnalysisMode(); // 'errors-only' | 'warnings-and-errors' | 'all'
 * const colors = prefs.getColorScheme(); // 'auto' | 'light' | 'dark'
 * ```
 *
 * @example Configuration Management
 * ```typescript
 * // Update specific preference section
 * prefs.updatePreference('display', {
 *   colorScheme: 'dark',
 *   verboseOutput: true
 * });
 *
 * // Reset everything to defaults
 * prefs.resetToDefaults();
 *
 * // Get full config for debugging
 * const allPrefs = prefs.getAllPreferences();
 * ```
 *
 * @author SideQuest
 * @version 1.0.0
 */
/**
 * Complete user preferences schema with comprehensive settings
 *
 * This interface defines all configurable aspects of the tool behavior.
 * Each section has a specific purpose in the configuration-agnostic design.
 */
interface UserPreferences {
    schemaVersion: string;
    preferences: {
        analysis: {
            defaultMode: "errors-only" | "warnings-and-errors" | "all";
            strictMode: boolean;
            includePatternChecking: boolean;
        };
        warnings: {
            showTscEslintSeparationWarning: boolean;
            showPerformanceWarnings: boolean;
            showConfigurationHints: boolean;
        };
        display: {
            colorScheme: "auto" | "light" | "dark";
            verboseOutput: boolean;
            showProgressIndicators: boolean;
        };
        watch: {
            autoDetectConfigChanges: boolean;
            debounceMs: number;
            intervalMs: number;
        };
        customTypeScriptScripts?: {
            enabled: boolean;
            defaultPreset: string;
            presetMappings: {
                [preset: string]: string[];
            };
            scriptTimeout: number;
            failureHandling: "continue" | "warn" | "fail";
        };
        customESLintScripts?: {
            enabled: boolean;
            defaultPreset: string;
            presetMappings: {
                [preset: string]: string[];
            };
            scriptTimeout: number;
            failureHandling: "continue" | "warn" | "fail";
        };
    };
    userChoices: {
        hasSeenTscEslintWarning: boolean;
        hasConfiguredSeparationOfConcerns: boolean;
        hasCompletedFirstRun: boolean;
        preferredEngine: "typescript-only" | "eslint-only" | "both-separate" | "both-mixed";
        lastConfigUpdate: string | null | undefined;
    };
}
export declare class PreferencesManager {
    private static instance;
    private preferencesPath;
    private preferences;
    private constructor();
    static getInstance(dataDirectory?: string): PreferencesManager;
    /**
     * Load preferences from file or create defaults
     */
    private loadPreferences;
    /**
     * Get default preferences
     */
    private getDefaultPreferences;
    /**
     * Migrate preferences between schema versions
     */
    private migratePreferences;
    /**
     * Save preferences to file
     */
    private savePreferences;
    /**
     * Check if user should see TypeScript/ESLint separation warning
     */
    shouldShowTscEslintWarning(): boolean;
    /**
     * Show TypeScript/ESLint separation warning and get user choice
     */
    showTscEslintSeparationWarning(): Promise<"typescript-only" | "both-separate" | "both-mixed" | "disable-warning">;
    /**
     * Get user's preferred analysis mode
     */
    getAnalysisMode(): "errors-only" | "warnings-and-errors" | "all";
    /**
     * Get user's strict mode preference
     */
    getStrictMode(): boolean;
    /**
     * Get user's color scheme preference
     */
    getColorScheme(): "auto" | "light" | "dark";
    /**
     * Update user preference
     */
    updatePreference<K extends keyof UserPreferences["preferences"]>(section: K, updates: Partial<UserPreferences["preferences"][K]>): void;
    /**
     * Get all preferences (for debugging/config display)
     */
    getAllPreferences(): UserPreferences;
    /**
     * Reset preferences to defaults
     */
    resetToDefaults(): void;
    /**
     * Update user choice/state
     */
    updateUserChoice<K extends keyof UserPreferences["userChoices"]>(key: K, value: UserPreferences["userChoices"][K]): void;
    /**
     * Check if user has configured separation of concerns
     */
    hasSeparationOfConcerns(): boolean;
}
export {};
//# sourceMappingURL=preferences-manager.d.ts.map