@geekmidas/cli 10.0.0-alpha.6 → 10.0.0-alpha.61

package/dist/{openapi-D-dx9Akj.cjs → OpenApiTsGenerator-BSrgw7B0.cjs}

@@ -1,21 +1,16 @@
-const require_chunk = require('./chunk-CUT6urMc.cjs');
-const require_discover = require('./discover-DTmFeloL.cjs');
-const require_config = require('./config-CNz5KaSR.cjs');
-const node_path = require_chunk.__toESM(require("node:path"));
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-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-Bc-4eA_p.cjs");
+let node_path = require("node:path");
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let _geekmidas_constructs_endpoints = require("@geekmidas/constructs/endpoints");
+let _geekmidas_schema_conversion = require("@geekmidas/schema/conversion");
 //#region src/build/endpoint-analyzer.ts
 /**
 * Analyze an endpoint to extract its features
 */
 function analyzeEndpointFeatures(endpoint) {
 	return {
-		hasAuth: !!endpoint.authorizer,
+		hasAuth: !!endpoint.authorizer || endpoint.hasSession === true,
 		hasServices: endpoint.services.length > 0,
 		hasDatabase: !!endpoint.databaseService,
 		hasBodyValidation: !!endpoint.input?.body,
@@ -85,7 +80,6 @@ function summarizeAnalysis(analyses) {
 		byFeature
 	};
 }
-
 //#endregion
 //#region src/build/handler-templates.ts
 /**
@@ -107,8 +101,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(
@@ -256,10 +249,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) => {
@@ -270,7 +263,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) => {
@@ -282,7 +275,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) => {
@@ -306,8 +299,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})
@@ -332,8 +324,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 `/**
@@ -425,7 +416,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
@@ -438,12 +429,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
@@ -458,7 +449,7 @@ export function setupStandardEndpoints(
   serviceDiscovery: ServiceDiscovery<any, any>,
   logger: Logger,
 ): void {
-${calls$1}
+${calls}
 }
 `;
 	}
@@ -528,9 +519,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;
@@ -587,7 +576,142 @@ export async function setupEndpoints(
 }
 `;
 }
+//#endregion
+//#region src/generators/telemetry.ts
+/**
+* Every package `@geekmidas/telescope/instrumentation` loads at runtime.
+*
+* All of them, rather than one as a proxy: the production bundle follows each
+* import, and a single missing one fails the build rather than the telemetry.
+*/
+const TELEMETRY_PACKAGES = [
+	"@opentelemetry/api",
+	"@opentelemetry/auto-instrumentations-node",
+	"@opentelemetry/exporter-logs-otlp-http",
+	"@opentelemetry/exporter-trace-otlp-http",
+	"@opentelemetry/instrumentation-pino",
+	"@opentelemetry/resources",
+	"@opentelemetry/sdk-logs",
+	"@opentelemetry/sdk-node",
+	"@opentelemetry/sdk-trace-base",
+	"@opentelemetry/sdk-trace-node",
+	"@opentelemetry/semantic-conventions"
+];
+/**
+* The directory of `name` as `node_modules` lookup finds it from `fromDir`,
+* symlinks resolved — or undefined.
+*
+* The directory walk alone, not `require.resolve`: that also searches
+* `NODE_PATH`, which a package manager's bin shim sets to its own store, so a
+* `gkm build` run through one would find packages the app never installed —
+* and the bundler, which does not look there, would then fail on them.
+*/
+function packageDir(fromDir, name) {
+	for (let dir = (0, node_path.resolve)(fromDir);; dir = (0, node_path.dirname)(dir)) {
+		const candidate = (0, node_path.join)(dir, "node_modules", name);
+		if ((0, node_fs.existsSync)((0, node_path.join)(candidate, "package.json"))) return (0, node_fs.realpathSync)(candidate);
+		if ((0, node_path.dirname)(dir) === dir) return void 0;
+	}
+}
+/**
+* Whether the telemetry packages resolve the way the bundler will resolve them:
+* telescope from the app, and the OpenTelemetry packages from telescope —
+* where a peer is linked under pnpm, which need not be where the app sees it.
+*/
+function telemetryResolvesFrom(appRoot) {
+	const telescope = packageDir(appRoot, "@geekmidas/telescope");
+	if (!telescope) return false;
+	return TELEMETRY_PACKAGES.every((pkg) => packageDir(telescope, pkg));
+}
+/** The telemetry half of a build context. */
+function telemetryFor(options) {
+	return {
+		serviceName: options.surfaceId ?? (0, node_path.basename)(options.appRoot),
+		...options.workspaceName && { serviceNamespace: options.workspaceName },
+		available: telemetryResolvesFrom(options.appRoot)
+	};
+}
+const HEADER = `/**
+ * Generated by 'gkm build --production'.
+ *
+ * Starts OpenTelemetry when OTEL_EXPORTER_OTLP_ENDPOINT names a collector, and
+ * does nothing otherwise: without it, the telemetry packages are not loaded.
+ * The standard OTEL_* variables (OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG,
+ * OTEL_EXPORTER_OTLP_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME)
+ * configure the rest.
+ */
+
+/** Telemetry was asked for and cannot start. The server runs without it. */
+export class TelemetryUnavailable extends Error {
+  constructor(readonly reason: string, options?: { cause?: unknown }) {
+    super(
+      \`OTEL_EXPORTER_OTLP_ENDPOINT is set, but \${reason} This server exports no traces or logs until that is fixed.\`,
+      options,
+    );
+    this.name = 'TelemetryUnavailable';
+  }
+}
+`;
+/**
+* The entry's `telemetry.ts`: a `startTelemetry()` the server awaits before it
+* imports the app, so the libraries the app loads are instrumented.
+*
+* Failing to start telemetry warns (a named `TelemetryUnavailable`, through
+* `process.emitWarning`) and never stops the server: an outage in observability
+* is not a reason to have an outage in the service.
+*/
+function generateTelemetryModule(telemetry) {
+	if (!telemetry?.available) return `${HEADER}
+export async function startTelemetry(): Promise<void> {
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return;
+
+  process.emitWarning(
+    new TelemetryUnavailable(
+      'this server was built without @geekmidas/telescope and the @opentelemetry packages it needs. Add them to the app and rebuild.',
+    ),
+  );
+}
+`;
+	const options = [
+		`serviceName: ${JSON.stringify(telemetry.serviceName)},`,
+		...telemetry.serviceNamespace ? [`serviceNamespace: ${JSON.stringify(telemetry.serviceNamespace)},`] : [],
+		"deploymentEnvironment: process.env.STAGE,",
+		"handleSignals: false,"
+	];
+	return `${HEADER}
+export async function startTelemetry(): Promise<void> {
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return;
+
+  let instrumentation;
+  try {
+    instrumentation = await import('@geekmidas/telescope/instrumentation');
+  } catch (cause) {
+    process.emitWarning(
+      new TelemetryUnavailable(
+        '@geekmidas/telescope/instrumentation or an @opentelemetry package it needs could not be loaded. Install them in the app and rebuild.',
+        { cause },
+      ),
+    );
+    return;
+  }
+
+  instrumentation.setupTelemetry({
+    ${options.join("\n    ")}
+  });
 
+  // Flush what is buffered when the process is told to stop. When nothing
+  // else handles the signal, re-raise it once flushed, so the process still
+  // stops the way it would have without this listener.
+  for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+    process.once(signal, () => {
+      void instrumentation.flushTelemetry().finally(() => {
+        if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+      });
+    });
+  }
+}
+`;
+}
 //#endregion
 //#region src/generators/EndpointGenerator.ts
 /**
@@ -605,11 +729,11 @@ export async function setupEndpoints(
 * Falls back to the configured paths for an app that declares no surface.
 */
 function runtimeFor(context, fromDir, owner) {
-	const module$1 = owner ? context.owners?.[owner] ?? context.surface?.module : context.surface?.module;
-	if (module$1) {
-		const specifier = importSpecifier(fromDir, module$1.specifier);
+	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 construct was declared with. Objects, not module paths:",
 				"// the entry imports the owner, so there is nothing to print.",
@@ -677,48 +801,35 @@ 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";
+		const target = options?.target ?? "aws";
+		const root = options?.root ?? process.cwd();
 		const enableOpenApi = options?.enableOpenApi || false;
 		const logger = console;
 		const routes = [];
 		if (constructs.length === 0) return routes;
-		if (provider === "server") {
+		if (target === "server") {
 			await this.generateEndpointsFile(outputDir, constructs, context);
 			const appFile = await this.generateAppFile(outputDir, context);
 			routes.push({
 				path: "*",
 				method: "ALL",
-				handler: (0, node_path.relative)(process.cwd(), appFile),
+				handler: (0, node_path.relative)(root, appFile),
 				authorizer: "none"
 			});
 			logger.log(`Generated server with ${constructs.length} endpoints${enableOpenApi ? " (OpenAPI enabled)" : ""}`);
-		} else if (provider === "aws-lambda") {
-			const routesDir = (0, node_path.join)(outputDir, "routes");
-			await (0, node_fs_promises.mkdir)(routesDir, { recursive: true });
-			for (const { key, construct, path } of constructs) {
-				const handlerFile = await this.generateHandlerFile(routesDir, path.relative, key, "aws-apigatewayv2", construct, context);
-				const routeInfo = {
-					path: construct._path,
-					method: construct.method,
-					handler: (0, node_path.relative)(process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
-					timeout: construct.timeout,
-					memorySize: construct.memorySize,
-					environment: await construct.getEnvironment({ markOptional: context.markOptional }),
-					dependencies: construct.constructs,
-					authorizer: construct.authorizer?.name ?? "none"
-				};
-				routes.push(routeInfo);
-				logger.log(`Generated handler for ${routeInfo.method} ${routeInfo.path}`);
-			}
-		} else for (const { key, construct, path } of constructs) {
-			const handlerFile = await this.generateHandlerFile(outputDir, path.relative, key, provider, construct, context);
+			return routes;
+		}
+		const routesDir = (0, node_path.join)(outputDir, "routes");
+		await (0, node_fs_promises.mkdir)(routesDir, { recursive: true });
+		for (const { key, construct, path } of constructs) {
+			const handlerFile = await this.generateHandlerFile(routesDir, path.relative, key, context);
 			const routeInfo = {
 				path: construct._path,
 				method: construct.method,
-				handler: (0, node_path.relative)(process.cwd(), handlerFile).replace(/\.ts$/, ".handler"),
+				handler: (0, node_path.relative)(root, handlerFile).replace(/\.ts$/, ".handler"),
 				timeout: construct.timeout,
 				memorySize: construct.memorySize,
 				environment: await construct.getEnvironment({ markOptional: context.markOptional }),
@@ -730,38 +841,21 @@ var EndpointGenerator = class extends require_discover.ConstructGenerator {
 		}
 		return routes;
 	}
-	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");
-		let content;
-		switch (provider) {
-			case "aws-apigatewayv1":
-				content = this.generateAWSApiGatewayV1Handler(importPath, exportName, context.storageDrivers);
-				break;
-			case "aws-apigatewayv2":
-				content = this.generateAWSApiGatewayV2Handler(importPath, exportName, context.storageDrivers);
-				break;
-			case "server":
-				content = this.generateServerHandler(importPath, exportName);
-				break;
-			default: throw new Error(`Unsupported provider: ${provider}`);
-		}
-		await (0, node_fs_promises.writeFile)(handlerPath, content);
+	async generateHandlerFile(outputDir, sourceFile, exportName, context) {
+		const handlerPath = (0, node_path.join)(outputDir, `${exportName}.ts`);
+		const importPath = (0, node_path.relative)((0, node_path.dirname)(handlerPath), sourceFile).replace(/\.ts$/, ".js");
+		await (0, node_fs_promises.writeFile)(handlerPath, this.generateAWSApiGatewayV2Handler(importPath, exportName, context.storageDrivers));
 		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';
@@ -772,7 +866,7 @@ import { ServiceDiscovery } from '@geekmidas/services';
 import type { Hono } from 'hono';
 ${endpointImports}
 
-export const endpoints: Endpoint<any, any, any, any, any, any, any, any, any, any, any, any, any, any>[] = [
+export const endpoints: Endpoint<any, any, any, any, any, any, any, any, any, any, any, any>[] = [
   ${allExportNames.join(",\n  ")}
 ];
 
@@ -823,11 +917,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);
@@ -849,43 +941,33 @@ 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;
 		const usesExternalTelescope = !!context.telescope?.telescopePath;
-		const studioEnabled = context.studio?.enabled;
-		const usesExternalStudio = !!context.studio?.studioPath;
-		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}';
-import { createMiddleware, createUI } from '@geekmidas/telescope/hono';`;
-		} 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}';
-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';
-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 = "";
+		if (telescopeEnabled) {
+			if (telescopeFromSurface) telescopeImports = `import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+import { createApi, createMiddleware } 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 { createApi, createMiddleware } from '@geekmidas/telescope/hono';`;
+			} else telescopeImports = `import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+import { createApi, createMiddleware } from '@geekmidas/telescope/hono';`;
+		}
+		const databaseApi = context.databaseApi;
+		const databaseApiImports = databaseApi ? `import { snifferContext } from '@geekmidas/constructs';
+import { createIntrospectionHandler } from '@geekmidas/db/introspect';
+import { ${databaseApi.database.exportName} as __introspectedDb } from '${importSpecifier((0, node_path.dirname)(appPath), databaseApi.database.specifier)}';` : "";
 		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') {
@@ -931,16 +1013,17 @@ 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));
 
-  // Mount telescope UI
-  const telescopeUI = createUI(telescope);
-  honoApp.route('${context.telescope?.path}', telescopeUI);
+  // Mount Telescope's JSON API
+  const telescopeApi = createApi(telescope);
+  honoApp.route('${context.telescope?.path}', telescopeApi);
 `;
-		else telescopeSetup = `
+			else telescopeSetup = `
   // Setup Telescope for debugging/monitoring
   const telescopeStorage = new InMemoryStorage({ maxEntries: ${context.telescope?.maxEntries} });
   const telescope = new Telescope({
@@ -954,31 +1037,21 @@ ${telescopeWebSocketSetupCode}
   // Add telescope middleware (before endpoints to capture all requests)
   honoApp.use('*', createMiddleware(telescope));
 
-  // Mount telescope UI
-  const telescopeUI = createUI(telescope);
-  honoApp.route('${context.telescope?.path}', telescopeUI);
+  // Mount Telescope's JSON API
+  const telescopeApi = createApi(telescope);
+  honoApp.route('${context.telescope?.path}', telescopeApi);
 `;
-		let studioSetup = "";
-		if (studioEnabled && studioFromDatabase) studioSetup = `
-  // Studio, built from the declared database. The client comes from the
-  // construct, so what you inspect is by definition what the handlers write to.
-  const studio = new Studio({
-    monitoring: { storage: new InMemoryMonitoringStorage({ maxEntries: 100 }) },
-    data: {
-      db: await __studioDb.service.register({ envParser, context: snifferContext }),
-      cursor: { field: 'id', direction: Direction.Desc },
-    },
-    enabled: true,
+		}
+		const databaseApiSetup = databaseApi ? `
+  // The database's structure and rows as JSON, read-only, for whatever tool
+  // the developer points at it. Dev only: it answers anyone who can reach the
+  // port.
+  const databaseApi = createIntrospectionHandler({
+    db: await __introspectedDb.service.register({ envParser, context: snifferContext }),
+    basePath: '${databaseApi.path}',
   });
-
-  const studioApp = createStudioApp(studio);
-  honoApp.route('${context.studio?.path}', studioApp);
-`;
-		else if (studioEnabled && usesExternalStudio) studioSetup = `
-  // Mount Studio data browser UI
-  const studioApp = createStudioApp(studio);
-  honoApp.route('${context.studio?.path}', studioApp);
-`;
+  honoApp.all('${databaseApi.path}/*', (c) => databaseApi(c.req.raw));
+` : "";
 		const content = `/**
  * Generated server application
  *
@@ -994,24 +1067,37 @@ import { setupQueues } from './queues.js';
 import { setupCrons } from './crons.js';
 ${runtime.imports}
 ${telescopeImports}
-${studioImports}
+${databaseApiImports}
 ${hooksImports}
 ${cors.imports}
 ${context.storageDrivers?.imports ?? ""}
 
 ${runtime.bindings}
-${telescopeFromSurface ? "const telescope = __surface.telescope;" : ""}
+${telescopeEnabled && telescopeFromSurface ? `// The surface's own Telescope, or the one \`telescope\` config describes.
+const telescope =
+  __surface.telescope ??
+  new Telescope({
+    enabled: true,
+    path: '${context.telescope?.path}',
+    ignorePatterns: ${JSON.stringify(context.telescope?.ignore)},
+    recordBody: ${context.telescope?.recordBody},
+    storage: new InMemoryStorage({ maxEntries: ${context.telescope?.maxEntries} }),
+  });` : ""}
 
 ${context.storageDrivers?.setup ? `// Which storage drivers exist is the entry point's decision: the scheme in
 // each injected URL picks one, so no construct and no application module names
 // a provider.
 ${context.storageDrivers.setup}
 ` : ""}
-export interface ServerApp {
+${context.surface ? `// Who this server is to Postgres: application_name on every connection.
+process.env.GKM_APP_NAME ??= ${JSON.stringify(context.surface.id)};
+
+` : ""}export interface ServerApp {
   app: HonoType;
   start: (options?: {
     port?: number;
-    serve: (app: HonoType, port: number) => void | Promise<void>;
+    /** Returns the server, so a shutdown can stop it taking requests. */
+    serve: (app: HonoType, port: number) => unknown;
   }) => Promise<void>;
 }
 
@@ -1051,7 +1137,7 @@ export interface ServerApp {
  */
 export async function createApp(app?: HonoType, enableOpenApi: boolean = true): Promise<ServerApp> {
   const honoApp = app || new Hono();
-${telescopeSetup}${cors.setup}${beforeSetupCall}${studioSetup}
+${telescopeSetup}${cors.setup}${beforeSetupCall}${databaseApiSetup}
   // Setup HTTP endpoints
   await setupEndpoints(honoApp, envParser, logger, enableOpenApi);
 ${afterSetupCall}
@@ -1069,9 +1155,11 @@ ${afterSetupCall}
 
       const port = options.port ?? 3000;
 
-      // Start subscribers in background (non-blocking, local development only)
-      await setupSubscribers(envParser, logger).catch((error) => {
+      // Mount pushed subscribers' routes and start polled ones. What comes
+      // back subscribes the routes, once the server can answer them.
+      const subscribeForPush = await setupSubscribers(honoApp, envParser, logger).catch((error) => {
         logger.error({ error }, 'Failed to start subscribers');
+        return async (_port: number) => {};
       });
 
       // Start queue workers in background (non-blocking, local development only)
@@ -1091,6 +1179,8 @@ ${afterSetupCall}
       await options.serve(honoApp, port);
 
       logger.info({ port }, 'Server started');
+
+      await subscribeForPush(port);
     }
   };
 }
@@ -1111,26 +1201,6 @@ export default createApp;
 	* object. Nothing has to be printed now, which is also why nothing has to be
 	* named in config.
 	*/
-	generateAWSApiGatewayV1Handler(importPath, exportName, drivers) {
-		return `import { AmazonApiGatewayV1Endpoint } from '@geekmidas/constructs/aws';
-import { ${exportName} } from '${importPath}';
-${drivers?.imports ?? ""}
-${drivers?.setup ? `\n// The handler registers the drivers its target needs.\n${drivers.setup}\n` : ""}
-const adapter = new AmazonApiGatewayV1Endpoint(${exportName});
-
-export const handler = adapter.handler;
-`;
-	}
-	/**
-	* One Lambda, one endpoint — and no environment import.
-	*
-	* The endpoint was built from its surface, so it carries the parser the
-	* adaptor needs. This used to read
-	* `import { envParser } from '../../config/env'`, a line the build wrote
-	* because a generator can print a module specifier and cannot print an
-	* object. Nothing has to be printed now, which is also why nothing has to be
-	* named in config.
-	*/
 	generateAWSApiGatewayV2Handler(importPath, exportName, drivers) {
 		return `import { AmazonApiGatewayV2Endpoint } from '@geekmidas/constructs/aws';
 import { ${exportName} } from '${importPath}';
@@ -1139,13 +1209,6 @@ ${drivers?.setup ? `\n// The handler registers the drivers its target needs.\n${
 const adapter = new AmazonApiGatewayV2Endpoint(${exportName});
 
 export const handler = adapter.handler;
-`;
-	}
-	generateServerHandler(importPath, exportName) {
-		return `import { ${exportName} } from '${importPath}';
-
-// Server handler - implement based on your server framework
-export const handler = ${exportName};
 `;
 	}
 	/**
@@ -1153,8 +1216,7 @@ 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 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;
@@ -1166,8 +1228,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') {
@@ -1182,9 +1243,11 @@ export const handler = ${exportName};
 `;
 		}
 		const subscriberSetup = includeSubscribers ? `
-      // Start subscribers in background
-      await setupSubscribers(envParser, logger).catch((error) => {
+      // Mount pushed subscribers' routes and start polled ones. What comes
+      // back subscribes the routes, once the server can answer them.
+      const subscribeForPush = await setupSubscribers(honoApp, envParser, logger).catch((error) => {
         logger.error({ error }, 'Failed to start subscribers');
+        return async (_port: number) => {};
       });
 
       // Start queue workers in background
@@ -1202,15 +1265,29 @@ export const handler = ${exportName};
 import { setupQueues } from './queues.js';
 import { setupCrons } from './crons.js';` : "";
 		const gracefulShutdownCode = enableGracefulShutdown ? `
-  // Graceful shutdown handling
+  // Graceful shutdown: stop taking requests, let in-flight ones finish, then
+  // close what constructs opened (database pools) — so a rolling deploy does
+  // not leave the old task holding connections. Bounded by
+  // GKM_SHUTDOWN_TIMEOUT_MS, 8s by default: under Docker's 10s stop timeout,
+  // so the process exits on its own terms rather than being killed mid-drain.
   let isShuttingDown = false;
 
   const shutdown = async () => {
     if (isShuttingDown) return;
     isShuttingDown = true;
-    logger.info('Graceful shutdown initiated');
-    // Allow in-flight requests to complete (30s timeout)
-    setTimeout(() => process.exit(0), 30000);
+    const deadline = Number(process.env.GKM_SHUTDOWN_TIMEOUT_MS) || 8000;
+    logger.info({ deadline }, 'Graceful shutdown initiated');
+    setTimeout(() => {
+      logger.warn({ deadline }, 'Shutdown deadline reached, exiting');
+      process.exit(1);
+    }, deadline).unref();
+    await new Promise<void>((resolve) => {
+      const close = (server as { close?: (done: () => void) => void } | undefined)?.close;
+      if (typeof close === 'function') close.call(server, () => resolve());
+      else resolve();
+    });
+    await runShutdownHooks((error) => logger.error({ error }, 'Shutdown hook failed'));
+    process.exit(0);
   };
 
   process.on('SIGTERM', shutdown);
@@ -1228,7 +1305,7 @@ import { setupCrons } from './crons.js';` : "";
  */
 import { Hono } from 'hono';
 import type { Hono as HonoType } from 'hono';
-import { setupEndpoints } from '${endpointsImportPath}';
+${enableGracefulShutdown ? "import { runShutdownHooks } from '@geekmidas/constructs';\n" : ""}import { setupEndpoints } from '${endpointsImportPath}';
 ${subscriberImport}
 ${runtime.imports}
 ${runtime.bindings}
@@ -1239,7 +1316,10 @@ ${context.storageDrivers?.imports ?? ""}
 ${context.storageDrivers?.setup ? `// The entry point registers the drivers its target needs.
 ${context.storageDrivers.setup}
 ` : ""}
-export interface ServerApp {
+${context.surface ? `// Who this server is to Postgres: application_name on every connection.
+process.env.GKM_APP_NAME ??= ${JSON.stringify(context.surface.id)};
+
+` : ""}export interface ServerApp {
   app: HonoType;
   start: (options?: {
     port?: number;
@@ -1256,6 +1336,35 @@ export async function createApp(app?: HonoType): Promise<ServerApp> {
   // Health check endpoint (always first)
   honoApp.get('${healthCheckPath}', (c) => c.json({ status: 'ok', timestamp: Date.now() }));
   honoApp.get('/ready', (c) => c.json({ ready: true }));
+
+  // An HttpError a handler or a session callback throws — a 401, a 404 —
+  // answers with its own status, as it does under gkm dev. The optimized
+  // handlers do not catch, so without this every one of them was a 500.
+  // Anything else is a 500 that says nothing about why, and is logged.
+  honoApp.onError((error, c) => {
+    const http = error as {
+      isHttpError?: boolean;
+      statusCode?: number;
+      statusMessage?: string;
+      code?: string;
+      details?: unknown;
+    };
+    if (http.isHttpError === true && typeof http.statusCode === 'number') {
+      return c.json(
+        {
+          name: error.name,
+          message: error.message,
+          statusCode: http.statusCode,
+          statusMessage: http.statusMessage,
+          code: http.code,
+          details: http.details,
+        },
+        http.statusCode as 500,
+      );
+    }
+    logger.error({ error }, 'Unhandled error');
+    return c.json({ message: 'Internal Server Error' }, 500);
+  });
 ${cors.setup}${beforeSetupCall}
   // Setup HTTP endpoints (OpenAPI: ${enableOpenApi})
   await setupEndpoints(honoApp, envParser, logger, ${enableOpenApi});
@@ -1272,13 +1381,15 @@ ${afterSetupCall}
       }
 
       const port = options.port ?? Number(process.env.PORT) ?? 3000;
+      let server: unknown;
 ${gracefulShutdownCode}${subscriberSetup}
       logger.info({ port }, 'Starting production server');
 
       // Start HTTP server using provided serve function
-      await options.serve(honoApp, port);
+      server = await options.serve(honoApp, port);
 
       logger.info({ port }, 'Production server started');
+${includeSubscribers ? "\n      await subscribeForPush(port);" : ""}
     }
   };
 }
@@ -1287,21 +1398,27 @@ ${gracefulShutdownCode}${subscriberSetup}
 export default createApp;
 `;
 		await (0, node_fs_promises.writeFile)(appPath, content);
-		await this.generateProductionServerEntry(outputDir);
+		await this.generateProductionServerEntry(outputDir, context);
 		return appPath;
 	}
 	/**
 	* Generate production server.ts entry point
 	*/
-	async generateProductionServerEntry(outputDir) {
+	async generateProductionServerEntry(outputDir, context) {
 		const serverPath = (0, node_path.join)(outputDir, "server.ts");
-		const content = `#!/usr/bin/env node
+		await (0, node_fs_promises.writeFile)((0, node_path.join)(outputDir, "telemetry.ts"), generateTelemetryModule(context.telemetry));
+		await (0, node_fs_promises.writeFile)(serverPath, `#!/usr/bin/env node
 /**
  * Production server entry point
- * Generated by 'gkm build --provider server --production'
+ * Generated by 'gkm build --production'
  */
 import { serve } from '@hono/node-server';
-import { createApp } from './app.js';
+import { startTelemetry } from './telemetry.js';
+
+// Before the app is imported, so the libraries it loads are instrumented.
+await startTelemetry();
+
+const { createApp } = await import('./app.js');
 
 const port = Number(process.env.PORT) || 3000;
 
@@ -1309,13 +1426,11 @@ const { start } = await createApp();
 
 await start({
   port,
-  serve: (app, port) => { serve({ fetch: app.fetch, port }); },
+  serve: (app, port) => serve({ fetch: app.fetch, port }),
 });
-`;
-		await (0, node_fs_promises.writeFile)(serverPath, content);
+`);
 	}
 };
-
 //#endregion
 //#region src/generators/OpenApiTsGenerator.ts
 /**
@@ -1466,11 +1581,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)) {
@@ -1486,7 +1601,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;
@@ -1506,17 +1621,17 @@ 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();
@@ -1524,14 +1639,11 @@ var OpenApiTsGenerator = class {
 			}
 			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)) {
@@ -1544,13 +1656,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(" | ");
@@ -1574,10 +1688,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";
 		}
@@ -1598,10 +1709,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}`;
@@ -1640,8 +1748,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
 // ============================================================
@@ -1665,6 +1772,8 @@ export interface CreateApiOptions {
   queryClient?: QueryClient;
   /** Optional request interceptor */
   onRequest?: (config: RequestInit) => RequestInit | Promise<RequestInit>;
+  /** The \`fetch\` requests go out on — a test browser's, for one */
+  fetch?: typeof fetch;
 }
 
 /**
@@ -1694,6 +1803,7 @@ export function createApi(options: CreateApiOptions) {
     securitySchemes,
     authStrategies: options.authStrategies,
     onRequest: options.onRequest,
+    ...(options.fetch ? { fetch: options.fetch } : {}),
   });
 
   const hooks = createEndpointHooks<paths>(fetcher, { queryClient: options.queryClient });
@@ -1818,258 +1928,38 @@ ${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
-/**
-* Default output path for generated OpenAPI client (used for single-app configs)
-*/
-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) {
-	if (config.openapi === false) return { enabled: false };
-	if (config.openapi === true || config.openapi === void 0) return {
-		enabled: true,
-		title: "API Documentation",
-		version: "1.0.0",
-		description: "Auto-generated API documentation from endpoints"
-	};
-	return {
-		enabled: config.openapi.enabled !== false,
-		title: config.openapi.title || "API Documentation",
-		version: config.openapi.version || "1.0.0",
-		description: config.openapi.description || "Auto-generated API documentation from endpoints"
-	};
-}
-/**
-* 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, off `AppSpec.code`,
-* not a `routes` field anybody wrote.
-*/
-async function generateOpenApiFrom(routes, options = {}) {
-	const loaded = await new EndpointGenerator().load(routes, void 0, options.bustCache);
-	return generateOpenApi(loaded.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({ openapi: options.openapi });
-	if (!openApiConfig.enabled) return null;
-	if (endpoints.length === 0) {
-		logger.log("No valid endpoints found for OpenAPI generation");
-		return null;
-	}
-	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 written = [];
-	for (const [surfaceId, surfaceEndpoints] of bySurface) {
-		const relative$1 = openApiPathFor(surfaceId);
-		const outputPath = (0, node_path.join)(process.cwd(), relative$1);
-		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$1);
-		logger.log(`📄 OpenAPI client generated: ${relative$1} (${surfaceEndpoints.length} endpoints)`);
+Object.defineProperty(exports, "EndpointGenerator", {
+	enumerable: true,
+	get: function() {
+		return EndpointGenerator;
 	}
-	return {
-		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 = {}) {
-	const logger = console;
-	try {
-		const loadedConfig = await require_config.loadWorkspaceConfig(options.cwd);
-		if (loadedConfig.type === "single") {
-			const config = loadedConfig.raw;
-			if (!config.openapi) config.openapi = { enabled: true };
-			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.openapi !== false && (typeof app.openapi !== "object" || app.openapi.enabled !== false));
-			if (backendApps.length === 0) {
-				logger.log("No backend apps with OpenAPI enabled found");
-				return;
-			}
-			if (options.app) {
-				const entry = backendApps.find(([name]) => name === options.app);
-				if (!entry) throw new Error(`App "${options.app}" not found or has OpenAPI disabled`);
-				const [appName, app] = entry;
-				const result = await generateOpenApiForApp(workspaceRoot, appName, app);
-				if (result) logger.log(`📄 [${appName}] Generated OpenAPI (${result.endpointCount} endpoints)`);
-				return;
-			}
-			for (const [appName, app] of backendApps) {
-				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);
-			}
-		}
-	} catch (error) {
-		throw new Error(`OpenAPI generation failed: ${error.message}`);
-	}
-}
-/**
-* Generate OpenAPI for a single named app within a workspace.
-* 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, silent = true) {
-	if (app.type !== "backend") return null;
-	const appPath = (0, node_path.join)(workspaceRoot, app.path);
-	const globs = [(0, node_path.join)(appPath, "**/*.ts")];
-	return generateOpenApiFrom(globs, {
-		openapi: app.openapi ?? { enabled: true },
-		silent
-	});
-}
-/**
-* Resolve the gkm bin path. Tests can override via `GKM_BIN_PATH` env var
-* to avoid depending on the built dist.
-*/
-function resolveGkmBinPath() {
-	if (process.env.GKM_BIN_PATH) return process.env.GKM_BIN_PATH;
-	return (0, node_url.fileURLToPath)(new URL("../bin/gkm.mjs", require("url").pathToFileURL(__filename).href));
-}
-/**
-* Spawn a subprocess that runs `gkm openapi --app <name>` with `cwd` set to
-* the app's directory. Inherits `NODE_OPTIONS` (which already contains
-* `--import tsx`), so the child gets a fresh tsx instance whose tsconfig
-* discovery picks up the app's tsconfig path aliases.
-*/
-async function runOpenApiInSubprocess(appCwd, appName) {
-	const binPath = resolveGkmBinPath();
-	await new Promise((resolve$1, reject) => {
-		const child = (0, node_child_process.spawn)(process.execPath, [
-			binPath,
-			"openapi",
-			"--app",
-			appName
-		], {
-			cwd: appCwd,
-			stdio: "inherit",
-			env: process.env
-		});
-		child.on("error", reject);
-		child.on("close", (code) => {
-			if (code === 0) resolve$1();
-			else reject(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, 'OPENAPI_OUTPUT_PATH', {
-  enumerable: true,
-  get: function () {
-    return OPENAPI_OUTPUT_PATH;
-  }
 });
-Object.defineProperty(exports, 'generateOpenApi', {
-  enumerable: true,
-  get: function () {
-    return generateOpenApi;
-  }
-});
-Object.defineProperty(exports, 'generateOpenApiFrom', {
-  enumerable: true,
-  get: function () {
-    return generateOpenApiFrom;
-  }
-});
-Object.defineProperty(exports, 'normalizeRoutes', {
-  enumerable: true,
-  get: function () {
-    return normalizeRoutes;
-  }
-});
-Object.defineProperty(exports, 'openApiPathFor', {
-  enumerable: true,
-  get: function () {
-    return openApiPathFor;
-  }
-});
-Object.defineProperty(exports, 'openapiCommand', {
-  enumerable: true,
-  get: function () {
-    return openapiCommand;
-  }
+Object.defineProperty(exports, "OpenApiTsGenerator", {
+	enumerable: true,
+	get: function() {
+		return OpenApiTsGenerator;
+	}
 });
-Object.defineProperty(exports, 'resolveOpenApiConfig', {
-  enumerable: true,
-  get: function () {
-    return resolveOpenApiConfig;
-  }
+Object.defineProperty(exports, "runtimeFor", {
+	enumerable: true,
+	get: function() {
+		return runtimeFor;
+	}
 });
-Object.defineProperty(exports, 'runtimeFor', {
-  enumerable: true,
-  get: function () {
-    return runtimeFor;
-  }
+Object.defineProperty(exports, "telemetryFor", {
+	enumerable: true,
+	get: function() {
+		return telemetryFor;
+	}
 });
-//# sourceMappingURL=openapi-D-dx9Akj.cjs.map
+
+//# sourceMappingURL=OpenApiTsGenerator-BSrgw7B0.cjs.map