0xray 2.0.0 → 2.1.0

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

@@ -0,0 +1,71 @@
+/**
+ * Configuration Loader
+ *
+ * Loads and validates 0xRay-specific configuration from opencode.json
+ *
+ * @version 1.0.0
+ * @since 2026-01-09
+ */
+export interface MultiAgentOrchestrationConfig {
+    enabled: boolean;
+    coordination_model: "async-multi-agent" | "sync-multi-agent";
+    max_concurrent_agents: number;
+    task_distribution_strategy: "capability-based" | "load-balanced" | "round-robin";
+    conflict_resolution: "expert-priority" | "majority-vote" | "consensus";
+    progress_tracking: boolean;
+    session_persistence: boolean;
+}
+export interface AutonomousReportingConfig {
+    enabled: boolean;
+    interval_minutes: number;
+    auto_schedule: boolean;
+    include_health_assessment: boolean;
+    include_agent_activities: boolean;
+    include_pipeline_operations: boolean;
+    include_critical_issues: boolean;
+    include_recommendations: boolean;
+    report_retention_days: number;
+    notification_channels: string[];
+}
+export interface XrayConfig {
+    multi_agent_orchestration: MultiAgentOrchestrationConfig;
+    autonomous_reporting: AutonomousReportingConfig;
+    disabled_agents: string[];
+}
+export declare class XrayConfigLoader {
+    private configPath;
+    private cachedConfig;
+    private cacheExpiry;
+    private lastLoadTime;
+    constructor(configPath?: string);
+    /**
+     * Load 0xRay configuration from the resolved config directory
+     */
+    loadConfig(): XrayConfig;
+    /**
+     * Parse configuration data with validation
+     */
+    private parseConfig;
+    /**
+     * Parse multi-agent orchestration configuration
+     */
+    private parseMultiAgentConfig;
+    /**
+     * Parse autonomous reporting configuration
+     */
+    private parseAutonomousReportingConfig;
+    /**
+     * Get default configuration
+     */
+    private getDefaultConfig;
+    /**
+     * Validate enum values
+     */
+    private validateEnum;
+    /**
+     * Clear configuration cache
+     */
+    clearCache(): void;
+}
+export declare const xrayConfigLoader: XrayConfigLoader;
+export { xrayConfigLoader as strRayConfigLoader, XrayConfigLoader as StringRayConfigLoader };

package/dist/core/config-loader.js

@@ -10,7 +10,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { frameworkLogger } from "./framework-logger.js";
 import { getConfigDir, resolveConfigPath } from "./config-paths.js";
-export class StringRayConfigLoader {
+export class XrayConfigLoader {
     configPath;
     cachedConfig = null;
     cacheExpiry = 30000; // 30 seconds
@@ -145,4 +145,6 @@ export class StringRayConfigLoader {
     }
 }
 // Export singleton instance
-export const strRayConfigLoader = new StringRayConfigLoader();
+export const xrayConfigLoader = new XrayConfigLoader();
+// Backward compat alias
+export { xrayConfigLoader as strRayConfigLoader, XrayConfigLoader as StringRayConfigLoader };

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

@@ -0,0 +1,62 @@
+/**
+ * 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. .opencode/xray/<relative_path>        (OpenCode root)
+ *   4. 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";
+/** Legacy env var name (backward compat) */
+export declare const STRRAY_CONFIG_DIR_ENV = "STRRAY_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.
+ */
+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

@@ -2,24 +2,25 @@
  * Config Path Resolver
  *
  * Centralizes all 0xRay config file path resolution.
- * Supports STRRAY_CONFIG_DIR env var for custom config roots,
- * making .opencode/ completely optional for environments like Hermes Agent.
+ * Supports XRAY_CONFIG_DIR env var for custom config roots.
  *
  * Resolution order (per file type):
- *   1. STRRAY_CONFIG_DIR/<relative_path>     (if env var set)
- *   2. .strray/<relative_path>                (preferred lightweight root)
- *   3. .opencode/strray/<relative_path>       (legacy OpenCode root)
+ *   1. XRAY_CONFIG_DIR/<relative_path>     (if env var set)
+ *   2. .xray/<relative_path>                (preferred lightweight root)
+ *   3. .opencode/xray/<relative_path>        (OpenCode root)
  *   4. null                                   (callers fall back to built-in defaults)
  *
  * For state/data directories, uses:
- *   1. STRRAY_CONFIG_DIR/state                 (if env var set)
- *   2. .strray/state
+ *   1. XRAY_CONFIG_DIR/state                 (if env var set)
+ *   2. .xray/state
  *   3. .opencode/state                         (legacy)
- *   4. .strray/state                           (default — always writable)
+ *   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";
+/** Legacy env var name (backward compat) */
 export const STRRAY_CONFIG_DIR_ENV = "STRRAY_CONFIG_DIR";
 /** Resolved config directories, cached per projectRoot */
 const _resolvedConfigDirs = new Map();
@@ -32,7 +33,7 @@ export function getConfigDir(projectRoot) {
     const cached = _resolvedConfigDirs.get(root);
     if (cached)
         return cached;
-    const envDir = process.env[STRRAY_CONFIG_DIR_ENV];
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV] || process.env[STRRAY_CONFIG_DIR_ENV];
     // Priority candidates
     const candidates = [];
     if (envDir) {
@@ -40,8 +41,8 @@ export function getConfigDir(projectRoot) {
         const resolved = resolve(root, envDir);
         candidates.push({ dir: resolved, source: "env" });
     }
-    candidates.push({ dir: join(root, ".strray"), source: "dot-strray" });
-    candidates.push({ dir: join(root, ".opencode", "strray"), source: "dot-opencode" });
+    candidates.push({ dir: join(root, ".xray"), source: "dot-xray" });
+    candidates.push({ dir: join(root, ".opencode", "xray"), source: "dot-opencode" });
     // Return the first that exists, or the highest-priority default
     for (const c of candidates) {
         if (existsSync(c.dir)) {
@@ -49,7 +50,7 @@ export function getConfigDir(projectRoot) {
             return c.dir;
         }
     }
-    // Nothing exists — use highest priority default (env > .strray > .opencode)
+    // Nothing exists — use highest priority default (env > .xray > .opencode)
     const defaultDir = candidates[0];
     _resolvedConfigDirs.set(root, defaultDir.dir);
     return defaultDir.dir;
@@ -63,13 +64,13 @@ export function getConfigDir(projectRoot) {
  */
 export function resolveConfigPath(relativePath, projectRoot) {
     const root = projectRoot || process.cwd();
-    const envDir = process.env[STRRAY_CONFIG_DIR_ENV];
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV] || process.env[STRRAY_CONFIG_DIR_ENV];
     const candidates = [];
     if (envDir) {
         candidates.push(resolve(root, envDir, relativePath));
     }
-    candidates.push(join(root, ".strray", relativePath));
-    candidates.push(join(root, ".opencode", "strray", relativePath));
+    candidates.push(join(root, ".xray", relativePath));
+    candidates.push(join(root, ".opencode", "xray", relativePath));
     for (const candidate of candidates) {
         if (existsSync(candidate)) {
             return candidate;
@@ -85,12 +86,12 @@ export function resolveConfigPath(relativePath, projectRoot) {
  */
 export function resolveStateDir(projectRoot) {
     const root = projectRoot || process.cwd();
-    const envDir = process.env[STRRAY_CONFIG_DIR_ENV];
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV] || process.env[STRRAY_CONFIG_DIR_ENV];
     const candidates = [];
     if (envDir) {
         candidates.push(join(root, envDir, "state"));
     }
-    candidates.push(join(root, ".strray", "state"));
+    candidates.push(join(root, ".xray", "state"));
     candidates.push(join(root, ".opencode", "state"));
     for (const candidate of candidates) {
         if (existsSync(candidate)) {
@@ -112,13 +113,13 @@ export function resolveStateFilePath(projectRoot) {
  */
 export function resolveProfilesDir(projectRoot) {
     const root = projectRoot || process.cwd();
-    const envDir = process.env[STRRAY_CONFIG_DIR_ENV];
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV] || process.env[STRRAY_CONFIG_DIR_ENV];
     const candidates = [];
     if (envDir) {
         candidates.push(join(root, envDir, "profiles"));
     }
-    candidates.push(join(root, ".strray", "profiles"));
-    candidates.push(join(root, ".opencode", "strray", "profiles"));
+    candidates.push(join(root, ".xray", "profiles"));
+    candidates.push(join(root, ".opencode", "xray", "profiles"));
     for (const candidate of candidates) {
         if (existsSync(candidate)) {
             return candidate;
@@ -132,14 +133,14 @@ export function resolveProfilesDir(projectRoot) {
  */
 export function resolveCodexPath(projectRoot) {
     const root = projectRoot || process.cwd();
-    const envDir = process.env[STRRAY_CONFIG_DIR_ENV];
+    const envDir = process.env[XRAY_CONFIG_DIR_ENV] || process.env[STRRAY_CONFIG_DIR_ENV];
     const candidates = [];
     if (envDir) {
         candidates.push(join(root, envDir, "codex.json"));
     }
-    candidates.push(join(root, ".strray", "codex.json"));
+    candidates.push(join(root, ".xray", "codex.json"));
     candidates.push(join(root, "xray", "codex.json"));
-    candidates.push(join(root, ".opencode", "strray", "codex.json"));
+    candidates.push(join(root, ".opencode", "xray", "codex.json"));
     // Additional fallback locations (for standalone usage)
     candidates.push(join(root, "codex.json"));
     candidates.push(join(root, "src", "codex.json"));

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

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ *
+ * @version 1.0.0
+ * @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;
+export { xrayContextLoader as strRayContextLoader, XrayContextLoader as StringRayContextLoader };

package/dist/core/context-loader.js

@@ -22,7 +22,7 @@ function isValidMatch(match, index) {
  *
  * Loads and parses the Universal Development Codex v1.2.0 from codex.json
  */
-export class StringRayContextLoader {
+export class XrayContextLoader {
     static instance;
     cachedContext = null;
     codexFilePaths = [];
@@ -33,10 +33,10 @@ export class StringRayContextLoader {
      * Get singleton instance
      */
     static getInstance() {
-        if (!StringRayContextLoader.instance) {
-            StringRayContextLoader.instance = new StringRayContextLoader();
+        if (!XrayContextLoader.instance) {
+            XrayContextLoader.instance = new XrayContextLoader();
         }
-        return StringRayContextLoader.instance;
+        return XrayContextLoader.instance;
     }
     /**
      * Load codex context
@@ -266,4 +266,6 @@ export class StringRayContextLoader {
 /**
  * Export singleton instance
  */
-export const strRayContextLoader = StringRayContextLoader.getInstance();
+export const xrayContextLoader = XrayContextLoader.getInstance();
+// Backward compat alias
+export { xrayContextLoader as strRayContextLoader, XrayContextLoader as StringRayContextLoader };

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

@@ -0,0 +1,53 @@
+/**
+ * 0xRay Context Size Validator
+ *
+ * Prevents system prompt bloat by validating and rejecting context-injection attempts
+ * that would exceed token budgets.
+ *
+ * @version 1.0.0
+ * @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;
+};