@expo/code-review-cli 0.12.3 → 0.12.5

package/build/research-mcp/server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ResearchAudit } from "./audit.js";
+import { createResearchNetwork } from "./network.js";
 import { sanitizeDocumentationQuery } from "./query-sanitizer.js";
 import { DIRECT_DOCUMENT_CONTEXT_MODES, fetchDocumentationUrl, resolveDirectDocumentationTarget, } from "./direct-fetch.js";
 import { searchExpoAlgolia } from "./expo-algolia.js";
@@ -26,7 +27,9 @@ export async function createDocumentationServer(options = {}) {
     const index = options.indexPath ? await loadSearchIndex(options.indexPath) : undefined;
     const maxCalls = Math.min(20, Math.max(1, options.maxCalls ?? 8));
     const maxResultsPerCall = Math.min(3, Math.max(1, options.maxResultsPerCall ?? 3));
+    const timeoutMs = Math.min(60_000, Math.max(1_000, options.timeoutMs ?? 30_000));
     const audit = new ResearchAudit(options.auditPath, maxCalls);
+    const baseFetch = options.fetchImplementation ?? fetch;
     const server = new McpServer({
         name: "review-research-mcp",
         version: "0.2.0",
@@ -40,7 +43,9 @@ export async function createDocumentationServer(options = {}) {
                 .default("all")
                 .describe("Documentation platform to search"),
             query: z.string().min(1).max(300).describe(queryGuidance),
-            limit: z.number().int().min(1).max(10).default(5),
+            // Advertise the limit this server actually enforces, so the caller's
+            // mental model matches what a request can return.
+            limit: z.number().int().min(1).max(maxResultsPerCall).default(maxResultsPerCall),
             language: z
                 .enum(LANGUAGES)
                 .optional()
@@ -65,9 +70,19 @@ export async function createDocumentationServer(options = {}) {
             openWorldHint: true,
         },
     }, async ({ platform, query, limit, language, providers, sourceKinds }) => {
-        const sanitizedQuery = sanitizeDocumentationQuery(query);
+        let sanitizedQuery;
+        try {
+            sanitizedQuery = sanitizeDocumentationQuery(query);
+        }
+        catch (error) {
+            // Audited by reason class only: the rejected text may be exactly the
+            // sensitive material the sanitizer refused to send.
+            await audit.rejected("search_platform_docs", "query-rejected");
+            throw error;
+        }
         const selectedProviders = (providers ?? defaultProviders(platform)).filter((provider) => platform === "all" || getProvider(provider).platform === platform);
         if (selectedProviders.length === 0) {
+            await audit.rejected("search_platform_docs", "query-rejected");
             throw new Error("No selected documentation provider matches the requested platform");
         }
         const boundedLimit = Math.min(limit, maxResultsPerCall);
@@ -77,6 +92,8 @@ export async function createDocumentationServer(options = {}) {
             query: sanitizedQuery,
         };
         const requestId = await audit.reserve("search_platform_docs", auditInput);
+        // One deadline and one request ledger for everything this call issues.
+        const network = createResearchNetwork(baseFetch, timeoutMs);
         try {
             const localResults = index
                 ? searchDocumentation(index, sanitizedQuery, {
@@ -94,10 +111,15 @@ export async function createDocumentationServer(options = {}) {
             const searched = await Promise.all(selectedProviders.map(async (provider) => {
                 if (provider === "expo") {
                     if (sourceKinds && !sourceKinds.includes("official-api")) {
-                        return { results: [], warnings: [] };
+                        return {
+                            results: [],
+                            warnings: [
+                                "Expo documentation search serves official-api sources only; the requested source kinds exclude it",
+                            ],
+                        };
                     }
                     try {
-                        const documents = await searchExpoAlgolia(sanitizedQuery, perProviderLimit);
+                        const documents = await searchExpoAlgolia(sanitizedQuery, perProviderLimit, network.fetch);
                         return {
                             results: documents.map((document, position) => ({
                                 id: `expo-algolia:${document.url}`,
@@ -125,7 +147,7 @@ export async function createDocumentationServer(options = {}) {
                     (!sourceKinds || sourceKinds.includes("official-guide")) &&
                     !language) {
                     try {
-                        const results = await searchOkHttpDocumentation(sanitizedQuery, perProviderLimit, options.fetchImplementation ?? fetch);
+                        const results = await searchOkHttpDocumentation(sanitizedQuery, perProviderLimit, network.fetch);
                         if (results.length > 0) {
                             return { results, warnings: [] };
                         }
@@ -146,9 +168,8 @@ export async function createDocumentationServer(options = {}) {
                 try {
                     return await searchRemoteDocumentation(provider, sanitizedQuery, perProviderLimit, {
                         apiKey: options.braveApiKey,
-                        ...(options.fetchImplementation
-                            ? { fetchImplementation: options.fetchImplementation }
-                            : {}),
+                        fetchImplementation: network.fetch,
+                        deadline: network.signal,
                         ...(language ? { language } : {}),
                         ...(sourceKinds ? { sourceKinds } : {}),
                     });
@@ -184,10 +205,13 @@ export async function createDocumentationServer(options = {}) {
             })
                 .slice(0, boundedLimit);
             const uniqueWarnings = [...new Set(warnings)].slice(0, 10);
+            const network_ = network.counts();
             const payload = {
                 notice: untrustedMaterialNotice,
                 retrieval: {
                     scopedWebSearch: Boolean(options.braveApiKey),
+                    // What this single budget unit actually cost.
+                    network: network_,
                     expoSearch: selectedProviders.includes("expo"),
                     localIndex: index
                         ? {
@@ -199,7 +223,7 @@ export async function createDocumentationServer(options = {}) {
                 ...(uniqueWarnings.length > 0 ? { warnings: uniqueWarnings } : {}),
                 results,
             };
-            await audit.complete(requestId, "search_platform_docs", auditInput, results, uniqueWarnings);
+            await audit.complete(requestId, "search_platform_docs", auditInput, results, uniqueWarnings, network_);
             return {
                 content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
             };
@@ -232,6 +256,8 @@ export async function createDocumentationServer(options = {}) {
                 .enum(DIRECT_DOCUMENT_CONTEXT_MODES)
                 .default("section")
                 .describe("Context breadth: focused=matched and adjacent passages, section=bounded contiguous window around the match, document=bounded extracted page text"),
+            // Focused passage count is a context-window control, deliberately
+            // independent of the search results-per-query bound.
             limit: z
                 .number()
                 .int()
@@ -247,28 +273,46 @@ export async function createDocumentationServer(options = {}) {
             openWorldHint: true,
         },
     }, async ({ url, provider, query, context, limit }) => {
-        const sanitizedQuery = query ? sanitizeDocumentationQuery(query) : undefined;
-        // Resolve and validate before recording anything. This prevents credentials,
-        // query strings, or covert high-entropy path data from reaching either the
-        // network or the append-only audit file.
-        const target = resolveDirectDocumentationTarget(url, provider);
+        let sanitizedQuery;
+        try {
+            sanitizedQuery = query ? sanitizeDocumentationQuery(query) : undefined;
+        }
+        catch (error) {
+            await audit.rejected("fetch_platform_doc", "query-rejected");
+            throw error;
+        }
+        // Resolve and validate before recording the input. This prevents
+        // credentials, query strings, or covert high-entropy path data from
+        // reaching either the network or the append-only audit file; a refusal is
+        // still audited by reason class so unmet demand stays visible.
+        let target;
+        try {
+            target = resolveDirectDocumentationTarget(url, provider);
+        }
+        catch (error) {
+            await audit.rejected("fetch_platform_doc", "url-rejected");
+            throw error;
+        }
         const auditInput = {
+            platform: getProvider(target.provider).platform,
             providers: [target.provider],
             ...(sanitizedQuery ? { query: sanitizedQuery } : {}),
             url: target.url.href,
             context,
         };
         const requestId = await audit.reserve("fetch_platform_doc", auditInput);
+        // A single URL still costs up to six round trips through the redirect
+        // chain, so this call needs the same deadline and ledger as a search.
+        const network = createResearchNetwork(baseFetch, timeoutMs);
         try {
             const fetched = await fetchDocumentationUrl(target.url.href, {
                 provider: target.provider,
                 ...(sanitizedQuery ? { query: sanitizedQuery } : {}),
                 context,
-                limit: Math.min(limit, maxResultsPerCall),
-                ...(options.fetchImplementation
-                    ? { fetchImplementation: options.fetchImplementation }
-                    : {}),
+                limit,
+                fetchImplementation: network.fetch,
             });
+            const network_ = network.counts();
             const payload = {
                 notice: untrustedMaterialNotice,
                 retrieval: {
@@ -277,6 +321,7 @@ export async function createDocumentationServer(options = {}) {
                     sourceKind: fetched.sourceKind,
                     canonicalUrl: fetched.canonicalUrl,
                     context: fetched.context,
+                    network: network_,
                 },
                 results: fetched.results,
             };
@@ -285,7 +330,7 @@ export async function createDocumentationServer(options = {}) {
                 platform: getProvider(fetched.provider).platform,
                 providers: [fetched.provider],
                 url: fetched.canonicalUrl,
-            }, fetched.results);
+            }, fetched.results, [], network_);
             return {
                 content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
             };

package/build/research-mcp/wrapper.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// @ref LLP 0013#one-package-two-binaries [implements] — the environment boundary the engine's MCP config cannot provide
+/**
+ * Environment boundary for the bounded documentation MCP.
+ *
+ * ECR declares a minimal `env` in the engine's MCP configuration, but neither
+ * engine treats that as a replacement: Claude Code and OpenCode both MERGE it
+ * onto the environment the engine already holds. Verified by spawning each
+ * engine against a probe MCP that records variable names — the child saw the
+ * engine's model credential on both, and OpenCode additionally passed through
+ * the runner's whole ambient environment.
+ *
+ * So the boundary has to be ours. The engine spawns this wrapper; the wrapper
+ * spawns the real server with an environment it CONSTRUCTS. Whatever the engine
+ * merged in reaches this process and stops here.
+ *
+ * This file deliberately does almost nothing. It loads no HTML/JSON parser and
+ * opens no socket, because it is the one process in the chain that still holds
+ * the engine's credentials. Everything that touches untrusted remote content
+ * runs in the child, which never receives them.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { constants } from "node:os";
+import { fileURLToPath } from "node:url";
+import { researchWrapperEnvironment } from "./child-env.js";
+const builtEntry = fileURLToPath(new URL("./cli.js", import.meta.url));
+const sourceEntry = fileURLToPath(new URL("./cli.ts", import.meta.url));
+const child = spawn(
+// The current interpreter by absolute path, never a PATH lookup: during a
+// review the cwd is the untrusted PR-head tree.
+process.execPath, [existsSync(builtEntry) ? builtEntry : sourceEntry, ...process.argv.slice(2)], {
+    env: researchWrapperEnvironment(process.env),
+    // The child owns the engine's stdio directly, so the wrapper never sits in
+    // the MCP byte stream and cannot truncate, buffer, or reorder a message.
+    stdio: "inherit",
+});
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+for (const signal of FORWARDED_SIGNALS) {
+    // The engine signals the process it spawned — us. Pass it on, or the server
+    // outlives the review and keeps its audit lock.
+    process.on(signal, () => {
+        child.kill(signal);
+    });
+}
+child.on("error", (error) => {
+    process.stderr.write(`review-research-mcp: failed to start bounded server: ${error.message}\n`);
+    process.exitCode = 1;
+});
+child.on("exit", (code, signal) => {
+    // Report a signal death as the conventional 128+n rather than a silent 0, so a
+    // killed server is distinguishable from a clean shutdown.
+    process.exitCode = signal ? 128 + (constants.signals[signal] ?? 0) : (code ?? 1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/code-review-cli",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description": "Generic, config-driven AI code reviewer engine. Repos supply their agents via .expo-code-review/.",
   "license": "MIT",
   "repository": {

package/templates/config.jsonc

@@ -26,15 +26,25 @@
 
   // Optional bounded platform research (ROOT-ONLY; off by default). Reviewer and
   // cross-file passes can call ECR's bundled MCP for exact API-symbol searches and
-  // supported documentation URLs. The MCP sanitizes queries, uses fixed provider
-  // allowlists, audits results, and never receives model credentials. BRAVE_SEARCH_API_KEY
-  // enables fixed site-scoped discovery; Expo uses its public documentation search.
-  // indexPath remains an optional offline fallback only.
+  // supported documentation URLs. The MCP uses fixed provider allowlists and audits
+  // every call. It runs behind a wrapper that rebuilds its environment from an
+  // explicit allowlist, because both engines MERGE the configured env onto their own
+  // rather than replacing it — so the server sees the search key and these limits,
+  // and never the model credential. BRAVE_SEARCH_API_KEY enables fixed site-scoped
+  // discovery; Expo uses its public documentation search.
+  //
+  // Queries are shape-checked, not confidentiality-checked: the reviewing model
+  // chooses the outbound terms, so enable this only where repository-derived terms
+  // may be shared with Brave and the documentation providers.
+  //
+  // maxQueries bounds MCP CALLS, not requests — one search can issue a discovery
+  // request per provider plus a page fetch per candidate. timeoutMs is the MCP's own
+  // end-to-end deadline per call. indexPath remains an optional offline fallback.
   // "research": {
   //   "enabled": true,
   //   "maxQueries": 8,
   //   "resultsPerQuery": 2,
-  //   "timeoutMs": 15000
+  //   "timeoutMs": 30000
   // },
 
   // Large diffs are split into focused chunks by changed-line count, plus a