@yasserkhanorg/e2e-agents 0.3.2

package/dist/provider_interface.d.ts

@@ -0,0 +1,358 @@
+/**
+ * LLM Provider Interface - Core abstraction for pluggable AI models
+ *
+ * Enables the autonomous testing system to work with any LLM:
+ * - Ollama (free, local)
+ * - Anthropic Claude (premium, vision support)
+ * - OpenAI (premium)
+ * - Custom providers (any OpenAI-compatible API)
+ *
+ * Design Philosophy:
+ * - Provider-agnostic: Switch LLMs without changing test logic
+ * - Capability-aware: System adapts based on provider features
+ * - Cost-conscious: Track token usage and costs
+ * - Hybrid-friendly: Mix free and premium providers
+ */
+/**
+ * Core LLM provider interface - all providers must implement this
+ */
+export interface LLMProvider {
+    /**
+     * Unique identifier for this provider
+     * Examples: 'anthropic', 'ollama', 'openai', 'custom'
+     */
+    name: string;
+    /**
+     * Generate text from a prompt
+     * Primary method for most LLM operations
+     */
+    generateText(prompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    /**
+     * Analyze images with vision models (optional - not all providers support)
+     * Used for spec screenshot comparison and visual bug detection
+     */
+    analyzeImage?(images: ImageInput[], prompt: string, options?: GenerateOptions): Promise<LLMResponse>;
+    /**
+     * Stream text generation (optional - for real-time UI feedback)
+     * Yields text chunks as they're generated
+     */
+    streamText?(prompt: string, options?: GenerateOptions): AsyncGenerator<string, void, unknown>;
+    /**
+     * Provider capabilities - what this LLM can do
+     */
+    capabilities: ProviderCapabilities;
+    /**
+     * Get usage statistics for cost tracking and monitoring
+     */
+    getUsageStats(): ProviderUsageStats;
+    /**
+     * Reset usage statistics (typically called at start of new cycle)
+     */
+    resetUsageStats(): void;
+}
+/**
+ * Options for text generation
+ */
+export interface GenerateOptions {
+    /**
+     * Maximum tokens to generate in response
+     * Helps control costs and response length
+     */
+    maxTokens?: number;
+    /**
+     * Temperature (0.0 - 1.0)
+     * Lower = more focused/deterministic, Higher = more creative/random
+     */
+    temperature?: number;
+    /**
+     * System prompt to set context/behavior
+     */
+    systemPrompt?: string;
+    /**
+     * Stop sequences - generation stops when these are encountered
+     */
+    stopSequences?: string[];
+    /**
+     * Top-p sampling (0.0 - 1.0)
+     * Alternative to temperature for controlling randomness
+     */
+    topP?: number;
+    /**
+     * Timeout for request in milliseconds
+     */
+    timeout?: number;
+}
+/**
+ * Image input for vision analysis
+ * Also supports PDF documents for specification parsing
+ */
+export interface ImageInput {
+    /**
+     * Base64-encoded image or document data
+     */
+    data?: string;
+    base64?: string;
+    /**
+     * Media type (e.g., 'image/png', 'image/jpeg', 'application/pdf')
+     */
+    mimeType?: 'image/png' | 'image/jpeg' | 'image/webp' | 'application/pdf';
+    mediaType?: 'image/png' | 'image/jpeg' | 'image/webp';
+    /**
+     * Optional description of what the image shows
+     */
+    description?: string;
+}
+/**
+ * Response from LLM generation
+ */
+export interface LLMResponse {
+    /**
+     * Generated text content
+     */
+    text: string;
+    /**
+     * Token usage for this request
+     */
+    usage: TokenUsage;
+    /**
+     * Calculated cost in USD
+     */
+    cost: number;
+    /**
+     * Optional confidence score (0.0 - 1.0) if provider supports it
+     */
+    confidence?: number;
+    /**
+     * Raw response metadata from provider (for debugging)
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Token usage information
+ */
+export interface TokenUsage {
+    /**
+     * Tokens in the prompt/input
+     */
+    inputTokens: number;
+    /**
+     * Tokens in the generated output
+     */
+    outputTokens: number;
+    /**
+     * Total tokens (input + output)
+     */
+    totalTokens: number;
+    /**
+     * Cached tokens (if provider supports caching)
+     */
+    cachedTokens?: number;
+}
+/**
+ * Provider capabilities - what features this LLM supports
+ */
+export interface ProviderCapabilities {
+    /**
+     * Supports image analysis (vision models)
+     */
+    vision: boolean;
+    /**
+     * Supports streaming responses
+     */
+    streaming: boolean;
+    /**
+     * Maximum context window in tokens
+     */
+    maxTokens: number;
+    /**
+     * Cost per 1 million input tokens (USD)
+     */
+    costPer1MInputTokens: number;
+    /**
+     * Cost per 1 million output tokens (USD)
+     */
+    costPer1MOutputTokens: number;
+    /**
+     * Supports function/tool calling
+     */
+    supportsTools: boolean;
+    /**
+     * Supports prompt caching to reduce costs
+     */
+    supportsPromptCaching: boolean;
+    /**
+     * Typical response time in milliseconds
+     */
+    typicalResponseTimeMs: number;
+}
+/**
+ * Cumulative usage statistics for a provider
+ */
+export interface ProviderUsageStats {
+    /**
+     * Total number of requests made
+     */
+    requestCount: number;
+    /**
+     * Total input tokens used
+     */
+    totalInputTokens: number;
+    /**
+     * Total output tokens generated
+     */
+    totalOutputTokens: number;
+    /**
+     * Total tokens (input + output)
+     */
+    totalTokens: number;
+    /**
+     * Total cost in USD
+     */
+    totalCost: number;
+    /**
+     * Average response time in milliseconds
+     */
+    averageResponseTimeMs: number;
+    /**
+     * Number of failed requests
+     */
+    failedRequests: number;
+    /**
+     * When stats tracking started
+     */
+    startTime: Date;
+    /**
+     * When stats were last updated
+     */
+    lastUpdated: Date;
+}
+/**
+ * Configuration for creating a provider
+ */
+export interface ProviderConfig {
+    /**
+     * Provider type
+     */
+    type: 'anthropic' | 'ollama' | 'openai' | 'custom';
+    /**
+     * Provider-specific configuration
+     */
+    config: AnthropicConfig | OllamaConfig | OpenAIConfig | CustomConfig;
+}
+/**
+ * Anthropic (Claude) provider configuration
+ */
+export interface AnthropicConfig {
+    /**
+     * Anthropic API key
+     */
+    apiKey: string;
+    /**
+     * Model to use (default: claude-sonnet-4-5-20250929)
+     */
+    model?: string;
+    /**
+     * API base URL (for testing/proxies)
+     */
+    baseUrl?: string;
+    /**
+     * Default max tokens for requests
+     */
+    defaultMaxTokens?: number;
+}
+/**
+ * Ollama (local/free) provider configuration
+ */
+export interface OllamaConfig {
+    /**
+     * Ollama API base URL (default: http://localhost:11434, normalized to /v1)
+     */
+    baseUrl?: string;
+    /**
+     * Model to use (default: deepseek-r1:7b)
+     * Other options: llama4:13b, deepseek-r1:14b
+     */
+    model?: string;
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+}
+/**
+ * OpenAI provider configuration
+ */
+export interface OpenAIConfig {
+    /**
+     * OpenAI API key
+     */
+    apiKey: string;
+    /**
+     * Model to use (default: gpt-4)
+     */
+    model?: string;
+    /**
+     * API base URL (for custom endpoints)
+     */
+    baseUrl?: string;
+    /**
+     * Organization ID (optional)
+     */
+    organizationId?: string;
+    /**
+     * Optional max context window in tokens (for capability reporting)
+     */
+    maxTokens?: number;
+    /**
+     * Optional cost per 1M input tokens (for cost tracking)
+     */
+    costPer1MInputTokens?: number;
+    /**
+     * Optional cost per 1M output tokens (for cost tracking)
+     */
+    costPer1MOutputTokens?: number;
+}
+/**
+ * Custom provider configuration
+ */
+export interface CustomConfig {
+    /**
+     * API endpoint URL
+     */
+    baseUrl: string;
+    /**
+     * Authentication headers
+     */
+    auth: Record<string, string>;
+    /**
+     * Model identifier
+     */
+    model: string;
+    /**
+     * Request format ('openai' | 'anthropic' | 'custom')
+     */
+    requestFormat: 'openai' | 'anthropic' | 'custom';
+    /**
+     * Custom request transformer (if format is 'custom')
+     */
+    transformRequest?: (prompt: string, options?: GenerateOptions) => unknown;
+    /**
+     * Custom response transformer (if format is 'custom')
+     */
+    transformResponse?: (response: unknown) => LLMResponse;
+}
+/**
+ * Error thrown by LLM providers
+ */
+export declare class LLMProviderError extends Error {
+    readonly provider: string;
+    readonly statusCode?: number | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, provider: string, statusCode?: number | undefined, cause?: unknown | undefined);
+}
+/**
+ * Error thrown when a required capability is not supported
+ */
+export declare class UnsupportedCapabilityError extends LLMProviderError {
+    constructor(provider: string, capability: string);
+}
+//# sourceMappingURL=provider_interface.d.ts.map

package/dist/provider_interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider_interface.d.ts","sourceRoot":"","sources":["../src/provider_interface.ts"],"names":[],"mappings":"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"}

package/dist/provider_interface.js

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

package/dist/provider_utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const API_KEY_PATTERNS: {
+    anthropic: RegExp;
+    openai: RegExp;
+};
+/**
+ * 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 declare function sanitizeErrorMessage(error: unknown, context: string): string;
+/**
+ * Generic timeout wrapper for promises
+ * Rejects with timeout error if promise doesn't resolve in time
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number | undefined, context: string): Promise<T>;
+/**
+ * Check if a hostname is localhost
+ * Used by URL validation to allow HTTP for local development
+ */
+export declare function isLocalhost(hostname: string | undefined): boolean;
+/**
+ * SECURITY: Validate and enforce HTTPS for remote URLs
+ * Allows HTTP only for localhost development
+ * Returns validation result with optional warning message
+ */
+export declare function validateAndSanitizeUrl(baseUrl: string | undefined): {
+    valid: boolean;
+    url?: string;
+    warning?: string;
+};
+//# sourceMappingURL=provider_utils.d.ts.map

package/dist/provider_utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider_utils.d.ts","sourceRoot":"","sources":["../src/provider_utils.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;CAG5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAyB5E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAkBZ;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAKjE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAClC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC5B;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAoBlD"}

package/dist/provider_utils.js

@@ -0,0 +1,103 @@
+"use strict";
+// Copyright (c) 2015-present Mattermost, Inc. All Rights Reserved.
+// See LICENSE.txt for license information.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API_KEY_PATTERNS = void 0;
+exports.sanitizeErrorMessage = sanitizeErrorMessage;
+exports.withTimeout = withTimeout;
+exports.isLocalhost = isLocalhost;
+exports.validateAndSanitizeUrl = validateAndSanitizeUrl;
+/**
+ * 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
+ */
+exports.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
+ */
+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
+ */
+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
+ */
+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
+ */
+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 };
+    }
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@yasserkhanorg/e2e-agents",
+  "version": "0.3.2",
+  "description": "Pluggable LLM provider library for AI-powered test automation. Use Claude, Ollama, or your own LLM. Integrate with Playwright, Jest, or any test framework. MCP server for test agents, cost tracking, and hybrid provider mode.",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/esm/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp-server.d.ts",
+      "require": "./dist/mcp-server.js",
+      "import": "./dist/esm/mcp-server.js"
+    },
+    "./schemas/impact": "./schemas/impact.schema.json",
+    "./schemas/gap": "./schemas/gap.schema.json",
+    "./schemas/plan": "./schemas/plan.schema.json",
+    "./schemas/traceability-input": "./schemas/traceability-input.schema.json",
+    "./schemas/subsystem-risk-map": "./schemas/subsystem-risk-map.schema.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "e2e-ai-agents": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc -p tsconfig.json",
+    "build:esm": "tsc -p tsconfig.esm.json && node scripts/write-esm-package.js",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "pretest": "npm run build",
+    "test": "node --test test/*.js",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "mcp:server": "node dist/mcp-server.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.73.0",
+    "glob": "^11.0.0",
+    "marked": "^15.0.6",
+    "openai": "^4.73.0",
+    "pdf-parse": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pdf-parse": "^1.1.4",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yasserfaraazkhan/e2e-agents.git"
+  },
+  "keywords": [
+    "llm",
+    "ai",
+    "testing",
+    "test-automation",
+    "e2e",
+    "playwright",
+    "jest",
+    "mocha",
+    "cypress",
+    "anthropic",
+    "claude",
+    "ollama",
+    "openai",
+    "mcp",
+    "model-context-protocol",
+    "test-agents",
+    "ai-testing",
+    "autonomous-testing",
+    "test-generation",
+    "ai-agents",
+    "provider-abstraction",
+    "framework-agnostic",
+    "cost-tracking",
+    "hybrid-mode",
+    "vision-analysis",
+    "screenshot-analysis",
+    "test-discovery",
+    "test-healing"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "Yasser Khan",
+  "homepage": "https://github.com/yasserfaraazkhan/e2e-agents",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/gap.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mattermost.com/schemas/e2e-agents/gap.schema.json",
+  "title": "GapReport",
+  "allOf": [
+    {
+      "$ref": "./impact.schema.json"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "mode": {
+          "const": "gap"
+        }
+      }
+    }
+  ]
+}