@websublime/vite-plugin-open-api-server 0.24.0-next.3 → 0.24.0-next.5

package/dist/index.js

@@ -1,11 +1,11 @@
-import { existsSync } from 'fs';
 import { createRequire } from 'module';
-import path2, { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-import { createOpenApiServer, executeSeeds, mountInternalApi, mountDevToolsRoutes } from '@websublime/vite-plugin-open-api-core';
+import { mountInternalApi, executeSeeds, createOpenApiServer, mountDevToolsRoutes } from '@websublime/vite-plugin-open-api-core';
 export { defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
 import pc from 'picocolors';
+import path2, { dirname, join } from 'path';
 import fg from 'fast-glob';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
 
@@ -329,6 +329,241 @@ function debounce(fn, delay) {
     }, delay);
   };
 }
+
+// src/multi-proxy.ts
+var DEVTOOLS_PROXY_PATH = "/_devtools";
+var API_PROXY_PATH = "/_api";
+var WS_PROXY_PATH = "/_ws";
+function getProxyConfig(vite) {
+  if (!vite.config.server) {
+    return null;
+  }
+  vite.config.server.proxy ??= {};
+  return vite.config.server.proxy;
+}
+function configureMultiProxy(vite, instances, port) {
+  const proxyConfig = getProxyConfig(vite);
+  if (!proxyConfig) {
+    return;
+  }
+  const httpTarget = `http://localhost:${port}`;
+  for (const instance of instances) {
+    const prefix = instance.config.proxyPath;
+    proxyConfig[prefix] = {
+      target: httpTarget,
+      changeOrigin: true,
+      rewrite: (path4) => {
+        if (path4 !== prefix && !path4.startsWith(`${prefix}/`) && !path4.startsWith(`${prefix}?`))
+          return path4;
+        const rest = path4.slice(prefix.length);
+        if (rest === "" || rest === "/") return "/";
+        if (rest.startsWith("?")) return `/${rest}`;
+        return rest;
+      },
+      headers: { "x-spec-id": instance.id }
+    };
+  }
+  proxyConfig[DEVTOOLS_PROXY_PATH] = {
+    target: httpTarget,
+    changeOrigin: true
+  };
+  proxyConfig[API_PROXY_PATH] = {
+    target: httpTarget,
+    changeOrigin: true
+  };
+  proxyConfig[WS_PROXY_PATH] = {
+    target: `ws://localhost:${port}`,
+    changeOrigin: true,
+    ws: true
+  };
+}
+
+// src/types.ts
+var ValidationError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ValidationError";
+    this.code = code;
+  }
+};
+function validateSpecs(specs) {
+  if (!specs || !Array.isArray(specs) || specs.length === 0) {
+    throw new ValidationError(
+      "SPECS_EMPTY",
+      "specs is required and must be a non-empty array of SpecConfig"
+    );
+  }
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i];
+    if (!spec || typeof spec !== "object") {
+      throw new ValidationError(
+        "SPEC_NOT_FOUND",
+        `specs[${i}]: must be a SpecConfig object, got ${spec === null ? "null" : typeof spec}`
+      );
+    }
+    if (!spec.spec || typeof spec.spec !== "string" || spec.spec.trim() === "") {
+      const identifier = spec.id ? ` (id: "${spec.id}")` : "";
+      throw new ValidationError(
+        "SPEC_NOT_FOUND",
+        `specs[${i}]${identifier}: spec field is required and must be a non-empty string (path or URL to OpenAPI spec)`
+      );
+    }
+  }
+}
+function resolveOptions(options) {
+  validateSpecs(options.specs);
+  return {
+    specs: options.specs.map((s) => ({
+      spec: s.spec,
+      // Placeholder — populated by orchestrator after document processing
+      id: s.id ?? "",
+      // Placeholder — populated by orchestrator after document processing
+      proxyPath: s.proxyPath ?? "",
+      // Preliminary — overwritten by deriveProxyPath() during orchestration
+      proxyPathSource: s.proxyPath?.trim() ? "explicit" : "auto",
+      handlersDir: s.handlersDir ?? "",
+      seedsDir: s.seedsDir ?? "",
+      idFields: s.idFields ?? {}
+    })),
+    port: options.port ?? 4e3,
+    enabled: options.enabled ?? true,
+    timelineLimit: options.timelineLimit ?? 500,
+    devtools: options.devtools ?? true,
+    cors: options.cors ?? true,
+    corsOrigin: options.corsOrigin ?? "*",
+    silent: options.silent ?? false,
+    logger: options.logger
+  };
+}
+
+// src/proxy-path.ts
+var RESERVED_PROXY_PATHS = [
+  DEVTOOLS_PROXY_PATH,
+  API_PROXY_PATH,
+  WS_PROXY_PATH
+];
+function deriveProxyPath(explicitPath, document, specId) {
+  if (explicitPath.trim()) {
+    return {
+      proxyPath: normalizeProxyPath(explicitPath.trim(), specId),
+      proxyPathSource: "explicit"
+    };
+  }
+  const servers = document.servers;
+  const serverUrl = servers?.[0]?.url?.trim();
+  if (!serverUrl) {
+    throw new ValidationError(
+      "PROXY_PATH_MISSING",
+      `[${specId}] Cannot derive proxyPath: no servers defined in the OpenAPI document. Set an explicit proxyPath in the spec configuration.`
+    );
+  }
+  let path4;
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(serverUrl);
+  } catch {
+  }
+  if (parsedUrl) {
+    try {
+      path4 = decodeURIComponent(parsedUrl.pathname);
+    } catch {
+      path4 = parsedUrl.pathname;
+    }
+  } else {
+    path4 = serverUrl;
+  }
+  return {
+    proxyPath: normalizeProxyPath(path4, specId),
+    proxyPathSource: "auto"
+  };
+}
+function normalizeProxyPath(path4, specId) {
+  path4 = path4.trim();
+  const queryIdx = path4.indexOf("?");
+  const hashIdx = path4.indexOf("#");
+  const cutIdx = Math.min(
+    queryIdx >= 0 ? queryIdx : path4.length,
+    hashIdx >= 0 ? hashIdx : path4.length
+  );
+  let normalized = path4.slice(0, cutIdx);
+  normalized = normalized.startsWith("/") ? normalized : `/${normalized}`;
+  normalized = normalized.replace(/\/{2,}/g, "/");
+  const segments = normalized.split("/");
+  const resolved = [];
+  for (const segment of segments) {
+    if (segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (resolved.length > 1) {
+        resolved.pop();
+      }
+      continue;
+    }
+    resolved.push(segment);
+  }
+  normalized = resolved.join("/") || "/";
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  if (normalized === "/") {
+    throw new ValidationError(
+      "PROXY_PATH_TOO_BROAD",
+      `[${specId}] proxyPath "/" is too broad \u2014 it would capture all requests. Set a more specific proxyPath (e.g., "/api/v1").`
+    );
+  }
+  return normalized;
+}
+function validateUniqueProxyPaths(specs) {
+  const paths = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const path4 = spec.proxyPath?.trim();
+    if (!path4) {
+      continue;
+    }
+    validateNotReservedPath(path4, spec.id);
+    if (paths.has(path4)) {
+      throw new ValidationError(
+        "PROXY_PATH_DUPLICATE",
+        `Duplicate proxyPath "${path4}" used by specs "${paths.get(path4)}" and "${spec.id}". Each spec must have a unique proxyPath.`
+      );
+    }
+    paths.set(path4, spec.id);
+  }
+  validateNoPrefixOverlaps(paths);
+}
+function validateNotReservedPath(path4, specId) {
+  for (const reserved of RESERVED_PROXY_PATHS) {
+    if (path4 === reserved || path4.startsWith(`${reserved}/`) || reserved.startsWith(path4)) {
+      throw new ValidationError(
+        "PROXY_PATH_OVERLAP",
+        `[${specId}] proxyPath "${path4}" collides with reserved path "${reserved}" used by the shared DevTools/API/WebSocket service.`
+      );
+    }
+  }
+}
+function validateNoPrefixOverlaps(paths) {
+  const sortedPaths = Array.from(paths.entries()).sort(([a], [b]) => a.length - b.length);
+  for (let i = 0; i < sortedPaths.length; i++) {
+    for (let j = i + 1; j < sortedPaths.length; j++) {
+      const [shorter, shorterId] = sortedPaths[i];
+      const [longer, longerId] = sortedPaths[j];
+      if (longer.startsWith(`${shorter}/`)) {
+        throw new ValidationError(
+          "PROXY_PATH_OVERLAP",
+          `Overlapping proxyPaths: "${shorter}" (${shorterId}) is a prefix of "${longer}" (${longerId}). This would cause routing ambiguity.`
+        );
+      }
+      if (longer.startsWith(shorter)) {
+        throw new ValidationError(
+          "PROXY_PATH_PREFIX_COLLISION",
+          `Proxy path prefix collision: "${shorter}" (${shorterId}) is a string prefix of "${longer}" (${longerId}). Vite's proxy uses startsWith matching, so "${shorter}" would incorrectly capture requests meant for "${longer}".`
+        );
+      }
+    }
+  }
+}
 async function loadSeeds(seedsDir, viteServer, cwd = process.cwd(), logger = console) {
   const seeds = /* @__PURE__ */ new Map();
   const absoluteDir = path2.resolve(cwd, seedsDir);
@@ -410,480 +645,56 @@ async function getSeedFiles(seedsDir, cwd = process.cwd()) {
   return files;
 }
 
-// src/types.ts
-var ValidationError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "ValidationError";
-    this.code = code;
+// src/spec-id.ts
+function slugify(input) {
+  return input.normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+function deriveSpecId(explicitId, document) {
+  if (explicitId.trim()) {
+    const id2 = slugify(explicitId);
+    if (!id2) {
+      throw new ValidationError(
+        "SPEC_ID_MISSING",
+        `Cannot derive spec ID: explicit id "${explicitId}" produces an empty slug. Please provide an id containing ASCII letters or numbers.`
+      );
+    }
+    return id2;
   }
-};
-function validateSpecs(specs) {
-  if (!specs || !Array.isArray(specs) || specs.length === 0) {
+  const title = document.info?.title;
+  if (!title || !title.trim()) {
     throw new ValidationError(
-      "SPECS_EMPTY",
-      "specs is required and must be a non-empty array of SpecConfig"
+      "SPEC_ID_MISSING",
+      "Cannot derive spec ID: info.title is missing from the OpenAPI document. Please set an explicit id in the spec configuration."
     );
   }
-  for (let i = 0; i < specs.length; i++) {
-    const spec = specs[i];
-    if (!spec.spec || typeof spec.spec !== "string" || spec.spec.trim() === "") {
-      const identifier = spec.id ? ` (id: "${spec.id}")` : "";
-      throw new ValidationError(
-        "SPEC_NOT_FOUND",
-        `specs[${i}]${identifier}: spec field is required and must be a non-empty string (path or URL to OpenAPI spec)`
-      );
-    }
-  }
-}
-function resolveOptions(options) {
-  validateSpecs(options.specs);
-  return {
-    specs: options.specs.map((s) => ({
-      spec: s.spec,
-      // Placeholder — populated by orchestrator after document processing
-      id: s.id ?? "",
-      // Placeholder — populated by orchestrator after document processing
-      proxyPath: s.proxyPath ?? "",
-      // Preliminary — overwritten by deriveProxyPath() during orchestration
-      proxyPathSource: s.proxyPath?.trim() ? "explicit" : "auto",
-      handlersDir: s.handlersDir ?? "",
-      seedsDir: s.seedsDir ?? "",
-      idFields: s.idFields ?? {}
-    })),
-    port: options.port ?? 4e3,
-    enabled: options.enabled ?? true,
-    timelineLimit: options.timelineLimit ?? 500,
-    devtools: options.devtools ?? true,
-    cors: options.cors ?? true,
-    corsOrigin: options.corsOrigin ?? "*",
-    silent: options.silent ?? false,
-    logger: options.logger
-  };
-}
-
-// src/plugin.ts
-var VIRTUAL_DEVTOOLS_TAB_ID = "virtual:open-api-devtools-tab";
-var RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID = `\0${VIRTUAL_DEVTOOLS_TAB_ID}`;
-function openApiServer(options) {
-  const resolvedOptions = resolveOptions(options);
-  let server = null;
-  let vite = null;
-  let fileWatcher = null;
-  let cwd = process.cwd();
-  return {
-    name: "vite-plugin-open-api-server",
-    // Only active in dev mode
-    apply: "serve",
-    /**
-     * Ensure @vue/devtools-api is available for the DevTools tab module
-     *
-     * The virtual module imports from '@vue/devtools-api', which Vite needs
-     * to pre-bundle so it can be resolved at runtime in the browser, even
-     * though the host app may not have it as a direct dependency.
-     */
-    config() {
-      if (!resolvedOptions.devtools || !resolvedOptions.enabled) {
-        return;
-      }
-      const require2 = createRequire(import.meta.url);
-      try {
-        require2.resolve("@vue/devtools-api");
-      } catch {
-        return;
-      }
-      return {
-        optimizeDeps: {
-          include: ["@vue/devtools-api"]
-        }
-      };
-    },
-    /**
-     * Resolve the virtual module for DevTools tab registration
-     */
-    resolveId(id) {
-      if (id === VIRTUAL_DEVTOOLS_TAB_ID) {
-        return RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID;
-      }
-    },
-    /**
-     * Load the virtual module that registers the custom Vue DevTools tab
-     *
-     * This code is served as a proper Vite module, allowing bare import
-     * specifiers to be resolved through Vite's dependency pre-bundling.
-     */
-    load(id) {
-      if (id === RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID) {
-        return `
-import { addCustomTab } from '@vue/devtools-api';
-
-try {
-  // Route through Vite's proxy so it works in all environments
-  const iframeSrc = window.location.origin + '/_devtools/';
-
-  addCustomTab({
-    name: 'vite-plugin-open-api-server',
-    title: 'OpenAPI Server',
-    icon: 'https://api.iconify.design/carbon:api-1.svg?width=24&height=24&color=%2394a3b8',
-    view: {
-      type: 'iframe',
-      src: iframeSrc,
-    },
-    category: 'app',
-  });
-} catch (e) {
-  // @vue/devtools-api not available - expected when the package is not installed
-}
-`;
-      }
-    },
-    /**
-     * Configure the Vite dev server
-     *
-     * This hook is called when the dev server is created.
-     * We use it to:
-     * 1. Start the OpenAPI mock server
-     * 2. Configure the Vite proxy to forward API requests
-     * 3. Set up file watching for hot reload
-     */
-    async configureServer(viteServer) {
-      vite = viteServer;
-      cwd = viteServer.config.root;
-      if (!resolvedOptions.enabled) {
-        return;
-      }
-      try {
-        const handlersResult = await loadHandlers(resolvedOptions.handlersDir, viteServer, cwd);
-        const seedsResult = await loadSeeds(resolvedOptions.seedsDir, viteServer, cwd);
-        let devtoolsSpaDir;
-        if (resolvedOptions.devtools) {
-          const pluginDir = dirname(fileURLToPath(import.meta.url));
-          const spaDir = join(pluginDir, "devtools-spa");
-          if (existsSync(spaDir)) {
-            devtoolsSpaDir = spaDir;
-          } else {
-            resolvedOptions.logger?.warn?.(
-              "[vite-plugin-open-api-server] DevTools SPA not found at",
-              spaDir,
-              '- serving placeholder. Run "pnpm build" to include the SPA.'
-            );
-          }
-        }
-        const opts = resolvedOptions;
-        server = await createOpenApiServer({
-          spec: opts.spec,
-          port: opts.port,
-          idFields: opts.idFields,
-          handlers: handlersResult.handlers,
-          // Seeds are populated via executeSeeds, not directly
-          seeds: /* @__PURE__ */ new Map(),
-          timelineLimit: opts.timelineLimit,
-          devtools: opts.devtools,
-          devtoolsSpaDir,
-          cors: opts.cors,
-          corsOrigin: opts.corsOrigin,
-          logger: opts.logger
-        });
-        if (seedsResult.seeds.size > 0) {
-          await executeSeeds(seedsResult.seeds, server.store, server.document);
-        }
-        await server.start();
-        configureProxy(viteServer, resolvedOptions.proxyPath, resolvedOptions.port);
-        const bannerInfo = extractBannerInfo(
-          server.registry,
-          {
-            info: {
-              title: server.document.info?.title ?? "OpenAPI Server",
-              version: server.document.info?.version ?? "1.0.0"
-            }
-          },
-          handlersResult.handlers.size,
-          seedsResult.seeds.size,
-          resolvedOptions
-        );
-        printBanner(bannerInfo, resolvedOptions);
-        await setupFileWatching();
-      } catch (error) {
-        printError("Failed to start OpenAPI mock server", error, resolvedOptions);
-        throw error;
-      }
-    },
-    /**
-     * Clean up when Vite server closes
-     */
-    async closeBundle() {
-      await cleanup();
-    },
-    /**
-     * Inject Vue DevTools custom tab registration script
-     *
-     * When devtools is enabled, this injects a script tag that loads the
-     * virtual module for custom tab registration. Using a virtual module
-     * (instead of an inline script) ensures that bare import specifiers
-     * like `@vue/devtools-api` are resolved through Vite's module pipeline.
-     */
-    transformIndexHtml() {
-      if (!resolvedOptions.devtools || !resolvedOptions.enabled) {
-        return;
-      }
-      return [
-        {
-          tag: "script",
-          attrs: { type: "module", src: `/@id/${VIRTUAL_DEVTOOLS_TAB_ID}` },
-          injectTo: "head"
-        }
-      ];
-    }
-  };
-  function configureProxy(vite2, proxyPath, port) {
-    const serverConfig = vite2.config.server ?? {};
-    const proxyConfig = serverConfig.proxy ?? {};
-    const escapedPath = proxyPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const pathPrefixRegex = new RegExp(`^${escapedPath}`);
-    proxyConfig[proxyPath] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true,
-      // Remove the proxy path prefix when forwarding
-      rewrite: (path4) => path4.replace(pathPrefixRegex, "")
-    };
-    proxyConfig["/_devtools"] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true
-    };
-    proxyConfig["/_api"] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true
-    };
-    proxyConfig["/_ws"] = {
-      target: `http://localhost:${port}`,
-      changeOrigin: true,
-      ws: true
-    };
-    if (vite2.config.server) {
-      vite2.config.server.proxy = proxyConfig;
-    }
-  }
-  async function setupFileWatching() {
-    if (!server || !vite) return;
-    const debouncedHandlerReload = debounce(reloadHandlers, 100);
-    const debouncedSeedReload = debounce(reloadSeeds, 100);
-    const watchOpts = resolvedOptions;
-    fileWatcher = await createFileWatcher({
-      handlersDir: watchOpts.handlersDir,
-      seedsDir: watchOpts.seedsDir,
-      cwd,
-      onHandlerChange: debouncedHandlerReload,
-      onSeedChange: debouncedSeedReload
-    });
-  }
-  async function reloadHandlers() {
-    if (!server || !vite) return;
-    try {
-      const handlersResult = await loadHandlers(
-        // biome-ignore lint/suspicious/noExplicitAny: v0.x compat — plugin.ts rewritten in Task 1.7
-        resolvedOptions.handlersDir,
-        vite,
-        cwd
-      );
-      server.updateHandlers(handlersResult.handlers);
-      server.wsHub.broadcast({
-        type: "handlers:updated",
-        data: { count: handlersResult.handlers.size }
-      });
-      printReloadNotification("handlers", handlersResult.handlers.size, resolvedOptions);
-    } catch (error) {
-      printError("Failed to reload handlers", error, resolvedOptions);
-    }
-  }
-  async function reloadSeeds() {
-    if (!server || !vite) return;
-    try {
-      const seedsResult = await loadSeeds(
-        // biome-ignore lint/suspicious/noExplicitAny: v0.x compat — plugin.ts rewritten in Task 1.7
-        resolvedOptions.seedsDir,
-        vite,
-        cwd
-      );
-      if (seedsResult.seeds.size > 0) {
-        server.store.clearAll();
-        await executeSeeds(seedsResult.seeds, server.store, server.document);
-      } else {
-        server.store.clearAll();
-      }
-      server.wsHub.broadcast({
-        type: "seeds:updated",
-        data: { count: seedsResult.seeds.size }
-      });
-      printReloadNotification("seeds", seedsResult.seeds.size, resolvedOptions);
-    } catch (error) {
-      printError("Failed to reload seeds", error, resolvedOptions);
-    }
-  }
-  async function cleanup() {
-    if (fileWatcher) {
-      await fileWatcher.close();
-      fileWatcher = null;
-    }
-    if (server) {
-      await server.stop();
-      server = null;
-    }
-    vite = null;
-  }
-}
-
-// src/spec-id.ts
-function slugify(input) {
-  return input.normalize("NFD").replace(new RegExp("\\p{M}", "gu"), "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
-}
-function deriveSpecId(explicitId, document) {
-  if (explicitId.trim()) {
-    const id2 = slugify(explicitId);
-    if (!id2) {
-      throw new ValidationError(
-        "SPEC_ID_MISSING",
-        `Cannot derive spec ID: explicit id "${explicitId}" produces an empty slug. Please provide an id containing ASCII letters or numbers.`
-      );
-    }
-    return id2;
-  }
-  const title = document.info?.title;
-  if (!title || !title.trim()) {
-    throw new ValidationError(
-      "SPEC_ID_MISSING",
-      "Cannot derive spec ID: info.title is missing from the OpenAPI document. Please set an explicit id in the spec configuration."
-    );
-  }
-  const id = slugify(title);
-  if (!id) {
-    throw new ValidationError(
-      "SPEC_ID_MISSING",
-      `Cannot derive spec ID: info.title "${title}" produces an empty slug. Please set an explicit id in the spec configuration.`
-    );
-  }
-  return id;
-}
-function validateUniqueIds(ids) {
-  const seen = /* @__PURE__ */ new Set();
-  const duplicates = /* @__PURE__ */ new Set();
-  for (const id of ids) {
-    if (seen.has(id)) {
-      duplicates.add(id);
-    }
-    seen.add(id);
-  }
-  if (duplicates.size > 0) {
-    const list = [...duplicates].join(", ");
-    throw new ValidationError(
-      "SPEC_ID_DUPLICATE",
-      `Duplicate spec IDs: ${list}. Each spec must have a unique ID. Set explicit ids in spec configuration to resolve.`
-    );
-  }
-}
-
-// src/proxy-path.ts
-function deriveProxyPath(explicitPath, document, specId) {
-  if (explicitPath.trim()) {
-    return {
-      proxyPath: normalizeProxyPath(explicitPath.trim(), specId),
-      proxyPathSource: "explicit"
-    };
-  }
-  const servers = document.servers;
-  const serverUrl = servers?.[0]?.url?.trim();
-  if (!serverUrl) {
-    throw new ValidationError(
-      "PROXY_PATH_MISSING",
-      `[${specId}] Cannot derive proxyPath: no servers defined in the OpenAPI document. Set an explicit proxyPath in the spec configuration.`
-    );
-  }
-  let path4;
-  let parsedUrl;
-  try {
-    parsedUrl = new URL(serverUrl);
-  } catch {
-  }
-  if (parsedUrl) {
-    try {
-      path4 = decodeURIComponent(parsedUrl.pathname);
-    } catch {
-      path4 = parsedUrl.pathname;
-    }
-  } else {
-    path4 = serverUrl;
-  }
-  return {
-    proxyPath: normalizeProxyPath(path4, specId),
-    proxyPathSource: "auto"
-  };
-}
-function normalizeProxyPath(path4, specId) {
-  path4 = path4.trim();
-  const queryIdx = path4.indexOf("?");
-  const hashIdx = path4.indexOf("#");
-  const cutIdx = Math.min(
-    queryIdx >= 0 ? queryIdx : path4.length,
-    hashIdx >= 0 ? hashIdx : path4.length
-  );
-  let normalized = path4.slice(0, cutIdx);
-  normalized = normalized.startsWith("/") ? normalized : `/${normalized}`;
-  normalized = normalized.replace(/\/{2,}/g, "/");
-  const segments = normalized.split("/");
-  const resolved = [];
-  for (const segment of segments) {
-    if (segment === ".") {
-      continue;
-    }
-    if (segment === "..") {
-      if (resolved.length > 1) {
-        resolved.pop();
-      }
-      continue;
-    }
-    resolved.push(segment);
-  }
-  normalized = resolved.join("/") || "/";
-  if (normalized.length > 1 && normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
-  }
-  if (normalized === "/") {
-    throw new ValidationError(
-      "PROXY_PATH_TOO_BROAD",
-      `[${specId}] proxyPath "/" is too broad \u2014 it would capture all requests. Set a more specific proxyPath (e.g., "/api/v1").`
-    );
-  }
-  return normalized;
-}
-function validateUniqueProxyPaths(specs) {
-  const paths = /* @__PURE__ */ new Map();
-  for (const spec of specs) {
-    const path4 = spec.proxyPath?.trim();
-    if (!path4) {
-      continue;
-    }
-    if (paths.has(path4)) {
-      throw new ValidationError(
-        "PROXY_PATH_DUPLICATE",
-        `Duplicate proxyPath "${path4}" used by specs "${paths.get(path4)}" and "${spec.id}". Each spec must have a unique proxyPath.`
-      );
-    }
-    paths.set(path4, spec.id);
-  }
-  const sortedPaths = Array.from(paths.entries()).sort(([a], [b]) => a.length - b.length);
-  for (let i = 0; i < sortedPaths.length; i++) {
-    for (let j = i + 1; j < sortedPaths.length; j++) {
-      const [shorter, shorterId] = sortedPaths[i];
-      const [longer, longerId] = sortedPaths[j];
-      if (longer.startsWith(`${shorter}/`)) {
-        throw new ValidationError(
-          "PROXY_PATH_OVERLAP",
-          `Overlapping proxyPaths: "${shorter}" (${shorterId}) is a prefix of "${longer}" (${longerId}). This would cause routing ambiguity.`
-        );
-      }
+  const id = slugify(title);
+  if (!id) {
+    throw new ValidationError(
+      "SPEC_ID_MISSING",
+      `Cannot derive spec ID: info.title "${title}" produces an empty slug. Please set an explicit id in the spec configuration.`
+    );
+  }
+  return id;
+}
+function validateUniqueIds(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (seen.has(id)) {
+      duplicates.add(id);
     }
+    seen.add(id);
+  }
+  if (duplicates.size > 0) {
+    const list = [...duplicates].join(", ");
+    throw new ValidationError(
+      "SPEC_ID_DUPLICATE",
+      `Duplicate spec IDs: ${list}. Each spec must have a unique ID. Set explicit ids in spec configuration to resolve.`
+    );
   }
 }
+
+// src/orchestrator.ts
 var SPEC_COLORS = [
   "#4ade80",
   // green
@@ -942,7 +753,7 @@ async function processSpec(specConfig, index, options, vite, cwd, logger) {
 }
 function buildCorsConfig(options) {
   const isWildcardOrigin = options.corsOrigin === "*" || Array.isArray(options.corsOrigin) && options.corsOrigin.includes("*");
-  const effectiveCorsOrigin = Array.isArray(options.corsOrigin) && options.corsOrigin.includes("*") ? "*" : options.corsOrigin;
+  const effectiveCorsOrigin = isWildcardOrigin ? "*" : options.corsOrigin;
   return {
     origin: effectiveCorsOrigin,
     allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
@@ -999,12 +810,11 @@ async function createOrchestrator(options, vite, cwd) {
       cwd,
       logger
     );
-    const specConfig = options.specs[i];
-    specConfig.id = resolvedConfig.id;
-    specConfig.proxyPath = resolvedConfig.proxyPath;
-    specConfig.proxyPathSource = resolvedConfig.proxyPathSource;
-    specConfig.handlersDir = resolvedConfig.handlersDir;
-    specConfig.seedsDir = resolvedConfig.seedsDir;
+    instance.config.id = resolvedConfig.id;
+    instance.config.proxyPath = resolvedConfig.proxyPath;
+    instance.config.proxyPathSource = resolvedConfig.proxyPathSource;
+    instance.config.handlersDir = resolvedConfig.handlersDir;
+    instance.config.seedsDir = resolvedConfig.seedsDir;
     instances.push(instance);
   }
   validateUniqueIds(instances.map((inst) => inst.id));
@@ -1025,12 +835,16 @@ async function createOrchestrator(options, vite, cwd) {
   if (options.devtools) {
     mountDevToolsSpa(mainApp, logger);
   }
+  if (instances.length > 1) {
+    logger.warn?.(
+      "[vite-plugin-open-api-server] Only first spec's internal API mounted on /_api; multi-spec support planned in Epic 3 (Task 3.x)."
+    );
+    mainApp.use("/_api/*", async (c, next) => {
+      await next();
+      c.header("X-Multi-Spec-Warning", `Only showing data for spec "${instances[0].id}"`);
+    });
+  }
   if (instances.length > 0) {
-    if (instances.length > 1) {
-      logger.warn?.(
-        "[vite-plugin-open-api-server] Only first spec's internal API mounted on /_api; multi-spec support planned in Epic 3 (Task 3.x)."
-      );
-    }
     const firstInstance = instances[0];
     mountInternalApi(mainApp, {
       store: firstInstance.server.store,
@@ -1048,6 +862,37 @@ async function createOrchestrator(options, vite, cwd) {
   const specsInfo = instances.map((inst) => inst.info);
   let serverInstance = null;
   let boundPort = 0;
+  async function startServerOnPort(fetchHandler, port) {
+    let createAdaptorServer;
+    try {
+      const nodeServer = await import('@hono/node-server');
+      createAdaptorServer = nodeServer.createAdaptorServer;
+    } catch {
+      throw new Error("@hono/node-server is required. Install with: npm install @hono/node-server");
+    }
+    const server = createAdaptorServer({ fetch: fetchHandler });
+    const actualPort = await new Promise((resolve, reject) => {
+      const onListening = () => {
+        server.removeListener("error", onError);
+        const addr = server.address();
+        resolve(typeof addr === "object" && addr ? addr.port : port);
+      };
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        server.close(() => {
+        });
+        if (err.code === "EADDRINUSE") {
+          reject(new Error(`[vite-plugin-open-api-server] Port ${port} is already in use.`));
+        } else {
+          reject(new Error(`[vite-plugin-open-api-server] Server error: ${err.message}`));
+        }
+      };
+      server.once("listening", onListening);
+      server.once("error", onError);
+      server.listen(port);
+    });
+    return { server, actualPort };
+  }
   return {
     app: mainApp,
     instances,
@@ -1059,51 +904,18 @@ async function createOrchestrator(options, vite, cwd) {
       if (serverInstance) {
         throw new Error("[vite-plugin-open-api-server] Server already running. Call stop() first.");
       }
-      let createAdaptorServer;
-      try {
-        const nodeServer = await import('@hono/node-server');
-        createAdaptorServer = nodeServer.createAdaptorServer;
-      } catch {
-        throw new Error(
-          "@hono/node-server is required. Install with: npm install @hono/node-server"
-        );
-      }
-      const server = createAdaptorServer({ fetch: mainApp.fetch });
-      await new Promise((resolve, reject) => {
-        const onListening = () => {
-          server.removeListener("error", onError);
-          const addr = server.address();
-          const actualPort = typeof addr === "object" && addr ? addr.port : options.port;
-          logger.info(
-            `[vite-plugin-open-api-server] Server started on http://localhost:${actualPort}`
-          );
-          boundPort = actualPort;
-          serverInstance = server;
-          resolve();
-        };
-        const onError = (err) => {
-          server.removeListener("listening", onListening);
-          server.close(() => {
-          });
-          serverInstance = null;
-          boundPort = 0;
-          if (err.code === "EADDRINUSE") {
-            reject(
-              new Error(`[vite-plugin-open-api-server] Port ${options.port} is already in use.`)
-            );
-          } else {
-            reject(new Error(`[vite-plugin-open-api-server] Server error: ${err.message}`));
-          }
-        };
-        server.once("listening", onListening);
-        server.once("error", onError);
-        server.listen(options.port);
-      });
+      const { server, actualPort } = await startServerOnPort(mainApp.fetch, options.port);
+      serverInstance = server;
+      boundPort = actualPort;
+      logger.info(`[vite-plugin-open-api-server] Server started on http://localhost:${actualPort}`);
     },
     async stop() {
       const server = serverInstance;
       if (server) {
         try {
+          if (typeof server.closeAllConnections === "function") {
+            server.closeAllConnections();
+          }
           await new Promise((resolve, reject) => {
             server.close((err) => {
               if (err) {
@@ -1126,6 +938,229 @@ async function createOrchestrator(options, vite, cwd) {
   };
 }
 
+// src/plugin.ts
+var VIRTUAL_DEVTOOLS_TAB_ID = "virtual:open-api-devtools-tab";
+var RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID = `\0${VIRTUAL_DEVTOOLS_TAB_ID}`;
+function openApiServer(options) {
+  const resolvedOptions = resolveOptions(options);
+  let orchestrator = null;
+  let fileWatchers = [];
+  let cwd = process.cwd();
+  return {
+    name: "vite-plugin-open-api-server",
+    apply: "serve",
+    /**
+     * Ensure @vue/devtools-api is available for the DevTools tab module
+     *
+     * The virtual module imports from '@vue/devtools-api', which Vite needs
+     * to pre-bundle so it can be resolved at runtime in the browser, even
+     * though the host app may not have it as a direct dependency.
+     */
+    config() {
+      if (!resolvedOptions.devtools || !resolvedOptions.enabled) {
+        return;
+      }
+      const require2 = createRequire(import.meta.url);
+      try {
+        require2.resolve("@vue/devtools-api");
+      } catch {
+        return;
+      }
+      return {
+        optimizeDeps: {
+          include: ["@vue/devtools-api"]
+        }
+      };
+    },
+    /**
+     * Resolve the virtual module for DevTools tab registration
+     */
+    resolveId(id) {
+      if (id === VIRTUAL_DEVTOOLS_TAB_ID) {
+        return RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID;
+      }
+    },
+    /**
+     * Load the virtual module that registers the custom Vue DevTools tab
+     *
+     * This code is served as a proper Vite module, allowing bare import
+     * specifiers to be resolved through Vite's dependency pre-bundling.
+     */
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_DEVTOOLS_TAB_ID) {
+        return `
+import { addCustomTab } from '@vue/devtools-api';
+
+try {
+  // Route through Vite's proxy so it works in all environments
+  const iframeSrc = window.location.origin + '${DEVTOOLS_PROXY_PATH}/';
+
+  addCustomTab({
+    name: 'vite-plugin-open-api-server',
+    title: 'OpenAPI Server',
+    icon: 'https://api.iconify.design/carbon:api-1.svg?width=24&height=24&color=%2394a3b8',
+    view: {
+      type: 'iframe',
+      src: iframeSrc,
+    },
+    category: 'app',
+  });
+} catch (e) {
+  // @vue/devtools-api not available - expected when the package is not installed
+}
+`;
+      }
+    },
+    /**
+     * Configure the Vite dev server
+     *
+     * This hook is called when the dev server is created.
+     * We use it to:
+     * 1. Create and start the multi-spec orchestrator
+     * 2. Configure Vite's multi-proxy for all specs
+     * 3. Set up per-spec file watchers for hot reload
+     * 4. Print startup banner
+     */
+    async configureServer(viteServer) {
+      cwd = viteServer.config.root;
+      if (!resolvedOptions.enabled) {
+        return;
+      }
+      try {
+        orchestrator = await createOrchestrator(resolvedOptions, viteServer, cwd);
+        await orchestrator.start();
+        configureMultiProxy(viteServer, orchestrator.instances, orchestrator.port);
+        fileWatchers = await setupPerSpecFileWatching(orchestrator, viteServer, cwd);
+        if (!resolvedOptions.silent && orchestrator.instances.length > 0) {
+          const firstInstance = orchestrator.instances[0];
+          const bannerInfo = extractBannerInfo(
+            firstInstance.server.registry,
+            {
+              info: {
+                title: firstInstance.server.document.info?.title ?? "OpenAPI Server",
+                version: firstInstance.server.document.info?.version ?? "1.0.0"
+              }
+            },
+            // Handler/seed counts are not tracked per-instance yet.
+            // Multi-spec banner (Epic 5, Task 5.1) will display proper per-spec counts.
+            0,
+            0,
+            resolvedOptions
+          );
+          printBanner(bannerInfo, resolvedOptions);
+        }
+      } catch (error) {
+        await teardown();
+        printError("Failed to start OpenAPI mock server", error, resolvedOptions);
+        throw error;
+      }
+    },
+    /**
+     * Inject Vue DevTools custom tab registration script
+     *
+     * When devtools is enabled, this injects a script tag that loads the
+     * virtual module for custom tab registration. Using a virtual module
+     * (instead of an inline script) ensures that bare import specifiers
+     * like `@vue/devtools-api` are resolved through Vite's module pipeline.
+     */
+    transformIndexHtml() {
+      if (!resolvedOptions.devtools || !resolvedOptions.enabled) {
+        return;
+      }
+      return [
+        {
+          tag: "script",
+          attrs: { type: "module", src: `/@id/${VIRTUAL_DEVTOOLS_TAB_ID}` },
+          injectTo: "head"
+        }
+      ];
+    },
+    /**
+     * Clean up when Vite server closes
+     *
+     * NOTE: closeBundle() is called by Vite when the dev server shuts down
+     * (e.g., Ctrl+C). This is the same lifecycle hook used in v0.x.
+     * While configureServer's viteServer.httpServer?.on('close', ...) is
+     * an alternative, closeBundle() is more reliable across Vite versions
+     * and is the established pattern in this codebase.
+     */
+    async closeBundle() {
+      await teardown();
+    }
+  };
+  async function teardown() {
+    await Promise.allSettled(fileWatchers.map((w) => w.close()));
+    fileWatchers = [];
+    if (orchestrator) {
+      try {
+        await orchestrator.stop();
+      } catch {
+      }
+      orchestrator = null;
+    }
+  }
+  async function setupPerSpecFileWatching(orch, viteServer, projectCwd) {
+    const watchers = [];
+    try {
+      for (const instance of orch.instances) {
+        const specServer = instance.server;
+        const specConfig = instance.config;
+        const debouncedHandlerReload = debounce(
+          () => reloadSpecHandlers(specServer, specConfig.handlersDir, viteServer, projectCwd),
+          100
+        );
+        const debouncedSeedReload = debounce(
+          () => reloadSpecSeeds(specServer, specConfig.seedsDir, viteServer, projectCwd),
+          100
+        );
+        const watcher = await createFileWatcher({
+          handlersDir: specConfig.handlersDir,
+          seedsDir: specConfig.seedsDir,
+          cwd: projectCwd,
+          onHandlerChange: debouncedHandlerReload,
+          onSeedChange: debouncedSeedReload
+        });
+        watchers.push(watcher);
+      }
+    } catch (error) {
+      await Promise.allSettled(watchers.map((w) => w.close()));
+      throw error;
+    }
+    return watchers;
+  }
+  async function reloadSpecHandlers(server, handlersDir, viteServer, projectCwd) {
+    try {
+      const logger = resolvedOptions.logger ?? console;
+      const handlersResult = await loadHandlers(handlersDir, viteServer, projectCwd, logger);
+      server.updateHandlers(handlersResult.handlers);
+      server.wsHub.broadcast({
+        type: "handlers:updated",
+        data: { count: handlersResult.handlers.size }
+      });
+      printReloadNotification("handlers", handlersResult.handlers.size, resolvedOptions);
+    } catch (error) {
+      printError("Failed to reload handlers", error, resolvedOptions);
+    }
+  }
+  async function reloadSpecSeeds(server, seedsDir, viteServer, projectCwd) {
+    try {
+      const logger = resolvedOptions.logger ?? console;
+      const seedsResult = await loadSeeds(seedsDir, viteServer, projectCwd, logger);
+      server.store.clearAll();
+      if (seedsResult.seeds.size > 0) {
+        await executeSeeds(seedsResult.seeds, server.store, server.document);
+      }
+      server.wsHub.broadcast({
+        type: "seeds:updated",
+        data: { count: seedsResult.seeds.size }
+      });
+      printReloadNotification("seeds", seedsResult.seeds.size, resolvedOptions);
+    } catch (error) {
+      printError("Failed to reload seeds", error, resolvedOptions);
+    }
+  }
+}
+
 // src/devtools.ts
 async function registerDevTools(app, options = {}) {
   const { enabled = true, label = "OpenAPI Server", port, host, protocol } = options;
@@ -1156,12 +1191,12 @@ async function registerDevTools(app, options = {}) {
     console.warn("[OpenAPI DevTools] Failed to register with Vue DevTools:", error);
   }
 }
-function getDevToolsUrl(port = 3e3, host, protocol) {
+function getDevToolsUrl(port = 4e3, host, protocol) {
   const actualProtocol = protocol || (typeof window !== "undefined" ? window.location.protocol.replace(":", "") : "http");
   const actualHost = host || (typeof window !== "undefined" ? window.location.hostname : "localhost");
   return `${actualProtocol}://${actualHost}:${port}/_devtools/`;
 }
 
-export { SPEC_COLORS, ValidationError, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };
+export { API_PROXY_PATH, DEVTOOLS_PROXY_PATH, SPEC_COLORS, ValidationError, WS_PROXY_PATH, configureMultiProxy, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map