@williamzujkowski/live-coding-music-mcp 1.0.0

package/dist/services/__mocks__/StrudelEngine.js

@@ -0,0 +1,157 @@
+/**
+ * Mock StrudelEngine for Jest testing
+ * Provides stub implementations for tests that don't need actual Strudel execution
+ */
+export class StrudelEngine {
+    transpile(code) {
+        if (!code || code.trim().length === 0) {
+            return {
+                success: false,
+                error: 'Empty pattern',
+                errorLocation: { line: 1, column: 1, offset: 0 },
+            };
+        }
+        // Simple validation - check for basic syntax issues
+        if (code.includes('(') && !code.includes(')')) {
+            return {
+                success: false,
+                error: 'Unexpected end of input',
+                errorLocation: { line: 1, column: code.length, offset: code.length },
+            };
+        }
+        return {
+            success: true,
+            transpiledCode: `return /* mock transpiled */ ${code};`,
+            locations: [],
+        };
+    }
+    validate(code) {
+        const errors = [];
+        const warnings = [];
+        const suggestions = [];
+        if (!code || code.trim().length === 0) {
+            return {
+                valid: false,
+                errors: ['Pattern is empty'],
+                warnings: [],
+                suggestions: ['Add a pattern like: s("bd hh sd hh")'],
+            };
+        }
+        const transpileResult = this.transpile(code);
+        if (!transpileResult.success) {
+            return {
+                valid: false,
+                errors: [transpileResult.error || 'Syntax error'],
+                warnings,
+                suggestions: ['Check pattern syntax'],
+                errorLocation: transpileResult.errorLocation
+                    ? { line: transpileResult.errorLocation.line, column: transpileResult.errorLocation.column }
+                    : undefined,
+            };
+        }
+        // Check for common issues
+        const gainMatches = code.match(/\.gain\s*\(\s*(\d+(?:\.\d+)?)\s*\)/g);
+        if (gainMatches) {
+            for (const match of gainMatches) {
+                const value = parseFloat(match.match(/(\d+(?:\.\d+)?)/)?.[1] || '0');
+                if (value > 2) {
+                    warnings.push(`High gain value (${value}) may cause distortion`);
+                }
+            }
+        }
+        if (!/setcpm|setbpm|cpm|bpm/.test(code)) {
+            suggestions.push('Consider setting tempo with setcpm(120)');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            suggestions,
+        };
+    }
+    queryEvents(code, start, end) {
+        const transpileResult = this.transpile(code);
+        if (!transpileResult.success) {
+            throw new Error(`Transpilation failed: ${transpileResult.error}`);
+        }
+        // Return mock events based on pattern content
+        const events = [];
+        const cycles = end - start;
+        // Simple mock - return 4 events per cycle for patterns containing s()
+        if (code.includes('s(')) {
+            const matches = code.match(/s\("([^"]+)"\)/);
+            if (matches) {
+                const sounds = matches[1].split(' ');
+                const eventsPerCycle = sounds.length;
+                const duration = 1 / eventsPerCycle;
+                for (let cycle = 0; cycle < cycles; cycle++) {
+                    for (let i = 0; i < sounds.length; i++) {
+                        events.push({
+                            value: { s: sounds[i] },
+                            start: start + cycle + i * duration,
+                            end: start + cycle + (i + 1) * duration,
+                            isWhole: true,
+                        });
+                    }
+                }
+            }
+        }
+        return events;
+    }
+    compile(code) {
+        const transpileResult = this.transpile(code);
+        if (!transpileResult.success) {
+            throw new Error(`Transpilation failed: ${transpileResult.error}`);
+        }
+        return {
+            queryArc: (start, end) => this.queryEvents(code, start, end),
+        };
+    }
+    analyzePattern(code) {
+        const metadata = {
+            eventsPerCycle: 0,
+            uniqueValues: [],
+            usesSound: false,
+            usesNote: false,
+            isStack: false,
+            functionsUsed: [],
+            complexity: 0,
+        };
+        // Extract BPM from setcpm
+        const bpmMatch = code.match(/setcpm\s*\(\s*(\d+(?:\.\d+)?)\s*\)/);
+        if (bpmMatch) {
+            metadata.bpm = parseFloat(bpmMatch[1]);
+        }
+        metadata.usesSound = /\bs\s*\(/.test(code) || /\bsound\s*\(/.test(code);
+        metadata.usesNote = /\bnote\s*\(/.test(code);
+        metadata.isStack = /\bstack\s*\(/.test(code);
+        // Extract function names
+        const funcMatches = code.match(/\b([a-z][a-zA-Z0-9_]*)\s*\(/g);
+        if (funcMatches) {
+            const funcNames = funcMatches.map(m => m.replace(/\s*\($/, ''));
+            metadata.functionsUsed = [...new Set(funcNames)];
+        }
+        try {
+            const events = this.queryEvents(code, 0, 1);
+            metadata.eventsPerCycle = events.length;
+            const values = events.map(e => {
+                if (typeof e.value === 'object' && e.value !== null) {
+                    return e.value.s || e.value.note || e.value.n || JSON.stringify(e.value);
+                }
+                return String(e.value);
+            });
+            metadata.uniqueValues = [...new Set(values)];
+            metadata.complexity = Math.min((events.length / 16) * 0.3 +
+                (metadata.uniqueValues.length / 8) * 0.2 +
+                (metadata.functionsUsed.length / 10) * 0.3 +
+                (metadata.isStack ? 0.1 : 0) +
+                (code.length / 500) * 0.1, 1);
+        }
+        catch {
+            metadata.complexity = Math.min((metadata.functionsUsed.length / 10) * 0.5 +
+                (code.length / 500) * 0.3 +
+                (metadata.isStack ? 0.2 : 0), 1);
+        }
+        return metadata;
+    }
+}

package/dist/types/AudioAnalysis.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for advanced audio analysis
+ */
+export {};

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/ErrorRecovery.js

@@ -0,0 +1,248 @@
+/**
+ * ErrorRecovery - Provides graceful error handling and recovery mechanisms
+ * Ensures the MCP server can recover from browser crashes, network issues, and pattern errors
+ */
+import { Logger } from './Logger.js';
+export class ErrorRecovery {
+    logger;
+    errorHistory = new Map();
+    ERROR_WINDOW = 60000; // 1 minute window for error tracking
+    constructor() {
+        this.logger = new Logger();
+    }
+    /**
+     * Executes an operation with automatic retry logic
+     * @param operation - Async function to execute
+     * @param operationName - Name for logging
+     * @param strategy - Recovery strategy configuration
+     * @returns Result of the operation
+     */
+    async executeWithRetry(operation, operationName, strategy = {
+        maxRetries: 3,
+        retryDelay: 1000,
+        exponentialBackoff: true
+    }) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= strategy.maxRetries; attempt++) {
+            try {
+                this.logger.debug(`Executing ${operationName} (attempt ${attempt + 1}/${strategy.maxRetries + 1})`);
+                const result = await operation();
+                // Success - clear error history for this operation
+                this.clearErrorHistory(operationName);
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                this.recordError(operationName);
+                this.logger.warn(`${operationName} failed (attempt ${attempt + 1}/${strategy.maxRetries + 1})`, { error: error.message });
+                // Don't retry on last attempt
+                if (attempt < strategy.maxRetries) {
+                    const delay = strategy.exponentialBackoff
+                        ? strategy.retryDelay * Math.pow(2, attempt)
+                        : strategy.retryDelay;
+                    this.logger.debug(`Waiting ${delay}ms before retry`);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All retries failed
+        this.logger.error(`${operationName} failed after ${strategy.maxRetries + 1} attempts`);
+        // Try fallback if available
+        if (strategy.fallbackAction) {
+            this.logger.info(`Executing fallback for ${operationName}`);
+            try {
+                return await strategy.fallbackAction();
+            }
+            catch (fallbackError) {
+                this.logger.error(`Fallback failed for ${operationName}`, fallbackError);
+            }
+        }
+        throw new Error(`${operationName} failed after ${strategy.maxRetries + 1} attempts: ${lastError?.message}`);
+    }
+    /**
+     * Wraps an operation with timeout protection
+     * @param operation - Async function to execute
+     * @param timeout - Timeout in milliseconds
+     * @param operationName - Name for error messages
+     * @returns Result of the operation
+     */
+    async executeWithTimeout(operation, timeout, operationName) {
+        return Promise.race([
+            operation(),
+            this.createTimeout(timeout, operationName)
+        ]);
+    }
+    /**
+     * Combines retry logic with timeout protection
+     * @param operation - Async function to execute
+     * @param operationName - Name for logging
+     * @param timeout - Timeout per attempt in milliseconds
+     * @param strategy - Recovery strategy
+     * @returns Result of the operation
+     */
+    async executeWithRetryAndTimeout(operation, operationName, timeout, strategy) {
+        return this.executeWithRetry(() => this.executeWithTimeout(operation, timeout, operationName), operationName, strategy);
+    }
+    /**
+     * Gracefully handles browser initialization errors
+     * @param initFunction - Browser initialization function
+     * @returns Initialization result
+     */
+    async handleBrowserInit(initFunction) {
+        return this.executeWithRetryAndTimeout(initFunction, 'Browser Initialization', 30000, // 30 second timeout
+        {
+            maxRetries: 2,
+            retryDelay: 2000,
+            exponentialBackoff: true,
+            fallbackAction: async () => {
+                this.logger.warn('Browser initialization failed, suggesting headless mode');
+                return 'Browser initialization failed. Try setting headless:true in config.json';
+            }
+        });
+    }
+    /**
+     * Handles pattern write errors with validation
+     * @param writeFunction - Pattern write function
+     * @param pattern - Pattern to write
+     * @returns Write result
+     */
+    async handlePatternWrite(writeFunction, pattern) {
+        return this.executeWithRetry(() => writeFunction(pattern), 'Pattern Write', {
+            maxRetries: 2,
+            retryDelay: 500,
+            exponentialBackoff: false,
+            fallbackAction: async () => {
+                // Try writing a simplified version
+                const simplified = this.simplifyPattern(pattern);
+                this.logger.info('Attempting to write simplified pattern');
+                return writeFunction(simplified);
+            }
+        });
+    }
+    /**
+     * Checks if an operation is experiencing repeated failures
+     * @param operationName - Name of operation to check
+     * @param threshold - Number of errors to consider "frequent"
+     * @returns True if operation is failing frequently
+     */
+    isFrequentlyFailing(operationName, threshold = 3) {
+        const errors = this.errorHistory.get(operationName) || [];
+        const now = Date.now();
+        // Count errors within the time window
+        const recentErrors = errors.filter(timestamp => now - timestamp < this.ERROR_WINDOW);
+        return recentErrors.length >= threshold;
+    }
+    /**
+     * Gets error statistics for monitoring
+     * @returns Error statistics by operation
+     */
+    getErrorStats() {
+        const stats = {};
+        const now = Date.now();
+        this.errorHistory.forEach((timestamps, operation) => {
+            const recentErrors = timestamps.filter(ts => now - ts < this.ERROR_WINDOW);
+            stats[operation] = {
+                count: recentErrors.length,
+                lastError: recentErrors.length > 0 ? new Date(Math.max(...recentErrors)) : null
+            };
+        });
+        return stats;
+    }
+    /**
+     * Clears error history for a specific operation
+     * @param operationName - Operation to clear
+     */
+    clearErrorHistory(operationName) {
+        this.errorHistory.delete(operationName);
+    }
+    /**
+     * Clears all error history
+     */
+    clearAllErrorHistory() {
+        this.errorHistory.clear();
+    }
+    /**
+     * Records an error occurrence
+     * @param operationName - Name of the operation
+     */
+    recordError(operationName) {
+        const errors = this.errorHistory.get(operationName) || [];
+        errors.push(Date.now());
+        // Keep only recent errors
+        const now = Date.now();
+        const recentErrors = errors.filter(ts => now - ts < this.ERROR_WINDOW);
+        this.errorHistory.set(operationName, recentErrors);
+    }
+    /**
+     * Creates a timeout promise
+     * @param ms - Timeout in milliseconds
+     * @param operationName - Name for error message
+     * @returns Promise that rejects after timeout
+     */
+    createTimeout(ms, operationName) {
+        return new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`${operationName} timed out after ${ms}ms`));
+            }, ms);
+        });
+    }
+    /**
+     * Sleep utility
+     * @param ms - Milliseconds to sleep
+     * @returns Promise that resolves after delay
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Simplifies a pattern by removing complex modifiers
+     * @param pattern - Original pattern
+     * @returns Simplified pattern
+     */
+    simplifyPattern(pattern) {
+        // Remove complex modifiers but keep core structure
+        let simplified = pattern;
+        // Remove effect chains but keep basic sound/note calls
+        simplified = simplified.replace(/\.(delay|reverb|room|lpf|hpf|bpf)\([^)]*\)/g, '');
+        // Remove complex transformations
+        simplified = simplified.replace(/\.(jux|iter|chop|striate|scramble)\([^)]*\)/g, '');
+        // Remove conditional modifications
+        simplified = simplified.replace(/\.(sometimes|often|rarely|every)\([^)]*\)/g, '');
+        this.logger.debug('Pattern simplified', {
+            original: pattern.substring(0, 50) + '...',
+            simplified: simplified.substring(0, 50) + '...'
+        });
+        return simplified;
+    }
+    /**
+     * Handles network-related errors
+     * @param operation - Operation that may fail due to network
+     * @param operationName - Name for logging
+     * @returns Operation result
+     */
+    async handleNetworkOperation(operation, operationName) {
+        return this.executeWithRetry(operation, operationName, {
+            maxRetries: 5,
+            retryDelay: 2000,
+            exponentialBackoff: true,
+            fallbackAction: async () => {
+                throw new Error(`Network operation ${operationName} failed - check internet connection`);
+            }
+        });
+    }
+    /**
+     * Creates a circuit breaker for operations that fail frequently
+     * @param operation - Operation to protect
+     * @param operationName - Name for tracking
+     * @param threshold - Number of failures before circuit opens
+     * @returns Protected operation
+     */
+    createCircuitBreaker(operation, operationName, threshold = 5) {
+        return async () => {
+            if (this.isFrequentlyFailing(operationName, threshold)) {
+                throw new Error(`Circuit breaker open for ${operationName} - operation disabled due to repeated failures`);
+            }
+            return operation();
+        };
+    }
+}

package/dist/utils/InputValidator.js

@@ -0,0 +1,281 @@
+/**
+ * InputValidator - Comprehensive parameter validation for Strudel MCP Server
+ *
+ * Provides robust validation for all user inputs to prevent:
+ * - Invalid musical parameters (BPM, gain, etc.)
+ * - Speaker damage from excessive gain values
+ * - Mathematically invalid patterns (e.g., Euclidean rhythms)
+ * - Security issues from malformed inputs
+ *
+ * All methods throw descriptive errors for invalid inputs.
+ */
+export class InputValidator {
+    // Valid scale names from MusicTheory service
+    static VALID_SCALES = [
+        'major', 'minor', 'dorian', 'phrygian', 'lydian', 'mixolydian',
+        'aeolian', 'locrian', 'pentatonic', 'blues', 'chromatic',
+        'wholetone', 'harmonic_minor', 'melodic_minor'
+    ];
+    // Valid chord progression styles from MusicTheory service
+    static VALID_CHORD_STYLES = [
+        'pop', 'jazz', 'blues', 'folk', 'rock', 'classical', 'modal', 'edm'
+    ];
+    // Valid root notes (12-tone chromatic scale)
+    static VALID_ROOT_NOTES = [
+        'C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'
+    ];
+    /**
+     * Validates BPM (Beats Per Minute) is within acceptable range
+     *
+     * @param bpm - Tempo in beats per minute
+     * @throws {Error} When BPM is not a number, not finite, or outside 20-300 range
+     *
+     * @example
+     * InputValidator.validateBPM(120); // ✓ Valid
+     * InputValidator.validateBPM(19);  // ✗ Throws: BPM must be between 20 and 300
+     */
+    static validateBPM(bpm) {
+        if (typeof bpm !== 'number') {
+            throw new Error('BPM must be a number');
+        }
+        if (isNaN(bpm) || !isFinite(bpm)) {
+            throw new Error('BPM must be a valid number');
+        }
+        if (bpm < 20 || bpm > 300) {
+            throw new Error(`BPM must be between 20 and 300, got ${bpm}`);
+        }
+    }
+    /**
+     * Validates gain is within safe range to prevent speaker damage
+     *
+     * @param gain - Audio gain multiplier (0 = silence, 1 = unity, 2 = max safe)
+     * @throws {Error} When gain is not a number, not finite, or outside 0-2.0 range
+     *
+     * @example
+     * InputValidator.validateGain(1.0);  // ✓ Valid (unity gain)
+     * InputValidator.validateGain(10);   // ✗ Throws: Gain must be between 0 and 2.0
+     */
+    static validateGain(gain) {
+        if (typeof gain !== 'number') {
+            throw new Error('Gain must be a number');
+        }
+        if (isNaN(gain) || !isFinite(gain)) {
+            throw new Error('Gain must be a valid number');
+        }
+        if (gain < 0 || gain > 2.0) {
+            throw new Error(`Gain must be between 0 and 2.0, got ${gain}`);
+        }
+    }
+    /**
+     * Validates Euclidean rhythm parameters are mathematically valid
+     *
+     * Euclidean rhythms distribute hits evenly across steps.
+     * Example: 3 hits in 8 steps = "X..X..X." pattern
+     *
+     * @param hits - Number of beats/hits (must be <= steps)
+     * @param steps - Total number of steps in the pattern
+     * @throws {Error} When hits > steps or parameters are not valid integers
+     *
+     * @example
+     * InputValidator.validateEuclidean(3, 8);   // ✓ Valid
+     * InputValidator.validateEuclidean(10, 8);  // ✗ Throws: Hits cannot exceed steps
+     */
+    static validateEuclidean(hits, steps) {
+        // Validate hits
+        if (typeof hits !== 'number') {
+            throw new Error('Hits must be a number');
+        }
+        if (isNaN(hits) || !isFinite(hits)) {
+            throw new Error('Hits must be a valid number');
+        }
+        if (!Number.isInteger(hits)) {
+            throw new Error('Hits must be an integer');
+        }
+        if (hits < 0) {
+            throw new Error('Hits must be a non-negative integer');
+        }
+        // Validate steps
+        if (typeof steps !== 'number') {
+            throw new Error('Steps must be a number');
+        }
+        if (isNaN(steps) || !isFinite(steps)) {
+            throw new Error('Steps must be a valid number');
+        }
+        if (!Number.isInteger(steps)) {
+            throw new Error('Steps must be an integer');
+        }
+        if (steps <= 0) {
+            throw new Error('Steps must be a positive integer');
+        }
+        if (steps > 256) {
+            throw new Error(`Steps cannot exceed 256, got ${steps}`);
+        }
+        // Validate relationship
+        if (hits > steps) {
+            throw new Error(`Hits (${hits}) cannot exceed steps (${steps})`);
+        }
+    }
+    /**
+     * Validates musical scale name is supported by MusicTheory service
+     *
+     * @param name - Scale name (must be lowercase)
+     * @throws {Error} When scale name is invalid or not a string
+     *
+     * Supported scales:
+     * - major, minor, pentatonic, blues
+     * - Modes: dorian, phrygian, lydian, mixolydian, aeolian, locrian
+     * - Special: chromatic, wholetone, harmonic_minor, melodic_minor
+     *
+     * @example
+     * InputValidator.validateScaleName('major');   // ✓ Valid
+     * InputValidator.validateScaleName('Major');   // ✗ Throws: Invalid scale (case-sensitive)
+     */
+    static validateScaleName(name) {
+        if (typeof name !== 'string') {
+            throw new Error('Scale name must be a string');
+        }
+        const trimmed = name.trim();
+        if (trimmed.length === 0) {
+            throw new Error('Scale name cannot be empty');
+        }
+        if (trimmed.length > 100) {
+            throw new Error('Scale name too long (max 100 characters)');
+        }
+        if (!this.VALID_SCALES.includes(trimmed)) {
+            throw new Error(`Invalid scale name: ${name}`);
+        }
+    }
+    /**
+     * Validates chord progression style is supported by MusicTheory service
+     *
+     * @param style - Chord style (must be lowercase)
+     * @throws {Error} When chord style is invalid or not a string
+     *
+     * Supported styles: pop, jazz, blues, folk, rock, classical, modal, edm
+     *
+     * @example
+     * InputValidator.validateChordStyle('jazz');   // ✓ Valid
+     * InputValidator.validateChordStyle('Jazz');   // ✗ Throws: Invalid chord style
+     */
+    static validateChordStyle(style) {
+        if (typeof style !== 'string') {
+            throw new Error('Chord style must be a string');
+        }
+        const trimmed = style.trim();
+        if (trimmed.length === 0) {
+            throw new Error('Chord style cannot be empty');
+        }
+        if (trimmed.length > 100) {
+            throw new Error('Chord style too long (max 100 characters)');
+        }
+        if (!this.VALID_CHORD_STYLES.includes(trimmed)) {
+            throw new Error(`Invalid chord style: ${style}`);
+        }
+    }
+    /**
+     * Validates musical root note is a valid chromatic note
+     *
+     * @param note - Root note (A-G with optional #, case insensitive)
+     * @throws {Error} When note is invalid or not a string
+     *
+     * Valid notes: C, C#, D, D#, E, F, F#, G, G#, A, A#, B
+     *
+     * @example
+     * InputValidator.validateRootNote('C');    // ✓ Valid
+     * InputValidator.validateRootNote('f#');   // ✓ Valid (normalized to F#)
+     * InputValidator.validateRootNote('X');    // ✗ Throws: Invalid root note
+     */
+    static validateRootNote(note) {
+        if (typeof note !== 'string') {
+            throw new Error('Root note must be a string');
+        }
+        const trimmed = note.trim();
+        if (trimmed.length === 0) {
+            throw new Error('Root note cannot be empty');
+        }
+        if (trimmed.length > 10) {
+            throw new Error(`Root note too long (max 10 characters, got ${trimmed.length})`);
+        }
+        const normalized = trimmed.toUpperCase();
+        if (!this.VALID_ROOT_NOTES.includes(normalized)) {
+            throw new Error(`Invalid root note: ${note}. Valid notes: ${this.VALID_ROOT_NOTES.join(', ')}`);
+        }
+    }
+    /**
+     * Validates string length to prevent resource exhaustion
+     *
+     * @param str - String to validate
+     * @param fieldName - Field name for error messages
+     * @param maxLength - Maximum allowed length (default: 1000)
+     * @param allowEmpty - Whether to allow empty strings (default: false for identifiers, true for content)
+     * @throws {Error} When string exceeds maximum length or is not a string
+     *
+     * @example
+     * InputValidator.validateStringLength('hello', 'pattern', 100);  // ✓ Valid
+     * InputValidator.validateStringLength('x'.repeat(1001), 'pattern');  // ✗ Throws
+     * InputValidator.validateStringLength('', 'pattern', 1000, true);  // ✓ Valid (clearing pattern)
+     * InputValidator.validateStringLength('', 'name', 1000, false);  // ✗ Throws
+     */
+    static validateStringLength(str, fieldName, maxLength = 1000, allowEmpty = true) {
+        if (typeof str !== 'string') {
+            throw new Error(`${fieldName} must be a string`);
+        }
+        if (!allowEmpty && str.trim().length === 0) {
+            throw new Error(`${fieldName} cannot be empty`);
+        }
+        if (str.length > maxLength) {
+            throw new Error(`${fieldName} too long (max ${maxLength} characters, got ${str.length})`);
+        }
+    }
+    /**
+     * Validates a value is within 0-1 range (normalized/ratio value)
+     *
+     * Used for parameters like complexity, swing amount, humanize amount, etc.
+     * that represent normalized ratios or percentages.
+     *
+     * @param value - Number to validate
+     * @param fieldName - Field name for error messages
+     * @throws {Error} When value is not in 0-1 range
+     *
+     * @example
+     * InputValidator.validateNormalizedValue(0.5, 'complexity');  // ✓ Valid
+     * InputValidator.validateNormalizedValue(1.5, 'complexity');  // ✗ Throws
+     */
+    static validateNormalizedValue(value, fieldName) {
+        if (typeof value !== 'number') {
+            throw new Error(`${fieldName} must be a number`);
+        }
+        if (isNaN(value) || !isFinite(value)) {
+            throw new Error(`${fieldName} must be a valid number`);
+        }
+        if (value < 0 || value > 1.0) {
+            throw new Error(`${fieldName} must be between 0 and 1.0, got ${value}`);
+        }
+    }
+    /**
+     * Validates a value is a positive integer (> 0)
+     *
+     * @param value - Number to validate
+     * @param fieldName - Field name for error messages
+     * @throws {Error} When value is not a positive integer
+     *
+     * @example
+     * InputValidator.validatePositiveInteger(5, 'count');    // ✓ Valid
+     * InputValidator.validatePositiveInteger(0, 'count');    // ✗ Throws: must be positive
+     * InputValidator.validatePositiveInteger(1.5, 'count');  // ✗ Throws: must be integer
+     */
+    static validatePositiveInteger(value, fieldName) {
+        if (typeof value !== 'number') {
+            throw new Error(`${fieldName} must be a number`);
+        }
+        if (isNaN(value) || !isFinite(value)) {
+            throw new Error(`${fieldName} must be a valid number`);
+        }
+        if (!Number.isInteger(value)) {
+            throw new Error(`${fieldName} must be an integer`);
+        }
+        if (value <= 0) {
+            throw new Error(`${fieldName} must be a positive integer`);
+        }
+    }
+}