0xray 2.0.0

package/dist/validation/report-content-validator.js

@@ -0,0 +1,218 @@
+/**
+ * Report Content Validator
+ * Reads and analyzes full report content to detect hidden errors and inconsistencies
+ */
+export class ReportContentValidator {
+    reportPatterns = {
+        // Error patterns that indicate real issues (excluding legitimate contexts)
+        criticalErrors: [
+            /\bERROR\b(?!\s*(handling|prevention|conditions?|messages?|logs?|recovery))/gi, // ERROR not followed by legitimate terms
+            /\bFAILED\b(?!\s*(to|attempts?|tests?|validation))/gi, // FAILED not in expected contexts
+            /\bCRASHED\b/gi,
+            /\bEXCEPTION\b(?!\s*(handling|thrown))/gi,
+            /\bFATAL\b(?!\s*(error|errors))/gi,
+            /❌/g,
+            /\[ERROR\]/g,
+            /\bBROKEN\b/gi,
+            /\bUNAVAILABLE\b/gi,
+            /\bDISABLED\b/gi,
+        ],
+        // Warning patterns that need attention
+        warnings: [
+            /\bWARNING\b/gi,
+            /\bWARN\b/gi,
+            /\bDEPRECATED\b/gi,
+            /\bUNSTABLE\b/gi,
+            /⚠️/g,
+            /\[WARN\]/g,
+        ],
+        // Success claims that might be false
+        falsePositives: [
+            /\bSUCCESS\b.*\bFAILED\b/gi, // Success mentioned but failed occurred
+            /\bPASSED\b.*\bERROR\b/gi, // Passed but errors present
+            /\bCOMPLETED\b.*\bCRASHED\b/gi, // Completed but crashed
+        ],
+        // Inconsistency patterns
+        inconsistencies: [
+            /\b(\d+)\s+total.*\b(\d+)\s+failed/i, // Mismatched counts
+            /\b(\d+)\s+passed.*\b(\d+)\s+failed/i, // Success/failure count mismatch
+            /health.*score.*(\d+).*issues.*(\d+)/i, // Health score vs issue count mismatch
+        ],
+    };
+    /**
+     * Validate full report content for hidden errors
+     */
+    async validateReportContent(reportPath, reportType) {
+        const issues = [];
+        const criticalErrors = [];
+        const warnings = [];
+        const falsePositives = [];
+        const inconsistencies = [];
+        try {
+            // Read full report content
+            const fs = await import("fs");
+            if (!fs.existsSync(reportPath)) {
+                issues.push(`Report file not found: ${reportPath}`);
+                return this.createValidationResult(false, issues, 0, 0, 0, 0, [], [], [], []);
+            }
+            const content = fs.readFileSync(reportPath, "utf8");
+            // Analyze for critical errors
+            for (const pattern of this.reportPatterns.criticalErrors) {
+                const matches = content.match(pattern);
+                if (matches) {
+                    criticalErrors.push(...matches.map((match) => `Critical error pattern: "${match}"`));
+                }
+            }
+            // Analyze for warnings
+            for (const pattern of this.reportPatterns.warnings) {
+                const matches = content.match(pattern);
+                if (matches) {
+                    warnings.push(...matches.map((match) => `Warning pattern: "${match}"`));
+                }
+            }
+            // Analyze for false positives
+            for (const pattern of this.reportPatterns.falsePositives) {
+                const matches = content.match(pattern);
+                if (matches) {
+                    falsePositives.push(...matches.map((match) => `False positive detected: "${match}"`));
+                }
+            }
+            // Analyze for inconsistencies
+            for (const pattern of this.reportPatterns.inconsistencies) {
+                const matches = content.match(pattern);
+                if (matches) {
+                    // Check if numbers don't add up
+                    const match = pattern.exec(content);
+                    if (match && match.length >= 3) {
+                        const num1 = parseInt(match[1] || "0");
+                        const num2 = parseInt(match[2] || "0");
+                        if (num1 > 0 && num2 > 0 && Math.abs(num1 - num2) > num1 * 0.1) {
+                            inconsistencies.push(`Number inconsistency: ${match[0]}`);
+                        }
+                    }
+                }
+            }
+            // Additional report-type specific validations
+            const typeSpecificIssues = await this.validateReportTypeSpecific(content, reportType);
+            issues.push(...typeSpecificIssues);
+            // Calculate risk level
+            const totalIssues = criticalErrors.length +
+                warnings.length +
+                falsePositives.length +
+                inconsistencies.length;
+            let riskLevel = "low";
+            if (criticalErrors.length > 0)
+                riskLevel = "critical";
+            else if (falsePositives.length > 0 || inconsistencies.length > 2)
+                riskLevel = "high";
+            else if (warnings.length > 5 || inconsistencies.length > 0)
+                riskLevel = "medium";
+            return {
+                valid: criticalErrors.length === 0 && falsePositives.length === 0,
+                issues,
+                summary: {
+                    errorCount: criticalErrors.length,
+                    warningCount: warnings.length,
+                    falsePositiveCount: falsePositives.length,
+                    inconsistencyCount: inconsistencies.length,
+                    riskLevel,
+                },
+                details: {
+                    criticalErrors,
+                    warnings,
+                    falsePositives,
+                    inconsistencies,
+                },
+            };
+        }
+        catch (error) {
+            issues.push(`Failed to validate report content: ${error}`);
+            return this.createValidationResult(false, issues, 0, 0, 0, 0, [], [], [], []);
+        }
+    }
+    async validateReportTypeSpecific(content, reportType) {
+        const issues = [];
+        switch (reportType) {
+            case "session":
+                // Check for session-specific issues
+                const hasSessionContent = content.includes("session") ||
+                    content.includes("Session") ||
+                    content.includes("coordinator") ||
+                    content.includes("agent") ||
+                    content.includes("delegation") ||
+                    content.includes("migration");
+                if (!hasSessionContent) {
+                    issues.push("Session report missing session-related content");
+                }
+                // Check for session management terminology
+                const sessionTerms = [
+                    "coordinator",
+                    "agent",
+                    "delegation",
+                    "migration",
+                    "persistence",
+                ];
+                const missingTerms = sessionTerms.filter((term) => content.includes(term) && !content.includes(term + " "));
+                if (missingTerms.length > 0) {
+                    issues.push(`Session report mentions sessions but lacks key terminology: ${missingTerms.join(", ")}`);
+                }
+                break;
+            case "framework":
+                // Check for framework health indicators
+                if (!content.includes("health") && !content.includes("Health")) {
+                    issues.push("Framework report missing health assessment");
+                }
+                if (content.includes("error") && !content.includes("resolution")) {
+                    issues.push("Framework report mentions errors but no resolution steps");
+                }
+                break;
+            case "validation":
+                // Check for validation completeness
+                if (!content.includes("validator") && !content.includes("validation")) {
+                    issues.push("Validation report missing validation terminology");
+                }
+                break;
+            case "simulation":
+                // Check for simulation metrics
+                if (!content.includes("simulation") && !content.includes("scenario")) {
+                    issues.push("Simulation report missing simulation context");
+                }
+                if (content.includes("success") && !content.includes("metrics")) {
+                    issues.push("Simulation report claims success but lacks performance metrics");
+                }
+                break;
+        }
+        return issues;
+    }
+    createValidationResult(valid, issues, errorCount, warningCount, falsePositiveCount, inconsistencyCount, criticalErrors, warnings, falsePositives, inconsistencies) {
+        return {
+            valid,
+            issues,
+            summary: {
+                errorCount,
+                warningCount,
+                falsePositiveCount,
+                inconsistencyCount,
+                riskLevel: "critical",
+            },
+            details: {
+                criticalErrors,
+                warnings,
+                falsePositives,
+                inconsistencies,
+            },
+        };
+    }
+    /**
+     * Get validation patterns for debugging
+     */
+    getValidationPatterns() {
+        return { ...this.reportPatterns };
+    }
+    /**
+     * Add custom validation pattern
+     */
+    addValidationPattern(category, pattern) {
+        this.reportPatterns[category].push(pattern);
+    }
+}

package/opencode.json

@@ -0,0 +1,153 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "compaction": {
+    "auto": true,
+    "prune": true
+  },
+  "mcp": {
+    "context7": {
+      "enabled": false
+    },
+    "global-everything": {
+      "enabled": false
+    },
+    "global-filesystem": {
+      "enabled": false
+    },
+    "global-git": {
+      "enabled": false
+    }
+  },
+  "agent": {
+    "architect": {
+      "description": "Architect agent for system design - PRIMARY for design decisions",
+      "temperature": 1,
+      "mode": "primary"
+    },
+    "strategist": {
+      "description": "Expert in system design, architecture decisions, and technical roadmaps",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "testing-lead": {
+      "description": "Testing lead for testing strategy",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "bug-triage-specialist": {
+      "description": "Bug triage specialist",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "code-reviewer": {
+      "description": "Code reviewer for quality",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "security-auditor": {
+      "description": "Security auditor",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "refactorer": {
+      "description": "Refactorer for code improvement",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "researcher": {
+      "description": "Researcher for codebase exploration",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "log-monitor": {
+      "description": "Log monitor for diagnostics",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "backend-engineer": {
+      "description": "Expert in REST/GraphQL APIs, microservices, authentication, server architecture, and backend performance",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "frontend-engineer": {
+      "description": "Expert in React, Vue, Angular, responsive design, and frontend performance",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "frontend-ui-ux-engineer": {
+      "description": "Expert in visual design, CSS systems, accessibility, and user experience",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "database-engineer": {
+      "description": "Expert in SQL/NoSQL databases, query optimization, data modeling, and database performance",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "devops-engineer": {
+      "description": "Expert in CI/CD pipelines, infrastructure as code, containerization, and deployment automation",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "mobile-developer": {
+      "description": "Expert in iOS, Android, React Native, and Flutter development",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "performance-engineer": {
+      "description": "Expert in profiling, benchmarking, load testing, and optimization",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "content-creator": {
+      "description": "Expert in creating marketing copy, technical documentation, blog posts, and social media content",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "growth-strategist": {
+      "description": "Expert in growth hacking, user acquisition, conversion optimization, and analytics",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "seo-consultant": {
+      "description": "Expert in search engine optimization, keyword research, and organic traffic growth",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "tech-writer": {
+      "description": "Expert in API documentation, README files, guides, and developer experience",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "multimodal-looker": {
+      "description": "Media file analysis and interpretation specialist for images, diagrams, PDFs, and visual content",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "code-analyzer": {
+      "description": "Code analyzer for metrics",
+      "temperature": 1,
+      "mode": "subagent"
+    },
+    "sisyphus": {
+      "description": "Sisyphus task agent",
+      "disable": true
+    },
+    "Planner-Sisyphus": {
+      "description": "Planner Sisyphus",
+      "disable": true
+    },
+    "OpenCode-Builder": {
+      "description": "OpenCode Builder",
+      "disable": true
+    },
+    "build": {
+      "description": "Build agent",
+      "disable": true
+    },
+    "plan": {
+      "description": "Plan agent",
+      "disable": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,170 @@
+{
+  "name": "0xray",
+  "version": "2.0.0",
+  "description": "Multi-agent orchestration and Codex governance for OpenCode, Hermes, Grok Build, and OpenClaw",
+  "readme": "README.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xRayAI/xray.git"
+  },
+  "homepage": "https://github.com/0xRayAI/xray#readme",
+  "bugs": {
+    "url": "https://github.com/0xRayAI/xray/issues"
+  },
+  "keywords": [
+    "ai",
+    "opencode",
+    "hermes",
+    "openclaw",
+    "grok",
+    "mcp",
+    "agent",
+    "orchestration",
+    "codex",
+    "error-prevention",
+    "multi-agent",
+    "framework",
+    "governance",
+    "cli",
+    "tui",
+    "hallucination-prevention",
+    "ai-slop-prevention",
+    "terminal-ai",
+    "ai-assistant",
+    "plugin-system"
+  ],
+  "type": "module",
+  "main": "./dist/plugin/xray-codex-injection.js",
+  "types": "./dist/plugin/xray-codex-injection.d.ts",
+  "bin": {
+    "0xray": "dist/cli/index.js",
+    "0xray-integration": "dist/scripts/integration.js"
+  },
+  "opencode": {
+    "plugin": "./dist/plugin/xray-codex-injection.js",
+    "mcps": "./dist/mcps/"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run prepare-consumer && npm run build:all && find dist -name '*.d.ts' -o -name '*.d.ts.map' -o -name '*.js.map' | xargs rm -f",
+    "version:bump": "node scripts/node/version-manager.mjs",
+    "version": "node scripts/node/version-manager.mjs",
+    "prebuild": "rm -rf dist tsconfig.tsbuildinfo tsconfig.*.tsbuildinfo",
+    "build": "tsc && mkdir -p dist/public dist/scripts && cp -r public/* dist/public/ && cp scripts/hooks/pre-command dist/scripts/ && cp scripts/hooks/pre-command.mjs dist/scripts/ && cp README.md AGENTS.md CHANGELOG.md LICENSE dist/ && find src -name '*.mjs' ! -path '*/__tests__/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done && for dir in skills integrations mcps; do find src/$dir -type f ! -name '*.ts' ! -path '*/.pytest_cache/*' | while read f; do tgt=\"dist/${f#src/}\"; mkdir -p \"$(dirname $tgt)\"; cp \"$f\" \"$tgt\"; done; done && mkdir -p dist/plugin && (find dist/plugin -name '*codex-injection*.js' -exec cp {} dist/plugin/xray-codex-injection.js \\; 2>/dev/null || true) && cp -r src/opencode/ .opencode/ && rm -rf .opencode/xray 2>/dev/null; mkdir -p .opencode/xray && cp xray/codex.json .opencode/xray/codex.json 2>/dev/null || true",
+    "build:all": "npm run build",
+    "ci-install": "npm ci",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo tsconfig.*.tsbuildinfo",
+    "test": "vitest run",
+    "test:batch": "npm test",
+    "test:unit": "npm test -- src/__tests__/unit/config-loader.test.ts src/__tests__/unit/state-manager.test.ts src/__tests__/unit/state-manager-persistence.test.ts src/__tests__/unit/context-loader.test.ts src/__tests__/unit/pattern-analyzer.test.ts src/__tests__/unit/complexity-calibrator.test.ts",
+    "test:core-framework": "npm test -- src/__tests__/unit/self-direction-activation.test.ts src/__tests__/unit/ast-code-parser.test.ts src/__tests__/unit/v2-deletion-protection.test.ts",
+    "test:security": "npm test -- src/__tests__/unit/security/security-hardener.test.ts src/__tests__/unit/security/security-headers.test.ts src/__tests__/unit/security/security-auditor.test.ts",
+    "test:performance": "npm test -- src/__tests__/unit/monitoring.test.ts src/__tests__/unit/benchmark.test.ts src/__tests__/unit/analytics.test.ts",
+    "test:session-management": "npm test -- src/__tests__/unit/session-state-manager.test.ts src/__tests__/unit/session-security-validator.test.ts src/__tests__/unit/session-coordination-validator.test.ts src/__tests__/unit/session-migration-validator.test.ts src/__tests__/unit/session-migration-logic.test.ts",
+    "test:code-analysis": "npm test -- src/__tests__/unit/codebase-context-analyzer.test.ts src/__tests__/unit/dependency-graph-builder.test.ts src/__tests__/unit/rule-enforcer.test.ts src/__tests__/unit/codex-parser.test.ts src/__tests__/unit/codex-injector.test.ts",
+    "test:processors": "npm test -- src/__tests__/unit/processor-activation.test.ts src/__tests__/unit/typescript-compilation-processor.test.ts",
+    "test:miscellaneous": "npm test -- src/__tests__/unit/blocked-test.test.ts",
+    "test:quick": "npm test -- src/__tests__/integration/boot-orchestrator.integration.test.ts src/__tests__/unit/config-loader.test.ts src/__tests__/unit/state-manager.test.ts",
+    "test:comprehensive": "npm run typecheck && npm run test:unit && npm run test:core-framework && npm run test:security && npm run test:performance && npm run test:session-management && npm run test:code-analysis && npm run test:processors && npm run test:miscellaneous",
+    "test:integration-all": "npm test -- src/__tests__/integration/",
+    "test:performance-all": "npm test -- src/__tests__/performance/ src/__tests__/unit/performance-system.test.ts src/__tests__/unit/benchmark.test.ts src/__tests__/unit/analytics.test.ts",
+    "test:agents-all": "echo 'Legacy agents test entry retired'",
+    "test:infrastructure": "npm test -- src/__tests__/infrastructure/",
+    "test:root": "npm test -- src/__tests__/integration/server.test.ts src/__tests__/framework-enforcement-integration.test.ts",
+    "test:pipelines": "node src/__tests__/pipeline/run-all-pipelines.mjs",
+    "test:full-suite": "npm run typecheck && npm run test:integration-all && npm run test:performance-all && npm run test:infrastructure && npm run test:root",
+    "postinstall": "node scripts/node/postinstall.cjs",
+    "setup-dev": "node scripts/node/setup-dev.cjs",
+    "prepare-consumer": "node scripts/node/prepare-consumer.cjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint -c tests/config/eslint.config.js src",
+    "lint:fix": "eslint src --fix",
+    "security-audit": "npm audit || true",
+    "test:security-audit": "npm run test:security",
+    "test:dependency-scan": "npm run security-audit",
+    "test:integration": "node scripts/mjs/test-consumer-readiness.mjs && node scripts/mjs/test-mcp-functionality.mjs",
+    "test:e2e": "node scripts/node/validate-mcp-connectivity.js && node scripts/node/validate-external-processes.js",
+    "validate": "echo \"[xray] Use 'npm test' or 'npm run test:comprehensive'.\"",
+    "validate:quick": "npm run validate",
+    "debug:inference:force": "STRRAY_FORCE_MCP_GOVERNANCE=true XRAY_DEV_PATH=dist node dist/cli/index.js inference:run --force",
+    "validate:full": "npm run validate",
+    "test:unified": "node scripts/test/test-unified-framework.mjs",
+    "test:consumer": "node scripts/test/test-consumer-readiness.cjs",
+    "config:setup": "node scripts/config/utils.js setup-dev",
+    "monitoring:start": "node scripts/monitoring/daemon.js start",
+    "monitoring:stop": "node scripts/monitoring/daemon.js stop",
+    "monitoring:report": "node scripts/monitoring/daemon.js report",
+    "build:run": "node scripts/build/utils.js build",
+    "build:clean": "node scripts/build/utils.js clean",
+    "build:verify": "node scripts/build/utils.js verify",
+    "enforce:versions": "bash scripts/node/enforce-version-compliance.sh",
+    "version:sync": "node scripts/node/universal-version-manager.js",
+    "preversion": "npm run version:sync",
+    "release": "node scripts/node/release.js",
+    "release:minor": "node scripts/node/release.mjs minor",
+    "release:major": "node scripts/node/release.mjs major",
+    "release:dry": "node scripts/node/release.js --dry-run",
+    "pre-publish-guard": "node scripts/node/pre-publish-guard.js",
+    "safe-publish": "npm run prepare-consumer && npm run build",
+    "publish": "npm run pre-publish-guard && npm run safe-publish",
+    "release:patch": "node scripts/node/release.mjs patch"
+  },
+  "files": [
+    "dist/",
+    "scripts/node/",
+    "scripts/integrations/",
+    "scripts/helpers/",
+    "scripts/hooks/",
+    "scripts/mjs/test-consumer-readiness.mjs",
+    "scripts/mjs/test-mcp-functionality.mjs",
+    "scripts/mjs/validate-mcp-connectivity.cjs",
+    "scripts/mjs/validate-postinstall-config.mjs",
+    "scripts/validate-stringray-comprehensive.js",
+    "src/opencode/",
+    "src/opencode/AGENTS-consumer.md",
+    "src/opencode/codex.codex",
+    "src/opencode/commands/",
+    "src/opencode/enforcer-config.json",
+    "src/opencode/openclaw/",
+    "src/opencode/workflows/",
+    "src/integrations/grok/plugin/0xray/",
+    "src/skills/",
+    "src/mcps/",
+    ".opencode/agents/",
+    ".opencode/commands/",
+    ".opencode/hooks/",
+    ".opencode/skills/",
+    ".opencode/integrations/",
+    ".opencode/init.sh",
+    ".opencode/workflows/",
+    ".opencode/codex.codex",
+    ".opencode/enforcer-config.json",
+    "opencode.json",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE",
+    "LICENSE.claude-seo",
+    "LICENSE.antigravity"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "commander": "^11.1.0",
+    "express": "^5.2.1",
+    "jsonwebtoken": "^9.0.3",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/express": "^5.0.0",
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/node": "^22.10.2",
+    "@types/ws": "^8.5.13",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "@vitest/coverage-v8": "^4.1.8",
+    "eslint": "^9.17.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.8"
+  }
+}

package/scripts/helpers/resolve-config-path.cjs

@@ -0,0 +1,57 @@
+/**
+ * Shared config path resolver for xray scripts (CJS version).
+ * Mirrors src/core/config-paths.ts logic.
+ */
+
+"use strict";
+const { existsSync } = require("fs");
+const { join, resolve } = require("path");
+
+const XRAY_CONFIG_DIR_ENV = "XRAY_CONFIG_DIR";
+
+const _cache = new Map();
+
+function getConfigDir(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const cached = _cache.get(root);
+  if (cached) return cached;
+
+  const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+  const candidates = [];
+
+  if (envDir) {
+    candidates.push(resolve(root, envDir));
+  }
+  candidates.push(join(root, ".opencode"));
+
+  for (const dir of candidates) {
+    if (existsSync(dir)) {
+      _cache.set(root, dir);
+      return dir;
+    }
+  }
+
+  _cache.set(root, candidates[0]);
+  return candidates[0];
+}
+
+function resolveConfigPath(relativePath, projectRoot) {
+  const root = projectRoot || process.cwd();
+  const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+
+  const candidates = [];
+  if (envDir) {
+    candidates.push(resolve(root, envDir, relativePath));
+  }
+  candidates.push(join(root, ".opencode", relativePath));
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0] || null;
+}
+
+module.exports = { getConfigDir, resolveConfigPath, XRAY_CONFIG_DIR_ENV };

package/scripts/helpers/resolve-config-path.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * Shared config path resolver for xray scripts (.mjs/.cjs/.js).
+ *
+ * Mirrors the logic in src/core/config-paths.ts so scripts don't need to
+ * import compiled TypeScript. Supports XRAY_CONFIG_DIR env var.
+ *
+ * Usage:
+ *   import { getConfigDir, resolveConfigPath } from "../helpers/resolve-config-path.mjs";
+ *   // or for CJS:
+ *   const { getConfigDir, resolveConfigPath } = require("../helpers/resolve-config-path.cjs");
+ */
+
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+
+const XRAY_CONFIG_DIR_ENV = "XRAY_CONFIG_DIR";
+
+/** Cache of resolved config dirs per project root */
+const _cache = new Map();
+
+/**
+ * Detect the best available config directory.
+ * Priority: XRAY_CONFIG_DIR > .opencode
+ */
+export function getConfigDir(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const cached = _cache.get(root);
+  if (cached) return cached;
+
+  const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+  const candidates = [];
+
+  if (envDir) {
+    candidates.push(resolve(root, envDir));
+  }
+  candidates.push(join(root, ".opencode"));
+
+  for (const dir of candidates) {
+    if (existsSync(dir)) {
+      _cache.set(root, dir);
+      return dir;
+    }
+  }
+
+  // Default: highest priority (env > .opencode)
+  _cache.set(root, candidates[0]);
+  return candidates[0];
+}
+
+/**
+ * Resolve a specific config file using the standard priority chain.
+ * Returns the first existing candidate, or the highest-priority default.
+ */
+export function resolveConfigPath(relativePath, projectRoot) {
+  const root = projectRoot || process.cwd();
+  const envDir = process.env[XRAY_CONFIG_DIR_ENV];
+
+  const candidates = [];
+  if (envDir) {
+    candidates.push(resolve(root, envDir, relativePath));
+  }
+  candidates.push(join(root, ".opencode", relativePath));
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0] || null;
+}