0xray 3.3.1 → 3.4.2

package/scripts/node/consumer-install-smoke.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * consumer-install-smoke.mjs — Clean-room pack + install verification.
+ *
+ * Simulates what consumers receive from npm without publishing.
+ *
+ * Usage:
+ *   node scripts/node/consumer-install-smoke.mjs
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "../..");
+
+const XRAY_MCP_NAMES = [
+  "xray-governance",
+  "xray-skills",
+  "xray-orchestrator",
+  "xray-enforcer",
+  "xray-researcher",
+  "xray-code-review",
+  "xray-architect-tools",
+];
+
+function run(cmd, cwd, { inherit = false } = {}) {
+  const result = execSync(cmd, {
+    cwd,
+    encoding: inherit ? undefined : "utf-8",
+    stdio: inherit ? "inherit" : "pipe",
+  });
+  return inherit ? "" : String(result).trim();
+}
+
+function main() {
+  console.log("\n=== Consumer Install Smoke ===\n");
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf-8"));
+  const version = pkg.version;
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "0xray-smoke-"));
+  let tarball = null;
+
+  try {
+    console.log("📦 npm pack...");
+    const packOut = run("npm pack --silent", rootDir);
+    tarball = packOut.split("\n").filter(Boolean).pop();
+    const tarballPath = path.join(rootDir, tarball);
+    if (!fs.existsSync(tarballPath)) {
+      throw new Error(`Tarball not found: ${tarballPath}`);
+    }
+
+    const consumerPkg = {
+      name: "0xray-smoke-consumer",
+      private: true,
+      version: "1.0.0",
+      dependencies: {
+        "0xray": `file:${tarballPath}`,
+      },
+    };
+    fs.writeFileSync(
+      path.join(tmpRoot, "package.json"),
+      JSON.stringify(consumerPkg, null, 2) + "\n",
+    );
+
+    console.log("📥 npm install (runs postinstall)...");
+    run("npm install", tmpRoot, { inherit: true });
+
+    const nmRoot = path.join(tmpRoot, "node_modules", "0xray");
+    const requiredFiles = [
+      "scripts/node/install-bridges.cjs",
+      "scripts/node/postinstall.cjs",
+      "package.json",
+      "xray/features.json",
+      "xray/features.schema.json",
+    ];
+
+    for (const rel of requiredFiles) {
+      const full = path.join(nmRoot, rel);
+      if (!fs.existsSync(full)) {
+        throw new Error(`Missing in tarball install: ${rel}`);
+      }
+      console.log(`  ✅ ${rel}`);
+    }
+
+    const installedPkg = JSON.parse(fs.readFileSync(path.join(nmRoot, "package.json"), "utf-8"));
+    if (installedPkg.version !== version) {
+      throw new Error(`Installed version ${installedPkg.version} != packed ${version}`);
+    }
+
+    const bridges = require(path.join(nmRoot, "scripts/node/install-bridges.cjs"));
+    for (const exp of ["installAllBridges", "resolveConsumerTargetDir", "isConsumerInstall"]) {
+      if (typeof bridges[exp] !== "function") {
+        throw new Error(`install-bridges missing export: ${exp}`);
+      }
+    }
+    console.log("  ✅ install-bridges exports");
+
+    if (!bridges.isConsumerInstall(nmRoot, tmpRoot)) {
+      throw new Error("isConsumerInstall should be true for node_modules/0xray → project root");
+    }
+    console.log("  ✅ consumer target resolution");
+
+    // Postinstall should have run; verify .mcp.json merge
+    const mcpPath = path.join(tmpRoot, ".mcp.json");
+    if (!fs.existsSync(mcpPath)) {
+      throw new Error(".mcp.json not created by postinstall");
+    }
+    const mcp = JSON.parse(fs.readFileSync(mcpPath, "utf-8"));
+    const servers = Object.keys(mcp.mcpServers || {});
+    for (const name of XRAY_MCP_NAMES) {
+      if (!servers.includes(name)) {
+        throw new Error(`Missing MCP server in .mcp.json: ${name}`);
+      }
+      const entry = mcp.mcpServers[name];
+      if (entry.command !== "npx") {
+        throw new Error(`${name} should use npx, got ${entry.command}`);
+      }
+    }
+    console.log(`  ✅ .mcp.json has ${XRAY_MCP_NAMES.length} npx MCP servers`);
+
+    const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
+    if (!fs.existsSync(consumerFeaturesPath)) {
+      throw new Error(".xray/features.json not deployed to consumer project by postinstall");
+    }
+    const features = JSON.parse(fs.readFileSync(consumerFeaturesPath, "utf-8"));
+    if (!features.memory_routing) {
+      throw new Error("Deployed features.json missing memory_routing block");
+    }
+    console.log("  ✅ .xray/features.json deployed with memory_routing");
+
+    const schemaInPackage = path.join(nmRoot, "xray", "features.schema.json");
+    if (!fs.existsSync(schemaInPackage)) {
+      throw new Error("xray/features.schema.json missing from installed package");
+    }
+    console.log("  ✅ xray/features.schema.json in package");
+
+    console.log("\n✅ Consumer install smoke passed\n");
+  } catch (err) {
+    console.error(`\n❌ Consumer smoke failed: ${err.message}\n`);
+    process.exit(1);
+  } finally {
+    if (tarball) {
+      try {
+        fs.unlinkSync(path.join(rootDir, tarball));
+      } catch {
+        /* best-effort */
+      }
+    }
+    try {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+main();

package/scripts/node/enforce-agents-md.mjs

@@ -1,12 +1,5 @@
 #!/usr/bin/env node
 /**
- * AGENTS.md Enforcement Script
- * 
- * Validates that AGENTS.md exists, is up-to-date, and follows the required format.
- * This script should be run in CI/CD, pre-commit hooks, and local validation.
- * 
- * @version 1.0.0
- * @framework xray v2
  */
 
 import fs from 'fs';
@@ -62,7 +55,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Run all validation checks
    */
   async validate() {
     console.log('🔍 AGENTS.md Enforcement Check');
@@ -148,14 +140,12 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Check if AGENTS.md file exists
    */
   checkFileExists() {
     return fs.existsSync(this.agentsPath);
   }
 
   /**
-   * Check for required sections
    */
   checkRequiredSections(content) {
     const missing = [];
@@ -188,7 +178,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Check for required agent definitions
    */
   checkRequiredAgents(content) {
     // Be flexible - check for agent names with or without @ prefix
@@ -199,7 +188,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Extract version from header
    */
   extractVersion(content) {
     const match = content.match(/\*\*Version\*\*:\s*(\d+\.\d+\.\d+)/);
@@ -207,7 +195,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Extract date from header
    */
   extractDate(content) {
     const match = content.match(/\*\*Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/);
@@ -215,7 +202,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Calculate how many days old the file is
    */
   calculateDaysOld(dateString) {
     const date = new Date(dateString);
@@ -225,18 +211,12 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Calculate content hash
    */
   calculateHash(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
   }
 
   /**
-   * Count codex terms (numbered rules or sections with multiple items)
-   * Looks for patterns like:
-   * - #### 1. Something
-   * - 1. **Something**
-   * - ## CRITICAL RULES (count as one term block)
    */
   countCodexTerms(content) {
     // Count #### numbered items
@@ -257,7 +237,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Log individual check result
    */
   logResult(check, status, message) {
     const icon = status === 'PASS' ? '✅' : status === 'FAIL' ? '❌' : status === 'WARN' ? '⚠️' : 'ℹ️';
@@ -266,7 +245,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Generate and display report
    */
   report(exitCode) {
     console.log('\n================================');
@@ -309,7 +287,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Auto-generate AGENTS.md from current agent configuration
    */
   async generate() {
     console.log('📝 Generating AGENTS.md...\n');
@@ -325,7 +302,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Load template file
    */
   async loadTemplate() {
     const templatePath = path.join(__dirname, '..', '..', '..', 'docs', 'AGENTS_TEMPLATE.md');
@@ -342,7 +318,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Discover agents from configuration
    */
   async discoverAgents() {
     const agents = [];
@@ -366,7 +341,6 @@ class AgentsMdEnforcer {
   }
 
   /**
-   * Populate template with agent data
    */
   populateTemplate(template, agents) {
     const now = new Date().toISOString().split('T')[0];

package/scripts/node/enforce-version-compliance.sh

@@ -7,7 +7,6 @@
 #
 # Usage: ./scripts/node/enforce-version-compliance.sh
 #
-# @version 1.0.0
 # @since 2026-01-15
 
 set -e

package/scripts/node/enforce-version-compliance.ts

@@ -1,15 +1,5 @@
 #!/usr/bin/env node
 /**
- * Version Compliance Enforcement Script
- *
- * Thin CLI wrapper around VersionComplianceProcessor.
- * Called by CI/CD, pre-commit hooks, and manual runs.
- *
- * This script should NOT contain enforcement logic - 
- * all logic lives in src/processors/version-compliance-processor.ts
- *
- * @version 1.0.0
- * @deprecated Use VersionComplianceProcessor directly in new code
  */
 
 import path from 'path';

package/scripts/node/install-bridges.cjs

@@ -10,19 +10,37 @@ const os = require("os");
 const { execSync } = require("child_process");
 
 const SKIP_DIRS = new Set(["node_modules", "logs"]);
-const MERGE_FILES = new Set(["xray/features.json", "enforcer-config.json"]);
+const MERGE_FILES = new Set(["enforcer-config.json"]);
 const KEEP_IF_EXISTS = new Set([".yml", ".yaml", ".md"]);
 
+/** Canonical 7-server MCP surface — matches package .mcp.json and Grok plugin */
+const XRAY_MCP_SERVERS = [
+  { name: "xray-governance", mcpCmd: "governance", env: { XRAY_FORCE_MCP_GOVERNANCE: "true" } },
+  { name: "xray-skills", mcpCmd: "skills", env: {} },
+  { name: "xray-orchestrator", mcpCmd: "orchestrator", env: {} },
+  { name: "xray-enforcer", mcpCmd: "enforcer", env: {} },
+  { name: "xray-researcher", mcpCmd: "researcher", env: {} },
+  { name: "xray-code-review", mcpCmd: "code-review", env: {} },
+  { name: "xray-architect-tools", mcpCmd: "architect-tools", env: {} },
+];
+
 function resolveConsumerTargetDir(packageRoot, fallbackDir) {
-  const resolvedPackage = path.resolve(packageRoot);
-  if (resolvedPackage.includes(`${path.sep}node_modules${path.sep}`)) {
-    let current = resolvedPackage;
-    while (current.includes(`${path.sep}node_modules${path.sep}`)) {
-      current = path.dirname(current);
-    }
-    return current;
+  const resolved = path.resolve(packageRoot);
+  const inNodeModules =
+    resolved.includes(`${path.sep}node_modules${path.sep}`) ||
+    resolved.endsWith(`${path.sep}node_modules`);
+
+  if (!inNodeModules) {
+    return fallbackDir || process.env.PWD || process.cwd();
+  }
+
+  let current = resolved;
+  while (path.basename(current) !== "node_modules") {
+    const parent = path.dirname(current);
+    if (parent === current) return fallbackDir || process.cwd();
+    current = parent;
   }
-  return fallbackDir || process.env.PWD || process.cwd();
+  return path.dirname(current);
 }
 
 function isConsumerInstall(packageRoot, targetDir) {
@@ -108,6 +126,91 @@ function copyPluginDir(src, dest) {
   return true;
 }
 
+function buildConsumerMcpConfig(targetDir) {
+  const mcpServers = {};
+  for (const s of XRAY_MCP_SERVERS) {
+    mcpServers[s.name] = {
+      command: "npx",
+      args: ["-y", "0xray", "mcp", s.mcpCmd],
+      env: { ...s.env, XRAY_ROOT: targetDir },
+    };
+  }
+  return { mcpServers };
+}
+
+function deployProjectMcpJson(targetDir, log) {
+  const destPath = path.join(targetDir, ".mcp.json");
+  const consumerConfig = buildConsumerMcpConfig(targetDir);
+  let existing = { mcpServers: {} };
+  if (fs.existsSync(destPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(destPath, "utf8"));
+    } catch {
+      existing = { mcpServers: {} };
+    }
+  }
+  const merged = {
+    ...existing,
+    mcpServers: { ...(existing.mcpServers || {}), ...consumerConfig.mcpServers },
+  };
+  fs.writeFileSync(destPath, JSON.stringify(merged, null, 2) + "\n");
+  log("mcp-config", "project .mcp.json deployed (7 xray servers)", "info");
+}
+
+function writePluginMcpJson(pluginDir, targetDir, log, label) {
+  if (!fs.existsSync(pluginDir)) return;
+  const dest = path.join(pluginDir, ".mcp.json");
+  fs.writeFileSync(dest, JSON.stringify(buildConsumerMcpConfig(targetDir), null, 2) + "\n");
+  log(label, "plugin .mcp.json patched for consumer", "info");
+}
+
+function mergeOpencodeJson(targetDir, packageRoot, log) {
+  const rootOpencode = path.join(packageRoot, "opencode.json");
+  const userOpencode = path.join(targetDir, "opencode.json");
+  if (!fs.existsSync(rootOpencode)) return;
+
+  try {
+    const srcData = JSON.parse(fs.readFileSync(rootOpencode, "utf8"));
+    if (fs.existsSync(userOpencode)) {
+      const destData = JSON.parse(fs.readFileSync(userOpencode, "utf8"));
+      const merged = { ...destData };
+      if (srcData.agent) merged.agent = srcData.agent;
+      if (srcData.mcp) merged.mcp = { ...destData.mcp, ...srcData.mcp };
+      if (srcData.compaction) merged.compaction = srcData.compaction;
+      fs.writeFileSync(userOpencode, JSON.stringify(merged, null, 2) + "\n");
+    } else {
+      fs.copyFileSync(rootOpencode, userOpencode);
+    }
+    log("opencode-bridge", "opencode.json merged", "info");
+  } catch (e) {
+    log("opencode-bridge", "opencode.json merge failed", "warn", { error: e.message });
+  }
+}
+
+function patchGrokHooks(pluginDir, packageRoot, targetDir, log, label) {
+  const hooksPath = path.join(pluginDir, "hooks", "hooks.json");
+  const hookScript = path.join(packageRoot, "dist", "integrations", "grok", "hooks", "pre-tool-use.js");
+  if (!fs.existsSync(hooksPath)) return;
+
+  try {
+    const hooks = JSON.parse(fs.readFileSync(hooksPath, "utf8"));
+    const preTool = hooks.hooks?.PreToolUse?.[0]?.hooks?.[0];
+    if (preTool && fs.existsSync(hookScript)) {
+      preTool.command = "node";
+      preTool.args = [hookScript];
+      preTool.env = {
+        ...(preTool.env || {}),
+        XRAY_ROOT: targetDir,
+        XRAY_AI_PATH: packageRoot,
+      };
+      fs.writeFileSync(hooksPath, JSON.stringify(hooks, null, 2) + "\n");
+      log(label, "hooks.json patched → enforcement gate", "info");
+    }
+  } catch (e) {
+    log(label, "hooks.json patch failed", "warn", { error: e.message });
+  }
+}
+
 function installOpencodeBridge(targetDir, packageRoot, log) {
   const opencodeSource = path.join(packageRoot, ".opencode");
   const opencodeDest = path.join(targetDir, ".opencode");
@@ -149,37 +252,25 @@ function findGrokPluginSource(packageRoot) {
   return candidates.find((p) => fs.existsSync(p));
 }
 
-function registerGrokMcpServers(packageRoot, targetDir, log) {
+function registerGrokMcpServers(targetDir, log) {
   try {
     execSync("which grok", { stdio: "ignore" });
   } catch {
-    log("grok-bridge", "grok CLI not on PATH — skipped MCP registration", "info");
+    log("grok-bridge", "grok CLI not on PATH — plugin .mcp.json still configured", "info");
     return;
   }
 
-  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 enforcerServer = path.join(packageRoot, "dist/mcps/enforcer-tools.server.js");
-
-  const servers = [
-    ["xray-governance", govServer, `XRAY_FORCE_MCP_GOVERNANCE=true`],
-    ["xray-skills", skillsServer, null],
-    ["xray-orchestrator", orchServer, null],
-    ["xray-enforcer", enforcerServer, null],
-  ];
-
-  for (const [name, serverPath, extraEnv] of servers) {
-    if (!fs.existsSync(serverPath)) continue;
+  for (const s of XRAY_MCP_SERVERS) {
     try {
-      const envFlags = extraEnv
-        ? `--env "${extraEnv}" --env "XRAY_ROOT=${targetDir}"`
-        : `--env "XRAY_ROOT=${targetDir}"`;
+      const envEntries = { ...s.env, XRAY_ROOT: targetDir };
+      const envFlags = Object.entries(envEntries)
+        .map(([k, v]) => `--env "${k}=${v}"`)
+        .join(" ");
       execSync(
-        `grok mcp add ${name} --command node --args "${serverPath}" ${envFlags}`,
+        `grok mcp add ${s.name} --command npx --args "-y" "0xray" "mcp" "${s.mcpCmd}" ${envFlags}`,
         { stdio: "pipe" }
       );
-      log("grok-bridge", `registered ${name}`, "info");
+      log("grok-bridge", `registered ${s.name} (npx)`, "info");
     } catch {
       // already registered or grok config conflict — non-blocking
     }
@@ -217,6 +308,8 @@ function installGrokBridge(targetDir, packageRoot, log) {
     if (copyPluginDir(sourceDir, dest)) {
       const rel = dest.startsWith(home) ? dest.replace(home, "~") : path.relative(targetDir, dest);
       log("grok-bridge", "plugin copied", "info", { path: rel || dest });
+      writePluginMcpJson(dest, targetDir, log, "grok-bridge");
+      patchGrokHooks(dest, packageRoot, targetDir, log, "grok-bridge");
       const copied = syncBuiltinSkills(path.join(dest, "skills"), packageRoot);
       if (copied > 0) log("grok-bridge", `plugin skills synced (${copied})`, "info", { path: rel });
     }
@@ -229,10 +322,10 @@ function installGrokBridge(targetDir, packageRoot, log) {
     log("grok-bridge", `global skills synced (${globalCopied})`, "info", { path: "~/.grok/skills/" });
   }
 
-  registerGrokMcpServers(packageRoot, targetDir, log);
+  registerGrokMcpServers(targetDir, log);
 }
 
-function installHermesBridge(packageRoot, log) {
+function installHermesBridge(targetDir, packageRoot, log) {
   const sources = [
     path.join(packageRoot, "dist", "integrations", "hermes-agent"),
     path.join(packageRoot, "src", "integrations", "hermes-agent"),
@@ -256,8 +349,15 @@ function installHermesBridge(packageRoot, log) {
   }
   log("hermes-bridge", "plugin copied", "info", { path: "~/.hermes/plugins/xray-hermes" });
 
+  writePluginMcpJson(targetPluginDir, targetDir, log, "hermes-bridge");
+
   const copied = syncBuiltinSkills(path.join(targetPluginDir, "skills"), packageRoot);
   if (copied > 0) log("hermes-bridge", `skills synced (${copied})`, "info");
+
+  // Marker so bridge.mjs resolves the consumer project on hook invocation
+  const rootMarker = path.join(targetPluginDir, "xray-consumer-root.txt");
+  fs.writeFileSync(rootMarker, targetDir + "\n");
+  log("hermes-bridge", "consumer root marker written", "info");
 }
 
 function installOpenclawBridge(targetDir, packageRoot, log) {
@@ -297,18 +397,27 @@ function installOpenclawBridge(targetDir, packageRoot, log) {
   if (copied > 0) log("openclaw-bridge", `skills synced (${copied})`, "info", { path: "~/.openclaw/skills/" });
 }
 
+const XRAY_CONFIG_FILES = ["codex.json", "features.json", "features.schema.json", "config.json"];
+
+function resolveXrayConfigSource(packageRoot, file) {
+  const dotXray = path.join(packageRoot, ".xray", file);
+  if (fs.existsSync(dotXray)) return dotXray;
+  const xrayDir = path.join(packageRoot, "xray", file);
+  if (fs.existsSync(xrayDir)) return xrayDir;
+  return null;
+}
+
 function deployXrayConfig(targetDir, packageRoot, log) {
-  const xraySourceDir = path.join(packageRoot, ".xray");
   const xrayTargetDir = path.join(targetDir, ".xray");
-  const configFiles = ["codex.json", "features.json", "config.json"];
-  if (!fs.existsSync(xraySourceDir)) return;
+  const hasAnySource = XRAY_CONFIG_FILES.some((file) => resolveXrayConfigSource(packageRoot, file));
+  if (!hasAnySource) return;
 
   if (!fs.existsSync(xrayTargetDir)) fs.mkdirSync(xrayTargetDir, { recursive: true });
   let copied = 0;
-  for (const file of configFiles) {
-    const src = path.join(xraySourceDir, file);
+  for (const file of XRAY_CONFIG_FILES) {
+    const src = resolveXrayConfigSource(packageRoot, file);
     const dst = path.join(xrayTargetDir, file);
-    if (!fs.existsSync(src)) continue;
+    if (!src) continue;
     const shouldCopy = !fs.existsSync(dst) || fs.statSync(src).mtime > fs.statSync(dst).mtime;
     if (shouldCopy) {
       fs.copyFileSync(src, dst);
@@ -316,6 +425,7 @@ function deployXrayConfig(targetDir, packageRoot, log) {
     }
   }
   if (copied > 0) log("xray-config", `${copied} files deployed`, "info", { path: ".xray/" });
+  return copied;
 }
 
 function installGitHooks(packageRoot, log) {
@@ -347,9 +457,11 @@ function installAllBridges(opts) {
   log("install-bridges", "starting 4-platform install", "info");
 
   deployXrayConfig(targetDir, packageRoot, log);
+  deployProjectMcpJson(targetDir, log);
+  mergeOpencodeJson(targetDir, packageRoot, log);
   installOpencodeBridge(targetDir, packageRoot, log);
   installGrokBridge(targetDir, packageRoot, log);
-  installHermesBridge(packageRoot, log);
+  installHermesBridge(targetDir, packageRoot, log);
   installOpenclawBridge(targetDir, packageRoot, log);
   installGitHooks(packageRoot, log);
 
@@ -361,4 +473,7 @@ module.exports = {
   resolveConsumerTargetDir,
   syncBuiltinSkills,
   isConsumerInstall,
+  deployXrayConfig,
+  resolveXrayConfigSource,
+  XRAY_CONFIG_FILES,
 };