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

package/dist/lib/server/api/docs/metadata-warnings.js

@@ -0,0 +1,274 @@
+import { defaultOpenAPIRegistry } from '../openapi-registry.js';
+import { DEV } from 'esm-env';
+import { failureClass } from '../../../failure-class';
+import { kitLogger } from '../../../kit-logger';
+import { settle } from '../settled';
+import { getVibesKit } from '../../../instance';
+const logger = kitLogger('openapi-metadata-warnings');
+const EXCLUDED_ROUTES = new Set([
+    'GET /api/chat/rooms/{chatRoomId}/stream',
+    'GET /api/test-telemetry',
+    'GET /api/test-otel-complete'
+]);
+// Cache to prevent repeated warnings for the same routes
+const warningCaches = new WeakMap();
+// Check interval: 30 seconds in development
+const CHECK_INTERVAL = 30 * 1000;
+function isExcluded(method, path) {
+    return EXCLUDED_ROUTES.has(`${method.toUpperCase()} ${path}`);
+}
+function normaliseRegisteredPath(path) {
+    const cleaned = path.startsWith('/') ? path : `/${path}`;
+    if (cleaned === '/') {
+        return '/api';
+    }
+    if (cleaned.startsWith('/api')) {
+        return cleaned;
+    }
+    return `/api${cleaned}`;
+}
+/** Join path segments with `/`, collapsing duplicate separators at the joins. */
+function joinPath(...segments) {
+    return segments
+        .map((segment, index) => index === 0 ? segment.replace(/\/+$/, '') || '/' : segment.replace(/^\/+|\/+$/g, ''))
+        .filter((segment, index) => index === 0 || segment.length > 0)
+        .join('/')
+        .replace(/^\/\//, '/');
+}
+/** `filePath` relative to `root` ('' separators normalised to `/`). */
+function pathRelativeTo(root, filePath) {
+    const normalisedRoot = root.replace(/\\/g, '/').replace(/\/+$/, '');
+    const normalisedFile = filePath.replace(/\\/g, '/');
+    return normalisedFile.startsWith(`${normalisedRoot}/`)
+        ? normalisedFile.slice(normalisedRoot.length + 1)
+        : normalisedFile;
+}
+export async function checkOpenAPIMetadataWarnings(registry = defaultOpenAPIRegistry(), mountRoutes, options = {}) {
+    // Only run in development
+    if (!(options.dev ?? DEV)) {
+        return;
+    }
+    const kit = getVibesKit();
+    const projectRoot = options.projectRoot ?? kit.config.docs?.projectRoot;
+    const now = Date.now();
+    const warningCache = warningCaches.get(registry) ?? {
+        lastChecked: 0,
+        warningsShown: new Set()
+    };
+    warningCaches.set(registry, warningCache);
+    // Rate limit checks to avoid spamming logs
+    if (now - warningCache.lastChecked < CHECK_INTERVAL) {
+        return;
+    }
+    warningCache.lastChecked = now;
+    const checked = await settle(async () => {
+        // Get all actual API route files (excluding auth)
+        if (mountRoutes === undefined && projectRoot === undefined) {
+            if (!warningCache.warningsShown.has('no-project-root')) {
+                logger.warn('OpenAPI metadata check skipped: declare config.docs.projectRoot (or pass mount routes) to scan route files');
+                warningCache.warningsShown.add('no-project-root');
+            }
+            return;
+        }
+        const fileSystem = options.fileSystem;
+        if (mountRoutes === undefined && fileSystem === undefined) {
+            if (!warningCache.warningsShown.has('no-file-system')) {
+                logger.warn('OpenAPI metadata check skipped: kit has no filesystem; pass a host fileSystem (or mount routes) to scan route files');
+                warningCache.warningsShown.add('no-file-system');
+            }
+            return;
+        }
+        // Route files are only scanned with a declared project root and a host filesystem.
+        const apiFiles = mountRoutes === undefined && projectRoot !== undefined && fileSystem !== undefined
+            ? await findApiRoutes(fileSystem, projectRoot)
+            : [];
+        const scannedRoutes = projectRoot === undefined || fileSystem === undefined
+            ? []
+            : await Promise.all(apiFiles.map((file) => filePathToApiRoute(fileSystem, file, projectRoot)));
+        // Get all registered routes from the OpenAPI registry
+        let registeredRoutes = registry.getRegisteredRoutes().map((route) => ({
+            method: route.method,
+            path: normaliseRegisteredPath(route.path),
+            hasMetadata: route.hasMetadata
+        }));
+        // Convert file paths to expected route paths for comparison
+        let expectedRoutes = (mountRoutes ?? scannedRoutes.flat()).map((route) => ({
+            ...route,
+            path: normaliseRegisteredPath(route.path)
+        }));
+        // Exclude intentionally undocumented routes from comparisons
+        registeredRoutes = registeredRoutes.filter((route) => !isExcluded(route.method, route.path));
+        expectedRoutes = expectedRoutes.filter((route) => !isExcluded(route.method, route.path));
+        // Find routes that exist as files but aren't registered
+        const unregisteredRoutes = expectedRoutes.filter((route) => !registeredRoutes.some((reg) => reg.method === route.method && reg.path === route.path));
+        // Find registered routes without metadata
+        const routesWithoutMetadata = registeredRoutes.filter((route) => !route.hasMetadata);
+        // Calculate coverage
+        const totalApiRoutes = expectedRoutes.length;
+        const routesWithMetadata = registeredRoutes.filter((route) => route.hasMetadata).length;
+        const coveragePercent = totalApiRoutes > 0 ? Math.round((routesWithMetadata / totalApiRoutes) * 100) : 0;
+        // Show warning if we have issues
+        if (unregisteredRoutes.length > 0 || routesWithoutMetadata.length > 0) {
+            if (!warningCache.warningsShown.has('summary')) {
+                const totalMissing = unregisteredRoutes.length + routesWithoutMetadata.length;
+                logger.warn(`⚠️  Missing OpenAPI metadata for ${totalMissing} endpoints (${coveragePercent}% coverage)`);
+                // Write detailed report to log file
+                await writeOpenAPIReport(fileSystem, projectRoot, {
+                    expectedRoutes,
+                    registeredRoutes,
+                    unregisteredRoutes,
+                    routesWithoutMetadata,
+                    apiFiles
+                });
+                // Show unregistered routes (not using vibes* wrappers)
+                if (unregisteredRoutes.length > 0) {
+                    logger.warn(`   Not using vibes* wrappers: ${unregisteredRoutes.length} endpoints`);
+                    const examples = unregisteredRoutes.slice(0, 3).map((r) => `${r.method} ${r.path}`);
+                    logger.info(`   Examples: ${examples.join(', ')}`);
+                    if (unregisteredRoutes.length > 3) {
+                        logger.info(`   ... and ${unregisteredRoutes.length - 3} more`);
+                    }
+                }
+                // Show registered routes missing metadata
+                if (routesWithoutMetadata.length > 0) {
+                    logger.warn(`   Missing metadata in vibes* config: ${routesWithoutMetadata.length} endpoints`);
+                    const examples = routesWithoutMetadata.slice(0, 3).map((r) => `${r.method} ${r.path}`);
+                    logger.info(`   Examples: ${examples.join(', ')}`);
+                    if (routesWithoutMetadata.length > 3) {
+                        logger.info(`   ... and ${routesWithoutMetadata.length - 3} more`);
+                    }
+                }
+                logger.info(`   Detailed report written to logs/openapi-invalid-endpoints.log`);
+                warningCache.warningsShown.add('summary');
+            }
+        }
+        else if (!warningCache.warningsShown.has('all-good')) {
+            // All routes have metadata - show success message once
+            logger.info('🎉 All API routes have OpenAPI metadata! Documentation coverage: 100%');
+            warningCache.warningsShown.add('all-good');
+        }
+    });
+    if (!checked.ok) {
+        logger.warn('Failed to check OpenAPI metadata warnings', {
+            reason: failureClass(checked.error)
+        });
+    }
+}
+/**
+ * Find all API route files recursively, excluding auth routes
+ */
+async function findApiRoutes(fs, projectRoot) {
+    const files = [];
+    const routesDir = joinPath(projectRoot, 'src/routes/api');
+    async function walkDir(dir) {
+        const listed = await settle(() => fs.readdir(dir, { withFileTypes: true }));
+        if (!listed.ok) {
+            logger.warn('Failed to read OpenAPI route directory', {
+                reason: failureClass(listed.error)
+            });
+            return;
+        }
+        for (const entry of listed.value) {
+            const fullPath = joinPath(dir, entry.name);
+            if (entry.isDirectory() && !entry.name.startsWith('_')) {
+                // Skip auth directory
+                if (entry.name === 'auth') {
+                    continue;
+                }
+                await walkDir(fullPath);
+            }
+            else if (entry.isFile() && entry.name === '+server.ts') {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walkDir(routesDir);
+    return files;
+}
+/**
+ * Convert file path to API route info with HTTP methods
+ */
+async function filePathToApiRoute(fs, filePath, projectRoot) {
+    // Convert absolute path to relative from project root, then to API route
+    const relativePath = pathRelativeTo(projectRoot, filePath);
+    // Convert src/routes/api/ai/agents/+server.ts -> /api/ai/agents
+    const routePath = relativePath
+        .replace('src/routes', '')
+        .replace('/+server.ts', '')
+        .replace(/\\/g, '/') // Handle Windows paths
+        .replace(/\[([^\]]+)\]/g, '{$1}'); // [id] -> {id}
+    // Read the file to detect which HTTP methods are actually exported
+    const read = await settle(() => fs.readFile(filePath, 'utf-8'));
+    if (!read.ok) {
+        logger.warn('Failed to read OpenAPI route file', { reason: failureClass(read.error) });
+        return [];
+    }
+    const fileContent = read.value;
+    const httpMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+    const exportedMethods = [];
+    for (const method of httpMethods) {
+        // Look for 'export const GET =' or 'export { GET }' patterns
+        const exportPattern = new RegExp(`export\\s+(?:const\\s+)?${method}\\s*[=:]|export\\s*{[^}]*\\b${method}\\b`);
+        if (exportPattern.test(fileContent)) {
+            exportedMethods.push(method);
+        }
+    }
+    return exportedMethods.map((method) => ({
+        method,
+        path: routePath
+    }));
+}
+/**
+ * Write detailed OpenAPI analysis report to log file
+ */
+async function writeOpenAPIReport(fs, projectRoot, data) {
+    if (projectRoot === undefined || fs === undefined)
+        return;
+    const logsDir = joinPath(projectRoot, 'logs');
+    // Ensure logs directory exists
+    const created = await settle(() => fs.mkdir(logsDir, { recursive: true }));
+    if (!created.ok) {
+        logger.warn('Failed to create OpenAPI report directory', {
+            reason: failureClass(created.error)
+        });
+    }
+    const report = [
+        '# OpenAPI Metadata Analysis Report',
+        `Generated: ${new Date().toISOString()}`,
+        '',
+        '## Summary',
+        `- Total API files found: ${data.apiFiles.length}`,
+        `- Total expected routes: ${data.expectedRoutes.length}`,
+        `- Total registered routes: ${data.registeredRoutes.length}`,
+        `- Routes with metadata: ${data.registeredRoutes.filter((r) => r.hasMetadata).length}`,
+        `- Unregistered routes: ${data.unregisteredRoutes.length}`,
+        `- Routes missing metadata: ${data.routesWithoutMetadata.length}`,
+        '',
+        '## API Files Found',
+        ...data.apiFiles.map((file) => `- ${file}`),
+        '',
+        '## Expected Routes (from file scan)',
+        ...data.expectedRoutes.map((route) => `- ${route.method} ${route.path}`),
+        '',
+        '## Registered Routes (in OpenAPI registry)',
+        ...data.registeredRoutes.map((route) => `- ${route.method} ${route.path} ${route.hasMetadata ? '✓' : '✗'}`),
+        '',
+        '## Unregistered Routes (not using vibes* wrappers)',
+        ...data.unregisteredRoutes.map((route) => `- ${route.method} ${route.path}`),
+        '',
+        '## Routes Missing Metadata (using vibes* but no metadata)',
+        ...data.routesWithoutMetadata.map((route) => `- ${route.method} ${route.path}`),
+        ''
+    ];
+    const reportPath = joinPath(logsDir, 'openapi-invalid-endpoints.log');
+    const written = await settle(() => fs.writeFile(reportPath, report.join('\n'), 'utf-8'));
+    if (!written.ok) {
+        logger.warn('Failed to write OpenAPI report', { reason: failureClass(written.error) });
+    }
+}
+/**
+ * Reset warning cache (useful for testing)
+ */
+export function resetWarningCache(registry = defaultOpenAPIRegistry()) {
+    warningCaches.delete(registry);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * `mountGraphQLRoute` — SvelteKit handlers that expose a GraphQL endpoint
+ * whose schema is derived from the in-memory OpenAPI registry. Same source
+ * of truth as `mountOpenApiRoute`.
+ *
+ * Tier 4 of `docs/architecture/DOCS-RUNTIME.md`. Lifted from
+ * `~/Projects/phx.digital/exemplar/src/routes/api/graphql/+server.ts`.
+ *
+ * Usage:
+ *   // apps/<feature>-web/src/routes/api/docs/graphql/+server.ts
+ *   import { mountGraphQLRoute } from '../../../index.ts/server/api/graphql/mount-graphql';
+ *   const { GET, POST, OPTIONS } = mountGraphQLRoute({
+ *     title: 'AI Web GraphQL',
+ *     version: '0.1.0',
+ *     graphqlEndpoint: '/api/docs/graphql'
+ *   });
+ *   export { GET, POST, OPTIONS };
+ */
+import type { RequestHandler } from '@sveltejs/kit';
+import { type MountOpenApiOptions } from '../mount-openapi.js';
+export interface MountGraphQLOptions extends MountOpenApiOptions {
+    /** Pathname the GraphQL endpoint is served at. Defaults to `/api/docs/graphql`. */
+    graphqlEndpoint?: string;
+}
+export interface GraphQLRouteHandlers {
+    GET: RequestHandler;
+    POST: RequestHandler;
+    OPTIONS: RequestHandler;
+}
+export declare function mountGraphQLRoute(options?: MountGraphQLOptions): GraphQLRouteHandlers;

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

@@ -0,0 +1,93 @@
+/**
+ * `mountGraphQLRoute` — SvelteKit handlers that expose a GraphQL endpoint
+ * whose schema is derived from the in-memory OpenAPI registry. Same source
+ * of truth as `mountOpenApiRoute`.
+ *
+ * Tier 4 of `docs/architecture/DOCS-RUNTIME.md`. Lifted from
+ * `~/Projects/phx.digital/exemplar/src/routes/api/graphql/+server.ts`.
+ *
+ * Usage:
+ *   // apps/<feature>-web/src/routes/api/docs/graphql/+server.ts
+ *   import { mountGraphQLRoute } from '../../../index.ts/server/api/graphql/mount-graphql';
+ *   const { GET, POST, OPTIONS } = mountGraphQLRoute({
+ *     title: 'AI Web GraphQL',
+ *     version: '0.1.0',
+ *     graphqlEndpoint: '/api/docs/graphql'
+ *   });
+ *   export { GET, POST, OPTIONS };
+ */
+import { createYoga } from 'graphql-yoga';
+import { makeExecutableSchema } from '@graphql-tools/schema';
+import { kitLogger } from '../../../kit-logger';
+import { loadKitConfig, loadKitConfigDefaults } from "../../../config/kit.config.descriptor.js";
+import { asVibesKitLocals } from '../../locals.js';
+import { createOpenAPIRegistry, defaultOpenAPIRegistry } from '../openapi-registry.js';
+import { registerRouteModules } from '../mount-openapi.js';
+import { openApiToGraphQLSchema } from './schema-from-openapi.js';
+const logger = kitLogger('mount-graphql');
+const CACHE_TTL = 60_000;
+export function mountGraphQLRoute(options = {}) {
+    const registry = options.registry ??
+        (options.routeModules !== undefined ? createOpenAPIRegistry() : defaultOpenAPIRegistry());
+    let cachedYoga = null;
+    let cacheTime = 0;
+    let cachedYogaKey = '';
+    async function buildYoga(event) {
+        await registerRouteModules(options, registry);
+        const requestBase = event.url.origin.replace(/\/$/, '');
+        const inferredServers = options.servers ?? [
+            { url: `${requestBase}/api`, description: 'Current Host API Server' }
+        ];
+        const routeCount = registry.getRegisteredRoutes().length;
+        if (routeCount === 0) {
+            logger.warn('Building GraphQL schema with zero registered REST routes — likely a lifecycle ordering issue. Confirm `+server.ts` files import before the GraphQL endpoint is hit.', { url: event.url.pathname });
+        }
+        // The contact origin is configuration: the kit config the request
+        // runtime resolves; no runtime means the declared schema default.
+        // 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 ?? {});
+        const contactOrigin = locals.runtime
+            ? (await loadKitConfig(locals.runtime)).docsContactOrigin
+            : loadKitConfigDefaults().docsContactOrigin;
+        const openApiSpec = registry.generateSpec({
+            title: options.title,
+            version: options.version,
+            description: options.description,
+            servers: inferredServers,
+            contactOrigin
+        });
+        const cacheKey = JSON.stringify(openApiSpec);
+        if (cachedYoga && Date.now() - cacheTime < CACHE_TTL && cachedYogaKey === cacheKey)
+            return cachedYoga;
+        const { typeDefs, resolvers } = openApiToGraphQLSchema(openApiSpec);
+        const schema = makeExecutableSchema({ typeDefs, resolvers });
+        const yogaApp = createYoga({
+            schema,
+            graphqlEndpoint: options.graphqlEndpoint ?? '/api/docs/graphql',
+            fetchAPI: { Response },
+            graphiql: false,
+            cors: {
+                origin: '*',
+                methods: ['GET', 'POST', 'OPTIONS'],
+                allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With']
+            },
+            context: ({ request, fetch }) => ({ request, fetch })
+        });
+        cachedYoga = yogaApp;
+        cacheTime = Date.now();
+        cachedYogaKey = cacheKey;
+        logger.info('GraphQL schema rebuilt from OpenAPI registry', { routeCount });
+        return yogaApp;
+    }
+    const handler = async (event) => {
+        const yogaApp = await buildYoga(event);
+        return yogaApp(event.request, event);
+    };
+    return {
+        GET: handler,
+        POST: handler,
+        OPTIONS: handler
+    };
+}

package/dist/lib/server/api/graphql/schema-from-openapi.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Derive a GraphQL schema from the in-memory OpenAPI registry.
+ *
+ * Lifted from `~/Projects/phx.digital/exemplar/src/routes/api/graphql/+server.ts`
+ * per Tier 4 of `docs/architecture/DOCS-RUNTIME.md`. Same source of truth
+ * as REST — when `vibesGET`/`vibesPOST`/etc. auto-register a route in
+ * `openAPIRegistry`, that route surfaces here as a GraphQL Query (GET) or
+ * Mutation (POST/PUT/PATCH/DELETE) field.
+ *
+ * The schema is a thin proxy: each resolver re-fetches the underlying REST
+ * endpoint via the SvelteKit event's `fetch`. Headers (auth, etc.) flow
+ * through; bodies for mutations come in as a String `input`.
+ */
+type Resolver = <TParent>(parent: TParent, args: {
+    input?: string;
+}, context: {
+    request: Request;
+    fetch?: typeof fetch;
+}) => Promise<string>;
+type ResolverMap = {
+    Query: Record<string, Resolver>;
+    Mutation?: Record<string, Resolver>;
+};
+export interface SchemaFromOpenApiResult {
+    typeDefs: string;
+    resolvers: ResolverMap;
+}
+/**
+ * Walk an OpenAPI spec and produce GraphQL typeDefs + resolvers. Each
+ * REST route becomes a GraphQL field that proxies the call via
+ * `eventFetch`. GETs land on Query; POST/PUT/PATCH/DELETE on Mutation
+ * (with optional String `input` argument).
+ */
+export declare function openApiToGraphQLSchema<TSpec>(openApiSpec: TSpec, eventFetch?: typeof fetch): SchemaFromOpenApiResult;
+export {};

package/dist/lib/server/api/graphql/schema-from-openapi.js

@@ -0,0 +1,219 @@
+/**
+ * Derive a GraphQL schema from the in-memory OpenAPI registry.
+ *
+ * Lifted from `~/Projects/phx.digital/exemplar/src/routes/api/graphql/+server.ts`
+ * per Tier 4 of `docs/architecture/DOCS-RUNTIME.md`. Same source of truth
+ * as REST — when `vibesGET`/`vibesPOST`/etc. auto-register a route in
+ * `openAPIRegistry`, that route surfaces here as a GraphQL Query (GET) or
+ * Mutation (POST/PUT/PATCH/DELETE) field.
+ *
+ * The schema is a thin proxy: each resolver re-fetches the underlying REST
+ * endpoint via the SvelteKit event's `fetch`. Headers (auth, etc.) flow
+ * through; bodies for mutations come in as a String `input`.
+ */
+import * as z from 'zod/v4';
+import { failureClass } from '../../../failure-class';
+import { kitLogger } from '../../../kit-logger';
+import { settle } from '../settled';
+const logger = kitLogger('graphql-schema');
+const METHOD_ORDER = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace'];
+/**
+ * The part of an OpenAPI document this module reads. Anything that is not an
+ * object with an object `paths` yields no operations; a path item entry that is
+ * not an operation object is skipped; a non-string operationId/summary is ignored.
+ */
+const operationSchema = z.looseObject({
+    operationId: z.string().optional().catch(undefined),
+    summary: z.string().optional().catch(undefined)
+});
+const pathItemSchema = z.record(z.string(), operationSchema.optional().catch(undefined));
+const openApiPathsSchema = z
+    .looseObject({
+    paths: z.record(z.string(), pathItemSchema.optional().catch(undefined)).catch({})
+})
+    .catch({ paths: {} });
+function ensureGraphQLCompliantName(name) {
+    if (!name)
+        return '_operation';
+    if (!/^[_A-Za-z]/.test(name)) {
+        return `_${name}`;
+    }
+    return name;
+}
+function toCamelCase(parts) {
+    if (parts.length === 0) {
+        return '';
+    }
+    return parts
+        .map((segment, index) => {
+        if (segment.length === 0)
+            return '';
+        const lower = segment.toLowerCase();
+        if (index === 0) {
+            return lower;
+        }
+        return lower.charAt(0).toUpperCase() + lower.slice(1);
+    })
+        .join('');
+}
+function sanitizeSegment(segment) {
+    return segment.replace(/[{}]/g, '').replace(/[^a-zA-Z0-9]/g, '');
+}
+function sanitizeOperationId(operationId) {
+    if (!operationId)
+        return '';
+    const spaced = operationId
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z0-9]+)/g, '$1 $2')
+        .replace(/[^a-zA-Z0-9]+/g, ' ');
+    const parts = spaced
+        .split(' ')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    return toCamelCase(parts);
+}
+function uniqueName(base, registry) {
+    let candidate = base;
+    let counter = 2;
+    while (registry.has(candidate)) {
+        candidate = `${base}${counter}`;
+        counter += 1;
+    }
+    registry.add(candidate);
+    return candidate;
+}
+function escapeDescription(description) {
+    if (!description)
+        return undefined;
+    return description.replace(/"""/g, '""');
+}
+function formatFieldDescription(summary, method, path) {
+    const methodPath = `${method.toUpperCase()} ${path}`;
+    if (!summary)
+        return methodPath;
+    if (summary.toLowerCase() === methodPath.toLowerCase())
+        return methodPath;
+    return `${summary} • ${methodPath}`;
+}
+function formatFieldDefinition(name, returnType, description, args) {
+    const escapedDescription = escapeDescription(description);
+    const lines = [];
+    if (escapedDescription) {
+        lines.push(`    """${escapedDescription}"""`);
+    }
+    const argSection = args ? `(${args})` : '';
+    lines.push(`    ${name}${argSection}: ${returnType}`);
+    return lines.join('\n');
+}
+/**
+ * Walk an OpenAPI spec and produce GraphQL typeDefs + resolvers. Each
+ * REST route becomes a GraphQL field that proxies the call via
+ * `eventFetch`. GETs land on Query; POST/PUT/PATCH/DELETE on Mutation
+ * (with optional String `input` argument).
+ */
+export function openApiToGraphQLSchema(openApiSpec, eventFetch) {
+    const usedQueryNames = new Set();
+    const usedMutationNames = new Set();
+    let typeDefs = `\n    type Query {\n  `;
+    const mutationFields = [];
+    const mutationResolvers = {};
+    const resolvers = {
+        Query: {}
+    };
+    const knownMethods = new Set(METHOD_ORDER);
+    const sortedPathEntries = Object.entries(openApiPathsSchema.parse(openApiSpec).paths).sort(([pathA], [pathB]) => pathA.localeCompare(pathB));
+    for (const [path, pathItem] of sortedPathEntries) {
+        if (!pathItem)
+            continue;
+        const methodEntries = Object.entries(pathItem)
+            .flatMap(([method, operation]) => operation && knownMethods.has(method.toLowerCase()) ? [[method, operation]] : [])
+            .sort(([methodA], [methodB]) => {
+            const a = methodA.toLowerCase();
+            const b = methodB.toLowerCase();
+            const aIndex = METHOD_ORDER.indexOf(a);
+            const bIndex = METHOD_ORDER.indexOf(b);
+            const aScore = aIndex === -1 ? METHOD_ORDER.length : aIndex;
+            const bScore = bIndex === -1 ? METHOD_ORDER.length : bIndex;
+            if (aScore !== bScore)
+                return aScore - bScore;
+            return a.localeCompare(b);
+        });
+        for (const [method, operation] of methodEntries) {
+            const methodLower = method.toLowerCase();
+            const pathSegments = path.split('/').filter(Boolean);
+            const apiSegments = pathSegments[0] === 'api' ? pathSegments.slice(1) : pathSegments;
+            const sanitizedSegments = apiSegments.map(sanitizeSegment).filter(Boolean);
+            const cleanPath = sanitizedSegments.length > 0 ? toCamelCase(sanitizedSegments) : 'root';
+            const fallbackName = `${methodLower}${cleanPath.charAt(0).toUpperCase() + cleanPath.slice(1)}`;
+            const { operationId, summary } = operation;
+            const fromOperationId = sanitizeOperationId(operationId);
+            let fieldName = ensureGraphQLCompliantName(fromOperationId || fallbackName);
+            if (!operationId || fieldName.toLowerCase() === fallbackName.toLowerCase()) {
+                fieldName = ensureGraphQLCompliantName(fallbackName);
+            }
+            if (methodLower === 'get') {
+                fieldName = uniqueName(fieldName, usedQueryNames);
+            }
+            else if (['post', 'put', 'patch', 'delete'].includes(methodLower)) {
+                fieldName = uniqueName(fieldName, usedMutationNames);
+            }
+            else {
+                fieldName = uniqueName(fieldName, usedQueryNames);
+            }
+            const fieldDescription = formatFieldDescription(summary, methodLower, path);
+            const httpMethod = methodLower.toUpperCase();
+            const makeResolver = (allowBody) => async (_parent, args, context) => {
+                const proxied = await settle(async () => {
+                    const targetPath = path.startsWith('/api') ? path : `/api${path}`;
+                    const requestFetch = context.fetch ?? eventFetch;
+                    if (!requestFetch)
+                        throw new Error('GraphQL REST proxy requires request-local fetch');
+                    const response = await requestFetch(targetPath, {
+                        method: httpMethod,
+                        headers: {
+                            'Content-Type': 'application/json',
+                            ...Object.fromEntries(context.request.headers)
+                        },
+                        body: allowBody && args.input ? JSON.stringify(JSON.parse(args.input)) : undefined
+                    });
+                    const result = await response.text();
+                    return response.ok ? result : `Error ${response.status}: ${result}`;
+                });
+                if (proxied.ok)
+                    return proxied.value;
+                // A fixed answer crosses GraphQL; only the failure class reaches the logger.
+                logger.warn('GraphQL REST proxy request failed', {
+                    reason: failureClass(proxied.error)
+                });
+                return 'Error: REST proxy request failed';
+            };
+            if (methodLower === 'get') {
+                typeDefs += `${formatFieldDefinition(fieldName, 'String', fieldDescription)}\n`;
+                resolvers.Query[fieldName] = makeResolver(false);
+            }
+            else if (['post', 'put', 'patch', 'delete'].includes(methodLower)) {
+                mutationFields.push(formatFieldDefinition(fieldName, 'String', fieldDescription, 'input: String'));
+                mutationResolvers[fieldName] = makeResolver(true);
+            }
+            else {
+                typeDefs += `${formatFieldDefinition(fieldName, 'String', fieldDescription)}\n`;
+                resolvers.Query[fieldName] = makeResolver(false);
+            }
+        }
+    }
+    if (Object.keys(resolvers.Query).length === 0) {
+        // GraphQL requires Query to declare a field; an API with no GET operations
+        // (or none at all) must still produce a valid, empty-looking schema.
+        typeDefs += `${formatFieldDefinition('_empty', 'String', 'No queryable operations are declared')}\n`;
+    }
+    typeDefs += `  }\n`;
+    if (mutationFields.length > 0) {
+        typeDefs += `\n  type Mutation {\n${mutationFields.join('\n')}\n  }\n`;
+        resolvers.Mutation = mutationResolvers;
+    }
+    logger.info('Generated GraphQL type definitions from OpenAPI', {
+        queries: Object.keys(resolvers.Query).length,
+        mutations: Object.keys(mutationResolvers).length
+    });
+    return { typeDefs, resolvers };
+}