fix(build): exec native esbuild binary directly in prepublish (dast-smoke base-red) (#9558)

* fix(build): exec native tool binaries directly in runBuildTool

#8858 routed every resolved local bin through process.execPath to avoid
Windows .cmd shims — but esbuild >=0.25 ships bin/esbuild as the NATIVE
platform executable (ELF on Linux), so Node parsed machine code as JS and
build:cli died with 'SyntaxError: Invalid or unexpected token', turning
dast-smoke red for every PR.

runBuildTool now sniffs the entry's magic bytes (ELF / Mach-O / PE) and
execs native binaries directly; JS entries keep going through this Node
binary (the .cmd-shim avoidance #8858 wanted).

Validation (RED->GREEN on this box):
- RED: node node_modules/esbuild/bin/esbuild --version -> SyntaxError (ELF)
- GREEN: the exact failing CI step reproduced via the new logic bundles
  open-sse/mcp-server/server.ts successfully (4.2MB output, 1.3s).

* fix(docs): add MDX frontmatter to the 20 remaining docs without it

Same failure class as AGENTROUTER_WAF (#9503) and DOCKER_RELEASE_CHANNELS
(this run's dast-smoke red): any doc without frontmatter breaks the
fumadocs MDX loader during next build, killing build:cli/dast-smoke for
every PR. Swept ALL of docs/ (i18n mirrors excluded) in one pass so this
class cannot recur one file at a time.

* docs(env): document OMNIROUTE_INTERNAL_SERVICE_TOKEN(+_FILE), OPENROUTER_PROVIDER_STATS_* and embedded-Redis binding vars

Pre-existing env/docs contract drift from recently merged features made
check:env-doc-sync red for any docs-touching PR. Values and defaults read
from the defining modules (internalServiceAuth.ts, openrouterProviderStats.ts).

* fix(build): resolve bundled npm-cli.js in the standard Unix layout + safe npm fallback off-Windows

The opencode-plugin step hard-failed on GitHub runners because
resolveBundledNpmEntry only looked next to the node binary (Windows zip
layout); hostedtoolcache Node keeps npm at <prefix>/lib/node_modules/npm.
Added that candidate, and when neither exists on non-Windows the step now
falls back to plain 'npm' — the .cmd-shim hazard #8858 avoids is
Windows-only.

* test(mutation): register xai-agent-tools-passthrough.test.ts in stryker tap.testFiles

The test landed on release/v3.8.50 covering
open-sse/handlers/chatCore/passthroughHelpers.ts without the stryker
registration, so Fast Quality Gates' drift detection reds any PR that
carries it. Mechanical registration so its mutant kills count.

---------

Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>

scripts/build/prepublish.ts

@@ -22,6 +22,9 @@ import {
   readdirSync,
   statSync,
   chmodSync,
+  openSync,
+  readSync,
+  closeSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -70,6 +73,30 @@ function resolveLocalBinEntry(packageName: string, binName: string): string | nu
  * tool lives in the local dependency tree; when it is not installed there the call
  * falls back to the Node-resolved `npx` entry point, and only then to the shim.
  */
+/**
+ * esbuild ≥0.25 ships its `bin/esbuild` as the NATIVE platform executable on
+ * Linux/macOS (ELF / Mach-O) instead of a JS shim — running it through
+ * `process.execPath` makes Node parse machine code as JavaScript and crash with
+ * "SyntaxError: Invalid or unexpected token". Sniff the magic bytes and exec
+ * native entries directly; JS entries keep going through this Node binary.
+ */
+function isNativeExecutable(entryPath: string): boolean {
+  try {
+    const fd = openSync(entryPath, "r");
+    const head = Buffer.alloc(4);
+    readSync(fd, head, 0, 4, 0);
+    closeSync(fd);
+    return (
+      (head[0] === 0x7f && head[1] === 0x45 && head[2] === 0x4c && head[3] === 0x46) || // ELF
+      head.readUInt32BE(0) === 0xfeedfacf || // Mach-O 64
+      head.readUInt32BE(0) === 0xcffaedfe || // Mach-O 64 (LE on disk)
+      (head[0] === 0x4d && head[1] === 0x5a) // PE (Windows MZ)
+    );
+  } catch {
+    return false;
+  }
+}
+
 function runBuildTool(
   packageName: string,
   binName: string,
@@ -78,6 +105,10 @@ function runBuildTool(
 ): void {
   const localEntry = resolveLocalBinEntry(packageName, binName);
   if (localEntry) {
+    if (isNativeExecutable(localEntry)) {
+      execFileSync(localEntry, [...args], options);
+      return;
+    }
     execFileSync(process.execPath, [localEntry, ...args], options);
     return;
   }
@@ -405,15 +436,23 @@ if (existsSync(opencodePluginSrc) && existsSync(join(opencodePluginSrc, "package
       // types). Without this install a fresh CI publish fails at this step.
       if (!existsSync(join(opencodePluginSrc, "node_modules"))) {
         const npmEntry = resolveBundledNpmEntry("npm-cli.js");
-        if (!npmEntry) {
+        if (npmEntry) {
+          execFileSync(process.execPath, [npmEntry, "install", "--no-audit", "--no-fund"], {
+            cwd: opencodePluginSrc,
+            stdio: "inherit",
+          });
+        } else if (process.platform !== "win32") {
+          // No bundled npm entry found (non-standard Node layout). Plain `npm` is
+          // safe here — the .cmd-shim hazard #8858 guards against is Windows-only.
+          execFileSync("npm", ["install", "--no-audit", "--no-fund"], {
+            cwd: opencodePluginSrc,
+            stdio: "inherit",
+          });
+        } else {
           throw new Error(
             "npm-cli.js not found next to the running Node binary; cannot install the plugin dependencies without falling back to a .cmd shim."
           );
         }
-        execFileSync(process.execPath, [npmEntry, "install", "--no-audit", "--no-fund"], {
-          cwd: opencodePluginSrc,
-          stdio: "inherit",
-        });
       }
       runBuildTool("tsup", "tsup", [], {
         cwd: opencodePluginSrc,