0xray 2.0.0

package/dist/utils/shutdown-handler.js

@@ -0,0 +1,75 @@
+/**
+ * Graceful Shutdown Handler
+ *
+ * Centralized shutdown handling for MCP servers.
+ * Extracts common shutdown patterns to reduce code duplication.
+ *
+ * @version 1.0.0
+ * @since 2026-03-22
+ */
+import { frameworkLogger } from "../core/framework-logger.js";
+/**
+ * Creates a graceful shutdown handler for MCP servers
+ *
+ * @param options - Configuration for the shutdown handler
+ * @returns ShutdownHandler with cleanup and stop methods
+ */
+export function createGracefulShutdown(options) {
+    const { serverName, server, shutdownTimeout = 5000 } = options;
+    let isShuttingDown = false;
+    const cleanup = async (signal) => {
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        await frameworkLogger.log(serverName, "shutdown-initiated", "info", { signal });
+        // Force exit after timeout
+        const timeout = setTimeout(() => {
+            frameworkLogger.log(serverName, "shutdown-timeout", "error", { message: "Graceful shutdown timeout, forcing exit..." });
+            process.exit(1);
+        }, shutdownTimeout);
+        try {
+            if (server && typeof server.close === "function") {
+                await server.close();
+            }
+            clearTimeout(timeout);
+            await frameworkLogger.log(serverName, "shutdown-complete", "info", { message: `${serverName} shut down gracefully` });
+            process.exit(0);
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            frameworkLogger.log(serverName, "shutdown-error", "error", { message: `Error during ${serverName} shutdown: ${error instanceof Error ? error.message : String(error)}` });
+            process.exit(1);
+        }
+    };
+    const stop = () => {
+        cleanup("manual-stop");
+    };
+    // Register signal handlers
+    process.on("SIGINT", () => cleanup("SIGINT"));
+    process.on("SIGTERM", () => cleanup("SIGTERM"));
+    process.on("SIGHUP", () => cleanup("SIGHUP"));
+    // Handle uncaught exceptions
+    process.on("uncaughtException", (error) => {
+        frameworkLogger.log(serverName, "uncaught-exception", "error", { message: `Uncaught Exception: ${error instanceof Error ? error.message : String(error)}` });
+        cleanup("uncaughtException");
+    });
+    // Handle unhandled rejections
+    process.on("unhandledRejection", (reason, promise) => {
+        frameworkLogger.log(serverName, "unhandled-rejection", "error", { message: `Unhandled Rejection at: ${String(promise)} reason: ${String(reason)}` });
+        cleanup("unhandledRejection");
+    });
+    // Monitor parent process (opencode) and shutdown if it dies
+    const checkParent = async () => {
+        try {
+            process.kill(process.ppid, 0);
+            setTimeout(checkParent, 1000);
+        }
+        catch {
+            await frameworkLogger.log(serverName, "parent-process-died", "info", { message: "Parent process (opencode) died, shutting down..." });
+            cleanup("parent-process-death");
+        }
+    };
+    // Start parent monitoring after 2 seconds
+    setTimeout(checkParent, 2000);
+    return { cleanup, stop };
+}

package/dist/utils/test-template-generator.js

@@ -0,0 +1,178 @@
+/**
+ * Test Template Generator for 0xRay Framework
+ *
+ * Automatically generates test templates for different file types
+ * to ensure consistent test coverage and structure.
+ */
+import { frameworkLogger } from "../core/framework-logger.js";
+import fs from "fs";
+/**
+ * Generate a test template based on file type and structure
+ */
+export function generateTestTemplate(options) {
+    const { filePath, componentName, exports = [], isReact = false, isTypeScript = false, } = options;
+    const fileName = filePath
+        .split("/")
+        .pop()
+        ?.replace(/\.(ts|tsx|js|jsx)$/, "") || "Unknown";
+    const testFileName = `${fileName}.test.${isTypeScript ? "ts" : "js"}${isReact ? "x" : ""}`;
+    if (isReact) {
+        return generateReactTestTemplate(fileName, componentName || fileName, isTypeScript);
+    }
+    return generateUnitTestTemplate(fileName, exports, isTypeScript);
+}
+/**
+ * Generate React component test template
+ */
+function generateReactTestTemplate(fileName, componentName, isTypeScript) {
+    const typeAnnotation = isTypeScript ? ": RenderResult" : "";
+    const typeImport = isTypeScript ? ", RenderResult" : "";
+    return `import { render, screen } from '@testing-library/react';
+import { expect, describe, it${typeImport} } from '${isTypeScript ? "vitest" : "jest"}';
+import { ${componentName} } from './${fileName}';
+
+describe('${componentName}', () => {
+  it('should render successfully', () => {
+    const { container }${typeAnnotation} = render(<${componentName} />);
+    expect(container).toBeInTheDocument();
+  });
+
+  it('should render with default props', () => {
+    render(<${componentName} />);
+    // Add specific assertions based on component behavior
+    expect(screen.getByRole('generic')).toBeInTheDocument();
+  });
+
+  // Add more test cases based on component props and behavior
+  // it('should handle prop changes', () => {
+  //   const { rerender } = render(<${componentName} prop="value" />);
+  //   expect(screen.getByText('value')).toBeInTheDocument();
+  //
+  //   rerender(<${componentName} prop="newValue" />);
+  //   expect(screen.getByText('newValue')).toBeInTheDocument();
+  // });
+
+  // Add accessibility tests
+  it('should be accessible', () => {
+    const { container } = render(<${componentName} />);
+    expect(container).toBeAccessible();
+  });
+});
+`;
+}
+/**
+ * Generate unit test template for utility functions/classes
+ */
+function generateUnitTestTemplate(fileName, exports, isTypeScript) {
+    const describeBlocks = exports
+        .map((exportName) => {
+        if (exportName.match(/^[A-Z]/)) {
+            // Class export
+            return generateClassTestTemplate(exportName);
+        }
+        else {
+            // Function export
+            return generateFunctionTestTemplate(exportName);
+        }
+    })
+        .join("\n\n");
+    return `import { expect, describe, it } from '${isTypeScript ? "vitest" : "jest"}';
+${exports.length > 0 ? `import { ${exports.join(", ")} } from './${fileName}';` : `// import functions from './${fileName}'`}
+
+${describeBlocks}
+
+describe('${fileName}', () => {
+  // Add general module tests here
+  it('should export expected functions', () => {
+    ${exports.length > 0 ? exports.map((exp) => `expect(typeof ${exp}).toBe('function');`).join("\n    ") : "// Add export tests"}
+  });
+});
+`;
+}
+/**
+ * Generate test template for a class
+ */
+function generateClassTestTemplate(className) {
+    return `describe('${className}', () => {
+  let instance: ${className};
+
+  beforeEach(() => {
+    // instance = new ${className}();
+  });
+
+  it('should create instance successfully', () => {
+    // expect(instance).toBeInstanceOf(${className});
+    expect(true).toBe(true); // Placeholder test
+  });
+
+  // Add method tests
+  // it('should have expected methods', () => {
+  //   expect(typeof instance.methodName).toBe('function');
+  // });
+
+  // Add property tests
+  // it('should have expected properties', () => {
+  //   expect(instance.propertyName).toBeDefined();
+  // });
+});`;
+}
+/**
+ * Generate test template for a function
+ */
+function generateFunctionTestTemplate(functionName) {
+    return `describe('${functionName}', () => {
+  it('should be a function', () => {
+    expect(typeof ${functionName}).toBe('function');
+  });
+
+  it('should handle basic input', () => {
+    // const result = ${functionName}(/* test input */);
+    // expect(result).toBe(/* expected output */);
+    expect(true).toBe(true); // Placeholder test
+  });
+
+  it('should handle edge cases', () => {
+    // Test null, undefined, empty inputs
+    // expect(() => ${functionName}(null)).toThrow();
+    expect(true).toBe(true); // Placeholder test
+  });
+
+  // Add more specific test cases based on function behavior
+});`;
+}
+/**
+ * Analyze a source file to extract exports for test generation
+ */
+export function analyzeSourceFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const exports = [];
+        const isReact = /\b(React|jsx?|tsx?)\b/.test(content) ||
+            filePath.endsWith(".tsx") ||
+            filePath.endsWith(".jsx");
+        const isTypeScript = filePath.endsWith(".ts") || filePath.endsWith(".tsx");
+        // Extract named exports
+        const exportMatches = content.match(/export\s+(?:const|function|class|let|var)\s+(\w+)/g);
+        if (exportMatches) {
+            exportMatches.forEach((match) => {
+                const nameMatch = match.match(/(?:const|function|class|let|var)\s+(\w+)/);
+                if (nameMatch && nameMatch[1] && !exports.includes(nameMatch[1])) {
+                    exports.push(nameMatch[1]);
+                }
+            });
+        }
+        // Extract default export if no named exports found
+        if (exports.length === 0 && /export\s+default/.test(content)) {
+            const fileName = filePath
+                .split("/")
+                .pop()
+                ?.replace(/\.(ts|tsx|js|jsx)$/, "") || "Component";
+            exports.push(fileName.charAt(0).toUpperCase() + fileName.slice(1));
+        }
+        return { exports, isReact, isTypeScript };
+    }
+    catch (error) {
+        frameworkLogger.log("test-template-generator", "analyze-file", "error", { error, message: `Error analyzing ${filePath}:` });
+        return { exports: [], isReact: false, isTypeScript: false };
+    }
+}

package/dist/utils/token-manager.js

@@ -0,0 +1,163 @@
+import * as fs from "fs";
+import * as path from "path";
+import { resolveConfigPath } from "../core/config-paths.js";
+export class TokenManager {
+    config;
+    constructor(configPath = resolveConfigPath("config.json") || path.join(process.cwd(), ".strray", "config.json")) {
+        this.config = this.loadConfig(configPath);
+    }
+    loadConfig(configPath) {
+        try {
+            const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            return (config.token_management || {
+                maxPromptTokens: 20000,
+                warningThreshold: 15000,
+                modelLimits: {},
+                contextPruning: {
+                    enabled: true,
+                    aggressivePruning: true,
+                    preserveCriticalContext: true,
+                },
+            });
+        }
+        catch (error) {
+            // Fallback defaults if config loading fails
+            return {
+                maxPromptTokens: 20000,
+                warningThreshold: 15000,
+                modelLimits: {},
+                contextPruning: {
+                    enabled: true,
+                    aggressivePruning: true,
+                    preserveCriticalContext: true,
+                },
+            };
+        }
+    }
+    /**
+     * Estimate token count for text (rough approximation)
+     * Uses 4 characters per token as a conservative estimate
+     */
+    estimateTokens(text) {
+        return Math.ceil(text.length / 4);
+    }
+    /**
+     * Check if prompt exceeds limits
+     */
+    checkLimits(prompt, modelName) {
+        const currentTokens = this.estimateTokens(prompt);
+        const maxTokens = modelName
+            ? this.config.modelLimits[modelName] || this.config.maxPromptTokens
+            : this.config.maxPromptTokens;
+        const withinLimit = currentTokens <= maxTokens;
+        const needsPruning = currentTokens > this.config.maxPromptTokens;
+        const warning = currentTokens > this.config.warningThreshold;
+        return {
+            withinLimit,
+            currentTokens,
+            maxTokens,
+            needsPruning,
+            warning,
+        };
+    }
+    /**
+     * Prune context to fit within token limits
+     */
+    pruneContext(context, targetTokens = this.config.maxPromptTokens) {
+        if (!this.config.contextPruning.enabled) {
+            return context;
+        }
+        const currentTokens = this.estimateTokens(context);
+        if (currentTokens <= targetTokens) {
+            return context; // No pruning needed
+        }
+        // Preserve critical sections (AGENTS.md header, codex terms, etc.)
+        const criticalSections = this.extractCriticalSections(context);
+        const criticalTokens = this.estimateTokens(criticalSections.join("\n"));
+        // Calculate available tokens for non-critical content
+        const availableTokens = Math.max(targetTokens - criticalTokens, targetTokens * 0.3); // Reserve at least 30%
+        const nonCriticalContent = this.extractNonCriticalContent(context);
+        const prunedNonCritical = this.pruneNonCriticalContent(nonCriticalContent, availableTokens);
+        return `${criticalSections.join("\n")}\n\n${prunedNonCritical}`;
+    }
+    extractCriticalSections(context) {
+        const lines = context.split("\n");
+        const criticalSections = [];
+        // Always preserve codex terms and framework overview
+        const codexSection = this.extractSection(lines, "Universal Development Codex");
+        const frameworkSection = this.extractSection(lines, "0xRay Framework");
+        if (codexSection)
+            criticalSections.push(codexSection);
+        if (frameworkSection)
+            criticalSections.push(frameworkSection);
+        return criticalSections;
+    }
+    extractSection(lines, sectionTitle) {
+        const startIndex = lines.findIndex((line) => line.includes(sectionTitle));
+        if (startIndex === -1)
+            return null;
+        let endIndex = lines.length;
+        for (let i = startIndex + 1; i < lines.length; i++) {
+            const currentLine = lines[i];
+            if (currentLine &&
+                currentLine.startsWith("#") &&
+                currentLine !== lines[startIndex]) {
+                endIndex = i;
+                break;
+            }
+        }
+        return lines.slice(startIndex, endIndex).join("\n");
+    }
+    extractNonCriticalContent(context) {
+        const criticalSections = this.extractCriticalSections(context);
+        let result = context;
+        for (const section of criticalSections) {
+            result = result.replace(section, "");
+        }
+        return result.trim();
+    }
+    pruneNonCriticalContent(content, maxTokens) {
+        const lines = content.split("\n");
+        const result = [];
+        let currentTokens = 0;
+        for (const line of lines) {
+            const lineTokens = this.estimateTokens(line);
+            if (currentTokens + lineTokens <= maxTokens) {
+                result.push(line);
+                currentTokens += lineTokens;
+            }
+            else {
+                // Truncate line if too long
+                if (lineTokens > maxTokens * 0.1) {
+                    // If single line is >10% of limit
+                    const maxChars = maxTokens * 4 * 0.1; // Convert tokens to chars
+                    result.push(line.substring(0, maxChars) + "...[truncated]");
+                }
+                break;
+            }
+        }
+        return result.join("\n");
+    }
+    /**
+     * Generate warning message for token limits
+     */
+    generateWarning(limitCheck) {
+        if (limitCheck.withinLimit && !limitCheck.warning)
+            return "";
+        const messages = [];
+        if (limitCheck.warning) {
+            messages.push(`⚠️  Token usage warning: ${limitCheck.currentTokens.toLocaleString()} tokens (${((limitCheck.currentTokens / limitCheck.maxTokens) * 100).toFixed(1)}% of limit)`);
+        }
+        if (!limitCheck.withinLimit) {
+            messages.push(`🚨 Token limit exceeded: ${limitCheck.currentTokens.toLocaleString()} > ${limitCheck.maxTokens.toLocaleString()} tokens`);
+            messages.push("Context will be automatically pruned to fit within limits.");
+        }
+        return messages.join("\n");
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}

package/dist/validation/estimation-validator.js

@@ -0,0 +1,241 @@
+/**
+ * Estimation Validator
+ *
+ * Tracks estimates vs. actuals and provides calibrated estimates
+ * Prevents the "always estimate high" syndrome by learning from history
+ */
+import { frameworkLogger } from '../core/framework-logger.js';
+/**
+ * Estimation Validator
+ * Tracks estimates and learns from actuals to improve future predictions
+ */
+export class EstimationValidator {
+    estimations = new Map();
+    calibrations = new Map();
+    STORAGE_KEY = 'strray-estimations';
+    constructor() {
+        this.loadFromStorage();
+    }
+    /**
+     * Start tracking an estimate
+     */
+    startEstimate(taskId, description, category, estimatedMinutes, confidence = 'medium') {
+        this.estimations.set(taskId, {
+            taskId,
+            description,
+            category,
+            estimatedMinutes,
+            actualMinutes: 0,
+            timestamp: new Date().toISOString(),
+            confidence,
+        });
+        void frameworkLogger.log('estimation-validator', 'estimate-started', 'info', {
+            taskId,
+            category,
+            estimatedMinutes,
+            confidence,
+        });
+    }
+    /**
+     * Complete tracking and record actual time
+     */
+    completeEstimate(taskId) {
+        const estimation = this.estimations.get(taskId);
+        if (!estimation) {
+            void frameworkLogger.log('estimation-validator', 'complete-failed', 'warning', {
+                taskId,
+                error: 'No estimate found for task',
+            });
+            return;
+        }
+        const startTime = new Date(estimation.timestamp).getTime();
+        const actualMinutes = Math.round((Date.now() - startTime) / 60000);
+        estimation.actualMinutes = actualMinutes;
+        // Update calibration for this category
+        this.updateCalibration(estimation);
+        // Log the result
+        const ratio = actualMinutes / estimation.estimatedMinutes;
+        const variance = Math.round((ratio - 1) * 100);
+        void frameworkLogger.log('estimation-validator', 'estimate-completed', 'info', {
+            taskId,
+            category: estimation.category,
+            estimated: estimation.estimatedMinutes,
+            actual: actualMinutes,
+            variance: `${variance > 0 ? '+' : ''}${variance}%`,
+        });
+        this.saveToStorage();
+    }
+    /**
+     * Get calibrated estimate based on historical data
+     */
+    getCalibratedEstimate(category, baseEstimate, confidence = 'medium') {
+        const calibration = this.calibrations.get(category);
+        if (!calibration || calibration.sampleSize < 3) {
+            // Not enough data - apply default calibration based on confidence
+            const factor = confidence === 'high' ? 0.5 : confidence === 'low' ? 2.0 : 1.0;
+            return {
+                calibratedEstimate: Math.round(baseEstimate * factor),
+                calibrationFactor: factor,
+                confidence: calibration?.sampleSize || 0,
+            };
+        }
+        // Use historical calibration
+        return {
+            calibratedEstimate: Math.round(baseEstimate * calibration.avgRatio),
+            calibrationFactor: calibration.avgRatio,
+            confidence: Math.min(calibration.sampleSize / 10, 1), // Max confidence at 10 samples
+        };
+    }
+    /**
+     * Check if an estimate needs adjustment
+     */
+    validateEstimate(category, estimate) {
+        const calibration = this.calibrations.get(category);
+        if (!calibration || calibration.sampleSize < 3) {
+            return {
+                isReasonable: true,
+                suggestedEstimate: estimate,
+                warning: `No calibration data for "${category}". Consider tracking actuals.`
+            };
+        }
+        const ratio = calibration.avgRatio;
+        // If consistently underestimating by >50%
+        if (ratio > 1.5) {
+            return {
+                isReasonable: false,
+                suggestedEstimate: Math.round(estimate * ratio),
+                warning: `Historical data shows tasks in "${category}" take ${Math.round(ratio * 100)}% of estimates. Consider ${Math.round(estimate * ratio)} minutes.`,
+            };
+        }
+        // If consistently overestimating by >50%
+        if (ratio < 0.5) {
+            return {
+                isReasonable: false,
+                suggestedEstimate: Math.round(estimate * ratio),
+                warning: `Historical data shows tasks in "${category}" take only ${Math.round(ratio * 100)}% of estimates. Consider ${Math.round(estimate * ratio)} minutes.`,
+            };
+        }
+        return { isReasonable: true, suggestedEstimate: estimate };
+    }
+    /**
+     * Get estimation accuracy report
+     */
+    getAccuracyReport() {
+        const categories = [];
+        // Collect all categories
+        for (const estimation of this.estimations.values()) {
+            if (!categories.includes(estimation.category)) {
+                categories.push(estimation.category);
+            }
+        }
+        const categoryBreakdown = categories.map(cat => {
+            const calibration = this.calibrations.get(cat);
+            if (!calibration)
+                return null;
+            let trend = 'accurate';
+            if (calibration.avgRatio > 1.2)
+                trend = 'under';
+            if (calibration.avgRatio < 0.8)
+                trend = 'over';
+            return {
+                category: cat,
+                sampleSize: calibration.sampleSize,
+                avgRatio: calibration.avgRatio,
+                trend,
+            };
+        }).filter((c) => c !== null);
+        // Calculate overall accuracy
+        const totalRatio = categoryBreakdown.reduce((sum, c) => sum + c.avgRatio, 0);
+        const overallAccuracy = categoryBreakdown.length > 0
+            ? 1 / (totalRatio / categoryBreakdown.length)
+            : 0;
+        // Generate recommendations
+        const recommendations = [];
+        const underEstimators = categoryBreakdown.filter(c => c.trend === 'under');
+        if (underEstimators.length > 0) {
+            recommendations.push(`You're consistently underestimating: ${underEstimators.map(c => c.category).join(', ')}`);
+        }
+        const overEstimators = categoryBreakdown.filter(c => c.trend === 'over');
+        if (overEstimators.length > 0) {
+            recommendations.push(`You're consistently overestimating: ${overEstimators.map(c => c.category).join(', ')}`);
+        }
+        const lowConfidence = categoryBreakdown.filter(c => c.sampleSize < 3);
+        if (lowConfidence.length > 0) {
+            recommendations.push(`Need more data for: ${lowConfidence.map(c => c.category).join(', ')}`);
+        }
+        return { overallAccuracy, categoryBreakdown, recommendations };
+    }
+    updateCalibration(estimation) {
+        const existing = this.calibrations.get(estimation.category);
+        if (!existing) {
+            this.calibrations.set(estimation.category, {
+                category: estimation.category,
+                avgRatio: estimation.actualMinutes / estimation.estimatedMinutes,
+                sampleSize: 1,
+                lastUpdated: new Date().toISOString(),
+            });
+            return;
+        }
+        // Update running average
+        const newRatio = estimation.actualMinutes / estimation.estimatedMinutes;
+        const newAvg = (existing.avgRatio * existing.sampleSize + newRatio) / (existing.sampleSize + 1);
+        existing.avgRatio = newAvg;
+        existing.sampleSize++;
+        existing.lastUpdated = new Date().toISOString();
+    }
+    loadFromStorage() {
+        try {
+            const data = localStorage.getItem(this.STORAGE_KEY);
+            if (data) {
+                const parsed = JSON.parse(data);
+                this.estimations = new Map(Object.entries(parsed.estimations || {}));
+                this.calibrations = new Map(Object.entries(parsed.calibrations || {}));
+            }
+        }
+        catch {
+            // Ignore storage errors
+        }
+    }
+    saveToStorage() {
+        try {
+            const data = {
+                estimations: Object.fromEntries(this.estimations),
+                calibrations: Object.fromEntries(this.calibrations),
+            };
+            localStorage.setItem(this.STORAGE_KEY, JSON.stringify(data));
+        }
+        catch {
+            // Ignore storage errors
+        }
+    }
+}
+// Singleton
+let validatorInstance = null;
+export function getEstimationValidator() {
+    if (!validatorInstance) {
+        validatorInstance = new EstimationValidator();
+    }
+    return validatorInstance;
+}
+/**
+ * Decorator for async functions to track estimates
+ */
+export function trackEstimate(taskId, description, category, estimatedMinutes) {
+    return function (_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            const validator = getEstimationValidator();
+            validator.startEstimate(taskId, description, category, estimatedMinutes);
+            try {
+                const result = await originalMethod.apply(this, args);
+                validator.completeEstimate(taskId);
+                return result;
+            }
+            catch (error) {
+                validator.completeEstimate(taskId);
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}