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

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { Plugin, ViteDevServer } from 'vite';
-import { Logger, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
+import { Logger, SpecInfo, OpenApiServer, HandlerFn, AnySeedFn } from '@websublime/vite-plugin-open-api-core';
 export { HandlerContext, HandlerDefinition, HandlerFn, HandlerReturn, SecurityContext, SeedContext, SeedDefinition, SeedFn, SeedHelper, defineHandlers, defineSeeds } from '@websublime/vite-plugin-open-api-core';
+import { OpenAPIV3_1 } from '@scalar/openapi-types';
+import { Hono } from 'hono';
 import { App } from 'vue';
 
 /**
@@ -42,6 +44,16 @@ declare class ValidationError extends Error {
     readonly code: ValidationErrorCode;
     constructor(code: ValidationErrorCode, message: string);
 }
+/**
+ * How a proxy path was determined.
+ *
+ * - `'explicit'` — set directly in SpecConfig.proxyPath
+ * - `'auto'` — auto-derived from the OpenAPI document's servers[0].url
+ *
+ * Used by both DeriveProxyPathResult and ResolvedSpecConfig to ensure
+ * the two sources of this value stay in sync.
+ */
+type ProxyPathSource = 'auto' | 'explicit';
 /**
  * Configuration for a single OpenAPI spec instance
  *
@@ -175,18 +187,18 @@ interface OpenApiServerOptions {
  */
 interface ResolvedSpecConfig {
     spec: string;
-    /** Guaranteed to be set after orchestrator resolution */
+    /** Empty string until orchestrator resolution; guaranteed non-empty after `createOrchestrator()` */
     id: string;
-    /** Guaranteed to be set after orchestrator resolution */
+    /** Empty string until orchestrator resolution; guaranteed non-empty after `createOrchestrator()` */
     proxyPath: string;
     /**
      * How proxyPath was determined — used for banner display.
      *
-     * Set during static option resolution. The orchestrator (Task 1.7)
-     * will pass this to the multi-spec banner so it can show
-     * "(auto-derived)" vs "(explicit)" next to each proxy path.
+     * Written back by the orchestrator after document processing.
+     * Used by the startup banner to display `(auto-derived)` vs
+     * `(explicit)` next to each proxy path.
      */
-    proxyPathSource: 'auto' | 'explicit';
+    proxyPathSource: ProxyPathSource;
     handlersDir: string;
     seedsDir: string;
     idFields: Record<string, string>;
@@ -208,6 +220,25 @@ interface ResolvedOptions {
     silent: boolean;
     logger?: Logger;
 }
+/**
+ * Validate that specs array is non-empty and each entry has a valid spec field.
+ *
+ * @param specs - Array of spec configurations to validate
+ * @throws {ValidationError} SPECS_EMPTY if specs array is missing or empty
+ * @throws {ValidationError} SPEC_NOT_FOUND if a spec entry has empty spec field
+ */
+declare function validateSpecs(specs: SpecConfig[]): void;
+/**
+ * Resolve options with defaults.
+ *
+ * Note: spec ID and proxyPath resolution requires processing the OpenAPI document
+ * first, so they are resolved later in the orchestrator.
+ * This function only resolves static defaults.
+ *
+ * @param options - User-provided options
+ * @returns Resolved options with all defaults applied
+ */
+declare function resolveOptions(options: OpenApiServerOptions): ResolvedOptions;
 
 /**
  * Vite Plugin Implementation
@@ -221,6 +252,244 @@ interface ResolvedOptions {
 
 declare function openApiServer(options: OpenApiServerOptions): Plugin;
 
+/**
+ * Spec ID Derivation
+ *
+ * What: Functions to derive and validate spec identifiers
+ * How: Slugifies explicit IDs or auto-derives from OpenAPI info.title
+ * Why: Each spec instance needs a unique, URL-safe identifier for routing,
+ *      DevTools grouping, logging, and default directory names
+ *
+ * @module spec-id
+ */
+
+/**
+ * Slugify a string for use as a spec identifier
+ *
+ * Rules:
+ * - Lowercase
+ * - Replace spaces and special chars with hyphens
+ * - Remove consecutive hyphens
+ * - Trim leading/trailing hyphens
+ *
+ * @example
+ * slugify("Swagger Petstore") → "swagger-petstore"
+ * slugify("Billing API v2")   → "billing-api-v2"
+ * slugify("café")             → "cafe"
+ */
+declare function slugify(input: string): string;
+/**
+ * Derive a spec ID from the processed OpenAPI document
+ *
+ * Priority:
+ * 1. Explicit id from config (if non-empty)
+ * 2. Slugified info.title from the processed document
+ *
+ * @param explicitId - ID from SpecConfig.id (may be empty)
+ * @param document - Processed OpenAPI document
+ * @returns Stable, URL-safe spec identifier
+ * @throws {ValidationError} SPEC_ID_MISSING if no ID can be derived (missing title and no explicit id)
+ */
+declare function deriveSpecId(explicitId: string, document: OpenAPIV3_1.Document): string;
+/**
+ * Validate spec IDs are unique across all specs
+ *
+ * Collects all duplicated IDs and reports them in a single error.
+ *
+ * @param ids - Array of resolved spec IDs
+ * @throws {ValidationError} SPEC_ID_DUPLICATE if duplicate IDs found
+ */
+declare function validateUniqueIds(ids: string[]): void;
+
+/**
+ * Proxy Path Auto-Detection
+ *
+ * What: Functions to derive and validate proxy paths for spec instances
+ * How: Extracts path from explicit config or auto-derives from servers[0].url
+ * Why: Each spec instance needs a unique, non-overlapping proxy path for
+ *      Vite proxy configuration and request routing
+ *
+ * @module proxy-path
+ */
+
+/**
+ * Result of proxy path derivation
+ *
+ * Includes the normalized path and how it was determined,
+ * so the startup banner can display "(auto-derived)" vs "(explicit)".
+ */
+interface DeriveProxyPathResult {
+    /** Normalized proxy path (e.g., "/api/v3") */
+    proxyPath: string;
+    /** How the path was determined */
+    proxyPathSource: ProxyPathSource;
+}
+/**
+ * Derive the proxy path from config or OpenAPI document's servers field
+ *
+ * Priority:
+ * 1. Explicit proxyPath from config (if non-empty after trimming)
+ * 2. Path portion of servers[0].url
+ *
+ * Full URLs (e.g., "https://api.example.com/api/v3") have their path
+ * extracted via the URL constructor. Relative paths (e.g., "/api/v3")
+ * are used directly.
+ *
+ * @param explicitPath - proxyPath from SpecConfig (may be empty)
+ * @param document - Processed OpenAPI document
+ * @param specId - Spec ID for error messages
+ * @returns Normalized proxy path with source indication
+ * @throws {ValidationError} PROXY_PATH_MISSING if path cannot be derived
+ * @throws {ValidationError} PROXY_PATH_TOO_BROAD if path resolves to "/" (e.g., "/", ".", "..")
+ *
+ * @example
+ * // Explicit path
+ * deriveProxyPath('/api/v3', document, 'petstore')
+ * // → { proxyPath: '/api/v3', proxyPathSource: 'explicit' }
+ *
+ * @example
+ * // Auto-derived from servers[0].url = "https://api.example.com/api/v3"
+ * deriveProxyPath('', document, 'petstore')
+ * // → { proxyPath: '/api/v3', proxyPathSource: 'auto' }
+ */
+declare function deriveProxyPath(explicitPath: string, document: OpenAPIV3_1.Document, specId: string): DeriveProxyPathResult;
+/**
+ * Normalize and validate a proxy path
+ *
+ * Rules:
+ * - Strip query strings and fragments
+ * - Ensure leading slash
+ * - Collapse consecutive slashes
+ * - Resolve dot segments ("." and ".." per RFC 3986 §5.2.4)
+ * - Remove trailing slash
+ * - Reject "/" as too broad (would capture all requests, including dot-segments that resolve to "/")
+ *
+ * @param path - Raw path string to normalize
+ * @param specId - Spec ID for error messages
+ * @returns Normalized path (e.g., "/api/v3")
+ * @throws {ValidationError} PROXY_PATH_TOO_BROAD if path resolves to "/" (e.g., "/", ".", "..")
+ *
+ * @example
+ * normalizeProxyPath('api/v3', 'petstore')   → '/api/v3'
+ * normalizeProxyPath('/api/v3/', 'petstore') → '/api/v3'
+ */
+declare function normalizeProxyPath(path: string, specId: string): string;
+/**
+ * Validate proxy paths are unique and non-overlapping
+ *
+ * Checks for:
+ * 1. Duplicate paths — two specs with the same proxyPath
+ * 2. Overlapping paths — one path is a prefix of another (e.g., "/api" and "/api/v1")
+ *    which would cause routing ambiguity
+ *
+ * @remarks
+ * Entries with an empty or falsy `proxyPath` are silently skipped. These
+ * represent specs whose proxy path has not yet been resolved (e.g., during
+ * early option resolution before the OpenAPI document is processed). Callers
+ * should expect unresolved entries to be excluded from uniqueness checks
+ * rather than triggering false-positive PROXY_PATH_DUPLICATE or
+ * PROXY_PATH_OVERLAP errors.
+ *
+ * @param specs - Array of spec entries with id and proxyPath.
+ *   Entries with empty/falsy proxyPath are skipped (unresolved).
+ * @throws {ValidationError} PROXY_PATH_DUPLICATE if duplicate paths found
+ * @throws {ValidationError} PROXY_PATH_OVERLAP if overlapping paths found
+ *
+ * @example
+ * // Throws PROXY_PATH_DUPLICATE
+ * validateUniqueProxyPaths([
+ *   { id: 'petstore', proxyPath: '/api/v3' },
+ *   { id: 'inventory', proxyPath: '/api/v3' },
+ * ]);
+ *
+ * @example
+ * // Throws PROXY_PATH_OVERLAP
+ * validateUniqueProxyPaths([
+ *   { id: 'petstore', proxyPath: '/api' },
+ *   { id: 'inventory', proxyPath: '/api/v1' },
+ * ]);
+ */
+declare function validateUniqueProxyPaths(specs: Array<{
+    id: string;
+    proxyPath: string;
+}>): void;
+
+/**
+ * Multi-Spec Orchestrator
+ *
+ * What: Central orchestrator that creates N spec instances and mounts them on a single Hono app
+ * How: Three phases — process specs, validate uniqueness, build main Hono app with dispatch middleware
+ * Why: Enables multiple OpenAPI specs to run on a single server with isolated stores and handlers
+ *
+ * @module orchestrator
+ */
+
+/**
+ * Deterministic color palette for spec identification in DevTools.
+ *
+ * Colors are assigned by index: spec 0 gets green, spec 1 gets blue, etc.
+ * Wraps around for >8 specs.
+ */
+declare const SPEC_COLORS: readonly string[];
+/**
+ * Resolved spec instance with all runtime data.
+ *
+ * Created during Phase 1 of orchestration. Each instance owns
+ * an isolated core `OpenApiServer` with its own store, registry,
+ * handlers, seeds, and timeline.
+ */
+interface SpecInstance {
+    /** Unique spec identifier (explicit or auto-derived from info.title) */
+    id: string;
+    /** Spec metadata for DevTools display and WebSocket protocol */
+    info: SpecInfo;
+    /** Core server instance (isolated Hono app, store, registry, etc.) */
+    server: OpenApiServer;
+    /** Resolved configuration for this spec */
+    config: ResolvedSpecConfig;
+}
+/**
+ * Orchestrator result — returned by `createOrchestrator()`.
+ *
+ * Provides access to the main Hono app (all specs mounted),
+ * individual spec instances, aggregated metadata, and lifecycle methods.
+ */
+interface OrchestratorResult {
+    /** Main Hono app with all specs mounted via X-Spec-Id dispatch */
+    app: Hono;
+    /** All spec instances (in config order) */
+    instances: SpecInstance[];
+    /** Spec metadata array for WebSocket `connected` event */
+    specsInfo: SpecInfo[];
+    /** Start the shared HTTP server on the configured port */
+    start(): Promise<void>;
+    /** Stop the HTTP server and clean up resources */
+    stop(): Promise<void>;
+    /** Actual bound port after start() resolves (0 before start or after stop) */
+    readonly port: number;
+}
+/**
+ * Create the multi-spec orchestrator.
+ *
+ * Flow:
+ * 1. **Phase 1 — Process specs**: For each spec config, load handlers/seeds,
+ *    create a core `OpenApiServer` instance, derive ID and proxy path.
+ * 2. **Phase 2 — Validate uniqueness**: Ensure all spec IDs and proxy paths
+ *    are unique and non-overlapping.
+ * 3. **Phase 3 — Build main app**: Create a single Hono app with CORS,
+ *    DevTools, Internal API, and X-Spec-Id dispatch middleware.
+ *
+ * **Note**: This function mutates `options.specs[i]` to write back resolved
+ * values (id, proxyPath, proxyPathSource, handlersDir, seedsDir) so that
+ * downstream consumers (banner, file watcher, plugin.ts) see the final values.
+ *
+ * @param options - Resolved plugin options (from `resolveOptions()`)
+ * @param vite - Vite dev server instance (for ssrLoadModule)
+ * @param cwd - Project root directory
+ * @returns Orchestrator result with app, instances, and lifecycle methods
+ */
+declare function createOrchestrator(options: ResolvedOptions, vite: ViteDevServer, cwd: string): Promise<OrchestratorResult>;
+
 /**
  * Handler Loading
  *
@@ -517,4 +786,4 @@ declare function registerDevTools(app: App, options?: RegisterDevToolsOptions):
  */
 declare function getDevToolsUrl(port?: number, host?: string, protocol?: 'http' | 'https'): string;
 
-export { type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, type SpecConfig, ValidationError, type ValidationErrorCode, createFileWatcher, debounce, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, openApiServer, registerDevTools };
+export { type DeriveProxyPathResult, type FileWatcher, type FileWatcherOptions, type LoadHandlersResult, type LoadSeedsResult, type OpenApiServerOptions, type OrchestratorResult, type ProxyPathSource, type RegisterDevToolsOptions, type ResolvedOptions, type ResolvedSpecConfig, SPEC_COLORS, type SpecConfig, type SpecInstance, ValidationError, type ValidationErrorCode, createFileWatcher, createOrchestrator, debounce, deriveProxyPath, deriveSpecId, getDevToolsUrl, getHandlerFiles, getSeedFiles, loadHandlers, loadSeeds, normalizeProxyPath, openApiServer, registerDevTools, resolveOptions, slugify, validateSpecs, validateUniqueIds, validateUniqueProxyPaths };