0xray 2.0.0

package/dist/core/config-loader.js

@@ -0,0 +1,148 @@
+/**
+ * Configuration Loader
+ *
+ * Loads and validates 0xRay-specific configuration from opencode.json
+ *
+ * @version 1.0.0
+ * @since 2026-01-09
+ */
+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 {
+    configPath;
+    cachedConfig = null;
+    cacheExpiry = 30000; // 30 seconds
+    lastLoadTime = 0;
+    constructor(configPath) {
+        this.configPath = configPath || resolveConfigPath("config.json") || path.join(getConfigDir(), "config.json");
+    }
+    /**
+     * Load 0xRay configuration from the resolved config directory
+     */
+    loadConfig() {
+        const now = Date.now();
+        // Return cached config if still valid
+        if (this.cachedConfig && now - this.lastLoadTime < this.cacheExpiry) {
+            return this.cachedConfig;
+        }
+        try {
+            const configPath = path.resolve(process.cwd(), this.configPath);
+            if (!fs.existsSync(configPath)) {
+                return this.getDefaultConfig();
+            }
+            const configData = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            const config = this.parseConfig(configData);
+            this.cachedConfig = config;
+            this.lastLoadTime = now;
+            return config;
+        }
+        catch (error) {
+            frameworkLogger.log("config-loader", "load-failed", "error", { error, message: "Failed to load 0xRay config" });
+            return this.getDefaultConfig();
+        }
+    }
+    /**
+     * Parse configuration data with validation
+     */
+    parseConfig(configData) {
+        // Handle null/undefined config data
+        if (!configData || typeof configData !== 'object') {
+            return this.getDefaultConfig();
+        }
+        const data = configData;
+        return {
+            multi_agent_orchestration: this.parseMultiAgentConfig(data.multi_agent_orchestration),
+            autonomous_reporting: this.parseAutonomousReportingConfig(data.autonomous_reporting),
+            disabled_agents: Array.isArray(data.disabled_agents)
+                ? data.disabled_agents
+                : [],
+        };
+    }
+    /**
+     * Parse multi-agent orchestration configuration
+     */
+    parseMultiAgentConfig(config) {
+        if (!config || typeof config !== 'object') {
+            return this.getDefaultConfig().multi_agent_orchestration;
+        }
+        const cfg = config;
+        return {
+            enabled: typeof cfg.enabled === 'boolean' ? cfg.enabled : true,
+            coordination_model: this.validateEnum(cfg.coordination_model, ["async-multi-agent", "sync-multi-agent"], "async-multi-agent"),
+            max_concurrent_agents: Math.max(1, Math.min(10, typeof cfg.max_concurrent_agents === 'number' ? cfg.max_concurrent_agents : 3)),
+            task_distribution_strategy: this.validateEnum(cfg.task_distribution_strategy, ["capability-based", "load-balanced", "round-robin"], "capability-based"),
+            conflict_resolution: this.validateEnum(cfg.conflict_resolution, ["expert-priority", "majority-vote", "consensus"], "expert-priority"),
+            progress_tracking: typeof cfg.progress_tracking === 'boolean' ? cfg.progress_tracking : true,
+            session_persistence: typeof cfg.session_persistence === 'boolean' ? cfg.session_persistence : true,
+        };
+    }
+    /**
+     * Parse autonomous reporting configuration
+     */
+    parseAutonomousReportingConfig(config) {
+        if (!config || typeof config !== 'object') {
+            return this.getDefaultConfig().autonomous_reporting;
+        }
+        const cfg = config;
+        return {
+            enabled: typeof cfg.enabled === 'boolean' ? cfg.enabled : false,
+            interval_minutes: Math.max(5, Math.min(1440, typeof cfg.interval_minutes === 'number' ? cfg.interval_minutes : 60)), // 5min to 24hrs
+            auto_schedule: typeof cfg.auto_schedule === 'boolean' ? cfg.auto_schedule : false,
+            include_health_assessment: typeof cfg.include_health_assessment === 'boolean' ? cfg.include_health_assessment : true,
+            include_agent_activities: typeof cfg.include_agent_activities === 'boolean' ? cfg.include_agent_activities : true,
+            include_pipeline_operations: typeof cfg.include_pipeline_operations === 'boolean' ? cfg.include_pipeline_operations : true,
+            include_critical_issues: typeof cfg.include_critical_issues === 'boolean' ? cfg.include_critical_issues : true,
+            include_recommendations: typeof cfg.include_recommendations === 'boolean' ? cfg.include_recommendations : true,
+            report_retention_days: Math.max(1, Math.min(365, typeof cfg.report_retention_days === 'number' ? cfg.report_retention_days : 30)),
+            notification_channels: Array.isArray(cfg.notification_channels)
+                ? cfg.notification_channels.filter((ch) => ["console", "file", "webhook"].includes(ch))
+                : ["console"],
+        };
+    }
+    /**
+     * Get default configuration
+     */
+    getDefaultConfig() {
+        return {
+            multi_agent_orchestration: {
+                enabled: true,
+                coordination_model: "async-multi-agent",
+                max_concurrent_agents: 3,
+                task_distribution_strategy: "capability-based",
+                conflict_resolution: "expert-priority",
+                progress_tracking: true,
+                session_persistence: true,
+            },
+            autonomous_reporting: {
+                enabled: false, // Disabled by default for performance
+                interval_minutes: 60,
+                auto_schedule: false,
+                include_health_assessment: true,
+                include_agent_activities: true,
+                include_pipeline_operations: true,
+                include_critical_issues: true,
+                include_recommendations: true,
+                report_retention_days: 30,
+                notification_channels: ["console"],
+            },
+            disabled_agents: [],
+        };
+    }
+    /**
+     * Validate enum values
+     */
+    validateEnum(value, allowedValues, defaultValue) {
+        return allowedValues.includes(value) ? value : defaultValue;
+    }
+    /**
+     * Clear configuration cache
+     */
+    clearCache() {
+        this.cachedConfig = null;
+        this.lastLoadTime = 0;
+    }
+}
+// Export singleton instance
+export const strRayConfigLoader = new StringRayConfigLoader();

package/dist/core/config-paths.js

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ *
+ * 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)
+ *   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
+ *   3. .opencode/state                         (legacy)
+ *   4. .strray/state                           (default — always writable)
+ */
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+/** Environment variable name for custom config root */
+export const STRRAY_CONFIG_DIR_ENV = "STRRAY_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 = projectRoot || process.cwd();
+    const cached = _resolvedConfigDirs.get(root);
+    if (cached)
+        return cached;
+    const envDir = process.env[STRRAY_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, ".strray"), source: "dot-strray" });
+    candidates.push({ dir: join(root, ".opencode", "strray"), source: "dot-opencode" });
+    // 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 > .strray > .opencode)
+    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 = projectRoot || process.cwd();
+    const envDir = 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));
+    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 = projectRoot || process.cwd();
+    const envDir = 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, ".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 = projectRoot || process.cwd();
+    const envDir = 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"));
+    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.
+ */
+export function resolveCodexPath(projectRoot) {
+    const root = projectRoot || process.cwd();
+    const envDir = 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, ".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"));
+    return candidates;
+}
+/**
+ * Get the logs directory for framework logging.
+ */
+export function resolveLogDir(projectRoot) {
+    const root = projectRoot || process.cwd();
+    // 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.js

@@ -0,0 +1,269 @@
+/**
+ * 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
+ */
+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 StringRayContextLoader {
+    static instance;
+    cachedContext = null;
+    codexFilePaths = [];
+    constructor() {
+        this.codexFilePaths = resolveCodexPath();
+    }
+    /**
+     * Get singleton instance
+     */
+    static getInstance() {
+        if (!StringRayContextLoader.instance) {
+            StringRayContextLoader.instance = new StringRayContextLoader();
+        }
+        return StringRayContextLoader.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 strRayContextLoader = StringRayContextLoader.getInstance();