0xray 3.4.1 → 3.4.3

package/dist/core/codex-injector.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 0xRay Codex Context Injector Hook
+ *
+ * Injects Universal Development Codex v1.2.0 context into agent operations.
+ * Follows production-tested pattern from rules-injector.
+ *
+ * @since 2026-01-06
+ */
+/**
+ * Create xray-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 declare function createXrayCodexInjectorHook(): {
+    name: "xray-codex-injector";
+    hooks: {
+        "agent.start": (sessionId: string) => Promise<void>;
+        "tool.execute.before": (input: {
+            tool: string;
+            args?: Record<string, unknown>;
+        }, sessionId: string) => Promise<void>;
+        "tool.execute.after": (input: {
+            tool: string;
+            args?: Record<string, unknown>;
+        }, output: {
+            output?: string;
+            [key: string]: unknown;
+        }, sessionId: string) => Promise<{
+            [key: string]: unknown;
+            output?: string;
+        } | {
+            output: string;
+        }>;
+    };
+};
+/**
+ * Get codex statistics for debugging
+ */
+export declare function getCodexStats(sessionId: string): {
+    loaded: boolean;
+    fileCount: number;
+    totalTerms: number;
+    version: string;
+};
+/**
+ * Clear codex cache (useful for testing or forced reload)
+ */
+export declare function clearCodexCache(sessionId?: string): void;
+/**
+ * CodexInjector class for plugin compatibility
+ */
+export declare class CodexInjector {
+    injectCodexRules(context: Record<string, unknown>, options: {
+        priority?: string;
+        mergeStrategy?: string;
+    }): Record<string, unknown>;
+    getCodexStats(): {
+        loaded: boolean;
+        fileCount: number;
+        totalTerms: number;
+        version: string;
+    };
+    /**
+     * Permissive comment validation - recognizes that comments are beneficial
+     * Only flags truly problematic patterns, provides guidance not requirements
+     */
+    validateCommentsPermissively(content: string): {
+        guidance: string[];
+        concerns: string[];
+    };
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Configuration Loader (backward-compat shim)
+ *
+ * Delegates to FeaturesConfigLoader as the single source of truth.
+ * Retained for backward compatibility -- all consumers of xrayConfigLoader
+ * continue to work without changes.
+ *
+ * @deprecated Use featuresConfigLoader from "./features-config.js" instead.
+ * Will be removed in v4.0.0.
+ */
+export type { MultiAgentOrchestrationConfig, AutonomousReportingConfig } from "./features-config.js";
+export interface XrayConfig {
+    multi_agent_orchestration: import("./features-config.js").MultiAgentOrchestrationConfig;
+    autonomous_reporting: import("./features-config.js").AutonomousReportingConfig;
+    disabled_agents: string[];
+}
+export declare class XrayConfigLoader {
+    private configPath;
+    private cachedConfig;
+    private cacheExpiry;
+    private lastLoadTime;
+    constructor(configPath?: string);
+    /**
+     * Load configuration -- delegates to FeaturesConfigLoader
+     * @deprecated Use featuresConfigLoader.getXrayConfig() instead.
+     */
+    loadConfig(): XrayConfig;
+    /**
+     * Parse configuration data with validation
+     * @deprecated Use featuresConfigLoader.loadConfig() instead.
+     */
+    private parseConfig;
+    /**
+     * Parse multi-agent orchestration configuration
+     * @deprecated Use featuresConfigLoader.loadConfig().multi_agent_orchestration instead.
+     */
+    private parseMultiAgentConfig;
+    /**
+     * Parse autonomous reporting configuration
+     * @deprecated Use featuresConfigLoader.loadConfig().autonomous_reporting instead.
+     */
+    private parseAutonomousReportingConfig;
+    /**
+     * Get default configuration
+     * @deprecated Use featuresConfigLoader.getDefaultConfig() instead.
+     */
+    private getDefaultConfig;
+    /**
+     * Validate enum values
+     * @deprecated Internal implementation detail.
+     */
+    private validateEnum;
+    /**
+     * Clear configuration cache
+     * @deprecated Use featuresConfigLoader.clearCache() instead.
+     */
+    clearCache(): void;
+}
+export declare const xrayConfigLoader: XrayConfigLoader;

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/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-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;
+};