@vibesdotdev/kit 0.0.0-stage → 1.0.0-rc.4

package/dist/lib/server/api/mount-openapi.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `mountOpenApiRoute` — one-line SvelteKit handler that emits the registered
+ * OpenAPI spec as JSON. Pairs with the auto-registration that already runs
+ * in every `vibesGET/POST/PUT/PATCH/DELETE` wrapper (see `endpoint/wrapper.ts:312`).
+ *
+ * Tier 3b of `docs/architecture/DOCS-RUNTIME.md`.
+ *
+ * Usage:
+ *   // apps/<feature>-web/src/routes/api/docs/openapi.json/+server.ts
+ *   import { mountOpenApiRoute } from '../../index.ts/server/api/mount-openapi';
+ *   export const GET = mountOpenApiRoute({
+ *     title: 'AI Web API',
+ *     version: '1.0.0'
+ *   });
+ *
+ * Explicit routeModules are loaded into a mount-owned registry. Callers omitting
+ * both routeModules and registry retain the legacy import-time registry and its
+ * requirement that endpoint modules load before the documentation request.
+ */
+import type { RequestHandler } from '@sveltejs/kit';
+import { type OpenAPIRegistry } from './openapi-registry.js';
+/** A route module (or a lazy loader for one), as `import.meta.glob` produces it. */
+export type RouteModuleSource<TModule = unknown> = TModule | (() => TModule | Promise<TModule>);
+export interface MountOpenApiOptions<TModule = unknown> {
+    /** Explicit ownership; omitted routeModules and registry retain the legacy default. */
+    registry?: OpenAPIRegistry;
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    routeModules?: Record<string, RouteModuleSource<TModule>>;
+    routeModulePathPrefix?: string;
+}
+export declare function registerRouteModules<TModule>(options: MountOpenApiOptions<TModule>, registry: OpenAPIRegistry): Promise<void>;
+export declare const OPENAPI_CORS_HEADERS: {
+    'Access-Control-Allow-Origin': string;
+    'Access-Control-Allow-Methods': string;
+    'Access-Control-Allow-Headers': string;
+};
+export declare function mountOpenApiRoute(options?: MountOpenApiOptions): RequestHandler;

package/dist/lib/server/api/mount-openapi.js

@@ -0,0 +1,151 @@
+/**
+ * `mountOpenApiRoute` — one-line SvelteKit handler that emits the registered
+ * OpenAPI spec as JSON. Pairs with the auto-registration that already runs
+ * in every `vibesGET/POST/PUT/PATCH/DELETE` wrapper (see `endpoint/wrapper.ts:312`).
+ *
+ * Tier 3b of `docs/architecture/DOCS-RUNTIME.md`.
+ *
+ * Usage:
+ *   // apps/<feature>-web/src/routes/api/docs/openapi.json/+server.ts
+ *   import { mountOpenApiRoute } from '../../index.ts/server/api/mount-openapi';
+ *   export const GET = mountOpenApiRoute({
+ *     title: 'AI Web API',
+ *     version: '1.0.0'
+ *   });
+ *
+ * Explicit routeModules are loaded into a mount-owned registry. Callers omitting
+ * both routeModules and registry retain the legacy import-time registry and its
+ * requirement that endpoint modules load before the documentation request.
+ */
+import { json } from '@sveltejs/kit';
+import * as z from 'zod/v4';
+import { failureClass } from '../../failure-class';
+import { kitLogger } from '../../kit-logger';
+import { loadKitConfig, loadKitConfigDefaults } from "../../config/kit.config.descriptor.js";
+import { asVibesKitLocals } from '../locals.js';
+import { settle } from './settled';
+import { createOpenAPIRegistry, defaultOpenAPIRegistry } from './openapi-registry.js';
+import { getVibesOpenApiRouteMetadata, registerWithOpenAPI } from '../endpoint/wrapper.js';
+const logger = kitLogger('mount-openapi');
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/** A route module is an object of named exports; anything else is skipped. */
+const routeModuleSchema = z.looseObject({});
+/** A lazy loader (what `import.meta.glob` yields without `eager`): any callable. Its result is parsed as a route module. */
+function isLoader(source) {
+    return typeof source === 'function';
+}
+/** An exported route handler: anything callable. */
+function isHandler(value) {
+    return typeof value === 'function';
+}
+function routePathFromModuleKey(moduleKey, prefix = '') {
+    const routePath = moduleKey.replace(/\\/g, '/').replace(/\/\+server\.[cm]?[jt]s$/, '');
+    const routeSegments = routePath
+        .split('/')
+        .filter((segment) => segment && segment !== '.' && segment !== '..');
+    const prefixSegments = prefix.split('/').filter(Boolean);
+    return `/${[...prefixSegments, ...routeSegments].join('/')}`;
+}
+/**
+ * Resolve a route module (or its lazy loader) to the handlers it exports.
+ * A loader that throws, or a value that is not a module object, yields none.
+ */
+async function loadRouteHandlers(moduleKey, source) {
+    let loaded = source;
+    if (isLoader(source)) {
+        const imported = await settle(source);
+        if (!imported.ok) {
+            logger.warn('Skipping OpenAPI route module after import failure', {
+                moduleKey,
+                reason: failureClass(imported.error)
+            });
+            return [];
+        }
+        loaded = imported.value;
+    }
+    const routeModule = routeModuleSchema.safeParse(loaded);
+    if (!routeModule.success)
+        return [];
+    const handlers = [];
+    for (const method of HTTP_METHODS) {
+        const handler = routeModule.data[method];
+        if (isHandler(handler))
+            handlers.push({ method, handler });
+    }
+    return handlers;
+}
+export async function registerRouteModules(options, registry) {
+    if (!options.routeModules)
+        return;
+    const expectedRoutes = [];
+    for (const [moduleKey, source] of Object.entries(options.routeModules)) {
+        const handlers = await loadRouteHandlers(moduleKey, source);
+        const routePath = routePathFromModuleKey(moduleKey, options.routeModulePathPrefix);
+        for (const { method, handler } of handlers) {
+            expectedRoutes.push({ method, path: routePath });
+            const metadata = getVibesOpenApiRouteMetadata(handler);
+            if (!metadata)
+                continue;
+            registerWithOpenAPI(method, routePath, metadata.config, { allowDuringBuild: true, registry });
+        }
+    }
+    registry.setExpectedRoutes(expectedRoutes);
+}
+export const OPENAPI_CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With'
+};
+/**
+ * The contact origin the document names: the kit config the request runtime
+ * resolves (`loadKitConfig` — a composed `kit` manifest, else the environment
+ * catalog for the runtime's tier). A host that hands no runtime has no config
+ * to read, so the schema's declared production default applies.
+ */
+async function contactOriginFor(event) {
+    // SAFETY: an absent `event.locals` carries no fields at all, so the empty
+    // object is the same shape SvelteKit hands before any handle has run; the
+    // only field read below is `runtime`, which stays undefined for it.
+    const locals = asVibesKitLocals(event.locals ?? {});
+    if (!locals.runtime)
+        return loadKitConfigDefaults().docsContactOrigin;
+    const config = await loadKitConfig(locals.runtime);
+    return config.docsContactOrigin;
+}
+export function mountOpenApiRoute(options = {}) {
+    const registry = options.registry ??
+        (options.routeModules !== undefined ? createOpenAPIRegistry() : defaultOpenAPIRegistry());
+    return async (event) => {
+        if (event.request?.method === 'OPTIONS') {
+            return new Response(null, {
+                status: 204,
+                headers: OPENAPI_CORS_HEADERS
+            });
+        }
+        await registerRouteModules(options, registry);
+        const routeCount = registry.getRegisteredRoutes().length;
+        if (routeCount === 0) {
+            logger.warn('Serving OpenAPI spec with zero registered routes — likely a lifecycle ordering issue. Confirm `+server.ts` files import before the spec endpoint is hit.', { url: event.url.pathname });
+        }
+        const inferredServers = options.servers ?? [
+            {
+                url: `${event.url.protocol}//${event.url.host}`,
+                description: 'Current host'
+            }
+        ];
+        const spec = registry.generateSpec({
+            title: options.title,
+            version: options.version,
+            description: options.description,
+            servers: inferredServers,
+            contactOrigin: await contactOriginFor(event)
+        });
+        return json(spec, {
+            headers: {
+                'Cache-Control': 'no-store, must-revalidate',
+                'Content-Type': 'application/json',
+                ...OPENAPI_CORS_HEADERS
+            }
+        });
+    };
+}

package/dist/lib/server/api/openapi-registry.d.ts

@@ -0,0 +1,249 @@
+/**
+ * OpenAPI Registry
+ *
+ * Global registry for API endpoints that automatically generates OpenAPI/Swagger documentation.
+ * Routes register themselves when imported, and the spec is generated on-demand.
+ */
+import * as z from 'zod/v4';
+import type { ZodSchema } from 'zod/v4';
+import type { MetadataWarningsOptions } from './docs/metadata-warnings.js';
+/** A JSON Schema node as produced by Zod's own generator; Zod owns this type. */
+export type OpenApiSchema = z.core.JSONSchema.JSONSchema;
+type OpenApiSchemaOrBoolean = z.core.JSONSchema._JSONSchema;
+export interface RouteConfig {
+    metadata?: {
+        summary?: string;
+        description?: string;
+        tags?: string[];
+        deprecated?: boolean;
+        operationId?: string;
+    };
+    validation?: {
+        query?: ZodSchema;
+        body?: ZodSchema;
+        params?: ZodSchema;
+        headers?: ZodSchema;
+    };
+    auth?: {
+        required?: boolean;
+        redirect?: boolean;
+        superuser?: boolean;
+        permissions?: string[];
+        roles?: string[];
+    };
+    responses?: {
+        [statusCode: string]: {
+            description: string;
+            schema?: ZodSchema;
+        };
+    };
+    rateLimit?: {
+        window?: string;
+        max?: number;
+    };
+}
+export interface RegisteredRoute {
+    method: string;
+    path: string;
+    config: RouteConfig;
+}
+export interface RegisterRouteOptions {
+    /** The host's declared build phase (SvelteKit `$app/environment` `building`). */
+    building?: boolean;
+    allowDuringBuild?: boolean;
+}
+export interface GenerateSpecOptions {
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    /**
+     * The origin the document names as its contact URL. Callers resolve it
+     * through the runtime (`loadKitConfig(runtime).docsContactOrigin`); omitted
+     * means the schema's declared production default.
+     */
+    contactOrigin?: string;
+}
+export type OpenApiParameter = {
+    name: string;
+    in: 'path' | 'query' | 'header';
+    required: boolean;
+    schema: OpenApiSchemaOrBoolean;
+    description: string | undefined;
+};
+export type OpenApiResponse = {
+    description: string;
+    content: {
+        'application/json': {
+            schema: OpenApiSchema;
+        };
+    } | undefined;
+};
+/** Responses keyed by HTTP status code. */
+export type OpenApiResponses = {
+    [statusCode: string]: OpenApiResponse;
+};
+export type OpenApiOperation = {
+    summary: string;
+    description: string | undefined;
+    tags: string[];
+    deprecated: boolean;
+    operationId: string;
+    parameters: OpenApiParameter[];
+    responses: OpenApiResponses;
+    security?: Array<{
+        sessionAuth: string[];
+        permissions?: string[];
+    }>;
+    requestBody?: {
+        required: boolean;
+        content: {
+            'application/json': {
+                schema: OpenApiSchema;
+            };
+        };
+    };
+};
+export type OpenApiSecurityScheme = {
+    type: 'apiKey';
+    in: 'cookie' | 'header';
+    name: string;
+    description: string;
+};
+/** The document `generateSpec` returns. */
+export type OpenApiDocument = {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
+        contact: {
+            name: string;
+            url: string;
+        };
+        license: {
+            name: string;
+            url: string;
+        };
+    };
+    servers: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, Record<string, OpenApiOperation>>;
+    components: {
+        schemas: Record<string, OpenApiSchema>;
+        securitySchemes: Record<string, OpenApiSecurityScheme>;
+    };
+    tags: Array<{
+        name: string;
+        description: string;
+    }>;
+};
+export declare class OpenAPIRegistry {
+    #private;
+    private expectedRoutes?;
+    private coverageOptions;
+    /**
+     * Host facts for the development-only coverage check: the project root and the
+     * host filesystem the route-file scan and report go through. Without a
+     * `fileSystem` the scan and report do not happen.
+     */
+    setCoverageOptions(options: MetadataWarningsOptions): void;
+    /** The exported handlers belonging to an explicit mount, including undocumented routes. */
+    setExpectedRoutes(routes: Array<{
+        method: string;
+        path: string;
+    }>): void;
+    private routes;
+    private componentSchemas;
+    /**
+     * Register a route with its configuration
+     */
+    register(method: string, path: string, config: RouteConfig, options?: RegisterRouteOptions): void;
+    /**
+     * Convert SvelteKit route pattern to OpenAPI path
+     * [param] -> {param}
+     * [...rest] -> {rest}
+     * [[optional]] -> {optional}
+     */
+    private convertToOpenAPIPath;
+    /**
+     * Convert a Zod schema to an OpenAPI JSON Schema using Zod v4's built-in generator.
+     * A hand-written JSON Schema object is passed through with a description added.
+     */
+    private zodToOpenAPISchema;
+    /**
+     * Extract path parameters from OpenAPI path
+     */
+    private extractPathParams;
+    /** Turn the top-level properties of a converted schema into OpenAPI parameters. */
+    private parametersFromSchema;
+    /**
+     * Generate OpenAPI operation object
+     */
+    private generateOperation;
+    /**
+     * Generate responses object
+     */
+    private generateResponses;
+    /**
+    /**
+     * Generate complete OpenAPI specification.
+     *
+     * The contact origin is configuration, never a literal here: it is the
+     * `docsContactOrigin` of the kit config the caller resolved through the
+     * runtime (`loadKitConfig(runtime)` — a composed `kit` manifest, else the
+     * environment catalog for the runtime's tier) and handed in as
+     * `options.contactOrigin`. Omitted means the schema's declared production
+     * default (`loadKitConfigDefaults()`).
+     */
+    generateSpec(options?: GenerateSpecOptions): OpenApiDocument;
+    /**
+     * Clear all registered routes (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get statistics about registered routes
+     */
+    getStats(): {
+        totalRoutes: number;
+        byMethod: {
+            [k: string]: number;
+        };
+        byTag: {
+            [k: string]: number;
+        };
+        paths: string[];
+    };
+    /**
+     * Get all registered routes for coverage analysis
+     */
+    getRegisteredRoutes(): Array<{
+        method: string;
+        path: string;
+        hasMetadata: boolean;
+    }>;
+    /**
+     * Check OpenAPI coverage after spec generation (when routes are loaded)
+     */
+    private checkCoverageAfterGeneration;
+    /**
+     * Register a reusable schema component
+     */
+    registerSchema(name: string, schema: ZodSchema): void;
+}
+/** Create an independent registry for an explicit API surface. */
+export declare function createOpenAPIRegistry(): OpenAPIRegistry;
+/**
+ * The default registry for callers that have not declared their mount
+ * inventory: neither an explicit `registry` nor `routeModules`. Created on first
+ * use and shared by every such caller in this process, so import-time
+ * registration and the documentation request still meet. A mount that declares
+ * its inventory gets its own registry through `createOpenAPIRegistry()` instead.
+ */
+export declare function defaultOpenAPIRegistry(): OpenAPIRegistry;
+export {};