@zerotal/core 1.9.0 → 1.10.0

package/src/command/builtin/AssetsPruneCommand.ts

@@ -0,0 +1,138 @@
+import { readdir, unlink } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { Command } from "../Command.ts";
+import type { Application } from "../../application/Application.ts";
+import type { ConfigManager } from "../../config/ConfigManager.ts";
+import { _recordedBuildOutput } from "../../dev/BuildOutput.ts";
+import type { AssetBuildConfig } from "../../dev/CssPlugins.ts";
+
+/** Bundler-generated code-split chunk, e.g. `chunk-2502z4dn.js` (+ `.map`). */
+const CHUNK_NAME = /^chunk-[a-z0-9]+\.js(\.map)?$/i;
+
+/**
+ * `bun zt assets:prune` — remove the chunks a previous release left behind.
+ *
+ * `assets:build --clean` cleans the directory it *builds into*, which is the build
+ * machine. It does nothing for the common release shape: build here, tar the output,
+ * extract it over `public/` there. Extracting a tarball merges — nothing removes a
+ * file the new release does not contain — so every deploy adds another set of
+ * content-hashed chunks to a directory that only ever grows. One app reached 225
+ * chunk files on disk for the 49 its entry point references.
+ *
+ * Nothing breaks while that happens, which is why it runs for months unnoticed. The
+ * accumulation even *masks* a stale-cache bug, because the pruned chunk an old
+ * browser asks for is usually still lying there. But it grows without bound on a box
+ * with a disk quota, and a release process that cannot say which files belong to the
+ * current release is one that cannot clean up after itself.
+ *
+ * This is that answer. `assets:build` records what it wrote; ship `.zerotal/` with
+ * the release and this removes what the record does not claim.
+ *
+ * ## What it will and will not delete
+ *
+ * Only two things qualify: a file an *earlier* recorded build wrote that the current
+ * one did not, and a file named the way the bundler names a code-split chunk.
+ * Everything else is left alone, because an output directory is usually `public/`,
+ * where a blanket sweep takes the app's images and favicon with it.
+ *
+ * @example
+ * ```bash
+ * # on the server, after extracting the release and before the restart
+ * bun zt assets:prune --dry-run   # list what would go
+ * bun zt assets:prune
+ * ```
+ *
+ * @category Build & assets
+ */
+export class AssetsPruneCommand extends Command {
+  static override commandName = "assets:prune";
+  static override description = "Remove asset files left behind by an earlier release";
+  static override needsApp = true;
+
+  static override flags = [
+    {
+      name: "dir",
+      type: "string" as const,
+      description: "Output directory to prune (defaults to the configured `app.assets.outDir`)",
+    },
+    {
+      name: "dry-run",
+      type: "boolean" as const,
+      description: "List what would be removed, and remove none of it",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const cwd = process.cwd();
+    const dir = (this.flags["dir"] as string | undefined) ?? this._configuredOutDir();
+    if (!dir) {
+      this.warn(
+        "No output directory to prune. Pass --dir, or configure app.assets.outDir in config/app.ts.",
+      );
+      return;
+    }
+
+    const root = resolve(cwd, dir);
+    const recorded = new Set(await _recordedBuildOutput(root, cwd));
+    if (recorded.size === 0) {
+      // Without a record, "what belongs to this release" has no answer, and the
+      // by-name sweep alone would be guessing about a directory it does not own.
+      this.warn(
+        `No build record for ${dir}. Run \`zt assets:build\` (and ship .zerotal/ with the ` +
+          `release) so a prune knows which files are the current one's.`,
+      );
+      return;
+    }
+
+    const stale: string[] = [];
+    for (const entry of await _listEntries(root)) {
+      if (recorded.has(entry)) continue;
+      if (!CHUNK_NAME.test(entry.split("/").at(-1) ?? "")) continue;
+      stale.push(entry);
+    }
+
+    if (stale.length === 0) {
+      this.info(`${dir}: nothing to prune — ${recorded.size} file(s) all accounted for.`);
+      return;
+    }
+
+    if (this.flags["dry-run"] === true) {
+      this.info(`${dir}: ${stale.length} file(s) would be removed:`);
+      for (const path of stale.sort()) this.line(`  ${path}`);
+      return;
+    }
+
+    let removed = 0;
+    for (const path of stale) {
+      try {
+        await unlink(join(root, path));
+        removed++;
+      } catch {
+        // Already gone, or held open. The next prune tries again, and a file we
+        // could not delete is not worth failing a release over.
+      }
+    }
+    this.info(`${dir}: removed ${removed} stale file(s), kept ${recorded.size}.`);
+  }
+
+  /** The configured asset output directory, or undefined when the app declares none. */
+  private _configuredOutDir(): string | undefined {
+    try {
+      const config = (this.app as Application).container.makeSync("config") as ConfigManager;
+      return (config.get("app.assets") as AssetBuildConfig | undefined)?.outDir;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+/** Every entry under `root`, relative and slash-normalised. Empty when unreadable. */
+async function _listEntries(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(root, { recursive: true });
+    return entries.map((entry) => relative(".", entry).split("\\").join("/"));
+  } catch {
+    return [];
+  }
+}

package/src/command/builtin/DeployCommand.ts

@@ -51,6 +51,12 @@ export abstract class DeployCommand extends Command {
       description: "Print the steps that would run, and run none of them",
       default: false,
     },
+    {
+      name: "check",
+      type: "boolean" as const,
+      description: "Run the preflight gate and stop — build nothing, migrate nothing",
+      default: false,
+    },
     {
       name: "skip-migrations",
       type: "boolean" as const,
@@ -77,6 +83,19 @@ export abstract class DeployCommand extends Command {
     const steps = this._steps(app, target);
     if (dryRun) return this._printPlan(app, target, steps);
 
+    // `--check` is the gate on its own, for the moment in a release script where the
+    // new code is on disk and the service has not restarted yet. Everything that can
+    // refuse has already run by the end of preflight and none of it mutates, so
+    // stopping here is a complete answer: exit 0 and restart, exit 1 and keep serving
+    // the previous release. A workspace that has lost its banking details or had its
+    // mail driver knocked back to `log` never goes live broken.
+    if (this.flags["check"] === true) {
+      await this._preflight(app, target);
+      this.newLine();
+      this.info(`${target} passed preflight. Nothing was built, migrated or restarted.`);
+      return;
+    }
+
     await this._preflight(app, target);
     await this._runSteps(app, steps);
     await this._verify(app);

package/src/command/builtin/index.ts

@@ -55,5 +55,6 @@ export { DeployCommand, makeDeployCommand } from "./DeployCommand.ts";
 export { MakeProviderCommand } from "./MakeProviderCommand.ts";
 export { CssBuildCommand } from "./CssBuildCommand.ts";
 export { AssetsBuildCommand } from "./AssetsBuildCommand.ts";
+export { AssetsPruneCommand } from "./AssetsPruneCommand.ts";
 export { LintPackagesCommand } from "./LintPackagesCommand.ts";
 export { MakePackageCommand } from "./MakePackageCommand.ts";

package/src/command/startZerotal.ts

@@ -8,17 +8,20 @@ import { CommandRunner } from "./CommandRunner.ts";
 import { configLoader } from "../config/ConfigLoader.ts";
 import { setAppEnv } from "../helpers/index.ts";
 import {
+  runtimeBelowFloor,
+  runtimeBelowFloorMessage,
   runtimeMismatch,
   runtimeMismatchAllowed,
   runtimeMismatchMessage,
 } from "../support/runtime.ts";
+import type { RuntimeMismatch } from "../support/runtime.ts";
 import { RuntimeMismatchError } from "../errors/RuntimeMismatchError.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;
+  configDir?: string | undefined;
 }
 
 /**
@@ -66,21 +69,45 @@ export async function startZerotal(
 }
 
 /**
- * Refuse to run when the project has two Bun runtimes in it.
+ * Refuse to run on a Bun the project does not agree with.
+ *
+ * Two disagreements, both about the same thing — which binary the assertions
+ * downstream of here are assertions *about*:
+ *
+ * - The runtime is below the `engines.bun` the project declares. Every generated
+ *   app writes that floor and nothing had ever enforced it.
+ * - The project installs a different Bun in `node_modules` than the one running.
+ *   Most projects do not install Bun as a package, so most never see this one.
  *
  * At the top of the entry point rather than in a check somebody remembers to run,
- * because the value is in it being unmissable: the failure it prevents is a suite
- * that passes about the wrong binary, and nothing downstream of here can notice
- * that. A project with no `node_modules/bun` — most of them — never sees this.
+ * because the value is in it being unmissable: the failure both prevent is a suite
+ * that passes about the wrong binary, and nothing downstream of here can notice that.
  *
- * @throws When the running Bun and the installed one disagree, unless
- *   `ZT_ALLOW_RUNTIME_MISMATCH` is set, which downgrades it to a warning on stderr.
+ * @throws When either check fails, unless `ZT_ALLOW_RUNTIME_MISMATCH` is set, which
+ *   downgrades it to a warning on stderr.
  * @internal
  */
 function assertOneRuntime(): void {
+  const floor = runtimeBelowFloor();
+  if (floor) {
+    _refuse(runtimeBelowFloorMessage(floor), {
+      running: floor.running,
+      installed: floor.required,
+      manifest: floor.manifest,
+    });
+  }
+
   const mismatch = runtimeMismatch();
-  if (!mismatch) return;
-  const message = runtimeMismatchMessage(mismatch);
+  if (mismatch) _refuse(runtimeMismatchMessage(mismatch), mismatch);
+}
+
+/**
+ * Stop, or warn and continue when the escape hatch is set.
+ *
+ * @param message - The full explanation, already formatted.
+ * @param mismatch - The two versions, carried on the error for a harness to read.
+ */
+function _refuse(message: string, mismatch: RuntimeMismatch): void {
   if (runtimeMismatchAllowed()) {
     console.warn(`\n⚠  ${message}\n`);
     return;

package/src/config/AppConfig.ts

@@ -63,17 +63,17 @@ export interface AppSecureHeadersConfig {
    * Enable HSTS (and the `Secure` flag on the XSRF-TOKEN cookie). Defaults to
    * `false` — turn it on for any deployment served over HTTPS.
    */
-  secure?: boolean;
+  secure?: boolean | undefined;
   /** `Strict-Transport-Security` max-age in seconds. Defaults to one year. */
-  hstsMaxAge?: number;
+  hstsMaxAge?: number | undefined;
   /** Include `includeSubDomains` in the HSTS header. Defaults to `true`. */
-  hstsIncludeSubDomains?: boolean;
+  hstsIncludeSubDomains?: boolean | undefined;
   /** Set the HSTS `preload` directive. Only with the domain registered. Defaults to `false`. */
-  hstsPreload?: boolean;
+  hstsPreload?: boolean | undefined;
   /** `Content-Security-Policy` value. Omitted by default. */
-  contentSecurityPolicy?: string;
+  contentSecurityPolicy?: string | undefined;
   /** `Referrer-Policy` value. Defaults to `strict-origin-when-cross-origin`. */
-  referrerPolicy?: string;
+  referrerPolicy?: string | undefined;
 }
 
 /**
@@ -106,7 +106,7 @@ export interface AppAssetsConfig {
    * // config/app.ts
    * assets: { entrypoint: 'resources/css/app.css', loader: { '.woff2': 'file', '.woff': 'file' } }
    */
-  loader?: Record<string, AssetLoaderKind>;
+  loader?: Record<string, AssetLoaderKind> | undefined;
 }
 
 /**
@@ -176,7 +176,7 @@ export interface AppConfigShape {
   /** 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;
+  tls?: AppTlsConfig | undefined;
   /**
    * Largest request body the server will accept, in bytes. Default: 8 MiB.
    *
@@ -237,7 +237,7 @@ export interface AppConfigShape {
 
   // ── Assets ────────────────────────────────────────────────────────────────
   /** Front-end asset bundling, built on `serve`. Omitted means no asset build. */
-  assets?: AppAssetsConfig;
+  assets?: AppAssetsConfig | undefined;
 
   // ── Dev mode ──────────────────────────────────────────────────────────────
   /**
@@ -256,7 +256,7 @@ export interface AppConfigShape {
    * }
    * ```
    */
-  dev?: DevConfigShape;
+  dev?: DevConfigShape | undefined;
 
   // ── Conventions ───────────────────────────────────────────────────────────
   /** Auto-discovery settings (enabled + per-concern paths). */

package/src/conventions/ConventionLoader.ts

@@ -45,7 +45,7 @@ export interface RunConventionsOptions {
   root: string;
   env: AppEnvironment;
   /** Per-concern directory overrides (config `discovery.paths`). */
-  paths?: Record<string, string>;
+  paths?: Record<string, string> | undefined;
   ctx: ConcernContext;
 }
 
@@ -105,7 +105,10 @@ export async function runConventions(
 ): Promise<void> {
   const orderedConcerns = [...concerns].sort((first, second) => first.order - second.order);
   for (const concern of orderedConcerns) {
-    if (concern.envs && !concern.envs.includes(options.env)) continue;
+    if (concern.envs && !concern.envs.includes(options.env)) {
+      await _announceSkipped(concern, options);
+      continue;
+    }
 
     if (concern.dir && concern.register) {
       const relativeDirectory = options.paths?.[concern.name] ?? concern.dir;
@@ -130,3 +133,37 @@ export async function runConventions(
     }
   }
 }
+
+/**
+ * Say once, at boot, that this process is not running a convention the app has
+ * written files for.
+ *
+ * An env-restricted concern is skipped by *not looking*, which is correct and
+ * completely silent: from a web process's point of view nothing is wrong, because
+ * from a web process's point of view nothing exists. An app ran for weeks in
+ * production with `app/schedules` full and no worker process — no inventory hold
+ * released, no payment reminder sent, nothing logged, and it was found by going
+ * looking rather than by being told.
+ *
+ * Only announced when the directory actually holds files: "skipping 0 schedules" on
+ * every boot of every app is noise, and noise is how the line that matters gets
+ * scrolled past.
+ */
+async function _announceSkipped(
+  concern: ConcernDescriptor,
+  options: RunConventionsOptions,
+): Promise<void> {
+  if (!concern.dir || !concern.register) return;
+
+  const relativeDirectory = options.paths?.[concern.name] ?? concern.dir;
+  const files = (await _scanDir(`${options.root}/${relativeDirectory}`)).filter(
+    (file) => !_shouldSkip(file),
+  );
+  if (files.length === 0) return;
+
+  frameworkLog("app").info(
+    `Skipping ${files.length} file(s) in ${relativeDirectory} — the "${concern.name}" convention ` +
+      `does not run in env=${options.env} (it runs in: ${(concern.envs ?? []).join(", ")}).`,
+    { convention: concern.name, env: options.env, files: files.length },
+  );
+}

package/src/dev/BuildOutput.ts

@@ -98,15 +98,67 @@ function _relative(root: string, path: string): string {
 }
 
 /**
- * The manifest lives outside `outdir` — writing it inside would put a file the
- * app then serves (and registers a route for) into the public directory.
+ * Where a directory's manifest lives.
+ *
+ * Outside `outdir` — writing it inside would put a file the app then serves (and
+ * registers a route for) into the public directory.
+ *
+ * Named from the output directory's path **relative to the project**, not its
+ * absolute one. The hash used to be `Bun.hash(absolutePath)`, which made the
+ * manifest belong to a machine rather than to a release: the same project built at
+ * `/home/me/app` and unpacked at `/opt/app` produced two different filenames, so a
+ * manifest that travelled with a deploy matched nothing at the other end and the
+ * server could not say which files belonged to the current release. It also meant
+ * moving a checkout silently orphaned the record and stopped pruning.
+ *
+ * @internal
  */
-function _manifestPath(root: string): string {
-  const slug = _relative(resolve(process.cwd()), root).replace(/[^a-z0-9]+/gi, "-") || "out";
+export function _buildManifestPath(root: string, cwd: string = process.cwd()): string {
+  const relativeRoot = _relative(resolve(cwd), resolve(root));
+  const slug = relativeRoot.replace(/[^a-z0-9]+/gi, "-") || "out";
   // The slug alone can collide (two different roots normalising to the same
   // name); the hash makes each directory's manifest its own.
-  const hash = Bun.hash(root).toString(36);
-  return join(process.cwd(), MANIFEST_DIR, `${slug}-${hash}.json`);
+  const hash = Bun.hash(relativeRoot).toString(36);
+  return join(cwd, MANIFEST_DIR, `${slug}-${hash}.json`);
+}
+
+/** Back-compat alias used throughout this module. */
+function _manifestPath(root: string): string {
+  return _buildManifestPath(root);
+}
+
+/**
+ * Every file the recorded builds wrote to `outdir`, relative and slash-normalised.
+ *
+ * The answer to "which assets belong to this release" — the question a deploy has
+ * to answer before it can remove anything, and the one that has no answer at all
+ * from inside a directory somebody extracted a tarball over.
+ *
+ * @param outdir - The output directory to describe.
+ * @param cwd - Project root the manifest is stored under. Defaults to the working directory.
+ * @returns The recorded files, or `[]` when no manifest exists.
+ *
+ * @internal
+ */
+export async function _recordedBuildOutput(
+  outdir: string,
+  cwd: string = process.cwd(),
+): Promise<string[]> {
+  try {
+    const contents = (await Bun.file(_buildManifestPath(outdir, cwd)).json()) as unknown;
+    if (Array.isArray(contents)) {
+      return contents.filter((entry): entry is string => typeof entry === "string").sort();
+    }
+    if (!contents || typeof contents !== "object") return [];
+    const files = new Set<string>();
+    for (const list of Object.values(contents as Record<string, unknown>)) {
+      if (!Array.isArray(list)) continue;
+      for (const entry of list) if (typeof entry === "string") files.add(entry);
+    }
+    return [...files].sort();
+  } catch {
+    return [];
+  }
 }
 
 /**

package/src/dev/CssPlugins.ts

@@ -210,13 +210,13 @@ export interface AssetBuildConfig {
   prefix: string;
   minify: boolean;
   /** Per-extension loader overrides (e.g. `{ ".woff2": "file" }`). See AppAssetsConfig. */
-  loader?: Record<string, string>;
+  loader?: Record<string, string> | undefined;
   /**
    * Delete everything in `outDir` this build did not write, rather than only what
    * the last build on this machine recorded. See {@link cleanBuildOutput} — it
    * refuses a directory that holds more than build output.
    */
-  clean?: boolean;
+  clean?: boolean | undefined;
 }
 
 /**

package/src/dev/DevDeck.ts

@@ -59,10 +59,10 @@ export interface DeckOptions {
   /** The user asked to quit — bound to `q`. */
   onQuit: () => void;
   /** Force a renderer. Defaults to tabs on a TTY, stream otherwise. */
-  mode?: "tabs" | "stream";
+  mode?: "tabs" | "stream" | undefined;
   /** Overridable for tests. Defaults to `process.stdout`/`process.stdin`. */
-  stdout?: DeckStdout;
-  stdin?: DeckStdin;
+  stdout?: DeckStdout | undefined;
+  stdin?: DeckStdin | undefined;
 }
 
 /** The bits of `process.stdout` the deck reads. */

package/src/dev/DevProcess.ts

@@ -110,9 +110,9 @@ export interface ResolvedDevProcess {
  */
 export interface DevConfigShape {
   /** App-level processes, registered after every provider's. */
-  processes?: DevProcessDefinition[];
+  processes?: DevProcessDefinition[] | undefined;
   /** Names to drop, whoever registered them. */
-  disable?: string[];
+  disable?: string[] | undefined;
 }
 
 /** The bits of `Application` this module needs — kept structural to avoid a cycle. */

package/src/dev/DevSupervisor.ts

@@ -1,4 +1,4 @@
-/**
+/**
  * Runs the dev processes and keeps them running.
  *
  * The supervisor owns lifetimes, not presentation: it spawns, watches, restarts,
@@ -72,17 +72,17 @@ export interface DevSupervisorHooks {
 /** @internal */
 export interface DevSupervisorOptions extends DevSupervisorHooks {
   cwd: string;
-  env?: Record<string, string | undefined>;
+  env?: Record<string, string | undefined> | undefined;
   /** Defaults to `Bun.spawn` with output piped and **stdin ignored**. */
-  spawn?: DevSpawnFn;
+  spawn?: DevSpawnFn | undefined;
   /**
    * Backoff before each retry, in ms. Overridable for the same reason `spawn`
    * is: a test of the restart policy should assert the policy, not spend three
    * seconds proving that `setTimeout` works.
    */
-  backoffMs?: number[];
+  backoffMs?: number[] | undefined;
   /** How long a run must last to be considered healthy. See {@link HEALTHY_AFTER_MS}. */
-  healthyAfterMs?: number;
+  healthyAfterMs?: number | undefined;
 }
 
 /** Give up after this many consecutive failed starts. */

package/src/dev/index.ts

@@ -33,7 +33,12 @@ export { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
 export { browserEnvDefines } from "./buildEnv.ts";
 export { detectCssPlugins, buildCssBundle, buildJsBundle } from "./CssPlugins.ts";
 export type { AssetBuildConfig } from "./CssPlugins.ts";
-export { pruneBuildOutput, cleanBuildOutput } from "./BuildOutput.ts";
+export {
+  pruneBuildOutput,
+  cleanBuildOutput,
+  _recordedBuildOutput,
+  _buildManifestPath,
+} from "./BuildOutput.ts";
 // Lets `serve` and any view provider agree on whether to build at boot, so a hardened
 // production unit with a read-only output directory logs a line instead of restart-looping.
 export { bootBuildDecision, isWritableDir } from "./bootBuild.ts";

package/src/dev/startDevMode.ts

@@ -31,7 +31,7 @@ export interface StartDevModeOptions {
    * and nothing to serve it to — `--only=queue` is supervision and a deck, and
    * the orchestrator that would call this never starts.
    */
-  build?: BuildHookFn;
+  build?: BuildHookFn | undefined;
   /** Everything the providers and the app contributed, already filtered. */
   processes: ResolvedDevProcess[];
   writer: OutputWriter;

package/src/doctor/throttleIdentity.ts

@@ -24,7 +24,7 @@
  * @module
  */
 import type { Application } from "../application/Application.ts";
-import { ThrottleMiddleware } from "../middleware/ThrottleMiddleware.ts";
+import { ThrottleMiddleware, _isIpDerived } from "../middleware/ThrottleMiddleware.ts";
 import { Router } from "../router/Router.ts";
 
 /** A registered throttle and how it decides who is who. */
@@ -64,7 +64,11 @@ function readIdentity(cls: unknown, where: string): ThrottleIdentity | null {
       name: (cls as { name?: string }).name || "ThrottleMiddleware",
       where,
       trustsProxies: typeof options.trustedProxies === "number" && options.trustedProxies > 0,
-      customKey: typeof options.keyResolver === "function",
+      // A resolver that keys on the client address is not an exemption — it is
+      // exactly the case this check exists for. `RateLimiter`'s `.byIp()`,
+      // `.byUser()` and `.byApiKey()` all mark themselves, so the named-limiter API
+      // stops slipping past the audit that covers the middleware it builds on.
+      customKey: typeof options.keyResolver === "function" && !_isIpDerived(options.keyResolver),
     };
   } catch {
     // A middleware that will not construct is a different problem, and not one

package/src/health/Health.ts

@@ -149,20 +149,20 @@ export const Health = new HealthRegistry();
 /** The health config, authored under the `health` key of `config/app.ts`. */
 export interface HealthConfigShape {
   /** Serve the endpoint. Default: on outside production, off in production. */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /** Route path. Default: `/health`. */
-  path?: string;
+  path?: string | undefined;
   /** Shared secret. Required in production; supplied via `?key=` or `X-Health-Key`. */
-  secret?: string;
+  secret?: string | undefined;
   /** Include per-check details. Set false for a bare `{ status }` body. Default: true. */
-  showDetails?: boolean;
+  showDetails?: boolean | undefined;
 }
 
 /** The health config after defaults and back-compat have been applied. */
 export interface ResolvedHealthConfig {
   enabled: boolean;
   path: string;
-  secret?: string;
+  secret?: string | undefined;
   showDetails: boolean;
 }
 

package/src/helpers/index.ts

@@ -298,5 +298,6 @@ export { markdownPage, type BunMarkdownOptions } from "./markdown.ts";
 // must not carry private copies.
 export { escapeHtml } from "./html.ts";
 export { pluralize, singularize, tableNameFor } from "../support/str.ts";
-export { deepMerge } from "../support/deepMerge.ts";
+export { deepMerge, definedOnly } from "../support/deepMerge.ts";
+export type { Resolved } from "../support/deepMerge.ts";
 export { parseCookieHeader } from "../support/cookie.ts";

package/src/helpers/markdown.ts

@@ -49,6 +49,13 @@ ${body}
  * Options for `Bun.markdown.html()`. bun-types exposes the options type only inside
  * its `markdown` namespace; this is the named, exported equivalent the framework uses.
  *
+ * Its optional properties stay `?: T` rather than `?: T | undefined`, unlike the
+ * framework's own option shapes. This one is not an option shape, it is a *mirror* of
+ * somebody else's signature, and a mirror that is wider than what it reflects stops
+ * being assignable to it — the value built here is handed straight to
+ * `Bun.markdown.html()`.
+ *
+ * @exact-optional-ignore
  * @internal
  */
 export interface BunMarkdownOptions {

package/src/http/UploadedFile.ts

@@ -19,9 +19,9 @@ export type StorageDisk = Pick<StorageDriver, "url"> & {
  */
 export interface FileValidationOptions {
   /** Maximum allowed size in bytes. */
-  maxSize?: number;
+  maxSize?: number | undefined;
   /** Allowed MIME types — e.g. `['image/jpeg', 'image/png', 'application/pdf']`. */
-  mimes?: string[];
+  mimes?: string[] | undefined;
 }
 
 /**

package/src/index.ts

@@ -162,7 +162,8 @@ export {
 export { config } from "./helpers/config.ts";
 export { pluralize, singularize, snakeCase, camelCase, tableNameFor } from "./support/str.ts";
 export { deepMerge } from "./support/deepMerge.ts";
-export type { DeepPartial } from "./support/deepMerge.ts";
+// `definedOnly` is a helper, not kernel surface — it lives on `@zerotal/core/helpers`.
+export type { DeepPartial, Resolved } from "./support/deepMerge.ts";
 // The type every class-keyed registry uses — a class rather than an instance.
 export type { ClassRef } from "./support/classRef.ts";
 export { safeEqual, sha256Hex, hmacHex } from "./support/crypto.ts";