@spotpatch/next 0.4.0 → 0.6.0

package/README.md

@@ -18,6 +18,8 @@
 
 The preview connects SpotPatch's element picker, source-aware context, bilingual multi-target requests, and optional review-gated AI Agent to a Next.js development server.
 
+Component `dataFlow` is not part of the Next.js preview yet. `spotpatch-next init` intentionally does not write that option, and `withSpotPatch({ dataFlow: {} })` is rejected instead of displaying a non-functional or misleading panel. The currently implemented data-flow Beta remains Vite + React 18 only.
+
 ### Implemented preview path
 
 - `withSpotPatch()` composes an existing `next.config` without evaluating it twice.
@@ -68,6 +70,36 @@ import "@spotpatch/next/client";
 
 Start development through the package script, not a direct `next dev` command. A successful startup prints one line beginning with `[spotpatch:next] ready`; the page then mounts one `spotpatch-root` Shadow DOM host with the **Select element** / **选择元素** action.
 
+### External Agent handoff (local validation)
+
+Enable the development-only handoff UI explicitly in the same wrapper options:
+
+```ts
+export default withSpotPatch({ externalAgent: true })(nextConfig);
+```
+
+Run setup and active commands from the exact canonical project root that owns the running `spotpatch-next dev` session. Setup is a dry run without `--write`:
+
+```bash
+pnpm exec spotpatch-next bridge setup --client claude --scope project --mode active --write
+MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:spotpatch
+
+pnpm exec spotpatch-next connect codex --allow-workspace-write
+
+pnpm exec spotpatch-next bridge setup --client cursor --scope project --write
+```
+
+The active command forms support an explicit session when `bridge sessions --json` reports multiple sessions for that exact root:
+
+```text
+spotpatch-next bridge channel claude [--session <opaque-id>]
+spotpatch-next connect codex --allow-workspace-write [--session <opaque-id>]
+```
+
+The Claude legacy environment belongs on the Claude host process. Claude Channels are a Research Preview, work only while the Channel-enabled session is running, and provide no completion acknowledgement; completion depends on Claude calling the SpotPatch result tool. Codex active mode is zero-setup: the Connector injects the project-local SpotPatch MCP entry into its App Server thread and does not create or modify `.codex/config.toml`. Codex can still load other MCP servers already enabled by the user's normal Codex configuration. The Connector accepts exactly `codex-cli 0.149.0`. `bridge setup --client codex ...` remains available only for optional Inbox use; Cursor and all generic MCP hosts remain Inbox-only.
+
+This path is `local-validation`, not part of the Next public-support promise. Automated fake-host and two-handoff tests exist, and a consecutive two-revision Codex flow has been manually validated on the recorded macOS/Next.js/Codex 0.149.0 environment. Real Claude Code consecutive delivery, repeatable real-host automation, and Windows process-tree cleanup remain `not-tested`; Cursor remains Inbox-only. See the [external Agent design and exact status](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/%E5%A4%96%E9%83%A8Agent%E8%BF%9E%E6%8E%A5/00-%E7%B4%A2%E5%BC%95%E4%B8%8E%E5%86%B3%E7%AD%96%E6%91%98%E8%A6%81.md).
+
 ### Current evidence and remaining gates
 
 The public preview has passed:
@@ -119,6 +151,8 @@ If React reports only a removed body attribute such as `cz-shortcut-listen="true
 
 当前预览把 SpotPatch 的元素选择、源码上下文、中英文多目标修改要求和可选审阅式 AI Agent 接入 Next.js 开发服务器。
 
+组件 `dataFlow` 尚未进入 Next.js 预览范围。`spotpatch-next init` 会有意不写入该选项；`withSpotPatch({ dataFlow: {} })` 会直接拒绝，而不是显示一个不能工作的误导性面板。当前已实现的数据链路 Beta 仍仅限 Vite + React 18。
+
 ### 已实现的预览链路
 
 - `withSpotPatch()` 组合现有 `next.config`，不会重复执行宿主配置。
@@ -169,6 +203,36 @@ import "@spotpatch/next/client";
 
 必须通过 package script 启动，而不是直接运行 `next dev`。成功启动时终端只打印一条以 `[spotpatch:next] ready` 开头的信息；页面随后挂载唯一 `spotpatch-root` Shadow DOM，并显示 **Select element** / **选择元素** 操作。
 
+### 外部 Agent 交接（本地验证）
+
+在同一包装器选项中显式启用仅开发期的交接 UI：
+
+```ts
+export default withSpotPatch({ externalAgent: true })(nextConfig);
+```
+
+必须在当前 `spotpatch-next dev` Session 所属的精确 canonical 项目根执行 setup 和主动命令。setup 不带 `--write` 时只是 dry-run：
+
+```bash
+pnpm exec spotpatch-next bridge setup --client claude --scope project --mode active --write
+MCP_PROTOCOL_NEGOTIATION=legacy claude --dangerously-load-development-channels server:spotpatch
+
+pnpm exec spotpatch-next connect codex --allow-workspace-write
+
+pnpm exec spotpatch-next bridge setup --client cursor --scope project --write
+```
+
+若 `bridge sessions --json` 报告该精确项目根有多个 Session，主动子命令支持显式选择：
+
+```text
+spotpatch-next bridge channel claude [--session <opaque-id>]
+spotpatch-next connect codex --allow-workspace-write [--session <opaque-id>]
+```
+
+Claude legacy 环境变量必须设置在 Claude 宿主进程。Claude Channels 仍是 Research Preview，只在已启用 Channel 的会话运行时工作，且没有 completion ACK；完成状态依赖 Claude 调用 SpotPatch 结果 tool。Codex 主动模式为零配置：Connector 只把当前项目的 SpotPatch MCP 配置注入它拥有的 App Server thread，不创建也不修改 `.codex/config.toml`；Codex 仍可能按用户既有配置启动其他已启用 MCP server。Connector 当前只接受 `codex-cli 0.149.0`。`bridge setup --client codex ...` 仅保留为可选 Inbox 配置；Cursor 和所有普通 MCP 宿主仍为 Inbox-only。
+
+该链路当前只是 `local-validation`，不属于 Next 正式支持承诺。仓库有假宿主和连续两 Handoff 自动化测试，并已在记录的 macOS/Next.js/Codex 0.149.0 环境人工验证连续两个 revision。真实 Claude Code 连续投递、可重复真实宿主自动化和 Windows 进程树清理仍为 `not-tested`；Cursor 保持 Inbox-only。准确边界见[外部 Agent 方案与实现状态](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/%E5%A4%96%E9%83%A8Agent%E8%BF%9E%E6%8E%A5/00-%E7%B4%A2%E5%BC%95%E4%B8%8E%E5%86%B3%E7%AD%96%E6%91%98%E8%A6%81.md)。
+
 ### 当前证据与剩余门禁
 
 公共预览已经通过：

package/dist/cli.js

@@ -3,6 +3,7 @@
 // src/cli.ts
 import { createRequire as createRequire2 } from "module";
 import path4 from "path";
+import { runSpotPatchBridgeCli } from "@spotpatch/bridge";
 
 // src/cli-owner.ts
 import { spawn } from "child_process";
@@ -282,7 +283,9 @@ import {
 } from "http";
 import {
   createAgentJobManager,
+  createExternalHandoffService,
   createRuntimeAiConfig,
+  createRuntimeDataFlowConfig,
   createSession,
   createSourceRegistrationService,
   createSourceRegistry,
@@ -297,7 +300,7 @@ import {
 // package.json
 var package_default = {
   name: "@spotpatch/next",
-  version: "0.4.0",
+  version: "0.6.0",
   description: "Development-only Next.js adapter and CLI for SpotPatch.",
   license: "MIT",
   repository: {
@@ -390,6 +393,7 @@ var package_default = {
     "verify:loader": "node scripts/verify-loader.cjs"
   },
   dependencies: {
+    "@spotpatch/bridge": "workspace:^",
     "@spotpatch/compiler": "workspace:^",
     "@spotpatch/dev-server": "workspace:^",
     "@spotpatch/runtime": "workspace:^",
@@ -563,6 +567,7 @@ async function createNextSidecar(sidecarOptions) {
   let closed = false;
   let registry;
   let agentManager;
+  let externalHandoffService;
   let handler = (_request, response) => {
     writeUnavailable(response, 503);
   };
@@ -621,9 +626,11 @@ async function createNextSidecar(sidecarOptions) {
         apiBase: SPOTPATCH_API_BASE,
         ai: createRuntimeAiConfig(input.options.ai),
         budget: input.options.budget,
+        dataFlow: createRuntimeDataFlowConfig(input.options.dataFlow),
         bundler: input.bundler,
         debug: input.options.debug,
         editor: input.options.editor,
+        externalAgent: input.options.externalAgent,
         framework: "next",
         frameworkVersion: input.nextVersion,
         locale: input.options.locale,
@@ -640,8 +647,24 @@ async function createNextSidecar(sidecarOptions) {
         environment: input.credentials,
         root: input.projectRoot
       });
+      const handoffService = input.options.externalAgent.enabled ? createExternalHandoffService({
+        framework: "next",
+        root: input.appRoot,
+        sessionId: session.id
+      }) : void 0;
+      if (handoffService !== void 0) {
+        try {
+          await handoffService.start();
+        } catch {
+          process.stderr.write(
+            "[spotpatch:next] External Agent handoff is unavailable; core tools remain active.\n"
+          );
+        }
+      }
+      externalHandoffService = handoffService;
       const middleware = createSpotPatchMiddleware({
         ...manager === void 0 ? {} : { agentManager: manager },
+        ...handoffService === void 0 ? {} : { externalHandoffService: handoffService },
         bootstrap: {
           expectedOrigin: input.publicOrigin,
           runtimeConfig
@@ -687,6 +710,8 @@ async function createNextSidecar(sidecarOptions) {
         writeUnavailable(response, 503);
       };
       registry?.clear();
+      await externalHandoffService?.close();
+      externalHandoffService = void 0;
       await agentManager?.close();
       server.closeIdleConnections();
       const closing = closeServer(server);
@@ -1037,9 +1062,7 @@ function importInsertionOffset(program) {
 function insertStaticImport(magicString, program, statement) {
   const offset = importInsertionOffset(program);
   if (offset === 0) {
-    magicString.prepend(`${statement}
-
-`);
+    magicString.prepend(`${statement}${program.body.length === 0 ? "\n" : "\n\n"}`);
     return;
   }
   magicString.appendRight(offset, `
@@ -1120,6 +1143,27 @@ function wrappedFactoryCall(declaration, wrapperName) {
   const callee = unwrapParentheses(factoryCall.callee);
   return callee.type === "Identifier" && callee.name === wrapperName ? factoryCall : void 0;
 }
+function staticPropertyName(property) {
+  if (property.computed) return void 0;
+  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"
+  );
+  if (properties.length > 1) {
+    throw new Error("SpotPatch init found duplicate dataFlow options.");
+  }
+  const property = properties[0];
+  if (property !== void 0 && !(property.value.type === "Literal" && property.value.value === false)) {
+    throw new Error(
+      "SpotPatch Next does not support component dataFlow yet; remove dataFlow or set it to false."
+    );
+  }
+}
 function transformNextConfig(absolutePath, source, trustedFastModeAvailable) {
   if (absolutePath.endsWith(".cjs") || absolutePath.endsWith(".cts")) {
     throw new Error(
@@ -1138,6 +1182,7 @@ 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,
@@ -1375,7 +1420,7 @@ async function checkNextIntegration(directory = process.cwd()) {
 // src/cli.ts
 function writeUsage() {
   process.stderr.write(
-    "Usage: spotpatch-next <dev|init|check>\n  dev [next dev options]  Start the local Next.js development server.\n  init                    Preview and apply safe integration changes.\n  check                   Verify the integration without writing files.\n"
+    "Usage: spotpatch-next <dev|init|check|connect|bridge>\n  dev [next dev options]  Start the local Next.js development server.\n  init                    Preview and apply safe integration changes.\n  check                   Verify the integration without writing files.\n  connect codex           Start the zero-setup Codex Agent connector.\n  bridge                  Run external-Agent MCP, CLI, or setup commands.\n"
   );
 }
 function verifyAdapterExports(appRoot) {
@@ -1467,6 +1512,12 @@ async function main(arguments_) {
   if (command === "check") {
     return runCheck(rest);
   }
+  if (command === "bridge") {
+    return runSpotPatchBridgeCli(rest, { adapter: "next" });
+  }
+  if (command === "connect") {
+    return runSpotPatchBridgeCli(arguments_, { adapter: "next" });
+  }
   writeUsage();
   return 1;
 }