@zerotal/core 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,123 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-08-30
+
+### Changed
+
+- **Optional properties in public option shapes are declared `?: T | undefined`.**
+  The generated `tsconfig.json` turns on `exactOptionalPropertyTypes`, under which
+  `image?: string` and `image?: string | undefined` are different types: only the
+  second accepts a key that is present and holds `undefined`. So an app with the
+  strictness the framework shipped it could not write the most ordinary thing there
+  is — `{ image: candidate ?? undefined }` — and had to spell every conditional field
+  `...(x ? { x } : {})` instead. An options bag exists to be spread into; one built by
+  spreading has conditionally-absent keys.
+
+  438 properties across 115 files, applied by `scripts/exact-optional.ts` and checked
+  by `bun run exact:optional:check` so the convention holds for shapes written later.
+  Scoped to exported `*Options` / `*Config` shapes — what an app constructs — rather
+  than every optional property in the codebase. Nothing changes for a reader: an
+  absent optional property already read as `undefined`.
+
+### Added
+
+- **`zt assets:prune`** — remove the chunks an earlier release left behind, on the
+  machine that never ran a build. `assets:build --clean` cleans the directory it
+  _builds into_, which does nothing for the common release shape: build here, tar the
+  output, extract it over `public/` there. Extracting merges — nothing removes a file
+  the new release does not contain — so every deploy adds another set of
+  content-hashed chunks. One app reached 225 chunk files for the 49 its entry point
+  references. Ship `.zerotal/` with the release and this removes what the build record
+  does not claim; without a record it says so and removes nothing rather than guessing.
+
+- **`definedOnly` (`@zerotal/core/helpers`) and the `Resolved<T>` type.** Widening the
+  option shapes moves a problem to the merge, and both of these are that problem's
+  answer. Object spread copies own properties even when their value is `undefined`,
+  so `{ ...DEFAULTS, ...options }` now lets an explicit `undefined` overwrite a
+  default; `definedOnly` drops those keys, turning "supplied as undefined" back into
+  "not supplied". (`deepMerge` already did this at every depth.)
+
+  `Resolved<T>` is what a defaults-applied object is. **`Required<T>` is not**, which
+  is the trap: `-?` removes the optionality a `?` introduced but not an `undefined`
+  written into the type, so `Required<Options>` quietly stopped meaning "the defaults
+  have been applied".
+
+- **`zt deploy:<env> --check`** — the preflight gate on its own. A release script has a
+  moment where the new code is on disk and the service has not restarted yet, and that
+  is where a gate belongs: exit 0 and restart, exit non-zero and keep serving the
+  previous release. Everything that can refuse already runs by the end of preflight and
+  none of it mutates, so stopping there is a complete answer rather than half a deploy.
+  A workspace that has lost its banking details, or had its mail driver knocked back to
+  `log`, never goes live broken.
+
+- **`engines.bun` is enforced.** Every generated app writes a floor and nothing had
+  ever read it. `runtimeMismatch` did not cover this: it compares the running Bun
+  against an _installed_ one, and most projects do not install Bun as a package, so
+  it correctly says nothing about most of them. `startZerotal()` now refuses to run
+  below the declared floor, so every `zt` command is covered.
+
+  The failure it catches is narrow and expensive. `Intl` output moves between Bun
+  releases, so a suite with currency or date assertions goes red on a runtime that is
+  otherwise fine, the failures name the code they touch, and the version is the last
+  thing anyone checks. `ZT_ALLOW_RUNTIME_MISMATCH=1` downgrades it to a warning.
+
+- **`@zerotal/core/runtime`** (`zerotal/runtime`) — a subpath exporting the checks
+  themselves: `runtimeBelowFloor`, `declaredBunFloor`, `runtimeMismatch`, `bunBinary`
+  and the messages that go with them, so a script or a test can make the same
+  assertion. A subpath rather than the main barrel, which is deliberately lean.
+
+- **A boot line when a convention is skipped in this environment.** 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, and
+  nothing logged, because there was nothing to log. It was found by going looking.
+
+  `runConventions` now says so once, at boot, and only when the directory actually
+  holds files:
+
+      Skipping 3 file(s) in app/schedules — the "schedules" convention does not run in env=web (it runs in: worker, console).
+
+  "Skipping 0 schedules" on every boot of every app would be noise, and noise is how
+  the line that matters gets scrolled past.
+
+### Fixed
+
+- **Named rate limiters honour `trustedProxies`.** `ThrottleMiddleware` resolves the
+  client address from the socket unless told how many proxies sit in front — that was
+  fixed, documented and covered by a doctor check. `RateLimiter`'s `.byIp()`,
+  `.byUser()` and `.byApiKey()` did not: they used a private resolver that read the
+  socket address and fell back to the **leftmost** `X-Forwarded-For` entry, with no
+  proxy count anywhere in it. A `keyResolver` replaces the middleware's own
+  proxy-aware path entirely, so the sibling API kept the bug the middleware had shed.
+
+  Two consequences, in opposite directions. Where there was no socket address a client
+  picked its own bucket by writing the header, which is the part of it the client
+  controls. Behind a real reverse proxy — where there _is_ a socket address — it was
+  the proxy's, so **every visitor shared one bucket**: the documented
+  `RateLimiter.for("login").limit(5).every(60)` was five attempts a minute across the
+  entire user base, and one attacker locked everybody out.
+
+  All three now resolve through the same proxy-aware function, and
+  `.trustedProxies(n)` is on the builder. The strategy is recorded and the resolver
+  built at the end, so `.byIp().trustedProxies(1)` and `.trustedProxies(1).byIp()`
+  mean the same thing.
+
+- **`zt doctor` audits named limiters.** Its `trustedProxies` check exempted any
+  throttle with a custom `keyResolver` — right for one keyed on a user id, where no
+  proxy can affect the answer, and exactly wrong for `RateLimiter`'s built-ins, which
+  _are_ custom resolvers and do key on an address. The check that exists to catch this
+  skipped the whole API that still had it. The built-in resolvers mark themselves now;
+  an app's own `.by(fn)` stays exempt, which is the point of the exemption.
+
+- **The build record is portable.** Its filename was hashed from the output
+  directory's _absolute_ path, so the same project built at `/home/me/app` and
+  unpacked at `/opt/app` wrote and looked for two different files. A record shipped
+  with a release matched nothing at the other end — which is why a server could not
+  say which files belonged to the current release — and moving a checkout silently
+  orphaned it. It is keyed on the path relative to the project now.
+
 ## [1.9.0] — 2026-08-29
 
 ### Added

package/api-surface.md

@@ -394,6 +394,7 @@ class LimiterDefinition = {
   register: () => LimiterDefinition
   toMiddleware: () => ThrottleMiddleware
   toMiddlewareClass: () => new () => ThrottleMiddleware
+  trustedProxies: (count: number) => LimiterDefinition
 }
 
 class MarkdownBuilder = {
@@ -808,23 +809,23 @@ interface ContainerBindings = {
 }
 
 interface CookieOptions = {
-  domain?: string
-  httpOnly?: boolean
-  maxAge?: number
+  domain?: string | undefined
+  httpOnly?: boolean | undefined
+  maxAge?: number | undefined
   name: string
-  path?: string
-  sameSite?: SameSite
-  secure?: boolean
+  path?: string | undefined
+  sameSite?: SameSite | undefined
+  secure?: boolean | undefined
   value: string
 }
 
 interface CorsOptions = {
-  allowedHeaders?: string[]
-  credentials?: boolean
-  exposedHeaders?: string[]
-  maxAge?: number
-  methods?: string[]
-  origin?: string | string[] | ((origin: string) => boolean)
+  allowedHeaders?: string[] | undefined
+  credentials?: boolean | undefined
+  exposedHeaders?: string[] | undefined
+  maxAge?: number | undefined
+  methods?: string[] | undefined
+  origin?: string | string[] | ((origin: string) => boolean) | undefined
 }
 
 interface DevProcessDefinition = {
@@ -870,9 +871,9 @@ interface ErrorDiagnosis = {
 }
 
 interface GroupOptions = {
-  domain?: string
-  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[]
-  prefix?: string
+  domain?: string | undefined
+  middleware?: string | string[] | MiddlewareClass | MiddlewareClass[] | undefined
+  prefix?: string | undefined
 }
 
 interface ModelClass = {
@@ -925,25 +926,25 @@ interface RouterMacros = {
 }
 
 interface SecureHeadersOptions = {
-  contentSecurityPolicy?: string
-  frameOptions?: false | 'DENY' | 'SAMEORIGIN'
-  hstsIncludeSubDomains?: boolean
-  hstsMaxAge?: number
-  hstsPreload?: boolean
-  permissionsPolicy?: string | false
-  referrerPolicy?: string
-  secure?: boolean
+  contentSecurityPolicy?: string | undefined
+  frameOptions?: false | 'DENY' | 'SAMEORIGIN' | undefined
+  hstsIncludeSubDomains?: boolean | undefined
+  hstsMaxAge?: number | undefined
+  hstsPreload?: boolean | undefined
+  permissionsPolicy?: string | false | undefined
+  referrerPolicy?: string | undefined
+  secure?: boolean | undefined
 }
 
 interface StartZerotalOptions = {
-  configDir?: string
+  configDir?: string | undefined
 }
 
 interface ThrottleOptions = {
-  keyResolver?: (ctx: HttpContext) => string
+  keyResolver?: ((ctx: HttpContext) => string) | undefined
   maxAttempts: number
-  trustedProxies?: number
-  windowSeconds?: number
+  trustedProxies?: number | undefined
+  windowSeconds?: number | undefined
 }
 
 interface ViewRegistration = {
@@ -952,14 +953,14 @@ interface ViewRegistration = {
 }
 
 interface WebhookOptions = {
-  algorithm?: 'sha256' | 'sha1' | 'sha512'
-  format?: 'raw' | 'stripe'
-  header?: string
-  prefix?: string
+  algorithm?: 'sha256' | 'sha1' | 'sha512' | undefined
+  format?: 'raw' | 'stripe' | undefined
+  header?: string | undefined
+  prefix?: string | undefined
   secret: string
-  timestampHeader?: string
-  timestampSeparator?: string
-  tolerance?: number
+  timestampHeader?: string | undefined
+  timestampSeparator?: string | undefined
+  tolerance?: number | undefined
 }
 
 interface WebSocketHandlers = {
@@ -998,6 +999,8 @@ type NextFn = () => Promise<Response | void>
 
 type ParamsOf = P extends `${string}:${infer Name}/${infer Rest}` ? { [K in Name]: RouteParamValue; } & ParamsOf<`/${Rest}`> : P extends `${string}:${infer Name}` ? { [K in Name]: RouteParamValue; } : P extends `${string}*${string}` ? {    "*": RouteParamValue | readonly RouteParamValue[];} : Record<never, never>
 
+type Resolved = { [K in keyof T]-?: Exclude<T[K], undefined>; }
+
 type RouteArgs = [params?: RouteParamValues, query?: RouteQuery]
 
 type RouteMiddleware = MiddlewareClass[] | RouteMethodMiddleware
@@ -1037,7 +1040,7 @@ function addToDefaultArrayExport = (source: string, identifier: string) => strin
 function registerProvider = (options: RegisterProviderOptions) => Promise<RegisterResult>
 
 interface RegisterProviderOptions = {
-  bootstrapPath?: string
+  bootstrapPath?: string | undefined
   className: string
   importPath: string
 }
@@ -1304,6 +1307,34 @@ class AssetsBuildCommand = {
   write: (msg: string) => void
 }
 
+class AssetsPruneCommand = {
+  new (): AssetsPruneCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    type: 'string';    description: string;    default?: never;} | {    name: string;    type: 'boolean';    description: string;    default: boolean;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
 class CompileCommand = {
   new (): CompileCommand
   static args: ArgDef[]
@@ -2191,7 +2222,7 @@ function DeployConfig = (options?: Partial<DeployConfigShape>) => DeployConfigSh
 
 interface AppAssetsConfig = {
   entrypoint: string | string[]
-  loader?: Record<string, AssetLoaderKind>
+  loader?: Record<string, AssetLoaderKind> | undefined
   minify: boolean
   outDir: string
   prefix: string
@@ -2199,11 +2230,11 @@ interface AppAssetsConfig = {
 
 interface AppConfigShape = {
   allowedOrigins: string[]
-  assets?: AppAssetsConfig
+  assets?: AppAssetsConfig | undefined
   conventions: ConventionsConfig
   cors: AppCorsConfig
   debug: boolean
-  dev?: DevConfigShape
+  dev?: DevConfigShape | undefined
   env: string
   health: boolean | HealthConfigShape
   http3: boolean
@@ -2215,7 +2246,7 @@ interface AppConfigShape = {
   secureHeaders: AppSecureHeadersConfig
   throttle: AppThrottleConfig
   timezone: string
-  tls?: AppTlsConfig
+  tls?: AppTlsConfig | undefined
   url: string
 }
 
@@ -2579,10 +2610,10 @@ interface HealthCheckReport = {
 }
 
 interface HealthConfigShape = {
-  enabled?: boolean
-  path?: string
-  secret?: string
-  showDetails?: boolean
+  enabled?: boolean | undefined
+  path?: string | undefined
+  secret?: string | undefined
+  showDetails?: boolean | undefined
 }
 
 interface HealthReport = {
@@ -2602,7 +2633,7 @@ interface HealthResult = {
 interface ResolvedHealthConfig = {
   enabled: boolean
   path: string
-  secret?: string
+  secret?: string | undefined
   showDetails: boolean
 }
 
@@ -2620,6 +2651,8 @@ function data_get = (target: unknown, key: string, defaultValue?: unknown) => un
 
 function deepMerge = <T extends object>(base: T, override: DeepPartial<T>) => T
 
+function definedOnly = <T extends object>(value: T) => { [K in keyof T]?: Exclude<T[K], undefined>; }
+
 function env = {    (key: string): string | undefined;    (key: string, fallback: string): string;    (key: string, fallback: boolean): boolean;    (key: string, fallback: number): number;}
 
 function pipe = <T, R>(value: T, fn: (val: T) => R) => R
@@ -2644,6 +2677,8 @@ function tap = <T>(value: T, callback: (val: T) => void) => T
 
 function tapAsync = <T>(value: T, callback: (val: T) => Promise<void>) => Promise<T>
 
+type Resolved = { [K in keyof T]-?: Exclude<T[K], undefined>; }
+
 ## ./http  `(./src/http/index.ts)`
 
 class Http = {
@@ -2802,8 +2837,8 @@ interface CliContext = {
 }
 
 interface FileValidationOptions = {
-  maxSize?: number
-  mimes?: string[]
+  maxSize?: number | undefined
+  mimes?: string[] | undefined
 }
 
 interface NegotiateMap = {
@@ -2955,10 +2990,10 @@ class SqliteLockDriver = {
 function LockConfig = (options?: Partial<LockConfigShape>) => LockConfigShape
 
 interface BlockOptions = {
-  refresh?: boolean
-  refreshEvery?: number
-  retryDelay?: number
-  timeout?: number
+  refresh?: boolean | undefined
+  refreshEvery?: number | undefined
+  retryDelay?: number | undefined
+  timeout?: number | undefined
 }
 
 interface LockConfigShape = {
@@ -2977,8 +3012,8 @@ interface LockDriver = {
 }
 
 interface RefreshOptions = {
-  refresh?: boolean
-  refreshEvery?: number
+  refresh?: boolean | undefined
+  refreshEvery?: number | undefined
 }
 
 type LockedCallback = (lock: ManagedLock, signal: AbortSignal) => Promise<T> | T
@@ -3093,16 +3128,16 @@ interface LogEntry = {
 }
 
 interface LoggerOptions = {
-  format?: 'text' | 'json'
+  format?: 'text' | 'json' | undefined
 }
 
 interface LoggingConfigShape = {
   channels: Record<string, ChannelConfig>
-  console?: ConsoleSinkConfig
+  console?: ConsoleSinkConfig | undefined
   default: string
-  file?: FileSinkConfig
-  requests?: boolean
-  slowQueryMs?: number
+  file?: FileSinkConfig | undefined
+  requests?: boolean | undefined
+  slowQueryMs?: number | undefined
 }
 
 type ChannelConfig = { driver: 'console'; level?: LogLevel; format?: 'json' | 'pretty' } | { driver: 'single'; level?: LogLevel; path: string } | { driver: 'daily'; level?: LogLevel; path: string; days?: number } | { driver: 'stack'; level?: LogLevel; channels: string[] } | { driver: 'null' }
@@ -3164,6 +3199,38 @@ type RouteTable = Readonly<Record<string, string>> | ReadonlyMap<string, string>
 
 type RouteTarget = string
 
+## ./runtime  `(./src/support/runtime.ts)`
+
+const RUNTIME_MISMATCH_ESCAPE = 'ZT_ALLOW_RUNTIME_MISMATCH'
+
+function bunBinary = () => string
+
+function declaredBunFloor = (cwd: string) => {    range: string;    manifest: string;} | null
+
+function installedBunVersion = (cwd: string) => {    version: string;    manifest: string;} | null
+
+function runtimeBelowFloor = (cwd?: string) => RuntimeFloor | null
+
+function runtimeBelowFloorMessage = (floor: RuntimeFloor) => string
+
+function runtimeMismatch = (cwd?: string) => RuntimeMismatch | null
+
+function runtimeMismatchAllowed = () => boolean
+
+function runtimeMismatchMessage = (mismatch: RuntimeMismatch) => string
+
+interface RuntimeFloor = {
+  manifest: string
+  required: string
+  running: string
+}
+
+interface RuntimeMismatch = {
+  installed: string
+  manifest: string
+  running: string
+}
+
 ## ./security  `(./src/security/index.ts)`
 
 class CryptKeyMissingError = {
@@ -3194,7 +3261,7 @@ function redactGraph = (value: unknown, options: RedactGraphOptions) => unknown
 
 interface RedactGraphOptions = {
   circular: string
-  flatten?: (value: unknown) => string | undefined
+  flatten?: ((value: unknown) => string | undefined) | undefined
   mask: string
   maxDepth: number
   sensitive: (key: string) => boolean
@@ -3224,27 +3291,27 @@ function snakeCase = (value: string) => string
 function tableNameFor = (className: string) => string
 
 interface DateOptions = {
-  dateStyle?: 'medium' | 'short' | 'full' | 'long'
-  locale?: string
-  timeStyle?: 'medium' | 'short' | 'full' | 'long'
-  timeZone?: string
+  dateStyle?: 'medium' | 'short' | 'full' | 'long' | undefined
+  locale?: string | undefined
+  timeStyle?: 'medium' | 'short' | 'full' | 'long' | undefined
+  timeZone?: string | undefined
 }
 
 interface FormatOptions = {
-  locale?: string
+  locale?: string | undefined
 }
 
 interface MoneyOptions = {
   currency: string
-  fractionDigits?: number
-  locale?: string
-  minorUnits?: boolean
+  fractionDigits?: number | undefined
+  locale?: string | undefined
+  minorUnits?: boolean | undefined
 }
 
 interface NumberOptions = {
-  locale?: string
-  maximumFractionDigits?: number
-  minimumFractionDigits?: number
+  locale?: string | undefined
+  maximumFractionDigits?: number | undefined
+  minimumFractionDigits?: number | undefined
 }
 
 ## ./storage  `(./src/storage/index.ts)`
@@ -3411,10 +3478,10 @@ const Storage = StorageManager
 function StorageConfig = (options?: Partial<StorageConfigShape>) => StorageConfigShape
 
 interface DiskServeConfig = {
-  expiresIn?: number
-  headers?: Record<string, string>
+  expiresIn?: number | undefined
+  headers?: Record<string, string> | undefined
   path: string
-  signed?: boolean
+  signed?: boolean | undefined
 }
 
 interface FakeStoredFile = {
@@ -3428,24 +3495,24 @@ interface FakeStoredFile = {
 interface LocalDiskConfig = {
   driver: 'local'
   root: string
-  serve?: DiskServeConfig
-  url?: string
+  serve?: DiskServeConfig | undefined
+  url?: string | undefined
 }
 
 interface PutOptions = {
-  contentType?: string
-  visibility?: 'public' | 'private'
+  contentType?: string | undefined
+  visibility?: 'public' | 'private' | undefined
 }
 
 interface S3DiskConfig = {
   bucket: string
   driver: 's3'
-  endpoint?: string
+  endpoint?: string | undefined
   key: string
   region: string
   secret: string
-  serve?: DiskServeConfig
-  url?: string
+  serve?: DiskServeConfig | undefined
+  url?: string | undefined
 }
 
 interface StorageConfigShape = {
@@ -3470,8 +3537,8 @@ interface StorageDriver = {
 }
 
 interface StorageFilesOptions = {
-  mounts?: Mount[]
-  storage?: StorageManager
+  mounts?: Mount[] | undefined
+  storage?: StorageManager | undefined
 }
 
 type DiskConfig = LocalDiskConfig | S3DiskConfig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -16,6 +16,7 @@
     "./logger": "./src/logger/index.ts",
     "./commands": "./src/command/builtin/index.ts",
     "./helpers": "./src/helpers/index.ts",
+    "./runtime": "./src/support/runtime.ts",
     "./shared": "./src/shared/index.ts",
     "./facades": "./src/facade/facades/index.ts",
     "./carbon": "./src/datetime/index.ts",

package/src/application/Application.ts

@@ -182,9 +182,9 @@ type PipeClass = new (...args: any[]) => Pipe<HttpContext>;
 
 /** Options form for `Application.create({ ... })`. */
 export interface CreateOptions {
-  providers?: ProviderClass[];
-  env?: Environment;
-  config?: ConfigLoader | ConfigMap;
+  providers?: ProviderClass[] | undefined;
+  env?: Environment | undefined;
+  config?: ConfigLoader | ConfigMap | undefined;
   /**
    * Drop {@link SecureHeadersMiddleware} from the front of the pipeline.
    *
@@ -194,7 +194,7 @@ export interface CreateOptions {
    * `config('app.secureHeaders')`; turn it off only when a proxy in front of the app is
    * already emitting the same headers.
    */
-  secureHeaders?: false;
+  secureHeaders?: false | undefined;
 }
 
 function _normaliseEnv(raw: string): Environment {

package/src/build/codemod.ts

@@ -40,7 +40,7 @@ export interface RegisterProviderOptions {
   /** Import specifier, e.g. '../app/providers/FooProvider.ts' or '@zerotal/foo'. */
   importPath: string;
   /** Bootstrap file. Default: 'bootstrap/providers.ts'. */
-  bootstrapPath?: string;
+  bootstrapPath?: string | undefined;
 }
 
 /**

package/src/command/CommandRunner.ts

@@ -363,6 +363,7 @@ export class CommandRunner {
       MakeProviderCommand,
       CssBuildCommand,
       AssetsBuildCommand,
+      AssetsPruneCommand,
       LintPackagesCommand,
       MakePackageCommand,
     } = await import("./builtin/index.ts");
@@ -414,6 +415,7 @@ export class CommandRunner {
         TestCommand,
         CssBuildCommand,
         AssetsBuildCommand,
+        AssetsPruneCommand,
         LintPackagesCommand,
         MakePackageCommand,
       ]);