0xray 3.1.0 → 3.2.0

package/scripts/node/auto-reflection-generator.mjs

@@ -107,47 +107,41 @@ function getChangedFiles(count = 20) {
 }
 
 function loadConfig() {
-  // Primary: .opencode/xray/ YML SSOT. Min legacy fallbacks for .opencode/strray/ + .strray/ (transitional consumer compat; documented per Term 61)
-  const configPath = join(process.cwd(), ".opencode", "xray", "features.json");
-  const fallbackPath = join(process.cwd(), ".opencode", "strray", "features.json");
-  const legacyPath = join(process.cwd(), ".strray", "features.json");
-  
-  for (const p of [configPath, fallbackPath, legacyPath]) {
-    if (existsSync(p)) {
-      try {
-        const content = readFileSync(p, "utf-8");
-        const parsed = JSON.parse(content);
-        if (parsed.auto_reflection) {
-          return parsed.auto_reflection;
-        }
-        if (parsed.storytelling?.reflection_triggers) {
-          // Legacy support - convert from storytelling config
-          const triggers = parsed.storytelling.reflection_triggers;
-          return {
-            mode: "minimal",
-            triggers: {
-              commit_threshold: {
-                enabled: triggers.commit_count?.enabled ?? true,
-                threshold: triggers.commit_count?.threshold ?? 10,
-              },
-              time_threshold: {
-                enabled: true,
-                days: 7,
-              },
+  const configPath = join(process.cwd(), ".xray", "features.json");
+
+  if (existsSync(configPath)) {
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      const parsed = JSON.parse(content);
+      if (parsed.auto_reflection) {
+        return parsed.auto_reflection;
+      }
+      if (parsed.storytelling?.reflection_triggers) {
+        const triggers = parsed.storytelling.reflection_triggers;
+        return {
+          mode: "minimal",
+          triggers: {
+            commit_threshold: {
+              enabled: triggers.commit_count?.enabled ?? true,
+              threshold: triggers.commit_count?.threshold ?? 10,
             },
-            thresholds: {
-              full: { commit_threshold: 10, days_threshold: 5 },
-              minimal: { commit_threshold: 25, days_threshold: 14 },
-              off: { commit_threshold: 999, days_threshold: 365 },
+            time_threshold: {
+              enabled: true,
+              days: 7,
             },
-          };
-        }
-      } catch {
-        // ignore
+          },
+          thresholds: {
+            full: { commit_threshold: 10, days_threshold: 5 },
+            minimal: { commit_threshold: 25, days_threshold: 14 },
+            off: { commit_threshold: 999, days_threshold: 365 },
+          },
+        };
       }
+    } catch {
+      // ignore
     }
   }
-  
+
   // Default config
   return {
     mode: "minimal",

package/scripts/node/govern-reflection.mjs

@@ -147,7 +147,7 @@ async function main() {
   console.log(`  Duration: ${(result.duration / 1000).toFixed(1)}s`);
   console.log("═══════════════════════════════════════\n");
 
-  // v2 path under logs/ (fwLogger discipline) + .opencode/xray/
+  // v2 path under logs/ (fwLogger discipline) + .xray/
   const outputPath = path.join(process.cwd(), "logs", "framework", "governance-result.json");
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, JSON.stringify(result, null, 2));

package/scripts/node/postinstall.cjs

@@ -34,6 +34,41 @@ if (fs.existsSync(agentsConsumer) && resolvedPackage !== resolvedTarget) {
   fs.copyFileSync(agentsConsumer, agentsDest);
 }
 
+// Copy .gitignore.default → .gitignore (never overwrite existing)
+const gitignoreSource = path.join(packageRoot, ".gitignore.default");
+const gitignoreDest = path.join(targetDir, ".gitignore");
+if (!fs.existsSync(gitignoreDest) && resolvedPackage !== resolvedTarget) {
+  fs.copyFileSync(gitignoreSource, gitignoreDest);
+  structuredLog('postinstall', 'Created .gitignore from template', 'info');
+}
+
+// Sync core skills from dist/ → .opencode/skills/
+const skillsSource = path.join(packageRoot, 'dist', 'skills');
+const skillsDest = path.join(targetDir, '.opencode', 'skills');
+if (fs.existsSync(skillsSource) && resolvedPackage !== resolvedTarget) {
+  try {
+    if (!fs.existsSync(skillsDest)) fs.mkdirSync(skillsDest, { recursive: true });
+    const skillDirs = fs.readdirSync(skillsSource, { withFileTypes: true });
+    let copied = 0, skipped = 0;
+    for (const entry of skillDirs) {
+      if (!entry.isDirectory()) continue;
+      const skillMd = path.join(skillsSource, entry.name, 'SKILL.md');
+      if (!fs.existsSync(skillMd)) continue;
+      const destMd = path.join(skillsDest, entry.name, 'SKILL.md');
+      const destDir = path.dirname(destMd);
+      if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+      if (fs.existsSync(destMd)) {
+        if (fs.statSync(skillMd).mtime <= fs.statSync(destMd).mtime) continue;
+      }
+      fs.copyFileSync(skillMd, destMd);
+      copied++;
+    }
+    if (copied > 0) structuredLog('postinstall', `Skills: ${copied} installed to .opencode/skills/`, 'info');
+  } catch (e) {
+    structuredLog('postinstall', `Skills sync skipped: ${e.message}`, 'warn');
+  }
+}
+
 // Register MCP servers with Grok CLI (if available) using absolute paths to installed dist
 // Full v2 surface: governance + skills + orchestrator + enforcer (additive, preserves prior behavior)
 if (resolvedPackage !== resolvedTarget) {
@@ -41,12 +76,12 @@ if (resolvedPackage !== resolvedTarget) {
     execSync('which grok', { stdio: 'ignore' });
     const govServer = path.join(packageRoot, 'dist/mcps/governance.server.js');
     const skillsServer = path.join(packageRoot, 'dist/mcps/knowledge-skills/skill-invocation.server.js');
-    const orchServer = path.join(packageRoot, 'dist/mcps/orchestrator/server.js');
+    const orchServer = path.join(packageRoot, 'dist/mcps/orchestrator.server.js');
     const enforcerServer = path.join(packageRoot, 'dist/mcps/enforcer-tools.server.js');
     const xrayRoot = targetDir;
 
     execSync(
-      `grok mcp add xray-governance --command node --args "${govServer}" --env "STRRAY_FORCE_MCP_GOVERNANCE=true" --env "XRAY_ROOT=${xrayRoot}"`,
+      `grok mcp add xray-governance --command node --args "${govServer}" --env "XRAY_FORCE_MCP_GOVERNANCE=true" --env "XRAY_ROOT=${xrayRoot}"`,
       { stdio: 'pipe' }
     );
     structuredLog('postinstall', 'Registered xray-governance with Grok CLI', 'info');

package/scripts/node/release.mjs

@@ -98,7 +98,7 @@ async function main() {
   // This removes the brittle "must be exactly one ahead" problem.
   let publishedVersion;
   try {
-    publishedVersion = execSync('npm view xray version', { encoding: 'utf-8' }).trim();
+    publishedVersion = execSync('npm view 0xray version', { encoding: 'utf-8' }).trim();
     console.log(`📌 Latest published on npm: ${publishedVersion}`);
   } catch {
     publishedVersion = '0.0.0';
@@ -154,7 +154,7 @@ async function main() {
   
   // Step 5: Push
   console.log('\n📦 Step 5: Pushing to origin...');
-  runCommand('git push origin master', 'Failed to push to origin');
+  runCommand('git push origin main', 'Failed to push to origin');
   runCommand(`git push origin v${newVersion}`, 'Failed to push tag');
 
   // Step 6: Publish to npm

package/scripts/node/setup-xai-oauth.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * xAI OAuth PKCE setup — saves verifier to temp file so it survives aborts.
+ *
+ * Usage:
+ *   node setup-xai-oauth.mjs              # prints URL, waits for callback
+ *   node setup-xai-oauth.mjs <code>       # exchange previously gotten code
+ *   node setup-xai-oauth.mjs daemon       # non-blocking: prints URL & exits,
+ *                                         # child server handles callback + deploy
+ */
+
+import { randomBytes, createHash } from "node:crypto";
+import { writeFileSync, readFileSync, unlinkSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { fork } from "node:child_process";
+import http from "node:http";
+
+const PORT = 56121;
+const HERMES_AUTH_PATH = join(homedir(), ".hermes", "auth.json");
+const VERIFIER_PATH = join(tmpdir(), "xray-xai-oauth-verifier.txt");
+const XAI_AUTH_URL = "https://auth.x.ai/oauth2/authorize";
+const XAI_TOKEN_URL = "https://auth.x.ai/oauth2/token";
+const XAI_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const REDIRECT_URI = `http://127.0.0.1:${PORT}/callback`;
+
+function generateVerifier() {
+  return randomBytes(32).toString("base64")
+    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+function challenge(verifier) {
+  return createHash("sha256").update(verifier).digest()
+    .toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+function printUrl(verifier) {
+  const codeChallenge = challenge(verifier);
+  const state = randomBytes(16).toString("hex");
+  const nonce = randomBytes(16).toString("hex");
+
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: XAI_CLIENT_ID,
+    redirect_uri: REDIRECT_URI,
+    scope: "openid profile email offline_access grok-cli:access api:access",
+    code_challenge: codeChallenge,
+    code_challenge_method: "S256",
+    state, nonce,
+    plan: "generic",
+    referrer: "hermes-agent",
+  }).toString();
+
+  console.log("\n========================================");
+  console.log("  xAI OAuth Setup");
+  console.log("========================================");
+  console.log("\nOpen this URL in your browser:\n");
+  console.log(`   ${XAI_AUTH_URL}?${params}\n`);
+  console.log("Authorize → callback handled → token saved → Railway deployed.");
+  console.log("You can close the browser tab when it says ✅ Authorized.\n");
+}
+
+async function startServer(verifier) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
+
+      if (url.pathname === "/callback" && url.searchParams.has("code")) {
+        const code = url.searchParams.get("code");
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(wrapHtml("<h1>✅ Authorized!</h1><p>Token saved. Railway deploying. You can close this window.</p>"));
+        try { unlinkSync(VERIFIER_PATH); } catch {}
+        // Give response a moment to send, then close
+        setTimeout(() => { server.close(); resolve(code); }, 100);
+        return;
+      }
+
+      if (url.pathname === "/callback") {
+        res.writeHead(400);
+        res.end("Missing code parameter");
+        return;
+      }
+
+      res.writeHead(404, { "Content-Type": "text/html" });
+      res.end(wrapHtml("<h1>404</h1><p>This server only handles xAI OAuth callbacks.</p>"));
+    });
+
+    server.listen(PORT, "127.0.0.1", () => {
+      // Persist verifier so it survives script abort
+      writeFileSync(VERIFIER_PATH, verifier, "utf-8");
+    });
+
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        console.error(`Port ${PORT} is already in use.`);
+      }
+      reject(err);
+    });
+  });
+}
+
+function wrapHtml(body) {
+  return `<html><head><style>body{font-family:sans-serif;display:flex;justify-content:center;align-items:center;height:100vh;background:#0f172a;color:#e2e8f0;text-align:center}</style></head><body>${body}</body></html>`;
+}
+
+async function exchangeCode(code, verifier) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: REDIRECT_URI,
+    code_verifier: verifier,
+    client_id: XAI_CLIENT_ID,
+  });
+
+  const response = await fetch(XAI_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${text}`);
+  }
+
+  return response.json();
+}
+
+function saveToken(tokens) {
+  const authData = {
+    "xai-oauth": {
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      expires_at: Math.floor(Date.now() / 1000) + (tokens.expires_in || 86400),
+      token_type: tokens.token_type || "Bearer",
+      scope: tokens.scope || "openid profile email offline_access grok-cli:access api:access",
+    },
+  };
+
+  mkdirSync(join(homedir(), ".hermes"), { recursive: true });
+  writeFileSync(HERMES_AUTH_PATH, JSON.stringify(authData, null, 2));
+
+  console.log(`\n✅ Token saved to ${HERMES_AUTH_PATH}`);
+  console.log(`   Expires: ${new Date(Date.now() + (tokens.expires_in || 86400) * 1000).toISOString()}\n`);
+  return authData;
+}
+
+async function deployToRailway() {
+  const { execSync } = await import("node:child_process");
+  const authContent = readFileSync(HERMES_AUTH_PATH, "utf-8");
+  const base64 = Buffer.from(authContent).toString("base64");
+
+  console.log("Setting Railway env var XRAY_HERMES_AUTH...");
+
+  // Use Railway API to set the variable
+  const projectId = execSync("railway project --json 2>/dev/null || echo ''", { encoding: "utf-8" }).trim();
+  console.log("Project info:", projectId || "(no project info)");
+
+  // We need to set the var via Railway env edit API or similar
+  // For now, fall back to railway run with the var
+  try {
+    execSync(`railway env edit --json -v XRAY_HERMES_AUTH="${base64}" 2>/dev/null`, {
+      stdio: "inherit",
+      timeout: 15000,
+    });
+  } catch {
+    // env edit might not support --json; try railway up instead
+    console.log("Attempting deploy with implicit env...");
+  }
+
+  console.log("Deploying to Railway...");
+  try {
+    execSync("railway up --service governance", { stdio: "inherit", timeout: 120000 });
+    console.log("\n✅ Deployed to Railway!");
+  } catch (err) {
+    console.error("\n⚠️  Deploy failed:", err.message);
+    console.log("Token was saved locally. Deploy manually: railway up --service governance");
+  }
+}
+
+// ── Daemon mode (non-blocking) ──────────────────────────────
+async function daemonMain() {
+  const verifier = generateVerifier();
+  printUrl(verifier);
+
+  try {
+    const code = await startServer(verifier);
+    try { unlinkSync(VERIFIER_PATH); } catch {}
+
+    console.log("Exchanging code for tokens...");
+    const tokens = await exchangeCode(code, verifier);
+    saveToken(tokens);
+    await deployToRailway();
+  } catch (err) {
+    console.error("\n❌ Failed:", err.message);
+    try { unlinkSync(VERIFIER_PATH); } catch {}
+    process.exit(1);
+  }
+}
+
+// ── Interactive mode (blocking for code exchange) ────────────
+async function interactiveMain() {
+  const existingCode = process.argv[2];
+
+  let verifier;
+  if (existingCode) {
+    verifier = readFileSync(VERIFIER_PATH, "utf-8").trim();
+    console.log("Using saved verifier from", VERIFIER_PATH);
+  } else {
+    verifier = generateVerifier();
+  }
+
+  try {
+    const code = existingCode || await startServer(verifier);
+    try { unlinkSync(VERIFIER_PATH); } catch {}
+
+    console.log("Exchanging code for tokens...");
+    const tokens = await exchangeCode(code, verifier);
+    saveToken(tokens);
+  } catch (err) {
+    console.error("\n❌ Setup failed:", err.message);
+    process.exit(1);
+  }
+}
+
+// ── Entry ────────────────────────────────────────────────────
+const isDaemon = process.argv[2] === "daemon";
+
+if (isDaemon) {
+  // Fork a child process that runs the daemon so the parent can exit immediately
+  const child = fork(process.argv[1], ["_daemon"], {
+    stdio: ["ignore", "pipe", "pipe", "ipc"],
+    detached: true,
+  });
+  child.stdout.on("data", (d) => process.stdout.write(d));
+  child.stderr.on("data", (d) => process.stderr.write(d));
+  child.unref();
+  // Give child a moment to start and print the URL
+  setTimeout(() => process.exit(0), 500);
+} else if (process.argv[2] === "_daemon") {
+  daemonMain();
+} else {
+  interactiveMain();
+}

package/scripts/node/setup.cjs

@@ -13,6 +13,9 @@ if (__dirname.includes("node_modules/xray")) {
   targetDir = process.env.PWD || process.cwd();
 }
 
+const resolvedPackage = path.resolve(packageRoot);
+const resolvedTarget = path.resolve(targetDir);
+
 console.log("🔧 xray Setup: Full configuration...\n");
 
 const hasHermes = fs.existsSync(path.join(targetDir, ".hermes")) &&
@@ -211,4 +214,29 @@ if (fs.existsSync(hermesSkillSource)) {
   } catch (e) { console.warn(`⚠️ Hermes skill: ${e.message}`); }
 }
 
+// 8. Deploy .xray/ config files (codex.json, features.json, config.json) for consumer installs
+const xraySourceDir = path.join(packageRoot, ".xray");
+const xrayTargetDir = path.join(targetDir, ".xray");
+const CONFIG_FILES = ["codex.json", "features.json", "config.json"];
+
+if (fs.existsSync(xraySourceDir) && resolvedPackage !== resolvedTarget) {
+  try {
+    if (!fs.existsSync(xrayTargetDir)) fs.mkdirSync(xrayTargetDir, { recursive: true });
+    let copied = 0;
+    for (const file of CONFIG_FILES) {
+      const src = path.join(xraySourceDir, file);
+      const dst = path.join(xrayTargetDir, file);
+      if (!fs.existsSync(src)) continue;
+      const shouldCopy = !fs.existsSync(dst) ||
+        fs.statSync(src).mtime > fs.statSync(dst).mtime;
+      if (shouldCopy) {
+        fs.copyFileSync(src, dst);
+        copied++;
+      }
+    }
+    if (copied > 0) console.log(`✅ .xray/: ${copied} config files deployed`);
+    else console.log("ℹ️  .xray/: up to date");
+  } catch (e) { console.warn(`⚠️ .xray/ deploy: ${e.message}`); }
+}
+
 console.log("\n✅ xray setup complete.\n");

package/scripts/node/universal-version-manager.js

@@ -136,9 +136,9 @@ const CALCULATED_COUNTS = calculateCounts();
 const OFFICIAL_VERSIONS = {
   // Framework version
   framework: {
-    version: "3.1.0",
+    version: "3.1.1",
       displayName: "xray: Self-Healing AI Governance OS",
-      lastUpdated: "2026-06-15",
+      lastUpdated: "2026-06-17",
     // Counts (auto-calculated, but can be overridden)
     ...CALCULATED_COUNTS,
   },
@@ -327,29 +327,29 @@ const UPDATE_PATTERNS = [
     },
 
     // === BADGE AND COUNT PATTERNS ===
-    // Test count in docs badge (e.g., tests-2527-brightgreen)
+    // Test count in docs badge (e.g., tests-2500-brightgreen)
     {
       pattern: /tests-[0-9]+(?=-brightgreen)/g,
       replacement: `tests-${OFFICIAL_VERSIONS.framework.tests}`,
     },
-    // Test count in npm badge (e.g., tests-2527%20passed-brightgreen)
+    // Test count in npm badge (e.g., tests-2500%20passed-brightgreen)
     {
       pattern: /tests-[0-9,]+%20passed/g,
       replacement: `tests-${OFFICIAL_VERSIONS.framework.tests}%20passed`,
     },
-    // Test count in prose (e.g., "2,2527 Tests" or "2527 Tests" but NOT in badge URLs)
+    // Test count in prose (e.g., "2,2500 Tests" or "2500 Tests" but NOT in badge URLs)
     {
       pattern: /(\*\s*✅\s*)([0-9]{1,3},?[0-9]{3})(\s*Tests)/g,
       replacement: (match, p1, p2, p3) => {
         return `${p1}${OFFICIAL_VERSIONS.framework.tests}${p3}`;
       },
     },
-    // Test count in feature bullets (e.g., "✅ 2527 Tests")
+    // Test count in feature bullets (e.g., "✅ 2500 Tests")
     {
       pattern: /[0-9]+ Tests/g,
       replacement: `${OFFICIAL_VERSIONS.framework.tests} Tests`,
     },
-    // Test count in config tree (e.g., "2527 tests")
+    // Test count in config tree (e.g., "2500 tests")
     {
       pattern: /[0-9]+ tests/g,
       replacement: `${OFFICIAL_VERSIONS.framework.tests} tests`,
@@ -384,7 +384,7 @@ const UPDATE_PATTERNS = [
       pattern: /xray AI v[0-9]+\.[0-9]+\.[0-9]+/g,
       replacement: `xray AI v${OFFICIAL_VERSIONS.framework.version}`,
     },
-    // Footer bare version (e.g., "**Version**: 1.22.67")
+    // Footer bare version (e.g., "**Version**: 3.1.0")
     {
       pattern: /\*\*Version\*\*:\s*[0-9]+\.[0-9]+\.[0-9]+/g,
       replacement: `**Version**: ${OFFICIAL_VERSIONS.framework.version}`,

package/scripts/node/version-manager.mjs

@@ -308,7 +308,7 @@ function updateAgentsMd(counts) {
   
   // Legacy header count update (min compat for old consumer AGENTS.md files only; xray v2 YML SSOT primary)
   agentsMd = agentsMd.replace(
-    /0xRay\s*2\.0\s*-\s*\d+\s+Agents|StringRay\s*-\s*\d+\s+Agents/,
+    /0xRay\s*2\.0\s*-\s*\d+\s+Agents|0xRay\s*-\s*\d+\s+Agents/,
     `xray v2 - ${counts.agents} Agents`
   );
   

package/src/integrations/grok/plugin/0xray/.mcp.json

@@ -1,23 +1,35 @@
 {
   "mcpServers": {
-    "0xray-governance": {
+    "xray-governance": {
       "command": "npx",
       "args": ["-y", "0xray", "mcp", "governance"],
       "env": {
         "XRAY_FORCE_MCP_GOVERNANCE": "true"
       }
     },
-    "0xray-skills": {
+    "xray-skills": {
       "command": "npx",
       "args": ["-y", "0xray", "mcp", "skills"]
     },
-    "0xray-orchestrator": {
+    "xray-orchestrator": {
       "command": "npx",
       "args": ["-y", "0xray", "mcp", "orchestrator"]
     },
-    "0xray-enforcer": {
+    "xray-enforcer": {
       "command": "npx",
       "args": ["-y", "0xray", "mcp", "enforcer"]
+    },
+    "xray-researcher": {
+      "command": "npx",
+      "args": ["-y", "0xray", "mcp", "researcher"]
+    },
+    "xray-code-review": {
+      "command": "npx",
+      "args": ["-y", "0xray", "mcp", "code-review"]
+    },
+    "xray-architect-tools": {
+      "command": "npx",
+      "args": ["-y", "0xray", "mcp", "architect-tools"]
     }
   }
 }

package/src/integrations/grok/plugin/0xray/hooks/hooks.json

@@ -8,7 +8,7 @@
             "type": "command",
             "command": "node",
             "args": [
-              "${STRRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/pre-tool-use.js"
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/pre-tool-use.js"
             ],
             "timeout": 30000
           }
@@ -21,7 +21,7 @@
           {
             "type": "command",
             "command": "echo",
-            "args": ["[0xRay] Grok session started with StringRay governance enabled"]
+            "args": ["[0xRay] Grok session started with 0xRay governance enabled"]
           }
         ]
       }

package/src/mcps/agent-resolver.ts

@@ -4,7 +4,6 @@
  * Resolves agent configurations from the 0xRay registry.
  * Used by the integration layer to programmatically access agent configs.
  *
- * @version 1.1.0
  * @since 2026-02-14
  */