npm - @zerotal/arch - Versions diffs - 1.9.0 → 1.10.0 - Mend

@zerotal/arch 1.9.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/api-surface.md +6 -6
package/docs/changelog.md +156 -0
package/docs/deployment.md +52 -4
package/docs/helpers.md +51 -0
package/docs/inertia/middleware.md +44 -0
package/docs/inertia/ssr.md +95 -10
package/docs/middleware.md +31 -0
package/docs/rate-limiting.md +45 -17
package/docs/scheduler.md +71 -8
package/docs/testing/index.md +99 -0
package/docs/upgrade.md +48 -0
package/package.json +3 -3
package/src/install/guidelines.ts +1 -1
package/src/mcp/stdio.ts +3 -3
package/src/tools/_probe.ts +2 -2

package/api-surface.md CHANGED Viewed

@@ -119,7 +119,7 @@ interface DoctorReport = {
 interface GuidelineOptions = {
   packages: string[]
   serverName: string
-  shape?: ProjectShape
+  shape?: ProjectShape | undefined
 }
 interface InstalledPackage = {
@@ -177,8 +177,8 @@ interface SchemaReport = {
 }
 interface SpawnProbeOptions = {
-  cwd?: string
-  timeoutMs?: number
+  cwd?: string | undefined
+  timeoutMs?: number | undefined
 }
 interface ToolContext = {
@@ -262,10 +262,10 @@ interface ServerIdentity = {
 }
 interface StdioOptions = {
-  input?: ReadableStream<Uint8Array<ArrayBufferLike>>
-  log?: (message: string) => void
+  input?: ReadableStream<Uint8Array<ArrayBufferLike>> | undefined
+  log?: ((message: string) => void) | undefined
   server: McpServer
-  write?: (frame: string) => void
+  write?: ((frame: string) => void) | undefined
 }
 interface ToolOutcome = {

package/docs/changelog.md CHANGED Viewed

@@ -27,6 +27,162 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
+## 1.10.0 — 2026-08-30
+A second report from the team building on Zerotal, and the things it found. Most of this
+release is failures that were silent by construction — mail delivered nowhere, a page
+shared as a grey rectangle, a schedule that never fired, a rate limiter with one bucket
+for everybody. None of them logged anything.
+**Three things to know before upgrading.**
+- **React apps using SSR now need `@inertiajs/react` installed.** It is the same adapter
+  your browser entry point already uses; the server renders through its `<App>` so
+  `<Head>` works. A missing one is a named error rather than a silent omission.
+- **`scheduler.timezone` does something now.** It was documented as informational and read
+  by nothing. Its default moved from the literal `"UTC"` to **the system zone**, so an app
+  that never set the key keeps doing exactly what it did — but an app that set it now gets
+  what it asked for. If you set it to `"UTC"` on a server that is not on UTC, your
+  schedules will move. See [the upgrade guide](/docs/upgrade#1-9-to-1-10).
+- **Named rate limiters need `.trustedProxies(n)` behind a proxy.** `.byIp()`, `.byUser()`
+  and `.byApiKey()` now ignore `X-Forwarded-For` unless told how many proxies sit in
+  front, which is the same rule `ThrottleMiddleware` already followed. `zt doctor` reports
+  any that need it.
+### Added
+- **`zt assets:prune`** — removes 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 usual release shape: build here, tar the output, extract it
+  over `public/` there. Extracting merges, so every deploy adds another set of
+  content-hashed chunks and none are ever removed. 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. See [Deployment](/docs/deployment#assetsprune--clearing-up-after-the-extract-instead-of-before-it).
+- **`zt deploy:<env> --check`** — the preflight gate on its own, for the point in a release
+  script where the new code is on disk and the service has not restarted. 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.
+- **`RateLimiter.trustedProxies(n)`** on the fluent builder, and
+  **`res.assertInertiaRedirect(url)`** in `@zerotal/testing` — the assertion that checks
+  what actually breaks on an Inertia redirect, which is the `X-Inertia` marker rather than
+  the status and `Location` a normal redirect assertion already covers.
+- **`@zerotal/core/runtime`** (`zerotal/runtime`) — the runtime checks as exports, so a
+  script or a test can make the same assertion `zt` makes: `runtimeBelowFloor`,
+  `declaredBunFloor`, `runtimeMismatch`, `bunBinary` and the messages that go with them.
+- **`definedOnly()` and `Resolved<T>`** on `@zerotal/core/helpers`, for merging an options
+  bag over defaults without an explicit `undefined` overwriting one.
+- **Scheduler timezone helpers** — `wallClockIn`, `isValidTimeZone`,
+  `CronExpression.matchesIn` and `CronExpression.nextRunAfterIn`, plus `SchedulerError` and
+  `UnknownTimeZoneError`.
+- **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: an app ran
+  for weeks in production with `app/schedules` full and no worker process, and nothing
+  logged anything because from a web process's point of view nothing existed.
+### Changed
+- **Optional properties in public option shapes are declared `?: T | undefined`.** The
+  generated `tsconfig.json` enables `exactOptionalPropertyTypes`, under which
+  `image?: string` refuses a key that is present and holds `undefined` — so
+  `{ image: candidate ?? undefined }`, the most ordinary thing there is, did not compile
+  and every conditionally-absent field had to be spelled `...(x ? { x } : {})`. 438
+  properties across 115 files. Nothing changes for a reader: an absent optional property
+  already read as `undefined`.
+- **`scheduler.timezone` is honoured**, and its default is the system zone rather than the
+  literal `"UTC"`. See the note above.
+- **`mail.driver: "log"` fails `zt doctor` in production** when `mail.from.address` has been
+  configured, and warns when it is still the placeholder. Mail written to a log file is
+  delivered to nobody and says so nowhere.
+### Fixed
+- **React SSR emitted no `<Head>` tags at all.** The React branch rendered the page
+  component directly, and `<Head>` renders nothing — it reports its children to a head
+  manager it reads from context, and rendering the component alone puts none there. So
+  every page served the template's `<head>`: no title, no description, no card. Nothing
+  failed and nothing logged, because the page is perfect in a browser, where React has run.
+  Only the readers that do not run JavaScript saw it — which is every link-preview scraper
+  and every `curl`.
+- **SMTP submission on port 587 sent nothing.** The STARTTLS handshake completed and then
+  the client's `EHLO` was dropped: `upgradeTLS()` returns the new socket while the
+  handshake is still in flight, and a write issued in that window is lost — not buffered,
+  not an error, gone. Port 465 was unaffected, so mail worked on the port nobody documents
+  and the 587 every provider _does_ document produced silence: no error, no bounce, no log
+  line, and password resets that never arrived.
+- **TLS certificates were not actually verified, on either SMTP transport.**
+  `rejectUnauthorized` is not enforced by the runtime — it reports a self-signed
+  certificate as authorized and puts the real reason beside it — so the connection was
+  encrypted and would have accepted that encryption from anyone in the network path. The
+  driver reads the handshake result itself now and fails closed.
+- **A scheduled task with a `timezone` took the whole scheduler down.** `Bun.cron`'s options
+  form throws, and it throws during registration, so the worker died on boot and
+  restart-looped: one task with a timezone stopped every task in the app. Zerotal evaluates
+  the zone itself now, and a task that cannot register takes only itself out.
+- **Named rate limiters ignored `trustedProxies`, and `zt doctor` was told not to look.**
+  `.byIp()`, `.byUser()` and `.byApiKey()` used a resolver that read the socket address and
+  fell back to the leftmost `X-Forwarded-For` entry with no proxy count. Behind a reverse
+  proxy every visitor keyed on the proxy's own address and shared one bucket, so a `login`
+  limiter of five attempts a minute was five attempts a minute for the entire user base and
+  one attacker locked everybody out. The doctor check written to catch this exempted any
+  custom `keyResolver`, which is what all three are.
+- **`ctx.session.intended()` could not read what `AuthMiddleware` stored.** It used the key
+  `intended` while the middleware and `redirect().intended()` used `intended_url`. Each pair
+  was internally consistent and separately tested, so every test passed — and an app that
+  mixed them, which the documentation invited, was silently sent to `/` after every sign-in.
+- **`MonitorStore` overwrote its own defaults with `undefined`.** It applied `?? …` defaults
+  and then spread `...opts` after them, and spread copies own properties even when they
+  hold `undefined` — so an unset config put `undefined` back over the retention window and
+  `prune()` computed a `NaN` cutoff, pruning nothing and reporting nothing.
+- **`engines.bun` is enforced.** Every generated app writes a floor and nothing read it.
+  `Intl` output moves between Bun releases, so a suite with currency or date assertions goes
+  red on a runtime that is otherwise fine and the failures name the code they touch rather
+  than the binary.
+- **The asset build record is portable.** Its filename was hashed from the output
+  directory's _absolute_ path, so a record shipped with a release matched nothing at the
+  other end and moving a checkout silently orphaned it.
+- **The React SSR root is marked `data-server-rendered`**, so the client hydrates the markup
+  instead of discarding it and rendering the page a second time. `POST /__ssr` returns the
+  same body shape as the Vue branch.
+### Documented
+- **["What a crawler sees"](/docs/inertia/ssr#what-a-crawler-sees)** — `inertia()` does not
+  server-render the component, which is the normal Inertia arrangement and worth saying out
+  loud: the served document is a `<title>` and a JSON blob. Which readers run JavaScript,
+  which do not, and the three ways to give the second group something to read.
+- **[Which Inertia redirects are covered](/docs/inertia/middleware#which-redirects-are-covered)**
+  — all of them, because `useOnce()` registers the middleware globally. Written down because
+  the opposite belief is what keeps an app's own workaround on every request forever.
+- **[`bun test` vs `bun zt test`](/docs/testing#bun-test-vs-bun-zt-test)** — the 30-second
+  timeout (the `bunfig.toml` key is ignored by Bun and `setDefaultTimeout()` in a preload
+  reaches only the first file, so the flag is the only mechanism that works), the runtime
+  check, and the fact that configuration resolves once per process — so a test that mutates
+  the environment in `beforeAll` is testing whichever file booted first.
+- **[Timezones](/docs/scheduler#timezones)** in the scheduler, **[the middleware names the
+  framework occupies](/docs/middleware#names-the-framework-already-occupies)**, and why
+  `X-Forwarded-For` is [counted from the right](/docs/rate-limiting#trustedproxies).
 ## 1.9.0 — 2026-08-29
 The gaps an app was filling in for itself: one Bun per project, a database backup that is not

package/docs/deployment.md CHANGED Viewed

@@ -38,6 +38,7 @@ deliberate: systemd, your container runtime or your deploy script owns process
 lifecycle, and this gives it a gate to restart behind.
 ```bash
+bun zt deploy:production --check            # run the gate only — see below
 bun zt deploy:production --dry-run          # print the plan, run none of it
 bun zt deploy:production --skip-migrations  # release without touching the schema
 bun zt deploy:production --probe=https://example.com  # real handshake at the end
@@ -75,10 +76,11 @@ Omit the file entirely and you get `DEFAULT_DEPLOY_TARGETS`: `production` and
 ### Your own release gate
 The framework's preflight knows the things a framework can know: that this really is the
-environment you think it is, that the config validators pass, that `doctor` is happy. It
-cannot know that this workspace has no cancellation policy, that mail is still wired to the
-`log` driver so nothing is ever sent, or that the owner account is still on the password
-`admin:create` issued it. Those refusals are yours.
+environment you think it is, that the config validators pass, that `doctor` is happy —
+which now includes refusing a production release whose `mail.driver` is still `log`,
+because mail written to a log file is delivered to nobody and says so nowhere. It
+cannot know that this workspace has no cancellation policy, or that the owner account
+is still on the password `admin:create` issued it. Those refusals are yours.
 Write them as a command and name it `release:check` (exported as
 `CONVENTIONAL_PREFLIGHT_COMMAND`). The pipeline finds it by name — nothing to wire up:
@@ -124,6 +126,27 @@ Two things worth adding while you are there: `assets:build` and `inertia:build`
 `--clean`, which removes anything in the output directory the build did not write — see
 [Build assets](#build-assets).
+### `--check`: the gate on its own
+A release script has a moment where the new code is on disk and the service has not
+restarted yet. That is the moment to ask whether this release is fit to go live, and
+`--check` is the whole preflight and nothing else:
+```bash
+# on the box, after the new release is unpacked and before the restart
+APP_ENV=production bun zt deploy:production --check || exit 1
+systemctl restart app
+```
+It runs the environment check, the config validators with production semantics,
+`doctor`, and your own `release:check` — everything that can refuse — and builds
+nothing, migrates nothing, restarts nothing. Exit 0 and restart; exit non-zero and
+keep serving the previous release, which is the point. A workspace that has lost its
+banking details, or had its mail driver knocked back to `log`, never goes live broken.
+`--check` and `--dry-run` answer different questions. `--dry-run` prints the plan
+without running any of it, including the gate. `--check` runs the gate for real.
 > **Note** — `deploy:<env>` runs **where the app runs**, with that environment's
 > variables. It does not reach another machine over SSH. Run it on the box, or in
 > the container build, as the step before the restart.
@@ -310,6 +333,31 @@ Ordering matters if the old release is still serving traffic: clearing the direc
 its bundles away, so do it as close to the swap as you can, or stage the release in a new
 directory and move it into place.
+### `assets:prune` — clearing up after the extract instead of before it
+Clearing the directory first has a cost the ordering note above hints at: between the
+`rm -rf` and the new files landing, the release still serving traffic has no bundles.
+If you would rather extract over the top and tidy afterwards, `assets:build` records
+what it wrote and `assets:prune` removes what that record does not claim:
+```bash
+# on the build machine — the record is written under .zerotal/
+bun zt assets:build
+tar -czf release.tgz public .zerotal   # ship the record with the release
+# on the server, after extracting and before the restart
+bun zt assets:prune --dry-run          # list what would go
+bun zt assets:prune
+```
+**Ship `.zerotal/` with the release** — that is the part that makes it work. Without
+the record, "which files belong to this release" has no answer on a server that never
+ran a build, and `assets:prune` says so and removes nothing rather than guessing.
+It is conservative by design: it deletes a file only when the record does not claim it
+_and_ it is named the way the bundler names a code-split chunk. Your images and
+favicon are never candidates, because an output directory is usually `public/`.
 ### `--clean` for a directory the build does not own outright
 The cleanup above recognises the filenames `Bun.build()` produces. An app that sets its own

package/docs/helpers.md CHANGED Viewed

@@ -393,6 +393,57 @@ matches how you want overrides to behave.
 > configured `driver`) are replaced by reference — they keep their prototype and are
 > never merged into.
+### `definedOnly` and `Resolved<T>` — merging a shallow options bag
+Every public option shape in the framework declares its optional properties as
+`?: T | undefined`, so that the most ordinary thing there is compiles under the
+`exactOptionalPropertyTypes` the generated `tsconfig.json` turns on:
+```typescript
+// in a controller
+import { Media } from "zerotal/media";
+await Media.store(file, { collection: request.input("collection") ?? undefined });
+```
+That flexibility moves a problem to the merge. **Object spread copies own properties
+even when their value is `undefined`**, so `{ ...DEFAULTS, ...options }` lets an
+explicitly-`undefined` field overwrite a default rather than leave it standing —
+which is how a `pingInterval` of `undefined` once became `setInterval(fn, 0)` and
+~830 pings a second. `definedOnly` is the fix: it drops the keys whose value is
+`undefined`, so "supplied as undefined" reads as "not supplied".
+```typescript fragment
+// in a class that takes options
+const merged = { ...DEFAULTS, ...definedOnly(options) };
+```
+`deepMerge` already does this for you — it skips `undefined` overrides at every
+depth — so `definedOnly` is for the shallow case where a spread is all you need.
+`Resolved<T>` is the type of what comes out. **`Required<T>` is not the same thing**,
+and that is the trap: `-?` removes the optionality a `?` introduced, but it does not
+remove an `undefined` written into the type. So `Required<MediaOptions>` still hands
+back `string | undefined` for a `collection?: string | undefined`, and a "defaults
+have been applied" type quietly stops meaning that.
+```typescript fragment
+// in a class that takes options
+interface Options {
+  retentionDays?: number | undefined;
+  storage?: string | undefined;
+}
+// Required<Pick<Options, "retentionDays">>  →  { retentionDays: number | undefined }  ✗
+// Resolved<Pick<Options, "retentionDays">>  →  { retentionDays: number }              ✓
+private readonly _opts: Resolved<Pick<Options, "retentionDays">> &
+  Omit<Options, "retentionDays">;
+```
+`Omit` rather than `& Options` for the rest: intersecting with the whole shape puts
+the optional declaration of each resolved field back alongside the required one, so
+the field reads as possibly `undefined` in the very code that just gave it a default.
 ## Fluent wrappers
 ### fluent

package/docs/inertia/middleware.md CHANGED Viewed

@@ -50,6 +50,50 @@ would just register it twice (and `useOnce` guards against that anyway).
 > the authenticated user is always populated by the time props are built; you don't
 > need to hand-order `InertiaMiddleware` relative to auth.
+## Which redirects are covered
+**All of them.** `useOnce()` registers `InertiaMiddleware` as _global_ middleware, so it
+runs on every request the app serves — however that route declared its own middleware,
+whether as an array, a map form (`{ ALL, POST }`), a group, or nothing at all. There is
+no route that reaches a controller without passing through it, so there is no redirect
+it does not mark.
+This is worth stating plainly because the opposite belief is expensive. An app that
+thinks some routes miss the middleware writes its own global `InertiaRedirectMiddleware`
+to cover them, and then cannot tell whether it is still needed: removing it leaves every
+test green either way, because the tests assert a status and a `Location` and those were
+never the part that broke.
+Three things have to be true for the Inertia client to follow a redirect, and the
+middleware guarantees all three:
+|                                                                              | Set on                                                                             |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| A redirect status — `303` after a non-GET, so the browser follows with `GET` | every Inertia redirect                                                             |
+| `Location`                                                                   | your handler; carried through untouched, along with `Set-Cookie`                   |
+| `X-Inertia: true`                                                            | **every** Inertia redirect, including one your handler already returned as a `303` |
+That last row is the one that was wrong before 1.8.0: the marker was set inside the
+302→303 conversion, so a handler doing the protocol-correct thing already —
+`http.redirect(to, 303)` — skipped the only line that marked the response as Inertia's.
+The request succeeded, the row was written, and the form sat there with its fields still
+filled in.
+### Pinning it from a test
+`assertRedirect` checks the two headers that were never the problem. `assertInertiaRedirect`
+checks all three:
+```typescript fragment
+// tests/Feature/OrdersTest.ts
+const res = await app.post("/orders", data, { headers: { "X-Inertia": "true" } });
+res.assertInertiaRedirect("/orders/1");
+```
+Send the request with the `X-Inertia` header, or there is nothing to assert — a redirect
+to a browser that is not running Inertia is just a redirect.
 ## Asset versioning
 The asset version is a string sent as part of every page object. When it changes, the

package/docs/inertia/ssr.md CHANGED Viewed

@@ -75,27 +75,112 @@ export class PostController {
 ### Requirements
 - `react-dom/server` ≥ 18 (for `renderToReadableStream`)
+- `@inertiajs/react` — the same adapter the browser entry point uses; the server
+  renders through its `<App>` so `<Head>` works (see below)
 - The HTML template must contain `<!-- @inertia -->`
 - The page component must exist under your pages directory (`resources/js/pages/<component>.tsx`)
-It throws if the template hasn't loaded, or if the component name contains path
-traversal (`..` or a leading `/`).
 ### inertia vs. inertiaStream
-| Criterion      | `inertia()`            | `inertiaStream()`                  |
-| -------------- | ---------------------- | ---------------------------------- |
-| Return type    | `Promise<void>`        | `Promise<void>`                    |
-| Rendering      | Buffered HTML string   | Streaming `renderToReadableStream` |
-| Response body  | Fully buffered string  | Streaming `ReadableStream`         |
-| TTFB           | After full render      | After the prefix is flushed        |
-| XHR navigation | JSON (the normal path) | N/A — only the first-page document |
+| Criterion      | `inertia()`              | `inertiaStream()`                  |
+| -------------- | ------------------------ | ---------------------------------- |
+| Return type    | `Promise<void>`          | `Promise<void>`                    |
+| Rendering      | None — empty root + JSON | Streaming `renderToReadableStream` |
+| Response body  | Fully buffered string    | Streaming `ReadableStream`         |
+| TTFB           | Immediate                | After the shell is ready           |
+| Page `<Head>`  | Client only              | Collected into the served `<head>` |
+| XHR navigation | JSON (the normal path)   | N/A — only the first-page document |
 For XHR navigations (`X-Inertia: true`), keep using `inertia()` — streaming only
 benefits the initial HTML document load.
 > **Tip** — Stream the heaviest landing pages and leave everything else on `inertia()`.
+## Page metadata: `<Head>` on the server
+Both server-rendered paths — `inertiaStream()` and the `/__ssr` endpoint — collect
+whatever your page's `<Head>` declares and splice it into the template's `<head>`
+before the response goes out. A page writes its metadata once, in the component, and
+gets it in the HTML as well as in the browser:
+```tsx fragment
+// resources/js/pages/Trips/Show.tsx
+import { Head } from "@inertiajs/react";
+export default function Show({ trip }) {
+  return (
+    <>
+      <Head>
+        <title>{trip.name}</title>
+        <meta name="description" content={trip.summary} />
+        <meta property="og:title" content={trip.name} />
+        <meta property="og:image" content={trip.heroUrl} />
+      </Head>
+      …
+    </>
+  );
+}
+```
+An injected tag **replaces** the template's tag of the same identity rather than
+being added after it — `<title>` by being a title, `<meta>` by its `name` or
+`property`. That is not a detail: a document with two `<title>` tags is a document
+with the _first_ one, so an appended title would be present, correct and ignored.
+Anything the template does not already declare is appended before `</head>`.
+Two things it does not do:
+- **The title callback is client-side.** `createInertiaApp({ title })` in your
+  browser entry point is not visible to the server, so a page rendering
+  `<Head><title>Kruger</title></Head>` serves `Kruger` and the browser then shows
+  `Kruger — App`. Put the suffix in the `<Head>` itself if the served title matters
+  to you, which for a link preview it usually does.
+- **`inertia()` does not render, so it does not collect.** A page returned through
+  plain `inertia()` sends the template's `<head>` as written. See
+  [What a crawler sees](#what-a-crawler-sees).
+## What a crawler sees
+`inertia()` — the default — **does not server-render the component at all.** Its
+response body is the template with an empty root and the page object beside it:
+```html
+<body>
+  <div id="app"></div>
+  <script type="application/json" data-page="app">
+    { … }
+  </script>
+</body>
+```
+That is the normal Inertia arrangement and it is the right default: the page is
+built by the client, and every navigation after the first is JSON. But it means the
+served document contains **a title and a JSON blob**, and it is worth knowing which
+readers of your site run JavaScript and which do not:
+| Reader                                               | Runs JavaScript       | Sees your page    |
+| ---------------------------------------------------- | --------------------- | ----------------- |
+| A browser                                            | yes                   | yes               |
+| Googlebot, Bingbot                                   | yes, on a second pass | yes, later        |
+| WhatsApp, Slack, iMessage, X, Facebook link previews | **no**                | title + meta only |
+| `curl`, uptime checks, most RSS and reader tools     | **no**                | title + meta only |
+So the link preview a page produces is decided entirely by its `<head>` — which is
+the template's, identically, on every page, unless you do one of these:
+1. **Switch the page to `inertiaStream()`.** The component is rendered, `<Head>` is
+   collected, and the served `<head>` is the page's own. This is the smallest change
+   and the one to reach for on pages that get shared.
+2. **Turn on endpoint SSR** (`ssr: true`) for the whole app.
+3. **Set the tags in middleware**, if the metadata is server-side data the component
+   does not otherwise need.
+`curl` is also how most people first check whether a deploy worked. An empty
+`<div id="app">` in that output is not a broken deploy.
+It throws if the template hasn't loaded, or if the component name contains path
+traversal (`..` or a leading `/`).
 ## Next steps
 - [Inertia overview](/docs/inertia) — the guide's front page and the rest of the sections.

package/docs/middleware.md CHANGED Viewed

@@ -206,6 +206,37 @@ The package ships several middleware you can drop straight into `app.use([...])`
 or a route's middleware array. Each extends `BaseMiddleware`, so `.with({ … })`
 bakes options into a zero-argument class.
+### Names the framework already occupies
+Middleware live in a flat namespace: your `app/middleware/` classes are discovered by
+class name, and so are the ones a package exports. Naming one of yours after one of
+these is not caught as a conflict — it surfaces later as a type error somewhere that
+does not mention either file, which is a confusing way to learn that
+`TwoFactorMiddleware` was taken.
+The full list, so you can check before you name:
+| Middleware                                                                             | Package                          |
+| -------------------------------------------------------------------------------------- | -------------------------------- |
+| `CorsMiddleware`, `SecureHeadersMiddleware`, `ThrottleMiddleware`, `WebhookMiddleware` | `@zerotal/core`                  |
+| `AuthMiddleware`, `GuestMiddleware`, `PersistUserMiddleware`, `RememberMeMiddleware`   | `@zerotal/auth`                  |
+| `BasicAuthMiddleware`, `BearerTokenMiddleware`, `JwtGuardMiddleware`                   | `@zerotal/auth`                  |
+| `RequireRoleMiddleware`, `RequirePermissionMiddleware`, `TwoFactorMiddleware`          | `@zerotal/auth`                  |
+| `ValidateSignatureMiddleware`                                                          | `@zerotal/auth`                  |
+| `SessionMiddleware`, `CsrfMiddleware`, `AuthSessionMiddleware`                         | `@zerotal/session`               |
+| `InertiaMiddleware`, `PrecognitionMiddleware`                                          | `@zerotal/inertia`               |
+| `AdminGuardMiddleware`, `AdminAbilityMiddleware`                                       | `@zerotal/admin`                 |
+| `MonitorAuthMiddleware`, `MonitorPayloadMiddleware`                                    | `@zerotal/monitor`               |
+| `IdempotencyMiddleware`                                                                | `@zerotal/cache`                 |
+| `LocaleMiddleware`                                                                     | `@zerotal/i18n`                  |
+| `EnsureTenancyMiddleware`                                                              | `@zerotal/tenancy`               |
+| `TelemetryMiddleware`                                                                  | `@zerotal/telemetry`             |
+| `BaseMiddleware`                                                                       | `@zerotal/core` (the base class) |
+If yours does something different from the framework's, say so in the name rather
+than shadowing it — `RequireTwoFactorMiddleware` for "fence the console until staff
+have enrolled" reads better than `TwoFactorMiddleware` anyway, and cannot collide.
 ### CorsMiddleware
 ```ts fragment

package/docs/rate-limiting.md CHANGED Viewed

@@ -70,6 +70,14 @@ ThrottleMiddleware.with({
 which entry is not attacker-controlled. Left `undefined` (or `0`), the unspoofable socket
 address is used.
+**Counted from the right, and that is the whole of it.** Each proxy _appends_ the address
+it received the request from, so the rightmost entries are the ones your own
+infrastructure wrote and the leftmost is whatever the client sent. Reading the header
+left-to-right — the obvious way, and how most hand-rolled versions do it — hands the
+limiter's key to the attacker: they set `X-Forwarded-For: <your CFO's IP>`, spend the
+budget, and the person whose address they borrowed is locked out of the form. A limiter
+that can be aimed is worse than no limiter, because it looks like it is working.
 > **Danger** — That default is right, and it is the wrong answer the moment you deploy
 > behind a proxy. The socket address is then the _proxy's_ — `127.0.0.1` for every visitor
 > — so everyone shares one bucket per form and the limiter inverts into the thing it was
@@ -117,8 +125,9 @@ import { RateLimiter } from "zerotal";
 // 1000 req/hour per authenticated user (falls back to IP when unauthenticated)
 RateLimiter.for("api").limit(1000).every(3600).byUser().register();
-// 5 login attempts per minute, per IP
-RateLimiter.for("login").limit(5).every(60).byIp().register();
+// 5 login attempts per minute, per IP. `.trustedProxies(1)` because this app is
+// behind one reverse proxy — without it every visitor shares the proxy's address.
+RateLimiter.for("login").limit(5).every(60).byIp().trustedProxies(1).register();
 // 500 req/min keyed by an API-key header (unknown key → per IP)
 RateLimiter.for("partner").limit(500).every(60).byApiKey("x-api-key").register();
@@ -140,12 +149,30 @@ RateLimiter.for("upload")
 Each `.by*()` call sets how requests are bucketed. The default (no `.by*()` call)
 is the client IP.
-| Method               | Keys on                                     | Falls back to            |
-| -------------------- | ------------------------------------------- | ------------------------ |
-| `.byUser()`          | `ctx.user.id`                               | IP when unauthenticated  |
-| `.byApiKey(header?)` | `x-api-key` header (or a custom header)     | IP when header is absent |
-| `.byIp()`            | Socket IP → `X-Forwarded-For` → `X-Real-IP` | `'unknown'`              |
-| `.by(fn)`            | Return value of your function               | —                        |
+| Method               | Keys on                                 | Falls back to            |
+| -------------------- | --------------------------------------- | ------------------------ |
+| `.byUser()`          | `ctx.user.id`                           | IP when unauthenticated  |
+| `.byApiKey(header?)` | `x-api-key` header (or a custom header) | IP when header is absent |
+| `.byIp()`            | Client IP (the explicit default)        | `'unknown'`              |
+| `.by(fn)`            | Return value of your function           | —                        |
+> **Danger** — **Every one of the built-in strategies can end up keying on an
+> address**, including `.byUser()` and `.byApiKey()` — for a request with no user and
+> no key, which on a login form is every request that matters. So a named limiter
+> behind a reverse proxy needs `.trustedProxies(n)` for exactly the reason
+> [`ThrottleMiddleware` does](#throttlemiddleware--inline): without it the address is
+> the socket's, which is the _proxy's_, and every visitor shares one bucket. A
+> `login` limiter of five attempts a minute becomes five attempts a minute for your
+> whole user base, and one attacker locks everybody out.
+>
+> ```typescript fragment
+> // config/limiters.ts — behind one reverse proxy
+> RateLimiter.for("login").limit(5).every(60).byIp().trustedProxies(1).register();
+> ```
+>
+> `zt doctor` reports a named limiter that keys on an address and was never told
+> about a proxy. `.by(fn)` is yours — it is exempt, and resolving the address is on
+> you if you use one.
 ### Applying a named limiter
@@ -263,15 +290,16 @@ await app.post("/login", { email: "a@b.c" }, { "X-Forwarded-For": "10.0.0.7" });
 ### `LimiterDefinition` (fluent)
-| Method     | Signature                                    | Description                                                |
-| ---------- | -------------------------------------------- | ---------------------------------------------------------- |
-| `limit`    | `limit(max: number): this`                   | Maximum requests in the window (default `60`).             |
-| `every`    | `every(seconds: number): this`               | Window duration in seconds (default `60`).                 |
-| `byUser`   | `byUser(): this`                             | Key by `ctx.user.id`; IP when unauthenticated.             |
-| `byApiKey` | `byApiKey(header?: string): this`            | Key by header value (default `x-api-key`); IP when absent. |
-| `byIp`     | `byIp(): this`                               | Key by client IP (the explicit default).                   |
-| `by`       | `by(fn: (ctx: HttpContext) => string): this` | Key by your own resolver.                                  |
-| `register` | `register(): this`                           | Register the limiter with the global registry.             |
+| Method           | Signature                                    | Description                                                |
+| ---------------- | -------------------------------------------- | ---------------------------------------------------------- |
+| `limit`          | `limit(max: number): this`                   | Maximum requests in the window (default `60`).             |
+| `every`          | `every(seconds: number): this`               | Window duration in seconds (default `60`).                 |
+| `byUser`         | `byUser(): this`                             | Key by `ctx.user.id`; IP when unauthenticated.             |
+| `byApiKey`       | `byApiKey(header?: string): this`            | Key by header value (default `x-api-key`); IP when absent. |
+| `byIp`           | `byIp(): this`                               | Key by client IP (the explicit default).                   |
+| `by`             | `by(fn: (ctx: HttpContext) => string): this` | Key by your own resolver.                                  |
+| `trustedProxies` | `trustedProxies(count: number): this`        | Proxies in front of the app — required behind one.         |
+| `register`       | `register(): this`                           | Register the limiter with the global registry.             |
 ### `ThrottleMiddleware`

package/docs/scheduler.md CHANGED Viewed

@@ -61,17 +61,43 @@ import { SchedulerConfig } from "@zerotal/scheduler";
 import { env } from "zerotal";
 export default SchedulerConfig({
-  timezone: env("APP_TIMEZONE", "UTC"),
+  timezone: env("APP_TIMEZONE", "Africa/Johannesburg"),
 });
 ```
-| Field      | Required | Default | Description                                                                             |
-| ---------- | -------- | ------- | --------------------------------------------------------------------------------------- |
-| `timezone` | no       | `"UTC"` | Informational only — `Bun.cron` uses the system timezone. Set per task with `timezone`. |
+| Field      | Required | Default         | Description                                                                        |
+| ---------- | -------- | --------------- | ---------------------------------------------------------------------------------- |
+| `timezone` | no       | the system zone | IANA zone every cron expression is read in, unless a task sets its own `timezone`. |
-> **Note** — The config `timezone` is informational. To evaluate a cron in a
-> specific zone, set `timezone` on the `Schedule` subclass or `.timezone(tz)` on a
-> facade task; that value is passed through to `Bun.cron`.
+## Timezones
+A cron expression is a wall clock: `0 3 * * *` means three in the morning
+_somewhere_. By default that somewhere is the server's zone. Set `scheduler.timezone`
+to make it one zone for the whole app, or `timezone` on a single schedule to override
+it:
+```typescript fragment
+export class SendDailyReports extends Schedule {
+  cron = "0 8 * * *";
+  timezone = "Africa/Johannesburg"; // 08:00 there, whatever the server is on
+}
+```
+The zone is evaluated by Zerotal, not by `Bun.cron` — which reads the system zone and
+has no option to change it. A zoned task ticks every minute and runs on the ticks
+where its expression matches the clock in its own zone, so it stays correct across a
+daylight-saving change rather than drifting by an hour twice a year. A minute is also
+the finest granularity `Bun.cron` accepts, so nothing is given up.
+Two consequences worth knowing:
+- **A skipped hour skips the schedules inside it, and a repeated hour runs them
+  twice.** That is what every cron does. A task at `0 2 * * *` in a zone that springs
+  from 01:59 to 03:00 does not run that day.
+- **An unknown zone name refuses at boot, loudly, and takes only its own task out.**
+  A registration failure used to propagate: the worker died during boot and
+  restart-looped, so one bad schedule stopped every schedule in the app. Now the
+  others start and the log names the one that did not.
 ## Defining schedules
@@ -134,7 +160,7 @@ Every setting is an optional property (or method) on your `Schedule` subclass:
 | `cron`                                                         | `string`                        | Cron expression (5- or 6-field). Set this **or** override `frequency()`.                                      |
 | `frequency(every)`                                             | method                          | Build the cadence fluently; return the task (see helpers below).                                              |
 | `name`                                                         | `string`                        | Task name in `schedule:list` and logs. Defaults to the class name.                                            |
-| `timezone`                                                     | `string`                        | IANA timezone the cron is evaluated in.                                                                       |
+| `timezone`                                                     | `string`                        | IANA timezone the cron is evaluated in — overrides `scheduler.timezone`. See [Timezones](#timezones).         |
 | `withoutOverlapping`                                           | `boolean \| OverlapLockOptions` | Skip a tick while a previous run is active; also takes a cross-process lock when a lock driver is configured. |
 | `environments`                                                 | `string[]`                      | Only run when `APP_ENV` is one of these.                                                                      |
 | `inBackground`                                                 | `boolean`                       | Run the body without blocking the scheduler tick.                                                             |
@@ -489,6 +515,19 @@ override async onStarted(): Promise<void> {
 For production, run the worker as a separate process so it can be scaled, restarted,
 and monitored independently of the web server.
+> **A web process says so when it is not running your schedules.** `app/schedules/`
+> is only discovered in `worker` and `console`, so a web process skips it by not
+> looking — which used to be completely silent, and is how an app runs for weeks in
+> production with every schedule written and none of them ever firing. A boot line
+> now names it:
+>
+> ```
+> Skipping 3 file(s) in app/schedules — the "schedules" convention does not run in env=web (it runs in: worker, console).
+> ```
+>
+> Seeing that on a web process is correct. Seeing it and having no worker running is
+> the hole.
 ## References
 The `Scheduler` facade resolves the `scheduler` container binding — a
@@ -514,6 +553,30 @@ The `Scheduler` facade resolves the `scheduler` container binding — a
 | `stop`  | `stop(): void`                                                     | Stop every running task.                           |
 | `tasks` | `get tasks(): ReadonlyMap<string, ScheduledTask>`                  | The registered tasks, keyed by name.               |
+### Timezone helpers
+The zone arithmetic the scheduler uses to evaluate a cron somewhere other than the
+server, exported because an app doing its own time-window logic needs the same
+answers.
+| Export                          | Signature                                            | Description                                                                                    |
+| ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `isValidTimeZone`               | `isValidTimeZone(tz: string): boolean`               | Whether this runtime knows the IANA zone. Check before storing one a user typed.               |
+| `wallClockIn`                   | `wallClockIn(date: Date, tz: string): Date`          | The same instant, shifted so the Date's _local_ getters read that zone's clock face.           |
+| `CronExpression.matchesIn`      | `matchesIn(date: Date, tz: string): boolean`         | Whether the expression fires at `date`, read in `tz`.                                          |
+| `CronExpression.nextRunAfterIn` | `nextRunAfterIn(expr, from: Date, tz): Date \| null` | The next real instant the expression fires on that zone's clock — correct across a DST change. |
+`wallClockIn` returns a Date that is a lie about the instant and true about the clock
+face: its epoch value is off by the zone offset. Pass it to a field comparison, never
+back to a caller.
+### Errors
+| Error                  | Thrown when                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| `SchedulerError`       | Base class for everything this package throws. Catch it to catch them all.                  |
+| `UnknownTimeZoneError` | A task declares a `timezone` this runtime does not know — at registration, naming the task. |
 ### ScheduledTask introspection
 | Member             | Signature                                   | Description                                       |

package/docs/testing/index.md CHANGED Viewed

@@ -209,6 +209,105 @@ observers, global scopes, and state-machine callbacks, plus framework event
 subscriptions. `createTestApp()` and `testApp.close()` call it for you, so suites
 using those helpers don't need the explicit `afterEach`.
+## `bun test` vs `bun zt test`
+Both run the same files. `bun zt test` is a wrapper that sets up three things Bun's
+runner does not, and each of them has cost somebody a day:
+|                  | `bun test`            | `bun zt test`                                              |
+| ---------------- | --------------------- | ---------------------------------------------------------- |
+| Per-test timeout | Bun's default, 5000ms | 30000ms (`--timeout`, override with `--timeout=`)          |
+| Runtime check    | none                  | refuses a Bun below the project's `engines.bun`            |
+| DB wiring        | none                  | preloads `@zerotal/testing/preload` and passes `ZT_DB_URL` |
+### The timeout
+Bun's default per-test timeout is 5000ms, and a suite that boots an app per file
+exceeds it on a loaded machine — CI, or a laptop that has just run `tsc`. The
+failures look like flakes, which is the expensive part: a flake gets re-run, and a
+re-run passes.
+`bun zt test` sets `--timeout=30000`. If you run `bun test` directly, pass it
+yourself, because **the two documented-looking alternatives do not work**:
+- `[test] timeout` in `bunfig.toml` — ignored.
+- `setDefaultTimeout()` in a preload — applies to the first test file only. Bun
+  re-imports the preload per file, but the setting does not survive.
+The command-line flag is the only mechanism that covers hooks as well as tests,
+which matters because it is usually a `beforeAll` that boots the app.
+### The runtime
+`engines.bun` in your `package.json` is a floor, and until you enforce it, it is a
+comment. The shell's `bun` and the project's can differ, and the difference between
+two Bun releases is real and narrow: `Intl` formatting, the SQLite bindings and
+`node:` compatibility all move. So a handful of currency or date assertions go red
+and the rest pass, and you go looking for a bug in the code they touch, because
+nothing in the failure says "wrong binary".
+`bun zt test` refuses to run below the declared floor. Direct `bun test` runs get the
+same check as a warning if you load the preload:
+```toml
+# bunfig.toml
+[test]
+preload = ["@zerotal/testing/preload"]
+timeout = 30000  # note: currently ignored by Bun — pass --timeout on the command line
+```
+Set `ZT_ALLOW_RUNTIME_MISMATCH=1` to downgrade the refusal to a warning while you
+are mid-upgrade.
+### `@zerotal/core/runtime`
+The checks behind the two paragraphs above, exported so a script or a test of your
+own can make the same assertion. `zt` runs both at the top of every command; the test
+preload runs the floor check as a warning.
+| Export                     | Signature                                                 | What it answers                                                                             |
+| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `declaredBunFloor`         | `declaredBunFloor(cwd): { range, manifest } \| null`      | The nearest `engines.bun` up the tree from `cwd`.                                           |
+| `runtimeBelowFloor`        | `runtimeBelowFloor(cwd?): RuntimeFloor \| null`           | Is this process below that floor? `null` when it is met or none is declared.                |
+| `runtimeBelowFloorMessage` | `runtimeBelowFloorMessage(floor): string`                 | The explanation to print — both versions, the manifest, and the way out.                    |
+| `installedBunVersion`      | `installedBunVersion(cwd): { version, manifest } \| null` | The Bun in `node_modules`, if the project installs one as a package.                        |
+| `runtimeMismatch`          | `runtimeMismatch(cwd?): RuntimeMismatch \| null`          | Does the running Bun differ from the installed one? Compared exactly — a patch is a binary. |
+| `runtimeMismatchMessage`   | `runtimeMismatchMessage(mismatch): string`                | The explanation for that one.                                                               |
+| `runtimeMismatchAllowed`   | `runtimeMismatchAllowed(): boolean`                       | Whether `ZT_ALLOW_RUNTIME_MISMATCH` is set.                                                 |
+| `bunBinary`                | `bunBinary(): string`                                     | The binary to spawn a child with — `process.execPath`, never the name PATH resolves.        |
+| `RUNTIME_MISMATCH_ESCAPE`  | `"ZT_ALLOW_RUNTIME_MISMATCH"`                             | The env var name, so a script can set it without hardcoding the string.                     |
+`RuntimeFloor` is `{ running, required, manifest }`; `RuntimeMismatch` is
+`{ running, installed, manifest }`. Both name the file the second version came from,
+because "which one is wrong" is the question you actually have.
+## Configuration is per-process, and `bun test` is one process
+Zerotal resolves configuration once, at boot. `bun test` runs every file in the same
+process, so **whichever file boots the app first fixes the configuration for all of
+them.**
+A test that sets an environment variable in its own `beforeAll` and then asserts on
+the resulting behaviour passes alone and fails in the suite — or worse, passes in the
+suite for a reason unrelated to what it claims to test:
+```typescript fragment
+// Passes alone. In a suite, the app may already be booted with CSRF on, and the
+// three "rejects without a token" assertions below pass on a 419 they would have
+// got anyway — never reaching the guard they name.
+beforeAll(() => {
+  Bun.env.CSRF_DISABLED = "1";
+});
+```
+Assert on the _relationship_ rather than on a literal — the published origin equals
+the configured one, whatever it is — or boot a dedicated app for the case:
+```typescript fragment
+const app = await createTestApp({ config: { app: { url: "https://example.test" } } });
+expect(page.canonical).toBe(config("app.url"));
+```
 ## Running the suite from a script
 A script that gates on the tests has to read the tests' exit status, and a pipe hides it:

package/docs/upgrade.md CHANGED Viewed

@@ -169,6 +169,54 @@ these are the changes that need action. Full detail is in the
    interface so pages that read them do not look unpassed; see
    [Typed props](/docs/inertia/props#typed-props).
+## 1.9 to 1.10
+Three settings changed meaning. Each is quiet if it does not apply to you, and each is
+worth thirty seconds of checking if it does.
+1. **`scheduler.timezone` is honoured.** It was documented as informational and read by
+   nothing, so whatever you put there had no effect and your schedules ran in the
+   server's zone. It is now the zone every schedule is evaluated in unless the task sets
+   its own.
+   Its default moved from the literal `"UTC"` to **the system zone**, so an app that never
+   set the key keeps doing exactly what it did. The case to check is an app that _did_:
+   ```ts fragment
+   // config/scheduler.ts
+   export default SchedulerConfig({ timezone: env("APP_TIMEZONE", "UTC") });
+   ```
+   On a server that is not on UTC, that line used to do nothing and now moves every
+   schedule. Either set it to the zone you actually want your crons read in — which is
+   the point of the setting — or delete the key to keep the server's zone.
+   `bun zt schedule:list` prints each task's next run in its own zone, which is the
+   quickest way to see whether anything moved.
+2. **Named rate limiters need `.trustedProxies(n)` behind a proxy.** `RateLimiter`'s
+   `.byIp()`, `.byUser()` and `.byApiKey()` ignored the proxy count entirely and read
+   `X-Forwarded-For` unconditionally. They now follow the same rule `ThrottleMiddleware`
+   already did — the header is consulted only when you say how many proxies sit in front:
+   ```ts fragment
+   RateLimiter.for("login").limit(5).every(60).byIp().trustedProxies(1).register();
+   ```
+   Without it the address used is the socket's, which behind a proxy is the _proxy's_, and
+   every visitor shares one bucket. `bun zt doctor` reports any limiter that needs this —
+   it could not before, because its check exempted custom key resolvers and all three of
+   these are one.
+3. **React apps using SSR need `@inertiajs/react` installed.** The same adapter your
+   browser entry point already uses. Server-side rendering now goes through its `<App>`,
+   which is what makes `<Head>` produce a title and an og: card in the HTML your server
+   actually sends. If it is missing you get a named error at render time, not a silent
+   omission.
+   Nothing to change if you already have it as a dependency, which every React Inertia app
+   does.
 ## The managed zt.ts
 `zt.ts` is framework-managed — the header says _do not modify_. If a release

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0"
+    "@zerotal/core": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.9.0"
+    "@zerotal/orm": "1.10.0"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [

package/src/install/guidelines.ts CHANGED Viewed

@@ -150,7 +150,7 @@ export interface GuidelineOptions {
    * How this project is configured, from {@link detectShape}. Omitted, the block
    * is what it always was — a function of the package list.
    */
-  shape?: ProjectShape;
+  shape?: ProjectShape | undefined;
 }
 /**

package/src/mcp/stdio.ts CHANGED Viewed

@@ -27,11 +27,11 @@ import type { JsonRpcResponse } from "./types.ts";
 export interface StdioOptions {
   server: McpServer;
   /** Byte source. Defaults to this process's stdin. */
-  input?: ReadableStream<Uint8Array>;
+  input?: ReadableStream<Uint8Array> | undefined;
   /** Frame sink. Defaults to this process's stdout. Injected in tests. */
-  write?: (frame: string) => void;
+  write?: ((frame: string) => void) | undefined;
   /** Diagnostics sink. Defaults to stderr — never stdout. */
-  log?: (message: string) => void;
+  log?: ((message: string) => void) | undefined;
 }
 /**

package/src/tools/_probe.ts CHANGED Viewed

@@ -35,8 +35,8 @@ export interface ProbeRunner {
 export interface SpawnProbeOptions {
   /** Where to start looking for the app. Defaults to the server's working directory. */
-  cwd?: string;
-  timeoutMs?: number;
+  cwd?: string | undefined;
+  timeoutMs?: number | undefined;
 }
 /**