@spotpatch/vite 1.0.0 → 1.2.0

package/README.md

@@ -22,22 +22,45 @@ import react from "@vitejs/plugin-react-swc";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [
-    spotPatch({
-      editor: "vscode",
-      redact: true,
-      allowLan: false,
-      locale: "auto",
-      maxTargets: 8,
-    }),
-    react(),
-  ],
+  plugins: [spotPatch(), react()],
 });
 ```
 
 SpotPatch injects no runtime, source markers, or local API endpoints into a
-production build. AI execution is disabled unless a trusted Node-side provider
-profile is explicitly configured; API keys must never use a `VITE_` prefix.
+production build. AI stays disabled when no AI environment exists. To enable the
+single-provider setup without changing `vite.config.ts`, add the three required
+values to a Git-ignored `.env.local`:
+
+```dotenv
+SPOTPATCH_AI_BASE_URL=https://relay.example.com/v1
+SPOTPATCH_AI_MODEL=provider-model-name
+SPOTPATCH_AI_API_KEY=<your-key>
+```
+
+`SPOTPATCH_AI_PROTOCOL` optionally selects `chat-completions` (the default) or
+`responses`. `SPOTPATCH_AI_AUTHENTICATION` optionally selects `bearer` (the
+default) or `x-api-key`. Partial environment configuration fails fast without
+printing credential values. API keys must never use a `VITE_` prefix.
+
+Source actions auto-detect Cursor or VS Code and open the selected file at its
+exact line and column. Set `editor: "cursor"` or `editor: "vscode"` only when an
+explicit preference is required. The workbench also links to the
+[SpotPatch GitHub repository](https://github.com/huanglvjing/spotpatch) for docs,
+issues, and project updates.
+
+Non-secret URL and model values can instead use the concise API:
+
+```ts
+spotPatch({
+  ai: {
+    baseURL: "https://relay.example.com/v1",
+    model: "provider-model-name",
+  },
+});
+```
+
+The full provider map remains available for multiple providers, multiple models,
+custom labels, checks, and limits.
 
 See the [repository README](https://github.com/huanglvjing/spotpatch#readme) for
 the complete setup and security model.

package/dist/index.cjs

@@ -37,6 +37,71 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/plugin.ts
+var import_node_path10 = __toESM(require("path"), 1);
+var import_vite2 = require("vite");
+
+// src/environment-ai.ts
+var AI_ENVIRONMENT_NAMES = Object.freeze({
+  authentication: "SPOTPATCH_AI_AUTHENTICATION",
+  baseURL: "SPOTPATCH_AI_BASE_URL",
+  credential: "SPOTPATCH_AI_API_KEY",
+  model: "SPOTPATCH_AI_MODEL",
+  protocol: "SPOTPATCH_AI_PROTOCOL"
+});
+function normalizedValue(environment, name) {
+  const value = environment[name];
+  if (value === void 0 || value.trim().length === 0) {
+    return void 0;
+  }
+  return value.trim();
+}
+function resolveEnvironmentAiConfiguration(environment) {
+  const baseURL = normalizedValue(environment, AI_ENVIRONMENT_NAMES.baseURL);
+  const model = normalizedValue(environment, AI_ENVIRONMENT_NAMES.model);
+  const credential = normalizedValue(environment, AI_ENVIRONMENT_NAMES.credential);
+  const protocol = normalizedValue(environment, AI_ENVIRONMENT_NAMES.protocol);
+  const authentication = normalizedValue(
+    environment,
+    AI_ENVIRONMENT_NAMES.authentication
+  );
+  const configuredValues = [baseURL, model, credential, protocol, authentication];
+  if (configuredValues.every((value) => value === void 0)) {
+    return Object.freeze({ ai: false });
+  }
+  const missing = [
+    [AI_ENVIRONMENT_NAMES.baseURL, baseURL],
+    [AI_ENVIRONMENT_NAMES.model, model],
+    [AI_ENVIRONMENT_NAMES.credential, credential]
+  ].filter((entry) => entry[1] === void 0).map(([name]) => name);
+  if (missing.length > 0) {
+    throw new RangeError(
+      `SpotPatch AI environment configuration is incomplete; missing ${missing.join(", ")}.`
+    );
+  }
+  if (baseURL === void 0 || model === void 0 || credential === void 0) {
+    throw new RangeError("SpotPatch AI environment configuration is incomplete.");
+  }
+  if (protocol !== void 0 && protocol !== "responses" && protocol !== "chat-completions") {
+    throw new RangeError(
+      "SpotPatch SPOTPATCH_AI_PROTOCOL must be responses or chat-completions."
+    );
+  }
+  if (authentication !== void 0 && authentication !== "bearer" && authentication !== "x-api-key") {
+    throw new RangeError(
+      "SpotPatch SPOTPATCH_AI_AUTHENTICATION must be bearer or x-api-key."
+    );
+  }
+  return Object.freeze({
+    ai: Object.freeze({
+      baseURL,
+      model,
+      ...protocol === void 0 ? {} : { protocol },
+      ...authentication === void 0 ? {} : { authentication }
+    })
+  });
+}
+
 // src/options.ts
 var import_shared = require("@spotpatch/shared");
 var import_zod = require("zod");
@@ -61,7 +126,7 @@ var DEFAULT_OPTIONS = Object.freeze({
   enabled: true,
   include: DEFAULT_INCLUDE,
   exclude: DEFAULT_EXCLUDE,
-  editor: "vscode",
+  editor: "auto",
   redact: true,
   budget: DEFAULT_BUDGET,
   shortcut: "Mod+Shift+S",
@@ -101,6 +166,7 @@ var aiOptionsSchema = import_zod.z.strictObject({
       type: import_zod.z.literal("openai-compatible"),
       label: import_zod.z.string(),
       protocol: import_zod.z.enum(["responses", "chat-completions"]),
+      authentication: import_zod.z.enum(["bearer", "x-api-key"]).optional(),
       baseURL: import_zod.z.string(),
       apiKeyEnv: import_zod.z.string(),
       models: import_zod.z.record(
@@ -118,6 +184,16 @@ var aiOptionsSchema = import_zod.z.strictObject({
     limits: agentLimitsSchema
   }).optional()
 });
+var simpleAiOptionsSchema = import_zod.z.strictObject({
+  baseURL: import_zod.z.string(),
+  model: import_zod.z.string(),
+  apiKeyEnv: import_zod.z.string().optional(),
+  protocol: import_zod.z.enum(["responses", "chat-completions"]).optional(),
+  authentication: import_zod.z.enum(["bearer", "x-api-key"]).optional(),
+  providerLabel: import_zod.z.string().optional(),
+  modelLabel: import_zod.z.string().optional(),
+  execution: aiOptionsSchema.shape.execution
+});
 function assertIdentifier(value, label) {
   if (!PROFILE_ID_PATTERN.test(value)) {
     throw new RangeError(
@@ -217,6 +293,7 @@ function resolveProviders(providers) {
             type: provider.type,
             label: nonEmpty(provider.label, "provider label", 100),
             protocol: provider.protocol,
+            authentication: provider.authentication ?? "bearer",
             baseURL: normalizeProviderBaseURL(provider.baseURL),
             apiKeyEnv: provider.apiKeyEnv,
             models,
@@ -260,7 +337,36 @@ function resolveAiOptions(options) {
   if (options === void 0 || options === false) {
     return false;
   }
-  const parsed = aiOptionsSchema.safeParse(options);
+  const expanded = "providers" in options ? options : (() => {
+    const simple = simpleAiOptionsSchema.safeParse(options);
+    if (!simple.success) {
+      throw new RangeError("SpotPatch AI configuration is invalid.");
+    }
+    const providerId = "default";
+    const modelId = "default";
+    return {
+      providers: {
+        [providerId]: {
+          type: "openai-compatible",
+          label: simple.data.providerLabel ?? "AI provider",
+          protocol: simple.data.protocol ?? "chat-completions",
+          authentication: simple.data.authentication ?? "bearer",
+          baseURL: simple.data.baseURL,
+          apiKeyEnv: simple.data.apiKeyEnv ?? "SPOTPATCH_AI_API_KEY",
+          models: {
+            [modelId]: {
+              label: simple.data.modelLabel ?? "AI model",
+              model: simple.data.model
+            }
+          },
+          defaultModel: modelId
+        }
+      },
+      defaultProvider: providerId,
+      ...simple.data.execution === void 0 ? {} : { execution: simple.data.execution }
+    };
+  })();
+  const parsed = aiOptionsSchema.safeParse(expanded);
   if (!parsed.success) {
     throw new RangeError("SpotPatch AI configuration is invalid.");
   }
@@ -320,7 +426,7 @@ function assertPositiveBudget(budget) {
     }
   }
 }
-function resolveOptions(options = {}) {
+function resolveOptions(options = {}, environmentAi) {
   const budget = Object.freeze({
     ...DEFAULT_OPTIONS.budget,
     ...options.budget
@@ -328,9 +434,13 @@ function resolveOptions(options = {}) {
   assertPositiveBudget(budget);
   const maxTargets = options.maxTargets ?? DEFAULT_OPTIONS.maxTargets;
   const locale = options.locale ?? DEFAULT_OPTIONS.locale;
+  const editor = options.editor ?? DEFAULT_OPTIONS.editor;
   if (!import_shared.SPOTPATCH_LOCALE_PREFERENCES.includes(locale)) {
     throw new RangeError("SpotPatch locale must be auto, en-US, or zh-CN.");
   }
+  if (!import_shared.SPOTPATCH_EDITOR_PREFERENCES.includes(editor)) {
+    throw new RangeError("SpotPatch editor must be auto, vscode, or cursor.");
+  }
   if (!Number.isSafeInteger(maxTargets) || maxTargets < 1 || maxTargets > import_shared.MAX_ANNOTATION_TARGETS) {
     throw new RangeError(
       `SpotPatch maxTargets must be an integer between 1 and ${String(import_shared.MAX_ANNOTATION_TARGETS)}.`
@@ -340,7 +450,7 @@ function resolveOptions(options = {}) {
     enabled: options.enabled ?? DEFAULT_OPTIONS.enabled,
     include: Object.freeze([...options.include ?? DEFAULT_OPTIONS.include]),
     exclude: Object.freeze([...options.exclude ?? DEFAULT_OPTIONS.exclude]),
-    editor: options.editor ?? DEFAULT_OPTIONS.editor,
+    editor,
     redact: options.redact ?? DEFAULT_OPTIONS.redact,
     budget,
     shortcut: options.shortcut ?? DEFAULT_OPTIONS.shortcut,
@@ -348,7 +458,7 @@ function resolveOptions(options = {}) {
     debug: options.debug ?? DEFAULT_OPTIONS.debug,
     locale,
     maxTargets,
-    ai: resolveAiOptions(options.ai)
+    ai: resolveAiOptions(options.ai ?? environmentAi)
   };
   if (resolved.shortcut.trim().length === 0) {
     throw new RangeError("SpotPatch shortcut cannot be empty.");
@@ -405,7 +515,7 @@ var import_node_path2 = __toESM(require("path"), 1);
 // package.json
 var package_default = {
   name: "@spotpatch/vite",
-  version: "1.0.0",
+  version: "1.2.0",
   description: "Vite development plugin for SpotPatch.",
   license: "MIT",
   repository: {
@@ -497,15 +607,17 @@ function readConsumerViteVersion(root) {
   return import_vite.version;
 }
 function createClientModule(input, clientBundle, viteVersion) {
+  const options = input.context.getOptions();
   const runtimeConfig = {
-    ai: createRuntimeAiConfig(input.options.ai),
-    budget: input.options.budget,
-    debug: input.options.debug,
-    locale: input.options.locale,
-    maxTargets: input.options.maxTargets,
-    redact: input.options.redact,
+    ai: createRuntimeAiConfig(options.ai),
+    budget: options.budget,
+    debug: options.debug,
+    editor: options.editor,
+    locale: options.locale,
+    maxTargets: options.maxTargets,
+    redact: options.redact,
     sessionToken: input.session.token,
-    shortcut: input.options.shortcut,
+    shortcut: options.shortcut,
     spotPatchVersion: package_default.version,
     viteVersion
   };
@@ -628,7 +740,7 @@ function snapshot(job) {
   );
 }
 function capabilityCacheKey(provider, model) {
-  const configurationDigest = (0, import_node_crypto2.createHash)("sha256").update(provider.baseURL).update("\0").update(provider.protocol).digest("hex");
+  const configurationDigest = (0, import_node_crypto2.createHash)("sha256").update(provider.baseURL).update("\0").update(provider.protocol).update("\0").update(provider.authentication).digest("hex");
   return `${provider.id}:${model.id}:${configurationDigest}`;
 }
 function freezeEvent(event) {
@@ -1553,18 +1665,18 @@ var EVENT_STREAM_END_STATUSES = /* @__PURE__ */ new Set([
   "reverted",
   "failed"
 ]);
-function matchAgentRequestPath(path10) {
-  if (path10 === import_shared7.SPOTPATCH_ENDPOINTS.agentCapability) {
+function matchAgentRequestPath(path11) {
+  if (path11 === import_shared7.SPOTPATCH_ENDPOINTS.agentCapability) {
     return Object.freeze({ kind: "capability" });
   }
-  if (path10 === import_shared7.SPOTPATCH_ENDPOINTS.agentJobs) {
+  if (path11 === import_shared7.SPOTPATCH_ENDPOINTS.agentJobs) {
     return Object.freeze({ kind: "create-job" });
   }
   const prefix = `${import_shared7.SPOTPATCH_ENDPOINTS.agentJobs}/`;
-  if (!path10.startsWith(prefix)) {
+  if (!path11.startsWith(prefix)) {
     return void 0;
   }
-  const segments = path10.slice(prefix.length).split("/");
+  const segments = path11.slice(prefix.length).split("/");
   const jobId = segments[0];
   const action = segments[1];
   if (segments.length !== 2 || jobId === void 0 || !AGENT_JOB_ID_PATTERN.test(jobId) || action === void 0 || !AGENT_JOB_ACTIONS.has(action)) {
@@ -1709,9 +1821,36 @@ async function handleAgentRequest(request, response, options, route, writeSucces
 
 // src/server/editor.ts
 var import_launch_editor = __toESM(require("launch-editor"), 1);
-var launchVSCode = (target, onError) => {
-  (0, import_launch_editor.default)(target, "code", onError);
-};
+var EDITOR_STARTUP_GRACE_MS = 150;
+function editorCommand(editor) {
+  if (editor === "vscode") {
+    return "code";
+  }
+  if (editor === "cursor") {
+    return "cursor";
+  }
+  return void 0;
+}
+var launchConfiguredEditor = (target, editor) => new Promise((resolve, reject) => {
+  let settled = false;
+  const startupTimer = setTimeout(() => {
+    settled = true;
+    resolve();
+  }, EDITOR_STARTUP_GRACE_MS);
+  const rejectStartup = () => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    clearTimeout(startupTimer);
+    reject(new Error("The configured editor could not be started."));
+  };
+  try {
+    (0, import_launch_editor.default)(target, editorCommand(editor), rejectStartup);
+  } catch {
+    rejectStartup();
+  }
+});
 
 // src/server/request-security.ts
 var import_node_crypto3 = require("crypto");
@@ -1892,23 +2031,24 @@ async function handleOpenEditor(request, options) {
     root: options.root
   });
   const target = `${sourcePath}:${String(body.line)}:${String(body.column)}`;
-  const editorLauncher = options.editorLauncher ?? launchVSCode;
+  const editorLauncher = options.editorLauncher ?? launchConfiguredEditor;
   try {
-    editorLauncher(target, () => {
-      options.logger?.warn("[spotpatch:server] VS Code rejected an editor request.");
-    });
+    await editorLauncher(target, options.options.editor);
   } catch (error) {
+    options.logger?.warn(
+      `[spotpatch:server] ${options.options.editor === "auto" ? "The detected editor" : options.options.editor} rejected an editor request.`
+    );
     throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.EDITOR_OPEN_FAILED, void 0, {
       cause: error
     });
   }
-  return Object.freeze({});
+  return Object.freeze({ editor: options.options.editor });
 }
 function createSpotPatchMiddleware(options) {
   return (request, response, next) => {
-    const path10 = requestPath(request);
-    const agentRoute = matchAgentRequestPath(path10);
-    if (path10 !== import_shared9.SPOTPATCH_ENDPOINTS.sourceContext && path10 !== import_shared9.SPOTPATCH_ENDPOINTS.openEditor && agentRoute === void 0 && !path10.startsWith(`${import_shared9.SPOTPATCH_API_BASE}/`)) {
+    const path11 = requestPath(request);
+    const agentRoute = matchAgentRequestPath(path11);
+    if (path11 !== import_shared9.SPOTPATCH_ENDPOINTS.sourceContext && path11 !== import_shared9.SPOTPATCH_ENDPOINTS.openEditor && agentRoute === void 0 && !path11.startsWith(`${import_shared9.SPOTPATCH_API_BASE}/`)) {
       next();
       return;
     }
@@ -1917,7 +2057,7 @@ function createSpotPatchMiddleware(options) {
         allowLan: options.options.allowLan,
         sessionToken: options.session.token
       });
-      if (path10 === import_shared9.SPOTPATCH_ENDPOINTS.sourceContext) {
+      if (path11 === import_shared9.SPOTPATCH_ENDPOINTS.sourceContext) {
         if (request.method !== "POST") {
           throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.INVALID_REQUEST);
         }
@@ -1925,7 +2065,7 @@ function createSpotPatchMiddleware(options) {
         writeJson(response, 200, { ok: true, data });
         return;
       }
-      if (path10 === import_shared9.SPOTPATCH_ENDPOINTS.openEditor) {
+      if (path11 === import_shared9.SPOTPATCH_ENDPOINTS.openEditor) {
         if (request.method !== "POST") {
           throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.INVALID_REQUEST);
         }
@@ -1973,11 +2113,16 @@ function createServerPlugin(input) {
         throw new Error("SpotPatch server initialized before Vite config resolution.");
       }
       const root = import_node_path6.default.resolve(config.root);
-      agentManager = input.options.ai === false ? void 0 : createAgentJobManager({ ai: input.options.ai, root });
+      const options = input.context.getOptions();
+      agentManager = options.ai === false ? void 0 : createAgentJobManager({
+        ai: options.ai,
+        environment: input.context.getCredentialEnvironment(),
+        root
+      });
       server.middlewares.use(
         createSpotPatchMiddleware({
           ...agentManager === void 0 ? {} : { agentManager },
-          options: input.options,
+          options,
           registry: input.registry,
           root,
           session: input.session,
@@ -1988,7 +2133,7 @@ function createServerPlugin(input) {
         void closeResources();
       });
       config.logger.info(
-        `[spotpatch:vite] Ready. Toggle picker with ${input.options.shortcut}.`
+        `[spotpatch:vite] Ready. Toggle picker with ${options.shortcut}.`
       );
     },
     async closeBundle() {
@@ -2180,7 +2325,7 @@ function getDisplayPath(root, id) {
 }
 function createTransformPlugin(input) {
   let root = process.cwd();
-  let filter = createTransformFilter(root, input.options);
+  let filter = createTransformFilter(root, input.context.getOptions());
   let logger;
   const warnedFiles = /* @__PURE__ */ new Set();
   const cache = /* @__PURE__ */ new Map();
@@ -2188,9 +2333,12 @@ function createTransformPlugin(input) {
     name: "spotpatch:transform",
     apply: "serve",
     enforce: "pre",
+    config(config, environment) {
+      input.configure?.(config, environment);
+    },
     configResolved(config) {
       root = import_node_path9.default.resolve(config.root);
-      filter = createTransformFilter(root, input.options);
+      filter = createTransformFilter(root, input.context.getOptions());
       logger = config.logger;
     },
     transform(code, id) {
@@ -2203,6 +2351,7 @@ function createTransformPlugin(input) {
         return cache.get(cacheKey) ?? null;
       }
       const startedAt = performance.now();
+      const options = input.context.getOptions();
       try {
         const result = injectSourceMarkers({
           code,
@@ -2220,7 +2369,7 @@ function createTransformPlugin(input) {
           map: result.map.toString()
         });
         cache.set(cacheKey, output);
-        if (input.options.debug) {
+        if (options.debug) {
           const elapsed = performance.now() - startedAt;
           logger?.info(
             `[spotpatch:transform] ${getDisplayPath(root, id)} ${elapsed.toFixed(2)}ms`
@@ -2230,7 +2379,7 @@ function createTransformPlugin(input) {
       } catch (error) {
         if (!warnedFiles.has(cleanId)) {
           warnedFiles.add(cleanId);
-          const detail = input.options.debug && error instanceof Error ? `: ${error.message}` : "";
+          const detail = options.debug && error instanceof Error ? `: ${error.message}` : "";
           logger?.warn(
             `[spotpatch:transform] Failed to transform ${getDisplayPath(root, id)}; using original module${detail}`
           );
@@ -2243,16 +2392,46 @@ function createTransformPlugin(input) {
 
 // src/plugin.ts
 function spotPatch(userOptions = {}) {
-  const options = resolveOptions(userOptions);
+  let options = resolveOptions(userOptions);
+  let credentialEnvironment = Object.freeze({});
   if (!options.enabled) {
     return [];
   }
   const registry = createSourceRegistry();
   const session = createSession();
+  const context = Object.freeze({
+    getCredentialEnvironment: () => credentialEnvironment,
+    getOptions: () => options
+  });
+  const configure = (config, environment) => {
+    const root = import_node_path10.default.resolve(process.cwd(), config.root ?? ".");
+    const loadedEnvironment = config.envDir === false ? process.env : (0, import_vite2.loadEnv)(environment.mode, import_node_path10.default.resolve(root, config.envDir ?? "."), "");
+    const environmentAi = userOptions.ai === void 0 ? resolveEnvironmentAiConfiguration(loadedEnvironment).ai : false;
+    options = resolveOptions(userOptions, environmentAi);
+    if (options.ai === false) {
+      credentialEnvironment = Object.freeze({});
+      return;
+    }
+    const names = new Set(
+      Object.values(options.ai.providers).map((provider) => provider.apiKeyEnv)
+    );
+    const missing = [...names].filter((name) => {
+      const value = loadedEnvironment[name];
+      return value === void 0 || value.trim().length === 0;
+    });
+    if (missing.length > 0) {
+      throw new RangeError(
+        `SpotPatch AI credential environment is missing ${missing.join(", ")}.`
+      );
+    }
+    credentialEnvironment = Object.freeze(
+      Object.fromEntries([...names].map((name) => [name, loadedEnvironment[name]]))
+    );
+  };
   return [
-    createTransformPlugin({ options, registry }),
-    createRuntimeInjectionPlugin({ options, session }),
-    createServerPlugin({ options, registry, session })
+    createTransformPlugin({ configure, context, registry }),
+    createRuntimeInjectionPlugin({ context, session }),
+    createServerPlugin({ context, registry, session })
   ];
 }