@claudetools/tools 0.3.9 → 0.5.0

package/dist/helpers/api-client.d.ts

@@ -48,3 +48,40 @@ export declare function injectContext(projectId: string, query: string, userId?:
         reason?: string;
     };
 }>;
+export interface CachedDoc {
+    library: string;
+    context7Id: string | null;
+    version: string | null;
+    fetchedAt: string;
+    size: number;
+    mode: 'code' | 'info';
+    content: string;
+    library_name?: string;
+}
+export interface DocsCacheListResponse {
+    libraries: {
+        library_id: string;
+        library_name: string;
+        topics?: string[];
+        cached_at: string;
+    }[];
+}
+/**
+ * List all cached documentation libraries (global cache)
+ */
+export declare function listCachedDocs(_projectId?: string): Promise<DocsCacheListResponse>;
+/**
+ * Get cached documentation for a specific library
+ */
+export declare function getCachedDocs(_projectId: string, // Unused - docs cache is global
+libraryId: string, topic?: string): Promise<CachedDoc | null>;
+/**
+ * Ensure documentation is cached (fetches from Context7 if needed)
+ */
+export declare function cacheDocs(_projectId: string, // Unused - docs cache is global
+libraryId: string, libraryName: string, _content?: string, // Unused - backend fetches from Context7
+topic?: string): Promise<{
+    success: boolean;
+    status?: string;
+    size?: number;
+}>;

package/dist/helpers/api-client.js

@@ -2,12 +2,19 @@
 // API Client and Memory Operations
 // =============================================================================
 import { API_BASE_URL, DEFAULT_USER_ID } from './config.js';
+import { getConfig } from './config-manager.js';
 export async function apiRequest(endpoint, method = 'GET', body) {
+    const config = getConfig();
+    const apiKey = config.apiKey || process.env.CLAUDETOOLS_API_KEY || process.env.MEMORY_API_KEY;
+    if (!apiKey) {
+        throw new Error('No API key found. Set CLAUDETOOLS_API_KEY or MEMORY_API_KEY in environment or ~/.claudetools/config.json');
+    }
     const url = `${API_BASE_URL}${endpoint}`;
     const options = {
         method,
         headers: {
             'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
         },
     };
     if (body) {
@@ -57,3 +64,66 @@ export async function injectContext(projectId, query, userId = DEFAULT_USER_ID)
     });
     return response.data;
 }
+/**
+ * List all cached documentation libraries (global cache)
+ */
+export async function listCachedDocs(_projectId // Unused - docs cache is global
+) {
+    try {
+        const response = await apiRequest('/api/v1/docs');
+        // Transform to expected format
+        return {
+            libraries: response.data.libraries.map(lib => ({
+                library_id: lib.library,
+                library_name: lib.library,
+                cached_at: new Date().toISOString(), // Not provided by list endpoint
+            })),
+        };
+    }
+    catch {
+        return { libraries: [] };
+    }
+}
+/**
+ * Get cached documentation for a specific library
+ */
+export async function getCachedDocs(_projectId, // Unused - docs cache is global
+libraryId, topic) {
+    try {
+        const modeParam = topic ? `?mode=info` : '';
+        const response = await apiRequest(`/api/v1/docs/${encodeURIComponent(libraryId)}${modeParam}`);
+        if (!response.success || !response.data) {
+            return null;
+        }
+        // Add compatibility alias
+        return {
+            ...response.data,
+            library_name: response.data.library,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure documentation is cached (fetches from Context7 if needed)
+ */
+export async function cacheDocs(_projectId, // Unused - docs cache is global
+libraryId, libraryName, _content, // Unused - backend fetches from Context7
+topic) {
+    try {
+        const response = await apiRequest('/api/v1/docs/ensure', 'POST', {
+            library: libraryName || libraryId,
+            mode: topic ? 'info' : 'code',
+            topic,
+        });
+        return {
+            success: response.success,
+            status: response.data?.status,
+            size: response.data?.size,
+        };
+    }
+    catch {
+        return { success: false };
+    }
+}

package/dist/helpers/codedna-monitoring.d.ts

@@ -0,0 +1,34 @@
+import { type ErrorRateResult } from './error-tracking.js';
+export interface DashboardMetrics {
+    timeRange: string;
+    errorMetrics: ErrorRateResult;
+    alerts: Alert[];
+    recommendations: string[];
+}
+export interface Alert {
+    level: 'info' | 'warning' | 'critical';
+    message: string;
+    metric: string;
+    value: number;
+    threshold: number;
+}
+/**
+ * Get dashboard metrics for a time range
+ */
+export declare function getDashboardMetrics(startTime: string, endTime: string): Promise<DashboardMetrics>;
+/**
+ * Get error metrics for last 24 hours
+ */
+export declare function getLast24Hours(): Promise<DashboardMetrics>;
+/**
+ * Get error metrics for last 7 days
+ */
+export declare function getLast7Days(): Promise<DashboardMetrics>;
+/**
+ * Print dashboard to console
+ */
+export declare function printDashboard(metrics: DashboardMetrics): void;
+/**
+ * CLI command: npm run codedna:monitor
+ */
+export declare function runMonitoring(): Promise<void>;

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/library-detection.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Context7-compatible library ID mappings
+ * Maps canonical names to context7 library IDs
+ */
+export declare const CONTEXT7_LIBRARY_IDS: Record<string, string>;
+export interface DetectedLibrary {
+    name: string;
+    context7Id?: string;
+    mentions: number;
+}
+/**
+ * Detect libraries mentioned in text
+ * @param text - Text to scan for library mentions
+ * @returns Array of detected libraries with mention counts
+ */
+export declare function detectLibraries(text: string): DetectedLibrary[];
+/**
+ * Detect libraries from goal and task descriptions
+ * @param goal - The epic/plan goal
+ * @param tasks - Array of task objects with title and description
+ * @returns Deduplicated list of detected libraries
+ */
+export declare function detectLibrariesFromPlan(goal: string, tasks: {
+    title: string;
+    description?: string;
+}[]): DetectedLibrary[];