@zerotal/core 1.0.0

package/src/command/builtin/StatusCommand.ts

@@ -0,0 +1,71 @@
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt status` — shows live metrics from the running server.
+ *
+ * Fetches GET /__zerotal/health from the running server and pretty-prints the
+ * metrics: uptime, pending HTTP requests, open WebSockets, memory, Bun version.
+ *
+ * The health endpoint is auto-enabled in development. For production, set
+ * `health: true` in config/app.ts.
+ *
+ * @category Diagnostics
+ */
+export class StatusCommand extends Command {
+  static commandName = "status";
+  static description = "Show live metrics from the running server";
+  static needsApp = false;
+  static args = [];
+  static flags = [
+    {
+      name: "port",
+      short: "p",
+      type: "number" as const,
+      description: "Port the server is listening on",
+      default: 3000,
+    },
+    {
+      name: "host",
+      type: "string" as const,
+      description: "Server hostname",
+      default: "localhost",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const port = this.flags["port"] as number;
+    const host = this.flags["host"] as string;
+    const url = `http://${host}:${port}/__zerotal/health`;
+
+    let data: Record<string, unknown>;
+    try {
+      const res = await fetch(url);
+      if (!res.ok) {
+        this.error(`Health endpoint returned ${res.status}.`);
+        this.dim("Make sure app.health is enabled and the server is running.");
+        process.exit(1);
+      }
+      data = (await res.json()) as Record<string, unknown>;
+    } catch {
+      this.error(`Could not reach ${url}`);
+      this.dim("Start the server with: bun zerotal.ts serve");
+      process.exit(1);
+    }
+
+    const memory = data.memory as { heapUsed?: number; rss?: number } | undefined;
+    const formatMegabytes = (bytes: number | undefined) =>
+      bytes !== undefined ? `${Math.round(bytes / 1024 / 1024)} MB` : "—";
+
+    this.section("Zerotal Server Status");
+    this.table([
+      ["Status", String(data.status ?? "?")],
+      ["Bun", String(data.version ?? "?")],
+      ["Uptime", `${Math.floor(Number(data.uptime ?? 0))} s`],
+      ["Pending requests", String(data.pendingRequests ?? 0)],
+      ["Open WebSockets", String(data.pendingWebSockets ?? 0)],
+      ["Heap used", formatMegabytes(memory?.heapUsed)],
+      ["RSS", formatMegabytes(memory?.rss)],
+    ]);
+    this.newLine();
+  }
+}

package/src/command/builtin/TestCommand.ts

@@ -0,0 +1,172 @@
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt test [pattern] [flags]` — runs the test suite in the test environment.
+ *
+ * Wraps `bun test` with proper app-environment setup:
+ *  - Sets APP_ENV=test before spawning so config loads correctly.
+ *  - Passes ZT_DB_URL to the child process; the @zerotal/testing/preload module
+ *    reads it and wires up the DB connection before each test file runs, so
+ *    withDatabase() and DB.table() work without manual beforeAll boilerplate.
+ *  - If @zerotal/testing is not installed the preload is silently skipped —
+ *    tests that use createTestApp() still work without it.
+ *
+ * All positional args and recognised flags are forwarded to bun test.
+ *
+ * @example
+ * ```bash
+ * bun zt test                        # run all tests
+ * bun zt test src/models             # filter by path
+ * bun zt test --coverage             # with coverage
+ * bun zt test --watch                # watch mode
+ * ```
+ *
+ * @category Testing
+ */
+export class TestCommand extends Command {
+  static commandName = "test";
+  static description = "Run the test suite in test environment";
+  static needsApp = false;
+
+  static override args = [{ name: "pattern", required: false, default: "" }];
+
+  static override flags = [
+    {
+      name: "coverage",
+      type: "boolean" as const,
+      description: "Collect test coverage",
+      default: false,
+    },
+    {
+      name: "watch",
+      short: "w",
+      type: "boolean" as const,
+      description: "Watch for file changes and re-run",
+      default: false,
+    },
+    {
+      name: "timeout",
+      type: "number" as const,
+      description: "Per-test timeout in milliseconds",
+      default: 0,
+    },
+    {
+      name: "bail",
+      type: "boolean" as const,
+      description: "Stop after first failure",
+      default: false,
+    },
+    {
+      name: "migrate",
+      type: "boolean" as const,
+      description: "Run database/migrations against the test database before the suite",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    // Resolve DB URL — prefer an explicit ZT_DB_URL, then DATABASE_URL,
+    // then fall back to :memory: (each createTestApp() call gets its own
+    // in-process SQLite; preload is a no-op for that case anyway).
+    const dbUrl = Bun.env["ZT_DB_URL"] ?? Bun.env["DATABASE_URL"] ?? ":memory:";
+
+    if (this.flags["migrate"]) {
+      const migrated = await _migrateTestDatabase(dbUrl);
+      if (migrated === null) {
+        this.error("--migrate needs @zerotal/orm installed in this project.");
+        return;
+      }
+      this.dim(
+        migrated.length > 0
+          ? `Migrated ${migrated.length} migration(s) into ${dbUrl}`
+          : `Test database schema already up to date`,
+      );
+    }
+
+    const bunArguments: string[] = ["test"];
+
+    // Only add --preload when @zerotal/testing is resolvable. If it isn't
+    // installed, skip the preload rather than crashing bun test startup.
+    const preloadPath = _resolvePreload(process.cwd());
+    if (preloadPath) {
+      bunArguments.push("--preload", preloadPath);
+    } else {
+      this.warn(
+        "@zerotal/testing not found — skipping DB preload (add it to devDependencies for withDatabase() auto-setup)",
+      );
+    }
+
+    const pattern = this.args["pattern"];
+    if (pattern) bunArguments.push(pattern);
+
+    if (this.flags["coverage"]) bunArguments.push("--coverage");
+    if (this.flags["watch"]) bunArguments.push("--watch");
+    if (this.flags["bail"]) bunArguments.push("--bail");
+
+    const timeout = this.flags["timeout"] as number | undefined;
+    if (timeout && timeout > 0) bunArguments.push(`--timeout=${timeout}`);
+
+    this.dim(`APP_ENV=test  ZT_DB_URL=${dbUrl}`);
+    this.dim(`bun ${bunArguments.join(" ")}\n`);
+
+    const subprocess = Bun.spawn(["bun", ...bunArguments], {
+      stdout: "inherit",
+      stderr: "inherit",
+      env: {
+        ...Bun.env,
+        APP_ENV: "test",
+        ZT_DB_URL: dbUrl,
+      } as Record<string, string | undefined>,
+    });
+
+    const code = await subprocess.exited;
+    // Mirror bun test's exit code — non-zero means failures or errors.
+    if (code !== 0) process.exit(code);
+  }
+}
+
+/** Try to resolve @zerotal/testing/preload from the app's working directory. */
+function _resolvePreload(cwd: string): string | null {
+  try {
+    return Bun.resolveSync("@zerotal/testing/preload", cwd);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Apply `database/migrations` to the test database before the suite starts.
+ *
+ * An `:memory:` database belongs to whichever process opened it, so there is
+ * nothing for a parent process to migrate — each test builds its own schema with
+ * `refreshDatabase({ migrate: true })`. This is for the file-backed or server
+ * databases where migrating once up front is both possible and much faster than
+ * migrating per test file.
+ *
+ * @returns The migrations applied, or `null` when the ORM is not installed.
+ */
+async function _migrateTestDatabase(dbUrl: string): Promise<string[] | null> {
+  if (dbUrl === ":memory:") return [];
+  try {
+    const { SQL } = await import("bun");
+    // Core does not depend on the ORM — this reaches for it only when the app
+    // being tested has one installed. The specifier lives in a variable so it
+    // stays a runtime lookup rather than a compile-time dependency.
+    const ormSpecifier = "@zerotal/orm";
+    const orm = (await import(ormSpecifier)) as {
+      MigrationRunner: new (o: { connection: unknown }) => {
+        runFromDirectory(dir: string): Promise<string[]>;
+      };
+      _setDbConnection(conn: unknown): void;
+      _setBaseModelConnection(conn: unknown): void;
+    };
+    const connection = new SQL(dbUrl);
+    // A migration's `up()` reaches for the ambient connection through `Schema`,
+    // so it has to be installed, not just handed to the runner.
+    orm._setDbConnection(connection);
+    orm._setBaseModelConnection(connection);
+    return await new orm.MigrationRunner({ connection }).runFromDirectory("database/migrations");
+  } catch {
+    return null;
+  }
+}

package/src/command/builtin/WorkerCommand.ts

@@ -0,0 +1,27 @@
+/**
+ * The `worker` command, which boots the app in the worker environment to
+ * process background jobs.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt worker` — boots the app in the worker environment to process
+ * background jobs. Aliased as `queue:work`.
+ *
+ * @category Serving
+ */
+export class WorkerCommand extends Command {
+  static commandName = "worker";
+  static description = "Start the background job worker process";
+  static aliases = ["queue:work"];
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    // Job classes self-register via the `jobs` convention concern during boot
+    // (bootAsWorker → conventions import every app/jobs/*.ts) — no codegen needed.
+    this.info("Starting Zerotal worker...");
+    await (this.app as import("../../application/Application.ts").Application).bootAsWorker();
+    // Keep the process alive — bootAsWorker() registers SIGTERM/SIGINT handlers.
+    await new Promise<never>(() => {});
+  }
+}

package/src/command/builtin/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Built-in CLI commands shipped with Zerotal, published as the
+ * `@zerotal/core/commands` subpath.
+ *
+ * These are the command classes the framework registers automatically during
+ * {@link CommandRunner.boot} — the `make:*` scaffolders, `serve`/`worker`
+ * process launchers, and diagnostics like `status`, `reload`, and `route:list`.
+ * They are all subclasses of the {@link Command} base class and are invoked
+ * through the scaffolded app's CLI entry point, `zt.ts`, as `bun zt <command>`.
+ *
+ * Which commands are available depends on the boot mode: `serve`, `reload`,
+ * `status`, and `route:list` are registered in every environment, while the
+ * scaffolding and worker commands are only registered outside `web` mode.
+ *
+ * @example
+ * ```bash
+ * # Start the dev server
+ * bun zt serve --dev
+ *
+ * # Scaffold a controller and list the registered routes
+ * bun zt make:controller PostController --resource
+ * bun zt route:list
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ServeCommand } from "./ServeCommand.ts";
+export { ReplCommand } from "./ReplCommand.ts";
+export { StartCommand } from "./StartCommand.ts";
+export { WorkerCommand } from "./WorkerCommand.ts";
+export { CompileCommand } from "./CompileCommand.ts";
+export { KeyGenerateCommand } from "./KeyGenerateCommand.ts";
+export { ReloadCommand } from "./ReloadCommand.ts";
+export { StatusCommand } from "./StatusCommand.ts";
+export { MakeControllerCommand } from "./MakeControllerCommand.ts";
+export { MakeMiddlewareCommand } from "./MakeMiddlewareCommand.ts";
+export { MakeCommandCommand } from "./MakeCommandCommand.ts";
+export { MakeRequestCommand } from "./MakeRequestCommand.ts";
+export { MakeEventCommand } from "./MakeEventCommand.ts";
+export { MakeListenerCommand } from "./MakeListenerCommand.ts";
+export { MakeJobCommand } from "./MakeJobCommand.ts";
+
+export { MakePolicyCommand } from "./MakePolicyCommand.ts";
+export { MakeNotificationCommand } from "./MakeNotificationCommand.ts";
+export { MakeObserverCommand } from "./MakeObserverCommand.ts";
+export { MakeResourceCommand } from "./MakeResourceCommand.ts";
+export { MakeTestCommand } from "./MakeTestCommand.ts";
+export { TestCommand } from "./TestCommand.ts";
+export { RouteListCommand } from "./RouteListCommand.ts";
+export { MakeProviderCommand } from "./MakeProviderCommand.ts";
+export { CssBuildCommand } from "./CssBuildCommand.ts";
+export { LintPackagesCommand } from "./LintPackagesCommand.ts";
+export { MakePackageCommand } from "./MakePackageCommand.ts";

package/src/command/scaffold/worker.ts.txt

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+// worker.ts
+// ─────────────────────────────────────────────────────────────────
+// Background worker process — runs alongside index.ts in production.
+// Handles queue jobs, scheduled tasks, and long-running background work.
+//
+// Start: bun worker.ts
+// The process stays alive until SIGTERM/SIGINT.
+// ─────────────────────────────────────────────────────────────────
+import app from './bootstrap/app.ts';
+
+await app.bootAsWorker();

package/src/command/scaffold/zerotal.ts.txt

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+// zerotal.ts
+// ─────────────────────────────────────────────────────────────────
+// DO NOT MODIFY THIS FILE.
+// This file is managed by the Zerotal framework.
+//
+// To add custom commands, create classes in app/commands/ and
+// register them in your AppServiceProvider.onBooted():
+//
+//   override async onBooted(): Promise<void> {
+//     if (this.app._env === 'console') {
+//       const runner = this.app.container.makeSync('commands');
+//       const { MyCommand } = await import('../commands/MyCommand.ts');
+//       runner.register(MyCommand);
+//     }
+//   }
+//
+// Help:  bun zerotal.ts list
+//        bun zerotal.ts help <command>
+// ─────────────────────────────────────────────────────────────────
+import app from './bootstrap/app.ts';
+import { CommandRunner } from '@zerotal/core';
+
+const runner = new CommandRunner(app);
+await runner.boot();
+await runner.run(process.argv.slice(2));

package/src/command/startZerotal.ts

@@ -0,0 +1,55 @@
+/**
+ * The single entry point an app's `zt.ts` calls. Encapsulates the full CLI
+ * boot sequence — config load + validate, runtime-env resolution, app import,
+ * and command dispatch — so app entry files stay a one-liner and the
+ * orchestration lives in one place.
+ */
+import { CommandRunner } from "./CommandRunner.ts";
+import { configLoader } from "../config/ConfigLoader.ts";
+import { setAppEnv } from "../helpers/index.ts";
+import type { Application } from "../application/Application.ts";
+
+/** Options for {@link startZerotal}. */
+export interface StartZerotalOptions {
+  /** Directory to load config from, resolved against the cwd. Default: `./config`. */
+  configDir?: string;
+}
+
+/**
+ * Boot and run the Zerotal CLI for an app.
+ *
+ * `loadApp` must **dynamically import** the app's bootstrap module
+ * (e.g. `() => import("./bootstrap/app")`). Passing a thunk rather than the app
+ * itself is deliberate and load-bearing:
+ *  - it guarantees `APP_ENV` is set (from the command) *before* the app module
+ *    evaluates, since ES imports are hoisted; and
+ *  - the literal `import("./bootstrap/app")` stays statically analysable, so
+ *    `bun build --compile` bundles the app into the production binary.
+ *
+ * @example
+ * // zt.ts
+ * import { startZerotal } from "@zerotal/core";
+ * await startZerotal(() => import("./bootstrap/app"));
+ */
+export async function startZerotal(
+  loadApp: () => Promise<{ default: Application }>,
+  options: StartZerotalOptions = {},
+): Promise<void> {
+  // Load + validate config synchronously — safe before the app boots.
+  const config = configLoader(options.configDir ?? "./config");
+  config.validate();
+
+  // Resolve the runtime boot mode (web / worker / console) from the command
+  // BEFORE importing the app module, which reads APP_ENV at evaluation time.
+  const command = process.argv[2] ?? "";
+  setAppEnv(command);
+
+  // Import the app now that APP_ENV is locked in, then inject the loaded config.
+  // (Job classes self-register during boot via the `jobs` convention concern.)
+  const { default: app } = await loadApp();
+  app.useConfig(config.all());
+
+  const runner = new CommandRunner(app);
+  await runner.boot();
+  await runner.run(process.argv.slice(2));
+}

package/src/config/AppConfig.ts

@@ -0,0 +1,253 @@
+/**
+ * The application-level configuration shape and its factory: the `app`
+ * namespace that every Zerotal app carries (identity, server/TLS, middleware
+ * defaults, conventions), with sensible defaults applied over caller overrides.
+ */
+import { deepMerge } from "../support/deepMerge.ts";
+import type { HealthConfigShape } from "../health/Health.ts";
+
+/** TLS certificate and key paths that enable HTTPS when provided. */
+export interface AppTlsConfig {
+  /** Path to the TLS certificate file. */
+  cert: string;
+  /** Path to the TLS private key file. */
+  key: string;
+}
+
+/** Auto-discovery (convention) settings. See docs/conventions.md. */
+export interface ConventionsConfig {
+  /** Master switch for convention-based auto-registration. Default: true */
+  enabled: boolean;
+  /** Per-concern directory overrides, relative to the app root. */
+  paths: {
+    providers: string;
+    middleware: string;
+    models: string;
+    observers: string;
+    policies: string;
+    listeners: string;
+    events: string;
+    jobs: string;
+    schedules: string;
+    validators: string;
+  };
+}
+
+/** App-level CORS defaults (consumed by `CorsMiddleware` when registered without options). */
+export interface AppCorsConfig {
+  origin: string | string[];
+  credentials: boolean;
+}
+
+/** App-level rate-limit defaults (consumed by `ThrottleMiddleware`). */
+export interface AppThrottleConfig {
+  maxAttempts: number;
+  windowSeconds: number;
+}
+
+/** App-level security-header defaults (consumed by `SecureHeadersMiddleware`). */
+export interface AppSecureHeadersConfig {
+  frameOptions: "DENY" | "SAMEORIGIN";
+}
+
+/**
+ * Front-end asset bundling. When set, `bun zerotal serve` bundles the
+ * entrypoint(s) with Bun's native bundler before starting (and rebuilds them on
+ * change under `serve --dev`). A JS/TS entry may `import` its CSS — Bun emits a
+ * sibling stylesheet. Tailwind v4 is picked up automatically when
+ * `bun-plugin-tailwind` is installed in the app.
+ */
+export interface AppAssetsConfig {
+  /** Entry file(s) to bundle, relative to the app root (e.g. `resources/js/app.ts`). */
+  entrypoint: string | string[];
+  /** Output directory for built bundles, relative to the app root. Default: `public`. */
+  outDir: string;
+  /** URL prefix the built assets are served under. Default: `/`. */
+  prefix: string;
+  /** Minify output. Default: true in production, false otherwise. */
+  minify: boolean;
+}
+
+/**
+ * Default request-body ceiling: 8 MiB.
+ *
+ * Chosen to comfortably fit a JSON API payload, a form post and an ordinary image upload
+ * while keeping the worst case a single request can pin in memory to something a small
+ * instance survives under concurrency. Bun's own 128 MiB default does not.
+ */
+export const DEFAULT_MAX_REQUEST_BODY_SIZE = 8 * 1024 * 1024;
+
+/**
+ * CORS defaults: same-origin only.
+ *
+ * `origin: "*"` was the previous default, which hands every browser on the internet a
+ * read of any endpoint that does not separately require a credential. An app that wants
+ * cross-origin access names the origins it means — the empty list is the honest default
+ * because the framework cannot know them.
+ */
+const DEFAULT_CORS: AppCorsConfig = { origin: [], credentials: false };
+const DEFAULT_THROTTLE: AppThrottleConfig = { maxAttempts: 120, windowSeconds: 60 };
+const DEFAULT_SECURE_HEADERS: AppSecureHeadersConfig = { frameOptions: "SAMEORIGIN" };
+
+const DEFAULT_CONVENTION_PATHS: ConventionsConfig["paths"] = {
+  providers: "app/providers",
+  middleware: "app/middleware",
+  models: "app/models",
+  observers: "app/observers",
+  policies: "app/policies",
+  listeners: "app/listeners",
+  events: "app/events",
+  jobs: "app/jobs",
+  schedules: "app/schedules",
+  validators: "app/validators",
+};
+
+// ── Full shape (resolved — what the config store holds after AppConfig()) ────
+
+/** The fully resolved `app` configuration as held in the config store. */
+export interface AppConfigShape {
+  // ── Identity ──────────────────────────────────────────────────────────────
+  /** Human-readable application name. */
+  name: string;
+  /** Runtime environment string. Mirrors APP_ENV. */
+  env: string;
+  /** Application secret key used for signing sessions / tokens. */
+  key: string;
+  /** Show verbose error pages and stack traces. */
+  debug: boolean;
+  /** Canonical public URL (e.g. https://myapp.com). */
+  url: string;
+  /** Default HTTP port. Overridden by --port CLI flag. Default: 3000 */
+  port: number;
+  /** Application locale used for date/number formatting. Default: 'en' */
+  locale: string;
+  /** Application timezone. Default: 'UTC' */
+  timezone: string;
+
+  // ── Server / TLS ──────────────────────────────────────────────────────────
+  /** Enable HTTP/3 over QUIC. Requires a valid tls config. Default: false */
+  http3: boolean;
+  /** TLS certificate + key for HTTPS. Enables HTTPS when set. */
+  tls?: AppTlsConfig;
+  /**
+   * Largest request body the server will accept, in bytes. Default: 8 MiB.
+   *
+   * Bodies are fully buffered before a handler sees them — a multipart upload
+   * materialises every file in RAM before `ctx.file()` reads a byte — so this is the
+   * ceiling on memory a single request can claim. Bun's own default is 128 MiB, which
+   * twenty concurrent POSTs turn into 2.5 GB resident on any route, authenticated or not.
+   *
+   * Raise it for an app that genuinely accepts large uploads, and prefer raising it on the
+   * upload route's proxy rather than globally.
+   */
+  maxRequestBodySize: number;
+  /**
+   * Health endpoint configuration. Pass an object to configure it
+   * (`enabled` / `path` / `secret` / `showDetails`); `enabled` defaults to on
+   * outside production. A bare `true`/`false` is shorthand for enable/disable
+   * with the other defaults. Default: `false`.
+   *
+   * @example
+   * ```ts
+   * health: {
+   *   enabled: true,                 // default: !production
+   *   path: "/health",              // default: '/health'
+   *   secret: env("HEALTH_KEY"),    // required in production
+   *   showDetails: true,            // false → bare { "status": "ok" }
+   * }
+   * ```
+   */
+  health: boolean | HealthConfigShape;
+
+  // ── Middleware defaults ───────────────────────────────────────────────────
+  /** CORS defaults applied by `CorsMiddleware` when registered without explicit options. */
+  cors: AppCorsConfig;
+  /** Rate-limit defaults applied by `ThrottleMiddleware`. */
+  throttle: AppThrottleConfig;
+  /** Security-header defaults applied by `SecureHeadersMiddleware`. */
+  secureHeaders: AppSecureHeadersConfig;
+
+  // ── Assets ────────────────────────────────────────────────────────────────
+  /** Front-end asset bundling, built on `serve`. Omitted means no asset build. */
+  assets?: AppAssetsConfig;
+
+  // ── Conventions ───────────────────────────────────────────────────────────
+  /** Auto-discovery settings (enabled + per-concern paths). */
+  conventions: ConventionsConfig;
+}
+
+// ── AppConfig factory ─────────────────────────────────────────────────────────
+
+/**
+ * Build the application-level config with sensible defaults.
+ *
+ * Pass overrides to customise any setting. Every field has a default that works
+ * out of the box so the minimum viable config is just `AppConfig({})`.
+ *
+ * @param options  Partial overrides; every field has a working default.
+ * @returns The fully resolved {@link AppConfigShape} with defaults applied.
+ *
+ * @example
+ * ```ts
+ * // config/app.ts
+ * import { AppConfig, env } from '@zerotal/core';
+ *
+ * export default AppConfig({
+ *   name: 'My App',
+ *   url:  env('APP_URL', 'http://localhost:3000'),
+ * });
+ * ```
+ */
+export function AppConfig(options: {
+  name?: string;
+  env?: string;
+  key?: string;
+  debug?: boolean;
+  url?: string;
+  port?: number;
+  locale?: string;
+  timezone?: string;
+  http3?: boolean;
+  tls?: AppTlsConfig;
+  maxRequestBodySize?: number;
+  health?: boolean | HealthConfigShape;
+  cors?: Partial<AppCorsConfig>;
+  throttle?: Partial<AppThrottleConfig>;
+  secureHeaders?: Partial<AppSecureHeadersConfig>;
+  assets?: { entrypoint: string | string[]; outDir?: string; prefix?: string; minify?: boolean };
+  conventions?: { enabled?: boolean; paths?: Partial<ConventionsConfig["paths"]> };
+}): AppConfigShape {
+  // Resolve env-derived defaults, then deep-merge the caller's overrides so partial nested
+  // overrides (e.g. `conventions.paths.models`) keep every other default in place.
+  const defaults: AppConfigShape = {
+    name: "Zerotal App",
+    env: Bun.env["APP_ENV"] ?? "development",
+    key: Bun.env["APP_KEY"] ?? "",
+    debug: Bun.env["APP_DEBUG"] !== "false",
+    url: Bun.env["APP_URL"] ?? "http://localhost:3000",
+    port: 3000,
+    locale: "en",
+    timezone: "UTC",
+    http3: false,
+    maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE,
+    health: false,
+    cors: DEFAULT_CORS,
+    throttle: DEFAULT_THROTTLE,
+    secureHeaders: DEFAULT_SECURE_HEADERS,
+    conventions: { enabled: true, paths: DEFAULT_CONVENTION_PATHS },
+  };
+  const resolved = deepMerge(defaults, options as Partial<AppConfigShape>);
+
+  // Normalise the optional `assets` block: fill outDir/prefix/minify defaults
+  // only when the app actually declares an asset entrypoint.
+  if (options.assets) {
+    const isProduction = resolved.env === "production" || resolved.env === "prod";
+    resolved.assets = {
+      entrypoint: options.assets.entrypoint,
+      outDir: options.assets.outDir ?? "public",
+      prefix: options.assets.prefix ?? "/",
+      minify: options.assets.minify ?? isProduction,
+    };
+  }
+  return resolved;
+}