profclaw 0.0.1-beta.1

package/dist/utils/ai-inference.js

@@ -0,0 +1,190 @@
+/**
+ * AI Inference Utility
+ *
+ * Lightweight AI inference for quick tasks like:
+ * - Ticket categorization (type, priority, labels)
+ * - Text summarization
+ * - Similarity matching
+ * - Smart suggestions
+ *
+ * Uses Ollama for local inference, falls back gracefully.
+ */
+import { logger } from './logger.js';
+const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || 'http://localhost:11434';
+const OLLAMA_MODEL = process.env.OLLAMA_MODEL || 'llama3.2';
+const INFERENCE_TIMEOUT = 30000; // 30 seconds for quick tasks
+/**
+ * Check if AI inference is available
+ */
+export async function isAIAvailable() {
+    try {
+        const response = await fetch(`${OLLAMA_BASE_URL}/api/tags`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run a quick AI inference with structured output
+ */
+export async function quickInference(systemPrompt, userPrompt, parseResponse) {
+    const startTime = Date.now();
+    try {
+        const response = await fetch(`${OLLAMA_BASE_URL}/api/chat`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: OLLAMA_MODEL,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: userPrompt },
+                ],
+                stream: false,
+                options: {
+                    temperature: 0.3, // Lower temperature for more consistent results
+                    num_predict: 512, // Short responses for quick tasks
+                },
+            }),
+            signal: AbortSignal.timeout(INFERENCE_TIMEOUT),
+        });
+        if (!response.ok) {
+            return {
+                success: false,
+                error: `Ollama API error: ${response.status}`,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        const result = (await response.json());
+        const content = result.message?.content || '';
+        try {
+            const parsed = parseResponse(content);
+            return {
+                success: true,
+                data: parsed,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        catch (parseError) {
+            logger.warn('[AI] Failed to parse response', { content, parseError });
+            return {
+                success: false,
+                error: 'Failed to parse AI response',
+                durationMs: Date.now() - startTime,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Inference failed',
+            durationMs: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * Auto-categorize a ticket based on title and description
+ */
+export async function categorizeTicket(title, description) {
+    const systemPrompt = `You are a ticket categorization system. Analyze the ticket and return a JSON object with:
+- type: one of "task", "bug", "feature", "epic", "story", "subtask"
+- priority: one of "critical", "high", "medium", "low", "none"
+- labels: array of 1-5 relevant labels (lowercase, hyphen-separated)
+- confidence: number 0-1 representing your confidence
+
+Rules:
+- "bug" = something broken, error, crash, not working
+- "feature" = new functionality request
+- "task" = work item, general task
+- "epic" = large initiative with multiple stories
+- "story" = user-facing requirement
+- "subtask" = small piece of larger work
+
+For priority:
+- "critical" = security issue, data loss, system down
+- "high" = important, affects many users
+- "medium" = standard priority
+- "low" = nice to have
+- "none" = informational
+
+Return ONLY valid JSON, no explanation.`;
+    const userPrompt = `Title: ${title}
+${description ? `Description: ${description}` : ''}`;
+    return quickInference(systemPrompt, userPrompt, (text) => {
+        // Extract JSON from response (handle markdown code blocks)
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            throw new Error('No JSON found');
+        const parsed = JSON.parse(jsonMatch[0]);
+        // Validate and normalize
+        const validTypes = ['task', 'bug', 'feature', 'epic', 'story', 'subtask'];
+        const validPriorities = ['critical', 'high', 'medium', 'low', 'none'];
+        return {
+            type: validTypes.includes(parsed.type) ? parsed.type : 'task',
+            priority: validPriorities.includes(parsed.priority) ? parsed.priority : 'medium',
+            labels: Array.isArray(parsed.labels) ? parsed.labels.slice(0, 5) : [],
+            confidence: typeof parsed.confidence === 'number' ? Math.min(1, Math.max(0, parsed.confidence)) : 0.5,
+        };
+    });
+}
+/**
+ * Get AI suggestions to improve a ticket
+ */
+export async function suggestTicketImprovements(title, description, type) {
+    const systemPrompt = `You are a ticket improvement assistant. Analyze the ticket and suggest improvements as JSON:
+- title: improved title (only if current is unclear, otherwise null)
+- description: improved description with more detail (only if needed, otherwise null)
+- acceptanceCriteria: array of 2-4 acceptance criteria (clear, testable statements)
+- suggestedLabels: array of 2-4 relevant labels
+- estimatedEffort: "small" (< 1 day), "medium" (1-3 days), "large" (> 3 days)
+
+Keep suggestions practical and actionable. Return ONLY valid JSON.`;
+    const userPrompt = `Type: ${type || 'task'}
+Title: ${title}
+${description ? `Description: ${description}` : 'No description provided'}`;
+    return quickInference(systemPrompt, userPrompt, (text) => {
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            throw new Error('No JSON found');
+        const parsed = JSON.parse(jsonMatch[0]);
+        return {
+            title: parsed.title || undefined,
+            description: parsed.description || undefined,
+            acceptanceCriteria: Array.isArray(parsed.acceptanceCriteria) ? parsed.acceptanceCriteria : undefined,
+            suggestedLabels: Array.isArray(parsed.suggestedLabels) ? parsed.suggestedLabels : undefined,
+            estimatedEffort: ['small', 'medium', 'large'].includes(parsed.estimatedEffort)
+                ? parsed.estimatedEffort
+                : undefined,
+        };
+    });
+}
+/**
+ * Generate a summary from ticket content
+ */
+export async function summarizeTicket(title, description, comments) {
+    const systemPrompt = `Summarize the ticket in 1-2 sentences. Be concise and focus on the main objective.`;
+    const userPrompt = `Title: ${title}
+${description ? `Description: ${description}` : ''}
+${comments && comments.length > 0 ? `\nComments:\n${comments.join('\n')}` : ''}`;
+    return quickInference(systemPrompt, userPrompt, (text) => text.trim());
+}
+/**
+ * Calculate text similarity score (simple word overlap for now)
+ * Returns 0-1 where 1 is identical
+ */
+export function calculateSimilarity(text1, text2) {
+    const normalize = (s) => s.toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '')
+        .split(/\s+/)
+        .filter(w => w.length > 2);
+    const words1 = new Set(normalize(text1));
+    const words2 = new Set(normalize(text2));
+    if (words1.size === 0 || words2.size === 0)
+        return 0;
+    const intersection = [...words1].filter(w => words2.has(w)).length;
+    const union = new Set([...words1, ...words2]).size;
+    return intersection / union; // Jaccard similarity
+}
+//# sourceMappingURL=ai-inference.js.map

package/dist/utils/ai-responder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AI Comment Responder
+ *
+ * Generates helpful AI responses to ticket comments using Ollama.
+ * Can analyze context, answer questions, and provide suggestions.
+ */
+import type { Ticket, TicketComment } from '../tickets/types.js';
+export interface AIResponseResult {
+    success: boolean;
+    response?: string;
+    shouldPost: boolean;
+    confidence: number;
+    responseType: 'answer' | 'clarification' | 'suggestion' | 'acknowledgment' | 'none';
+    error?: string;
+    durationMs: number;
+}
+/**
+ * Analyze a comment to determine if it needs an AI response
+ */
+export declare function analyzeComment(comment: string, ticket: Pick<Ticket, 'title' | 'description' | 'type' | 'status' | 'labels'>, previousComments?: TicketComment[]): Promise<{
+    needsResponse: boolean;
+    reason: string;
+    responseType: AIResponseResult['responseType'];
+}>;
+/**
+ * Generate an AI response to a comment
+ */
+export declare function generateResponse(comment: string, ticket: Pick<Ticket, 'title' | 'description' | 'type' | 'status' | 'labels' | 'priority'>, previousComments?: TicketComment[], responseType?: AIResponseResult['responseType']): Promise<AIResponseResult>;
+/**
+ * Full pipeline: analyze comment and generate response if needed
+ */
+export declare function processComment(comment: string, ticket: Pick<Ticket, 'title' | 'description' | 'type' | 'status' | 'labels' | 'priority'>, previousComments?: TicketComment[], options?: {
+    autoPost?: boolean;
+    minConfidence?: number;
+}): Promise<AIResponseResult>;
+/**
+ * Get a quick status on AI responder availability
+ */
+export declare function getResponderStatus(): Promise<{
+    available: boolean;
+    model: string;
+    baseUrl: string;
+}>;
+//# sourceMappingURL=ai-responder.d.ts.map

package/dist/utils/ai-responder.js

@@ -0,0 +1,272 @@
+/**
+ * AI Comment Responder
+ *
+ * Generates helpful AI responses to ticket comments using Ollama.
+ * Can analyze context, answer questions, and provide suggestions.
+ */
+import { logger } from './logger.js';
+import { quickInference, isAIAvailable } from './ai-inference.js';
+const OLLAMA_BASE_URL = process.env.OLLAMA_BASE_URL || 'http://localhost:11434';
+const OLLAMA_MODEL = process.env.OLLAMA_MODEL || 'llama3.2';
+const RESPONSE_TIMEOUT = 60000; // 60 seconds for longer responses
+/**
+ * Analyze a comment to determine if it needs an AI response
+ */
+export async function analyzeComment(comment, ticket, previousComments = []) {
+    const systemPrompt = `You analyze ticket comments to determine if an AI assistant should respond.
+
+Return a JSON object with:
+- needsResponse: boolean - true if AI should respond
+- reason: brief explanation
+- responseType: "answer" | "clarification" | "suggestion" | "acknowledgment" | "none"
+
+Respond TRUE for:
+- Direct questions about implementation, approach, or status
+- Requests for help or clarification
+- Technical questions the AI can help with
+- Comments asking for suggestions or alternatives
+
+Respond FALSE for:
+- Simple status updates ("working on this", "done", "merged")
+- Acknowledgments without questions ("thanks", "got it", "ok")
+- Comments that are clearly human-to-human conversation
+- Already answered questions (check previous comments)
+- Inflammatory or off-topic comments
+
+Return ONLY valid JSON.`;
+    const userPrompt = `Ticket: ${ticket.title}
+Type: ${ticket.type}
+Status: ${ticket.status}
+Description: ${ticket.description || 'None'}
+Labels: ${ticket.labels.join(', ') || 'None'}
+
+Previous comments (last 3):
+${previousComments.slice(-3).map((c) => `- ${c.author.name}: ${c.content}`).join('\n') || 'None'}
+
+New comment to analyze:
+"${comment}"`;
+    const result = await quickInference(systemPrompt, userPrompt, (text) => {
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            throw new Error('No JSON found');
+        return JSON.parse(jsonMatch[0]);
+    });
+    if (!result.success || !result.data) {
+        return { needsResponse: false, reason: 'Analysis failed', responseType: 'none' };
+    }
+    return {
+        needsResponse: result.data.needsResponse === true,
+        reason: result.data.reason || '',
+        responseType: result.data.responseType || 'none',
+    };
+}
+/**
+ * Generate an AI response to a comment
+ */
+export async function generateResponse(comment, ticket, previousComments = [], responseType = 'answer') {
+    const startTime = Date.now();
+    try {
+        const available = await isAIAvailable();
+        if (!available) {
+            return {
+                success: false,
+                shouldPost: false,
+                confidence: 0,
+                responseType: 'none',
+                error: 'AI service not available',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        const systemPrompt = buildSystemPrompt(responseType, ticket);
+        const userPrompt = buildUserPrompt(comment, ticket, previousComments);
+        logger.debug('[AIResponder] Generating response', { ticketType: ticket.type, responseType });
+        const response = await fetch(`${OLLAMA_BASE_URL}/api/chat`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                model: OLLAMA_MODEL,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: userPrompt },
+                ],
+                stream: false,
+                options: {
+                    temperature: 0.5,
+                    num_predict: 1024,
+                },
+            }),
+            signal: AbortSignal.timeout(RESPONSE_TIMEOUT),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            logger.error('[AIResponder] API error', undefined, { status: response.status, error: errorText });
+            return {
+                success: false,
+                shouldPost: false,
+                confidence: 0,
+                responseType: 'none',
+                error: `API error: ${response.status}`,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        const result = (await response.json());
+        const content = result.message?.content || '';
+        // Parse response to extract confidence and actual response
+        const { responseText, confidence, shouldPost } = parseResponse(content, responseType);
+        logger.info('[AIResponder] Response generated', {
+            responseType,
+            confidence,
+            shouldPost,
+            length: responseText.length,
+            durationMs: Date.now() - startTime,
+        });
+        return {
+            success: true,
+            response: responseText,
+            shouldPost,
+            confidence,
+            responseType,
+            durationMs: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        logger.error('[AIResponder] Generation failed', error instanceof Error ? error : undefined);
+        return {
+            success: false,
+            shouldPost: false,
+            confidence: 0,
+            responseType: 'none',
+            error: error instanceof Error ? error.message : 'Unknown error',
+            durationMs: Date.now() - startTime,
+        };
+    }
+}
+/**
+ * Full pipeline: analyze comment and generate response if needed
+ */
+export async function processComment(comment, ticket, previousComments = [], options = {}) {
+    const startTime = Date.now();
+    const { autoPost = false, minConfidence = 0.6 } = options;
+    // First, analyze if response is needed
+    const analysis = await analyzeComment(comment, ticket, previousComments);
+    if (!analysis.needsResponse) {
+        logger.debug('[AIResponder] No response needed', { reason: analysis.reason });
+        return {
+            success: true,
+            shouldPost: false,
+            confidence: 0,
+            responseType: 'none',
+            durationMs: Date.now() - startTime,
+        };
+    }
+    // Generate response
+    const result = await generateResponse(comment, ticket, previousComments, analysis.responseType);
+    // Override shouldPost based on options
+    if (autoPost && result.success && result.confidence >= minConfidence) {
+        result.shouldPost = true;
+    }
+    else if (!autoPost) {
+        result.shouldPost = false;
+    }
+    return result;
+}
+// === Helper Functions ===
+function buildSystemPrompt(responseType, ticket) {
+    const basePrompt = `You are a helpful AI assistant for a software project ticket system.
+You're responding to a comment on a ${ticket.type} ticket (status: ${ticket.status}, priority: ${ticket.priority}).
+
+Guidelines:
+- Be concise and helpful
+- Focus on actionable information
+- Use technical language appropriate for developers
+- If unsure, ask clarifying questions
+- Never make promises about timelines
+- Reference relevant documentation or patterns when helpful`;
+    switch (responseType) {
+        case 'answer':
+            return `${basePrompt}
+
+Your task: Provide a direct, helpful answer to the question or request.
+Format: Start with the key answer, then add supporting details if needed.`;
+        case 'clarification':
+            return `${basePrompt}
+
+Your task: Ask clarifying questions to better understand the request.
+Format: Acknowledge what you understand, then ask specific questions.`;
+        case 'suggestion':
+            return `${basePrompt}
+
+Your task: Provide constructive suggestions or alternatives.
+Format: Present 2-3 concrete suggestions with brief pros/cons.`;
+        case 'acknowledgment':
+            return `${basePrompt}
+
+Your task: Acknowledge the comment and offer to help if needed.
+Format: Brief acknowledgment with optional follow-up offer.`;
+        default:
+            return basePrompt;
+    }
+}
+function buildUserPrompt(comment, ticket, previousComments) {
+    let prompt = `**Ticket Context:**
+Title: ${ticket.title}
+Type: ${ticket.type}
+Status: ${ticket.status}
+Labels: ${ticket.labels.join(', ') || 'None'}
+${ticket.description ? `\nDescription:\n${ticket.description}` : ''}`;
+    if (previousComments.length > 0) {
+        prompt += `\n\n**Recent Comments:**\n`;
+        prompt += previousComments.slice(-5).map((c) => {
+            const author = c.author.type === 'ai' ? `AI (${c.author.name})` : c.author.name;
+            return `- ${author}: ${c.content}`;
+        }).join('\n');
+    }
+    prompt += `\n\n**Comment to respond to:**\n"${comment}"`;
+    prompt += `\n\nProvide a helpful response:`;
+    return prompt;
+}
+function parseResponse(content, responseType) {
+    // Clean up the response
+    let responseText = content.trim();
+    // Remove any markdown code block wrapping
+    if (responseText.startsWith('```')) {
+        responseText = responseText.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
+    }
+    // Calculate confidence based on response quality indicators
+    let confidence = 0.7; // Base confidence
+    // Higher confidence for longer, more detailed responses
+    if (responseText.length > 200)
+        confidence += 0.1;
+    if (responseText.length > 500)
+        confidence += 0.05;
+    // Lower confidence for short responses
+    if (responseText.length < 50)
+        confidence -= 0.2;
+    // Check for uncertainty markers
+    const uncertaintyMarkers = ['i\'m not sure', 'i think', 'maybe', 'possibly', 'unclear'];
+    if (uncertaintyMarkers.some((m) => responseText.toLowerCase().includes(m))) {
+        confidence -= 0.1;
+    }
+    // Check for definitive markers
+    const definitiveMarkers = ['specifically', 'exactly', 'definitely', 'here\'s how'];
+    if (definitiveMarkers.some((m) => responseText.toLowerCase().includes(m))) {
+        confidence += 0.1;
+    }
+    // Clamp confidence
+    confidence = Math.min(1, Math.max(0, confidence));
+    // Determine if should post based on response type and confidence
+    const shouldPost = responseType !== 'none' && confidence >= 0.5 && responseText.length >= 20;
+    return { responseText, confidence, shouldPost };
+}
+/**
+ * Get a quick status on AI responder availability
+ */
+export async function getResponderStatus() {
+    const available = await isAIAvailable();
+    return {
+        available,
+        model: OLLAMA_MODEL,
+        baseUrl: OLLAMA_BASE_URL,
+    };
+}
+//# sourceMappingURL=ai-responder.js.map

package/dist/utils/circuit-breaker.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Circuit Breaker Implementation
+ *
+ * Protects against cascading failures by "opening" the circuit
+ * when error rates exceed thresholds, preventing further requests
+ * until the service has time to recover.
+ */
+import { AppError } from '../types/errors.js';
+/**
+ * Circuit breaker states
+ */
+export declare enum CircuitState {
+    /** Circuit is closed, requests flow normally */
+    CLOSED = "CLOSED",
+    /** Circuit is open, requests are blocked */
+    OPEN = "OPEN",
+    /** Circuit is testing if service recovered */
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker configuration
+ */
+export interface CircuitBreakerConfig {
+    /** Name for logging/debugging */
+    name: string;
+    /** Number of failures before opening circuit */
+    failureThreshold: number;
+    /** Time window for counting failures (ms) */
+    failureWindow: number;
+    /** Time to wait before attempting recovery (ms) */
+    resetTimeout: number;
+    /** Number of successful requests in half-open before closing */
+    successThreshold: number;
+    /** Request timeout (ms) */
+    timeout?: number;
+}
+/**
+ * Circuit breaker statistics
+ */
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    totalRequests: number;
+    lastFailureTime?: Date;
+    lastSuccessTime?: Date;
+    stateChangedAt: Date;
+}
+/**
+ * Circuit breaker error
+ */
+export declare class CircuitBreakerError extends AppError {
+    constructor(name: string, state: CircuitState);
+}
+/**
+ * Circuit Breaker implementation
+ */
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private failureCount;
+    private successCount;
+    private totalRequests;
+    private lastFailureTime?;
+    private lastSuccessTime?;
+    private stateChangedAt;
+    private failures;
+    private resetTimer?;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Execute a function through the circuit breaker
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute function with timeout
+     */
+    private withTimeout;
+    /**
+     * Handle successful execution
+     */
+    private onSuccess;
+    /**
+     * Handle failed execution
+     */
+    private onFailure;
+    /**
+     * Transition to a new state
+     */
+    private transitionTo;
+    /**
+     * Get current statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset(): void;
+    /**
+     * Manually open the circuit breaker
+     */
+    open(): void;
+    /**
+     * Get current state
+     */
+    getState(): CircuitState;
+}
+/**
+ * Circuit breaker registry for managing multiple breakers
+ */
+declare class CircuitBreakerRegistry {
+    private breakers;
+    /**
+     * Get or create a circuit breaker
+     */
+    getOrCreate(name: string, config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+    /**
+     * Get all circuit breakers
+     */
+    getAll(): Map<string, CircuitBreaker>;
+    /**
+     * Get stats for all breakers
+     */
+    getAllStats(): Record<string, CircuitBreakerStats>;
+    /**
+     * Reset a specific breaker
+     */
+    reset(name: string): void;
+    /**
+     * Reset all breakers
+     */
+    resetAll(): void;
+}
+export declare const circuitBreakers: CircuitBreakerRegistry;
+/**
+ * Decorator to wrap a function with a circuit breaker
+ */
+export declare function withCircuitBreaker<TArgs extends unknown[], TResult>(name: string, config?: Partial<CircuitBreakerConfig>): (_target: object, _propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: TArgs) => Promise<TResult>>) => TypedPropertyDescriptor<(...args: TArgs) => Promise<TResult>>;
+export {};
+//# sourceMappingURL=circuit-breaker.d.ts.map