zudojs-cli 2.1.3 → 2.2.0

package/dist/src/templates/resource/layers/resourceMemory.template.js

@@ -0,0 +1,87 @@
+/**
+ * zudojs-cli — A resource's repository contract and in-memory store.
+ */
+/** `repositories/<slug>.repository.ts`: the contract and a memory store. */
+export function renderResourceRepository(n) {
+    const types = `Create${n.entity}Input, ${n.entity}, ${n.entity}Page, ${n.entity}PageRequest, Update${n.entity}Input`;
+    return `import { randomUUID } from "node:crypto";
+
+import { ConflictError } from "@zudojs/errors";
+
+import type { ${types} } from "../dtos/${n.slug}.dto.js";
+
+/** Storage contract for ${n.label} records; the service depends on this only. */
+export interface ${n.pascal}Repository {
+  /** One page in creation order, continuing after \`cursor\` when given. */
+  list(page: ${n.entity}PageRequest): Promise<${n.entity}Page>;
+  findById(id: string): Promise<${n.entity} | undefined>;
+  create(input: Create${n.entity}Input): Promise<${n.entity}>;
+  update(id: string, input: Update${n.entity}Input): Promise<${n.entity} | undefined>;
+  delete(id: string): Promise<boolean>;
+}
+
+/** Most records the in-memory store keeps, so it cannot exhaust memory. */
+const MAX_RECORDS = 10_000;
+
+/**
+ * Keeps ${n.label} records in process memory: for development and tests.
+ * Data is lost on restart. Swap the implementation in container.ts.
+ */
+export class InMemory${n.pascal}Repository implements ${n.pascal}Repository {
+  private readonly records = new Map<string, ${n.entity}>();
+
+  public async list(page: ${n.entity}PageRequest): Promise<${n.entity}Page> {
+    // A Map iterates in insertion order, which is creation order here.
+    const all = [...this.records.values()];
+    let start = 0;
+    if (page.cursor !== undefined) {
+      const at = all.findIndex((record) => record.id === page.cursor);
+      if (at === -1) return { items: [], nextCursor: null };
+      start = at + 1;
+    }
+    const items = all.slice(start, start + page.limit);
+    const last = items.at(-1);
+    const nextCursor = last !== undefined && start + page.limit < all.length ? last.id : null;
+    return { items, nextCursor };
+  }
+
+  public async findById(id: string): Promise<${n.entity} | undefined> {
+    return this.records.get(id);
+  }
+
+  public async create(input: Create${n.entity}Input): Promise<${n.entity}> {
+    if (this.records.size >= MAX_RECORDS) {
+      throw new ConflictError("The in-memory ${n.label} store is full.");
+    }
+    const now = new Date().toISOString();
+    const record: ${n.entity} = {
+      id: randomUUID(),
+      name: input.name,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.records.set(record.id, record);
+    return record;
+  }
+
+  public async update(
+    id: string,
+    input: Update${n.entity}Input,
+  ): Promise<${n.entity} | undefined> {
+    const existing = this.records.get(id);
+    if (existing === undefined) return undefined;
+    const updated: ${n.entity} = {
+      ...existing,
+      name: input.name ?? existing.name,
+      updatedAt: new Date().toISOString(),
+    };
+    this.records.set(id, updated);
+    return updated;
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    return this.records.delete(id);
+  }
+}
+`;
+}

package/dist/src/templates/resource/layers/resourcePrisma.template.d.ts

@@ -12,4 +12,3 @@ export declare function renderPrismaRepository(n: ResourceNames, appSrcFromRepos
 export declare function renderPrismaModel(n: ResourceNames): string;
 /** Whether `schema` already declares a model named `entity`. */
 export declare function hasPrismaModel(schema: string, entity: string): boolean;
-//# sourceMappingURL=resourcePrisma.template.d.ts.map

package/dist/src/templates/resource/layers/resourcePrisma.template.js

@@ -7,7 +7,7 @@
  */
 /** `repositories/<slug>.prisma.repository.ts`. */
 export function renderPrismaRepository(n, appSrcFromRepositories) {
-    const types = `Create${n.entity}Input, ${n.entity}, Update${n.entity}Input`;
+    const types = `Create${n.entity}Input, ${n.entity}, ${n.entity}Page, ${n.entity}PageRequest, Update${n.entity}Input`;
     const delegate = `prisma().${n.entityCamel}`;
     return `import { prisma } from "${appSrcFromRepositories}/integrations/database.js";
 import type { ${types} } from "../dtos/${n.slug}.dto.js";
@@ -29,17 +29,19 @@ function to${n.entity}(row: ${n.entity}Row): ${n.entity} {
   };
 }
 
-/** Most rows \`findAll\` returns; add pagination before raising it. */
-const LIST_LIMIT = 1000;
-
 /** Stores ${n.label} records in the \`${n.slug.replace(/-/g, "_")}\` table through Prisma. */
 export class Prisma${n.pascal}Repository implements ${n.pascal}Repository {
-  public async findAll(): Promise<readonly ${n.entity}[]> {
+  public async list(page: ${n.entity}PageRequest): Promise<${n.entity}Page> {
+    // Keyset pagination: one row more than asked tells whether a next page
+    // exists; \`cursor\` names the last row seen and \`skip: 1\` steps past it.
     const rows = await ${delegate}.findMany({
-      orderBy: { createdAt: "asc" },
-      take: LIST_LIMIT,
+      orderBy: [{ createdAt: "asc" }, { id: "asc" }],
+      take: page.limit + 1,
+      ...(page.cursor === undefined ? {} : { cursor: { id: page.cursor }, skip: 1 }),
     });
-    return rows.map(to${n.entity});
+    const items = rows.slice(0, page.limit).map(to${n.entity});
+    const last = items.at(-1);
+    return { items, nextCursor: rows.length > page.limit && last !== undefined ? last.id : null };
   }
 
   public async findById(id: string): Promise<${n.entity} | undefined> {
@@ -86,4 +88,3 @@ model ${n.entity} {
 export function hasPrismaModel(schema, entity) {
     return new RegExp(`^model\\s+${entity}\\s*\\{`, "m").test(schema);
 }
-//# sourceMappingURL=resourcePrisma.template.js.map

package/dist/src/templates/resource/layers/resourceService.template.d.ts

@@ -1,13 +1,6 @@
 /**
- * zudojs-cli — A resource's service and controller.
+ * zudojs-cli — A resource's service.
  */
 import type { ResourceNames } from "../resource.names.js";
 /** `services/<slug>.service.ts`: CRUD with NotFoundError for missing ids. */
 export declare function renderResourceService(n: ResourceNames): string;
-/**
- * `controllers/<slug>.controller.ts`: validates input with the DTO schemas
- * and maps service results to responses. Handlers are arrow properties so
- * they can be passed to the router unbound.
- */
-export declare function renderResourceController(n: ResourceNames, appSrcFromControllers: string): string;
-//# sourceMappingURL=resourceService.template.d.ts.map

package/dist/src/templates/resource/layers/resourceService.template.js

@@ -1,11 +1,12 @@
 /**
- * zudojs-cli — A resource's service and controller.
+ * zudojs-cli — A resource's service.
  */
 /** `services/<slug>.service.ts`: CRUD with NotFoundError for missing ids. */
 export function renderResourceService(n) {
-    const types = `Create${n.entity}Input, ${n.entity}, Update${n.entity}Input`;
+    const types = `Create${n.entity}Input, ${n.entity}, ${n.entity}Page, List${n.pascal}Query, Update${n.entity}Input`;
     return `import { NotFoundError } from "@zudojs/errors";
 
+import { DEFAULT_PAGE_SIZE } from "../dtos/${n.slug}.dto.js";
 import type { ${types} } from "../dtos/${n.slug}.dto.js";
 import type { ${n.pascal}Repository } from "../repositories/${n.slug}.repository.js";
 
@@ -13,8 +14,12 @@ import type { ${n.pascal}Repository } from "../repositories/${n.slug}.repository
 export class ${n.pascal}Service {
   public constructor(private readonly repository: ${n.pascal}Repository) {}
 
-  public list(): Promise<readonly ${n.entity}[]> {
-    return this.repository.findAll();
+  /** One page of ${n.label} records (\`limit\` defaults to DEFAULT_PAGE_SIZE). */
+  public list(query: List${n.pascal}Query): Promise<${n.entity}Page> {
+    return this.repository.list({
+      limit: query.limit ?? DEFAULT_PAGE_SIZE,
+      ...(query.cursor === undefined ? {} : { cursor: query.cursor }),
+    });
   }
 
   public async get(id: string): Promise<${n.entity}> {
@@ -43,53 +48,3 @@ function notFound(id: string): NotFoundError {
 }
 `;
 }
-/**
- * `controllers/<slug>.controller.ts`: validates input with the DTO schemas
- * and maps service results to responses. Handlers are arrow properties so
- * they can be passed to the router unbound.
- */
-export function renderResourceController(n, appSrcFromControllers) {
-    const schemas = `Create${n.entity}Schema, ${n.entity}ParamsSchema, Update${n.entity}Schema`;
-    return `import type { HttpResponseContext, HttpRouterContext } from "@zudojs/http";
-
-import { ${schemas} } from "../dtos/${n.slug}.dto.js";
-import type { ${n.pascal}Service } from "../services/${n.slug}.service.js";
-import { empty, json, readJsonBody, validationFailed } from "${appSrcFromControllers}/utils/http.js";
-
-/** HTTP handlers for ${n.routePath}. */
-export class ${n.pascal}Controller {
-  public constructor(private readonly service: ${n.pascal}Service) {}
-
-  public readonly list = async (): Promise<HttpResponseContext> =>
-    json(200, await this.service.list());
-
-  public readonly get = async (ctx: HttpRouterContext): Promise<HttpResponseContext> => {
-    const params = ${n.entity}ParamsSchema.safeParse(ctx.params);
-    if (!params.success) return validationFailed(params.issues);
-    return json(200, await this.service.get(params.data.id));
-  };
-
-  public readonly create = async (ctx: HttpRouterContext): Promise<HttpResponseContext> => {
-    const body = Create${n.entity}Schema.safeParse(readJsonBody(ctx));
-    if (!body.success) return validationFailed(body.issues);
-    return json(201, await this.service.create(body.data));
-  };
-
-  public readonly update = async (ctx: HttpRouterContext): Promise<HttpResponseContext> => {
-    const params = ${n.entity}ParamsSchema.safeParse(ctx.params);
-    if (!params.success) return validationFailed(params.issues);
-    const body = Update${n.entity}Schema.safeParse(readJsonBody(ctx));
-    if (!body.success) return validationFailed(body.issues);
-    return json(200, await this.service.update(params.data.id, body.data));
-  };
-
-  public readonly remove = async (ctx: HttpRouterContext): Promise<HttpResponseContext> => {
-    const params = ${n.entity}ParamsSchema.safeParse(ctx.params);
-    if (!params.success) return validationFailed(params.issues);
-    await this.service.remove(params.data.id);
-    return empty(204);
-  };
-}
-`;
-}
-//# sourceMappingURL=resourceService.template.js.map

package/dist/src/templates/resource/resource.files.d.ts

@@ -30,4 +30,3 @@ export interface ResourceWiring {
 }
 /** Describes how a resource is registered (see {@link ResourceWiring}). */
 export declare function resourceWiring(n: ResourceNames, layout: ResourceLayout): ResourceWiring;
-//# sourceMappingURL=resource.files.d.ts.map

package/dist/src/templates/resource/resource.files.js

@@ -36,7 +36,11 @@ export function resourceLayerPaths(n, layout, layer) {
         case "routes":
             return [joinPath(layout.base, "routes", `${n.slug}.routes.ts`)];
         case "test":
-            return [joinPath(layout.appRoot, "tests", `${n.slug}.test.ts`)];
+            // A module resource's test sits under tests/modules/<module>/, so two
+            // modules can each have a resource of the same name.
+            return [
+                joinPath(layout.appRoot, "tests", posix.relative(layout.appSrc, layout.base), `${n.slug}.test.ts`),
+            ];
     }
 }
 /** Renders `layers` of a resource as `{ path: content }`. */
@@ -65,11 +69,9 @@ export function renderResourceLayers(n, layout, layers) {
             case "routes":
                 files[path] = renderResourceRoutes(n);
                 break;
-            case "test": {
-                const tests = joinPath(layout.appRoot, "tests");
-                files[path] = renderResourceTest(n, posix.relative(tests, layout.base));
+            case "test":
+                files[path] = renderResourceTest(n, posix.relative(posix.dirname(path), layout.base));
                 break;
-            }
         }
     }
     return files;
@@ -96,4 +98,3 @@ export function resourceWiring(n, layout) {
         containerKey: key,
     };
 }
-//# sourceMappingURL=resource.files.js.map

package/dist/src/templates/resource/resource.names.d.ts

@@ -41,4 +41,3 @@ export declare function resourceNames(raw: string): ResourceNames;
  * Pass `capitalize` for the start of a sentence ("An example").
  */
 export declare function withArticle(noun: string, capitalize?: boolean): string;
-//# sourceMappingURL=resource.names.d.ts.map

package/dist/src/templates/resource/resource.names.js

@@ -72,4 +72,3 @@ export function withArticle(noun, capitalize = false) {
     const article = vowel ? "an" : "a";
     return `${capitalize ? article.charAt(0).toUpperCase() + article.slice(1) : article} ${noun}`;
 }
-//# sourceMappingURL=resource.names.js.map

package/dist/src/templates/resource/resource.type.d.ts

@@ -16,4 +16,3 @@ export interface ResourceLayout {
 export declare function toAppSrc(layout: ResourceLayout, layerDir: string): string;
 /** Joins path segments, dropping empty ones. */
 export declare function joinPath(...parts: readonly string[]): string;
-//# sourceMappingURL=resource.type.d.ts.map

package/dist/src/templates/resource/resource.type.js

@@ -12,4 +12,3 @@ export function toAppSrc(layout, layerDir) {
 export function joinPath(...parts) {
     return posix.join(...parts.filter((part) => part.length > 0));
 }
-//# sourceMappingURL=resource.type.js.map

package/dist/src/templates/shared/appRuntime.template.d.ts

@@ -52,4 +52,3 @@ export declare function renderModuleFile(options: {
 }): string;
 /** Renders a service class using the real `createLogger` factory. */
 export declare function renderServiceFile(name: string): string;
-//# sourceMappingURL=appRuntime.template.d.ts.map

package/dist/src/templates/shared/appRuntime.template.js

@@ -54,7 +54,6 @@ ${options.modules.map((m) => `    new ${m.className}(),`).join("\n")}${options.m
         : `\n      metadata: { port: ${options.port} },`;
     return `import type { Server } from "node:http";
 
-import { resolveEnvironment } from "@zudojs/constants";
 import { createContainer } from "@zudojs/container";
 import type { Module } from "@zudojs/core";
 import { createEventBus } from "@zudojs/events";
@@ -79,6 +78,10 @@ export interface AppOptions {
  * modules share, and the options describing this application. Integrations
  * (\`src/integrations\`) are registered first so they start before, and stop
  * after, every other module.
+ *
+ * The runtime's container is the one modules see as
+ * \`context.application.container\`; server.ts registers the composition
+ * root (\`container.ts\`) in it under \`APP_DEPENDENCIES\`.
  */
 export function createApp(options: AppOptions): Runtime {
   const logger = createLogger({ name: ${literal(options.applicationName)} });
@@ -97,9 +100,8 @@ ${registration}
     {
       applicationName: ${literal(options.applicationName)},
       applicationVersion: "0.1.0",
-      // NODE_ENV is read the same way the framework reads it: \`prod\` and
-      // \`Production\` are production, an unknown value warns once.
-      environment: resolveEnvironment(),
+      // Resolved once by loadConfig (configs/index.ts) from NODE_ENV.
+      environment: options.config.nodeEnv,
       // Signals are handled explicitly in server.ts.
       handleSignals: false,${metadata}
     },
@@ -166,4 +168,3 @@ export class ${className} {
 }
 `;
 }
-//# sourceMappingURL=appRuntime.template.js.map

package/dist/src/templates/shared/capability.template.d.ts

@@ -31,4 +31,3 @@ export declare function resolveProjectCapabilities(options: ScaffoldOptions): re
  * `zudojs add` and `zudojs doctor` use.
  */
 export declare function capabilityPackages(capabilities: readonly string[]): readonly string[];
-//# sourceMappingURL=capability.template.d.ts.map

package/dist/src/templates/shared/capability.template.js

@@ -59,4 +59,3 @@ export function capabilityPackages(capabilities) {
     }
     return [...packages];
 }
-//# sourceMappingURL=capability.template.js.map

package/dist/src/templates/shared/dockerfile/dockerfile.install.d.ts

@@ -32,4 +32,3 @@ export declare function lockedInstallSteps(packageManager: string): DockerInstal
  * package, so it cannot pin this app's isolated install.
  */
 export declare function workspaceMemberInstallSteps(packageManager: string): DockerInstallSteps;
-//# sourceMappingURL=dockerfile.install.d.ts.map

package/dist/src/templates/shared/dockerfile/dockerfile.install.js

@@ -86,4 +86,3 @@ export function workspaceMemberInstallSteps(packageManager) {
             };
     }
 }
-//# sourceMappingURL=dockerfile.install.js.map

package/dist/src/templates/shared/dockerfile/dockerfile.template.d.ts

@@ -35,4 +35,3 @@ export declare function renderWorkspaceAppDockerfile(options: {
     readonly port: number;
     readonly packageManager: string;
 }): string;
-//# sourceMappingURL=dockerfile.template.d.ts.map

package/dist/src/templates/shared/dockerfile/dockerfile.template.js

@@ -12,15 +12,26 @@ import { lockedInstallSteps, workspaceMemberInstallSteps, } from "./dockerfile.i
 function runnerFor(packageManager) {
     return packageManager === "npm" || packageManager === "bun" ? "npm" : packageManager;
 }
-/** The runtime stage of a single-package image. */
-function runtimeStage(port, dist, from) {
+/**
+ * The runtime stage of a single-package image. With Prisma, the schema,
+ * migrations and `prisma.config.ts` come along (the CLI is a runtime
+ * dependency), so the same image applies migrations.
+ */
+function runtimeStage(port, dist, from, prisma = false) {
+    const migrations = prisma
+        ? `COPY --from=build --chown=node:node ${from}/prisma ./prisma
+COPY --from=build --chown=node:node ${from}/prisma.config.ts ./
+# Apply migrations with this image before starting a new version:
+#   docker run --rm --env-file .env <image> npx prisma migrate deploy
+`
+        : "";
     return `FROM node:24-alpine AS runtime
 ENV NODE_ENV=production
 WORKDIR /app
 COPY --from=build --chown=node:node ${from}/package.json ./
 COPY --from=build --chown=node:node ${from}/node_modules ./node_modules
 COPY --from=build --chown=node:node ${from}/${dist} ./${dist}
-USER node
+${migrations}USER node
 EXPOSE ${port}
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s CMD ["node", "-e", "fetch('http://127.0.0.1:${port}/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
 CMD ["node", "${dist}/server.js"]
@@ -58,7 +69,7 @@ export function renderAppPackageDockerfile(options) {
         ...(steps.prune === undefined ? [] : [`RUN ${steps.prune}`]),
         "",
     ];
-    return `${lines.join("\n")}\n${runtimeStage(options.port, "dist", "/app")}`;
+    return `${lines.join("\n")}\n${runtimeStage(options.port, "dist", "/app", options.prisma === true)}`;
 }
 /**
  * A Dockerfile for a workspace whose server lives in `appDirectory`. The whole
@@ -92,4 +103,3 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=15s CMD ["node", "-e", "f
 CMD ["node", "${dist}/server.js"]
 `;
 }
-//# sourceMappingURL=dockerfile.template.js.map

package/dist/src/templates/shared/dockerfile/index.d.ts

@@ -3,4 +3,3 @@
  */
 export * from "./dockerfile.template.js";
 export * from "./dockerfile.install.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/templates/shared/dockerfile/index.js

@@ -3,4 +3,3 @@
  */
 export * from "./dockerfile.template.js";
 export * from "./dockerfile.install.js";
-//# sourceMappingURL=index.js.map

package/dist/src/templates/shared/index.d.ts

@@ -5,5 +5,5 @@ export * from "./appRuntime.template.js";
 export * from "./capability.template.js";
 export * from "./dockerfile/index.js";
 export * from "./pnpm.template.js";
+export { renderShutdownBlock } from "./server.parts.js";
 export * from "./server.template.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/templates/shared/index.js

@@ -5,5 +5,5 @@ export * from "./appRuntime.template.js";
 export * from "./capability.template.js";
 export * from "./dockerfile/index.js";
 export * from "./pnpm.template.js";
+export { renderShutdownBlock } from "./server.parts.js";
 export * from "./server.template.js";
-//# sourceMappingURL=index.js.map

package/dist/src/templates/shared/pnpm.template.d.ts

@@ -30,4 +30,3 @@ export declare const PNPM_ALLOWED_BUILD_SCRIPTS: readonly ["esbuild", "@swc/core
  * when it writes the file itself.
  */
 export declare function renderPnpmWorkspaceFile(packages?: readonly string[]): string;
-//# sourceMappingURL=pnpm.template.d.ts.map

package/dist/src/templates/shared/pnpm.template.js

@@ -62,4 +62,3 @@ export function renderPnpmWorkspaceFile(packages = []) {
     lines.push("");
     return lines.join("\n");
 }
-//# sourceMappingURL=pnpm.template.js.map

package/dist/src/templates/shared/server.parts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * zudojs-cli — Fragments of the generated `src/server.ts`.
+ *
+ * The OpenAPI lines (also inserted by `zudojs add openapi`) and the
+ * shutdown block. `server.template.ts` assembles them.
+ */
+/**
+ * The lines `zudojs add openapi` (or `create`) puts in server.ts.
+ *
+ * The documentation page is served in every environment but production:
+ * it lists every route and its schemas, which a public deployment should
+ * not hand out by default. `/openapi.json` stays, for clients and tooling.
+ */
+export declare function openApiServerLines(title: string): {
+    readonly importLine: string;
+    readonly mountLine: string;
+};
+/**
+ * The SIGINT/SIGTERM handlers and the "Listening on" line.
+ *
+ * The signal listeners stay registered (`process.on`, not `once`) for the
+ * whole shutdown. Under `tsx watch`, Ctrl+C delivers SIGINT twice (from the
+ * terminal and forwarded by the watcher); with `once` the second signal
+ * found no listener and Node's default action killed the process before
+ * the runtime had stopped or logged anything. "Listening on" is logged once
+ * the listeners are in place, so a signal sent after it is always handled.
+ */
+export declare function renderShutdownBlock(): string;

package/dist/src/templates/shared/server.parts.js

@@ -0,0 +1,59 @@
+/**
+ * zudojs-cli — Fragments of the generated `src/server.ts`.
+ *
+ * The OpenAPI lines (also inserted by `zudojs add openapi`) and the
+ * shutdown block. `server.template.ts` assembles them.
+ */
+/** Emits a string as a TypeScript string literal that cannot break out. */
+function literal(value) {
+    return JSON.stringify(value);
+}
+/**
+ * The lines `zudojs add openapi` (or `create`) puts in server.ts.
+ *
+ * The documentation page is served in every environment but production:
+ * it lists every route and its schemas, which a public deployment should
+ * not hand out by default. `/openapi.json` stays, for clients and tooling.
+ */
+export function openApiServerLines(title) {
+    return {
+        importLine: `import { mountOpenAPI } from "@zudojs/http";`,
+        mountLine: `mountOpenAPI(router, { info: { title: ${literal(title)}, version: "0.1.0" }, docsPath: config.nodeEnv === "production" ? false : "/docs" });`,
+    };
+}
+/**
+ * The SIGINT/SIGTERM handlers and the "Listening on" line.
+ *
+ * The signal listeners stay registered (`process.on`, not `once`) for the
+ * whole shutdown. Under `tsx watch`, Ctrl+C delivers SIGINT twice (from the
+ * terminal and forwarded by the watcher); with `once` the second signal
+ * found no listener and Node's default action killed the process before
+ * the runtime had stopped or logged anything. "Listening on" is logged once
+ * the listeners are in place, so a signal sent after it is always handled.
+ */
+export function renderShutdownBlock() {
+    return `let stopping = false;
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => {
+    if (stopping) {
+      console.log(\`Received \${signal} again: already shutting down.\`);
+      return;
+    }
+    stopping = true;
+    console.log(\`Received \${signal}: shutting down.\`);
+    void drainIntegrations(integrations)
+      .then(() => server.stop())
+      .then(() => runtime.stop())
+      .then(() => {
+        process.exit(0);
+      })
+      .catch((error: unknown) => {
+        console.error(error);
+        process.exit(1);
+      });
+  });
+}
+
+console.log(\`Listening on http://\${config.host}:\${server.address?.port ?? config.port}\`);
+`;
+}

package/dist/src/templates/shared/server.template.d.ts

@@ -1,27 +1,27 @@
 /**
  * zudojs-cli — Generated `src/server.ts`
  *
- * The entry point loads the configuration, builds a router with
- * `createRouter()`, registers every route through `registerRoutes` (from
- * the composition root in `container.ts`), mounts the OpenAPI document and
- * `/docs` page when the `openapi` capability is on, and serves the router
- * with `createHttpServer` + `createNodeHttpAdapter`.
+ * The entry point loads the configuration, builds the runtime with
+ * `createApp()`, constructs the composition root (`container.ts`) and
+ * registers it in the runtime's DI container, builds a router with
+ * `createRouter()`, registers every route through `registerRoutes`, mounts
+ * the OpenAPI document (and, outside production, the `/docs` page) when the
+ * `openapi` capability is on, and serves the router with `createHttpServer`
+ * + `createNodeHttpAdapter`.
  *
  * Every response passes through the @zudojs/security default headers, a
  * CORS policy that allows only `CORS_ORIGINS` (none by default) and a
- * per-client rate limit (`RATE_LIMIT_MAX` per `RATE_LIMIT_WINDOW_MS`). Exposed
- * 4xx errors are answered with their status; anything else is a generic
- * 500. On SIGINT/SIGTERM integrations drain, HTTP stops, then the runtime
- * stops. `tests/generatedProject.typecheck.test.ts` type-checks the output
- * against the current `@zudojs/*` sources.
- *
- * The signal listeners stay registered (`process.on`, not `once`) for the
- * whole shutdown. Under `tsx watch`, Ctrl+C delivers SIGINT twice (from the
- * terminal and forwarded by the watcher); with `once` the second signal
- * found no listener and Node's default action killed the process before
- * the runtime had stopped or logged anything. "Listening on" is logged once
- * the listeners are in place, so a signal sent after it is always handled.
+ * per-client rate limit (`RATE_LIMIT_MAX` per `RATE_LIMIT_WINDOW_MS`; 0
+ * turns it off). Exposed errors are answered with their status; anything
+ * else is logged with the runtime's logger and answered with a generic 500
+ * built inside the pipeline, so it carries the security headers too. It
+ * used to rethrow, which left the adapter to answer a bare 500 that nothing
+ * logged. On SIGINT/SIGTERM integrations drain, HTTP stops, then the
+ * runtime stops (see `server.parts.ts`).
+ * `tests/generatedProject.typecheck.test.ts` type-checks the output against
+ * the current `@zudojs/*` sources; `tests/cli.round12.server.test.ts` runs it.
  */
+export { openApiServerLines } from "./server.parts.js";
 /** Options for {@link renderServerFile}. */
 export interface ServerFileOptions {
     /** Title of the OpenAPI document. */
@@ -29,11 +29,5 @@ export interface ServerFileOptions {
     /** Whether `/openapi.json` and `/docs` are mounted. */
     readonly openapi: boolean;
 }
-/** The lines `zudojs add openapi` (or `create`) puts in server.ts. */
-export declare function openApiServerLines(title: string): {
-    readonly importLine: string;
-    readonly mountLine: string;
-};
 /** Renders `src/server.ts`. */
 export declare function renderServerFile(options: ServerFileOptions): string;
-//# sourceMappingURL=server.template.d.ts.map