@claudetools/tools 0.4.0 → 0.5.1

package/dist/helpers/codedna-monitoring.js

@@ -0,0 +1,159 @@
+// =============================================================================
+// CodeDNA Monitoring Dashboard
+// =============================================================================
+//
+// Query functions for monitoring CodeDNA performance and error rates.
+//
+import { getErrorRate } from './error-tracking.js';
+/**
+ * Get dashboard metrics for a time range
+ */
+export async function getDashboardMetrics(startTime, endTime) {
+    const errorMetrics = await getErrorRate({ startTime, endTime });
+    const alerts = [];
+    const recommendations = [];
+    // Check error rate threshold (>5% is warning, >10% is critical)
+    if (errorMetrics.errorRate > 10) {
+        alerts.push({
+            level: 'critical',
+            message: 'CodeDNA error rate exceeds 10%',
+            metric: 'error_rate',
+            value: errorMetrics.errorRate,
+            threshold: 10,
+        });
+        recommendations.push('Investigate template fetch errors and validation failures');
+        recommendations.push('Check Cloudflare Workers logs for registry issues');
+    }
+    else if (errorMetrics.errorRate > 5) {
+        alerts.push({
+            level: 'warning',
+            message: 'CodeDNA error rate exceeds 5%',
+            metric: 'error_rate',
+            value: errorMetrics.errorRate,
+            threshold: 5,
+        });
+        recommendations.push('Monitor error trends over next 24 hours');
+    }
+    // Check validation errors
+    const validationErrors = errorMetrics.errorsByType['validation_error'] || 0;
+    if (validationErrors > errorMetrics.totalErrors * 0.5) {
+        alerts.push({
+            level: 'info',
+            message: 'High percentage of validation errors (>50%)',
+            metric: 'validation_error_rate',
+            value: (validationErrors / errorMetrics.totalErrors) * 100,
+            threshold: 50,
+        });
+        recommendations.push('Review Entity DSL documentation with users');
+        recommendations.push('Consider adding Entity DSL syntax examples to error messages');
+    }
+    // Check template fetch errors
+    const templateErrors = errorMetrics.errorsByType['template_error'] || 0;
+    if (templateErrors > 3) {
+        alerts.push({
+            level: 'warning',
+            message: 'Multiple template fetch errors detected',
+            metric: 'template_errors',
+            value: templateErrors,
+            threshold: 3,
+        });
+        recommendations.push('Verify Cloudflare Workers deployment is healthy');
+        recommendations.push('Check R2 storage bucket access');
+        recommendations.push('Verify DOCS_CACHE KV namespace is operational');
+    }
+    // Check network errors
+    const networkErrors = errorMetrics.errorsByType['network_error'] || 0;
+    if (networkErrors > 2) {
+        alerts.push({
+            level: 'warning',
+            message: 'Network connectivity issues detected',
+            metric: 'network_errors',
+            value: networkErrors,
+            threshold: 2,
+        });
+        recommendations.push('Check api.claudetools.dev availability');
+        recommendations.push('Verify network connection and firewall rules');
+    }
+    return {
+        timeRange: `${startTime} to ${endTime}`,
+        errorMetrics,
+        alerts,
+        recommendations,
+    };
+}
+/**
+ * Get error metrics for last 24 hours
+ */
+export async function getLast24Hours() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    return getDashboardMetrics(startTime, endTime);
+}
+/**
+ * Get error metrics for last 7 days
+ */
+export async function getLast7Days() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    return getDashboardMetrics(startTime, endTime);
+}
+/**
+ * Print dashboard to console
+ */
+export function printDashboard(metrics) {
+    console.log('\n=================================================');
+    console.log('CodeDNA Monitoring Dashboard');
+    console.log('=================================================\n');
+    console.log(`Time Range: ${metrics.timeRange}\n`);
+    console.log('Error Metrics:');
+    console.log(`  Total Errors: ${metrics.errorMetrics.totalErrors}`);
+    console.log(`  Error Rate: ${metrics.errorMetrics.errorRate.toFixed(2)}%\n`);
+    console.log('Errors by Type:');
+    Object.entries(metrics.errorMetrics.errorsByType).forEach(([type, count]) => {
+        console.log(`  ${type}: ${count}`);
+    });
+    console.log();
+    console.log('Errors by Operation:');
+    Object.entries(metrics.errorMetrics.errorsByOperation).forEach(([op, count]) => {
+        console.log(`  ${op}: ${count}`);
+    });
+    console.log();
+    if (metrics.alerts.length > 0) {
+        console.log('Alerts:');
+        metrics.alerts.forEach(alert => {
+            const emoji = alert.level === 'critical' ? '🔴' : alert.level === 'warning' ? '🟡' : 'ℹ️';
+            console.log(`  ${emoji} [${alert.level.toUpperCase()}] ${alert.message}`);
+            console.log(`     ${alert.metric}: ${alert.value} (threshold: ${alert.threshold})`);
+        });
+        console.log();
+    }
+    if (metrics.recommendations.length > 0) {
+        console.log('Recommendations:');
+        metrics.recommendations.forEach((rec, i) => {
+            console.log(`  ${i + 1}. ${rec}`);
+        });
+        console.log();
+    }
+    if (metrics.errorMetrics.recentErrors.length > 0) {
+        console.log('Recent Errors (last 10):');
+        metrics.errorMetrics.recentErrors.forEach((error, i) => {
+            console.log(`  ${i + 1}. [${error.timestamp}] ${error.operation}`);
+            console.log(`     Type: ${error.errorType}`);
+            console.log(`     Message: ${error.errorMessage}`);
+        });
+    }
+    console.log('\n=================================================\n');
+}
+/**
+ * CLI command: npm run codedna:monitor
+ */
+export async function runMonitoring() {
+    console.log('Fetching CodeDNA metrics for last 24 hours...\n');
+    const metrics = await getLast24Hours();
+    printDashboard(metrics);
+    // Exit with error code if critical alerts
+    const hasCritical = metrics.alerts.some(a => a.level === 'critical');
+    if (hasCritical) {
+        process.exit(1);
+    }
+}

package/dist/helpers/error-tracking.d.ts

@@ -0,0 +1,73 @@
+export interface CodeDNAError {
+    timestamp: string;
+    operation: 'generate_api' | 'generate_frontend' | 'generate_component' | 'validate_spec' | 'list_generators' | 'template_fetch';
+    errorType: 'validation_error' | 'generation_error' | 'template_error' | 'network_error' | 'unknown_error';
+    errorMessage: string;
+    context: {
+        spec?: string;
+        framework?: string;
+        generatorId?: string;
+        templateFile?: string;
+        stackTrace?: string;
+    };
+    projectId?: string;
+}
+export declare class CodeDNAErrorTracker {
+    private static instance;
+    private constructor();
+    static getInstance(): CodeDNAErrorTracker;
+    /**
+     * Track a CodeDNA error
+     */
+    trackError(error: Omit<CodeDNAError, 'timestamp'>): Promise<void>;
+    /**
+     * Track validation error
+     */
+    trackValidationError(spec: string, errors: string[], projectId?: string): Promise<void>;
+    /**
+     * Track generation error
+     */
+    trackGenerationError(framework: string, spec: string, error: Error, projectId?: string): Promise<void>;
+    /**
+     * Track template fetch error
+     */
+    trackTemplateFetchError(generatorId: string, templateFile: string, error: Error, projectId?: string): Promise<void>;
+    /**
+     * Track network error
+     */
+    trackNetworkError(operation: CodeDNAError['operation'], error: Error, projectId?: string): Promise<void>;
+}
+export declare const errorTracker: CodeDNAErrorTracker;
+/**
+ * Get error rate for monitoring dashboard
+ */
+export interface ErrorRateQuery {
+    startTime: string;
+    endTime: string;
+    operation?: CodeDNAError['operation'];
+    errorType?: CodeDNAError['errorType'];
+}
+export interface ErrorRateResult {
+    totalErrors: number;
+    errorsByType: Record<string, number>;
+    errorsByOperation: Record<string, number>;
+    errorRate: number;
+    recentErrors: CodeDNAError[];
+}
+/**
+ * Query for error rate monitoring
+ *
+ * Example usage:
+ * ```typescript
+ * const result = await getErrorRate({
+ *   startTime: '2025-12-04T00:00:00Z',
+ *   endTime: '2025-12-05T00:00:00Z',
+ *   operation: 'generate_api'
+ * });
+ *
+ * if (result.errorRate > 5) {
+ *   console.warn('CodeDNA error rate exceeds 5%:', result);
+ * }
+ * ```
+ */
+export declare function getErrorRate(query: ErrorRateQuery): Promise<ErrorRateResult>;

package/dist/helpers/error-tracking.js

@@ -0,0 +1,164 @@
+// =============================================================================
+// CodeDNA Error Tracking
+// =============================================================================
+//
+// Centralized error tracking for CodeDNA operations with memory storage
+// and analytics queries.
+//
+import { storeFact, searchMemory } from './api-client.js';
+import { DEFAULT_USER_ID, resolveProjectId } from './config.js';
+export class CodeDNAErrorTracker {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!CodeDNAErrorTracker.instance) {
+            CodeDNAErrorTracker.instance = new CodeDNAErrorTracker();
+        }
+        return CodeDNAErrorTracker.instance;
+    }
+    /**
+     * Track a CodeDNA error
+     */
+    async trackError(error) {
+        try {
+            const errorRecord = {
+                ...error,
+                timestamp: new Date().toISOString(),
+            };
+            // Store error in memory system as a fact
+            const userId = DEFAULT_USER_ID;
+            const projectId = error.projectId || resolveProjectId();
+            await storeFact(projectId, 'CodeDNA', 'ERROR_OCCURRED', error.operation, JSON.stringify(errorRecord), userId);
+            // Log to console for immediate visibility
+            console.error('[CodeDNA Error]', {
+                operation: error.operation,
+                type: error.errorType,
+                message: error.errorMessage,
+            });
+        }
+        catch (trackingError) {
+            // Don't fail the operation if error tracking fails
+            console.error('[CodeDNA Error Tracking Failed]', trackingError);
+        }
+    }
+    /**
+     * Track validation error
+     */
+    async trackValidationError(spec, errors, projectId) {
+        await this.trackError({
+            operation: 'validate_spec',
+            errorType: 'validation_error',
+            errorMessage: `Validation failed: ${errors.join(', ')}`,
+            context: {
+                spec,
+            },
+            projectId,
+        });
+    }
+    /**
+     * Track generation error
+     */
+    async trackGenerationError(framework, spec, error, projectId) {
+        await this.trackError({
+            operation: 'generate_api',
+            errorType: 'generation_error',
+            errorMessage: error.message,
+            context: {
+                spec,
+                framework,
+                stackTrace: error.stack,
+            },
+            projectId,
+        });
+    }
+    /**
+     * Track template fetch error
+     */
+    async trackTemplateFetchError(generatorId, templateFile, error, projectId) {
+        await this.trackError({
+            operation: 'template_fetch',
+            errorType: 'template_error',
+            errorMessage: error.message,
+            context: {
+                generatorId,
+                templateFile,
+                stackTrace: error.stack,
+            },
+            projectId,
+        });
+    }
+    /**
+     * Track network error
+     */
+    async trackNetworkError(operation, error, projectId) {
+        await this.trackError({
+            operation,
+            errorType: 'network_error',
+            errorMessage: error.message,
+            context: {
+                stackTrace: error.stack,
+            },
+            projectId,
+        });
+    }
+}
+// Export singleton instance
+export const errorTracker = CodeDNAErrorTracker.getInstance();
+/**
+ * Query for error rate monitoring
+ *
+ * Example usage:
+ * ```typescript
+ * const result = await getErrorRate({
+ *   startTime: '2025-12-04T00:00:00Z',
+ *   endTime: '2025-12-05T00:00:00Z',
+ *   operation: 'generate_api'
+ * });
+ *
+ * if (result.errorRate > 5) {
+ *   console.warn('CodeDNA error rate exceeds 5%:', result);
+ * }
+ * ```
+ */
+export async function getErrorRate(query) {
+    const userId = DEFAULT_USER_ID;
+    const projectId = resolveProjectId();
+    // Search for error facts
+    const searchQuery = `CodeDNA ERROR_OCCURRED ${query.operation || ''}`;
+    const result = await searchMemory(projectId, searchQuery, 100, userId);
+    // Parse error records from facts
+    const errors = result.relevant_facts
+        .map((fact) => {
+        try {
+            return JSON.parse(fact.fact);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e !== null)
+        .filter((e) => {
+        const errorTime = new Date(e.timestamp).getTime();
+        const start = new Date(query.startTime).getTime();
+        const end = new Date(query.endTime).getTime();
+        return errorTime >= start && errorTime <= end;
+    })
+        .filter((e) => !query.operation || e.operation === query.operation)
+        .filter((e) => !query.errorType || e.errorType === query.errorType);
+    // Calculate error rate (errors per 100 operations - assuming 1:1 for now)
+    const errorRate = errors.length > 0 ? (errors.length / Math.max(errors.length, 1)) * 100 : 0;
+    // Group by type and operation
+    const errorsByType = {};
+    const errorsByOperation = {};
+    errors.forEach(error => {
+        errorsByType[error.errorType] = (errorsByType[error.errorType] || 0) + 1;
+        errorsByOperation[error.operation] = (errorsByOperation[error.operation] || 0) + 1;
+    });
+    return {
+        totalErrors: errors.length,
+        errorsByType,
+        errorsByOperation,
+        errorRate,
+        recentErrors: errors.slice(0, 10), // Last 10 errors
+    };
+}

package/dist/helpers/usage-analytics.d.ts

@@ -0,0 +1,91 @@
+export interface UsageEvent {
+    timestamp: string;
+    operation: 'generate_api' | 'generate_frontend' | 'generate_component' | 'validate_spec';
+    generator?: string;
+    framework?: string;
+    entityName?: string;
+    fieldCount?: number;
+    specLength?: number;
+    filesGenerated?: number;
+    linesOfCode?: number;
+    tokensSaved?: number;
+    options?: {
+        auth?: boolean;
+        validation?: boolean;
+        tests?: boolean;
+        database?: string;
+    };
+    success: boolean;
+    executionTimeMs?: number;
+    projectId?: string;
+}
+export declare class UsageAnalytics {
+    private static instance;
+    private constructor();
+    static getInstance(): UsageAnalytics;
+    /**
+     * Track a successful generation
+     */
+    trackGeneration(event: Omit<UsageEvent, 'timestamp' | 'success'>): Promise<void>;
+    /**
+     * Track a validation
+     */
+    trackValidation(spec: string, valid: boolean, entityName?: string, fieldCount?: number, projectId?: string): Promise<void>;
+}
+export declare const analytics: UsageAnalytics;
+/**
+ * Analytics query interface
+ */
+export interface AnalyticsQuery {
+    startTime: string;
+    endTime: string;
+    operation?: UsageEvent['operation'];
+    generator?: string;
+    framework?: string;
+}
+export interface AnalyticsResult {
+    totalGenerations: number;
+    totalTokensSaved: number;
+    avgTokensSavedPerGeneration: number;
+    totalLinesOfCode: number;
+    totalFiles: number;
+    generatorStats: Record<string, {
+        count: number;
+        tokensSaved: number;
+        linesOfCode: number;
+        filesGenerated: number;
+    }>;
+    frameworkStats: Record<string, number>;
+    optionsUsage: {
+        auth: number;
+        validation: number;
+        tests: number;
+    };
+    entityPatterns: Record<string, number>;
+    avgExecutionTime?: number;
+    recentGenerations: UsageEvent[];
+}
+/**
+ * Query usage analytics
+ */
+export declare function getUsageAnalytics(query: AnalyticsQuery): Promise<AnalyticsResult>;
+/**
+ * Get analytics for last 24 hours
+ */
+export declare function getLast24HoursAnalytics(): Promise<AnalyticsResult>;
+/**
+ * Get analytics for last 7 days
+ */
+export declare function getLast7DaysAnalytics(): Promise<AnalyticsResult>;
+/**
+ * Get analytics for last 30 days
+ */
+export declare function getLast30DaysAnalytics(): Promise<AnalyticsResult>;
+/**
+ * Print analytics report
+ */
+export declare function printAnalytics(result: AnalyticsResult, title?: string): void;
+/**
+ * Weekly analytics summary
+ */
+export declare function weeklyAnalyticsSummary(): Promise<void>;