@rulecatch/ai-pooler 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,625 @@
+/**
+ * Rulecatch AI - MCP Development Analytics Types
+ *
+ * Event types and interfaces for tracking AI-assisted development metrics.
+ */
+/**
+ * Types of events tracked by Rulecatch AI
+ */
+type AIEventType = 'ai_request' | 'ai_response' | 'tool_call' | 'tool_result' | 'code_accept' | 'code_reject' | 'code_modify' | 'session_start' | 'session_end' | 'session_pause' | 'session_resume' | 'conversation_turn' | 'file_operation' | 'rule_deviation' | 'error';
+/**
+ * Categories of rule violations that can be tracked
+ */
+type RuleViolationCategory = 'coding_standard' | 'db_pattern' | 'security' | 'performance' | 'architecture' | 'documentation' | 'testing' | 'custom';
+/**
+ * Severity levels for rule violations
+ */
+type RuleViolationSeverity = 'info' | 'warning' | 'error';
+/**
+ * Supported AI models for cost calculation
+ * Updated January 2026
+ */
+type AIModel = 'claude-opus-4-5' | 'claude-sonnet-4' | 'claude-3.5-sonnet' | 'claude-3.5-haiku' | 'claude-3-opus' | 'claude-3-sonnet' | 'claude-3-haiku' | 'gpt-4' | 'gpt-4-turbo' | 'gpt-4o' | 'gpt-4o-mini' | 'o1' | 'o1-mini' | 'o1-pro' | 'gemini-2.0-flash' | 'gemini-1.5-pro' | 'gemini-1.5-flash' | 'unknown';
+/**
+ * Base event interface for all AI development events
+ */
+interface AIDevEvent {
+    /** Event type identifier */
+    type: AIEventType;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Unique session identifier */
+    sessionId: string;
+    /** Project identifier (from license) */
+    projectId: string;
+    /** Input tokens consumed */
+    inputTokens?: number;
+    /** Output tokens generated */
+    outputTokens?: number;
+    /** Cache read tokens (prompt caching) */
+    cacheReadTokens?: number;
+    /** Cache write tokens (prompt caching) */
+    cacheWriteTokens?: number;
+    /** Thinking tokens (extended thinking) */
+    thinkingTokens?: number;
+    /** Prompt character length */
+    promptLength?: number;
+    /** Response character length */
+    responseLength?: number;
+    /** Context window usage (0-1) */
+    contextUsage?: number;
+    /** Time to first token in ms */
+    timeToFirstToken?: number;
+    /** Total response time in ms */
+    totalResponseTime?: number;
+    /** Active coding time in ms (excludes idle) */
+    activeTime?: number;
+    /** Request latency in ms */
+    latency?: number;
+    /** AI model used */
+    model?: AIModel | string;
+    /** Estimated cost in USD */
+    estimatedCost?: number;
+    /** Was prompt cached */
+    promptCached?: boolean;
+    /** MCP tool name (for tool events) */
+    toolName?: string;
+    /** Whether the tool call succeeded */
+    toolSuccess?: boolean;
+    /** Tool execution duration in ms */
+    toolDuration?: number;
+    /** Tool input size (for Bash commands, file content, etc.) */
+    toolInputSize?: number;
+    /** Tool output size */
+    toolOutputSize?: number;
+    /** Lines of code added */
+    linesAdded?: number;
+    /** Lines of code removed */
+    linesRemoved?: number;
+    /** Files modified in this event */
+    filesModified?: string[];
+    /** Programming language */
+    language?: string;
+    /** Framework or library context */
+    framework?: string;
+    /** File operation type */
+    fileOperation?: 'read' | 'write' | 'edit' | 'delete' | 'create';
+    /** Conversation turn number */
+    turnNumber?: number;
+    /** Whether user intervened/modified */
+    userIntervention?: boolean;
+    /** Task/feature being worked on */
+    taskContext?: string;
+    /** Error message if event is an error */
+    errorMessage?: string;
+    /** Error was recovered from */
+    errorRecovered?: boolean;
+    /** Retry attempt number */
+    retryAttempt?: number;
+    /** Rule that was deviated from (for rule_deviation events) */
+    ruleName?: string;
+    /** Source of the rule (e.g., "CLAUDE.md", "eslint", "project-standards") */
+    ruleSource?: string;
+    /** Category of the rule violation */
+    ruleCategory?: RuleViolationCategory;
+    /** Severity of the violation */
+    ruleSeverity?: RuleViolationSeverity;
+    /** Description of what rule was violated (rule violation) */
+    ruleDescription?: string;
+    /** The problematic code or pattern that violated the rule */
+    violatingCode?: string;
+    /** Suggested fix or correct pattern */
+    suggestedFix?: string;
+    /** File where the violation occurred */
+    violationFile?: string;
+    /** Line number(s) where violation occurred */
+    violationLine?: number;
+    /** Whether the violation was auto-corrected */
+    corrected?: boolean;
+    /** Confidence score that this is actually a violation (0-1) */
+    violationConfidence?: number;
+    /** Git username */
+    gitUsername?: string;
+    /** Git email */
+    gitEmail?: string;
+    /** Repository name (e.g., "user/repo") */
+    gitRepo?: string;
+    /** Current branch */
+    gitBranch?: string;
+    /** Current commit (short hash) */
+    gitCommit?: string;
+    /** Whether there are uncommitted changes */
+    gitDirty?: boolean;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Session metrics aggregated from events
+ */
+interface SessionMetrics {
+    /** Session identifier */
+    sessionId: string;
+    /** Session start time */
+    startTime: string;
+    /** Session end time (if ended) */
+    endTime?: string;
+    /** Total elapsed duration in seconds */
+    duration: number;
+    /** Active coding time in seconds (excludes idle) */
+    activeDuration: number;
+    /** Total input tokens */
+    totalInputTokens: number;
+    /** Total output tokens */
+    totalOutputTokens: number;
+    /** Total thinking tokens */
+    totalThinkingTokens: number;
+    /** Total cache read tokens */
+    totalCacheReadTokens: number;
+    /** Cache hit rate (0-1) */
+    cacheHitRate: number;
+    /** Average context usage (0-1) */
+    avgContextUsage: number;
+    /** Total estimated cost in USD */
+    totalCost: number;
+    /** Cost breakdown by file */
+    costByFile: Record<string, number>;
+    /** Cost breakdown by language */
+    costByLanguage: Record<string, number>;
+    /** Number of AI requests */
+    requestCount: number;
+    /** Number of conversation turns */
+    conversationTurns: number;
+    /** Average response time in ms */
+    avgResponseTime: number;
+    /** Average time to first token in ms */
+    avgTimeToFirstToken: number;
+    /** Number of tool calls */
+    toolCallCount: number;
+    /** Tool success rate (0-1) */
+    toolSuccessRate: number;
+    /** Tool calls by name */
+    toolCallsByName: Record<string, number>;
+    /** Tool failures by name */
+    toolFailuresByName: Record<string, number>;
+    /** Lines of code added */
+    totalLinesAdded: number;
+    /** Lines of code removed */
+    totalLinesRemoved: number;
+    /** Net lines changed */
+    netLinesChanged: number;
+    /** Unique files modified */
+    uniqueFilesModified: number;
+    /** Files with most changes */
+    topModifiedFiles: Array<{
+        file: string;
+        changes: number;
+    }>;
+    /** Code acceptance rate (0-1) */
+    codeAcceptanceRate: number;
+    /** User intervention rate (0-1) */
+    userInterventionRate: number;
+    /** Most used model */
+    primaryModel: string;
+    /** Models used with request counts */
+    modelUsage: Record<string, number>;
+    /** Languages used */
+    languages: string[];
+    /** Tokens per minute */
+    tokensPerMinute: number;
+    /** Lines per hour */
+    linesPerHour: number;
+    /** Cost per line of code */
+    costPerLine: number;
+    /** Errors encountered */
+    errorCount: number;
+    /** Error recovery rate */
+    errorRecoveryRate: number;
+    /** Total rule violations detected */
+    totalRuleViolations: number;
+    /** Rule violations by category */
+    violationsByCategory: Record<RuleViolationCategory, number>;
+    /** Rule violations by severity */
+    violationsBySeverity: Record<RuleViolationSeverity, number>;
+    /** Rule violations by source (CLAUDE.md, eslint, etc.) */
+    violationsBySource: Record<string, number>;
+    /** Most common rule violations */
+    topRuleViolations: Array<{
+        rule: string;
+        count: number;
+        severity: RuleViolationSeverity;
+    }>;
+    /** Percentage of violations that were auto-corrected */
+    violationCorrectionRate: number;
+    /** Files with most violations */
+    filesWithMostViolations: Array<{
+        file: string;
+        count: number;
+    }>;
+}
+/**
+ * Git context information collected automatically
+ */
+interface GitContext {
+    /** Git username (from git config user.name) */
+    username?: string;
+    /** Git email (from git config user.email) */
+    email?: string;
+    /** Remote repository URL */
+    repoUrl?: string;
+    /** Repository name (extracted from URL) */
+    repoName?: string;
+    /** Current branch name */
+    branch?: string;
+    /** Current commit hash (short) */
+    commit?: string;
+    /** Full commit hash */
+    commitFull?: string;
+    /** Commit message (first line) */
+    commitMessage?: string;
+    /** Commit author */
+    commitAuthor?: string;
+    /** Commit timestamp */
+    commitTimestamp?: string;
+    /** Whether there are uncommitted changes */
+    isDirty?: boolean;
+    /** Number of uncommitted files */
+    uncommittedFiles?: number;
+    /** Root directory of the git repository */
+    rootDir?: string;
+}
+/**
+ * Configuration for the MCP server
+ */
+interface MCPConfig {
+    /** Rulecatch AI license key */
+    licenseKey?: string;
+    /** Project identifier */
+    projectId: string;
+    /** Rulecatch API endpoint */
+    endpoint?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Batch events before sending */
+    batchSize?: number;
+    /** Flush interval in ms */
+    flushInterval?: number;
+    /** Include file paths in events */
+    includeFilePaths?: boolean;
+    /** Languages to track (empty = all) */
+    trackLanguages?: string[];
+    /** Track active time (requires more events) */
+    trackActiveTime?: boolean;
+    /** Idle timeout in ms (default: 5 minutes) */
+    idleTimeout?: number;
+    /** Automatically collect and send git context */
+    trackGitContext?: boolean;
+    /** Working directory for git context collection */
+    cwd?: string;
+    /** Project version (semver) for version correlation */
+    version?: string;
+    /** Git commit hash for version correlation */
+    commit?: string;
+}
+/**
+ * Model pricing per 1M tokens
+ * Updated January 2026
+ */
+interface ModelPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+    cacheReadPer1M?: number;
+    cacheWritePer1M?: number;
+    thinkingPer1M?: number;
+}
+/**
+ * Pricing table for cost calculation
+ * Source: Official pricing pages as of January 2026
+ */
+declare const MODEL_PRICING: Record<AIModel, ModelPricing>;
+/**
+ * Calculate cost from token usage with caching support
+ */
+declare function calculateCost(model: AIModel | string, inputTokens: number, outputTokens: number, options?: {
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    thinkingTokens?: number;
+}): number;
+/**
+ * Estimate tokens from character count
+ * Rough approximation: ~4 chars per token for English
+ */
+declare function estimateTokens(charCount: number): number;
+/**
+ * Format duration in human-readable form
+ */
+declare function formatDuration(seconds: number): string;
+/**
+ * Format cost in USD
+ */
+declare function formatCost(cost: number): string;
+
+/**
+ * Client-side encryption for PII (Zero-Knowledge Architecture)
+ *
+ * All PII (emails, usernames, file paths) is encrypted on the client
+ * before being sent to Rulecatch API. We never see plaintext PII.
+ *
+ * The user's privacy key is derived from their password or a separate
+ * key they set during setup. Without this key, the data is unreadable.
+ */
+interface EncryptedField {
+    /** Base64-encoded ciphertext */
+    ciphertext: string;
+    /** Base64-encoded initialization vector */
+    iv: string;
+    /** Base64-encoded authentication tag (GCM) */
+    tag: string;
+}
+interface PrivacyConfig {
+    /** User's privacy key (password-derived or standalone) */
+    privacyKey: string;
+    /** Salt for key derivation (stored with user account, not secret) */
+    salt: string;
+}
+/**
+ * Derive an encryption key from a password/passphrase
+ * Uses PBKDF2 with 100k iterations for brute-force resistance
+ */
+declare function deriveKey(password: string, salt: string): Buffer;
+/**
+ * Generate a random salt for new users
+ */
+declare function generateSalt(): string;
+/**
+ * Encrypt a PII field (email, username, file path, etc.)
+ * Returns ciphertext + IV + auth tag for storage
+ */
+declare function encryptPII(plaintext: string, key: Buffer): EncryptedField;
+/**
+ * Decrypt a PII field
+ * Used client-side in the dashboard to show actual values
+ */
+declare function decryptPII(encrypted: EncryptedField, key: Buffer): string;
+/**
+ * Create a one-way hash for indexing/grouping
+ * Cannot be reversed, but same input = same hash (for deduplication)
+ *
+ * We use a truncated hash (16 chars) to prevent rainbow table attacks
+ * while still allowing grouping by the same identifier.
+ */
+declare function hashForIndex(plaintext: string, salt: string): string;
+/**
+ * Encrypt all PII fields in an event payload
+ * Non-PII fields are passed through unchanged
+ */
+declare function encryptEventPII(event: Record<string, unknown>, key: Buffer, salt: string): Record<string, unknown>;
+/**
+ * Decrypt all PII fields in an event payload
+ * Used in the dashboard to display actual values
+ */
+declare function decryptEventPII(event: Record<string, unknown>, key: Buffer): Record<string, unknown>;
+/**
+ * Verify a privacy key is correct by attempting to decrypt a test value
+ */
+declare function verifyPrivacyKey(testCiphertext: EncryptedField, expectedPlaintext: string, key: Buffer): boolean;
+
+/**
+ * Git Context Collection
+ *
+ * Automatically collects git information from the current repository.
+ * This provides context about the development environment to track
+ * which project/branch/commit is being worked on.
+ */
+
+/**
+ * Check if we're in a git repository
+ */
+declare function isGitRepo(cwd?: string): boolean;
+/**
+ * Get the root directory of the git repository
+ */
+declare function getGitRoot(cwd?: string): string | null;
+/**
+ * Collect git context from the current directory
+ */
+declare function collectGitContext(cwd?: string): GitContext;
+/**
+ * Watch for git changes (branch switches, commits, etc.)
+ * Returns a cleanup function to stop watching
+ */
+declare function watchGitChanges(callback: (context: GitContext) => void, options?: {
+    cwd?: string;
+    pollInterval?: number;
+}): () => void;
+/**
+ * Get a summary string for the current git context
+ */
+declare function getGitSummary(context: GitContext): string;
+
+/**
+ * @rulecatch/ai-pooler - AI Development Analytics Pooler
+ *
+ * Production-grade tracking for AI-assisted development including:
+ * - Token usage with prompt caching and thinking tokens
+ * - Active time tracking (coding vs idle)
+ * - Per-file and per-language cost breakdown
+ * - Conversation turns and user interventions
+ * - Response latency metrics
+ */
+
+/**
+ * Initialize the Rulecatch AI MCP server
+ */
+declare function init(options: MCPConfig): void;
+/**
+ * Start a new development session
+ */
+declare function startSession(): string;
+/**
+ * End the current session
+ */
+declare function endSession(): SessionMetrics | null;
+/**
+ * Track an AI request/response with full metrics
+ */
+declare function trackAIRequest(params: {
+    model: AIModel | string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    thinkingTokens?: number;
+    promptLength?: number;
+    responseLength?: number;
+    contextUsage?: number;
+    timeToFirstToken?: number;
+    totalResponseTime?: number;
+    filesContext?: string[];
+    language?: string;
+    taskContext?: string;
+    metadata?: Record<string, unknown>;
+}): void;
+/**
+ * Track a conversation turn (user message + AI response cycle)
+ */
+declare function trackConversationTurn(params: {
+    userIntervention?: boolean;
+    taskContext?: string;
+    metadata?: Record<string, unknown>;
+}): void;
+/**
+ * Track a tool call with enhanced metrics
+ */
+declare function trackToolCall(params: {
+    toolName: string;
+    success: boolean;
+    duration: number;
+    inputSize?: number;
+    outputSize?: number;
+    linesAdded?: number;
+    linesRemoved?: number;
+    filesModified?: string[];
+    language?: string;
+    fileOperation?: 'read' | 'write' | 'edit' | 'delete' | 'create';
+    retryAttempt?: number;
+    metadata?: Record<string, unknown>;
+}): void;
+/**
+ * Track file operation (read/write/edit)
+ */
+declare function trackFileOperation(params: {
+    operation: 'read' | 'write' | 'edit' | 'delete' | 'create';
+    file: string;
+    linesAdded?: number;
+    linesRemoved?: number;
+    language?: string;
+    duration?: number;
+}): void;
+/**
+ * Track code acceptance/rejection with context
+ */
+declare function trackCodeDecision(params: {
+    accepted: boolean;
+    linesAdded?: number;
+    linesRemoved?: number;
+    filesModified?: string[];
+    language?: string;
+    userIntervention?: boolean;
+    taskContext?: string;
+}): void;
+/**
+ * Track an error event
+ */
+declare function trackError(params: {
+    message: string;
+    recovered?: boolean;
+    retryAttempt?: number;
+    toolName?: string;
+    metadata?: Record<string, unknown>;
+}): void;
+/**
+ * Track a rule violation (coding standard violation, pattern anti-pattern, etc.)
+ *
+ * Use this to track when AI-generated code violates established
+ * project rules like those in CLAUDE.md, eslint configs, or architectural patterns.
+ *
+ * @example
+ * trackRuleDeviation({
+ *   ruleName: 'use-bulkwrite',
+ *   ruleSource: 'CLAUDE.md',
+ *   category: 'db_pattern',
+ *   severity: 'warning',
+ *   description: 'MongoDB writes should use bulkWrite instead of individual operations',
+ *   violatingCode: 'await collection.updateOne(...)',
+ *   suggestedFix: 'Use collection.bulkWrite([{ updateOne: {...} }])',
+ *   file: 'src/api/ingest.ts',
+ *   line: 238,
+ *   corrected: true,
+ *   confidence: 0.95,
+ * });
+ */
+declare function trackRuleDeviation(params: {
+    /** Name/identifier of the rule that was violated */
+    ruleName: string;
+    /** Source of the rule (e.g., "CLAUDE.md", "eslint", "project-standards") */
+    ruleSource?: string;
+    /** Category of the rule violation */
+    category?: RuleViolationCategory;
+    /** Severity of the violation */
+    severity?: RuleViolationSeverity;
+    /** Description of what rule was violated */
+    description?: string;
+    /** The problematic code or pattern */
+    violatingCode?: string;
+    /** Suggested fix or correct pattern */
+    suggestedFix?: string;
+    /** File where the violation occurred */
+    file?: string;
+    /** Line number where violation occurred */
+    line?: number;
+    /** Whether the violation was auto-corrected */
+    corrected?: boolean;
+    /** Confidence score (0-1) that this is actually a violation */
+    confidence?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}): void;
+/**
+ * Track a generic event
+ */
+declare function track(event: AIDevEvent): void;
+/**
+ * Flush events to Rulecatch API
+ */
+declare function flush(): Promise<void>;
+/**
+ * Get current session metrics
+ */
+declare function getSessionMetrics(): SessionMetrics | null;
+/**
+ * Check if a session is active
+ */
+declare function isSessionActive(): boolean;
+/**
+ * Get current session ID
+ */
+declare function getSessionId(): string | null;
+/**
+ * Pause session (marks idle period)
+ */
+declare function pauseSession(): void;
+/**
+ * Resume session
+ */
+declare function resumeSession(): void;
+/**
+ * Get current git context
+ */
+declare function getGitContext(): GitContext;
+/**
+ * Manually refresh git context
+ */
+declare function refreshGitContext(): GitContext;
+
+export { MODEL_PRICING, calculateCost, collectGitContext, decryptEventPII, decryptPII, deriveKey, encryptEventPII, encryptPII, endSession, estimateTokens, flush, formatCost, formatDuration, generateSalt, getGitContext, getGitRoot, getGitSummary, getSessionId, getSessionMetrics, hashForIndex, init, isGitRepo, isSessionActive, pauseSession, refreshGitContext, resumeSession, startSession, track, trackAIRequest, trackCodeDecision, trackConversationTurn, trackError, trackFileOperation, trackRuleDeviation, trackToolCall, verifyPrivacyKey, watchGitChanges };
+export type { AIDevEvent, AIEventType, AIModel, EncryptedField, GitContext, MCPConfig, ModelPricing, PrivacyConfig, RuleViolationCategory, RuleViolationSeverity, SessionMetrics };