@zerotal/core 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,210 @@ 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
+
+- **`@zerotal/core/env` is documented.** A whole subpath — a strict, fully typed environment
+  schema — had no page. `EnvSchema.define()` with the `t` field builders reports **every**
+  failing variable at once rather than one per restart, which is the difference between one fix
+  and three round trips through a deploy. See
+  [Configuration](/docs/config-system#declaring-the-whole-environment--envschema).
+
+- **`negotiate()` is documented.** One route, three audiences: a browser, an API client and the
+  console, without three copies of the logic. It is what the framework's own error handler uses,
+  which is why a 422 is a redirect-with-errors for a form post and a JSON body for a fetch.
+
+- **The hashing helpers get the paragraph `safeEqual` deserves.** `a === b` on a token returns as
+  soon as two bytes differ, and how long it took measures how much of the prefix was right —
+  enough, over many attempts, to recover a secret a character at a time.
+
+- Routing, config, cookie, view, storage and Carbon types are named.
+
+### Changed
+
+- **INTERNAL: 58 exports are marked `@internal`** — the file-routing internals, the router's
+  compiled state, the context registry, the metrics instrumentation hooks, the view component
+  symbols, and the config map/path types. Still exported, still working; none is something an
+  app constructs.
+
+### Changed
+
+- **INTERNAL: the dev orchestrator's 26 exports are marked `@internal`.** `DevSupervisor`,
+  `DevChild`, `DevSpawnFn`, `StreamDeck`, `TabsDeck`, `createDeck`, `collectDevProcesses`,
+  `buildCssBundle`, `buildJsBundle`, `bootBuildDecision`, `detectCssPlugins`, `isWritableDir`,
+  `startDevMode`, `registerDevHtmlSnippet`, `DEV_RELOAD_CLIENT`, `SERVER_PROCESS_NAME` and their
+  option/result types.
+
+  **Nothing is removed and nothing breaks** — they are still exported and still work. What
+  changes is the promise: they leave the recorded API surface, because an app never constructs
+  any of them and the only callers outside `@zerotal/core` are sibling framework packages wiring
+  their own dev-time build. `DevProcessDefinition` — the one a package author actually writes —
+  is unaffected and stays documented.
+
+### Added
+
+- **One project, one Bun.** `engines.bun` is a floor and nothing enforces it, so a project
+  can end up serving its app with one runtime and running its suite with another — the
+  shell's `bun` and a `node_modules/bun` put there by a transitive peer dependency nobody
+  declared. Nothing announces that, and a green suite is then evidence about a binary the app
+  is not served by. `startZerotal()` now compares `Bun.version` against the installed
+  manifest and refuses on a mismatch, naming both versions and the two ways out. It is not a
+  pin: the version to agree on is whichever one the project installed, so `bun update bun`
+  moves it. `ZT_ALLOW_RUNTIME_MISMATCH=1` downgrades the refusal to a warning.
+
+- **`DeployTarget.preflight`** — a slot for the app's own release gate, run after the config
+  validators and `doctor` and before anything is built or migrated. A command named
+  `release:check` is found by convention with nothing to wire up. A declared name that is not
+  registered **fails** the deploy rather than being skipped: a missing `inertia:build` means
+  the app has no Inertia, but a missing gate means the gate is not running, which is the
+  state the feature exists to prevent.
+
+- **`zerotal/shared`** — the helpers that are safe to import from a browser bundle:
+  `pluralize`, `singularize`, `snakeCase`, `camelCase`, `tableNameFor`, `Str`, and new
+  `formatMoney` / `formatNumber` / `formatDate`. Everything reachable from it is pure, and a
+  test bundles the entry point for the browser to keep it that way. Without it a page that
+  wants the framework's `pluralize` gets a second implementation written by hand, and the
+  second copy is always the worse one — `"supplier line"` pluralises to `"supplier lines"`,
+  and the naive rule gives `"suppliers line"`.
+
+- **`doctor` check: rate-limit identity.** `ThrottleMiddleware` keys on the socket address
+  unless told how many proxies sit in front of the app. That default is right and it is the
+  wrong answer the moment you deploy behind one: the socket address is then the proxy's for
+  every request, everybody shares a bucket, and the limiter inverts into a way for one
+  attacker to lock out the rest. Nothing observable says so. A production-like deployment
+  with a registered throttle and no `trustedProxies` is now reported.
+
+### Changed
+
+- **`zt test` spawns the binary running it**, not the name `bun` for the OS to resolve
+  against `PATH`. A command whose job is to run this app's tests was handing them to whatever
+  the shell happened to offer, so `node_modules/.bin/bun zt test` satisfied every check in
+  the parent process and still ran the suite on a different runtime.
+
+- **`BaseMiddleware.with()`** now documents that each call creates a distinct class and any
+  per-class state goes with it — so re-using one `.with()` export on two routes shares that
+  state. For `ThrottleMiddleware` that state is the hit counter, and on a sign-in flow it
+  means a handful of fumbled passwords can spend the allowance a legitimate person needs to
+  answer their second factor.
+
 ## [1.8.0] — 2026-08-24
 
 ### Added