@beignet/cli 0.0.36 → 0.0.38

package/src/outbox.ts

@@ -1,5 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import type { ErrorReporterPort } from "@beignet/core/error-reporting";
 import type {
   DrainOutboxOptions,
   DrainOutboxResult,
@@ -11,6 +12,10 @@ import type {
 } from "@beignet/core/outbox";
 import { createJiti } from "jiti";
 import { loadBeignetConfig, normalizePath } from "./config.js";
+import {
+  flushOperationalErrorReporter,
+  reportOperationalFailure,
+} from "./operational-error-reporting.js";
 
 /**
  * Options for running one bounded outbox drain pass.
@@ -159,6 +164,7 @@ type OutboxDrainPorts = {
   logger?: OutboxDrainLogger;
   devtools?: OutboxDrainInstrumentation;
   instrumentation?: OutboxDrainInstrumentation;
+  errorReporter?: ErrorReporterPort;
 };
 
 type OutboxDrainContext = {
@@ -240,6 +246,60 @@ export async function runOutboxDrain(
           attempts: message.attempts,
         });
       },
+      onDeadLetter(error, message) {
+        return reportOperationalFailure({
+          ctx,
+          error,
+          reportOptions: {
+            level: "error",
+            mechanism: "beignet.outbox.cli",
+            handled: false,
+            tags: {
+              "beignet.kind": "outbox",
+              "beignet.outbox.kind": message.kind,
+              "beignet.outbox.name": message.name,
+              "beignet.outbox.outcome": "deadLettered",
+            },
+            contexts: {
+              outbox: {
+                messageId: message.id,
+                kind: message.kind,
+                name: message.name,
+                attempts: message.attempts,
+                maxAttempts: message.maxAttempts,
+                outcome: "deadLettered",
+              },
+            },
+          },
+        });
+      },
+      onSettlementError(settlementError, message) {
+        return reportOperationalFailure({
+          ctx,
+          error: settlementError,
+          reportOptions: {
+            level: "error",
+            mechanism: "beignet.outbox.cli",
+            handled: false,
+            tags: {
+              "beignet.kind": "outbox",
+              "beignet.outbox.kind": message.kind,
+              "beignet.outbox.name": message.name,
+              "beignet.outbox.outcome": "settlementFailed",
+            },
+            contexts: {
+              outbox: {
+                messageId: message.id,
+                kind: message.kind,
+                name: message.name,
+                attempts: message.attempts,
+                maxAttempts: message.maxAttempts,
+                outcome: "settlementFailed",
+              },
+            },
+          },
+        });
+      },
     });
 
     await recordOutboxDrain(ctx, result);
@@ -251,7 +311,24 @@ export async function runOutboxDrain(
       result,
       durationMs: Math.round(performance.now() - startedAt),
     };
+  } catch (error) {
+    await reportOperationalFailure({
+      ctx,
+      error,
+      reportOptions: {
+        level: "error",
+        mechanism: "beignet.outbox.cli",
+        handled: false,
+        tags: {
+          "beignet.kind": "outbox",
+          "beignet.outbox.outcome": "drainFailed",
+        },
+        contexts: { outbox: { outcome: "drainFailed" } },
+      },
+    });
+    throw error;
   } finally {
+    await flushOperationalErrorReporter(ctx);
     await outboxModule.stopOutboxDrainContext?.(ctx, contextArgs);
   }
 }

package/src/provider-add.ts

@@ -97,7 +97,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-flags-openfeature`",
       "- Peer dependency: `@openfeature/server-sdk`",
-      "- The preset wires `createOpenFeatureFlagsProvider()` in `server/providers.ts` and defers `flags` in `infra/app-ports.ts`.",
+      "- The preset wires `createOpenFeatureFlagsProvider()` in `server/providers.ts` and defers `flags` in `infra/port-wiring.ts`.",
       "- Configure the OpenFeature provider globally or replace this preset with `createOpenFeatureFlagsProvider(...)` when the app needs provider-specific setup.",
       "- Use `ctx.ports.flags` in app code; `ctx.ports.openFeature` is available as an escape hatch.",
       "",
@@ -138,7 +138,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-jobs-bullmq`",
       "- Peer dependency: `bullmq`",
-      "- The preset wires `createBullMQJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/app-ports.ts`.",
+      "- The preset wires `createBullMQJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/port-wiring.ts`.",
       "- Set `BULLMQ_REDIS_URL` before booting the app; the default points at local Redis.",
       "- Dispatching enqueues jobs, but nothing executes them until a worker entrypoint runs `createBullMQJobWorker(...)` in a worker process. See the jobs docs page.",
       "- Use `ctx.ports.jobs.dispatch(...)` in app code; `ctx.ports.bullMQJobs` is available as an escape hatch.",
@@ -180,7 +180,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-jobs-inngest`",
       "- Peer dependency: `inngest`",
-      "- The preset wires `createInngestJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/app-ports.ts`.",
+      "- The preset wires `createInngestJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/port-wiring.ts`.",
       "- Define jobs with `defineJob(...)` and dispatch them through `ctx.ports.jobs.dispatch(...)`.",
       "- Execution needs an Inngest serve route built from `createInngestJobFunction(...)` and `serve(...)`. See the jobs docs page.",
       "- Use `ctx.ports.inngest` only as an escape hatch for Inngest-specific workflow APIs; prefer `ctx.ports.jobs.dispatch(...)` for Beignet jobs.",
@@ -222,7 +222,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-mail-resend`",
       "- Peer dependency: `resend`",
-      "- The preset wires `createResendMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/app-ports.ts`.",
+      "- The preset wires `createResendMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `RESEND_API_KEY` and `RESEND_FROM` values before sending mail.",
       "- Use `ctx.ports.mailer` in app code; `ctx.ports.resend` is available as an escape hatch.",
       "",
@@ -268,7 +268,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-mail-smtp`",
       "- Peer dependency: `nodemailer`",
-      "- The preset wires `createSmtpMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/app-ports.ts`.",
+      "- The preset wires `createSmtpMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `MAIL_*` values before sending mail.",
       "- Use `ctx.ports.mailer` in app code; `ctx.ports.smtp` is available as an escape hatch.",
       "",
@@ -317,7 +317,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-payments-stripe`",
       "- Peer dependency: `stripe`",
-      "- The preset wires `createStripePaymentsProvider()` in `server/providers.ts` and defers `payments` in `infra/app-ports.ts`.",
+      "- The preset wires `createStripePaymentsProvider()` in `server/providers.ts` and defers `payments` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` values before taking payments.",
       "- Stripe requires a webhook route: run `beignet make payments` for the full billing slice, including a `createPaymentWebhookRoute(...)` route.",
       "- Use `ctx.ports.payments` in app code; `ctx.ports.stripe` is available as an escape hatch.",
@@ -360,7 +360,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "## Meilisearch search",
       "",
       "- Package: `@beignet/provider-search-meilisearch`",
-      "- The preset wires `createMeilisearchSearchProvider()` in `server/providers.ts` and defers `search` in `infra/app-ports.ts`.",
+      "- The preset wires `createMeilisearchSearchProvider()` in `server/providers.ts` and defers `search` in `infra/port-wiring.ts`.",
       "- Set `MEILISEARCH_HOST` before booting the app; set `MEILISEARCH_API_KEY` when your Meilisearch server requires one.",
       "- Use `ctx.ports.search` in app code; `ctx.ports.meilisearch` is available as an escape hatch.",
       "",
@@ -434,7 +434,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-cache-redis`",
       "- Peer dependency: `ioredis`",
-      "- The preset wires `createRedisCacheProvider()` in `server/providers.ts` and defers `cache` in `infra/app-ports.ts`.",
+      "- The preset wires `createRedisCacheProvider()` in `server/providers.ts` and defers `cache` in `infra/port-wiring.ts`.",
       "- Set `REDIS_URL` before booting the app.",
       "- Use `ctx.ports.cache` in app code; `ctx.ports.redis` is available as an escape hatch.",
       "",
@@ -475,7 +475,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-event-bus-redis`",
       "- Peer dependency: `ioredis`",
-      "- The preset wires `createRedisEventBusProvider()` in `server/providers.ts` and defers `eventBus` in `infra/app-ports.ts`.",
+      "- The preset wires `createRedisEventBusProvider()` in `server/providers.ts` and defers `eventBus` in `infra/port-wiring.ts`.",
       "- Set `REDIS_EVENT_BUS_URL` before booting the app.",
       "- Redis Pub/Sub delivery is best-effort and cross-process, but not durable: use outbox/jobs for side effects that need retry, replay, or dead-letter handling.",
       "- Use `ctx.ports.eventBus` in app code; `ctx.ports.redisEventBus` is available as an escape hatch.",
@@ -518,7 +518,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-locks-redis`",
       "- Peer dependency: `ioredis`",
-      "- The preset wires `createRedisLocksProvider()` in `server/providers.ts` and defers `locks` in `infra/app-ports.ts`.",
+      "- The preset wires `createRedisLocksProvider()` in `server/providers.ts` and defers `locks` in `infra/port-wiring.ts`.",
       "- Set `REDIS_LOCKS_URL` before booting the app.",
       "- Use `ctx.ports.locks` in app code; `ctx.ports.redisLocks` is available as an escape hatch.",
       "",
@@ -579,7 +579,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-storage-s3`",
       "- Peer dependencies: `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`",
-      "- The preset wires `createS3StorageProvider()` in `server/providers.ts` and defers `storage` in `infra/app-ports.ts`.",
+      "- The preset wires `createS3StorageProvider()` in `server/providers.ts` and defers `storage` in `infra/port-wiring.ts`.",
       "- Set `STORAGE_S3_BUCKET` before booting the app; set endpoint and credentials when using an S3-compatible host outside AWS defaults.",
       "- Use `ctx.ports.storage` in app code; `ctx.ports.s3Storage` is available as an escape hatch.",
       "",
@@ -625,7 +625,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-storage-vercel-blob`",
       "- Peer dependency: `@vercel/blob`",
-      "- The preset wires `createVercelBlobStorageProvider()` in `server/providers.ts` and defers `storage` in `infra/app-ports.ts`.",
+      "- The preset wires `createVercelBlobStorageProvider()` in `server/providers.ts` and defers `storage` in `infra/port-wiring.ts`.",
       "- On Vercel, connect a Blob store to the project and `BLOB_READ_WRITE_TOKEN` is set automatically; set it manually elsewhere.",
       "- The store is uniform-visibility (`BLOB_ACCESS`, default `private`): Vercel Blob does not report per-object access back, so mixed visibility needs a second store.",
       "- Use `ctx.ports.storage` in app code; `ctx.ports.vercelBlob` is available as an escape hatch.",
@@ -673,7 +673,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-rate-limit-upstash`",
       "- Peer dependencies: `@upstash/ratelimit` and `@upstash/redis`",
-      "- The preset wires `createUpstashRateLimitProvider()` in `server/providers.ts` and defers `rateLimit` in `infra/app-ports.ts`.",
+      "- The preset wires `createUpstashRateLimitProvider()` in `server/providers.ts` and defers `rateLimit` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` values before rate limiting requests.",
       "- Use `ctx.ports.rateLimit` in app code; `ctx.ports.upstash` is available as an escape hatch.",
       "",
@@ -778,9 +778,9 @@ export async function addProviderPreset(
       ),
     },
     {
-      path: config.paths.infrastructurePorts,
+      path: config.paths.portWiring,
       content: updateInfrastructurePortsFile(
-        await readRequiredAppFile(targetDir, config.paths.infrastructurePorts),
+        await readRequiredAppFile(targetDir, config.paths.portWiring),
         preset.appPort.key,
       ),
     },
@@ -1056,13 +1056,17 @@ function ensureTypeProperty(
 function ensureDeferredPort(source: string, portKey: string): string {
   const match = /\bdeferred\s*:\s*\[/.exec(source);
   if (!match) {
-    throw new Error("Could not find `deferred: [...]` in infra/app-ports.ts.");
+    throw new Error(
+      "Could not find `deferred: [...]` in infra/port-wiring.ts.",
+    );
   }
 
   const openBracket = source.indexOf("[", match.index);
   const closeBracket = matchingDelimiterIndex(source, openBracket, "[", "]");
   if (closeBracket === -1) {
-    throw new Error("Could not parse `deferred` array in infra/app-ports.ts.");
+    throw new Error(
+      "Could not parse `deferred` array in infra/port-wiring.ts.",
+    );
   }
 
   const arrayText = source.slice(openBracket, closeBracket + 1);

package/src/provider-audit.ts

@@ -149,7 +149,7 @@ export async function auditProviders(
     ? await readCachedSource(targetDir, config.paths.ports, sourceCache)
     : "";
   const infrastructurePath = directoryPath(
-    path.dirname(config.paths.infrastructurePorts),
+    path.dirname(config.paths.portWiring),
   );
   const schemaDir = `${infrastructurePath}/db/schema`;
 
@@ -1015,6 +1015,14 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function configuredProviderRequiredEnv(
+  envVars: readonly string[],
+  config: ResolvedBeignetConfig,
+): string[] {
+  const ignored = new Set(config.providerAudit.ignoreRequiredEnv);
+  return envVars.filter((envVar) => !ignored.has(envVar));
+}
+
 function configuredProviderRequiredTables(
   tableNames: readonly string[],
   config: ResolvedBeignetConfig,
@@ -1140,13 +1148,18 @@ async function providerAuditEntryForRule(options: {
   const requiredEnv =
     options.rule.variants !== undefined
       ? aggregateVariantRequirement(variants, "requiredEnv")
-      : await requirementAudit(options.rule.requiredEnv ?? [], (envVar) =>
-          providerRequiredEnvExists(
-            options.targetDir,
-            options.configFiles,
-            envVar,
-            options.sourceCache,
+      : await requirementAudit(
+          configuredProviderRequiredEnv(
+            options.rule.requiredEnv ?? [],
+            options.config,
           ),
+          (envVar) =>
+            providerRequiredEnvExists(
+              options.targetDir,
+              options.configFiles,
+              envVar,
+              options.sourceCache,
+            ),
         );
 
   const requiredTables =
@@ -1222,12 +1235,16 @@ async function providerVariantAudit(options: {
   variant: ProviderDoctorVariantRule;
   registered: boolean;
 }): Promise<ProviderVariantAudit> {
+  const requiredEnv = configuredProviderRequiredEnv(
+    options.variant.requiredEnv,
+    options.config,
+  );
   if (!options.registered) {
     return {
       name: options.variant.name,
       displayName: options.variant.displayName,
       registration: "inactive",
-      requiredEnv: inactiveRequirement(options.variant.requiredEnv),
+      requiredEnv: inactiveRequirement(requiredEnv),
       requiredTables: inactiveRequirement(options.variant.requiredTables),
     };
   }
@@ -1240,7 +1257,7 @@ async function providerVariantAudit(options: {
       options.variant.registrationSeverity,
       options.providerEntries,
     ),
-    requiredEnv: await requirementAudit(options.variant.requiredEnv, (envVar) =>
+    requiredEnv: await requirementAudit(requiredEnv, (envVar) =>
       providerRequiredEnvExists(
         options.targetDir,
         options.configFiles,
@@ -1662,13 +1679,13 @@ function isInfraOrServerFile(
 ): boolean {
   const serverDir = directoryPath(path.dirname(config.paths.server));
   const infrastructureDir = directoryPath(
-    path.dirname(config.paths.infrastructurePorts),
+    path.dirname(config.paths.portWiring),
   );
 
   return (
     file === config.paths.server ||
     file.startsWith(`${serverDir}/`) ||
-    file === config.paths.infrastructurePorts ||
+    file === config.paths.portWiring ||
     file.startsWith(`${infrastructureDir}/`)
   );
 }

package/src/schedule.ts

@@ -1,5 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import type { ErrorReporterPort } from "@beignet/core/error-reporting";
 import type { ProviderInstrumentationPort } from "@beignet/core/providers";
 import type {
   ScheduleDef,
@@ -8,6 +9,10 @@ import type {
 } from "@beignet/core/schedules";
 import { createJiti } from "jiti";
 import { loadBeignetConfig, normalizePath } from "./config.js";
+import {
+  flushOperationalErrorReporter,
+  reportOperationalFailure,
+} from "./operational-error-reporting.js";
 
 /**
  * Options for running one app-owned schedule.
@@ -56,6 +61,7 @@ type ScheduleContext = {
     logger?: ScheduleLogger;
     devtools?: ProviderInstrumentationPort;
     instrumentation?: ProviderInstrumentationPort;
+    errorReporter?: ErrorReporterPort;
   };
 };
 
@@ -131,7 +137,31 @@ export async function runAppSchedule(
       },
     });
 
-    await runner.run(schedule, runOptions);
+    try {
+      await runner.run(schedule, runOptions);
+    } catch (error) {
+      await reportOperationalFailure({
+        ctx: scheduleContext,
+        error,
+        reportOptions: {
+          level: "error",
+          mechanism: "beignet.schedule.cli",
+          handled: false,
+          tags: {
+            "beignet.kind": "schedule",
+            "beignet.schedule": schedule.name,
+          },
+          contexts: {
+            schedule: {
+              name: schedule.name,
+              source: runOptions.source ?? "beignet-cli",
+              attempt: runOptions.attempt ?? null,
+            },
+          },
+        },
+      });
+      throw error;
+    }
 
     return {
       schemaVersion: 1,
@@ -148,6 +178,7 @@ export async function runAppSchedule(
       durationMs: Math.round(performance.now() - startedAt),
     };
   } finally {
+    await flushOperationalErrorReporter(scheduleContext);
     await scheduleModule.stopScheduleContext?.(ctx, contextArgs);
   }
 }

package/src/task.ts

@@ -3,6 +3,11 @@ import path from "node:path";
 import type { TaskDef, TaskRunContextArgs } from "@beignet/core/tasks";
 import { createJiti } from "jiti";
 import { loadBeignetConfig, normalizePath } from "./config.js";
+import {
+  flushOperationalErrorReporter,
+  type OperationalErrorReportingContext,
+  reportOperationalFailure,
+} from "./operational-error-reporting.js";
 
 /**
  * Options for running an app-owned operational task.
@@ -63,10 +68,35 @@ export async function runAppTask(
     : {};
 
   try {
-    const output = await runTask(task, {
-      input: parsedInput,
-      ctx,
-    });
+    let output: unknown;
+    try {
+      output = await runTask(task, {
+        input: parsedInput,
+        ctx,
+      });
+    } catch (error) {
+      await reportOperationalFailure({
+        ctx: toOperationalContext(ctx),
+        error,
+        reportOptions: {
+          level: "error",
+          mechanism: "beignet.task.cli",
+          handled: false,
+          tags: {
+            "beignet.kind": "task",
+            "beignet.task": task.name,
+          },
+          contexts: {
+            task: {
+              name: task.name,
+              tenant: options.tenant ?? null,
+              source: "beignet-cli",
+            },
+          },
+        },
+      });
+      throw error;
+    }
 
     return {
       schemaVersion: 1,
@@ -79,10 +109,17 @@ export async function runAppTask(
       durationMs: Math.round(performance.now() - startedAt),
     };
   } finally {
+    await flushOperationalErrorReporter(toOperationalContext(ctx));
     await taskModule.stopTaskContext?.(ctx, contextArgs);
   }
 }
 
+function toOperationalContext(ctx: unknown): OperationalErrorReportingContext {
+  return typeof ctx === "object" && ctx !== null
+    ? (ctx as OperationalErrorReportingContext)
+    : {};
+}
+
 function parseTaskInputFlag(input: RunAppTaskOptions["input"]): unknown {
   if (input === undefined) return {};
   if (typeof input !== "string") return input;

package/src/templates/base.ts

@@ -314,7 +314,7 @@ Use \`${cli} make feature projects --recipe full-slice\` when you want a richer
 - \`features/shared/errors.ts\` keeps application errors and route-owned error schemas together.
 - \`ports/\` defines app-owned dependencies.
 - \`infra/\` implements ports for the selected runtime.
-- \`infra/db/schema/\` contains the Drizzle schema, \`drizzle/\` contains the checked-in migrations, and \`infra/todos/\` contains the durable todo repository adapter.
+- \`infra/db/client.ts\` owns the process-wide database client shared by Better Auth and the Beignet provider; the public server \`stop()\` closes it after provider shutdown. \`infra/db/schema/\` contains the Drizzle schema, \`drizzle/\` contains the checked-in migrations, and \`infra/todos/\` contains the durable todo repository adapter.
 - \`server/routes.ts\` keeps the central route registry and OpenAPI contract list.
 - \`server/context.ts\` declares the context blueprint shared by the server and route tests.
 - \`server/providers.ts\` wires devtools, Better Auth, pino, ${
@@ -342,6 +342,7 @@ ${optionalAuthRedirects}
           cli +
           " db migrate` against it before starting the app."
   }
+- Size the process-wide database client for the deployment. Postgres and MySQL use the generated pool-limit environment variable; count web, worker, preview, and task processes against the database connection limit, and keep writable SQLite files on one host.
 - Run \`${cli} db generate\` and \`${cli} db migrate\` after changing the Drizzle schema.
 - Run \`${cli} db reset\` to rebuild a local ${
     ctx.database === "sqlite"
@@ -438,11 +439,15 @@ export function envExample(ctx: TemplateContext): string {
             "# Local Postgres matching the docker one-liner below; point at your own server in production.",
             `# ${databaseStartCommand("postgres", ctx.name)}`,
             `POSTGRES_DB_URL=${databaseLocalUrl("postgres", ctx.name)}`,
+            "# Maximum connections opened by each running app process.",
+            "POSTGRES_DB_POOL_MAX=5",
           ]
         : [
             "# Local MySQL matching the docker one-liner below; point at your own server in production.",
             `# ${databaseStartCommand("mysql", ctx.name)}`,
             `MYSQL_DB_URL=${databaseLocalUrl("mysql", ctx.name)}`,
+            "# Maximum connections opened by each running app process.",
+            "MYSQL_DB_POOL_MAX=5",
           ];
 
   const lines = [

package/src/templates/db/index.ts

@@ -10,6 +10,7 @@ import { sqliteDbFiles } from "./sqlite.js";
  */
 export type DbTemplateFiles = {
   drizzleConfig: string;
+  dbClient: string;
   dbSchema: string;
   drizzleTodoRepository: string;
   dbRepositories: string;

package/src/templates/db/mysql.ts

@@ -36,6 +36,22 @@ export function mysqlDbFiles(ctx: TemplateContext): DbTemplateFiles {
 		url: process.env.MYSQL_DB_URL ?? "${databaseLocalUrl("mysql", ctx.name)}",
 	},
 };
+`,
+    dbClient: `import "@beignet/core/server-only";
+import mysql from "mysql2/promise";
+import { env } from "@/lib/env";
+
+export const databaseClient = mysql.createPool({
+	uri: env.MYSQL_DB_URL,
+	connectionLimit: env.MYSQL_DB_POOL_MAX,
+});
+
+let closePromise: Promise<void> | undefined;
+
+export function closeDatabaseClient(): Promise<void> {
+	closePromise ??= Promise.resolve().then(() => databaseClient.end());
+	return closePromise;
+}
 `,
     dbSchema: `import {
 	boolean,

package/src/templates/db/postgres.ts

@@ -33,6 +33,22 @@ export function postgresDbFiles(ctx: TemplateContext): DbTemplateFiles {
 		url: process.env.POSTGRES_DB_URL ?? "${databaseLocalUrl("postgres", ctx.name)}",
 	},
 };
+`,
+    dbClient: `import "@beignet/core/server-only";
+import pg from "pg";
+import { env } from "@/lib/env";
+
+export const databaseClient = new pg.Pool({
+	connectionString: env.POSTGRES_DB_URL,
+	max: env.POSTGRES_DB_POOL_MAX,
+});
+
+let closePromise: Promise<void> | undefined;
+
+export function closeDatabaseClient(): Promise<void> {
+	closePromise ??= Promise.resolve().then(() => databaseClient.end());
+	return closePromise;
+}
 `,
     dbSchema: `import { boolean, index, pgTable, text, timestamp } from "drizzle-orm/pg-core";
 

package/src/templates/db/sqlite.ts

@@ -24,6 +24,22 @@ const files = {
 		authToken: process.env.SQLITE_DB_AUTH_TOKEN,
 	},
 };
+`,
+  dbClient: `import "@beignet/core/server-only";
+import { createClient } from "@libsql/client";
+import { env } from "@/lib/env";
+
+export const databaseClient = createClient({
+	url: env.SQLITE_DB_URL,
+	authToken: env.SQLITE_DB_AUTH_TOKEN,
+});
+
+let closePromise: Promise<void> | undefined;
+
+export function closeDatabaseClient(): Promise<void> {
+	closePromise ??= Promise.resolve().then(() => databaseClient.close());
+	return closePromise;
+}
 `,
   dbSchema: `import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
 

package/src/templates/index.ts

@@ -19,8 +19,8 @@ import { dbFiles } from "./db/index.js";
 import {
   betterAuth,
   env,
-  infrastructurePorts,
   ports,
+  portWiring,
   server,
   serverFiles,
   serverProviders,
@@ -109,7 +109,8 @@ export function getTemplateFiles(ctx: TemplateContext): TemplateFile[] {
     },
     { path: "ports/index.ts", content: ports(ctx) },
     { path: "ports/auth.ts", content: serverFiles.authPort },
-    { path: "infra/app-ports.ts", content: infrastructurePorts(ctx) },
+    { path: "infra/port-wiring.ts", content: portWiring(ctx) },
+    { path: "infra/db/client.ts", content: db.dbClient },
     { path: "infra/db/database-ready.ts", content: db.databaseReady },
     { path: "infra/db/provider.ts", content: db.dbProvider },
     { path: "infra/db/repositories.ts", content: db.dbRepositories },
@@ -137,7 +138,7 @@ export function getTemplateFiles(ctx: TemplateContext): TemplateFile[] {
     ...testSupportTemplateFiles,
     { path: "lib/use-case.ts", content: serverFiles.useCaseBuilder },
     { path: "lib/routes.ts", content: serverFiles.routesBuilder },
-    { path: "server/index.ts", content: server(ctx) },
+    { path: "server/index.ts", content: server() },
     { path: "server/context.ts", content: serverFiles.serverContext },
     { path: "server/routes.ts", content: serverFiles.serverRoutes },
     { path: "server/providers.ts", content: serverProviders(ctx) },