@yasserkhanorg/impact-gate 2.0.0

package/dist/esm/prompts/strategist.js

@@ -0,0 +1,61 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { sanitizeForPrompt } from '../crew/sanitize.js';
+import { extractJsonFromResponse } from './json_extract.js';
+export function buildStrategistPrompt(ctx) {
+    const flowsBlock = ctx.impactedFlows
+        .map((f) => {
+        const specs = f.existingSpecs.map((s) => `${s.path} (${s.coverageLevel})`).join(', ') || 'none';
+        return [
+            `- ${f.flowId} (${f.priority}): ${f.flowName}`,
+            `  Route Family: ${f.routeFamily}`,
+            `  Action: ${f.action}`,
+            `  Confidence: ${f.confidence}%`,
+            `  Existing Coverage: ${specs}`,
+            `  User Actions: ${sanitizeForPrompt(f.userActions.join('; ') || 'unknown')}`,
+            `  Changed Files: ${f.changedFiles.join(', ')}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+    const crossImpactBlock = ctx.crossImpacts.length > 0
+        ? ctx.crossImpacts.map((ci) => `- ${ci.sourceFamily} → ${ci.affectedFamily} (${ci.riskLevel}): ${ci.sharedDependency} — ${ci.evidence}`).join('\n')
+        : 'No cross-family impacts detected.';
+    const regressionBlock = ctx.regressionRisks.length > 0
+        ? ctx.regressionRisks.map((r) => `- ${r.familyId} (risk=${r.riskScore}): ${r.reason}`).join('\n')
+        : 'No regression risk data available.';
+    return [
+        'You are a senior QA strategist designing the overall test strategy for a code change.',
+        '',
+        `IMPACTED FLOWS (${ctx.impactedFlows.length}):`,
+        flowsBlock,
+        '',
+        'CROSS-FAMILY IMPACTS:',
+        crossImpactBlock,
+        '',
+        'REGRESSION RISK:',
+        regressionBlock,
+        '',
+        'TASK: Design a prioritized test strategy for each impacted flow.',
+        '',
+        'For each flow, decide:',
+        '1. Approach: full-test (comprehensive), smoke-test (critical path only), skip, or manual-review',
+        '2. Priority: P0 (critical path), P1 (important), P2 (nice to have)',
+        '3. Test categories to cover (from: happy-path, edge-case, boundary, negative, state-transition, race-condition, permission, accessibility, performance)',
+        '4. Cross-impact risk level based on shared dependencies',
+        '',
+        'Return strict JSON only with this shape:',
+        '{"strategy":[{"flowId":"<id>","flowName":"<name>","priority":"P0|P1|P2","approach":"full-test|smoke-test|skip|manual-review","rationale":"<why this approach>","testCategories":["happy-path","edge-case",...],"crossImpactRisk":"high|medium|low|none"}]}',
+        '',
+        'Rules:',
+        '- P0 flows with create_spec or add_scenarios action should always get full-test.',
+        '- Flows with high cross-impact risk should be promoted to at least P1.',
+        '- Flows with high regression risk should include edge-case and boundary categories.',
+        '- Skip flows only if confidence < 30 AND no cross-impact risk.',
+        '- Include accessibility category for any flow involving interactive UI elements.',
+        '- Include permission category for any flow involving role-based features.',
+        '- Keep rationale concise (1-2 sentences) explaining why this approach was chosen.',
+    ].join('\n');
+}
+export function parseStrategistResponse(text) {
+    return extractJsonFromResponse(text, (obj) => obj != null && typeof obj === 'object' && Array.isArray(obj.strategy));
+}

package/dist/esm/prompts/test-designer.js

@@ -0,0 +1,92 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { extractJsonFromResponse } from './json_extract.js';
+import { formatApiSurfaceForPrompt } from '../knowledge/api_surface.js';
+import { sanitizeForPrompt } from '../crew/sanitize.js';
+export function buildTestDesignerPrompt(ctx) {
+    const relevantClasses = ctx.apiSurface.pageObjects
+        .map((po) => po.className)
+        .filter((name) => {
+        const lower = name.toLowerCase();
+        const hints = [ctx.flow.routeFamily, ctx.flow.featureId, ...ctx.flow.userActions.join(' ').split(/\s+/)]
+            .filter(Boolean)
+            .map((s) => s.toLowerCase().replace(/[^a-z]/g, ''));
+        return lower.includes('page') || hints.some((h) => h.length > 3 && lower.includes(h));
+    })
+        .slice(0, 10);
+    const apiBlock = relevantClasses.length > 0
+        ? formatApiSurfaceForPrompt(ctx.apiSurface, relevantClasses)
+        : 'No page objects available.';
+    const existingSpecsBlock = ctx.existingSpecs.length > 0
+        ? ctx.existingSpecs.map((s) => `- ${s.relativePath}: ${s.testTitles.join(', ')}`).join('\n')
+        : 'No existing specs.';
+    const crossImpactBlock = ctx.crossImpacts.length > 0
+        ? ctx.crossImpacts.map((ci) => `- ${ci.sourceFamily} → ${ci.affectedFamily}: ${ci.sharedDependency} (${ci.riskLevel})`).join('\n')
+        : 'None detected.';
+    const categories = ctx.strategy.testCategories.join(', ');
+    return [
+        `You are a senior QA engineer designing comprehensive test cases for a ${ctx.profile?.projectName || 'project'} user flow.`,
+        '',
+        `FLOW: ${ctx.flow.flowName}`,
+        `Flow ID: ${ctx.flow.flowId}`,
+        `Route Family: ${ctx.flow.routeFamily}${ctx.flow.featureId ? ` / ${ctx.flow.featureId}` : ''}`,
+        `Route: ${ctx.flow.specificRoute || '(not specified)'}`,
+        `Priority: ${ctx.strategy.priority}`,
+        `Approach: ${ctx.strategy.approach}`,
+        `User Actions: ${sanitizeForPrompt(ctx.flow.userActions.join('; ') || 'unknown')}`,
+        `Evidence: ${sanitizeForPrompt(ctx.flow.evidence)}`,
+        '',
+        `REQUIRED TEST CATEGORIES: ${categories}`,
+        '',
+        'AVAILABLE PAGE OBJECTS:',
+        apiBlock,
+        '',
+        'EXISTING SPECS (avoid duplicating these):',
+        existingSpecsBlock,
+        '',
+        'CROSS-FAMILY IMPACTS:',
+        crossImpactBlock,
+        '',
+        'TASK: Design structured test cases for this flow.',
+        '',
+        'Return strict JSON only with this shape:',
+        '{"testDesign":{"flowId":"<id>","flowName":"<name>","testCases":[{"name":"<descriptive name>","type":"<category>","preconditions":["<state required>"],"steps":["<user action>"],"expectedOutcome":"<what should happen>","priority":"P0|P1|P2","rationale":"<why this test matters>"}]}}',
+        '',
+        'TYPE VALUES: happy-path, edge-case, boundary, negative, state-transition, race-condition, permission, accessibility, performance',
+        '',
+        'Rules:',
+        '- Every test must describe a specific USER ACTION, not an implementation detail.',
+        '- Steps must be concrete: "click Create Channel button" not "test channel creation".',
+        '- Include preconditions (logged-in role, existing data state, etc.).',
+        '- Reference only page objects and methods listed above.',
+        '- Include a mandatory rationale explaining why this specific test case matters.',
+        '- Do NOT duplicate tests already covered by existing specs.',
+        '- Maximum 15 test cases per flow.',
+        '- For accessibility: test keyboard navigation, screen reader support, ARIA labels.',
+        '- For performance: test with realistic data volumes, measure load times.',
+        '- For edge cases: test unicode input, max-length fields, empty states, concurrent edits.',
+        '',
+        'FEW-SHOT EXAMPLES:',
+        '',
+        'Edge case example:',
+        '```json',
+        '{"name":"channel creation with unicode characters and max-length name","type":"edge-case","preconditions":["logged in as team member","team has < 1000 channels"],"steps":["open create channel dialog","enter 64-character name with emoji and CJK characters","click Create"],"expectedOutcome":"channel created successfully, name renders correctly in sidebar and header","priority":"P1","rationale":"catches encoding issues in channel name storage and rendering"}',
+        '```',
+        '',
+        'Permission example:',
+        '```json',
+        '{"name":"guest user cannot archive a public channel","type":"permission","preconditions":["logged in as guest user","guest has access to public channel"],"steps":["open channel header menu","look for Archive Channel option"],"expectedOutcome":"Archive Channel option is not visible in the menu","priority":"P0","rationale":"permission escalation bug — guests archiving channels could disrupt entire teams"}',
+        '```',
+        '',
+        'Accessibility example:',
+        '```json',
+        '{"name":"keyboard navigation through channel switcher results","type":"accessibility","preconditions":["logged in","channel switcher open via Ctrl+K"],"steps":["type partial channel name","press ArrowDown to navigate results","press Enter to select"],"expectedOutcome":"focus moves visually and via aria-activedescendant, selected channel opens","priority":"P1","rationale":"screen reader users rely on keyboard navigation — broken focus management makes the app unusable"}',
+        '```',
+    ].join('\n');
+}
+export function parseTestDesignerResponse(text) {
+    return extractJsonFromResponse(text, (obj) => {
+        const r = obj;
+        return r?.testDesign?.testCases != null && Array.isArray(r.testDesign.testCases);
+    });
+}

package/dist/esm/provider_factory.js

@@ -0,0 +1,366 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+import { AnthropicProvider } from './anthropic_provider.js';
+import { logger } from './logger.js';
+import { CustomProvider } from './custom_provider.js';
+import { OllamaProvider } from './ollama_provider.js';
+import { OpenAIProvider } from './openai_provider.js';
+import { UnsupportedCapabilityError } from './provider_interface.js';
+/**
+ * LLM Provider Factory
+ *
+ * Creates and configures LLM providers based on configuration.
+ * Supports multiple strategies:
+ * - Single provider (Ollama, Anthropic, etc.)
+ * - Hybrid provider (free primary + premium fallback)
+ * - Auto-selection based on environment
+ *
+ * Usage:
+ *
+ * // Create single provider
+ * const provider = LLMProviderFactory.create({
+ *   type: 'ollama',
+ *   config: { model: 'deepseek-r1:7b' }
+ * });
+ *
+ * // Create hybrid provider
+ * const provider = LLMProviderFactory.createHybrid({
+ *   primary: { type: 'ollama', config: { model: 'deepseek-r1:7b' } },
+ *   fallback: { type: 'anthropic', config: { apiKey: '...' } },
+ *   useFallbackFor: ['vision']
+ * });
+ *
+ * // Auto-detect from environment
+ * const provider = LLMProviderFactory.createFromEnv();
+ */
+export class LLMProviderFactory {
+    /**
+     * Create a single LLM provider
+     */
+    static create(config) {
+        switch (config.type) {
+            case 'ollama':
+                return new OllamaProvider(config.config);
+            case 'anthropic':
+                return new AnthropicProvider(config.config);
+            case 'openai':
+                return new OpenAIProvider(config.config);
+            case 'custom':
+                return new CustomProvider(config.config);
+            default:
+                throw new Error(`Unknown provider type: ${config.type}`);
+        }
+    }
+    /**
+     * Create a hybrid provider (free primary + premium fallback)
+     *
+     * Use cases:
+     * - Most operations use free Ollama
+     * - Vision tasks fall back to Claude
+     * - Complex diagnosis falls back to Claude
+     *
+     * This gives best cost/quality balance:
+     * - ~$20/month instead of $80/month (75% cost reduction)
+     * - Still get premium quality for vision and complex tasks
+     */
+    static createHybrid(config) {
+        const primary = this.create(config.primary);
+        const fallback = this.create(config.fallback);
+        return new HybridProvider({
+            primary,
+            fallback,
+            useFallbackFor: config.useFallbackFor || ['vision'],
+        });
+    }
+    /**
+     * Auto-detect provider from environment variables
+     *
+     * Priority:
+     * 1. LLM_PROVIDER env var (ollama, anthropic, openai)
+     * 2. ANTHROPIC_API_KEY exists → Anthropic
+     * 3. OPENAI_API_KEY exists → OpenAI
+     * 4. Ollama running locally → Ollama
+     * 5. Error (no provider available)
+     */
+    static async createFromEnv() {
+        const providerType = process.env.LLM_PROVIDER?.toLowerCase();
+        const normalizedProviderType = providerType?.trim().toLowerCase();
+        if (normalizedProviderType && !['ollama', 'openai', 'anthropic', 'auto'].includes(normalizedProviderType)) {
+            throw new Error(`Unknown LLM_PROVIDER value "${providerType}". Expected one of: ollama, openai, anthropic, auto`);
+        }
+        if (normalizedProviderType === 'ollama') {
+            return new OllamaProvider({
+                baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434/v1',
+                model: process.env.OLLAMA_MODEL || 'deepseek-r1:7b',
+            });
+        }
+        if (normalizedProviderType === 'openai') {
+            if (!process.env.OPENAI_API_KEY) {
+                throw new Error('OPENAI_API_KEY environment variable is required for OpenAI provider');
+            }
+            return new OpenAIProvider({
+                apiKey: process.env.OPENAI_API_KEY,
+                model: process.env.OPENAI_MODEL || 'gpt-4',
+                baseUrl: process.env.OPENAI_BASE_URL,
+                organizationId: process.env.OPENAI_ORG_ID,
+            });
+        }
+        if (normalizedProviderType === 'anthropic') {
+            if (!process.env.ANTHROPIC_API_KEY) {
+                throw new Error('ANTHROPIC_API_KEY environment variable is required for Anthropic provider');
+            }
+            return new AnthropicProvider({
+                apiKey: process.env.ANTHROPIC_API_KEY,
+                model: process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-5-20250929',
+            });
+        }
+        if (process.env.ANTHROPIC_API_KEY) {
+            return new AnthropicProvider({
+                apiKey: process.env.ANTHROPIC_API_KEY,
+                model: process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-5-20250929',
+            });
+        }
+        if (process.env.OPENAI_API_KEY) {
+            return new OpenAIProvider({
+                apiKey: process.env.OPENAI_API_KEY,
+                model: process.env.OPENAI_MODEL || 'gpt-4',
+                baseUrl: process.env.OPENAI_BASE_URL,
+                organizationId: process.env.OPENAI_ORG_ID,
+            });
+        }
+        // Try Ollama as default
+        const ollama = new OllamaProvider({});
+        const health = await ollama.checkHealth();
+        if (health.healthy) {
+            logger.info('Auto-detected Ollama provider (free, local)');
+            return ollama;
+        }
+        throw new Error('No LLM provider available. Please either:\n' +
+            '1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh\n' +
+            '2. Set ANTHROPIC_API_KEY environment variable\n' +
+            '3. Set OPENAI_API_KEY environment variable\n' +
+            '4. Set LLM_PROVIDER environment variable');
+    }
+    /**
+     * Create provider from an explicit preference when supplied, otherwise
+     * fall back to environment auto-detection.
+     */
+    static async createFromPreference(providerPreference) {
+        const normalized = providerPreference?.trim().toLowerCase();
+        if (!normalized || normalized === 'auto') {
+            return this.createFromEnv();
+        }
+        return this.createFromString(normalized);
+    }
+    /**
+     * Create provider from simple string format
+     *
+     * Examples:
+     * - "ollama" → Ollama with defaults
+     * - "ollama:deepseek-r1:14b" → Ollama with specific model
+     * - "anthropic" → Anthropic with env API key
+     * - "anthropic:claude-opus-4-5" → Anthropic with specific model
+     * - "openai" → OpenAI with env API key
+     * - "openai:gpt-4" → OpenAI with specific model
+     */
+    static createFromString(providerString) {
+        const [type, ...modelParts] = providerString.split(':');
+        const model = modelParts.join(':');
+        switch (type.toLowerCase()) {
+            case 'ollama':
+                return new OllamaProvider({
+                    model: model || 'deepseek-r1:7b',
+                });
+            case 'anthropic':
+                if (!process.env.ANTHROPIC_API_KEY) {
+                    throw new Error('ANTHROPIC_API_KEY environment variable is required');
+                }
+                return new AnthropicProvider({
+                    apiKey: process.env.ANTHROPIC_API_KEY,
+                    model: model || 'claude-sonnet-4-5-20250929',
+                });
+            case 'openai':
+                if (!process.env.OPENAI_API_KEY) {
+                    throw new Error('OPENAI_API_KEY environment variable is required');
+                }
+                return new OpenAIProvider({
+                    apiKey: process.env.OPENAI_API_KEY,
+                    model: model || 'gpt-4',
+                    baseUrl: process.env.OPENAI_BASE_URL,
+                    organizationId: process.env.OPENAI_ORG_ID,
+                });
+            default:
+                throw new Error(`Unknown provider type: ${type}`);
+        }
+    }
+}
+/**
+ * Hybrid Provider - Mix free and premium providers
+ *
+ * Strategy:
+ * - Use free provider (Ollama) for most operations (~80% of requests)
+ * - Fall back to premium (Claude) only when needed (~20% of requests)
+ *
+ * Cost savings example:
+ * - Pure Claude: $80/month
+ * - Pure Ollama: $0/month but no vision
+ * - Hybrid: $20/month (75% cost reduction, keeps vision)
+ */
+class HybridProvider {
+    constructor(config) {
+        this.name = 'hybrid';
+        this.capabilities = {
+            // Report combined capabilities
+            vision: true, // Fallback provides vision
+            streaming: true, // Both support streaming
+            maxTokens: 0, // Will be set in constructor
+            costPer1MInputTokens: 0, // Variable cost
+            costPer1MOutputTokens: 0, // Variable cost
+            supportsTools: true,
+            supportsPromptCaching: false,
+            typicalResponseTimeMs: 0, // Variable
+        };
+        this.primary = config.primary;
+        this.fallback = config.fallback;
+        this.useFallbackFor = new Set(config.useFallbackFor);
+        // Set combined capabilities
+        this.capabilities.maxTokens = Math.max(this.primary.capabilities.maxTokens, this.fallback.capabilities.maxTokens);
+        this.capabilities.typicalResponseTimeMs = this.primary.capabilities.typicalResponseTimeMs;
+    }
+    async generateText(prompt, options) {
+        // Use primary for text generation (free)
+        logger.debug(`[Hybrid] Using ${this.primary.name} for text generation`);
+        return await this.primary.generateText(prompt, options);
+    }
+    async analyzeImage(images, prompt, options) {
+        // Check if vision is a fallback trigger
+        if (this.useFallbackFor.has('vision')) {
+            // Use fallback if primary doesn't support vision
+            if (!this.primary.capabilities.vision) {
+                logger.debug(`[Hybrid] Using ${this.fallback.name} for vision analysis (primary doesn't support vision)`);
+                if (!this.fallback.analyzeImage) {
+                    throw new UnsupportedCapabilityError(this.name, 'vision');
+                }
+                return await this.fallback.analyzeImage(images, prompt, options);
+            }
+        }
+        // Try primary first
+        if (this.primary.analyzeImage) {
+            logger.debug(`[Hybrid] Using ${this.primary.name} for vision analysis`);
+            return await this.primary.analyzeImage(images, prompt, options);
+        }
+        throw new UnsupportedCapabilityError(this.name, 'vision');
+    }
+    async *streamText(prompt, options) {
+        // Use primary for streaming (free)
+        if (!this.primary.streamText) {
+            throw new UnsupportedCapabilityError(this.primary.name, 'streaming');
+        }
+        logger.debug(`[Hybrid] Using ${this.primary.name} for streaming`);
+        yield* this.primary.streamText(prompt, options);
+    }
+    getUsageStats() {
+        const primaryStats = this.primary.getUsageStats();
+        const fallbackStats = this.fallback.getUsageStats();
+        // Combine stats
+        const totalRequests = primaryStats.requestCount + fallbackStats.requestCount;
+        return {
+            requestCount: totalRequests,
+            totalInputTokens: primaryStats.totalInputTokens + fallbackStats.totalInputTokens,
+            totalOutputTokens: primaryStats.totalOutputTokens + fallbackStats.totalOutputTokens,
+            totalTokens: primaryStats.totalTokens + fallbackStats.totalTokens,
+            totalCost: primaryStats.totalCost + fallbackStats.totalCost,
+            averageResponseTimeMs: totalRequests > 0
+                ? (primaryStats.averageResponseTimeMs * primaryStats.requestCount +
+                    fallbackStats.averageResponseTimeMs * fallbackStats.requestCount) / totalRequests
+                : 0,
+            failedRequests: primaryStats.failedRequests + fallbackStats.failedRequests,
+            startTime: new Date(Math.min(primaryStats.startTime.getTime(), fallbackStats.startTime.getTime())),
+            lastUpdated: new Date(Math.max(primaryStats.lastUpdated.getTime(), fallbackStats.lastUpdated.getTime())),
+        };
+    }
+    resetUsageStats() {
+        this.primary.resetUsageStats();
+        this.fallback.resetUsageStats();
+    }
+    async checkHealth() {
+        const primaryHealth = await this.primary.checkHealth();
+        if (primaryHealth.healthy) {
+            return { healthy: true, message: `${this.primary.name}: ${primaryHealth.message}` };
+        }
+        const fallbackHealth = await this.fallback.checkHealth();
+        if (fallbackHealth.healthy) {
+            return {
+                healthy: true,
+                message: `${this.primary.name} unhealthy (${primaryHealth.message}); fallback ${this.fallback.name}: ${fallbackHealth.message}`,
+            };
+        }
+        return {
+            healthy: false,
+            message: `${this.primary.name} unhealthy (${primaryHealth.message}); fallback ${this.fallback.name} unhealthy (${fallbackHealth.message})`,
+        };
+    }
+    /**
+     * Get breakdown of which provider was used for what
+     */
+    getProviderBreakdown() {
+        const primaryStats = this.primary.getUsageStats();
+        const fallbackStats = this.fallback.getUsageStats();
+        // Calculate what it would cost if we used only fallback
+        const totalRequests = primaryStats.requestCount + fallbackStats.requestCount;
+        const fallbackCostPerRequest = fallbackStats.requestCount > 0 ? fallbackStats.totalCost / fallbackStats.requestCount : 0;
+        const hypotheticalFullCost = totalRequests * fallbackCostPerRequest;
+        const actualCost = primaryStats.totalCost + fallbackStats.totalCost;
+        const savings = hypotheticalFullCost - actualCost;
+        const savingsPercent = hypotheticalFullCost > 0 ? (savings / hypotheticalFullCost) * 100 : 0;
+        return {
+            primary: {
+                name: this.primary.name,
+                stats: primaryStats,
+            },
+            fallback: {
+                name: this.fallback.name,
+                stats: fallbackStats,
+            },
+            costSavings: `$${savings.toFixed(2)} saved (${savingsPercent.toFixed(1)}% reduction)`,
+        };
+    }
+}
+/**
+ * Helper to validate provider setup
+ */
+export async function validateProviderSetup(provider) {
+    const capabilities = [];
+    if (provider.capabilities.vision) {
+        capabilities.push('✓ Vision support (screenshot comparison)');
+    }
+    else {
+        capabilities.push('✗ No vision support');
+    }
+    if (provider.capabilities.streaming) {
+        capabilities.push('✓ Streaming responses');
+    }
+    if (provider.capabilities.supportsTools) {
+        capabilities.push('✓ Function calling');
+    }
+    capabilities.push(`✓ ${provider.capabilities.maxTokens.toLocaleString()} token context window`);
+    capabilities.push(`✓ Cost: $${provider.capabilities.costPer1MOutputTokens}/1M tokens`);
+    try {
+        // Try a simple request
+        const response = await provider.generateText('Say "OK" if you can read this', {
+            maxTokens: 10,
+        });
+        return {
+            valid: response.text.length > 0,
+            message: `Provider '${provider.name}' is working correctly`,
+            capabilities,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            message: `Provider '${provider.name}' validation failed: ${error instanceof Error ? error.message : String(error)}`,
+            capabilities,
+        };
+    }
+}

package/dist/esm/provider_interface.js

@@ -0,0 +1,23 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * Error thrown by LLM providers
+ */
+export class LLMProviderError extends Error {
+    constructor(message, provider, statusCode, cause) {
+        super(message);
+        this.provider = provider;
+        this.statusCode = statusCode;
+        this.cause = cause;
+        this.name = 'LLMProviderError';
+    }
+}
+/**
+ * Error thrown when a required capability is not supported
+ */
+export class UnsupportedCapabilityError extends LLMProviderError {
+    constructor(provider, capability) {
+        super(`Provider '${provider}' does not support capability: ${capability}`, provider);
+        this.name = 'UnsupportedCapabilityError';
+    }
+}

package/dist/esm/provider_utils.js

@@ -0,0 +1,96 @@
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+/**
+ * SECURITY: Shared utility functions for all LLM providers
+ * Eliminates code duplication and ensures consistent error handling
+ */
+/**
+ * Pre-compiled regex patterns for API key validation
+ * Compiled once and reused to avoid repeated regex compilation
+ */
+export const API_KEY_PATTERNS = {
+    anthropic: /^sk-ant-[a-zA-Z0-9_\-]{20,}$/,
+    openai: /^sk-[a-zA-Z0-9_\-]{20,}$/,
+};
+/**
+ * SECURITY: Sanitize error messages to prevent information leakage
+ * Maps specific API errors to safe, user-friendly messages
+ * Prevents leaking stack traces, API keys, or internal details
+ */
+export function sanitizeErrorMessage(error, context) {
+    if (error instanceof Error) {
+        const msg = error.message.toLowerCase();
+        // Map specific API errors to safe messages
+        if (msg.includes('401') || msg.includes('authentication')) {
+            return `Authentication failed (${context})`;
+        }
+        if (msg.includes('429') || msg.includes('rate')) {
+            return `Rate limit exceeded (${context})`;
+        }
+        if (msg.includes('timeout') || msg.includes('etimedout')) {
+            return `Request timeout (${context})`;
+        }
+        if (msg.includes('network') || msg.includes('econnrefused')) {
+            return `Connection failed (${context})`;
+        }
+        if (msg.includes('enotfound') || msg.includes('getaddrinfo')) {
+            return `Host not found (${context})`;
+        }
+        // Don't leak stack traces, API keys, or internal details
+        return `Operation failed (${context})`;
+    }
+    return 'An unexpected error occurred';
+}
+/**
+ * Generic timeout wrapper for promises
+ * Rejects with timeout error if promise doesn't resolve in time
+ */
+export function withTimeout(promise, timeoutMs, context) {
+    if (!timeoutMs) {
+        return promise;
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Request timeout (${context})`)), timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+/**
+ * Check if a hostname is localhost
+ * Used by URL validation to allow HTTP for local development
+ */
+export function isLocalhost(hostname) {
+    if (!hostname) {
+        return false;
+    }
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+}
+/**
+ * SECURITY: Validate and enforce HTTPS for remote URLs
+ * Allows HTTP only for localhost development
+ * Returns validation result with optional warning message
+ */
+export function validateAndSanitizeUrl(baseUrl) {
+    if (!baseUrl) {
+        return { valid: true };
+    }
+    try {
+        const url = new URL(baseUrl);
+        // For non-localhost URLs, require HTTPS
+        if (!isLocalhost(url.hostname) && url.protocol !== 'https:') {
+            return {
+                valid: false,
+                warning: `HTTPS required for remote URLs. Got: ${url.protocol}//${url.hostname}`,
+            };
+        }
+        return { valid: true, url: baseUrl };
+    }
+    catch {
+        return { valid: false };
+    }
+}