@geekmidas/cli 10.0.0-alpha.10 → 10.0.0-alpha.100

package/dist/EndpointGenerator-By5_tYE9.cjs

@@ -0,0 +1,1090 @@
+const require_errors = require("./errors-DMC4Umsb.cjs");
+const require_discover = require("./discover-BfhVW_kT.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");
+//#region src/generators/clientTelemetry.ts
+/**
+* Whether a generated client propagates trace context by default.
+*
+* `false` (the default) prints a client that sends no trace headers unless
+* its caller passes `telemetry`. Anything else prints that default into
+* `createApi`: `true`, or `{ sampleRate }` — the stage's rate, for the page
+* views no OpenTelemetry SDK is tracing. A caller's own `telemetry` option
+* still wins.
+*/
+/** A `sampleRate` outside 0–1, which no sampler can honour. */
+var InvalidClientTelemetrySampleRate = class extends require_errors.GkmError {
+	sampleRate;
+	constructor(sampleRate) {
+		super(`The client's telemetry sample rate must be a number from 0 to 1, got ${sampleRate}. Pass the stage's rate, such as 0.1, or leave it out for 1.`);
+		this.sampleRate = sampleRate;
+		this.name = "InvalidClientTelemetrySampleRate";
+	}
+};
+/** The `telemetry` default as the generated module prints it. */
+function printTelemetryDefault(telemetry) {
+	if (typeof telemetry === "boolean") return String(telemetry);
+	const { sampleRate } = telemetry;
+	if (!Number.isFinite(sampleRate) || sampleRate < 0 || sampleRate > 1) throw new InvalidClientTelemetrySampleRate(sampleRate);
+	return `{ sampleRate: ${sampleRate} }`;
+}
+/**
+* `--telemetry [rate]` for a client default, as `gkm openapi` takes it — and
+* as a site's Dockerfile passes it to the `gkm openapi --app` it runs.
+*/
+function telemetryArgs(telemetry) {
+	if (!telemetry) return [];
+	if (telemetry === true) return ["--telemetry"];
+	return ["--telemetry", String(telemetry.sampleRate)];
+}
+/** What `--telemetry [rate]` parsed to: on, at a rate when one was given. */
+function parseTelemetryFlag(value) {
+	if (value === void 0 || value === false) return void 0;
+	if (value === true) return true;
+	return { sampleRate: Number(value) };
+}
+//#endregion
+//#region src/generators/telemetry.ts
+/** Each endpoint's own `.telemetry({ ignore, attributes })`, as routes. */
+function routeTelemetry(endpoints) {
+	return endpoints.flatMap((endpoint) => endpoint.telemetry ? [{
+		method: endpoint.method,
+		path: endpoint.route,
+		...endpoint.telemetry
+	}] : []);
+}
+/**
+* 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;
+	}
+}
+/**
+* The telemetry packages that do not 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. Empty when every one does.
+*/
+function missingTelemetryPackages(appRoot) {
+	const telescope = packageDir(appRoot, "@geekmidas/telescope");
+	if (!telescope) return ["@geekmidas/telescope", ...TELEMETRY_PACKAGES];
+	return TELEMETRY_PACKAGES.filter((pkg) => !packageDir(telescope, pkg));
+}
+/**
+* An app uses a `Telemetry` construct and cannot load what it needs to.
+*
+* Failed at build, not at startup: a process that was given telemetry and
+* quietly ran without it is an outage nobody can see into.
+*/
+var TelemetryPackagesMissing = class extends require_errors.GkmError {
+	app;
+	missing;
+	dir;
+	command;
+	constructor(app, missing, dir) {
+		const command = `pnpm --dir ${dir || "."} add ${missing.join(" ")}`;
+		super(`'${app}' uses a Telemetry construct, and ${missing.join(", ")} ${missing.length === 1 ? "does" : "do"} not resolve from it — its server would start without exporting a span. Add them to the app and build again:\n\n  ${command}\n`);
+		this.app = app;
+		this.missing = missing;
+		this.dir = dir;
+		this.name = "TelemetryPackagesMissing";
+		this.command = command;
+	}
+};
+/**
+* The telemetry half of a build context: undefined for a process with no
+* edge to a `Telemetry` node, and — for one with an edge — what its entry
+* starts with, once every package it needs resolves.
+*/
+function telemetryFor(options) {
+	const { node } = options;
+	if (!node) return void 0;
+	const missing = missingTelemetryPackages(options.appRoot);
+	if (missing.length > 0) throw new TelemetryPackagesMissing(options.app, missing, (0, node_path.relative)(options.cwd ?? process.cwd(), options.appRoot));
+	return {
+		serviceName: options.serviceName,
+		...options.workspaceName && { serviceNamespace: options.workspaceName },
+		ignorePaths: [...node.ignorePaths ?? []],
+		attributes: { ...node.attributes },
+		routes: [...options.routes ?? []]
+	};
+}
+const HEADER = `/**
+ * Generated by gkm, for the production entry and the \`gkm dev\` one alike.
+ *
+ * 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.
+ */
+
+import type { MiddlewareHandler } from 'hono';
+
+export interface StartTelemetryOptions {
+  /** Requests whose spans would only be noise: health checks, by default. */
+  ignorePaths?: string[];
+  /**
+   * The API's own sites — the origins its CORS allows — read on each request.
+   * Their \`traceparent\` is continued, as is an internal caller's; anyone
+   * else's starts a new trace linked to the one it claimed.
+   */
+  trustedOrigins?: () => readonly string[];
+}
+`;
+/** `/users/:id` as a pattern over a request's path. */
+function routePattern(path) {
+	return `^${path.split("/").map((segment) => {
+		if (segment.startsWith(":")) return "[^/]+";
+		if (segment === "*") return ".*";
+		return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	}).join("/")}/?$`;
+}
+/**
+* The entry's `telemetry.ts`: a `startTelemetry()` the server awaits before it
+* imports the app, so the libraries the app loads are instrumented. It returns
+* the Hono middleware that traces each request, or undefined when telemetry is
+* off — the server mounts it ahead of every route.
+*
+* Without a context — a process with no edge to a `Telemetry` node — it is a
+* stub that loads nothing and says nothing: telemetry is not something that
+* process was given.
+*
+* 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) return `${HEADER}
+// This process has no Telemetry construct, so there is nothing to start.
+export async function startTelemetry(
+  _options: StartTelemetryOptions = {},
+): Promise<MiddlewareHandler | undefined> {
+  return undefined;
+}
+`;
+	const options = [
+		`serviceName: ${JSON.stringify(telemetry.serviceName)},`,
+		...telemetry.serviceNamespace ? [`serviceNamespace: ${JSON.stringify(telemetry.serviceNamespace)},`] : [],
+		"deploymentEnvironment: process.env.STAGE,",
+		...Object.keys(telemetry.attributes).length ? [`resourceAttributes: ${JSON.stringify(telemetry.attributes)},`] : [],
+		"handleSignals: false,",
+		"instrumentPino: false,",
+		"incomingHttpSpans: false,"
+	];
+	const routes = telemetry.routes.map((route) => ({
+		method: route.method.toUpperCase(),
+		pattern: routePattern(route.path),
+		...route.ignore ? { ignore: true } : {},
+		...route.attributes && Object.keys(route.attributes).length ? { attributes: route.attributes } : {}
+	}));
+	const withAttributes = routes.some((route) => "attributes" in route);
+	return `${HEADER}
+/** 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 Telemetry construct's own ignored paths, beside the entry's. */
+const IGNORE_PATHS: string[] = ${JSON.stringify(telemetry.ignorePaths)};
+
+/** Each route's own .telemetry({ ignore, attributes }). */
+const ROUTES: {
+  method: string;
+  pattern: string;
+  ignore?: boolean;
+  attributes?: Record<string, string>;
+}[] = ${JSON.stringify(routes)};
+
+const MATCHERS = ROUTES.map((route) => ({ ...route, regex: new RegExp(route.pattern) }));
+
+function routeOf(method: string, path: string) {
+  return MATCHERS.find(
+    (route) => (route.method === method || route.method === 'ALL' || route.method === 'ANY') && route.regex.test(path),
+  );
+}
+
+export async function startTelemetry(
+  options: StartTelemetryOptions = {},
+): Promise<MiddlewareHandler | undefined> {
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) return undefined;
+
+  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 undefined;
+  }
+
+  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);
+      });
+    });
+  }
+
+  // A SERVER span per request, opened by the app itself rather than by
+  // hooking node:http: \`GET /users/:id\`, continuing an incoming traceparent
+  // from the API's own sites and internal callers (a new, linked trace from
+  // anyone else), with the handler — its logs, fetches and queries — running
+  // inside it.
+  const spans = instrumentation.honoTelemetryMiddleware({
+    ignorePaths: [...(options.ignorePaths ?? []), ...IGNORE_PATHS],
+    trustedOrigins: options.trustedOrigins,
+    ...(MATCHERS.some((route) => route.ignore)
+      ? { shouldSkip: (c) => routeOf(c.req.method, c.req.path)?.ignore === true }
+      : {}),
+  });
+${withAttributes ? `
+  // A route's own attributes, on the span the middleware just opened.
+  const { trace } = await import('@opentelemetry/api');
+  return (c, next) =>
+    spans(c, async () => {
+      const attributes = routeOf(c.req.method, c.req.path)?.attributes;
+      if (attributes) trace.getActiveSpan()?.setAttributes(attributes);
+      await next();
+    });
+` : `  return spans;
+`}}
+`;
+}
+/**
+* What an entry starts telemetry with, before it imports the app — shared by
+* the production server, a self-serving surface's server and the `gkm dev`
+* entry, so the three cannot start it differently. Defines `requestSpans`.
+*/
+function startTelemetryCode(ignorePaths) {
+	return `// The API's own sites, known once the app has read its configuration: the
+// origins its CORS allows are the ones whose trace context is continued.
+let trustedOrigins: readonly string[] = [];
+
+// Before the app is imported, so the libraries it loads are instrumented.
+const { startTelemetry } = await import('./telemetry.js');
+const requestSpans = await startTelemetry({
+  ignorePaths: ${JSON.stringify(ignorePaths)},
+  trustedOrigins: () => trustedOrigins,
+});
+`;
+}
+/** Mounts `requestSpans` on `app` ahead of every route. */
+function mountRequestSpansCode(app) {
+	return `// The span middleware goes on before any route, so every request runs in it.
+if (requestSpans) ${app}.use('*', requestSpans);
+`;
+}
+/** Writes the entry's `telemetry.ts` beside it. */
+async function writeTelemetryModule(outputDir, telemetry) {
+	await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+	await (0, node_fs_promises.writeFile)((0, node_path.join)(outputDir, "telemetry.ts"), generateTelemetryModule(telemetry));
+}
+//#endregion
+//#region src/generators/EndpointGenerator.ts
+/**
+* How a generated entry gets its logger and environment parser.
+*
+* From the surface it serves, when there is one: the surface holds both as
+* *objects*, and discovery already recorded which module declares it, so the
+* entry imports that module and reads them off it.
+*
+* The alternative — the shape this replaces — was naming both in config as
+* module paths, `envParser: './config/env#envParser'`, and printing an import
+* for each. Two strings per app, checked by nothing, describing files the
+* surface was already holding the contents of.
+*
+* Falls back to the configured paths for an app that declares no surface.
+*/
+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.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.",
+				"const envParser = __surface.envParser;",
+				"const logger = __surface.logger;"
+			].join("\n")
+		};
+	}
+	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) {
+	const rel = (0, node_path.relative)(fromDir, target).replace(/\.ts$/, ".js");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+/**
+* CORS for a surface, derived rather than hand-written.
+*
+* Who may call a surface is already in the graph — every construct that
+* declared an edge to it — and reaches the process as one comma-separated
+* value. An application that maintained this by hand maintained a list that was
+* wrong in two directions at once: it trusted origins nothing was serving, and
+* it could not name hosts a deploy had not chosen yet.
+*
+* Only the parts a graph cannot answer are configurable, and every one has a
+* default: a surface that says nothing about CORS still gets it.
+*/
+function corsFor(surface) {
+	if (!surface) return {
+		imports: "",
+		setup: ""
+	};
+	const cors = surface.cors ?? {};
+	const allowHeaders = [.../* @__PURE__ */ new Set([
+		"content-type",
+		"authorization",
+		"traceparent",
+		"tracestate",
+		...cors.allowHeaders ?? []
+	])];
+	return {
+		imports: `import { cors } from 'hono/cors';`,
+		setup: `
+  // Who may call ${surface.id}, read off the graph rather than listed here.
+  {
+    const { origins } = envParser
+      .create((get) => ({
+        origins: get('${surface.trustedOriginsKey}')
+          .string()
+          .default('')
+          .transform((value: string) =>
+            value.split(',').map((origin) => origin.trim()).filter(Boolean),
+          ),
+      }))
+      .parse();
+
+    // The same origins are the ones whose trace context the request spans
+    // continue — the server reads them back from \`createApp\`.
+    trustedOrigins.push(...origins);
+
+    honoApp.use('*', cors({
+      origin: origins,
+      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+      allowHeaders: ${JSON.stringify(allowHeaders)},${cors.exposeHeaders ? `\n      exposeHeaders: ${JSON.stringify(cors.exposeHeaders)},` : ""}
+      credentials: ${cors.credentials ?? true},
+      maxAge: ${cors.maxAge ?? 86400},
+    }));
+  }
+`
+	};
+}
+var EndpointGenerator = class extends require_discover.ConstructGenerator {
+	isConstruct(value) {
+		return _geekmidas_constructs_endpoints.Endpoint.isEndpoint(value);
+	}
+	async build(context, constructs, outputDir, options) {
+		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 (target === "server") {
+			await this.generateEndpointsFile(outputDir, constructs);
+			const appFile = await this.generateAppFile(outputDir, context);
+			routes.push({
+				path: "*",
+				method: "ALL",
+				handler: (0, node_path.relative)(root, appFile),
+				authorizer: "none"
+			});
+			logger.log(`Generated server with ${constructs.length} endpoints${enableOpenApi ? " (OpenAPI enabled)" : ""}`);
+			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)(root, 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}`);
+		}
+		return routes;
+	}
+	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) {
+		const endpointsPath = (0, node_path.join)(outputDir, "endpoints.ts");
+		const importsByFile = /* @__PURE__ */ new Map();
+		for (const { path, key } of endpoints) {
+			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 content = `import type { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import { HonoEndpoint } from '@geekmidas/constructs/hono';
+import { Endpoint } from '@geekmidas/constructs/endpoints';
+import { ServiceDiscovery } from '@geekmidas/services';
+import type { Hono } from 'hono';
+${Array.from(importsByFile.entries()).map(([importPath, exports]) => `import { ${exports.join(", ")} } from '${importPath}';`).join("\n")}
+
+export const endpoints: Endpoint<any, any, any, any, any, any, any, any, any, any, any, any>[] = [
+  ${endpoints.map(({ key }) => key).join(",\n  ")}
+];
+
+export async function setupEndpoints(
+  app: Hono,
+  envParser: EnvironmentParser<any>,
+  logger: Logger,
+  enableOpenApi: boolean = true,
+): Promise<void> {
+  const serviceDiscovery = ServiceDiscovery.getInstance(envParser);
+
+  // Configure OpenAPI options based on enableOpenApi flag
+  const openApiOptions: any = enableOpenApi ? {
+    docsPath: '/__docs',
+    openApiOptions: {
+      title: 'API Documentation',
+      version: '1.0.0',
+      description: 'Generated API documentation'
+    }
+  } : { docsPath: false };
+
+  HonoEndpoint.addRoutes(endpoints, serviceDiscovery, app, openApiOptions);
+
+  // Add Swagger UI if OpenAPI is enabled
+  if (enableOpenApi) {
+    try {
+      const { swaggerUI } = await import('@hono/swagger-ui');
+      app.get('/__docs/ui', swaggerUI({ url: '/__docs' }));
+    } catch {
+      // @hono/swagger-ui not installed, skip Swagger UI
+    }
+  }
+}
+`;
+		await (0, node_fs_promises.writeFile)(endpointsPath, content);
+		return endpointsPath;
+	}
+	async generateAppFile(outputDir, context) {
+		await writeTelemetryModule(outputDir, context.telemetry);
+		if (context.production?.enabled) return this.generateProductionAppFile(outputDir, context);
+		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 telescopeFromSurface = !!context.surface?.module && !usesExternalTelescope;
+		let telescopeImports = "";
+		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) {
+			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') {
+    await serverHooks.beforeSetup(honoApp, { envParser, logger });
+  }
+`;
+			afterSetupCall = `
+  // Call afterSetup hook if defined
+  if (typeof serverHooks.afterSetup === 'function') {
+    await serverHooks.afterSetup(honoApp, { envParser, logger });
+  }
+`;
+		}
+		const telescopeWebSocketSetupCode = telescopeWebSocketEnabled ? `
+  // Setup WebSocket for real-time telescope updates
+  try {
+    const { createNodeWebSocket } = await import('@hono/node-ws');
+    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app: honoApp });
+    // Add WebSocket route directly to main app (sub-app routes don't support WS upgrade)
+    honoApp.get('${context.telescope?.path}/ws', upgradeWebSocket(() => ({
+      onOpen: (_event: Event, ws: any) => {
+        telescope.addWsClient(ws);
+      },
+      onClose: (_event: Event, ws: any) => {
+        telescope.removeWsClient(ws);
+      },
+      onMessage: (event: MessageEvent, ws: any) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.type === 'ping') {
+            ws.send(JSON.stringify({ type: 'pong' }));
+          }
+        } catch {
+          // Ignore invalid messages
+        }
+      },
+    })));
+    // Store injectWebSocket for server entry to call after serve()
+    (honoApp as any).__injectWebSocket = injectWebSocket;
+    logger.info('Telescope WebSocket enabled');
+  } catch (e) {
+    logger.warn({ err: e }, 'WebSocket support not available - install @hono/node-ws for real-time updates');
+  }
+` : "";
+		let telescopeSetup = "";
+		if (telescopeEnabled) {
+			if (telescopeFromSurface || usesExternalTelescope) telescopeSetup = `
+${telescopeWebSocketSetupCode}
+  // Add telescope middleware (before endpoints to capture all requests)
+  honoApp.use('*', createMiddleware(telescope));
+
+  // Mount Telescope's JSON API
+  const telescopeApi = createApi(telescope);
+  honoApp.route('${context.telescope?.path}', telescopeApi);
+`;
+			else telescopeSetup = `
+  // Setup Telescope for debugging/monitoring
+  const telescopeStorage = new InMemoryStorage({ maxEntries: ${context.telescope?.maxEntries} });
+  const telescope = new Telescope({
+    enabled: true,
+    path: '${context.telescope?.path}',
+    ignorePatterns: ${JSON.stringify(context.telescope?.ignore)},
+    recordBody: ${context.telescope?.recordBody},
+    storage: telescopeStorage,
+  });
+${telescopeWebSocketSetupCode}
+  // Add telescope middleware (before endpoints to capture all requests)
+  honoApp.use('*', createMiddleware(telescope));
+
+  // Mount Telescope's JSON API
+  const telescopeApi = createApi(telescope);
+  honoApp.route('${context.telescope?.path}', telescopeApi);
+`;
+		}
+		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}',
+  });
+  honoApp.all('${databaseApi.path}/*', (c) => databaseApi(c.req.raw));
+` : "";
+		const content = `/**
+ * Generated server application
+ *
+ * ⚠️  WARNING: This is for LOCAL DEVELOPMENT ONLY
+ * The subscriber polling mechanism is not production-ready.
+ * For production, use AWS Lambda with SQS/SNS event sources.
+ */
+import { Hono } from 'hono';
+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}
+${databaseApiImports}
+${hooksImports}
+${cors.imports}
+${context.storageDrivers?.imports ?? ""}
+
+${runtime.bindings}
+${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 drivers exist — storage, cache, events — 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}
+` : ""}
+${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;
+  /** The origins this API's CORS allows: its own sites. */
+  trustedOrigins: readonly string[];
+  start: (options?: {
+    port?: number;
+    /** Returns the server, so a shutdown can stop it taking requests. */
+    serve: (app: HonoType, port: number) => unknown;
+  }) => Promise<void>;
+}
+
+/**
+ * Create and configure the Hono application
+ *
+ * @param app - Optional Hono app instance to configure (creates new one if not provided)
+ * @param enableOpenApi - Enable OpenAPI documentation (default: true)
+ * @returns Server app with configured Hono app and start function
+ *
+ * @example
+ * // With Bun
+ * import { createApp } from './.gkm/server/app.js';
+ *
+ * const { app, start } = await createApp();
+ *
+ * await start({
+ *   port: 3000,
+ *   serve: (app, port) => {
+ *     Bun.serve({ port, fetch: app.fetch });
+ *   }
+ * });
+ *
+ * @example
+ * // With Node.js (using @hono/node-server)
+ * import { serve } from '@hono/node-server';
+ * import { createApp } from './.gkm/server/app.js';
+ *
+ * const { app, start } = await createApp();
+ *
+ * await start({
+ *   port: 3000,
+ *   serve: (app, port) => {
+ *     serve({ fetch: app.fetch, port });
+ *   }
+ * });
+ */
+export async function createApp(app?: HonoType, enableOpenApi: boolean = true): Promise<ServerApp> {
+  const honoApp = app || new Hono();
+  const trustedOrigins: string[] = [];
+${telescopeSetup}${cors.setup}${beforeSetupCall}${databaseApiSetup}
+  // Setup HTTP endpoints
+  await setupEndpoints(honoApp, envParser, logger, enableOpenApi);
+${afterSetupCall}
+
+  return {
+    app: honoApp,
+    trustedOrigins,
+    async start(options) {
+      if (!options?.serve) {
+        throw new Error(
+          'serve function is required. Pass a serve function for your runtime:\\n' +
+          '  - Bun: (app, port) => Bun.serve({ port, fetch: app.fetch })\\n' +
+          '  - Node: (app, port) => serve({ fetch: app.fetch, port })'
+        );
+      }
+
+      const port = options.port ?? 3000;
+
+      // 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({ err: error }, 'Failed to start subscribers');
+        return async (_port: number) => {};
+      });
+
+      // Start queue workers in background (non-blocking, local development only)
+      await setupQueues(envParser, logger).catch((error) => {
+        logger.error({ err: 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({ err: error }, 'Failed to schedule crons');
+      });
+
+      logger.info({ port }, 'Starting server');
+
+      // Start HTTP server using provided serve function
+      await options.serve(honoApp, port);
+
+      logger.info({ port }, 'Server started');
+
+      await subscribeForPush(port);
+    }
+  };
+}
+
+// Default export for convenience
+export default createApp;
+`;
+		await (0, node_fs_promises.writeFile)(appPath, content);
+		return appPath;
+	}
+	/**
+	* 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}';
+${drivers?.imports ?? ""}
+${drivers?.setup ? `\n// The handler registers the drivers its target needs.\n${drivers.setup}\n` : ""}
+const adapter = new AmazonApiGatewayV2Endpoint(${exportName});
+
+export const handler = adapter.handler;
+`;
+	}
+	/**
+	* Generate a production-optimized app.ts file
+	* No dev tools (Telescope, Studio, WebSocket), includes health checks and graceful shutdown
+	*/
+	async generateProductionAppFile(outputDir, context) {
+		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;
+		const enableOpenApi = production.openapi;
+		const includeSubscribers = production.subscribers === "include";
+		const cors = corsFor(context.surface);
+		let hooksImports = "";
+		let beforeSetupCall = "";
+		let afterSetupCall = "";
+		if (context.hooks?.serverHooksPath) {
+			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') {
+    await serverHooks.beforeSetup(honoApp, { envParser, logger });
+  }
+`;
+			afterSetupCall = `
+  // Call afterSetup hook if defined
+  if (typeof serverHooks.afterSetup === 'function') {
+    await serverHooks.afterSetup(honoApp, { envParser, logger });
+  }
+`;
+		}
+		const subscriberSetup = includeSubscribers ? `
+      // 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({ err: error }, 'Failed to start subscribers');
+        return async (_port: number) => {};
+      });
+
+      // Start queue workers in background
+      await setupQueues(envParser, logger).catch((error) => {
+        logger.error({ err: 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({ err: error }, 'Failed to schedule crons');
+      });
+` : "";
+		const subscriberImport = includeSubscribers ? `import { setupSubscribers } from './subscribers.js';
+import { setupQueues } from './queues.js';
+import { setupCrons } from './crons.js';` : "";
+		const gracefulShutdownCode = enableGracefulShutdown ? `
+  // 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;
+    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({ err: error }, 'Shutdown hook failed'));
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+` : "";
+		const content = `/**
+ * Generated production server application
+ *
+ * This is a production-optimized build without dev tools.
+ * - No Telescope debugging dashboard
+ * - No Studio database browser
+ * - No WebSocket updates
+ * - Includes health checks and graceful shutdown
+ */
+import { Hono } from 'hono';
+import type { Hono as HonoType } from 'hono';
+${enableGracefulShutdown ? "import { runShutdownHooks } from '@geekmidas/constructs';\n" : ""}import { setupEndpoints } from './endpoints.js';
+${subscriberImport}
+${runtime.imports}
+${runtime.bindings}
+${hooksImports}
+${cors.imports}
+${context.storageDrivers?.imports ?? ""}
+
+${context.storageDrivers?.setup ? `// The entry point registers the drivers its target needs.
+${context.storageDrivers.setup}
+` : ""}
+${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;
+  /** The origins this API's CORS allows: its own sites. */
+  trustedOrigins: readonly string[];
+  start: (options?: {
+    port?: number;
+    serve: (app: HonoType, port: number) => void | Promise<void>;
+  }) => Promise<void>;
+}
+
+/**
+ * Create and configure the production Hono application
+ */
+export async function createApp(app?: HonoType): Promise<ServerApp> {
+  const honoApp = app || new Hono();
+  const trustedOrigins: string[] = [];
+
+  // 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({ err: 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});
+${afterSetupCall}
+  return {
+    app: honoApp,
+    trustedOrigins,
+    async start(options) {
+      if (!options?.serve) {
+        throw new Error(
+          'serve function is required. Pass a serve function for your runtime:\\n' +
+          '  - Bun: (app, port) => Bun.serve({ port, fetch: app.fetch })\\n' +
+          '  - Node: (app, port) => serve({ fetch: app.fetch, port })'
+        );
+      }
+
+      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
+      server = await options.serve(honoApp, port);
+
+      logger.info({ port }, 'Production server started');
+${includeSubscribers ? "\n      await subscribeForPush(port);" : ""}
+    }
+  };
+}
+
+// Default export for convenience
+export default createApp;
+`;
+		await (0, node_fs_promises.writeFile)(appPath, content);
+		await this.generateProductionServerEntry(outputDir, context);
+		return appPath;
+	}
+	/**
+	* Generate production server.ts entry point
+	*/
+	async generateProductionServerEntry(outputDir, context) {
+		const serverPath = (0, node_path.join)(outputDir, "server.ts");
+		const content = `#!/usr/bin/env node
+/**
+ * Production server entry point
+ * Generated by 'gkm build --production'
+ */
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+
+${startTelemetryCode([context.production?.healthCheck ?? "/health", "/ready"])}
+const { createApp } = await import('./app.js');
+
+const port = Number(process.env.PORT) || 3000;
+
+const app = new Hono();
+${mountRequestSpansCode("app")}
+const created = await createApp(app);
+trustedOrigins = created.trustedOrigins;
+const { start } = created;
+
+await start({
+  port,
+  serve: (app, port) => serve({ fetch: app.fetch, port }),
+});
+`;
+		await (0, node_fs_promises.writeFile)(serverPath, content);
+	}
+};
+//#endregion
+Object.defineProperty(exports, "EndpointGenerator", {
+	enumerable: true,
+	get: function() {
+		return EndpointGenerator;
+	}
+});
+Object.defineProperty(exports, "mountRequestSpansCode", {
+	enumerable: true,
+	get: function() {
+		return mountRequestSpansCode;
+	}
+});
+Object.defineProperty(exports, "parseTelemetryFlag", {
+	enumerable: true,
+	get: function() {
+		return parseTelemetryFlag;
+	}
+});
+Object.defineProperty(exports, "printTelemetryDefault", {
+	enumerable: true,
+	get: function() {
+		return printTelemetryDefault;
+	}
+});
+Object.defineProperty(exports, "routeTelemetry", {
+	enumerable: true,
+	get: function() {
+		return routeTelemetry;
+	}
+});
+Object.defineProperty(exports, "runtimeFor", {
+	enumerable: true,
+	get: function() {
+		return runtimeFor;
+	}
+});
+Object.defineProperty(exports, "startTelemetryCode", {
+	enumerable: true,
+	get: function() {
+		return startTelemetryCode;
+	}
+});
+Object.defineProperty(exports, "telemetryArgs", {
+	enumerable: true,
+	get: function() {
+		return telemetryArgs;
+	}
+});
+Object.defineProperty(exports, "telemetryFor", {
+	enumerable: true,
+	get: function() {
+		return telemetryFor;
+	}
+});
+Object.defineProperty(exports, "writeTelemetryModule", {
+	enumerable: true,
+	get: function() {
+		return writeTelemetryModule;
+	}
+});
+
+//# sourceMappingURL=EndpointGenerator-By5_tYE9.cjs.map