@zerotal/core 1.6.3 → 1.7.2

package/CHANGELOG.md

@@ -8,6 +8,182 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+### Added
+
+- **`@zerotal/core/errors`** — a subpath for the error classes, so a module that can run in a
+  browser can import `ZerotalError` without reaching the root entry. The root re-exports
+  `CommandRunner`, which reaches the built-in CLI commands and `await import("bun")`, so a single
+  root import is enough to make a browser bundle fail at resolution. `@zerotal/core/helpers`
+  already covered `deepMerge` the same way.
+
+  The rule this makes workable: **core's root entry is server-only.** Anything that might be
+  bundled for a browser imports from a narrow subpath.
+
+
+## [1.7.1] — 2026-08-16
+
+### Changed
+
+- **`APP_ENV` is the deployment name; the runtime mode moved to `APP_TYPE`.** They shared one
+  variable and the mode won: `setAppEnv()` overwrote `APP_ENV` with `web` / `worker` /
+  `console` at boot, so an app whose `.env` said `APP_ENV=development` read `"console"` back
+  from `env("APP_ENV")` inside every CLI command.
+
+  The dangerous direction is the one nobody hits in development. A guard written the obvious
+  way —
+
+  ```ts
+  if (env("APP_ENV") === "production") refuseToWipe();
+  ```
+
+  — was **inert in every console command**, which is exactly where destructive commands live.
+  1.7.0 patched the framework's own gates by parking a copy that `deployEnv()` read back, but
+  application code reading the documented variable the documented way still got the mode.
+
+  Two questions, two variables. `setAppEnv()` no longer touches `APP_ENV` at all and writes
+  the mode to `APP_TYPE`; `runtimeMode()` reads it, and falls back to the legacy location so a
+  process started by an older launcher still boots the right providers. An explicit
+  `APP_TYPE` wins over the command, which is how `serve --dev` boots its supervised server as
+  `web`. `deployEnv()` and `config("app.env")` are unchanged and still correct.
+
+  No action needed in an app unless it sets `APP_ENV=web` by hand to force web mode — that
+  still works, and `APP_TYPE=web` is the spelling to move to.
+
+  Found seeding the first cookbook app, where a guard fired that should not have.
+
+### Fixed
+
+- **`Router.raw()` did not answer `HEAD`.** The pipeline derives a `HEAD` handler from every
+  `GET` — its own docblock notes that not doing so gives "every uptime monitor,
+  load-balancer probe, CDN origin check and `curl -I`" a 404 — and the raw path was left out
+  of it. So `curl -I` against a raw route answered 404 while the `GET` beside it answered 200. This framework's own site serves `/docs/*` and `/blog` from raw routes, so every link
+  checker and uptime probe aimed at the documentation was told the page did not exist.
+
+  Derived from the wrapped handler rather than the bare one, so the security headers below
+  ride along and a `HEAD` cannot answer with fewer than the `GET` it mirrors. A `HEAD` the
+  app registered itself still wins. Third gap in the same family, after the headers and
+  static files: any path that answers a request without running the pipeline needs whatever
+  the pipeline was doing for it.
+
+- **The dev deck would not scroll.** On the alternate screen a terminal has no scrollback of
+  its own, so the wheel and the scrollbar had nothing to move and the deck read as frozen —
+  from the moment tabs mode starts, every way of looking at an older line has to come from
+  the deck itself, and only Page Up/Down did.
+
+  It now asks the terminal to send the wheel as cursor keys (`?1007h`, released again on
+  exit) and handles `↑`/`↓` and Home/End. Deliberately not mouse tracking, which would give
+  real wheel events at the price of the terminal's own text selection.
+
+  Two things had to change underneath. A read from stdin is not one key: a wheel tick arrives
+  as the same arrow repeated once per line, all in one chunk, and two fast keystrokes arrive
+  together — so a chunk is split into keys and the frame painted once at the end. And a card
+  that has been scrolled up now holds its place: `scroll` counts up from the newest line, so a
+  busy process used to drag the window down by a line for every line it printed, sliding the
+  text somebody had stopped to read off the top while they read it. A card pinned to the
+  bottom still follows its output, which is the one that should.
+
+Both of the next two were found by wiring DevTools into this repo's own `apps/docs` and
+driving it in a browser.
+
+- **`Router.raw()` responses carried no security headers.** A raw route opts out of the
+  _request_ pipeline — CSRF on a transport endpoint, session resolution on a relay — and was
+  silently opting its response out of `SecureHeadersMiddleware` too. This framework's own
+  documentation site serves every `/docs/*` page from a raw route, so every page of it went
+  out with no `X-Content-Type-Options: nosniff`, no `X-Frame-Options`, no
+  `Referrer-Policy` and no `Permissions-Policy`. In production the reverse proxy happened
+  to add two of them, which is why nothing had noticed.
+
+  The header set is now applied to raw responses at compile time, **add-if-absent** rather
+  than overwrite: a raw route is the one place a handler owns its whole response, and an
+  endpoint that deliberately allows framing has a reason the framework cannot see. The
+  response is only reconstructed when something is missing, so the hot path — Flow's action
+  endpoint is a raw route — pays nothing when it already has them.
+
+  This is the third surface in the same family, after the pipeline and static files. Any
+  path that answers a request without running middleware needs the same treatment.
+
+- **`redactGraph` masked booleans.** Sensitivity is judged by key name, by substring, so
+  `cors.credentials` matched "credential" and the DevTools Config tab reported
+  `‹redacted›` where the answer was `false`. A boolean has two possible values: masking one
+  conceals nothing a reader could not guess, and hides the security setting they opened the
+  tab to check. Booleans now pass through; numbers still mask, since a number can be a PIN
+  or an account. The helper also gained the test file it shipped without.
+
+## [1.7.0] — 2026-08-16
+
+### Fixed
+
+- **Security headers now cover static files.** Files under `public/` are handed to Bun as
+  pre-registered responses and served without entering JavaScript, so no middleware ran for
+  them — including `SecureHeadersMiddleware`, which the framework advertises as automatic.
+  Every asset went out with no `X-Content-Type-Options: nosniff`, which is precisely the
+  response class sniffing protection exists for. The header set is baked into the compiled
+  response at registration time, so Bun still serves the file natively; a header a mount
+  declares itself still wins.
+
+- **`BaseMiddleware.with()` type-checks its options.** `Opts` has a default computed from the
+  middleware class, but a type parameter in an argument position is inferred from the
+  _argument_ and only falls back to its default when inference finds nothing — so
+  `with({ … })` inferred `Opts` from the object literal and type-checked the literal against
+  itself. Every callback parameter arrived implicitly `any`, and a misspelled option was
+  accepted in silence. `NoInfer` on the parameter makes the middleware's own option type the
+  one that governs. It caught a real defect on the first run: `StorageProvider` was passing
+  an `unknown` where a `StorageManager` was expected.
+
+### Added
+
+- **`DeepPartial<T>`, and `deepMerge` accepts it.** `deepMerge` does a deep merge and
+  declared `override: Partial<T>`, which only makes the top level optional — so
+  `{ drivers: { anthropic: { apiKey } } }`, the commonest thing anyone writes in a config
+  file, was a type error against any shape whose nested block has other keys.
+  `@zerotal/ai` had already hit this and defined a private copy; that copy is now deleted and
+  the type is exported from the kernel. `BaseMiddleware.with()` takes it too, since it
+  deep-merges as well.
+
+- **`zt doctor --url` reports duplicated security headers.** A header the app sets and the
+  proxy also sets is invisible from inside the process. Conflicting values fail — browsers do
+  not agree which copy applies, so the control is enforced inconsistently — and identical
+  duplicates warn. `Permissions-Policy` and `Referrer-Policy` are deliberately not checked:
+  a comma is legitimate syntax there, and a probe that cried wolf on a correct header would
+  be switched off before it caught a real one.
+
+- **`RequestFailed` carries the error's class name and stack.** It had the message and the
+  status, which is enough to say a request failed and not enough to say anything about how.
+  A subscriber rendering a failure — the devtools Exception tab is the first — has nothing to
+  show without them, and by the time the event is emitted the error object is the only place
+  they exist. Both are optional trailing parameters, so nothing that constructs or reads the
+  event needs to change.
+
+- **`Application.providerReport`** — what each provider cost to boot and what it put in the
+  container, in boot order. `bootDurationMs` said the app took 240ms and nothing said which
+  provider spent it; the container listed a hundred bindings and nothing said who bound
+  them. Boot order is itself the third answer, since it decides who wins a contested
+  binding.
+
+  Provenance comes from diffing the container registry around each provider's hooks rather
+  than from the container recording a registrar — it keeps the cost at boot instead of on
+  every binding, and adds no mutable state to the container for a question only a debugging
+  tool asks. Async hooks are timed across their `await`, not up to it.
+
+- **`FrameworkEvents.subscriptions()` and `Emitter.registrations()`** — which events have
+  subscribers, and what reacts to them. The bus is the framework's nervous system and had
+  been entirely invisible: `handlerCount()` returned one number for the whole thing.
+
+- **`redactGraph` on the `@zerotal/core/security` subpath** — the object-graph redaction walk
+  that every recorder needs and that three packages had each written for themselves. Copy a
+  value, replace what a key name says is a secret, come back with something
+  `JSON.stringify` survives.
+
+  Shared because the hard parts are the same everywhere and are easy to get subtly wrong:
+  cycles (a model with a back-reference to its parent is ordinary, and `JSON.stringify`
+  throws on it), a depth bound (recording is on the request path), and values that read
+  better flat than walked (`Object.entries` on a `Date` or a `File` produces something worse
+  than useless).
+
+  It is not a policy. Callers bring their own markers and their own sensitivity predicate,
+  because those are not interchangeable — a debug panel's `‹redacted›` is a display choice,
+  while an adapter implementing a published wire protocol has its markers specified for it.
+
 ## [1.6.3] — 2026-08-15
 
 ### Added