0xray 4.0.12 → 4.0.13

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

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,169 +0,0 @@
-/**
- * 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

@@ -1,120 +0,0 @@
-/**
- * 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

@@ -1,268 +0,0 @@
-/**
- * 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

@@ -1,52 +0,0 @@
-/**
- * 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;
-};