@geekmidas/cli 10.0.0-alpha.2 → 10.0.0-alpha.21

package/dist/{openapi-c9bpieI5.cjs → openapi-B8bu_OXN.cjs}

@@ -1,13 +1,12 @@
-const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_discover = require('./discover-DTmFeloL.cjs');
-const require_config = require('./config-BholeD-0.cjs');
-const node_path = require_chunk.__toESM(require("node:path"));
-const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
-const node_child_process = require_chunk.__toESM(require("node:child_process"));
-const __geekmidas_constructs_endpoints = require_chunk.__toESM(require("@geekmidas/constructs/endpoints"));
-const node_url = require_chunk.__toESM(require("node:url"));
-const __geekmidas_schema_conversion = require_chunk.__toESM(require("@geekmidas/schema/conversion"));
-
+const require_discover = require("./discover-BERGFg8v.cjs");
+const require_config = require("./config-DSXI480r.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_child_process = require("node:child_process");
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _geekmidas_constructs_endpoints = require("@geekmidas/constructs/endpoints");
+let node_url = require("node:url");
+let _geekmidas_schema_conversion = require("@geekmidas/schema/conversion");
 //#region src/build/endpoint-analyzer.ts
 /**
 * Analyze an endpoint to extract its features
@@ -84,7 +83,6 @@ function summarizeAnalysis(analyses) {
 		byFeature
 	};
 }
-
 //#endregion
 //#region src/build/handler-templates.ts
 /**
@@ -106,8 +104,7 @@ function generateMinimalHandler(analysis) {
 	const { exportName, features } = analysis;
 	const method = analysis.method.toLowerCase();
 	const validators = generateValidators(exportName, features);
-	const hasValidators = validators.length > 0;
-	if (!hasValidators && !features.hasOutputValidation) return `
+	if (!(validators.length > 0) && !features.hasOutputValidation) return `
   // Minimal handler: ${analysis.route} (${analysis.method})
   app.${method}('${analysis.route}', async (c) => {
     const result = await ${exportName}.handler(
@@ -255,10 +252,10 @@ function generateValidatorsFile(analyses) {
 	const needsQuery = analyses.some((a) => a.features.hasQueryValidation);
 	const needsParams = analyses.some((a) => a.features.hasParamValidation);
 	if (!needsBody && !needsQuery && !needsParams) return `// No validators needed for this build\nexport {};\n`;
-	const exports$1 = [];
+	const exports = [];
 	const factories = [];
 	if (needsBody) {
-		exports$1.push("validateBody");
+		exports.push("validateBody");
 		factories.push(`
 export const validateBody = (endpoint: any) =>
   validator('json', async (value, c) => {
@@ -269,7 +266,7 @@ export const validateBody = (endpoint: any) =>
   });`);
 	}
 	if (needsQuery) {
-		exports$1.push("validateQuery");
+		exports.push("validateQuery");
 		factories.push(`
 export const validateQuery = (endpoint: any) =>
   validator('query', async (_, c) => {
@@ -281,7 +278,7 @@ export const validateQuery = (endpoint: any) =>
   });`);
 	}
 	if (needsParams) {
-		exports$1.push("validateParams");
+		exports.push("validateParams");
 		factories.push(`
 export const validateParams = (endpoint: any) =>
   validator('param', async (params, c) => {
@@ -305,8 +302,7 @@ ${factories.join("\n")}
 */
 function generateMinimalEndpointFile(analysis, endpointImport) {
 	const { exportName, features } = analysis;
-	const needsValidators = features.hasBodyValidation || features.hasQueryValidation || features.hasParamValidation;
-	const validatorImport = needsValidators ? generateValidatorImportsForEndpoint(analysis) : "";
+	const validatorImport = features.hasBodyValidation || features.hasQueryValidation || features.hasParamValidation ? generateValidatorImportsForEndpoint(analysis) : "";
 	const handler = generateMinimalHandler(analysis);
 	return `/**
  * Minimal endpoint: ${analysis.route} (${analysis.method})
@@ -331,8 +327,7 @@ ${handler}
 */
 function generateStandardEndpointFile(analysis, endpointImport) {
 	const { exportName, features } = analysis;
-	const needsValidators = features.hasBodyValidation || features.hasQueryValidation || features.hasParamValidation;
-	const validatorImport = needsValidators ? generateValidatorImportsForEndpoint(analysis) : "";
+	const validatorImport = features.hasBodyValidation || features.hasQueryValidation || features.hasParamValidation ? generateValidatorImportsForEndpoint(analysis) : "";
 	const eventsImport = features.hasEvents ? `import { publishConstructEvents } from '@geekmidas/constructs/endpoints';` : "";
 	const handler = generateStandardHandler(analysis);
 	return `/**
@@ -424,7 +419,7 @@ export function setupFullEndpoints(
 	}
 	const imports = tierEndpoints.map((a) => `import { setup${capitalize(a.exportName)} } from './${a.exportName}.js';`).join("\n");
 	if (tier === "minimal") {
-		const calls$1 = tierEndpoints.map((a) => `  setup${capitalize(a.exportName)}(app, logger);`).join("\n");
+		const calls = tierEndpoints.map((a) => `  setup${capitalize(a.exportName)}(app, logger);`).join("\n");
 		return `/**
  * Minimal-tier endpoint index (${tierEndpoints.length} endpoints)
  * Near-raw-Hono performance
@@ -437,12 +432,12 @@ export function setupMinimalEndpoints(
   app: Hono,
   logger: Logger,
 ): void {
-${calls$1}
+${calls}
 }
 `;
 	}
 	if (tier === "standard") {
-		const calls$1 = tierEndpoints.map((a) => `  setup${capitalize(a.exportName)}(app, serviceDiscovery, logger);`).join("\n");
+		const calls = tierEndpoints.map((a) => `  setup${capitalize(a.exportName)}(app, serviceDiscovery, logger);`).join("\n");
 		return `/**
  * Standard-tier endpoint index (${tierEndpoints.length} endpoints)
  * Auth and/or services enabled
@@ -457,7 +452,7 @@ export function setupStandardEndpoints(
   serviceDiscovery: ServiceDiscovery<any, any>,
   logger: Logger,
 ): void {
-${calls$1}
+${calls}
 }
 `;
 	}
@@ -527,9 +522,7 @@ function generateEndpointFilesNested(analyses, endpointImports) {
 			case "standard":
 				files[fileName] = generateStandardEndpointFile(analysis, endpointImport);
 				break;
-			case "full":
-				files[fileName] = generateFullEndpointFile(analysis, endpointImport);
-				break;
+			case "full": files[fileName] = generateFullEndpointFile(analysis, endpointImport);
 		}
 	}
 	return files;
@@ -586,7 +579,6 @@ export async function setupEndpoints(
 }
 `;
 }
-
 //#endregion
 //#region src/generators/EndpointGenerator.ts
 /**
@@ -603,24 +595,21 @@ export async function setupEndpoints(
 *
 * Falls back to the configured paths for an app that declares no surface.
 */
-function runtimeFor(context, fromDir) {
-	const module$1 = context.surface?.module;
-	if (module$1) {
-		const specifier = importSpecifier(fromDir, module$1.specifier);
+function runtimeFor(context, fromDir, owner) {
+	const module = owner ? context.owners?.[owner] ?? context.surface?.module : context.surface?.module;
+	if (module) {
+		const specifier = importSpecifier(fromDir, module.specifier);
 		return {
-			imports: `import { ${module$1.exportName} as __surface } from '${specifier}';`,
+			imports: `import { ${module.exportName} as __surface } from '${specifier}';`,
 			bindings: [
-				"// What this surface was declared with. Objects, not module paths:",
-				"// the entry imports the surface, so there is nothing to print.",
+				"// What this construct was declared with. Objects, not module paths:",
+				"// the entry imports the owner, so there is nothing to print.",
 				"const envParser = __surface.envParser;",
 				"const logger = __surface.logger;"
 			].join("\n")
 		};
 	}
-	return {
-		imports: [`import ${context.envParserImportPattern} from '${importSpecifier(fromDir, context.envParserPath)}';`, `import ${context.loggerImportPattern} from '${importSpecifier(fromDir, context.loggerPath)}';`].join("\n"),
-		bindings: ""
-	};
+	throw new Error(`No owner to take a logger and an environment parser from${owner ? ` for "${owner}"` : ""}. Build it from a \`RestApi\` or a \`Worker\`.`);
 }
 /** A relative specifier ESM will accept: always prefixed, never bare. */
 function importSpecifier(fromDir, target) {
@@ -679,7 +668,7 @@ function corsFor(surface) {
 }
 var EndpointGenerator = class extends require_discover.ConstructGenerator {
 	isConstruct(value) {
-		return __geekmidas_constructs_endpoints.Endpoint.isEndpoint(value);
+		return _geekmidas_constructs_endpoints.Endpoint.isEndpoint(value);
 	}
 	async build(context, constructs, outputDir, options) {
 		const provider = options?.provider || "aws-apigatewayv2";
@@ -735,8 +724,7 @@ var EndpointGenerator = class extends require_discover.ConstructGenerator {
 	async generateHandlerFile(outputDir, sourceFile, exportName, provider, _endpoint, context) {
 		const handlerFileName = `${exportName}.ts`;
 		const handlerPath = (0, node_path.join)(outputDir, handlerFileName);
-		const relativePath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile);
-		const importPath = relativePath.replace(/\.ts$/, ".js");
+		const importPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile).replace(/\.ts$/, ".js");
 		let content;
 		switch (provider) {
 			case "aws-apigatewayv1":
@@ -754,16 +742,14 @@ var EndpointGenerator = class extends require_discover.ConstructGenerator {
 		return handlerPath;
 	}
 	async generateEndpointsFile(outputDir, endpoints, context) {
-		const endpointsFileName = "endpoints.ts";
-		const endpointsPath = (0, node_path.join)(outputDir, endpointsFileName);
+		const endpointsPath = (0, node_path.join)(outputDir, "endpoints.ts");
 		const importsByFile = /* @__PURE__ */ new Map();
 		for (const { path, key } of endpoints) {
-			const relativePath = (0, node_path.relative)((0, node_path.dirname)(endpointsPath), path.relative);
-			const importPath = relativePath.replace(/\.ts$/, ".js");
+			const importPath = (0, node_path.relative)((0, node_path.dirname)(endpointsPath), path.relative).replace(/\.ts$/, ".js");
 			if (!importsByFile.has(importPath)) importsByFile.set(importPath, []);
 			importsByFile.get(importPath)?.push(key);
 		}
-		const endpointImports = Array.from(importsByFile.entries()).map(([importPath, exports$1]) => `import { ${exports$1.join(", ")} } from '${importPath}';`).join("\n");
+		const endpointImports = Array.from(importsByFile.entries()).map(([importPath, exports]) => `import { ${exports.join(", ")} } from '${importPath}';`).join("\n");
 		const allExportNames = endpoints.map(({ key }) => key);
 		if (context.production?.enabled && context.production.optimizedHandlers) return this.generateOptimizedEndpointsFile(endpointsPath, endpoints, endpointImports, allExportNames);
 		const content = `import type { EnvironmentParser } from '@geekmidas/envkit';
@@ -825,11 +811,9 @@ export async function setupEndpoints(
 		const analyses = endpoints.map(({ key, construct }) => analyzeEndpoint(construct, key));
 		const endpointImports = endpoints.map(({ key, path }) => {
 			const tierDir = (0, node_path.join)(endpointsDir, "standard");
-			const relativePath = (0, node_path.relative)(tierDir, path.relative);
-			const importPath = relativePath.replace(/\.ts$/, ".js");
 			return {
 				exportName: key,
-				importPath
+				importPath: (0, node_path.relative)(tierDir, path.relative).replace(/\.ts$/, ".js")
 			};
 		});
 		const summary = summarizeAnalysis(analyses);
@@ -851,8 +835,7 @@ export async function setupEndpoints(
 	}
 	async generateAppFile(outputDir, context) {
 		if (context.production?.enabled) return this.generateProductionAppFile(outputDir, context);
-		const appFileName = "app.ts";
-		const appPath = (0, node_path.join)(outputDir, appFileName);
+		const appPath = (0, node_path.join)(outputDir, "app.ts");
 		const runtime = runtimeFor(context, (0, node_path.dirname)(appPath));
 		const telescopeEnabled = context.telescope?.enabled;
 		const telescopeWebSocketEnabled = context.telescope?.websocket;
@@ -862,32 +845,35 @@ export async function setupEndpoints(
 		const studioFromDatabase = !usesExternalStudio && !!context.studio?.database;
 		const telescopeFromSurface = !!context.surface?.module && !usesExternalTelescope;
 		let telescopeImports = "";
-		if (telescopeEnabled) if (telescopeFromSurface) telescopeImports = "import { createMiddleware, createUI } from '@geekmidas/telescope/hono';";
-		else if (usesExternalTelescope) {
-			const relativeTelescopePath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.telescope?.telescopePath);
-			telescopeImports = `import ${context.telescope?.telescopeImportPattern} from '${relativeTelescopePath}';
+		if (telescopeEnabled) {
+			if (telescopeFromSurface) telescopeImports = "import { createMiddleware, createUI } from '@geekmidas/telescope/hono';";
+			else if (usesExternalTelescope) {
+				const relativeTelescopePath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.telescope?.telescopePath);
+				telescopeImports = `import ${context.telescope?.telescopeImportPattern} from '${relativeTelescopePath}';
 import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`;
-		} else telescopeImports = `import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+			} else telescopeImports = `import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
 import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`;
+		}
 		let studioImports = "";
-		if (studioEnabled) if (usesExternalStudio) {
-			const relativeStudioPath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.studio?.studioPath);
-			studioImports = `import ${context.studio?.studioImportPattern} from '${relativeStudioPath}';
+		if (studioEnabled) {
+			if (usesExternalStudio) {
+				const relativeStudioPath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.studio?.studioPath);
+				studioImports = `import ${context.studio?.studioImportPattern} from '${relativeStudioPath}';
 import { createStudioApp } from '@geekmidas/studio/server/hono';`;
-		} else if (studioFromDatabase) {
-			const dbSpecifier = importSpecifier((0, node_path.dirname)(appPath), context.studio.database.specifier);
-			studioImports = `import { snifferContext } from '@geekmidas/constructs';
+			} else if (studioFromDatabase) {
+				const dbSpecifier = importSpecifier((0, node_path.dirname)(appPath), context.studio.database.specifier);
+				studioImports = `import { snifferContext } from '@geekmidas/constructs';
 import { Direction, InMemoryMonitoringStorage, Studio } from '@geekmidas/studio';
 import { ${context.studio.database.exportName} as __studioDb } from '${dbSpecifier}';
 import { createStudioApp } from '@geekmidas/studio/server/hono';`;
-		} else studioImports = "";
+			} else studioImports = "";
+		}
 		const cors = corsFor(context.surface);
 		let hooksImports = "";
 		let beforeSetupCall = "";
 		let afterSetupCall = "";
 		if (context.hooks?.serverHooksPath) {
-			const relativeHooksPath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.hooks.serverHooksPath);
-			hooksImports = `import * as serverHooks from '${relativeHooksPath}';`;
+			hooksImports = `import * as serverHooks from '${(0, node_path.relative)((0, node_path.dirname)(appPath), context.hooks.serverHooksPath)}';`;
 			beforeSetupCall = `
   // Call beforeSetup hook if defined
   if (typeof serverHooks.beforeSetup === 'function') {
@@ -933,7 +919,8 @@ import { createStudioApp } from '@geekmidas/studio/server/hono';`;
   }
 ` : "";
 		let telescopeSetup = "";
-		if (telescopeEnabled) if (telescopeFromSurface || usesExternalTelescope) telescopeSetup = `
+		if (telescopeEnabled) {
+			if (telescopeFromSurface || usesExternalTelescope) telescopeSetup = `
 ${telescopeWebSocketSetupCode}
   // Add telescope middleware (before endpoints to capture all requests)
   honoApp.use('*', createMiddleware(telescope));
@@ -942,7 +929,7 @@ ${telescopeWebSocketSetupCode}
   const telescopeUI = createUI(telescope);
   honoApp.route('${context.telescope?.path}', telescopeUI);
 `;
-		else telescopeSetup = `
+			else telescopeSetup = `
   // Setup Telescope for debugging/monitoring
   const telescopeStorage = new InMemoryStorage({ maxEntries: ${context.telescope?.maxEntries} });
   const telescope = new Telescope({
@@ -960,6 +947,7 @@ ${telescopeWebSocketSetupCode}
   const telescopeUI = createUI(telescope);
   honoApp.route('${context.telescope?.path}', telescopeUI);
 `;
+		}
 		let studioSetup = "";
 		if (studioEnabled && studioFromDatabase) studioSetup = `
   // Studio, built from the declared database. The client comes from the
@@ -993,6 +981,7 @@ import type { Hono as HonoType } from 'hono';
 import { setupEndpoints } from './endpoints.js';
 import { setupSubscribers } from './subscribers.js';
 import { setupQueues } from './queues.js';
+import { setupCrons } from './crons.js';
 ${runtime.imports}
 ${telescopeImports}
 ${studioImports}
@@ -1080,6 +1069,12 @@ ${afterSetupCall}
         logger.error({ error }, 'Failed to start queue workers');
       });
 
+      // Schedule this app's crons. Caught like the others: a scheduler that
+      // cannot start is not a reason for the HTTP server not to.
+      await setupCrons(envParser, logger).catch((error) => {
+        logger.error({ error }, 'Failed to schedule crons');
+      });
+
       logger.info({ port }, 'Starting server');
 
       // Start HTTP server using provided serve function
@@ -1148,10 +1143,8 @@ export const handler = ${exportName};
 	* No dev tools (Telescope, Studio, WebSocket), includes health checks and graceful shutdown
 	*/
 	async generateProductionAppFile(outputDir, context) {
-		const appFileName = "app.ts";
-		const appPath = (0, node_path.join)(outputDir, appFileName);
-		const relativeLoggerPath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.loggerPath);
-		const relativeEnvParserPath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.envParserPath);
+		const appPath = (0, node_path.join)(outputDir, "app.ts");
+		const runtime = runtimeFor(context, (0, node_path.dirname)(appPath));
 		const production = context.production;
 		const healthCheckPath = production.healthCheck;
 		const enableGracefulShutdown = production.gracefulShutdown;
@@ -1162,8 +1155,7 @@ export const handler = ${exportName};
 		let beforeSetupCall = "";
 		let afterSetupCall = "";
 		if (context.hooks?.serverHooksPath) {
-			const relativeHooksPath = (0, node_path.relative)((0, node_path.dirname)(appPath), context.hooks.serverHooksPath);
-			hooksImports = `import * as serverHooks from '${relativeHooksPath}';`;
+			hooksImports = `import * as serverHooks from '${(0, node_path.relative)((0, node_path.dirname)(appPath), context.hooks.serverHooksPath)}';`;
 			beforeSetupCall = `
   // Call beforeSetup hook if defined
   if (typeof serverHooks.beforeSetup === 'function') {
@@ -1187,9 +1179,16 @@ export const handler = ${exportName};
       await setupQueues(envParser, logger).catch((error) => {
         logger.error({ error }, 'Failed to start queue workers');
       });
+
+      // Schedule this app's crons. Caught like the others: a scheduler that
+      // cannot start is not a reason for the HTTP server not to.
+      await setupCrons(envParser, logger).catch((error) => {
+        logger.error({ error }, 'Failed to schedule crons');
+      });
 ` : "";
 		const subscriberImport = includeSubscribers ? `import { setupSubscribers } from './subscribers.js';
-import { setupQueues } from './queues.js';` : "";
+import { setupQueues } from './queues.js';
+import { setupCrons } from './crons.js';` : "";
 		const gracefulShutdownCode = enableGracefulShutdown ? `
   // Graceful shutdown handling
   let isShuttingDown = false;
@@ -1205,7 +1204,6 @@ import { setupQueues } from './queues.js';` : "";
   process.on('SIGTERM', shutdown);
   process.on('SIGINT', shutdown);
 ` : "";
-		const endpointsImportPath = production.optimizedHandlers ? "./endpoints/index.js" : "./endpoints.js";
 		const content = `/**
  * Generated production server application
  *
@@ -1217,10 +1215,10 @@ import { setupQueues } from './queues.js';` : "";
  */
 import { Hono } from 'hono';
 import type { Hono as HonoType } from 'hono';
-import { setupEndpoints } from '${endpointsImportPath}';
+import { setupEndpoints } from '${production.optimizedHandlers ? "./endpoints/index.js" : "./endpoints.js"}';
 ${subscriberImport}
-import ${context.envParserImportPattern} from '${relativeEnvParserPath}';
-import ${context.loggerImportPattern} from '${relativeLoggerPath}';
+${runtime.imports}
+${runtime.bindings}
 ${hooksImports}
 ${cors.imports}
 ${context.storageDrivers?.imports ?? ""}
@@ -1284,7 +1282,7 @@ export default createApp;
 	*/
 	async generateProductionServerEntry(outputDir) {
 		const serverPath = (0, node_path.join)(outputDir, "server.ts");
-		const content = `#!/usr/bin/env node
+		await (0, node_fs_promises.writeFile)(serverPath, `#!/usr/bin/env node
 /**
  * Production server entry point
  * Generated by 'gkm build --provider server --production'
@@ -1300,11 +1298,9 @@ await start({
   port,
   serve: (app, port) => { serve({ fetch: app.fetch, port }); },
 });
-`;
-		await (0, node_fs_promises.writeFile)(serverPath, content);
+`);
 	}
 };
-
 //#endregion
 //#region src/generators/OpenApiTsGenerator.ts
 /**
@@ -1455,11 +1451,11 @@ var OpenApiTsGenerator = class {
 				}
 			}
 		}
-		const registrySchemas = await (0, __geekmidas_schema_conversion.getRegisteredZodJsonSchemas)();
+		const registrySchemas = await (0, _geekmidas_schema_conversion.getRegisteredZodJsonSchemas)();
 		for (const [rawName, rawSchema] of Object.entries(registrySchemas)) {
 			const defName = this.pascalCase(rawName);
 			if (collectedDefs.has(defName) || generatedNames.has(defName)) continue;
-			const { id: _id, $defs: _defs,...rest } = rawSchema;
+			const { id: _id, $defs: _defs, ...rest } = rawSchema;
 			collectedDefs.set(defName, rest);
 		}
 		for (const [defName, defSchema] of collectedDefs) if (!generatedNames.has(defName)) {
@@ -1475,7 +1471,7 @@ var OpenApiTsGenerator = class {
 	*/
 	async getSchemaName(schema, defaultName) {
 		try {
-			const metadata = await (0, __geekmidas_schema_conversion.getSchemaMetadata)(schema);
+			const metadata = await (0, _geekmidas_schema_conversion.getSchemaMetadata)(schema);
 			if (metadata?.id) return this.pascalCase(metadata.id);
 		} catch {}
 		return defaultName;
@@ -1495,27 +1491,29 @@ var OpenApiTsGenerator = class {
 	async schemaToInterfaceWithDefs(schema, name, collectedDefs) {
 		try {
 			const vendor = schema["~standard"]?.vendor;
-			if (!vendor || !(vendor in __geekmidas_schema_conversion.StandardSchemaJsonSchema)) return null;
-			const toJsonSchema = __geekmidas_schema_conversion.StandardSchemaJsonSchema[vendor];
+			if (!vendor || !(vendor in _geekmidas_schema_conversion.StandardSchemaJsonSchema)) return unknownType(name);
+			const toJsonSchema = _geekmidas_schema_conversion.StandardSchemaJsonSchema[vendor];
 			const jsonSchema = await toJsonSchema(schema);
-			if (!jsonSchema) return null;
+			if (!jsonSchema) return unknownType(name);
 			if (jsonSchema.$defs && typeof jsonSchema.$defs === "object") {
 				for (const [defName, defSchema] of Object.entries(jsonSchema.$defs)) if (!collectedDefs.has(defName)) {
-					const { id,...schemaWithoutId } = defSchema;
+					const { id, ...schemaWithoutId } = defSchema;
 					collectedDefs.set(defName, schemaWithoutId);
 				}
 			}
-			const { $defs,...schemaWithoutDefs } = jsonSchema;
+			const { $defs, ...schemaWithoutDefs } = jsonSchema;
+			const ref = schemaWithoutDefs.$ref;
+			if (ref && Object.keys(schemaWithoutDefs).every((k) => k === "$ref" || k === "$schema")) {
+				const target = ref.split("/").pop();
+				return target === name ? null : `export type ${name} = ${target};`;
+			}
 			return this.jsonSchemaToInterface(schemaWithoutDefs, name);
 		} catch {
-			return null;
+			return unknownType(name);
 		}
 	}
 	jsonSchemaToInterface(schema, name) {
-		if (schema.type !== "object" || !schema.properties) {
-			const typeStr = this.jsonSchemaTypeToTs(schema);
-			return `export type ${name} = ${typeStr};`;
-		}
+		if (schema.type !== "object" || !schema.properties) return `export type ${name} = ${this.jsonSchemaTypeToTs(schema)};`;
 		const props = [];
 		const required = new Set(schema.required || []);
 		for (const [propName, propSchema] of Object.entries(schema.properties)) {
@@ -1528,13 +1526,15 @@ var OpenApiTsGenerator = class {
 	}
 	jsonSchemaTypeToTs(schema) {
 		if (!schema) return "unknown";
-		if (schema.$ref) {
-			const refName = schema.$ref.split("/").pop() || "unknown";
-			return refName;
-		}
+		if (schema.$ref) return schema.$ref.split("/").pop() || "unknown";
+		if (schema.const !== void 0) return typeof schema.const === "string" ? `'${schema.const}'` : String(schema.const);
 		if (schema.anyOf) return schema.anyOf.map((s) => this.jsonSchemaTypeToTs(s)).join(" | ");
 		if (schema.oneOf) return schema.oneOf.map((s) => this.jsonSchemaTypeToTs(s)).join(" | ");
 		if (schema.allOf) return schema.allOf.map((s) => this.jsonSchemaTypeToTs(s)).join(" & ");
+		if (Array.isArray(schema.type)) return schema.type.map((type) => this.jsonSchemaTypeToTs({
+			...schema,
+			type
+		})).join(" | ");
 		switch (schema.type) {
 			case "string":
 				if (schema.enum) return schema.enum.map((e) => `'${e}'`).join(" | ");
@@ -1558,10 +1558,7 @@ var OpenApiTsGenerator = class {
 					}
 					return `{ ${props.join("; ")} }`;
 				}
-				if (schema.additionalProperties) {
-					const valueType = this.jsonSchemaTypeToTs(schema.additionalProperties);
-					return `Record<string, ${valueType}>`;
-				}
+				if (schema.additionalProperties) return `Record<string, ${this.jsonSchemaTypeToTs(schema.additionalProperties)}>`;
 				return "Record<string, unknown>";
 			default: return "unknown";
 		}
@@ -1582,10 +1579,7 @@ var OpenApiTsGenerator = class {
 			}
 			const firstWithParams = infos.find((i) => i.input?.params);
 			let paramsEntry = "";
-			if (firstWithParams?.input?.params) {
-				const paramsName = await this.getSchemaName(firstWithParams.input.params, `${this.getSchemaBaseName(firstWithParams)}Params`);
-				paramsEntry = `\n    parameters: {\n      path: ${paramsName};\n    };`;
-			}
+			if (firstWithParams?.input?.params) paramsEntry = `\n    parameters: {\n      path: ${await this.getSchemaName(firstWithParams.input.params, `${this.getSchemaBaseName(firstWithParams)}Params`)};\n    };`;
 			pathEntries.push(`  '${route}': {${paramsEntry}\n${methodEntries.join("\n")}\n  };`);
 		}
 		return `export interface paths {\n${pathEntries.join("\n")}\n}`;
@@ -1624,8 +1618,7 @@ var OpenApiTsGenerator = class {
 			return acc;
 		}, {});
 		const schemeNames = securitySchemes.map((s) => `'${s.name}'`).join(" | ");
-		const hasSecuritySchemes = schemeNames.length > 0;
-		const createApiSection = hasSecuritySchemes ? `
+		const createApiSection = schemeNames.length > 0 ? `
 // ============================================================
 // API Client Factory
 // ============================================================
@@ -1802,20 +1795,14 @@ ${createApiSection}
 `;
 	}
 };
-
-//#endregion
-//#region src/workspace/client-generator.ts
 /**
-* Normalize routes to an array of patterns.
-* Handles string, string[], and PartitionedRoutes (extracts paths).
-* @internal Exported for use in dev command
+* The declaration for a schema that cannot be converted — a vendor with no
+* converter, or one that fails. The paths interface names it either way, so
+* leaving it undeclared made the generated client fail to compile.
 */
-function normalizeRoutes(routes) {
-	if (!routes) return [];
-	if (require_discover.isPartitionedRoutes(routes)) return Array.isArray(routes.paths) ? routes.paths : [routes.paths];
-	return Array.isArray(routes) ? routes : [routes];
+function unknownType(name) {
+	return `export type ${name} = unknown;`;
 }
-
 //#endregion
 //#region src/openapi.ts
 /**
@@ -1823,6 +1810,16 @@ function normalizeRoutes(routes) {
 */
 const OPENAPI_OUTPUT_PATH = "./.gkm/openapi.ts";
 /**
+* Where a surface's generated client lands.
+*
+* Named from the surface, so `new RestApi('Webhooks')` writes
+* `.gkm/openapi/webhooks.ts` — the same kebab form that gives it its container
+* name and its `WEBHOOKS_URL`.
+*/
+function openApiPathFor(surfaceId) {
+	return `./.gkm/openapi/${(0, _geekmidas_manifest.kebabCase)(surfaceId)}.ts`;
+}
+/**
 * Resolve OpenAPI config from GkmConfig
 */
 function resolveOpenApiConfig(config) {
@@ -1841,33 +1838,65 @@ function resolveOpenApiConfig(config) {
 	};
 }
 /**
-* Generate OpenAPI spec from endpoints
-* @returns Object with output path and endpoint count, or null if disabled
+* Load endpoints from a glob, then generate.
+*
+* For the callers that have no endpoints in hand — `gkm openapi`, and `gkm dev`
+* regenerating on reload. The glob is the app's derived one — the conventional
+* directories under it — not a `routes` field anybody wrote.
 */
-async function generateOpenApi(config, options = {}) {
+async function generateOpenApiFrom(routes, options = {}) {
+	return generateOpenApi((await new EndpointGenerator().load(routes, void 0, options.bustCache)).map(({ construct }) => construct), options);
+}
+/**
+* Generate an OpenAPI spec for each surface these endpoints name.
+*
+* Takes the endpoints, not a glob to find them with. The build has already
+* loaded every one of them to generate handlers, so globbing again was a second
+* discovery pass over the same files — and the reason this function needed a
+* `routes` to be told where to look, which is how a retired config field stayed
+* load-bearing.
+*
+* @returns What was written, or null if disabled or there were none
+*/
+async function generateOpenApi(endpoints, options = {}) {
 	const logger = options.silent ? { log: () => {} } : console;
-	const openApiConfig = resolveOpenApiConfig(config);
+	const openApiConfig = resolveOpenApiConfig({ openapi: options.openapi });
 	if (!openApiConfig.enabled) return null;
-	const endpointGenerator = new EndpointGenerator();
-	const loadedEndpoints = await endpointGenerator.load(config.routes, void 0, options.bustCache);
-	if (loadedEndpoints.length === 0) {
+	if (endpoints.length === 0) {
 		logger.log("No valid endpoints found for OpenAPI generation");
 		return null;
 	}
-	const endpoints = loadedEndpoints.map(({ construct }) => construct);
-	const outputPath = (0, node_path.join)(process.cwd(), OPENAPI_OUTPUT_PATH);
-	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(outputPath), { recursive: true });
+	const bySurface = /* @__PURE__ */ new Map();
+	for (const endpoint of endpoints) {
+		const owner = endpoint.owner ?? endpoint.surface?.id;
+		if (!owner) continue;
+		const existing = bySurface.get(owner);
+		if (existing) existing.push(endpoint);
+		else bySurface.set(owner, [endpoint]);
+	}
+	if (bySurface.size === 0) {
+		logger.log("No endpoints named a surface, so no OpenAPI was generated");
+		return null;
+	}
 	const tsGenerator = new OpenApiTsGenerator();
-	const tsContent = await tsGenerator.generate(endpoints, {
-		title: openApiConfig.title,
-		version: openApiConfig.version,
-		description: openApiConfig.description
-	});
-	await (0, node_fs_promises.writeFile)(outputPath, tsContent);
-	logger.log(`📄 OpenAPI client generated: ${OPENAPI_OUTPUT_PATH}`);
+	const written = [];
+	for (const [surfaceId, surfaceEndpoints] of bySurface) {
+		const relative = openApiPathFor(surfaceId);
+		const outputPath = (0, node_path.join)(process.cwd(), relative);
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(outputPath), { recursive: true });
+		const tsContent = await tsGenerator.generate(surfaceEndpoints, {
+			title: openApiConfig.title ?? surfaceId,
+			version: openApiConfig.version,
+			description: openApiConfig.description
+		});
+		await (0, node_fs_promises.writeFile)(outputPath, tsContent);
+		written.push(relative);
+		logger.log(`📄 OpenAPI client generated: ${relative} (${surfaceEndpoints.length} endpoints)`);
+	}
 	return {
-		outputPath,
-		endpointCount: loadedEndpoints.length
+		outputPath: (0, node_path.join)(process.cwd(), written[0]),
+		outputPaths: written.map((r) => (0, node_path.join)(process.cwd(), r)),
+		endpointCount: endpoints.length
 	};
 }
 async function openapiCommand(options = {}) {
@@ -1877,12 +1906,12 @@ async function openapiCommand(options = {}) {
 		if (loadedConfig.type === "single") {
 			const config = loadedConfig.raw;
 			if (!config.openapi) config.openapi = { enabled: true };
-			const result = await generateOpenApi(config);
+			const result = await generateOpenApiFrom(config.constructs, { openapi: config.openapi });
 			if (result) logger.log(`Found ${result.endpointCount} endpoints`);
 		} else {
 			const { workspace } = loadedConfig;
 			const workspaceRoot = workspace.root;
-			const backendApps = Object.entries(workspace.apps).filter(([_, app]) => app.type === "backend" && app.routes !== void 0 && app.openapi !== false && (typeof app.openapi !== "object" || app.openapi.enabled !== false));
+			const backendApps = Object.entries(workspace.apps).filter(([_, app]) => app.type === "backend" && app.openapi !== false && (typeof app.openapi !== "object" || app.openapi.enabled !== false));
 			if (backendApps.length === 0) {
 				logger.log("No backend apps with OpenAPI enabled found");
 				return;
@@ -1896,8 +1925,12 @@ async function openapiCommand(options = {}) {
 				return;
 			}
 			for (const [appName, app] of backendApps) {
-				if (app.type !== "backend" || !app.routes) continue;
 				const appPath = (0, node_path.join)(workspaceRoot, app.path);
+				if ((0, node_path.resolve)(appPath) === (0, node_path.resolve)(workspaceRoot)) {
+					const result = await generateOpenApiForApp(workspaceRoot, appName, app, false);
+					if (result) logger.log(`Found ${result.endpointCount} endpoints`);
+					continue;
+				}
 				await runOpenApiInSubprocess(appPath, appName);
 			}
 		}
@@ -1910,18 +1943,13 @@ async function openapiCommand(options = {}) {
 * Runs in-process. The caller is responsible for ensuring `process.cwd()`
 * is the app's directory so tsx loads the app's tsconfig path aliases.
 */
-async function generateOpenApiForApp(workspaceRoot, _appName, app) {
-	if (app.type !== "backend" || !app.routes) return null;
+async function generateOpenApiForApp(workspaceRoot, _appName, app, silent = true) {
+	if (app.type !== "backend") return null;
 	const appPath = (0, node_path.join)(workspaceRoot, app.path);
-	const routes = normalizeRoutes(app.routes);
-	const routesGlob = routes.map((r) => (0, node_path.join)(appPath, r));
-	const gkmConfig = {
-		routes: routesGlob,
-		envParser: app.envParser || "",
-		logger: app.logger || "",
-		openapi: app.openapi
-	};
-	return generateOpenApi(gkmConfig, { silent: true });
+	return generateOpenApiFrom([(0, node_path.join)(appPath, "**/*.ts")], {
+		openapi: app.openapi ?? { enabled: true },
+		silent
+	});
 }
 /**
 * Resolve the gkm bin path. Tests can override via `GKM_BIN_PATH` env var
@@ -1953,46 +1981,58 @@ async function runOpenApiInSubprocess(appCwd, appName) {
 		child.on("error", reject);
 		child.on("close", (code) => {
 			if (code === 0) resolve();
-			else reject(new Error(`OpenAPI generation for app "${appName}" exited with code ${code}`));
+			else reject(/* @__PURE__ */ new Error(`OpenAPI generation for app "${appName}" exited with code ${code}`));
 		});
 	});
 }
-
 //#endregion
-Object.defineProperty(exports, 'EndpointGenerator', {
-  enumerable: true,
-  get: function () {
-    return EndpointGenerator;
-  }
+Object.defineProperty(exports, "EndpointGenerator", {
+	enumerable: true,
+	get: function() {
+		return EndpointGenerator;
+	}
 });
-Object.defineProperty(exports, 'OPENAPI_OUTPUT_PATH', {
-  enumerable: true,
-  get: function () {
-    return OPENAPI_OUTPUT_PATH;
-  }
+Object.defineProperty(exports, "OPENAPI_OUTPUT_PATH", {
+	enumerable: true,
+	get: function() {
+		return OPENAPI_OUTPUT_PATH;
+	}
 });
-Object.defineProperty(exports, 'generateOpenApi', {
-  enumerable: true,
-  get: function () {
-    return generateOpenApi;
-  }
+Object.defineProperty(exports, "generateOpenApi", {
+	enumerable: true,
+	get: function() {
+		return generateOpenApi;
+	}
 });
-Object.defineProperty(exports, 'normalizeRoutes', {
-  enumerable: true,
-  get: function () {
-    return normalizeRoutes;
-  }
+Object.defineProperty(exports, "generateOpenApiFrom", {
+	enumerable: true,
+	get: function() {
+		return generateOpenApiFrom;
+	}
 });
-Object.defineProperty(exports, 'openapiCommand', {
-  enumerable: true,
-  get: function () {
-    return openapiCommand;
-  }
+Object.defineProperty(exports, "openApiPathFor", {
+	enumerable: true,
+	get: function() {
+		return openApiPathFor;
+	}
 });
-Object.defineProperty(exports, 'resolveOpenApiConfig', {
-  enumerable: true,
-  get: function () {
-    return resolveOpenApiConfig;
-  }
+Object.defineProperty(exports, "openapiCommand", {
+	enumerable: true,
+	get: function() {
+		return openapiCommand;
+	}
+});
+Object.defineProperty(exports, "resolveOpenApiConfig", {
+	enumerable: true,
+	get: function() {
+		return resolveOpenApiConfig;
+	}
+});
+Object.defineProperty(exports, "runtimeFor", {
+	enumerable: true,
+	get: function() {
+		return runtimeFor;
+	}
 });
-//# sourceMappingURL=openapi-c9bpieI5.cjs.map
+
+//# sourceMappingURL=openapi-B8bu_OXN.cjs.map