0xray 4.0.13 → 4.0.15

package/dist/core/config-paths.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Config Path Resolver
+ *
+ * Centralizes all 0xRay config file path resolution.
+ * Supports XRAY_CONFIG_DIR env var for custom config roots.
+ *
+ * Resolution order (per file type):
+ *   1. XRAY_CONFIG_DIR/<relative_path>     (if env var set)
+ *   2. .xray/<relative_path>                 (preferred lightweight root)
+ *   3. null                                   (callers fall back to built-in defaults)
+ *
+ * For state/data directories, uses:
+ *   1. XRAY_CONFIG_DIR/state                 (if env var set)
+ *   2. .xray/state
+ *   3. .opencode/state                         (legacy)
+ *   4. .xray/state                              (default — always writable)
+ */
+/** Environment variable name for custom config root */
+export declare const XRAY_CONFIG_DIR_ENV = "XRAY_CONFIG_DIR";
+/**
+ * Detect the best available config directory.
+ * Scans in priority order and caches the first one that exists (or the first default).
+ */
+export declare function getConfigDir(projectRoot?: string): string;
+/**
+ * Resolve a specific config file path using the standard priority chain.
+ * Returns null if no suitable path is found (caller should use defaults).
+ *
+ * @param relativePath - Path relative to config dir (e.g., "features.json")
+ * @param projectRoot  - Optional project root override
+ */
+export declare function resolveConfigPath(relativePath: string, projectRoot?: string): string | null;
+/**
+ * Get the state persistence directory (the parent directory for state.json).
+ * Similar logic to resolveConfigPath but for the state/ subdirectory.
+ */
+export declare function resolveStateDir(projectRoot?: string): string;
+/**
+ * Get the state persistence FILE path (e.g. .opencode/state/state.json).
+ * Prefer this over resolveStateDir when you need a file path for fs.writeFileSync.
+ */
+export declare function resolveStateFilePath(projectRoot?: string): string;
+/**
+ * Get the profiles storage directory.
+ */
+export declare function resolveProfilesDir(projectRoot?: string): string;
+/**
+ * Resolve codex.json path.
+ * Has additional fallback locations beyond the standard config dir.
+ */
+/** Environment variable for explicit project root override */
+export declare const XRAY_ROOT_ENV = "XRAY_ROOT";
+/**
+ * Resolve project root using XRAY_ROOT env var if set,
+ * otherwise fall back to projectRoot param or cwd.
+ */
+export declare function resolveProjectRoot(projectRoot?: string): string;
+export declare function resolveCodexPath(projectRoot?: string): string[];
+/**
+ * Get the logs directory for framework logging.
+ */
+export declare function resolveLogDir(projectRoot?: string): string;
+/**
+ * Reset the cached config dir (useful for testing).
+ */
+export declare function resetConfigDirCache(): void;

package/dist/core/config-paths.js

@@ -0,0 +1,169 @@
+/**
+ * Config Path Resolver
+ *
+ * Centralizes all 0xRay config file path resolution.
+ * Supports XRAY_CONFIG_DIR env var for custom config roots.
+ *
+ * Resolution order (per file type):
+ *   1. XRAY_CONFIG_DIR/<relative_path>     (if env var set)
+ *   2. .xray/<relative_path>                 (preferred lightweight root)
+ *   3. null                                   (callers fall back to built-in defaults)
+ *
+ * For state/data directories, uses:
+ *   1. XRAY_CONFIG_DIR/state                 (if env var set)
+ *   2. .xray/state
+ *   3. .opencode/state                         (legacy)
+ *   4. .xray/state                              (default — always writable)
+ */
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+/** Environment variable name for custom config root */
+export const XRAY_CONFIG_DIR_ENV = "XRAY_CONFIG_DIR";
+/** Resolved config directories, cached per projectRoot */
+const _resolvedConfigDirs = new Map();
+/**
+ * Detect the best available config directory.
+ * Scans in priority order and caches the first one that exists (or the first default).
+ */
+export function getConfigDir(projectRoot) {
+    const root = resolveRoot(projectRoot);
+    const cached = _resolvedConfigDirs.get(root);
+    if (cached)
+        return cached;
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+    // Priority candidates
+    const candidates = [];
+    if (envDir) {
+        // Explicit env override — always use this even if it doesn't exist yet
+        const resolved = resolve(root, envDir);
+        candidates.push({ dir: resolved, source: "env" });
+    }
+    candidates.push({ dir: join(root, ".xray"), source: "dot-xray" });
+    // Return the first that exists, or the highest-priority default
+    for (const c of candidates) {
+        if (existsSync(c.dir)) {
+            _resolvedConfigDirs.set(root, c.dir);
+            return c.dir;
+        }
+    }
+    // Nothing exists — use highest priority default (env > .xray)
+    const defaultDir = candidates[0];
+    _resolvedConfigDirs.set(root, defaultDir.dir);
+    return defaultDir.dir;
+}
+/**
+ * Resolve a specific config file path using the standard priority chain.
+ * Returns null if no suitable path is found (caller should use defaults).
+ *
+ * @param relativePath - Path relative to config dir (e.g., "features.json")
+ * @param projectRoot  - Optional project root override
+ */
+export function resolveConfigPath(relativePath, projectRoot) {
+    const root = resolveRoot(projectRoot);
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+    const candidates = [];
+    if (envDir) {
+        candidates.push(resolve(root, envDir, relativePath));
+    }
+    candidates.push(join(root, ".xray", relativePath));
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    // Return highest-priority default path even if it doesn't exist
+    // (callers will handle missing file gracefully)
+    return candidates[0] ?? null;
+}
+/**
+ * Get the state persistence directory (the parent directory for state.json).
+ * Similar logic to resolveConfigPath but for the state/ subdirectory.
+ */
+export function resolveStateDir(projectRoot) {
+    const root = resolveRoot(projectRoot);
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+    const candidates = [];
+    if (envDir) {
+        candidates.push(join(root, envDir, "state"));
+    }
+    candidates.push(join(root, ".xray", "state"));
+    candidates.push(join(root, ".opencode", "state"));
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    // Default: use highest-priority path (will be auto-created by StateManager)
+    return candidates[0];
+}
+/**
+ * Get the state persistence FILE path (e.g. .opencode/state/state.json).
+ * Prefer this over resolveStateDir when you need a file path for fs.writeFileSync.
+ */
+export function resolveStateFilePath(projectRoot) {
+    return join(resolveStateDir(projectRoot), "state.json");
+}
+/**
+ * Get the profiles storage directory.
+ */
+export function resolveProfilesDir(projectRoot) {
+    const root = resolveRoot(projectRoot);
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+    const candidates = [];
+    if (envDir) {
+        candidates.push(join(root, envDir, "profiles"));
+    }
+    candidates.push(join(root, ".xray", "profiles"));
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+/**
+ * Resolve codex.json path.
+ * Has additional fallback locations beyond the standard config dir.
+ */
+/** Environment variable for explicit project root override */
+export const XRAY_ROOT_ENV = "XRAY_ROOT";
+/**
+ * Resolve project root using XRAY_ROOT env var if set,
+ * otherwise fall back to projectRoot param or cwd.
+ */
+export function resolveProjectRoot(projectRoot) {
+    return process.env[XRAY_ROOT_ENV] || projectRoot || process.cwd();
+}
+/** @deprecated Use resolveProjectRoot — kept for internal consistency */
+function resolveRoot(projectRoot) {
+    return resolveProjectRoot(projectRoot);
+}
+export function resolveCodexPath(projectRoot) {
+    const root = resolveRoot(projectRoot);
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+    const candidates = [];
+    if (envDir) {
+        candidates.push(join(root, envDir, "codex.json"));
+    }
+    candidates.push(join(root, ".xray", "codex.json"));
+    candidates.push(join(root, "xray", "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"));
+    return candidates;
+}
+/**
+ * Get the logs directory for framework logging.
+ */
+export function resolveLogDir(projectRoot) {
+    const root = resolveRoot(projectRoot);
+    // Logs always go to logs/framework/ regardless of config dir
+    return join(root, "logs", "framework");
+}
+/**
+ * Reset the cached config dir (useful for testing).
+ */
+export function resetConfigDirCache() {
+    _resolvedConfigDirs.clear();
+}

package/dist/core/context-loader.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 0xRay Context Loader
+ *
+ * Loads Universal Development Codex v1.2.0 context for agent initialization.
+ * Provides structured access to 30+ codex terms, interweaves, lenses, and anti-patterns.
+ *
+ * @since 2026-01-06
+ */
+/**
+ * Codex term structure
+ */
+export interface CodexTerm {
+    number: number;
+    description: string;
+    category: "core" | "extended" | "architecture" | "advanced";
+    zeroTolerance?: boolean;
+    enforcementLevel?: "low" | "medium" | "high" | "blocking";
+}
+/**
+ * Parsed codex context
+ */
+export interface CodexContext {
+    version: string;
+    lastUpdated: string;
+    terms: Map<number, CodexTerm>;
+    interweaves: string[];
+    lenses: string[];
+    principles: string[];
+    antiPatterns: string[];
+    validationCriteria: Record<string, boolean>;
+    frameworkAlignment: Record<string, string>;
+    errorPreventionTarget: number;
+}
+/**
+ * Context loading result
+ */
+export interface ContextLoadResult {
+    success: boolean;
+    context?: CodexContext;
+    error?: string;
+    warnings: string[];
+}
+/**
+ * 0xRay Context Loader
+ *
+ * Loads and parses the Universal Development Codex v1.2.0 from codex.json
+ */
+export declare class XrayContextLoader {
+    private static instance;
+    private cachedContext;
+    private codexFilePaths;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): XrayContextLoader;
+    /**
+     * Load codex context
+     *
+     * Attempts to load the Universal Development Codex from multiple possible locations.
+     * Returns cached context if available and not expired.
+     */
+    loadCodexContext(projectRoot: string): Promise<ContextLoadResult>;
+    /**
+     * Parse codex content from JSON or Markdown
+     *
+     * Extracts all 30+ codex terms, interweaves, lenses, and principles from content.
+     * Supports both JSON and Markdown formats with explicit format detection.
+     */
+    private parseCodexContent;
+    private inferTermCategory;
+    /**
+     * Get specific codex term by number
+     */
+    getTerm(context: CodexContext, termNumber: number): CodexTerm | undefined;
+    /**
+     * Get all core terms (1-10)
+     */
+    getCoreTerms(context: CodexContext): CodexTerm[];
+    /**
+     * Get zero-tolerance terms that require immediate blocking
+     */
+    getZeroToleranceTerms(context: CodexContext): CodexTerm[];
+    /**
+     * Validate action against codex
+     *
+     * Checks if an action complies with relevant codex terms.
+     * Returns validation result with violations and recommendations.
+     */
+    validateAgainstCodex(context: CodexContext, action: string, actionDetails: Record<string, unknown>): {
+        compliant: boolean;
+        violations: Array<{
+            term: CodexTerm;
+            reason: string;
+            severity: "low" | "medium" | "high" | "blocking";
+        }>;
+        recommendations: string[];
+    };
+    /**
+     * Clear cached context (useful for testing or forced reload)
+     */
+    clearCache(): void;
+    /**
+     * Check if context is loaded and valid
+     */
+    isContextLoaded(): boolean;
+    /**
+     * Get context statistics
+     */
+    getContextStats(): {
+        loaded: boolean;
+        termCount: number;
+        categoryBreakdown: Record<string, number>;
+        zeroToleranceCount: number;
+    };
+}
+/**
+ * Export singleton instance
+ */
+export declare const xrayContextLoader: XrayContextLoader;

package/dist/core/context-loader.js

@@ -0,0 +1,268 @@
+/**
+ * 0xRay Context Loader
+ *
+ * Loads Universal Development Codex v1.2.0 context for agent initialization.
+ * Provides structured access to 30+ codex terms, interweaves, lenses, and anti-patterns.
+ *
+ * @since 2026-01-06
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { parseCodexContent, detectContentFormat, } from "../utils/codex-parser.js";
+import { resolveCodexPath } from "./config-paths.js";
+/**
+ * Type guard for regex match results
+ */
+function isValidMatch(match, index) {
+    return match !== null && match[index] !== undefined;
+}
+/**
+ * 0xRay Context Loader
+ *
+ * Loads and parses the Universal Development Codex v1.2.0 from codex.json
+ */
+export class XrayContextLoader {
+    static instance;
+    cachedContext = null;
+    codexFilePaths = [];
+    constructor() {
+        this.codexFilePaths = resolveCodexPath();
+    }
+    /**
+     * Get singleton instance
+     */
+    static getInstance() {
+        if (!XrayContextLoader.instance) {
+            XrayContextLoader.instance = new XrayContextLoader();
+        }
+        return XrayContextLoader.instance;
+    }
+    /**
+     * Load codex context
+     *
+     * Attempts to load the Universal Development Codex from multiple possible locations.
+     * Returns cached context if available and not expired.
+     */
+    async loadCodexContext(projectRoot) {
+        const warnings = [];
+        // Validate project root
+        if (!projectRoot || projectRoot.trim() === "") {
+            return {
+                success: false,
+                error: "Invalid project root path: path cannot be empty",
+                warnings,
+            };
+        }
+        if (this.cachedContext) {
+            return {
+                success: true,
+                context: this.cachedContext,
+                warnings,
+            };
+        }
+        for (const relativePath of this.codexFilePaths) {
+            const fullPath = path.join(projectRoot, relativePath);
+            if (fs.existsSync(fullPath)) {
+                try {
+                    const content = fs.readFileSync(fullPath, "utf-8");
+                    const context = this.parseCodexContent(content, fullPath);
+                    this.cachedContext = context;
+                    return {
+                        success: true,
+                        context,
+                        warnings,
+                    };
+                }
+                catch (error) {
+                    const msg = `Failed to parse ${fullPath}: ${error instanceof Error ? error.message : String(error)}`;
+                    warnings.push(msg);
+                }
+            }
+        }
+        return {
+            success: false,
+            error: "No valid codex file found. Checked: " + this.codexFilePaths.join(", "),
+            warnings,
+        };
+    }
+    /**
+     * Parse codex content from JSON or Markdown
+     *
+     * Extracts all 30+ codex terms, interweaves, lenses, and principles from content.
+     * Supports both JSON and Markdown formats with explicit format detection.
+     */
+    parseCodexContent(content, sourcePath) {
+        // Validate inputs before format detection
+        if (!content || content.trim() === "") {
+            throw new Error("Invalid content provided");
+        }
+        if (!sourcePath || sourcePath.trim() === "") {
+            throw new Error("Invalid source path provided");
+        }
+        // Detect format before parsing
+        const formatResult = detectContentFormat(content);
+        if (formatResult.format === "unknown") {
+            throw new Error(`Unable to detect content format for ${sourcePath}. Content appears to be neither valid JSON nor Markdown.`);
+        }
+        const result = parseCodexContent(content, sourcePath);
+        if (!result.success) {
+            throw new Error(result.error || "Failed to parse codex content");
+        }
+        if (!result.context) {
+            throw new Error("Parsing succeeded but no context was returned");
+        }
+        return result.context;
+    }
+    inferTermCategory(termNumber, termName) {
+        if (termNumber <= 10) {
+            return "core";
+        }
+        else if (termNumber <= 20) {
+            return "extended";
+        }
+        else if (termNumber <= 30) {
+            return "architecture";
+        }
+        else {
+            return "advanced";
+        }
+    }
+    /**
+     * Get specific codex term by number
+     */
+    getTerm(context, termNumber) {
+        return context.terms.get(termNumber);
+    }
+    /**
+     * Get all core terms (1-10)
+     */
+    getCoreTerms(context) {
+        return Array.from(context.terms.values())
+            .filter((term) => term.category === "core")
+            .sort((a, b) => a.number - b.number);
+    }
+    /**
+     * Get zero-tolerance terms that require immediate blocking
+     */
+    getZeroToleranceTerms(context) {
+        return Array.from(context.terms.values())
+            .filter((term) => term.zeroTolerance || term.enforcementLevel === "blocking")
+            .sort((a, b) => a.number - b.number);
+    }
+    /**
+     * Validate action against codex
+     *
+     * Checks if an action complies with relevant codex terms.
+     * Returns validation result with violations and recommendations.
+     */
+    validateAgainstCodex(context, action, actionDetails) {
+        // Input validation
+        if (!context || !context.terms) {
+            throw new Error("Invalid codex context provided");
+        }
+        if (!action || action.trim() === "") {
+            throw new Error("Invalid action provided");
+        }
+        const violations = [];
+        const recommendations = [];
+        const dangerousPatterns = ["any", "@ts-ignore", "@ts-expect-error"];
+        if (dangerousPatterns.some((pattern) => action.includes(pattern))) {
+            const term11 = context.terms.get(11);
+            if (term11) {
+                violations.push({
+                    term: term11,
+                    reason: 'Type safety violation detected - using "any" or type suppression',
+                    severity: term11.enforcementLevel || "high",
+                });
+            }
+        }
+        // Check for unresolved tasks in code
+        const codeContent = typeof actionDetails.code === "string" ? actionDetails.code : "";
+        if (codeContent.includes("TODO") ||
+            codeContent.includes("FIXME") ||
+            codeContent.includes("XXX") ||
+            action.includes("TODO") ||
+            action.includes("FIXME") ||
+            action.includes("XXX")) {
+            const term7 = context.terms.get(7);
+            if (term7) {
+                violations.push({
+                    term: term7,
+                    reason: "Unresolved tasks detected - violates Resolve All Errors principle",
+                    severity: "blocking",
+                });
+            }
+        }
+        if (actionDetails.isOverEngineered) {
+            const term3 = context.terms.get(3);
+            if (term3) {
+                violations.push({
+                    term: term3,
+                    reason: "Solution appears over-engineered - violates simplicity principle",
+                    severity: term3.enforcementLevel || "medium",
+                });
+                recommendations.push("Simplify the solution by removing unnecessary abstractions");
+            }
+        }
+        if (actionDetails.isInfiniteLoop ||
+            action.includes("while(true)") ||
+            action.includes("for(;;)")) {
+            const term8 = context.terms.get(8);
+            if (term8) {
+                violations.push({
+                    term: term8,
+                    reason: "Infinite loop detected - violates termination principle",
+                    severity: term8.enforcementLevel || "blocking",
+                });
+                recommendations.push("Add clear termination conditions to prevent infinite loops");
+            }
+        }
+        return {
+            compliant: violations.length === 0,
+            violations,
+            recommendations,
+        };
+    }
+    /**
+     * Clear cached context (useful for testing or forced reload)
+     */
+    clearCache() {
+        this.cachedContext = null;
+    }
+    /**
+     * Check if context is loaded and valid
+     */
+    isContextLoaded() {
+        return this.cachedContext !== null;
+    }
+    /**
+     * Get context statistics
+     */
+    getContextStats() {
+        if (!this.cachedContext) {
+            return {
+                loaded: false,
+                termCount: 0,
+                categoryBreakdown: {},
+                zeroToleranceCount: 0,
+            };
+        }
+        const context = this.cachedContext;
+        const terms = Array.from(context.terms.values());
+        const categoryBreakdown = {};
+        terms.forEach((term) => {
+            categoryBreakdown[term.category] =
+                (categoryBreakdown[term.category] || 0) + 1;
+        });
+        return {
+            loaded: true,
+            termCount: context.terms.size,
+            categoryBreakdown,
+            zeroToleranceCount: this.getZeroToleranceTerms(context).length,
+        };
+    }
+}
+/**
+ * Export singleton instance
+ */
+export const xrayContextLoader = XrayContextLoader.getInstance();

package/dist/core/context-validator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 0xRay Context Size Validator
+ *
+ * Prevents system prompt bloat by validating and rejecting context-injection attempts
+ * that would exceed token budgets.
+ *
+ * @since 2026-03-03
+ */
+/**
+ * Context size configuration
+ */
+export interface ContextSizeConfig {
+    maxSystemPromptLength: number;
+    maxCodexContextLength: number;
+    maxTotalPromptLength: number;
+    enableCompression: boolean;
+    preventDuplicateContent: boolean;
+}
+/**
+ * Context validation result
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    sizeInTokens: number;
+    exceedsBudget: boolean;
+    warnings: string[];
+    compressionApplied: boolean;
+    optimizedContent?: string;
+}
+/**
+ * Validate context size and detect bloat
+ */
+export declare function validateContext(context: string, config?: Partial<ContextSizeConfig>): ValidationResult;
+/**
+ * Validate context collection (multiple contexts combined)
+ */
+export declare function validateContextCollection(contexts: string[], config?: Partial<ContextSizeConfig>): ValidationResult;
+/**
+ * Prevent system prompt bloat middleware
+ */
+export declare function preventSystemPromptBloat(context: string, onWarning?: (warning: string) => void): string;
+/**
+ * Utility function to check if a prompt is likely to cause overflow
+ */
+export declare function isPromptLikelyToOverflow(prompt: string): boolean;
+/**
+ * Generate a safe system prompt template
+ */
+export declare function generateSafeSystemPrompt(baseTemplate: string, additionalContext: string, maxTokens?: number): {
+    prompt: string;
+    safe: boolean;
+};