@gotza02/sequential-thinking 10000.2.0 → 10000.2.2

package/dist/tools/sports/tools/match.js

@@ -10,26 +10,10 @@ import { getGlobalCache, CacheService } from '../core/cache.js';
 import { formatMatchesTable, formatScore, formatMatchStatus } from '../utils/formatter.js';
 import { CACHE_CONFIG, LEAGUES } from '../core/constants.js';
 import { logger } from '../../../utils.js';
-// ============= Helper Functions =============
-/**
- * Get date context for search queries
- */
-function getDateContext() {
-    const now = new Date();
-    const month = now.toLocaleDateString('en-US', { month: 'long' });
-    const year = now.getFullYear();
-    return ` ${month} ${year}`;
-}
-/**
- * Normalize team names for better matching
- */
-function normalizeTeamName(name) {
-    return name
-        .toLowerCase()
-        .replace(/\b(fc|afc|sc|cf|united|utd|city|town|athletic|albion|rovers|wanderers|olympic|real)\b/g, '')
-        .replace(/\s+/g, ' ')
-        .trim();
-}
+import { getDateContext, isTeamMatch, getAnalysisInstructions } from './match-helpers.js';
+// Note: calculateAdaptiveTTL, calculateProbabilityRange, calculateFormPoints,
+// calculateExpectedGoals, calculateProbabilitiesFromForm, and getLeagueId
+// are defined locally in this file with specific implementations for match analysis
 /**
  * Try to find match ID from API by team names and league
  */
@@ -48,9 +32,9 @@ async function findMatchId(homeTeam, awayTeam, league) {
         if (liveResult.success && liveResult.data) {
             const match = liveResult.data.find(m => {
                 const isHomeMatch = homeIds.includes(m.homeTeam.id) ||
-                    normalizeTeamName(m.homeTeam.name).includes(normalizeTeamName(homeTeam));
+                    isTeamMatch(homeTeam, m.homeTeam.name);
                 const isAwayMatch = awayIds.includes(m.awayTeam.id) ||
-                    normalizeTeamName(m.awayTeam.name).includes(normalizeTeamName(awayTeam));
+                    isTeamMatch(awayTeam, m.awayTeam.name);
                 return isHomeMatch && isAwayMatch;
             });
             if (match)
@@ -248,7 +232,7 @@ function formatH2HData(h2h, homeTeam, awayTeam) {
  * Get match result character (W/D/L) for a team
  */
 function getMatchResultChar(match, teamName) {
-    const isHome = match.homeTeam.name.includes(teamName);
+    const isHome = isTeamMatch(teamName, match.homeTeam.name);
     const homeScore = match.score?.home ?? 0;
     const awayScore = match.score?.away ?? 0;
     if (isHome) {
@@ -265,7 +249,8 @@ function formatTeamForm(form, teamName, isHomeTeam) {
     const label = isHomeTeam ? 'Home' : 'Away';
     let output = `### ${teamName} Recent Form (Last ${form.length})\n`;
     output += form.map(m => {
-        const opponent = isHomeTeam ? m.awayTeam.name : m.homeTeam.name;
+        const isHomeInMatch = isTeamMatch(teamName, m.homeTeam.name);
+        const opponent = isHomeInMatch ? m.awayTeam.name : m.homeTeam.name;
         const score = m.score ? `${m.score.home}-${m.score.away}` : '?';
         const result = getMatchResultChar(m, teamName);
         return `- ${result} vs ${opponent} (${score})`;
@@ -345,65 +330,6 @@ async function scrapeContentWithErrorHandling(url, type) {
         return `${type.charAt(0).toUpperCase() + type.slice(1)} scrape failed: ${errorMsg}`;
     }
 }
-/**
- * Get analysis framework instructions
- */
-function getAnalysisInstructions() {
-    return `INSTRUCTIONS: Act as a World-Class Football Analysis Panel. Provide a deep, non-obvious analysis using this framework:\n\n` +
-        `1. 📊 THE DATA SCIENTIST (Quantitative):\n   - Analyze xG trends & Possession stats.\n   - Assess Home/Away variance.\n\n` +
-        `2. 🧠 THE TACTICAL SCOUT (Qualitative):\n   - Stylistic Matchup (Press vs Block).\n   - Key Battles.\n\n` +
-        `3. 🚑 THE PHYSIO (Physical Condition):\n   - FATIGUE CHECK: Days rest? Travel distance?\n   - Squad Depth: Who has the better bench?\n\n` +
-        `4. 🎯 SET PIECE ANALYST:\n   - Corners/Free Kicks: Strong vs Weak?\n   - Who is most likely to score from a header?\n\n` +
-        `5. 💎 THE INSIDER (External Factors):\n   - Market Movements (Odds dropping?).\n   - Referee & Weather impact.\n\n` +
-        `6. 🕵️ THE SKEPTIC & SCENARIOS:\n   - Why might the favorite LOSE?\n   - Game Script: "If Team A scores first..."\n\n` +
-        `🏆 FINAL VERDICT:\n   - Asian Handicap Leans\n   - Goal Line (Over/Under)\n   - The "Value Pick"`;
-}
-/**
- * Calculate adaptive TTL based on data type and match timing
- */
-function calculateAdaptiveTTL(dataType, matchDate) {
-    const now = Date.now();
-    const hoursUntilMatch = matchDate
-        ? (matchDate.getTime() - now) / (1000 * 60 * 60)
-        : Infinity;
-    switch (dataType) {
-        case 'odds':
-            // Odds change frequently - short TTL
-            if (hoursUntilMatch < 1)
-                return 60 * 1000; // 1 minute
-            if (hoursUntilMatch < 24)
-                return 5 * 60 * 1000; // 5 minutes
-            return 15 * 60 * 1000; // 15 minutes
-        case 'lineups':
-            // Lineups announced ~1 hour before match
-            if (hoursUntilMatch < 2)
-                return 5 * 60 * 1000; // 5 minutes
-            return 60 * 60 * 1000; // 1 hour
-        case 'news':
-            // News changes throughout the day
-            if (hoursUntilMatch < 24)
-                return 15 * 60 * 1000; // 15 minutes
-            return 60 * 60 * 1000; // 1 hour
-        case 'stats':
-        case 'h2h':
-            // Historical stats don't change
-            return 24 * 60 * 60 * 1000; // 24 hours
-        case 'form':
-            // Form updates after each match
-            if (hoursUntilMatch < 0)
-                return 60 * 1000; // Live match - 1 minute
-            return 6 * 60 * 60 * 1000; // 6 hours
-        case 'match':
-            // Match data changes based on timing
-            if (hoursUntilMatch < 0)
-                return 60 * 1000; // Live - 1 minute
-            if (hoursUntilMatch < 1)
-                return 5 * 60 * 1000; // 5 minutes
-            return 30 * 60 * 1000; // 30 minutes
-        default:
-            return 30 * 60 * 1000; // 30 minutes default
-    }
-}
 /**
  * Perform comprehensive match analysis using web search
  */
@@ -465,24 +391,6 @@ async function scrapeDeepDiveSources(candidateUrls) {
     }
     return output;
 }
-/**
- * Calculate probability range with uncertainty quantification
- */
-function calculateProbabilityRange(baseProbability, dataQuality) {
-    // Higher data quality = narrower range
-    const qualityFactor = dataQuality.score / 100;
-    const baseUncertainty = 0.15; // 15% base uncertainty
-    // Adjust uncertainty based on data quality
-    const adjustedUncertainty = baseUncertainty * (1 - qualityFactor * 0.7);
-    // Calculate range
-    const mid = baseProbability;
-    const margin = adjustedUncertainty * Math.sqrt(baseProbability * (1 - baseProbability));
-    return {
-        low: Math.max(0, mid - margin * 1.645), // 5th percentile
-        mid,
-        high: Math.min(1, mid + margin * 1.645), // 95th percentile
-    };
-}
 /**
  * Detect value bets from predictions and odds
  */
@@ -493,22 +401,33 @@ async function detectValueBets(apiData, homeTeam, awayTeam) {
     // Estimate probabilities from API data
     // Simple model: use form and H2H to estimate
     let homeWinProb = 0.33;
-    let drawProb = 0.33;
+    let drawProb = 0.34;
     let awayWinProb = 0.33;
-    if (apiData.homeForm && apiData.awayForm) {
-        const homeWins = apiData.homeForm.filter(m => {
-            const isHome = m.homeTeam.name.includes(homeTeam);
-            return isHome ? (m.score?.home ?? 0) > (m.score?.away ?? 0) : (m.score?.away ?? 0) > (m.score?.home ?? 0);
-        }).length;
-        const awayWins = apiData.awayForm.filter(m => {
-            const isAway = m.awayTeam.name.includes(awayTeam);
-            return isAway ? (m.score?.away ?? 0) > (m.score?.home ?? 0) : (m.score?.home ?? 0) > (m.score?.away ?? 0);
-        }).length;
-        // Normalize to probabilities
-        const total = homeWins + awayWins + 2; // +2 for draws
-        homeWinProb = (homeWins + 1) / total;
-        awayWinProb = (awayWins + 1) / total;
-        drawProb = 1 - homeWinProb - awayWinProb;
+    if (apiData.homeForm?.length && apiData.awayForm?.length) {
+        // Calculate form based on points (3 for win, 1 for draw)
+        const homePoints = calculateFormPoints(apiData.homeForm, homeTeam);
+        const awayPoints = calculateFormPoints(apiData.awayForm, awayTeam);
+        // Number of matches played
+        const homeMatches = apiData.homeForm.length;
+        const awayMatches = apiData.awayForm.length;
+        // Points per game
+        const homePPG = homePoints / homeMatches;
+        const awayPPG = awayPoints / awayMatches;
+        // Max PPG is 3, so normalize to probability
+        // Give small bonus to home team (home advantage ~5-10%)
+        const totalPPG = homePPG + awayPPG;
+        if (totalPPG > 0) {
+            homeWinProb = Math.min(0.6, (homePPG / totalPPG) * 0.9 + 0.05); // Home advantage
+            awayWinProb = Math.min(0.5, (awayPPG / totalPPG) * 0.9);
+            // Draw probability based on how close the teams are
+            const ppgDiff = Math.abs(homePPG - awayPPG);
+            drawProb = Math.max(0.15, 0.35 - ppgDiff * 0.1); // Closer teams = higher draw chance
+            // Normalize to ensure sum = 1
+            const total = homeWinProb + drawProb + awayWinProb;
+            homeWinProb /= total;
+            drawProb /= total;
+            awayWinProb /= total;
+        }
     }
     // Calculate value for each market
     const markets = [
@@ -537,6 +456,100 @@ async function detectValueBets(apiData, homeTeam, awayTeam) {
             });
         }
     }
+    // Check Asian Handicap market if available
+    if (apiData.odds.asianHandicap) {
+        const ah = apiData.odds.asianHandicap;
+        // Estimate AH probability based on match probabilities and line
+        // Simplified: home wins if they overcome the handicap
+        const ahHomeProb = homeWinProb + (drawProb * 0.5); // Approximate
+        const ahAwayProb = awayWinProb + (drawProb * 0.5);
+        if (ah.home && ahHomeProb > 0) {
+            const fairOdds = 1 / ahHomeProb;
+            const value = (ah.home / fairOdds) - 1;
+            if (value >= 0.05) {
+                const kelly = (ahHomeProb * ah.home - 1) / (ah.home - 1);
+                valueBets.push({
+                    selection: `${homeTeam} AH ${ah.line > 0 ? '+' : ''}${ah.line}`,
+                    market: 'asian_handicap',
+                    odds: ah.home,
+                    fairOdds,
+                    value,
+                    confidence: Math.min(90, 50 + value * 200),
+                    kellyFraction: Math.max(0, kelly / 2),
+                    recommendedStake: Math.max(0, kelly / 2) * 100,
+                    reasoning: `Line ${ah.line}, estimated prob ${(ahHomeProb * 100).toFixed(1)}%`,
+                });
+            }
+        }
+        if (ah.away && ahAwayProb > 0) {
+            const fairOdds = 1 / ahAwayProb;
+            const value = (ah.away / fairOdds) - 1;
+            if (value >= 0.05) {
+                const kelly = (ahAwayProb * ah.away - 1) / (ah.away - 1);
+                valueBets.push({
+                    selection: `${awayTeam} AH ${ah.line > 0 ? '-' : '+'}${Math.abs(ah.line)}`,
+                    market: 'asian_handicap',
+                    odds: ah.away,
+                    fairOdds,
+                    value,
+                    confidence: Math.min(90, 50 + value * 200),
+                    kellyFraction: Math.max(0, kelly / 2),
+                    recommendedStake: Math.max(0, kelly / 2) * 100,
+                    reasoning: `Line ${-ah.line}, estimated prob ${(ahAwayProb * 100).toFixed(1)}%`,
+                });
+            }
+        }
+    }
+    // Check Over/Under market if available
+    if (apiData.odds.overUnder) {
+        const ou = apiData.odds.overUnder;
+        // Estimate over probability based on expected goals
+        const expectedTotal = (apiData.homeForm?.length && apiData.awayForm?.length)
+            ? calculateExpectedGoals(apiData, homeTeam, awayTeam)
+            : { home: 1.5, away: 1.2 };
+        const totalXG = expectedTotal.home + expectedTotal.away;
+        // Simple model: over if total xG > line
+        const overProb = totalXG > ou.line
+            ? 0.5 + (totalXG - ou.line) * 0.1
+            : 0.5 - (ou.line - totalXG) * 0.1;
+        const underProb = 1 - overProb;
+        if (ou.over && overProb > 0) {
+            const fairOdds = 1 / Math.min(0.9, Math.max(0.1, overProb));
+            const value = (ou.over / fairOdds) - 1;
+            if (value >= 0.05) {
+                const kelly = (overProb * ou.over - 1) / (ou.over - 1);
+                valueBets.push({
+                    selection: `Over ${ou.line}`,
+                    market: 'over_under',
+                    odds: ou.over,
+                    fairOdds,
+                    value,
+                    confidence: Math.min(90, 50 + value * 200),
+                    kellyFraction: Math.max(0, kelly / 2),
+                    recommendedStake: Math.max(0, kelly / 2) * 100,
+                    reasoning: `Line ${ou.line}, expected goals ${totalXG.toFixed(1)}`,
+                });
+            }
+        }
+        if (ou.under && underProb > 0) {
+            const fairOdds = 1 / Math.min(0.9, Math.max(0.1, underProb));
+            const value = (ou.under / fairOdds) - 1;
+            if (value >= 0.05) {
+                const kelly = (underProb * ou.under - 1) / (ou.under - 1);
+                valueBets.push({
+                    selection: `Under ${ou.line}`,
+                    market: 'over_under',
+                    odds: ou.under,
+                    fairOdds,
+                    value,
+                    confidence: Math.min(90, 50 + value * 200),
+                    kellyFraction: Math.max(0, kelly / 2),
+                    recommendedStake: Math.max(0, kelly / 2) * 100,
+                    reasoning: `Line ${ou.line}, expected goals ${totalXG.toFixed(1)}`,
+                });
+            }
+        }
+    }
     return valueBets.sort((a, b) => b.value - a.value);
 }
 /**
@@ -544,7 +557,7 @@ async function detectValueBets(apiData, homeTeam, awayTeam) {
  */
 function calculateFormPoints(form, teamName) {
     return form.reduce((sum, m) => {
-        const isHome = m.homeTeam.name.includes(teamName);
+        const isHome = isTeamMatch(teamName, m.homeTeam.name);
         const score = m.score;
         if (!score)
             return sum;
@@ -558,16 +571,90 @@ function calculateFormPoints(form, teamName) {
     }, 0);
 }
 /**
- * Calculate probabilities from form data
+ * Calculate expected goals from form data
+ * Uses average goals scored and conceded to estimate xG
+ */
+function calculateExpectedGoals(apiData, homeTeam, awayTeam) {
+    if (!apiData?.homeForm?.length || !apiData?.awayForm?.length) {
+        // Default: league average with home advantage
+        return { home: 1.5, away: 1.2 };
+    }
+    // Calculate average goals scored and conceded for home team
+    let homeGoalsScored = 0;
+    let homeGoalsConceded = 0;
+    let homeMatchesWithScores = 0;
+    for (const match of apiData.homeForm) {
+        if (match.score) {
+            const isHomeInMatch = isTeamMatch(homeTeam, match.homeTeam.name);
+            homeGoalsScored += isHomeInMatch ? match.score.home : match.score.away;
+            homeGoalsConceded += isHomeInMatch ? match.score.away : match.score.home;
+            homeMatchesWithScores++;
+        }
+    }
+    // Calculate average goals scored and conceded for away team
+    let awayGoalsScored = 0;
+    let awayGoalsConceded = 0;
+    let awayMatchesWithScores = 0;
+    for (const match of apiData.awayForm) {
+        if (match.score) {
+            const isAwayInMatch = isTeamMatch(awayTeam, match.awayTeam.name);
+            awayGoalsScored += isAwayInMatch ? match.score.away : match.score.home;
+            awayGoalsConceded += isAwayInMatch ? match.score.home : match.score.away;
+            awayMatchesWithScores++;
+        }
+    }
+    // Calculate averages
+    const homeScoringAvg = homeMatchesWithScores > 0 ? homeGoalsScored / homeMatchesWithScores : 1.5;
+    const homeConcedingAvg = homeMatchesWithScores > 0 ? homeGoalsConceded / homeMatchesWithScores : 1.2;
+    const awayScoringAvg = awayMatchesWithScores > 0 ? awayGoalsScored / awayMatchesWithScores : 1.2;
+    const awayConcedingAvg = awayMatchesWithScores > 0 ? awayGoalsConceded / awayMatchesWithScores : 1.5;
+    // xG estimate using average of "what team scores" and "what opponent concedes"
+    // with home advantage adjustment
+    const homeAdvantage = 1.15; // ~15% boost for home
+    const homeXG = ((homeScoringAvg + awayConcedingAvg) / 2) * homeAdvantage;
+    const awayXG = (awayScoringAvg + homeConcedingAvg) / 2;
+    // Clamp to reasonable values (0.5 to 3.5 goals)
+    return {
+        home: Math.min(3.5, Math.max(0.5, homeXG)),
+        away: Math.min(3.5, Math.max(0.5, awayXG)),
+    };
+}
+/**
+ * Calculate probabilities from form data using proper normalization
  */
 function calculateProbabilitiesFromForm(homeForm, awayForm, homeTeam, awayTeam) {
     const homePoints = calculateFormPoints(homeForm, homeTeam);
     const awayPoints = calculateFormPoints(awayForm, awayTeam);
-    const totalPoints = homePoints + awayPoints + 5; // +5 for draw possibility
+    // Points per game
+    const homePPG = homePoints / Math.max(1, homeForm.length);
+    const awayPPG = awayPoints / Math.max(1, awayForm.length);
+    // Use Bradley-Terry inspired model
+    // Convert PPG to relative strength (max 3 points per game)
+    const homeStrength = homePPG / 3;
+    const awayStrength = awayPPG / 3;
+    // Apply home advantage (~10% boost)
+    const homeAdvantage = 1.1;
+    const effectiveHomeStrength = homeStrength * homeAdvantage;
+    // Calculate probabilities
+    const totalStrength = effectiveHomeStrength + awayStrength;
+    if (totalStrength < 0.1) {
+        // Not enough data, return defaults
+        return { homeWin: 0.35, draw: 0.30, awayWin: 0.35 };
+    }
+    // Raw win probabilities (before draw adjustment)
+    const rawHomeWin = effectiveHomeStrength / totalStrength;
+    const rawAwayWin = awayStrength / totalStrength;
+    // Draw probability based on how close teams are
+    // When teams are equal, draw probability is higher
+    const strengthDiff = Math.abs(homeStrength - awayStrength);
+    const drawProb = Math.max(0.15, 0.30 - strengthDiff * 0.3);
+    // Adjust win probabilities to account for draw
+    const remainingProb = 1 - drawProb;
+    const winRatio = rawHomeWin / (rawHomeWin + rawAwayWin);
     return {
-        homeWin: (homePoints + 1.5) / totalPoints,
-        draw: 5 / totalPoints,
-        awayWin: (awayPoints + 1.5) / totalPoints,
+        homeWin: remainingProb * winRatio,
+        draw: drawProb,
+        awayWin: remainingProb * (1 - winRatio),
     };
 }
 /**
@@ -609,7 +696,7 @@ async function buildStructuredAnalysis(homeTeam, awayTeam, league, apiData, cove
             homeWinProbability: predictions.matchResult.homeWin,
             drawProbability: predictions.matchResult.draw,
             awayWinProbability: predictions.matchResult.awayWin,
-            expectedGoals: { home: 1.3, away: 1.2 }, // Placeholder - would need xG data
+            expectedGoals: calculateExpectedGoals(apiData, homeTeam, awayTeam),
             keyStats: [],
         },
         tacticalScout: {
@@ -821,8 +908,8 @@ Data cached for 1 minute.`, {
                 matches = result.data;
                 // Filter by team if specified
                 if (team) {
-                    matches = matches.filter((m) => m.homeTeam.name.toLowerCase().includes(team.toLowerCase()) ||
-                        m.awayTeam.name.toLowerCase().includes(team.toLowerCase()));
+                    matches = matches.filter((m) => isTeamMatch(team, m.homeTeam.name) ||
+                        isTeamMatch(team, m.awayTeam.name));
                 }
                 // Limit results
                 matches = matches.slice(0, limit);
@@ -934,6 +1021,21 @@ Requires API provider with match ID.`, {
     });
 }
 // ============= Helper Functions =============
+/**
+ * Calculate probability range with uncertainty quantification
+ */
+function calculateProbabilityRange(baseProbability, dataQuality) {
+    const qualityFactor = dataQuality.score / 100;
+    const baseUncertainty = 0.15;
+    const adjustedUncertainty = baseUncertainty * (1 - qualityFactor * 0.7);
+    const mid = baseProbability;
+    const margin = adjustedUncertainty * Math.sqrt(mid * (1 - mid) + 0.1);
+    return {
+        low: Math.max(0, mid - margin * 1.96),
+        mid: Math.min(1, Math.max(0, mid)),
+        high: Math.min(1, mid + margin * 1.96),
+    };
+}
 /**
  * Get league ID from league name
  */

package/dist/tools/sports.js

@@ -91,7 +91,7 @@ function registerLegacyAnalyzeMatch(server) {
                     const data = await response.json();
                     const items = data.web?.results || [];
                     items.forEach((item) => candidateUrls.push(item.url));
-                    resultsText = items.map((item) => `- [${item.title}](${item.url}): ${item.description}`).join('\n');
+                    resultsText = items.map((item) => `- [${item.title}](${item.url}): ${item.description ?? ''}`).join('\n');
                 }
                 else if (searchProvider === 'exa') {
                     const response = await fetchWithRetry('https://api.exa.ai/search', {
@@ -107,7 +107,7 @@ function registerLegacyAnalyzeMatch(server) {
                     const data = await response.json();
                     const items = data.results || [];
                     items.forEach((item) => candidateUrls.push(item.url));
-                    resultsText = items.map((item) => `- [${item.title}](${item.url}): ${item.text || item.title}`).join('\n');
+                    resultsText = items.map((item) => `- [${item.title}](${item.url}): ${item.text ?? item.title}`).join('\n');
                 }
                 else if (searchProvider === 'google') {
                     const response = await fetchWithRetry(`https://www.googleapis.com/customsearch/v1?key=${process.env.GOOGLE_SEARCH_API_KEY}&cx=${process.env.GOOGLE_SEARCH_CX}&q=${encodeURIComponent(q.query)}&num=4`);
@@ -116,7 +116,7 @@ function registerLegacyAnalyzeMatch(server) {
                     const data = await response.json();
                     const items = data.items || [];
                     items.forEach((item) => candidateUrls.push(item.link));
-                    resultsText = items.map((item) => `- [${item.title}](${item.link}): ${item.snippet}`).join('\n');
+                    resultsText = items.map((item) => `- [${item.title}](${item.link}): ${item.snippet ?? ''}`).join('\n');
                 }
                 return `### ${q.type}\n${resultsText}\n`;
             }

package/dist/utils.d.ts

@@ -1,63 +1,130 @@
+declare const CONFIG: {
+    readonly COMMAND_TIMEOUT: 60000;
+    readonly MAX_BUFFER: number;
+    readonly MAX_PATTERN_LENGTH: 500;
+    readonly MAX_QUANTIFIERS: 20;
+    readonly MAX_LOCKS: 1000;
+    readonly DNS_TIMEOUT: 5000;
+    readonly MAX_INPUT_LENGTH: 10000;
+    readonly RETRY: {
+        readonly MAX_RETRIES: 3;
+        readonly BASE_DELAY: 1000;
+        readonly BACKOFF_MULTIPLIER: 2;
+    };
+};
+/**
+ * Whitelist of safe commands. Consider loading from config file for flexibility.
+ */
+declare const SAFE_COMMANDS: ReadonlySet<string>;
+export declare class SecurityError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class ValidationError extends Error {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(message: string, timeout: number);
+}
+interface ParsedCommand {
+    command: string;
+    args: string[];
+}
 /**
- * Execute a shell command with security protections against command injection.
- * Uses spawn() instead of exec() to avoid shell interpretation.
- *
- * @param command - The command string to execute
- * @param options - Execution options (timeout, maxBuffer)
- * @returns Promise with stdout and stderr
- * @throws Error if command contains shell metacharacters or is not whitelisted
+ * Robust command parser supporting quotes and escapes.
+ * State machine implementation for correctness.
  */
-export declare function execAsync(command: string, options?: {
+declare function parseCommand(command: string): ParsedCommand;
+export interface ExecOptions {
     timeout?: number;
     maxBuffer?: number;
-}): Promise<{
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ExecResult {
     stdout: string;
     stderr: string;
-}>;
+    exitCode: number;
+    executionTime: number;
+}
+/**
+ * Execute command securely using spawn (no shell interpretation).
+ */
+export declare function execAsync(command: string, options?: ExecOptions): Promise<ExecResult>;
 export declare class AsyncMutex {
-    private mutex;
-    lock(): Promise<() => void>;
-    dispatch<T>(fn: (() => T | PromiseLike<T>)): Promise<T>;
+    private queue;
+    private locked;
+    acquire(): Promise<() => void>;
+    private release;
+    dispatch<T>(fn: () => T | PromiseLike<T>): Promise<T>;
+}
+export declare class FileLock {
+    private locks;
+    private queue;
+    private readonly maxLocks;
+    constructor(maxLocks?: 1000);
+    acquire(filePath: string, timeout?: number): Promise<{
+        release: () => void;
+    }>;
+    private waitForLock;
+    private release;
+    private cleanupStaleLocks;
+    getLockCount(): number;
+    getQueueCount(): number;
 }
+export declare const fileLock: FileLock;
 export declare function validatePath(requestedPath: string): string;
+declare function isPrivateIPv4(ip: string): boolean;
+declare function isPrivateIPv6(ip: string): boolean;
 export declare function validatePublicUrl(urlString: string): Promise<void>;
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LoggerOptions {
+    level?: LogLevel;
+    useColors?: boolean;
+    output?: 'stdout' | 'stderr';
+}
 declare class Logger {
     private level;
-    constructor();
+    private useColors;
+    private output;
+    private static readonly LEVELS;
+    private static readonly COLORS;
+    constructor(options?: LoggerOptions);
     private shouldLog;
-    debug(msg: string, ...args: any[]): void;
-    info(msg: string, ...args: any[]): void;
-    warn(msg: string, ...args: any[]): void;
-    error(msg: string, ...args: any[]): void;
+    private formatMessage;
+    private print;
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    setLevel(level: LogLevel): void;
 }
 export declare const logger: Logger;
-/**
- * Validate a regex pattern for ReDoS vulnerabilities
- * @throws Error if pattern is unsafe
- */
+export declare class ReDoSError extends SecurityError {
+    constructor(message: string);
+}
 export declare function validateRegexPattern(pattern: string): void;
-/**
- * Create a RegExp object with ReDoS protection
- * @param pattern - The regex pattern
- * @param flags - Regex flags (g, i, m, etc.)
- * @returns Safe RegExp object
- * @throws Error if pattern is unsafe
- */
 export declare function createSafeRegex(pattern: string, flags?: string): RegExp;
-export declare const DEFAULT_HEADERS: {
-    'User-Agent': string;
-    Accept: string;
-    'Accept-Language': string;
-};
-export declare function fetchWithRetry(url: string, options?: any, retries?: number, backoff?: number): Promise<Response>;
-export declare function withRetry(fn: () => Promise<any>, maxRetries?: number, baseDelay?: number): Promise<any>;
-export declare class FileLock {
-    locks: Map<any, any>;
-    acquire(filePath: string, timeout?: number): Promise<{
-        release: () => void;
-    }>;
+export declare const DEFAULT_HEADERS: Readonly<Record<string, string>>;
+export interface FetchOptions extends RequestInit {
+    retries?: number;
+    backoff?: number;
+    validateUrl?: boolean;
 }
-export declare const fileLock: FileLock;
-export declare function sanitizeInput(input: any, maxLength?: number): string;
-export {};
+export declare function fetchWithRetry(url: string, options?: FetchOptions): Promise<Response>;
+export declare function withRetry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    onRetry?: (error: Error, attempt: number) => void;
+    shouldRetry?: (error: Error) => boolean;
+}): Promise<T>;
+export interface SanitizeOptions {
+    maxLength?: number;
+    allowedPattern?: RegExp;
+    removeNull?: boolean;
+    trim?: boolean;
+}
+export declare function sanitizeInput(input: unknown, options?: SanitizeOptions): string;
+export { CONFIG, SAFE_COMMANDS, parseCommand, isPrivateIPv4, isPrivateIPv6, Logger, };