@spotpatch/vite 1.7.0 → 1.9.0

package/README.md

@@ -17,24 +17,26 @@ The supported Vite integration for SpotPatch: select React UI, trace it to JSX/T
 
 SpotPatch runs only with the Vite development server. Production builds contain no SpotPatch Runtime, source markers, or local API endpoints.
 
-### Install
+### One-command setup (recommended)
 
 ```bash
-npm install --save-dev @spotpatch/vite
-# or
-pnpm add -D @spotpatch/vite
+npx --yes @spotpatch/vite@latest setup
 ```
 
-### Initialize
+This npm-bootstrap command supports both npm and pnpm projects. It fetches the registry's actual latest CLI, detects the project package manager, installs that CLI's exact SpotPatch version, updates a supported `vite.config.*`, and verifies the result. The exact-version handoff avoids pnpm 11's default 24-hour `minimumReleaseAge` policy silently resolving `@latest` to an older mature release.
 
-Run the safe, idempotent initializer and its read-only diagnostic:
+The initializer supports configuration objects and object-returning `defineConfig` callbacks, while ambiguous dynamic configurations fail without writing the config.
+
+For npm, installation and initialization can also be kept separate:
 
 ```bash
-pnpm exec spotpatch-vite init
-pnpm exec spotpatch-vite check
+npm install --save-dev @spotpatch/vite@latest
+npx spotpatch-vite init
 ```
 
-The initializer places SpotPatch before the React plugin. When the project has a local TypeScript installation and root `tsconfig.json`, it also exposes the in-page Review / Trusted direct selector without duplicating provider configuration:
+With pnpm 11, use the recommended setup command, install a trusted exact version, or wait until the release is 24 hours old. SpotPatch does not globally disable the project's supply-chain quarantine.
+
+The initializer places SpotPatch before the React plugin so source markers are injected before React transforms the module:
 
 ```ts
 // vite.config.ts
@@ -43,10 +45,12 @@ import react from "@vitejs/plugin-react-swc";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [spotPatch({ trustedFastMode: true }), react()],
+  plugins: [spotPatch({ dataFlow: {}, trustedFastMode: true }), react()],
 });
 ```
 
+When no safe local TypeScript check can be discovered, it generates `spotPatch({ dataFlow: {} })` and keeps Review mode. Unsupported dynamic configuration can still be integrated manually using the same plugin order.
+
 Start the application normally:
 
 ```bash
@@ -55,16 +59,22 @@ pnpm dev
 
 Select **Select element** in the bottom-right corner or press `Mod+Shift+S`. SpotPatch can collect multiple targets across same-project pages, preserve them through navigation and workbench close/reopen cycles, keep a separate instruction for each one, open the exact source location in Cursor or VS Code, and generate a structured prompt without requiring AI configuration.
 
+### Component data flow (Beta)
+
+The current `setup/init` writes `spotPatch({ dataFlow: {} })` automatically; use the same option for manual integration. The Vite + React 18 development-only **Data flow** and **Page APIs** tabs show proven method/path, parameter keys, source-consumed response fields, data destinations, actually dispatched requests, and unassigned current-page traffic. Query values and response bodies are not collected. A relationship is reported only when stable component/source/callsite/invocation evidence agrees; ambiguous traffic remains unknown or unassigned. Data-flow AI, safe JSON response inspection, and Next.js are not included in this Beta. See the repository's [exact implementation status](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/%E7%BB%84%E4%BB%B6%E6%95%B0%E6%8D%AE%E9%93%BE%E8%B7%AF/13-Beta%E5%AE%9E%E7%8E%B0%E7%8A%B6%E6%80%81%E4%B8%8E%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C.md).
+
+Supported adapters include direct/component-service `fetch`, Axios, React Query/TanStack Query callbacks, and experimental tRPC logical procedures. tRPC batch HTTP transport remains separate evidence and is never assigned by timing or URL similarity.
+
 ### Compatibility
 
 | Dependency           | Supported range                |
 | -------------------- | ------------------------------ |
 | Node.js              | `>=20.19.0`                    |
-| Vite                 | `^5.0.0                        |     | ^6.0.0 |     | ^7.0.0` |
+| Vite                 | `>=5.0.0 <8.0.0`               |
 | React public support | `18.2–18.3`                    |
 | Default source files | `src/**/*.jsx`, `src/**/*.tsx` |
 
-React 19 is not part of the Vite v1 public support promise. Next.js projects must not use this package as a substitute for a Next adapter; see the repository's [Next.js status](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/Next%E9%80%82%E9%85%8D/00-%E7%B4%A2%E5%BC%95%E4%B8%8E%E6%9E%B6%E6%9E%84%E6%91%98%E8%A6%81.md).
+React 19, including 19.2.x, is not part of the Vite v1 public support promise. You may try it experimentally, but verify picking, source resolution, HMR, and the AI workflow in your application before relying on it. Next.js projects must not use this package as a substitute for a Next adapter; see the repository's [Next.js status](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/Next%E9%80%82%E9%85%8D/00-%E7%B4%A2%E5%BC%95%E4%B8%8E%E6%9E%B6%E6%9E%84%E6%91%98%E8%A6%81.md).
 
 ### Options
 
@@ -79,6 +89,7 @@ spotPatch({
   locale: "auto",
   maxTargets: 8,
   ai: false,
+  dataFlow: false,
 });
 ```
 
@@ -96,6 +107,7 @@ spotPatch({
 | `locale`          | `"auto"`                                          | Resolves `en-US` or `zh-CN`.                                            |
 | `maxTargets`      | `8`                                               | Targets allowed in one change request by default.                       |
 | `ai`              | disabled or a detected complete environment       | Optional provider and Agent settings.                                   |
+| `dataFlow`        | `false`                                           | Opt-in dispatch-only component data-flow Beta.                          |
 | `trustedFastMode` | `false`                                           | Exposes Review/Trusted direct and discovers TypeScript for Review.      |
 
 The package exports the option types, AI provider types, Agent limits, and immutable defaults. See the [public API specification](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/03-%E5%85%AC%E5%85%B1API%E4%B8%8E%E6%95%B0%E6%8D%AE%E6%A8%A1%E5%9E%8B.md) for the complete constraints.
@@ -129,7 +141,7 @@ spotPatch({
 
 The default Agent path is review-gated: **Check environment** provides an optional source-free capability diagnostic, while Run starts the real isolated tool session directly and proves tool continuation inline. The Agent supplies bounded nearby project conventions, exposes file tools rather than an arbitrary shell, reuses current host-run checks, and shows the complete Diff before Apply.
 
-`spotpatch-vite init` automatically enables the page selector when it can discover a local TypeScript check. The equivalent concise manual option is:
+To expose the optional Trusted direct mode, configure it explicitly. It requires a local TypeScript project check; otherwise keep the default Review mode:
 
 ```ts
 spotPatch({ trustedFastMode: true });
@@ -149,6 +161,8 @@ The page defaults to Review. Choosing Trusted direct uses the exact SpotPatch so
 
 ### Troubleshooting
 
+- **pnpm 11 installs an older version for `@latest`:** its default 24-hour `minimumReleaseAge` policy selects the newest mature release. Use the recommended `npx ... setup`, specify a trusted exact version, or wait 24 hours.
+- **Initializer rejects the config:** use a configuration object or a callback with one unambiguous object return. For conditional returns or dynamic plugin arrays, configure `spotPatch({ dataFlow: {} })` manually before the React plugin.
 - **No selection button:** confirm `spotPatch()` appears before the React plugin and that the app is running through `vite`/`vite dev`, not `vite preview`.
 - **No exact source location:** confirm the component is authored in an included `.jsx` or `.tsx` file under `src`, or configure `include` explicitly.
 - **AI is unavailable:** provide all three required environment values or set `ai: false`; partial environment configuration fails closed.
@@ -169,24 +183,26 @@ The page defaults to Review. Choosing Trusted direct uses the exact SpotPatch so
 
 SpotPatch 只在 Vite 开发服务器中运行。生产构建不包含 SpotPatch Runtime、源码标记或本地 API 端点。
 
-### 安装
+### 一条命令接入（推荐）
 
 ```bash
-npm install --save-dev @spotpatch/vite
-# 或
-pnpm add -D @spotpatch/vite
+npx --yes @spotpatch/vite@latest setup
 ```
 
-### 初始化
+这条由 npm 引导的命令同时支持 npm 和 pnpm 项目。它先取得 registry 真正的最新 CLI，再识别项目包管理器、安装该 CLI 对应的 SpotPatch 精确版本、安全更新受支持的 `vite.config.*` 并验证结果。精确版本交接可以避免 pnpm 11 默认 24 小时 `minimumReleaseAge` 把 `@latest` 解析成较旧的成熟版本。
 
-运行安全、幂等的初始化命令，再执行只读诊断：
+初始化器支持配置对象和返回对象的 `defineConfig` 回调；有歧义的动态配置会在不写入配置文件的情况下失败。
+
+npm 项目也可以分开安装和初始化：
 
 ```bash
-pnpm exec spotpatch-vite init
-pnpm exec spotpatch-vite check
+npm install --save-dev @spotpatch/vite@latest
+npx spotpatch-vite init
 ```
 
-初始化器会把 SpotPatch 放在 React 插件之前；项目存在本地 TypeScript 与根 `tsconfig.json` 时，还会自动开放页面内的“审阅 / 可信极速”选择，不需要重复填写 Provider：
+pnpm 11 项目请使用推荐的 setup 命令、安装已确认的精确版本，或等待发布满 24 小时。SpotPatch 不会全局关闭项目的供应链隔离策略。
+
+初始化器会将 SpotPatch 放在 React 插件之前，确保源码标记在 React 转换前注入：
 
 ```ts
 // vite.config.ts
@@ -195,10 +211,12 @@ import react from "@vitejs/plugin-react-swc";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [spotPatch({ trustedFastMode: true }), react()],
+  plugins: [spotPatch({ dataFlow: {}, trustedFastMode: true }), react()],
 });
 ```
 
+无法发现安全的本地 TypeScript 检查时，初始化器会生成 `spotPatch({ dataFlow: {} })` 并保持审阅模式。不受支持的动态配置仍可按相同插件顺序手动接入。
+
 照常启动应用：
 
 ```bash
@@ -207,16 +225,22 @@ pnpm dev
 
 点击右下角的 **选择元素** 或按下 `Mod+Shift+S`。SpotPatch 支持跨同一项目的多个页面采集目标，在页面跳转及工作台关闭/重开后保留目标与独立修改要求，在 Cursor 或 VS Code 中打开精确位置，并且在完全不配置 AI 的情况下生成结构化 Prompt。
 
+### 组件数据链路（Beta）
+
+新版 `setup/init` 会自动写入 `spotPatch({ dataFlow: {} })`，手工接入时使用同一选项。Vite + React 18 开发期的 **数据链路** 与 **页面接口** 页签会显示有证据的 method/path、参数键、源码消费字段、数据去向、实际 dispatch 请求和当前页面未归属流量；不采集 query 值或响应体。只有稳定组件、源码、callsite 与 invocation 证据一致时才建立关联，歧义流量保持 unknown/unassigned。当前不包含 data-flow AI、安全 JSON 响应读取或 Next.js 支持。准确范围见仓库中的 [实现状态文档](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/%E7%BB%84%E4%BB%B6%E6%95%B0%E6%8D%AE%E9%93%BE%E8%B7%AF/13-Beta%E5%AE%9E%E7%8E%B0%E7%8A%B6%E6%80%81%E4%B8%8E%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C.md)。
+
+已支持的适配器包括组件直接/Service `fetch`、Axios、React Query/TanStack Query 回调和实验性的 tRPC 逻辑 procedure。tRPC batch HTTP 传输保持为独立证据，绝不按时间或 URL 相似度强行归属。
+
 ### 兼容范围
 
 | 依赖           | 正式支持范围                   |
 | -------------- | ------------------------------ |
 | Node.js        | `>=20.19.0`                    |
-| Vite           | `^5.0.0                        |     | ^6.0.0 |     | ^7.0.0` |
+| Vite           | `>=5.0.0 <8.0.0`               |
 | React 正式支持 | `18.2–18.3`                    |
 | 默认源码文件   | `src/**/*.jsx`、`src/**/*.tsx` |
 
-React 19 不在 Vite v1 正式承诺内。Next.js 项目不能把本包当作 Next 适配器使用；准确状态见仓库中的 [Next.js 适配说明](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/Next%E9%80%82%E9%85%8D/00-%E7%B4%A2%E5%BC%95%E4%B8%8E%E6%9E%B6%E6%9E%84%E6%91%98%E8%A6%81.md)。
+React 19（包括 19.2.x）不在 Vite v1 正式承诺内。可以作为实验性组合尝试，但在日常使用前必须在自身项目验证元素选择、源码定位、HMR 和 AI 流程。Next.js 项目不能把本包当作 Next 适配器使用；准确状态见仓库中的 [Next.js 适配说明](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/Next%E9%80%82%E9%85%8D/00-%E7%B4%A2%E5%BC%95%E4%B8%8E%E6%9E%B6%E6%9E%84%E6%91%98%E8%A6%81.md)。
 
 ### 选项
 
@@ -231,6 +255,7 @@ spotPatch({
   locale: "auto",
   maxTargets: 8,
   ai: false,
+  dataFlow: false,
 });
 ```
 
@@ -248,6 +273,7 @@ spotPatch({
 | `locale`          | `"auto"`                     | 自动解析 `en-US` 或 `zh-CN`。                          |
 | `maxTargets`      | `8`                          | 一次修改任务默认允许的目标数。                         |
 | `ai`              | 关闭或检测到完整环境配置     | 可选 Provider 和 Agent 配置。                          |
+| `dataFlow`        | `false`                      | 可选 dispatch-only 组件数据链路 Beta。                 |
 | `trustedFastMode` | `false`                      | 开放审阅/可信极速选择；TypeScript 检查供审阅模式使用。 |
 
 本包导出选项类型、AI Provider 类型、Agent 限制和不可变默认值。完整约束见[公共 API 规范](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/03-%E5%85%AC%E5%85%B1API%E4%B8%8E%E6%95%B0%E6%8D%AE%E6%A8%A1%E5%9E%8B.md)。
@@ -281,7 +307,7 @@ spotPatch({
 
 默认 Agent 路径必须经过审阅：“检查运行环境”提供不含源码的可选能力诊断；点击运行会直接进入真实隔离工具会话，并在会话内证明工具续接能力。Agent 会提供有界的就近项目规范，只暴露文件工具而不是任意 Shell，复用当前变更版本中由宿主实际执行的检查，并在 Apply 前展示完整 Diff。
 
-`spotpatch-vite init` 能发现本地 TypeScript 校验时会自动开放页面选择；等价的简洁手动配置只有一行：
+需要开放可选的“可信极速”模式时，请显式配置。它要求项目能提供本地 TypeScript 检查；否则请保持默认的审阅模式：
 
 ```ts
 spotPatch({ trustedFastMode: true });
@@ -301,6 +327,8 @@ spotPatch({ trustedFastMode: true });
 
 ### 常见问题
 
+- **pnpm 11 对 `@latest` 安装了旧版本：**默认 24 小时 `minimumReleaseAge` 会选择最新的成熟版本。请使用推荐的 `npx ... setup`、安装已确认的精确版本，或等待 24 小时。
+- **初始化器拒绝配置：**请使用配置对象，或只含一个明确对象返回的回调。存在条件返回或动态插件数组时，手动将 `spotPatch({ dataFlow: {} })` 放到 React 插件之前。
 - **没有选择元素按钮：**确认 `spotPatch()` 位于 React 插件之前，并且应用通过 `vite`/`vite dev` 而不是 `vite preview` 启动。
 - **没有精确源码位置：**确认组件来自 include 范围内的 `.jsx` 或 `.tsx` 文件，默认范围是 `src`。
 - **AI 不可用：**提供全部三个必需环境变量，或者显式设置 `ai: false`；不完整配置会安全失败。

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFile } from "fs/promises";
+import { readFile as readFile2 } from "fs/promises";
 import { createRequire } from "module";
-import path2 from "path";
+import path3 from "path";
 
 // src/initializer.ts
 import path from "path";
@@ -68,6 +68,16 @@ function insertStaticImport(magicString, program, statement) {
   magicString.appendRight(offset, `
 ${statement}`);
 }
+function importQuote(source, program) {
+  const firstImport = importsOf(program)[0];
+  if (firstImport !== void 0) {
+    const quote = source[firstImport.source.start];
+    if (quote === '"' || quote === "'") {
+      return quote;
+    }
+  }
+  return '"';
+}
 function collectIdentifierNames(program) {
   const names = /* @__PURE__ */ new Set();
   new Visitor({
@@ -153,6 +163,47 @@ function resolveConfigExpression(program) {
   }
   return unwrapExpression(resolved);
 }
+function resolveFactoryConfigObject(expression) {
+  const factory = unwrapExpression(expression);
+  if (factory.type !== "ArrowFunctionExpression" && factory.type !== "FunctionExpression") {
+    return void 0;
+  }
+  if (factory.body === null) {
+    throw new Error(
+      "SpotPatch init cannot use a defineConfig callback without a body."
+    );
+  }
+  if (factory.body.type !== "BlockStatement") {
+    const returned2 = unwrapExpression(factory.body);
+    return returned2.type === "ObjectExpression" ? returned2 : void 0;
+  }
+  const returns = [];
+  new Visitor({
+    ReturnStatement(statement) {
+      returns.push(statement);
+    }
+  }).visit({
+    type: "Program",
+    body: factory.body.body,
+    sourceType: "module",
+    hashbang: null,
+    start: factory.body.start,
+    end: factory.body.end
+  });
+  const onlyReturn = returns.length === 1 ? returns[0] : void 0;
+  if (onlyReturn?.argument == null) {
+    throw new Error(
+      "SpotPatch init requires a defineConfig callback with exactly one top-level object return."
+    );
+  }
+  const returned = unwrapExpression(onlyReturn.argument);
+  if (returned.type !== "ObjectExpression") {
+    throw new Error(
+      "SpotPatch init requires the defineConfig callback to return a configuration object directly."
+    );
+  }
+  return returned;
+}
 function resolveConfigObject(program) {
   const expression = resolveConfigExpression(program);
   if (expression.type === "ObjectExpression") {
@@ -166,10 +217,14 @@ function resolveConfigObject(program) {
       if (value.type === "ObjectExpression") {
         return value;
       }
+      const callbackObject = resolveFactoryConfigObject(value);
+      if (callbackObject !== void 0) {
+        return callbackObject;
+      }
     }
   }
   throw new Error(
-    "SpotPatch init currently supports an object passed to defineConfig in vite.config."
+    "SpotPatch init supports a configuration object or an object-returning callback passed to defineConfig."
   );
 }
 function propertyName(property) {
@@ -204,8 +259,12 @@ function childIndent(source, object) {
   }
   return `${lineIndentAt(source, object.start)}  `;
 }
-function trustedFastCall(pluginName, enabled) {
-  return enabled ? `${pluginName}({ trustedFastMode: true })` : `${pluginName}()`;
+function initializedPluginCall(pluginName, trustedFastMode) {
+  const options = [
+    "dataFlow: {}",
+    ...trustedFastMode ? ["trustedFastMode: true"] : []
+  ];
+  return `${pluginName}({ ${options.join(", ")} })`;
 }
 function directPluginCalls(plugins, pluginName) {
   return plugins.elements.filter((element) => {
@@ -216,12 +275,12 @@ function directPluginCalls(plugins, pluginName) {
     return callee.type === "Identifier" && callee.name === pluginName;
   });
 }
-function enableTrustedFastMode(magicString, source, call) {
+function enableInitializedOptions(magicString, source, call, trustedFastMode) {
   if (call.arguments.length === 0) {
     magicString.overwrite(
       call.start,
       call.end,
-      `${source.slice(call.start, call.end - 1)}{ trustedFastMode: true })`
+      initializedPluginCall(source.slice(call.start, call.callee.end), trustedFastMode)
     );
     return;
   }
@@ -233,33 +292,55 @@ function enableTrustedFastMode(magicString, source, call) {
   if (value.type !== "ObjectExpression") {
     throw new Error("SpotPatch init requires spotPatch options to be an object.");
   }
-  const property = findProperty(value, "trustedFastMode");
-  if (property !== void 0) {
-    const propertyValue = unwrapExpression(property.value);
+  if (value.properties.some((property) => property.type === "SpreadElement")) {
+    throw new Error(
+      "SpotPatch init cannot prove dataFlow through spread spotPatch options."
+    );
+  }
+  const dataFlowProperty = findProperty(value, "dataFlow");
+  const trustedFastModeProperty = findProperty(value, "trustedFastMode");
+  const missingProperties = [];
+  if (dataFlowProperty === void 0) {
+    missingProperties.push("dataFlow: {}");
+  } else {
+    const dataFlowValue = unwrapExpression(dataFlowProperty.value);
+    if (dataFlowValue.type === "Literal" && dataFlowValue.value === false) {
+      magicString.overwrite(dataFlowValue.start, dataFlowValue.end, "{}");
+    } else if (dataFlowValue.type !== "ObjectExpression") {
+      throw new Error(
+        "SpotPatch init requires dataFlow to be false or an options object."
+      );
+    }
+  }
+  if (trustedFastMode && trustedFastModeProperty === void 0) {
+    missingProperties.push("trustedFastMode: true");
+  } else if (trustedFastModeProperty !== void 0) {
+    const propertyValue = unwrapExpression(trustedFastModeProperty.value);
     if (propertyValue.type !== "Literal" || typeof propertyValue.value !== "boolean") {
       throw new Error(
         "SpotPatch init requires trustedFastMode to be a boolean literal."
       );
     }
-    if (!propertyValue.value) {
+    if (trustedFastMode && !propertyValue.value) {
       magicString.overwrite(propertyValue.start, propertyValue.end, "true");
     }
-    return;
   }
+  if (missingProperties.length === 0) return;
   const indent = childIndent(source, value);
   if (value.properties.length === 0) {
-    magicString.appendLeft(value.end - 1, " trustedFastMode: true ");
+    magicString.appendLeft(value.end - 1, ` ${missingProperties.join(", ")} `);
   } else {
     magicString.appendLeft(
       value.properties[0]?.start ?? value.end - 1,
-      `trustedFastMode: true,
+      `${missingProperties.join(`,
+${indent}`)},
 ${indent}`
     );
   }
 }
 function addPluginCall(magicString, source, config, pluginName, trustedFastModeAvailable) {
   const pluginsProperty = findProperty(config, "plugins");
-  const call = trustedFastCall(pluginName, trustedFastModeAvailable);
+  const call = initializedPluginCall(pluginName, trustedFastModeAvailable);
   if (pluginsProperty === void 0) {
     const indent = childIndent(source, config);
     if (config.properties.length === 0) {
@@ -284,14 +365,19 @@ ${indent}`
     throw new Error("SpotPatch init found duplicate spotPatch plugins.");
   }
   if (existing[0] !== void 0) {
-    if (trustedFastModeAvailable) {
-      enableTrustedFastMode(magicString, source, existing[0]);
-    }
+    enableInitializedOptions(
+      magicString,
+      source,
+      existing[0],
+      trustedFastModeAvailable
+    );
     return;
   }
   const first = value.elements.find((element) => element !== null);
   if (first === void 0) {
     magicString.appendLeft(value.end - 1, call);
+  } else if (!source.slice(value.start, first.start).includes("\n")) {
+    magicString.appendLeft(first.start, `${call}, `);
   } else {
     magicString.appendLeft(
       first.start,
@@ -308,10 +394,11 @@ function transformViteConfig(absolutePath, source, trustedFastModeAvailable) {
   const magicString = new MagicString(source);
   if (existingPluginName === void 0) {
     const specifier = pluginName === "spotPatch" ? "spotPatch" : `spotPatch as ${pluginName}`;
+    const quote = importQuote(source, program);
     insertStaticImport(
       magicString,
       program,
-      `import { ${specifier} } from ${JSON.stringify(ADAPTER_PACKAGE_NAME)};`
+      `import { ${specifier} } from ${quote}${ADAPTER_PACKAGE_NAME}${quote};`
     );
   }
   addPluginCall(magicString, source, config, pluginName, trustedFastModeAvailable);
@@ -384,15 +471,119 @@ async function checkViteIntegration(directory = process.cwd()) {
   }
 }
 
+// src/setup.ts
+import { spawn } from "child_process";
+import { access, readFile } from "fs/promises";
+import path2 from "path";
+var VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+async function pathExists(absolutePath) {
+  try {
+    await access(absolutePath);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+      return false;
+    }
+    throw error;
+  }
+}
+async function detectPackageManager(appRoot = process.cwd(), userAgent = process.env.npm_config_user_agent ?? "") {
+  const manifestPath = path2.join(appRoot, "package.json");
+  const manifest = JSON.parse(
+    await readFile(manifestPath, "utf8")
+  );
+  const declared = manifest.packageManager;
+  if (typeof declared === "string") {
+    const name = declared.split("@", 1)[0];
+    if (name === "pnpm" || name === "npm") {
+      return name;
+    }
+    throw new Error(
+      `SpotPatch setup supports npm and pnpm projects; package.json declares ${declared}.`
+    );
+  }
+  const [hasPnpmLock, hasNpmLock] = await Promise.all([
+    pathExists(path2.join(appRoot, "pnpm-lock.yaml")),
+    pathExists(path2.join(appRoot, "package-lock.json"))
+  ]);
+  if (hasPnpmLock !== hasNpmLock) {
+    return hasPnpmLock ? "pnpm" : "npm";
+  }
+  if (hasPnpmLock && hasNpmLock) {
+    throw new Error(
+      "SpotPatch setup found both pnpm-lock.yaml and package-lock.json; remove the stale lockfile or run installation and init separately."
+    );
+  }
+  if (userAgent.startsWith("pnpm/")) {
+    return "pnpm";
+  }
+  if (userAgent.startsWith("npm/")) {
+    return "npm";
+  }
+  throw new Error(
+    "SpotPatch setup could not determine npm or pnpm; run installation and init separately."
+  );
+}
+function createInstallCommand(packageManager, version, platform = process.platform) {
+  if (!VERSION_PATTERN.test(version)) {
+    throw new Error("SpotPatch setup could not determine its package version.");
+  }
+  const packageSpecifier = `@spotpatch/vite@${version}`;
+  return Object.freeze({
+    executable: platform === "win32" ? `${packageManager}.cmd` : packageManager,
+    arguments: Object.freeze(
+      packageManager === "pnpm" ? ["add", "-D", packageSpecifier] : ["install", "--save-dev", packageSpecifier]
+    )
+  });
+}
+async function readCurrentAdapterVersion() {
+  const manifest = JSON.parse(
+    await readFile(new URL("../package.json", import.meta.url), "utf8")
+  );
+  const version = manifest.version;
+  if (typeof version !== "string" || !VERSION_PATTERN.test(version)) {
+    throw new Error("SpotPatch setup could not determine its package version.");
+  }
+  return version;
+}
+async function installCurrentAdapter(packageManager, appRoot = process.cwd()) {
+  const version = await readCurrentAdapterVersion();
+  const command = createInstallCommand(packageManager, version);
+  process.stdout.write(
+    `[spotpatch:vite] installing @spotpatch/vite@${version} with ${packageManager}...
+`
+  );
+  await new Promise((resolve, reject) => {
+    const child = spawn(command.executable, command.arguments, {
+      cwd: appRoot,
+      env: process.env,
+      shell: false,
+      stdio: "inherit"
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(
+          `SpotPatch setup installation failed (${signal ?? `exit ${String(code)}`}).`
+        )
+      );
+    });
+  });
+}
+
 // src/cli.ts
-var VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/u;
+var VERSION_PATTERN2 = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/u;
 function writeUsage() {
   process.stderr.write(
-    "Usage: spotpatch-vite <init|check>\n  init   Preview and apply safe Vite integration changes.\n  check  Verify the Vite integration without writing files.\n"
+    "Usage: spotpatch-vite <setup|init|check>\n  setup  Install this CLI's exact @spotpatch/vite version, then initialize it.\n  init   Preview and apply safe Vite integration changes.\n  check  Verify the Vite integration without writing files.\n"
   );
 }
 async function inspectViteProject(appRoot = process.cwd()) {
-  const resolveFromApplication = createRequire(path2.join(appRoot, "package.json"));
+  const resolveFromApplication = createRequire(path3.join(appRoot, "package.json"));
   let adapterEntry;
   let viteManifestPath;
   try {
@@ -407,9 +598,9 @@ async function inspectViteProject(appRoot = process.cwd()) {
   if (adapterEntry.length === 0) {
     throw new Error("SpotPatch could not resolve the Vite adapter export.");
   }
-  const manifest = JSON.parse(await readFile(viteManifestPath, "utf8"));
+  const manifest = JSON.parse(await readFile2(viteManifestPath, "utf8"));
   const version = typeof manifest === "object" && manifest !== null && "version" in manifest && typeof manifest.version === "string" ? manifest.version : void 0;
-  const match = version === void 0 ? null : VERSION_PATTERN.exec(version);
+  const match = version === void 0 ? null : VERSION_PATTERN2.exec(version);
   const major = Number(match?.[1]);
   if (version === void 0 || match === null || !Number.isSafeInteger(major) || major < 5 || major >= 8) {
     throw new Error(
@@ -451,6 +642,14 @@ ${change.nextContent}`);
   writeTrustedModeStatus(plan.trustedFastModeAvailable);
   return 0;
 }
+async function runSetup(arguments_) {
+  if (arguments_.length !== 0) {
+    throw new Error("SpotPatch setup does not accept positional arguments.");
+  }
+  const packageManager = await detectPackageManager();
+  await installCurrentAdapter(packageManager);
+  return runInit([]);
+}
 async function runCheck(arguments_) {
   if (arguments_.length !== 0) {
     throw new Error("SpotPatch check does not accept positional arguments.");
@@ -473,6 +672,9 @@ async function runCheck(arguments_) {
 }
 async function main(arguments_) {
   const [command, ...rest] = arguments_;
+  if (command === "setup") {
+    return runSetup(rest);
+  }
   if (command === "init") {
     return runInit(rest);
   }