@zerotal/arch 1.7.4 → 1.8.0

package/docs/changelog.md

@@ -27,6 +27,247 @@ 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.8.0 — 2026-08-24
+
+The first render mode, the codemod runner 2.0 depends on, and four failures that
+each looked like something other than what they were.
+
+### Added
+
+- **`static interactive = false` — the first rung of Flow's render modes.** Every component
+  until now was maximally interactive: rendered on the server, dehydrated into a snapshot,
+  tracked by the client, reachable over a socket. Right for a counter, wasteful for a nav rail.
+  A static component is rendered in full by its parent and nothing else — no `onDehydrate`, no
+  snapshot, no `<script type="application/json">`, no entry in the client's registry, and no
+  `data-flow-root`, which would freeze it at its first render since its only route to an update
+  is the parent re-rendering it. It takes no place in `_childIds` and does not shift its
+  interactive siblings' ids, so no sibling remounts and loses its state when a static one
+  appears above it. `lazy`, `defer` and `stream` throw rather than being ignored: each waits
+  for the client to ask for the real render, and a static child never registers to do the
+  asking.
+
+  Opt-in — nothing existing changes. `this.isInteractive` reports the mode from inside the
+  component, and being a new public member it takes that name away from applications; it is on
+  the documented reserved list. See [Static children](/docs/flow/layouts#static-children).
+
+- **`zt upgrade` — the codemod runner.** The 2.0 ledger's rule is that every entry that can
+  have a codemod has one before 2.0 ships, and until now nothing had been built, which made
+  the ledger a list of changes nobody could afford to make.
+
+  **Dry by default**, which is backwards from most tools and deliberate: it rewrites source
+  across a whole project, and the first run should be something you can read and disagree with.
+  `--write` applies it. Nothing is written until the whole plan is known, so a run that fails
+  halfway leaves no half-upgraded tree, and `--dry` exercises the same code path as the real
+  thing rather than a parallel one that can drift from it. Codemods see each other's output,
+  because two of them touching one file across a version range is ordinary.
+
+  **What it could not do is the headline.** A codemod that walks past what it does not
+  understand is worse than none, since the changes it _did_ make imply the job is finished. So
+  every codemod returns two lists and the runner prints the second last and loudest, with file,
+  line and a reason. The first codemod covers the deprecated aliases — `BaseModel` → `Model`,
+  `routes:types` → `route:types`, `serve --dev` → `dev`. See [Commands](/docs/commands).
+
+- **`--clean` on `assets:build` and `inertia:build`.** Pruning is conservative by default:
+  chunk-shaped filenames, plus whatever the last build on this machine recorded in `.zerotal/`.
+  That cannot recognise output some other naming produced. `--clean` needs no record — the
+  output directory belongs to the build, and what the build did not write does not belong in
+  it. It refuses `public/` and the project root, where deleting what was not rebuilt takes the
+  app's images and favicon with it, which is the one failure here that building again cannot
+  undo. Pruning stays the default; only you can say the directory holds nothing else.
+
+- **Agent skills, from `@zerotal/arch`.** `AGENTS.md` is short because every prompt it lands
+  in pays for its whole length, so it points rather than teaches. That has a cost: an agent
+  gets a map and no detail, and the detail is where the expensive mistakes live. A skill is a
+  file with a one-line description that costs nothing until an agent decides it is relevant,
+  so a procedure can be written out in full. Two ship — one on changing the schema (who owns
+  it in your app, the mixin columns nothing declares, and why an unguarded `ALTER TABLE`
+  collides during a release's `migrate`) and one on shipping a release (naming your own deploy
+  steps, replacing the asset directory rather than merging into it, `trustedProxies` behind a
+  proxy, and the pipe that hides a test suite's exit status).
+
+  Written to `.agents/skills`, plus `.claude/skills` when that agent is detected. To replace
+  one this ships, edit it and delete its marker line — a `SKILL.md` without the marker is
+  yours and is never rewritten. `ArchConfig({ skills: false })` turns the feature off. Run
+  `zt arch:update` to install them.
+
+- **`zt doctor` reports agent instructions that no longer describe your project.** Every fact
+  in the generated block moves without anyone thinking about the file: add a migrations
+  directory, turn `synchronize` off, install a package. It goes on reading as current while
+  describing the app you used to have, and guidance that is confidently out of date gets
+  followed rather than questioned. Skills rot the same way and are easier to miss, since
+  nothing reads one until an agent decides it is relevant — by which point it is being acted
+  on. The check regenerates both and compares, and names `zt arch:update` as the fix. A
+  warning, not a failure: it misleads a reader, it does not stop the app working.
+
+### Changed
+
+- **A Flow page with nothing interactive on it opens no socket.** Every page connected at
+  boot, unconditionally — so a marketing page, a docs article or a rendered report held a
+  WebSocket per visitor, open on both ends for the life of the visit, to carry nothing. Both
+  paths that write to the socket take a `FlowComponent`, so with none registered there was not
+  a frame that _could_ be sent. The connection is made when something needs it now: after the
+  initial scan, after an SPA navigation, after a patch registers a child. `<Link navigate>`
+  fetches over HTTP, so a static page with links stays disconnected. A routed page honours the
+  same static, which is the half that matters — a page is a component, and one whose children
+  are static but which is interactive itself still connects.
+
+- **The `@zerotal/arch` agent block describes how your app is set up, not only what it
+  installed.** A package list answers "what is available here", which is not the question that
+  decides what an agent should write: the framework's contracts are not uniform across
+  projects, and the places they differ are the places where guessing wrong compiles cleanly and
+  fails at runtime. `AGENTS.md` now states the four facts that change an instruction — who owns
+  the schema, whether route names are typed, whether `exactOptionalPropertyTypes` or
+  `noUncheckedIndexedAccess` are on, and whether there are tests to run. Read off disk rather
+  than from a booted app, because a project that will not boot is often why the agent surface
+  is being installed. `.env` is deliberately not among the files read: this output is committed
+  and pasted into prompts, and a detector that reads secrets is one refactor away from emitting
+  them. Re-run `zt arch:update` to pick it up.
+
+### Fixed
+
+- **No mail could be sent over port 587.** A STARTTLS upgrade hands back a new socket and
+  leaves the old one attached, still firing its callbacks — and what that one delivers from
+  then on is the undecrypted TLS stream. Both sets of handlers appended to a single reply
+  buffer, so handshake records and ciphertext sat in the middle of the server's replies and no
+  line in the buffer matched a reply any more: the driver waited out its timeout without ever
+  parsing the `250`, and the server logged a connection lost after STARTTLS. Measured, 1,737
+  bytes of ciphertext went into the discarded socket's handler while the TLS handler received
+  the replies.
+
+  `close` and `error` were worse than `data`. The plaintext socket ending is a normal part of
+  handing over to TLS, and it marked the live connection closed — rejecting whatever was
+  waiting on the session that had just replaced it. Each set of callbacks now captures the
+  generation it was installed for, and an upgrade bumps it.
+
+- **An Inertia `303` redirect left the browser doing nothing at all.** `X-Inertia: true` was
+  set inside the 302-to-303 conversion, so it only ever reached a redirect that arrived as a
+  301 or 302 from a non-GET handler. A handler returning the 303 the protocol asks for skipped
+  the only line that marked its response — and `redirect(to, 303)` is what
+  [Authentication](/docs/authentication) tells people to write, in eight places. The form
+  submitted, the row was written, the mail went out, and the fields stayed filled in: a hang
+  from both ends, which is the worst shape a failure can take. Marking now happens for every
+  redirect status on an Inertia request, with the conversion a separate decision on top of it.
+  `307` and `308` are marked but left alone, since preserving the method is the whole reason to
+  choose them.
+
+- **Answering the busy-port menu killed `serve --dev` on the spot.** The banner printed, then
+  `exited with code 1`, and nothing said why. Reading a prompt locks Bun's stdin stream, and
+  the lock is deliberately held for the life of the command so a second prompt can still read —
+  so the dev deck taking the terminal over threw `ReadableStream is locked`. It died inside the
+  alternate screen buffer, and restoring the terminal on the way out erased the error along
+  with everything else drawn there, which is why this was reported as "it just exits" rather
+  than as the error it was. The prompt hands stdin back where it took it; a deck that still
+  cannot have stdin degrades to streaming rather than dying, and a dev-mode failure stops the
+  deck before it reports.
+
+- **Two builds sharing an output directory deleted each other's files.** Nothing forbids
+  `inertia:build` and `assets:build` writing to the same place, and the defaults invite it: one
+  writes to `public/assets`, `app.assets.outDir` often names the same directory, and the
+  default release pipeline runs them one after the other. The record of what to prune was one
+  flat list per directory, so each build read the other's files as its own previous build and
+  removed them. The release ended with whichever ran last and nothing reported a problem — the
+  build that lost still said "Build complete" on its way out, and the page it served then 404'd
+  its own script. The record is keyed by entry point now: a file another build claimed is not
+  this one's to remove, while chunks nobody claims are still swept.
+
+- **`zt doctor` failed a schema configuration that works.** Sync on plus migrations present
+  read as "the schema needs exactly one source of truth", which misses the documented
+  arrangement where sync builds the schema from the models so a fresh clone runs without a
+  migration step, and `synchronize` is an expression that is false in production, where the
+  deploy runs `migrate`. The two never apply in the same environment. It fails in production
+  now, where the deploy really does run both, and warns elsewhere. A check that cries wolf
+  against a correct configuration is what stops `zt doctor` ever being trusted to gate a
+  deploy.
+
+### Documented
+
+- **Replace a release directory, do not merge into it.** Chasing 195 orphaned chunks on a
+  server showed the build was never the problem — ten releases of a code-split app into one
+  directory hold steady at the build's own output, and every one of the reporting app's 68
+  chunks is referenced. What accumulates is the _release_: the archive is extracted over the
+  running directory, so every file in it is written and every file not in it is left alone, and
+  nothing on that machine ever runs a build. They stay publicly fetchable at their
+  content-hashed URLs, which is how copy that was taken down went on being served.
+  [Deployment](/docs/deployment) now gives the two spellings that replace the directory.
+
+## 1.7.5 — 2026-08-23
+
+Two bugs that shipped to every deployed app, a package promoted to `stable`, and
+the gates that would have caught both.
+
+### Changed
+
+- **`@zerotal/arch` is `stable`.** Reviewed ahead of its 1.9.0 date. The API follows
+  SemVer strictly from here, and that promise covers the **MCP tool contract** — tool
+  names, their arguments, and the shape of what they return. That is what an agent
+  client is configured against, and nothing type-level can see it: `archTools` has the
+  same signature however the tools are named. `mcp-surface.md` records all nine and CI
+  diffs it on every change. The protocol revision the server speaks is not covered; it
+  follows the protocol.
+
+- **INTERNAL — the writers behind `arch:install` are no longer public API.**
+  `detectAgents`, `applyMcpConfig`, `applyBlock`, `buildGuidelines` and the rest are
+  `@internal`: still exported, still working, no longer promised. Their only caller is
+  the install command, and freezing them would have committed the shape of `.mcp.json`
+  writing to the rest of the 1.x line on behalf of a caller who never arrived.
+
+- **INTERNAL — `api-surface.md` honours `@internal` across every package.** The
+  contract has always read "anything importable without an `@internal` marker keeps its
+  shape", and the generator did not read the tag — so symbols already marked internal
+  were recorded as though promised. 374 entries across 13 packages are omitted now,
+  every one verified marked. Nothing changes at runtime or in the types; the file
+  listing the promises now lists the promises.
+
+- **A modal locks the page behind it.** `<Modal>` and `<Drawer>` trapped focus
+  correctly while the page underneath kept scrolling, which on a phone reads as the
+  dialog having broken the page.
+
+- **Flow marks the active nav link for everyone.** `<Link navigate>` set
+  `data-current`, which styles a link, and nothing that announces it. It sets
+  `aria-current="page"` alongside now, so a screen reader can tell which of thirty nav
+  items is the current page.
+
+### Fixed
+
+- **Assets were cache-busted in development and not in production.** `asset()` appended
+  `?v=` only when a dev version was set, so every deployed Zerotal app served the
+  previous build's JavaScript and CSS to anyone with a warm cache — indefinitely, since
+  the URL never changed. The version is now derived from the built files themselves, so
+  it is stable across restarts and moves when the files do.
+
+- **DevTools mounted on production pages.** The provider is gated on the environment, so
+  the endpoints are absent outside development — and the client took that to mean it
+  could start anyway, pinning a floating panel to the page whose tabs read
+  `Could not read the map — HTTP 404`. It now mounts only when the server half says it
+  is there, via a `<meta>` the middleware writes, and makes no request at all on a
+  public hostname.
+
+- **Browser tests drove an unstyled site.** `Router.static("/", public)` is registered
+  only for the `web` environment, and a test app is not one — so every `FlowBrowser`
+  suite served pages without their stylesheet. Invisible to assertions that read text;
+  fatal for anything measuring layout.
+
+### Documented
+
+- **Every TypeScript example in the documentation is compiled against the real
+  packages**, on every pull request. 1,593 blocks. The gate found examples importing
+  symbols that do not exist (`currentUser`, `Layout` from the wrong package), calling
+  methods that were renamed (`Cache.put`), and configuring fields with `env()` where the
+  type is a literal union. Blocks deliberately written as fragments say so in their
+  fence and are recorded by key, so a new one is a deliberate act rather than a silent
+  exemption.
+
+- **A break cannot ship without a release note.** `api:surface:check` demands a
+  regenerated snapshot when an export changes and then goes quiet, so the changelog was
+  defended by remembering — and 1.7.3 shipped the removal of Flow's `this.title(…)` with
+  no BREAKING entry. That entry is now in 1.7.3's notes, the support policy counts three
+  breaks rather than two, and `breaking:check` reads the snapshot diff so the next one
+  cannot pass silently.
+
+- **A maturity label falls due.** The review release for a package below `stable` lives
+  in its `package.json` as `maturityReview`, and the package-conventions gate fails once
+  the version reaches it.
+
 ## 1.7.4 — 2026-08-21
 
 A debug panel that was reaching production, a column type MySQL would not index, and
@@ -89,7 +330,33 @@ A debug panel that was reaching production, a column type MySQL would not index,
 
 ## 1.7.3 — 2026-08-20
 
-Two fields that accepted input and threw it away, and a CI job that was testing nothing.
+Two fields that accepted input and threw it away, a CI job that was testing nothing, and a
+name given back to applications.
+
+### Changed
+
+- **BREAKING — `this.title(…)` is removed from Flow components.** Declare `static title`
+  instead, as a string or a function of the component:
+
+  ```ts fragment
+  // Before
+  override async mount(): Promise<void> {
+    this.title(`Search: ${this.query}`);
+  }
+
+  // After
+  static title = (c: SearchPage) => (c.query ? `Search: ${c.query}` : "Search");
+  ```
+
+  The instance method held a name four separate components wanted for their own data — a
+  media row, a guide, a review, an issue — for a one-line accessor that belongs on the class.
+  The static form is also the better one: it is resolved on the server for every render and
+  every patch, so a title that depends on state follows it without an action remembering to
+  update it.
+
+  A call to `this.title(…)` on a component that declares its own `title` field now sets that
+  field instead of the document title, which is silent. Search your components for
+  `this.title(` before upgrading; every hit is either a migration or was already shadowed.
 
 ### Fixed
 

package/docs/client/index.md

@@ -10,7 +10,7 @@ looking up an address. `@zerotal/client` is the outbound HTTP client — a thin,
 expressive wrapper over `fetch` that adds what every real integration ends up
 needing anyway and that is tedious to get right by hand.
 
-```ts
+```ts fragment
 import { Client } from "@zerotal/client";
 
 const charge = await Client.post("https://api.stripe.com/v1/charges", {
@@ -71,7 +71,7 @@ otherwise. A 2xx returns; anything else throws, which [Errors](#errors) covers.
 
 ### Query parameters
 
-```ts
+```ts fragment
 await Client.get("https://api.example.com/v1/charges", undefined, {
   query: { limit: 25, status: "succeeded", created: { gte: 1_700_000_000 } },
 });
@@ -87,7 +87,7 @@ A plain object or array is JSON-encoded with the matching `Content-Type`. Anythi
 a raw string — passes straight through, so the runtime sets the header itself
 (including multipart boundaries):
 
-```ts
+```ts fragment
 // Form-encoded, which several gateways still require
 await Client.post(
   "https://api.example.com/v1/charges",
@@ -99,7 +99,7 @@ await Client.post(
 
 Per request, merged over the client's defaults:
 
-```ts
+```ts fragment
 await Client.post("https://api.example.com/v1/messages", payload, {
   headers: { "Idempotency-Key": crypto.randomUUID() },
 });
@@ -125,7 +125,7 @@ export default ClientConfig({
 A `token` may also be a function, including an async one, which is how credentials
 that expire are handled — it is resolved per request:
 
-```ts
+```ts fragment
 export default ClientConfig({
   token: async () => await currentAccessToken(),
 });
@@ -136,7 +136,7 @@ Change it at runtime with `setToken(token)`, or pass `null` to clear it. Its typ
 
 For an API that wants something other than a bearer token, set the header directly:
 
-```ts
+```ts fragment
 export default ClientConfig({
   headers: { "X-Api-Key": env("PARTNER_API_KEY", "") },
 });
@@ -147,7 +147,7 @@ export default ClientConfig({
 `onUnauthorized` receives the error and a `retry` function, so a token can be
 refreshed and the original request replayed once:
 
-```ts
+```ts fragment
 export default ClientConfig({
   onUnauthorized: async (error, retry) => retry({ Authorization: `Bearer ${await refresh()}` }),
 });
@@ -158,7 +158,7 @@ export default ClientConfig({
 There is no timeout by default, because the right one depends on the upstream. Set a
 default and override per request:
 
-```ts
+```ts fragment
 export default ClientConfig({ timeout: 10_000 });
 
 // This one is slow and we accept that
@@ -174,7 +174,7 @@ A network blip or a `503` is worth trying again; a `422` never is. `retry` retri
 idempotent requests on network errors, 5xx and 429 with exponential backoff, and
 honours a `Retry-After` header when the server sends one:
 
-```ts
+```ts fragment
 export default ClientConfig({ retry: 2 });
 
 await Client.post("https://api.example.com/v1/charges", body, { retry: false });
@@ -189,7 +189,7 @@ statuses qualify.
 
 A non-2xx throws `ApiClientError`, carrying what you need to decide what happened:
 
-```ts
+```ts fragment
 import { ApiClientError } from "@zerotal/client";
 
 try {
@@ -219,7 +219,7 @@ everything queued behind it. A `CircuitBreaker` stops after a threshold of
 consecutive failures, fails fast for a cooldown, then lets a single request through
 to test the water:
 
-```ts
+```ts fragment
 export default ClientConfig({
   circuitBreaker: { threshold: 5, cooldownMs: 30_000 },
 });
@@ -237,7 +237,7 @@ to the same upstream and should trip together.
 
 Upload with `FormData`; download by asking for the body you want:
 
-```ts
+```ts fragment
 const form = new FormData();
 form.append("file", Bun.file("./invoice.pdf"));
 await Client.post("https://api.example.com/v1/documents", form);
@@ -255,7 +255,7 @@ const pdf = await Client.get("https://api.example.com/v1/documents/doc_1", undef
 `onResponse` runs after every 2xx with the `ResponseContext`. Both take one function
 or an array:
 
-```ts
+```ts fragment
 export default ClientConfig({
   onRequest: (config) => {
     config.headers["X-Request-Id"] = crypto.randomUUID();

package/docs/commands.md

@@ -72,7 +72,7 @@ signature's first token is the name; `{arg}` is required, `{arg?}` optional,
 `{arg=default}` has a default, `{--flag}` is a boolean flag, and `{--flag=}` /
 `{--flag=default}` is a string flag.
 
-```typescript
+```typescript fragment
 // in a service provider or bootstrap script
 const runner = app.container.tryMake("commands");
 
@@ -110,7 +110,7 @@ so it wins a name collision. The directory is configurable via
 
 To register a folder from somewhere else, call `discover()` yourself:
 
-```typescript
+```typescript fragment
 // in a service provider or bootstrap script
 await runner.discover("./vendor/acme/commands");
 ```
@@ -124,7 +124,7 @@ returns the list of registered names.
 The `Command` base class provides coloured output helpers and interactive
 prompts. The prompts read from stdin and only work on a real TTY:
 
-```typescript
+```typescript fragment
 // inside a command's run()
 this.info("Success"); // green
 this.warn("Heads up"); // yellow
@@ -291,7 +291,7 @@ Dev processes
 Your app has the last word. `app.dev.disable` removes a process by name, and
 registering the same name again replaces it rather than adding a second tab:
 
-```ts
+```ts fragment
 // config/app.ts
 export default AppConfig({
   dev: {
@@ -315,6 +315,38 @@ Packages register their own — see
 | `bun zt doctor`        | Check the app for silent misconfigurations             |
 | `bun zt key:generate`  | Generate a new `APP_KEY` and write it to `.env`        |
 | `bun zt lint:packages` | Check every workspace package against convention rules |
+| `bun zt upgrade`       | Apply the codemods for a version upgrade               |
+
+### Upgrading between versions
+
+`bun zt upgrade --to <version>` applies the codemods a version gap calls for —
+mechanical rewrites the framework can make on your behalf when an API changes.
+
+```bash
+bun zt upgrade --to 2.0.0            # print the plan, change nothing
+bun zt upgrade --to 2.0.0 --write    # apply it
+```
+
+**It writes nothing unless you ask.** That is the opposite of most tools and
+deliberate: it rewrites source across your whole project, so the first run should
+be something you can read and disagree with. `--from` defaults to the `zerotal`
+version in your `package.json`.
+
+The half worth reading is the last one. A codemod that quietly walks past
+something it does not understand is worse than none, because the changes it _did_
+make suggest the job is finished — so anything it recognised and deliberately did
+not touch is listed with a file, a line and a reason:
+
+```text
+1 place(s) need a decision this cannot make for you:
+  app/models/Post.ts:9  export function all<T extends BaseModel>(rows: T[]): T[] {
+    `BaseModel` in a type position. It resolves to the same class as `Model`, so
+    this compiles either way — renaming it is a readability call, not a
+    correctness one.
+```
+
+Run it again after applying: a second run should report no changes. Codemods are
+idempotent, and that is the cheapest way to confirm one did what it said.
 
 `doctor` runs every static sanity check against the booted app and prints each
 finding with its fix: APP_KEY strength, `database.synchronize` colliding with