0xray 4.0.27 → 4.0.29

package/scripts/node/mcp-launch.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Start an MCP server with an allowlisted environment.
+ *
+ *   node mcp-launch.cjs --keep PATH,HOME,XRAY_ROOT[,NAME...] -- <cmd> [args...]
+ *
+ * argv carries names only. The host merges the config `env` block onto this
+ * process, so values come from the live environment. The child receives
+ * process.env filtered to those names. stdio is inherited. Signals and the
+ * exit code are forwarded.
+ */
+const { spawn } = require("child_process");
+
+function fail(message) {
+  process.stderr.write(`mcp-launch: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const keepIdx = argv.indexOf("--keep");
+  const dash = argv.indexOf("--");
+  if (keepIdx < 0 || dash < 0 || dash !== keepIdx + 2 || dash >= argv.length - 1) {
+    fail("usage: node mcp-launch.cjs --keep NAME[,NAME...] -- <cmd> [args...]");
+  }
+  const keep = argv[keepIdx + 1]
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+  if (keep.length === 0) fail("--keep needs at least one name");
+  for (const name of keep) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) fail(`refusing keep name ${name}`);
+  }
+  return { keep, command: argv[dash + 1], args: argv.slice(dash + 2) };
+}
+
+function childEnv(keep) {
+  const env = {};
+  for (const name of keep) {
+    if (process.env[name] != null) env[name] = process.env[name];
+  }
+  return env;
+}
+
+function main() {
+  const { keep, command, args } = parseArgs(process.argv.slice(2));
+  const child = spawn(command, args, { env: childEnv(keep), stdio: "inherit" });
+  const forward = (signal) => {
+    if (!child.pid) return;
+    try {
+      child.kill(signal);
+    } catch {
+      /* child already exited */
+    }
+  };
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => forward(signal));
+  }
+  child.on("error", (err) => fail(err.message));
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code == null ? 1 : code);
+  });
+}
+
+main();

package/scripts/node/postinstall.cjs

@@ -2,12 +2,8 @@
 
 const fs = require("fs");
 const path = require("path");
-const {
-  installAllBridges,
-  resolveConsumerTargetDir,
-  isConsumerInstall,
-} = require("./install-bridges.cjs");
-const { applyConsumerGitignore } = require("./consumer-gitignore.cjs");
+const { resolveConsumerTargetDir } = require("./install-bridges.cjs");
+const { linkVendoredRepertoire } = require("./wear-vendored-repertoire.cjs");
 const {
   overlayConsumerTree,
   mintConsumerFromSsot,
@@ -18,13 +14,9 @@ const {
   readPackageIdentity,
 } = require("../foundry/mint-suit.cjs");
 
-function structuredLog(component, action, status, details) {
-  const ts = new Date().toISOString();
-  const detailsPart = details ? ` | ${JSON.stringify(details)}` : "";
-  console.log(`${ts} [${component}] ${action} - ${String(status).toUpperCase()}${detailsPart}`);
-}
-
 const XRAY_MANAGED_AGENTS_MARKER = "<!-- 0xray-managed -->";
+const XRAY_MANAGED_AGENTS_BEGIN = "<!-- 0xray-managed:begin -->";
+const XRAY_MANAGED_AGENTS_END = "<!-- 0xray-managed:end -->";
 
 function fillConsumerPlaceholders(content, consumer) {
   const name = consumer.name || "this project";
@@ -36,73 +28,57 @@ function fillConsumerPlaceholders(content, consumer) {
     .join(versionParen);
 }
 
-function deployManagedAgents(packageRoot, targetDir, log) {
-  const agentsConsumer = path.join(packageRoot, "AGENTS-consumer.md");
-  const agentsDest = path.join(targetDir, "AGENTS.md");
-  if (!fs.existsSync(agentsConsumer)) return;
-  const shouldDeployAgents =
-    !fs.existsSync(agentsDest) ||
-    fs.readFileSync(agentsDest, "utf8").includes(XRAY_MANAGED_AGENTS_MARKER);
-  if (shouldDeployAgents) {
-    let content = fs.readFileSync(agentsConsumer, "utf8");
-    const consumer = readPackageIdentity(path.join(targetDir, "package.json"));
-    content = fillConsumerPlaceholders(content, consumer);
-    if (!content.includes(XRAY_MANAGED_AGENTS_MARKER)) {
-      content = `${content.trimEnd()}\n\n${XRAY_MANAGED_AGENTS_MARKER}\n`;
-    }
-    fs.writeFileSync(agentsDest, content);
-  } else {
-    log("postinstall", "Skipped AGENTS.md (consumer-customized)", "info");
+function renderManagedAgents(packageRoot, targetDir) {
+  let content = fs.readFileSync(path.join(packageRoot, "AGENTS-consumer.md"), "utf8");
+  const consumer = readPackageIdentity(path.join(targetDir, "package.json"));
+  content = fillConsumerPlaceholders(content, consumer).trim();
+  if (!content.includes(XRAY_MANAGED_AGENTS_MARKER)) {
+    content = `${content}\n\n${XRAY_MANAGED_AGENTS_MARKER}`;
   }
+  return `${XRAY_MANAGED_AGENTS_BEGIN}\n${content}\n${XRAY_MANAGED_AGENTS_END}\n`;
 }
 
-function deployConsumerGitignore(packageRoot, targetDir, log) {
-  const gitignoreResult = applyConsumerGitignore(targetDir, packageRoot);
-  if (gitignoreResult === "created") {
-    log("postinstall", "Created .gitignore from template", "info");
-  } else if (gitignoreResult === "merged") {
-    log("postinstall", "Merged 0xray suit entries into .gitignore", "info");
-  }
+function managedRegion(text) {
+  const beginAt = text.indexOf(XRAY_MANAGED_AGENTS_BEGIN);
+  const endAt = text.indexOf(XRAY_MANAGED_AGENTS_END);
+  if (beginAt === -1 || endAt === -1 || endAt < beginAt) return null;
+  return {
+    before: text.slice(0, beginAt),
+    after: text.slice(endAt + XRAY_MANAGED_AGENTS_END.length),
+  };
 }
 
-/**
- * Wear bridges for consumers (full 4-platform) and the framework repo (dogfood).
- * installAllBridges already decides which path.
- */
-function runPostinstall(packageRoot, targetDir, log) {
-  const logFn = log || structuredLog;
-  const resolvedPackage = path.resolve(packageRoot);
-  const resolvedTarget = path.resolve(targetDir);
-  const consumer = isConsumerInstall(resolvedPackage, resolvedTarget);
+function outsideRegionEdited(parts) {
+  return parts.before.trim() !== "" || parts.after.trim() !== "";
+}
 
-  if (consumer) {
-    deployManagedAgents(resolvedPackage, resolvedTarget, logFn);
-    deployConsumerGitignore(resolvedPackage, resolvedTarget, logFn);
+function deployManagedAgents(packageRoot, targetDir, log) {
+  const agentsConsumer = path.join(packageRoot, "AGENTS-consumer.md");
+  const agentsDest = path.join(targetDir, "AGENTS.md");
+  if (!fs.existsSync(agentsConsumer)) return;
+  const next = renderManagedAgents(packageRoot, targetDir);
+  if (!fs.existsSync(agentsDest)) {
+    fs.writeFileSync(agentsDest, next);
+    return;
   }
-
-  try {
-    installAllBridges({
-      targetDir: resolvedTarget,
-      packageRoot: resolvedPackage,
-      log: logFn,
-    });
-    if (consumer) {
-      mintConsumerSuit(resolvedPackage, resolvedTarget, logFn);
-    }
-  } catch (e) {
-    logFn("postinstall", "Bridge install failed", "error", { error: e.message });
-    throw e;
+  const current = fs.readFileSync(agentsDest, "utf8");
+  const parts = managedRegion(current);
+  if (!parts || outsideRegionEdited(parts)) {
+    fs.writeFileSync(path.join(targetDir, "AGENTS.md.0xray-new"), next);
+    log("postinstall", "AGENTS.md left in place; wrote AGENTS.md.0xray-new", "info");
+    return;
   }
+  const beginAt = next.indexOf(XRAY_MANAGED_AGENTS_BEGIN);
+  const endAt = next.indexOf(XRAY_MANAGED_AGENTS_END);
+  const interior = next.slice(beginAt, endAt + XRAY_MANAGED_AGENTS_END.length);
+  const updated = `${parts.before}${interior}${parts.after}`;
+  if (updated !== current) fs.writeFileSync(agentsDest, updated);
+}
 
-  if (consumer) {
-    logFn(
-      "postinstall",
-      "0xRay framework installed (4 bridges). Run `npx 0xray setup` for symlinks/Hermes skill extras.",
-      "success",
-    );
-  } else {
-    logFn("postinstall", "framework dogfood wear complete", "success");
-  }
+/** npm install links vendored @0xray/repertoire and nothing else. The suit is `npx 0xray wear`. */
+function runPostinstall(packageRoot, targetDir, _log) {
+  linkVendoredRepertoire(packageRoot, targetDir);
+  console.log("Run `npx 0xray wear`");
 }
 
 module.exports = {

package/scripts/node/unwear-cursor-hooks.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Remove the Cursor suit. Prints "restored" only when the file bytes match
+ * the snapshot exactly. A mismatch keeps the snapshot and exits non-zero.
+ *
+ *   npx 0xray unwear
+ *   node node_modules/0xray/scripts/node/unwear-cursor-hooks.cjs [project]
+ */
+const path = require("path");
+const { unwearCursorHooks } = require("./install-bridges.cjs");
+
+const target = path.resolve(process.argv[2] || process.cwd());
+let restored = false;
+try {
+  restored = unwearCursorHooks(target);
+} catch (err) {
+  process.stderr.write(`${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+}
+if (!restored) process.exit(1);
+process.stdout.write(`unwear: restored cursor hooks at ${target}\n`);

package/scripts/node/wear-cursor-hooks.cjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Wear the Cursor suit in a git work tree.
+ *   npx 0xray wear
+ *   node node_modules/0xray/scripts/node/wear-cursor-hooks.cjs [project]
+ */
+const path = require("path");
+const { wearCursorHooks } = require("./install-bridges.cjs");
+
+const target = path.resolve(process.argv[2] || process.cwd());
+const packageRoot = path.resolve(__dirname, "..", "..");
+try {
+  wearCursorHooks(target, packageRoot, () => {});
+} catch (err) {
+  process.stderr.write(`${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+}

package/scripts/node/wear-vendored-repertoire.cjs

@@ -122,6 +122,38 @@ function wearDestinations(packageRoot, targetDir) {
   return dests;
 }
 
+function repertoireLinkDest(targetDir) {
+  return path.join(targetDir, "node_modules", "@0xray", "repertoire");
+}
+
+function relativeRepertoireLink(vendor, dest) {
+  return path.relative(path.dirname(dest), vendor);
+}
+
+/**
+ * Create one relative symlink at <target>/node_modules/@0xray/repertoire.
+ * A real directory or a symlink that is not this link is left in place.
+ */
+function linkVendoredRepertoire(packageRoot, targetDir) {
+  const vendor = resolveVendoredRepertoire(packageRoot);
+  if (!vendor) return { linked: false, vendor: null, dest: null };
+  const dest = repertoireLinkDest(targetDir);
+  const rel = relativeRepertoireLink(vendor, dest);
+  try {
+    const st = fs.lstatSync(dest);
+    if (st.isSymbolicLink() && fs.readlinkSync(dest) === rel) {
+      return { linked: true, vendor, dest, unchanged: true };
+    }
+    return { linked: false, vendor, dest, skipped: true };
+  } catch {
+    /* dest absent */
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  fs.symlinkSync(rel, dest, linkType);
+  return { linked: true, vendor, dest, unchanged: false };
+}
+
 function wearVendoredRepertoire(packageRoot, targetDir, log) {
   const vendor = resolveVendoredRepertoire(packageRoot);
   if (!vendor) return { worn: [], vendor: null };
@@ -153,6 +185,9 @@ function hasFileProtocolDependency(pkg) {
 module.exports = {
   resolveVendoredRepertoire,
   wearVendoredRepertoire,
+  linkVendoredRepertoire,
+  relativeRepertoireLink,
+  repertoireLinkDest,
   wearDestinations,
   hasFileProtocolDependency,
 };

package/src/integrations/openclaw/plugin/xray-pre-tool/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xray-pre-tool",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "private": true,
   "type": "module",
   "description": "0xRay constitution + temperament PreToolUse for OpenClaw",

package/xray/features.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./features.schema.json",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "description": "0xRay Framework - Unified Feature Configuration",
   "suit_temperament": {
     "profile": "auto",