@spotpatch/next 0.6.0 → 0.7.0

package/dist/cli.js

@@ -9,6 +9,7 @@ import { runSpotPatchBridgeCli } from "@spotpatch/bridge";
 import { spawn } from "child_process";
 import { randomBytes } from "crypto";
 import { serializeResolvedSpotPatchOptions } from "@spotpatch/dev-server";
+import { SPOTPATCH_API_BASE as SPOTPATCH_API_BASE2 } from "@spotpatch/shared";
 
 // src/cli-args.ts
 import { isLoopbackHostname } from "@spotpatch/dev-server";
@@ -289,8 +290,12 @@ import {
   createSession,
   createSourceRegistrationService,
   createSourceRegistry,
-  createSpotPatchMiddleware
+  createSpotPatchMiddleware,
+  resolveManagedExecutionValidation
 } from "@spotpatch/dev-server";
+import {
+  createExternalAgentSupervisor
+} from "@spotpatch/bridge";
 import {
   SPOTPATCH_API_BASE,
   SPOTPATCH_ENDPOINTS,
@@ -300,7 +305,7 @@ import {
 // package.json
 var package_default = {
   name: "@spotpatch/next",
-  version: "0.6.0",
+  version: "0.7.0",
   description: "Development-only Next.js adapter and CLI for SpotPatch.",
   license: "MIT",
   repository: {
@@ -516,38 +521,102 @@ function validateCredentialEnvironment(options, credentials) {
     throw new TypeError("The SpotPatch credential environment is inconsistent.");
   }
 }
-async function selfCheckSidecar(sidecarOrigin, publicOrigin, expectedConfig) {
-  const response = await fetch(new URL(SPOTPATCH_ENDPOINTS.bootstrap, sidecarOrigin), {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Origin: publicOrigin,
-      "Sec-Fetch-Site": "same-origin"
-    },
-    body: "{}",
-    signal: AbortSignal.timeout(SIDECAR_SELF_CHECK_TIMEOUT_MS)
-  });
+function diagnosticUrl(value, fallbackOrigin) {
+  try {
+    const url = new URL(value, fallbackOrigin);
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return fallbackOrigin;
+  }
+}
+async function checkBootstrapRoute(routeOrigin, expectedOrigin, expectedConfig) {
+  const requestUrl = new URL(SPOTPATCH_ENDPOINTS.bootstrap, routeOrigin);
+  let response;
+  try {
+    response = await fetch(requestUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Origin: expectedOrigin,
+        "Sec-Fetch-Site": "same-origin"
+      },
+      body: "{}",
+      redirect: "manual",
+      signal: AbortSignal.timeout(SIDECAR_SELF_CHECK_TIMEOUT_MS)
+    });
+  } catch {
+    return Object.freeze({
+      finalUrl: diagnosticUrl(requestUrl.href, routeOrigin),
+      kind: "unreachable",
+      ok: false
+    });
+  }
+  const redirectLocation = response.headers.get("location");
+  const finalUrl = diagnosticUrl(
+    redirectLocation === null ? response.url || requestUrl.href : new URL(redirectLocation, response.url || requestUrl.href).href,
+    routeOrigin
+  );
   const declaredLength = Number(response.headers.get("content-length"));
   if (Number.isFinite(declaredLength) && declaredLength > SIDECAR_SELF_CHECK_LIMIT_BYTES) {
     await response.body?.cancel();
-    throw new Error("SpotPatch Sidecar self-check failed.");
+    return Object.freeze({
+      finalUrl,
+      kind: "response-invalid",
+      ok: false,
+      status: response.status
+    });
   }
   const text = await response.text();
-  if (!response.ok || !response.headers.get("cache-control")?.toLowerCase().includes("no-store") || Buffer.byteLength(text, "utf8") > SIDECAR_SELF_CHECK_LIMIT_BYTES) {
-    throw new Error("SpotPatch Sidecar self-check failed.");
+  if (!response.ok) {
+    return Object.freeze({
+      finalUrl,
+      kind: "http",
+      ok: false,
+      status: response.status
+    });
+  }
+  if (!response.headers.get("cache-control")?.toLowerCase().includes("no-store") || Buffer.byteLength(text, "utf8") > SIDECAR_SELF_CHECK_LIMIT_BYTES) {
+    return Object.freeze({
+      finalUrl,
+      kind: "response-invalid",
+      ok: false,
+      status: response.status
+    });
   }
   let value;
   try {
     value = JSON.parse(text);
-  } catch (error) {
-    throw new Error("SpotPatch Sidecar self-check failed.", { cause: error });
+  } catch {
+    return Object.freeze({
+      finalUrl,
+      kind: "response-invalid",
+      ok: false,
+      status: response.status
+    });
   }
   if (typeof value !== "object" || value === null || Array.isArray(value) || Object.keys(value).length !== 2 || !("ok" in value) || value.ok !== true || !("data" in value)) {
-    throw new Error("SpotPatch Sidecar self-check failed.");
+    return Object.freeze({
+      finalUrl,
+      kind: "response-invalid",
+      ok: false,
+      status: response.status
+    });
   }
   const parsed = runtimeConfigSchema.safeParse(value.data);
   const parsedExpected = runtimeConfigSchema.safeParse(expectedConfig);
   if (!parsed.success || !parsedExpected.success || JSON.stringify(parsed.data) !== JSON.stringify(parsedExpected.data)) {
+    return Object.freeze({
+      finalUrl,
+      kind: "response-invalid",
+      ok: false,
+      status: response.status
+    });
+  }
+  return Object.freeze({ ok: true });
+}
+async function selfCheckSidecar(sidecarOrigin, publicOrigin, expectedConfig) {
+  const result = await checkBootstrapRoute(sidecarOrigin, publicOrigin, expectedConfig);
+  if (!result.ok) {
     throw new Error("SpotPatch Sidecar self-check failed.");
   }
 }
@@ -568,6 +637,9 @@ async function createNextSidecar(sidecarOptions) {
   let registry;
   let agentManager;
   let externalHandoffService;
+  let externalAgentSupervisor;
+  let spotPatchMiddleware;
+  let publicRouteCheck;
   let handler = (_request, response) => {
     writeUnavailable(response, 503);
   };
@@ -652,9 +724,11 @@ async function createNextSidecar(sidecarOptions) {
         root: input.appRoot,
         sessionId: session.id
       }) : void 0;
+      let handoffReady = false;
       if (handoffService !== void 0) {
         try {
           await handoffService.start();
+          handoffReady = true;
         } catch {
           process.stderr.write(
             "[spotpatch:next] External Agent handoff is unavailable; core tools remain active.\n"
@@ -662,9 +736,32 @@ async function createNextSidecar(sidecarOptions) {
         }
       }
       externalHandoffService = handoffService;
+      let supervisor;
+      if (handoffReady) {
+        try {
+          const validation = await resolveManagedExecutionValidation({
+            ai: input.options.ai,
+            appRoot: input.appRoot
+          });
+          supervisor = await createExternalAgentSupervisor({
+            bridgeAdapter: "next",
+            checks: validation.checks,
+            limits: validation.limits,
+            root: input.appRoot,
+            sessionId: session.id,
+            projectLabel: input.appRoot.split(/[\\/]/u).at(-1) ?? "project"
+          });
+        } catch {
+          process.stderr.write(
+            "[spotpatch:next] Managed Agent control is unavailable; Inbox remains active.\n"
+          );
+        }
+      }
+      externalAgentSupervisor = supervisor;
       const middleware = createSpotPatchMiddleware({
         ...manager === void 0 ? {} : { agentManager: manager },
         ...handoffService === void 0 ? {} : { externalHandoffService: handoffService },
+        ...supervisor === void 0 ? {} : { externalAgentControl: supervisor },
         bootstrap: {
           expectedOrigin: input.publicOrigin,
           runtimeConfig
@@ -689,6 +786,7 @@ async function createNextSidecar(sidecarOptions) {
       });
       registry = sourceRegistry;
       agentManager = manager;
+      spotPatchMiddleware = middleware;
       handler = (request, response) => {
         if (requestPath(request.url) === NEXT_INTERNAL_REGISTRATION_PATH) {
           registration.handler(request, response);
@@ -699,8 +797,26 @@ async function createNextSidecar(sidecarOptions) {
         });
       };
       await selfCheckSidecar(sidecarOrigin, input.publicOrigin, runtimeConfig);
+      publicRouteCheck = Object.freeze({
+        expectedConfig: runtimeConfig,
+        publicOrigin: input.publicOrigin
+      });
       active = true;
     },
+    async checkPublicRoute() {
+      if (closed || !active || publicRouteCheck === void 0) {
+        return Object.freeze({
+          finalUrl: sidecarOrigin,
+          kind: "unreachable",
+          ok: false
+        });
+      }
+      return await checkBootstrapRoute(
+        publicRouteCheck.publicOrigin,
+        publicRouteCheck.publicOrigin,
+        publicRouteCheck.expectedConfig
+      );
+    },
     async close() {
       if (closed) {
         return;
@@ -710,6 +826,10 @@ async function createNextSidecar(sidecarOptions) {
         writeUnavailable(response, 503);
       };
       registry?.clear();
+      spotPatchMiddleware?.dispose();
+      spotPatchMiddleware = void 0;
+      await externalAgentSupervisor?.dispose();
+      externalAgentSupervisor = void 0;
       await externalHandoffService?.close();
       externalHandoffService = void 0;
       await agentManager?.close();
@@ -724,6 +844,8 @@ async function createNextSidecar(sidecarOptions) {
 // src/cli-owner.ts
 var CONFIGURATION_STARTUP_TIMEOUT_MS = 6e4;
 var FORCED_TERMINATION_TIMEOUT_MS = 5e3;
+var PUBLIC_ROUTE_CANARY_RETRY_MS = 250;
+var PUBLIC_ROUTE_CANARY_TIMEOUT_MS = 6e4;
 var MAX_CONFIGURATION_REQUESTS = 32;
 var ID_PATTERN2 = /^[A-Za-z0-9_-]{16,128}$/u;
 function isRecord2(value) {
@@ -782,6 +904,51 @@ function waitForChild(child) {
     });
   });
 }
+function waitForDelay(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(
+        signal.reason instanceof Error ? signal.reason : new Error("SpotPatch public-route wait was aborted.")
+      );
+      return;
+    }
+    const timer = setTimeout(resolve, milliseconds);
+    timer.unref();
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(
+          signal.reason instanceof Error ? signal.reason : new Error("SpotPatch public-route wait was aborted.")
+        );
+      },
+      { once: true }
+    );
+  });
+}
+function publicRouteCanaryError(result) {
+  if (result.ok) {
+    throw new TypeError("A successful public route canary has no error.");
+  }
+  const status = result.status === void 0 ? "unavailable" : String(result.status);
+  return new Error(
+    `SpotPatch public-route canary failed at ${result.finalUrl} (stage=${result.kind}, status=${status}). Check Proxy/Middleware matcher exclusions for ${SPOTPATCH_API_BASE2}.`
+  );
+}
+async function waitForPublicRoute(sidecar, signal) {
+  const deadline = Date.now() + PUBLIC_ROUTE_CANARY_TIMEOUT_MS;
+  while (!signal.aborted) {
+    const result = await sidecar.checkPublicRoute();
+    if (result.ok) {
+      return;
+    }
+    if (result.kind !== "unreachable" || Date.now() >= deadline) {
+      throw publicRouteCanaryError(result);
+    }
+    await waitForDelay(PUBLIC_ROUTE_CANARY_RETRY_MS, signal);
+  }
+  throw signal.reason;
+}
 async function closeSidecar(sidecar) {
   let timer;
   try {
@@ -820,6 +987,8 @@ async function runNextDevelopment(arguments_) {
   let configured = false;
   let failureCode;
   let configurationQueue = Promise.resolve();
+  const publicRouteCanaryAbort = new AbortController();
+  let publicRouteCanary;
   const handleConfiguration = async (value) => {
     const correlation = readCorrelation(value, launchNonce);
     let message;
@@ -881,10 +1050,30 @@ async function runNextDevelopment(arguments_) {
     if (!configured) {
       configured = true;
       clearTimeout(startupTimer);
-      process.stdout.write(
-        `[spotpatch:next] ready for Next.js ${project.nextVersion} (${dev.bundler}) at ${dev.publicOrigin}
+      if (message.options.enabled) {
+        publicRouteCanary = waitForPublicRoute(
+          sidecar,
+          publicRouteCanaryAbort.signal
+        ).then(
+          () => {
+            process.stdout.write(
+              `[spotpatch:next] ready for Next.js ${project.nextVersion} (${dev.bundler}) at ${dev.publicOrigin}
 `
-      );
+            );
+          },
+          (error) => {
+            if (publicRouteCanaryAbort.signal.aborted) {
+              return;
+            }
+            failureCode = "PUBLIC_ROUTE_CANARY_FAILED";
+            process.stderr.write(
+              `[spotpatch:next] ${error instanceof Error ? error.message : "SpotPatch public-route canary failed."}
+`
+            );
+            lifecycle.child?.kill("SIGTERM");
+          }
+        );
+      }
     }
     return createAck(message, { ok: true });
   };
@@ -961,6 +1150,7 @@ async function runNextDevelopment(arguments_) {
   process.once("SIGINT", onSigint);
   process.once("SIGTERM", onSigterm);
   const result = await waitForChild(child);
+  publicRouteCanaryAbort.abort();
   clearTimeout(startupTimer);
   process.off("SIGINT", onSigint);
   process.off("SIGTERM", onSigterm);
@@ -968,6 +1158,7 @@ async function runNextDevelopment(arguments_) {
     clearTimeout(forceTimer);
   }
   await configurationQueue;
+  await publicRouteCanary;
   try {
     await closeSidecar(sidecar);
   } catch {
@@ -997,7 +1188,7 @@ import {
   integrationPathExists,
   readIntegrationFile
 } from "@spotpatch/dev-server";
-import { DEFAULT_AGENT_LIMITS } from "@spotpatch/shared";
+import { DEFAULT_AGENT_LIMITS, SPOTPATCH_API_BASE as SPOTPATCH_API_BASE3 } from "@spotpatch/shared";
 import { MagicString } from "magic-string";
 import {
   parseSync,
@@ -1023,6 +1214,8 @@ var INSTRUMENTATION_EXTENSIONS = Object.freeze([
   ".cts",
   ".cjs"
 ]);
+var PROXY_FILE_BASE_NAMES = Object.freeze(["proxy", "middleware"]);
+var SPOTPATCH_MATCHER_EXCLUSION = "__spotpatch(?:/|$)";
 var SIMPLE_SCRIPT_ARGUMENT_PATTERN = /^[A-Za-z0-9._:/=@%+,-]+$/u;
 function isParserErrorSeverity(value) {
   return value === "Error";
@@ -1030,6 +1223,10 @@ function isParserErrorSeverity(value) {
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function staticStringLiteral(value) {
+  if (!isRecord3(value) || value.type !== "Literal") return void 0;
+  return typeof value.value === "string" ? value.value : void 0;
+}
 function parseModule(absolutePath, source) {
   const result = parseSync(absolutePath, source, {
     sourceType: "module",
@@ -1148,21 +1345,102 @@ function staticPropertyName(property) {
   if (property.key.type === "Identifier") return property.key.name;
   return property.key.type === "Literal" && typeof property.key.value === "string" ? property.key.value : void 0;
 }
-function assertSupportedDataFlowOption(factory) {
-  const argument = factory.arguments[0];
-  if (argument?.type !== "ObjectExpression") return;
-  const properties = argument.properties.filter(
-    (property2) => property2.type === "Property" && staticPropertyName(property2) === "dataFlow"
+function unwrapExpression(expression) {
+  let current = expression;
+  while (current.type === "ParenthesizedExpression" || current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSTypeAssertion" || current.type === "TSNonNullExpression") {
+    current = current.expression;
+  }
+  return current;
+}
+function findObjectProperty(object, name) {
+  const matches = object.properties.filter(
+    (property) => property.type === "Property" && staticPropertyName(property) === name
   );
-  if (properties.length > 1) {
-    throw new Error("SpotPatch init found duplicate dataFlow options.");
+  if (matches.length > 1) {
+    throw new Error(`SpotPatch init found duplicate ${name} options.`);
+  }
+  return matches[0];
+}
+function lineIndentAt(source, offset) {
+  const lineStart = source.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+  return /^[\t ]*/u.exec(source.slice(lineStart, offset))?.[0] ?? "";
+}
+function childIndent(source, object) {
+  const first = object.properties[0];
+  return first === void 0 ? `${lineIndentAt(source, object.start)}  ` : lineIndentAt(source, first.start);
+}
+function initializedNextOptions(trustedFastModeAvailable) {
+  return `{ externalAgent: true${trustedFastModeAvailable ? ", trustedFastMode: true" : ""} }`;
+}
+function enableNextOptions(magicString, source, factory, trustedFastModeAvailable) {
+  const argument = factory.arguments[0];
+  if (factory.arguments.length === 0) {
+    magicString.appendLeft(
+      factory.end - 1,
+      initializedNextOptions(trustedFastModeAvailable)
+    );
+    return;
+  }
+  if (factory.arguments.length !== 1 || argument === void 0 || argument.type === "SpreadElement") {
+    throw new Error("SpotPatch init cannot safely update withSpotPatch options.");
+  }
+  const options = unwrapExpression(argument);
+  if (options.type !== "ObjectExpression") {
+    throw new Error("SpotPatch init requires withSpotPatch options to be an object.");
+  }
+  if (options.properties.some((property) => property.type === "SpreadElement")) {
+    throw new Error(
+      "SpotPatch init cannot prove externalAgent through spread withSpotPatch options."
+    );
   }
-  const property = properties[0];
-  if (property !== void 0 && !(property.value.type === "Literal" && property.value.value === false)) {
+  const dataFlowProperty = findObjectProperty(options, "dataFlow");
+  const dataFlowValue = dataFlowProperty === void 0 ? void 0 : unwrapExpression(dataFlowProperty.value);
+  if (dataFlowValue !== void 0 && !(dataFlowValue.type === "Literal" && dataFlowValue.value === false)) {
     throw new Error(
       "SpotPatch Next does not support component dataFlow yet; remove dataFlow or set it to false."
     );
   }
+  const missing = [];
+  const externalAgentProperty = findObjectProperty(options, "externalAgent");
+  if (externalAgentProperty === void 0) {
+    missing.push("externalAgent: true");
+  } else {
+    const value = unwrapExpression(externalAgentProperty.value);
+    if (value.type !== "Literal" || typeof value.value !== "boolean") {
+      throw new Error("SpotPatch init requires externalAgent to be a boolean literal.");
+    }
+    if (!value.value) {
+      magicString.overwrite(value.start, value.end, "true");
+    }
+  }
+  const trustedFastModeProperty = findObjectProperty(options, "trustedFastMode");
+  if (trustedFastModeAvailable && trustedFastModeProperty === void 0) {
+    missing.push("trustedFastMode: true");
+  } else if (trustedFastModeProperty !== void 0) {
+    const value = unwrapExpression(trustedFastModeProperty.value);
+    if (value.type !== "Literal" || typeof value.value !== "boolean") {
+      throw new Error(
+        "SpotPatch init requires trustedFastMode to be a boolean literal."
+      );
+    }
+    if (trustedFastModeAvailable && !value.value) {
+      magicString.overwrite(value.start, value.end, "true");
+    }
+  }
+  if (missing.length === 0) {
+    return;
+  }
+  const indent = childIndent(source, options);
+  if (options.properties.length === 0) {
+    magicString.appendLeft(options.end - 1, ` ${missing.join(", ")} `);
+  } else {
+    magicString.appendLeft(
+      options.properties[0]?.start ?? options.end - 1,
+      `${missing.join(`,
+${indent}`)},
+${indent}`
+    );
+  }
 }
 function transformNextConfig(absolutePath, source, trustedFastModeAvailable) {
   if (absolutePath.endsWith(".cjs") || absolutePath.endsWith(".cts")) {
@@ -1182,16 +1460,8 @@ function transformNextConfig(absolutePath, source, trustedFastModeAvailable) {
   const wrapperName = existingWrapperName ?? chooseWrapperName(program);
   const existingFactory = existingWrapperName === void 0 ? void 0 : wrappedFactoryCall(defaultExport.declaration, existingWrapperName);
   if (existingFactory !== void 0) {
-    assertSupportedDataFlowOption(existingFactory);
-    if (trustedFastModeAvailable && existingFactory.arguments.length === 0) {
-      magicString.overwrite(
-        existingFactory.start,
-        existingFactory.end,
-        `${wrapperName}({ trustedFastMode: true })`
-      );
-      return magicString.toString();
-    }
-    return source;
+    enableNextOptions(magicString, source, existingFactory, trustedFastModeAvailable);
+    return magicString.toString();
   }
   if (existingWrapperName === void 0) {
     const specifier = wrapperName === "withSpotPatch" ? "withSpotPatch" : `withSpotPatch as ${wrapperName}`;
@@ -1208,7 +1478,7 @@ function transformNextConfig(absolutePath, source, trustedFastModeAvailable) {
   magicString.overwrite(
     defaultExport.declaration.start,
     defaultExport.declaration.end,
-    `${wrapperName}(${trustedFastModeAvailable ? "{ trustedFastMode: true }" : ""})(${expression})`
+    `${wrapperName}(${initializedNextOptions(trustedFastModeAvailable)})(${expression})`
   );
   return magicString.toString();
 }
@@ -1233,6 +1503,230 @@ function transformInstrumentationClient(absolutePath, source) {
   );
   return magicString.toString();
 }
+function findVariableInitializer(program, name) {
+  for (const statement of program.body) {
+    if (statement.type !== "VariableDeclaration") {
+      continue;
+    }
+    for (const declaration of statement.declarations) {
+      if (declaration.id.type === "Identifier" && declaration.id.name === name && declaration.init !== null) {
+        return declaration.init;
+      }
+    }
+  }
+  return void 0;
+}
+function resolveStaticNextConfigObject(program) {
+  const exported = findDefaultExport(program).declaration;
+  if (exported.type === "FunctionDeclaration" || exported.type === "TSDeclareFunction" || exported.type === "ClassDeclaration" || exported.type === "TSInterfaceDeclaration") {
+    return void 0;
+  }
+  let expression = unwrapExpression(exported);
+  if (expression.type === "Identifier") {
+    const initializer = findVariableInitializer(program, expression.name);
+    expression = initializer === void 0 ? expression : unwrapExpression(initializer);
+  }
+  if (expression.type === "CallExpression") {
+    const factory = unwrapExpression(expression.callee);
+    const hostArgument = expression.arguments[0];
+    if (factory.type === "CallExpression" && hostArgument !== void 0 && hostArgument.type !== "SpreadElement") {
+      expression = unwrapExpression(hostArgument);
+      if (expression.type === "Identifier") {
+        const initializer = findVariableInitializer(program, expression.name);
+        expression = initializer === void 0 ? expression : unwrapExpression(initializer);
+      }
+    }
+  }
+  return expression.type === "ObjectExpression" ? expression : void 0;
+}
+function proxyFileExtensions(program) {
+  const extensions = new Set(
+    INSTRUMENTATION_EXTENSIONS.map((extension) => extension.slice(1))
+  );
+  const config = resolveStaticNextConfigObject(program);
+  const pageExtensions = config === void 0 ? void 0 : findObjectProperty(config, "pageExtensions");
+  if (pageExtensions === void 0) {
+    return Object.freeze([...extensions]);
+  }
+  const value = unwrapExpression(pageExtensions.value);
+  if (value.type !== "ArrayExpression") {
+    throw new Error(
+      "SPOTPATCH_PROXY_MATCHER_UNSAFE: pageExtensions must be a static string array so SpotPatch can inspect Proxy/Middleware files."
+    );
+  }
+  for (const element of value.elements) {
+    const extension = staticStringLiteral(element);
+    if (typeof extension !== "string" || extension.length === 0 || extension.includes("/") || extension.includes("\\")) {
+      throw new Error(
+        "SPOTPATCH_PROXY_MATCHER_UNSAFE: pageExtensions must contain only static filename extensions."
+      );
+    }
+    extensions.add(extension.replace(/^\.+/u, ""));
+  }
+  return Object.freeze([...extensions]);
+}
+function rewriteMatcherSource(value) {
+  if (value.includes(SPOTPATCH_MATCHER_EXCLUSION)) {
+    return value;
+  }
+  if (value === SPOTPATCH_API_BASE3 || value.startsWith(`${SPOTPATCH_API_BASE3}/`)) {
+    throw new Error(
+      `SPOTPATCH_PROXY_MATCHER_UNSAFE: Proxy/Middleware explicitly claims ${SPOTPATCH_API_BASE3}.`
+    );
+  }
+  if (value.startsWith("/((?!")) {
+    return `/((?!${SPOTPATCH_MATCHER_EXCLUSION}|${value.slice(5)}`;
+  }
+  if (value === "/:path*" || value === "/:path(.*)" || value === "/(.*)" || value === "/:slug*") {
+    return `/((?!${SPOTPATCH_MATCHER_EXCLUSION}).*)`;
+  }
+  if (value.startsWith("/:") || value.startsWith("/(")) {
+    throw new Error(
+      `SPOTPATCH_PROXY_MATCHER_UNSAFE: cannot safely exclude ${SPOTPATCH_API_BASE3} from matcher ${JSON.stringify(value)}.`
+    );
+  }
+  return value;
+}
+function rewriteMatcherLiteral(magicString, expression) {
+  const value = unwrapExpression(expression);
+  if (value.type !== "Literal" || typeof value.value !== "string") {
+    throw new Error(
+      "SPOTPATCH_PROXY_MATCHER_UNSAFE: matcher entries must use static string sources."
+    );
+  }
+  const rewritten = rewriteMatcherSource(value.value);
+  if (rewritten !== value.value) {
+    magicString.overwrite(value.start, value.end, JSON.stringify(rewritten));
+  }
+}
+function rewriteMatcherEntry(magicString, expression) {
+  const value = unwrapExpression(expression);
+  if (value.type !== "ObjectExpression") {
+    rewriteMatcherLiteral(magicString, value);
+    return;
+  }
+  if (value.properties.some((property) => property.type === "SpreadElement")) {
+    throw new Error(
+      "SPOTPATCH_PROXY_MATCHER_UNSAFE: matcher objects cannot contain spreads."
+    );
+  }
+  const source = findObjectProperty(value, "source");
+  if (source === void 0) {
+    throw new Error(
+      "SPOTPATCH_PROXY_MATCHER_UNSAFE: matcher objects require a static source."
+    );
+  }
+  rewriteMatcherLiteral(magicString, source.value);
+}
+function transformProxyModule(absolutePath, source) {
+  if (absolutePath.endsWith(".cjs") || absolutePath.endsWith(".cts")) {
+    throw new Error(
+      "SPOTPATCH_PROXY_MATCHER_UNSAFE: CommonJS Proxy/Middleware requires a manual __spotpatch matcher exclusion."
+    );
+  }
+  const { program } = parseModule(absolutePath, source);
+  const configDeclarations = [];
+  let unsupportedConfigExport = false;
+  for (const statement of program.body) {
+    if (statement.type !== "ExportNamedDeclaration") {
+      continue;
+    }
+    const declaration = statement.declaration;
+    if (declaration?.type === "VariableDeclaration") {
+      for (const declarator of declaration.declarations) {
+        if (declarator.id.type !== "Identifier" || declarator.id.name !== "config") {
+          continue;
+        }
+        if (declarator.init === null) {
+          unsupportedConfigExport = true;
+          continue;
+        }
+        const value2 = unwrapExpression(declarator.init);
+        if (value2.type === "ObjectExpression") {
+          configDeclarations.push(value2);
+        } else {
+          unsupportedConfigExport = true;
+        }
+      }
+    }
+    if (statement.specifiers.some(
+      (specifier) => specifier.exported.type === "Identifier" && specifier.exported.name === "config"
+    )) {
+      unsupportedConfigExport = true;
+    }
+  }
+  if (unsupportedConfigExport || configDeclarations.length > 1) {
+    throw new Error(
+      "SPOTPATCH_PROXY_MATCHER_UNSAFE: export const config must be one static object."
+    );
+  }
+  const magicString = new MagicString(source);
+  const config = configDeclarations[0];
+  if (config === void 0) {
+    if (collectIdentifierNames(program).has("config")) {
+      throw new Error(
+        "SPOTPATCH_PROXY_MATCHER_UNSAFE: a local config binding prevents a safe matcher export."
+      );
+    }
+    magicString.append(
+      `${source.endsWith("\n") || source.length === 0 ? "" : "\n"}
+export const config = { matcher: [${JSON.stringify(`/((?!${SPOTPATCH_MATCHER_EXCLUSION}).*)`)}] };
+`
+    );
+    return magicString.toString();
+  }
+  const matcher = findObjectProperty(config, "matcher");
+  if (matcher === void 0) {
+    const indent = childIndent(source, config);
+    const property = `matcher: [${JSON.stringify(`/((?!${SPOTPATCH_MATCHER_EXCLUSION}).*)`)}]`;
+    if (config.properties.length === 0) {
+      magicString.appendLeft(config.end - 1, `
+${indent}${property},
+`);
+    } else {
+      magicString.appendLeft(
+        config.properties[0]?.start ?? config.end - 1,
+        `${property},
+${indent}`
+      );
+    }
+    return magicString.toString();
+  }
+  const value = unwrapExpression(matcher.value);
+  if (value.type === "ArrayExpression") {
+    for (const element of value.elements) {
+      if (element === null || element.type === "SpreadElement") {
+        throw new Error(
+          "SPOTPATCH_PROXY_MATCHER_UNSAFE: matcher arrays cannot contain holes or spreads."
+        );
+      }
+      rewriteMatcherEntry(magicString, element);
+    }
+  } else {
+    rewriteMatcherEntry(magicString, value);
+  }
+  return magicString.toString();
+}
+async function findProxyModule(appRoot, configPath, configSource) {
+  const { program } = parseModule(configPath, configSource);
+  const extensions = proxyFileExtensions(program);
+  const candidates = (await Promise.all(
+    [appRoot, path3.join(appRoot, "src")].flatMap(
+      (directory) => PROXY_FILE_BASE_NAMES.flatMap(
+        (baseName) => extensions.map(async (extension) => {
+          const candidate = path3.join(directory, `${baseName}.${extension}`);
+          return await integrationPathExists(candidate) ? candidate : void 0;
+        })
+      )
+    )
+  )).filter((value) => value !== void 0);
+  if (candidates.length > 1) {
+    throw new Error(
+      `SPOTPATCH_PROXY_MATCHER_UNSAFE: found multiple Proxy/Middleware files (${candidates.map((candidate) => path3.relative(appRoot, candidate)).join(", ")}).`
+    );
+  }
+  return candidates[0];
+}
 function parsePackageManifest(source) {
   let value;
   try {
@@ -1363,7 +1857,9 @@ async function planNextIntegration(directory = process.cwd()) {
   ]);
   const trustedFastModeAvailable = discoveredCheck !== void 0;
   const instrumentationPath = await resolveInstrumentationPath(appRoot, configPath);
+  const proxyPath = await findProxyModule(appRoot, configPath, configSource);
   const instrumentationSource = await integrationPathExists(instrumentationPath) ? await readIntegrationFile(instrumentationPath) : void 0;
+  const proxySource = proxyPath === void 0 ? void 0 : await readIntegrationFile(proxyPath);
   const changes = [
     createIntegrationFileChange(
       appRoot,
@@ -1382,7 +1878,15 @@ async function planNextIntegration(directory = process.cwd()) {
       packagePath,
       transformPackageJson(packageSource),
       packageSource
-    )
+    ),
+    ...proxyPath === void 0 || proxySource === void 0 ? [] : [
+      createIntegrationFileChange(
+        appRoot,
+        proxyPath,
+        transformProxyModule(proxyPath, proxySource),
+        proxySource
+      )
+    ]
   ].filter((change) => change !== void 0);
   return Object.freeze({
     appRoot,