0xray 2.0.0

package/dist/core/codex-formatter.js

@@ -0,0 +1,220 @@
+/**
+ * Codex Formatter — Standalone Codex-to-Prompt Converter
+ *
+ * Converts 0xRay's Universal Development Codex terms into
+ * formatted system prompt text. No OpenCode dependency, no plugin
+ * API, no framework imports. Pure input/output.
+ *
+ * This is the decoupled replacement for the codex injection that
+ * previously lived inside the OpenCode plugin (xray-codex-injection.ts).
+ *
+ * Usage from any host (Node.js, Python via bridge, HTTP, etc.):
+ *   import { formatCodexPrompt } from './codex-formatter.js';
+ *   const prompt = formatCodexPrompt({ projectRoot: '/path' });
+ *   // Append to system prompt
+ *
+ * @version 1.0.0
+ * @since 2026-03-28
+ */
+import { readFileSync, existsSync } from "fs";
+import { join, resolve } from "path";
+// ============================================================================
+// Built-in Fallback Codex (when no codex.json is found)
+// ============================================================================
+export const BUILTIN_CODEX = {
+    version: "fallback-1.0.0",
+    terms: [
+        {
+            id: "resolve-all-errors",
+            title: "Resolve All Errors",
+            description: "Never leave unhandled errors, rejected promises, or uncaught exceptions in production code. Every error path must have explicit handling or propagation.",
+            severity: "blocking",
+            examples: ["catch (err) { logger.error('Operation failed', err); throw err; }"],
+        },
+        {
+            id: "tests-required",
+            title: "Tests Required",
+            description: "Every new function, method, or module must have corresponding test coverage. Tests should validate both happy path and error cases.",
+            severity: "blocking",
+        },
+        {
+            id: "no-console-in-production",
+            title: "No Console in Production",
+            description: "Use structured logging instead of console.log, console.warn, or console.error. Console statements leak through to agent consoles and create noise.",
+            severity: "blocking",
+        },
+        {
+            id: "type-safety",
+            title: "Type Safety",
+            description: "Prefer explicit types over 'any'. Use TypeScript strict mode features. Validate external data at boundaries.",
+            severity: "high",
+        },
+        {
+            id: "input-validation",
+            title: "Input Validation",
+            description: "Validate all external inputs at the system boundary. Never trust client-side data, environment variables, or API responses without validation.",
+            severity: "high",
+        },
+        {
+            id: "immutable-state",
+            title: "Immutable State Updates",
+            description: "Prefer immutable patterns for state updates. Avoid mutating function parameters or shared state directly.",
+            severity: "high",
+        },
+        {
+            id: "error-boundaries",
+            title: "Error Boundaries",
+            description: "Wrap operations in try/catch with meaningful error messages. Include context about what failed and why.",
+            severity: "medium",
+        },
+        {
+            id: "dead-code-elimination",
+            title: "Dead Code Elimination",
+            description: "Remove unused imports, variables, functions, and commented-out code before committing.",
+            severity: "medium",
+        },
+    ],
+};
+// ============================================================================
+// Config Resolution
+// ============================================================================
+/**
+ * Find codex.json using the standard priority chain.
+ * Mirrors config-paths.ts resolveCodexPath() but returns first match.
+ */
+export function findCodexPath(projectRoot) {
+    const root = projectRoot || process.cwd();
+    const envDir = process.env.STRRAY_CONFIG_DIR;
+    const candidates = [];
+    if (envDir) {
+        candidates.push(resolve(root, envDir, "codex.json"));
+    }
+    candidates.push(join(root, ".strray", "codex.json"));
+    candidates.push(join(root, ".opencode", "strray", "codex.json"));
+    // Additional fallback locations (for standalone usage)
+    candidates.push(join(root, "codex.json"));
+    candidates.push(join(root, "src", "codex.json"));
+    candidates.push(join(root, "docs", "agents", "codex.json"));
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Load and parse codex.json. Falls back to built-in codex if not found.
+ */
+export function loadCodex(projectRoot) {
+    const codexPath = findCodexPath(projectRoot);
+    if (codexPath) {
+        try {
+            const raw = readFileSync(codexPath, "utf-8");
+            const config = JSON.parse(raw);
+            return { config, source: codexPath };
+        }
+        catch {
+            // Fall through to built-in
+        }
+    }
+    return { config: BUILTIN_CODEX, source: null };
+}
+// ============================================================================
+// Formatting
+// ============================================================================
+const SEVERITY_LABELS = {
+    blocking: "BLOCKING",
+    high: "HIGH PRIORITY",
+    medium: "MEDIUM",
+};
+const SEVERITY_EMOJI = {
+    blocking: "🔴",
+    high: "🟡",
+    medium: "🟢",
+};
+/**
+ * Format codex terms into a system-prompt-ready string.
+ *
+ * This is the primary export. Any host (OpenCode, Hermes, Claude Desktop,
+ * custom agent) can call this to get enforcement text for their system prompt.
+ */
+export function formatCodexPrompt(options = {}) {
+    const { projectRoot, severityFilter, includeExamples = false, maxTerms, header, includeConfigPath = true, compressed = false, } = options;
+    const { config, source } = loadCodex(projectRoot);
+    // Filter terms by severity
+    let terms = config.terms;
+    if (severityFilter && severityFilter.length > 0) {
+        terms = terms.filter((t) => severityFilter.includes(t.severity));
+    }
+    // Sort by severity (blocking first, then high, then medium)
+    const severityOrder = { blocking: 0, high: 1, medium: 2 };
+    terms = [...terms].sort((a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3));
+    // Limit term count
+    if (maxTerms && terms.length > maxTerms) {
+        terms = terms.slice(0, maxTerms);
+    }
+    // Build prompt sections
+    const parts = [];
+    // Header
+    if (header) {
+        parts.push(header);
+    }
+    else {
+        parts.push(`## 0xRay Universal Development Codex v${config.version}`);
+        parts.push("The following rules are enforced on all code operations. Violations will be caught by quality gates.");
+    }
+    // Terms
+    for (const term of terms) {
+        const emoji = SEVERITY_EMOJI[term.severity] || "⚪";
+        const label = SEVERITY_LABELS[term.severity] || term.severity.toUpperCase();
+        const line = `\n**${emoji} ${term.id}** [${label}]`;
+        parts.push(line);
+        // Always include description for blocking/high, skip for medium when compressed
+        if (term.description && !(compressed && term.severity === "medium")) {
+            parts.push(`  ${term.description}`);
+        }
+        if (includeExamples && term.examples && term.examples.length > 0) {
+            parts.push("  Examples:");
+            for (const example of term.examples) {
+                parts.push(`  \`${example}\``);
+            }
+        }
+    }
+    // Footer
+    if (includeConfigPath && source) {
+        parts.push(`\n_Config source: ${source}_`);
+    }
+    const prompt = parts.join("\n");
+    return {
+        prompt,
+        termCount: terms.length,
+        totalTerms: config.terms.length,
+        version: config.version,
+        configPath: source,
+        charCount: prompt.length,
+    };
+}
+/**
+ * Get codex as a structured JSON object (for programmatic consumers).
+ */
+export function getCodexConfig(options = {}) {
+    const { config, source } = loadCodex(options.projectRoot);
+    return {
+        version: config.version,
+        terms: config.terms,
+        termCount: config.terms.length,
+        source,
+    };
+}
+/**
+ * Get a minimal codex prompt for token-constrained environments.
+ * Only includes blocking terms, no descriptions.
+ */
+export function formatMinimalCodexPrompt(options = {}) {
+    return formatCodexPrompt({
+        ...options,
+        severityFilter: ["blocking"],
+        compressed: true,
+        includeConfigPath: false,
+    });
+}

package/dist/core/codex-injector.js

@@ -0,0 +1,424 @@
+/**
+ * 0xRay Codex Context Injector Hook
+ *
+ * Injects Universal Development Codex v1.2.0 context into agent operations.
+ * Follows production-tested pattern from rules-injector.
+ *
+ * @version 1.0.0
+ * @since 2026-01-06
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { frameworkLogger } from "../core/framework-logger.js";
+import { resolveCodexPath } from "./config-paths.js";
+// Dynamic imports for cross-environment compatibility
+let extractCodexMetadata;
+let StringRayContextLoader;
+let importsInitialized = false;
+async function initializeImports() {
+    if (importsInitialized)
+        return;
+    try {
+        const codexParser = await import("../utils/codex-parser.js");
+        const contextLoaderModule = await import("./context-loader.js");
+        extractCodexMetadata = codexParser.extractCodexMetadata;
+        StringRayContextLoader = contextLoaderModule.StringRayContextLoader;
+    }
+    catch {
+        const codexParser = await import("../utils/codex-parser");
+        const contextLoaderModule = await import("./context-loader");
+        extractCodexMetadata = codexParser.extractCodexMetadata;
+        StringRayContextLoader = contextLoaderModule.StringRayContextLoader;
+    }
+    importsInitialized = true;
+}
+/**
+ * Session cache for codex context
+ */
+const codexCache = new Map();
+/**
+ * Codex file locations resolved through the standard priority chain.
+ * Uses config-paths.ts resolver so STRRAY_CONFIG_DIR and .strray/ work.
+ */
+function getCodexFileLocations(projectRoot) {
+    const root = projectRoot || process.cwd();
+    return resolveCodexPath(root);
+}
+/**
+ * Read file content safely
+ */
+function readFileContent(filePath) {
+    try {
+        if (fs.existsSync(filePath)) {
+            return fs.readFileSync(filePath, "utf-8");
+        }
+    }
+    catch (error) {
+        frameworkLogger.log("codex-injector", "read-file-error", "error", { error, message: "0xRay Codex Hook Error" });
+    }
+    return null;
+}
+/**
+ * Create codex context entry
+ */
+async function createCodexContextEntry(filePath, content) {
+    await initializeImports();
+    if (!extractCodexMetadata) {
+        throw new Error("Codex metadata extractor not available");
+    }
+    const metadata = extractCodexMetadata(content);
+    return {
+        id: `strray-codex-${path.basename(filePath)}`,
+        source: filePath,
+        content,
+        priority: "critical",
+        metadata: {
+            version: metadata.version,
+            termCount: metadata.termCount,
+            loadedAt: new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Load codex context for current session
+ */
+async function loadCodexContext(sessionId) {
+    if (codexCache.has(sessionId)) {
+        return codexCache.get(sessionId);
+    }
+    const codexContexts = [];
+    const locations = getCodexFileLocations();
+    for (const relativePath of locations) {
+        try {
+            const fullPath = path.isAbsolute(relativePath) ? relativePath : path.join(process.cwd(), relativePath);
+            const content = readFileContent(fullPath);
+            if (content) {
+                const entry = await createCodexContextEntry(fullPath, content);
+                codexContexts.push(entry);
+            }
+        }
+        catch (error) {
+            frameworkLogger.log("codex-injector", "load-codex-context-error", "error", { error, message: "0xRay Codex Hook Error" });
+        }
+    }
+    codexCache.set(sessionId, codexContexts);
+    return codexContexts;
+}
+/**
+ * Format codex context for display
+ */
+function formatCodexContext(contexts, sessionId) {
+    if (contexts.length === 0) {
+        return "⚠️ No codex context available";
+    }
+    const parts = ["0xRay Codex Context"];
+    for (const context of contexts) {
+        parts.push(`✅ ${context.source} (${context.metadata.termCount} terms)`);
+    }
+    const stats = getCodexStats(sessionId);
+    parts.push(`📁 ${stats.fileCount} source(s)`);
+    parts.push(`🎯 90% runtime error prevention target`);
+    return parts.join("\n");
+}
+/**
+ * Create strray-codex-injector hook
+ *
+ * This hook injects codex context into tool outputs and displays
+ * a welcome message on agent startup, following the production-tested
+ * pattern from OpenCode's rules-injector.
+ */
+export function createStringRayCodexInjectorHook() {
+    return {
+        name: "strray-codex-injector",
+        hooks: {
+            "agent.start": async (sessionId) => {
+                const jobId = `agent-start-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+                try {
+                    await frameworkLogger.log("codex-injector", "agent.start hook triggered", "info", { jobId, sessionId });
+                    // Load codex context to ensure it's available for the session
+                    await loadCodexContext(sessionId);
+                    const stats = getCodexStats(sessionId);
+                    if (stats.loaded) {
+                        await frameworkLogger.log("codex-injector", "-stringray-codex-loaded-stats-totalterms-terms-sta", "success", {
+                            message: `✅ 0xRay Codex loaded: ${stats.totalTerms} terms, ${stats.fileCount} sources`,
+                        });
+                        await frameworkLogger.log("codex-injector", "codex context loaded successfully", "success", { jobId, ...stats });
+                    }
+                    else {
+                        await frameworkLogger.log("codex-injector", "-no-codex-files-found-checked-strray-codex-json-co", "info", {
+                            message: `⚠️  No codex files found. Checked: ${getCodexFileLocations().join(", ")}`,
+                        });
+                        await frameworkLogger.log("codex-injector", "no codex files found", "error", { jobId });
+                    }
+                }
+                catch (error) {
+                    await frameworkLogger.log("codex-injector", "agent.start hook failed", "error", { jobId, error });
+                    frameworkLogger.log("codex-injector", "agent-start-hook-error", "error", { error, jobId, message: "Error in agent.start hook" });
+                    throw error;
+                }
+            },
+            "tool.execute.before": async (input, sessionId) => {
+                const jobId = `tool-before-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+                try {
+                    await frameworkLogger.log("codex-injector", "tool.execute.before hook triggered", "info", { jobId, tool: input.tool, sessionId });
+                    // Log ALL tool usage for framework transparency
+                    await frameworkLogger.log("framework-activity", `tool called: ${input.tool}`, "info", {
+                        jobId,
+                        tool: input.tool,
+                        args: input.args,
+                        sessionId,
+                    });
+                    // Skip codex enforcement during testing
+                    if (process.env.NODE_ENV === "test" ||
+                        process.env.STRRAY_TEST_MODE === "true") {
+                        await frameworkLogger.log("codex-injector", "skipping enforcement in test mode", "info", { jobId });
+                        return;
+                    }
+                    // Only enforce on critical tools that could violate codex terms
+                    const criticalTools = ["write", "edit", "multiedit", "batch"];
+                    if (!criticalTools.includes(input.tool)) {
+                        await frameworkLogger.log("codex-injector", "non-critical tool allowed", "info", { jobId, tool: input.tool });
+                        return; // Allow non-critical tools
+                    }
+                    await frameworkLogger.log("codex-injector", "enforcing codex on critical tool", "info", { jobId, tool: input.tool });
+                    // Load codex context for validation
+                    const codexContexts = await loadCodexContext(sessionId);
+                    if (codexContexts.length === 0) {
+                        await frameworkLogger.log("codex-injector", "-no-codex-loaded-allowing-action-but-enforcement-d", "info", {
+                            message: "⚠️  No codex loaded - allowing action but enforcement disabled",
+                        });
+                        await frameworkLogger.log("codex-injector", "no codex context available", "error", { jobId, sessionId });
+                        return;
+                    }
+                    await frameworkLogger.log("codex-injector", "codex context loaded for validation", "success", { jobId, contextCount: codexContexts.length });
+                    // Use the initialized context loader
+                    await initializeImports();
+                    const ContextLoaderClass = StringRayContextLoader;
+                    const contextLoader = new ContextLoaderClass();
+                    const loadResult = await contextLoader.loadCodexContext(sessionId);
+                    if (!loadResult.success || !loadResult.context) {
+                        // Codex context warning - operational, keep
+                        return;
+                    }
+                    // Validate action against codex
+                    const actionDescription = `${input.tool} ${JSON.stringify(input.args || {})}`;
+                    const validation = contextLoader.validateAgainstCodex(loadResult.context, actionDescription, {
+                        strictMode: true,
+                        blockOnViolations: true,
+                    });
+                    if (!validation.compliant) {
+                        // Check for blocking violations
+                        const blockingViolations = validation.violations.filter((v) => v.severity === "blocking");
+                        if (blockingViolations.length > 0) {
+                            const errorMsg = `🚫 BLOCKED: Codex violation detected\n${blockingViolations.map((v) => `• ${v.reason}`).join("\n")}`;
+                            frameworkLogger.log("codex-injector", "blocking-violation", "error", { message: errorMsg, jobId });
+                            frameworkLogger.log("codex-injector", "blocking codex violation detected", "error", {
+                                jobId,
+                                violationCount: blockingViolations.length,
+                                tool: input.tool,
+                            });
+                            throw new Error(`Codex enforcement blocked action: ${blockingViolations[0]?.reason || "Unknown violation"}`);
+                        }
+                        // Log non-blocking violations but allow action
+                        await frameworkLogger.log("codex-injector", "-codex-warnings-detected-", "info", { message: `⚠️  Codex warnings detected:` });
+                        for (const v of validation.violations) {
+                            await frameworkLogger.log("codex-injector", "-v-reason-", "info", { message: `   • ${v.reason}` });
+                        }
+                        await frameworkLogger.log("codex-injector", "-recommendations-validation-recommendations-join-", "info", {
+                            message: `💡 Recommendations: ${validation.recommendations.join(", ")}`,
+                        });
+                        frameworkLogger.log("codex-injector", "non-blocking codex warnings", "info", {
+                            jobId,
+                            warningCount: validation.violations.length,
+                            tool: input.tool,
+                        });
+                    }
+                    else {
+                        frameworkLogger.log("codex-injector", "codex validation passed", "success", { jobId, tool: input.tool });
+                    }
+                }
+                catch (error) {
+                    frameworkLogger.log("codex-injector", "tool.execute.before hook error", "error", {
+                        jobId,
+                        error: error instanceof Error ? error.message : String(error),
+                        tool: input.tool,
+                    });
+                    frameworkLogger.log("codex-injector", "tool-execute-before-hook-error", "error", {
+                        error,
+                        message: "Error in tool.execute.before hook",
+                        jobId,
+                        tool: input.tool,
+                    });
+                    // For blocking violations, re-throw to prevent action
+                    if (error instanceof Error &&
+                        error.message.includes("Codex enforcement blocked action")) {
+                        throw error;
+                    }
+                    // For other errors, log but allow action to prevent breaking workflow
+                }
+            },
+            "tool.execute.after": async (input, output, sessionId) => {
+                const jobId = `tool-after-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+                try {
+                    frameworkLogger.log("codex-injector", "tool.execute.after hook triggered", "info", { jobId, tool: input.tool, sessionId });
+                    // Skip codex enforcement during testing
+                    if (process.env.NODE_ENV === "test" ||
+                        process.env.STRRAY_TEST_MODE === "true") {
+                        frameworkLogger.log("codex-injector", "skipping injection in test mode", "info", { jobId });
+                        return output;
+                    }
+                    if (!["read", "write", "edit", "multiedit", "batch"].includes(input.tool)) {
+                        frameworkLogger.log("codex-injector", "non-critical tool - no injection", "info", { jobId, tool: input.tool });
+                        return output;
+                    }
+                    await frameworkLogger.log("codex-injector", "-stringray-tool-execution-hook-triggered-for-input", "info", {
+                        message: `🔧 0xRay: Tool execution hook triggered for ${input.tool}`,
+                    });
+                    const codexContexts = await loadCodexContext(sessionId);
+                    await frameworkLogger.log("codex-injector", "-stringray-loaded-codexcontexts-length-codex-conte", "info", {
+                        message: `📚 0xRay: Loaded ${codexContexts.length} codex contexts`,
+                    });
+                    frameworkLogger.log("codex-injector", "codex contexts loaded for injection", "success", {
+                        jobId,
+                        contextCount: codexContexts.length,
+                        tool: input.tool,
+                    });
+                    if (codexContexts.length === 0) {
+                        return output;
+                    }
+                    const formattedCodex = formatCodexContext(codexContexts, sessionId);
+                    const injectedOutput = {
+                        ...output,
+                        output: `${formattedCodex}\n${output.output || ""}`,
+                    };
+                    frameworkLogger.log("codex-injector", "codex context injected into output", "success", {
+                        jobId,
+                        tool: input.tool,
+                        outputLength: injectedOutput.output?.length,
+                    });
+                    return injectedOutput;
+                }
+                catch (error) {
+                    frameworkLogger.log("codex-injector", "tool.execute.after hook error", "error", {
+                        jobId,
+                        error: error instanceof Error ? error.message : String(error),
+                        tool: input.tool,
+                    });
+                    frameworkLogger.log("codex-injector", "tool-execute-after-hook-error", "error", {
+                        error,
+                        message: "Error in tool.execute.after hook",
+                        jobId,
+                        tool: input.tool,
+                    });
+                    // Return original output on error to not break the session
+                    return output;
+                }
+            },
+        },
+    };
+}
+/**
+ * Get codex statistics for debugging
+ */
+export function getCodexStats(sessionId) {
+    const contexts = codexCache.get(sessionId);
+    if (!contexts || contexts.length === 0) {
+        return {
+            loaded: false,
+            fileCount: 0,
+            totalTerms: 0,
+            version: "unknown",
+        };
+    }
+    const totalTerms = contexts.reduce((sum, ctx) => sum + ctx.metadata.termCount, 0);
+    return {
+        loaded: true,
+        fileCount: contexts.length,
+        totalTerms,
+        version: contexts[0].metadata.version,
+    };
+}
+/**
+ * Clear codex cache (useful for testing or forced reload)
+ */
+export function clearCodexCache(sessionId) {
+    if (sessionId) {
+        codexCache.delete(sessionId);
+    }
+    else {
+        codexCache.clear();
+    }
+}
+/**
+ * CodexInjector class for plugin compatibility
+ */
+export class CodexInjector {
+    injectCodexRules(context, options) {
+        // Implementation for plugin compatibility
+        return context;
+    }
+    getCodexStats() {
+        // Return aggregated stats for plugin
+        const allContexts = [];
+        for (const contexts of Array.from(codexCache.values())) {
+            allContexts.push(...contexts);
+        }
+        const totalTerms = allContexts.reduce((sum, ctx) => sum + ctx.metadata.termCount, 0);
+        return {
+            loaded: allContexts.length > 0,
+            fileCount: allContexts.length,
+            totalTerms,
+            version: allContexts.length > 0 ? allContexts[0].metadata.version : "unknown",
+        };
+    }
+    /**
+     * Permissive comment validation - recognizes that comments are beneficial
+     * Only flags truly problematic patterns, provides guidance not requirements
+     */
+    validateCommentsPermissively(content) {
+        const guidance = [];
+        const concerns = [];
+        const lines = content.split("\n");
+        let commentLines = 0;
+        let codeLines = 0;
+        let todoCount = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Skip empty lines
+            if (!trimmed)
+                continue;
+            // Count code vs comments
+            if (trimmed.startsWith("//") ||
+                trimmed.startsWith("/*") ||
+                trimmed.startsWith("*") ||
+                trimmed.startsWith("*/")) {
+                commentLines++;
+            }
+            else {
+                codeLines++;
+            }
+            // Check for problematic patterns
+            if (trimmed.includes("TODO") ||
+                trimmed.includes("FIXME") ||
+                trimmed.includes("XXX")) {
+                todoCount++;
+            }
+        }
+        // Provide helpful guidance (not requirements)
+        const commentRatio = commentLines / (commentLines + codeLines);
+        if (commentLines === 0 && codeLines > 30) {
+            guidance.push("💡 Consider adding comments for complex logic - they improve maintainability");
+        }
+        if (commentRatio > 0.4) {
+            guidance.push("💡 High comment ratio detected - consider if code can be made more self-explanatory");
+        }
+        if (todoCount > 3) {
+            concerns.push("⚠️ Multiple unresolved tasks detected - consider addressing or documenting timelines");
+        }
+        // Recognize good commenting practices
+        if (commentRatio > 0.1 && commentRatio < 0.3) {
+            guidance.push("✅ Good balance of code and comments detected");
+        }
+        return { guidance, concerns };
+    }
+}