@aventara/client 0.1.0-pilot.4 → 1.0.0-rc.1

package/README.md

@@ -2,19 +2,19 @@
 
 The development-time generator for Aventara typed remote clients. It fetches a deployed framework's `ClientContract`
 from `<entrypoint>/_contract`, verifies it, and writes a standalone TypeScript client into your project. The generated
-client is the product: it imports nothing from this package, or from `@aventara/core`, at runtime.
+client is what you ship: at runtime it imports nothing from this package or from `@aventara/core`.
 
-Every argument and result type in the generated client is core's own derivation — `@aventara/core`'s published
-declarations, copied into the tree and instantiated over the deployment's ClientContract — so the client agrees with the
-server by construction.
+Every argument and result type in the generated client is core's own derivation: `@aventara/core`'s published
+declarations, copied into the tree and instantiated over the deployment's ClientContract. The client's types therefore
+match the server's.
 
 ## Setting up a frontend: `avclient init`
 
 ```bash
-npx @aventara/client@pilot init      # in your frontend project; pnpm: pnpm dlx @aventara/client@pilot init
+npx @aventara/client@rc init      # in your frontend project; pnpm: pnpm dlx @aventara/client@rc init
 ```
 
-It asks — or takes from flags, or with `--yes` takes every default — four things, and writes the setup:
+It asks four things and writes the setup. Each answer can also come from a flag, and `--yes` takes every default:
 
 | Flag | Question | Default |
 |---|---|---|
@@ -23,12 +23,16 @@ It asks — or takes from flags, or with `--yes` takes every default — four th
 | `--generate-at <dir>` | Where the client goes | `./src/api` |
 | `--package-manager <npm\|pnpm>` | | the lockfile's, else the launching one, else npm |
 
-It writes `framework.client.ts` (or reuses the config the project already has), the variable into `.env` (only with a variable), `"avclient:generate": "avclient
-generate"` into the scripts and `@aventara/client` as an **exact** devDependency at its own version; runs the install
-(`--skip-install` prints it instead); and generates the client right away (`--skip-generate` to skip; a server that does
-not answer leaves the files and names `avclient generate`). Existing content that differs is listed and replaced only
-when you confirm, or with `--yes`; where nobody can be asked, nothing is touched. The generated tree is meant to be
-committed: regenerating it needs a running server.
+It writes `framework.client.ts` (or reuses the config the project already has), the variable into `.env` (only with a
+variable), `"avclient:generate": "avclient generate"` into the scripts, and `@aventara/client` as an exact
+devDependency at its own version. Then it runs the install (`--skip-install` prints it instead) and generates the
+client right away (`--skip-generate` skips that). A server that does not answer leaves the files in place and names
+`avclient generate`; `--verbose` shows the install's output as it runs.
+
+Each step (the install, loading the config, fetching the ClientContract, emitting, checking and writing) is shown on
+stderr while it runs: live on a terminal, and one plain line per step in a pipe, in CI or with `NO_COLOR`. Existing
+content that differs is listed and replaced only when you confirm, or with `--yes`; where nobody can be asked, nothing
+is touched. Commit the generated tree, because regenerating it needs a running server.
 
 ## Generating a client
 
@@ -50,19 +54,26 @@ and run:
 npx avclient generate [--yes]
 ```
 
-**The config file** is loaded the way Prisma 7 loads `prisma.config.ts`: `framework.client.ts` — or `.mts`, `.cts`,
-`.js`, `.mjs`, `.cjs` — in ES module or CommonJS syntax, whatever your `package.json`'s `"type"`. A
-`framework.client.mts` written by 0.1.0-pilot.1 keeps working, and `avclient init` reuses it. Two config files in one
-directory are refused, naming both.
-
-- **`entrypoint`** is the deployment's framework entrypoint: origin plus mount path, one absolute `http(s)` URL. It
-  may not carry credentials — the platform's `fetch` refuses such a URL, and the entrypoint ships inside the client.
-- **`generateAt`** is a directory you may share with your own files. The generator owns exactly two entries in it —
-  `AvClient.ts` and `generated/` — and never reads, moves or removes anything else there.
+The config file is loaded the way Prisma 7 loads `prisma.config.ts`: `framework.client.ts` (or `.mts`, `.cts`, `.js`,
+`.mjs`, `.cjs`), in ES module or CommonJS syntax, whatever your `package.json`'s `"type"`. A `framework.client.mts`
+written by 0.1.0-pilot.1 keeps working, and `avclient init` reuses it. Two config files in one directory are refused,
+naming both.
+
+- `entrypoint` is the deployment's framework entrypoint: origin plus mount path, one absolute `http(s)` URL. It may
+  not carry credentials, because the platform's `fetch` refuses such a URL and the entrypoint ships inside the client.
+- `generateAt` is a directory you may share with your own files. The generator owns exactly two entries in it,
+  `AvClient.ts` and `generated/`, and never reads, moves or removes anything else there.
+- The `.env` cascade is read from the current directory before the config is evaluated, highest precedence first: the
+  process environment, `.env.<mode>.local`, `.env.<mode>`, `.env.local`, `.env`; `mode` is `NODE_ENV`, or
+  `development`. The config reads it through `env("NAME")`; `process.env` is never written.
+- Content the generator did not produce in `AvClient.ts` or `generated/` is listed, and you are asked before it is
+  overwritten or removed. That includes what a killed run left in the `generated/` it moved aside. `--yes` answers yes.
+  Where nobody can answer (stdin is not a terminal, as in CI), the run is refused and nothing is touched. A cancelled
+  or refused run still prints every warning it raised.
 
 ### Your tsconfig decides how the client is written
 
-The client is TypeScript source that **your own toolchain compiles**, like your own files — `tsc`, Next.js (Turbopack or
+The client is TypeScript source that your own toolchain compiles, like your own files: `tsc`, Next.js (Turbopack or
 webpack), Vite, `tsx`, Node's type stripping. Its modules import each other the way your project imports its files,
 read from your `tsconfig.json` (the nearest one above `generateAt`, `extends` included) by Prisma 7's rules:
 
@@ -70,7 +81,7 @@ read from your `tsconfig.json` (the nearest one above `generateAt`, `extends` in
 |---|---|---|
 | `allowImportingTsExtensions` or `rewriteRelativeImportExtensions` (Vite's react-ts template, Node's type stripping) | `./generated/client.ts` | `./api/AvClient.ts` |
 | `moduleResolution: "bundler"` (Next.js) or `module: "commonjs"` | `./generated/client` | `./api/AvClient` |
-| anything else — `module: "nodenext"`/`"node16"` (NestJS 12) | `./generated/client.js` | `./api/AvClient.js` (ES module) or `./api/AvClient` (CommonJS) |
+| anything else, such as `module: "nodenext"`/`"node16"` (NestJS 12) | `./generated/client.js` | `./api/AvClient.js` (ES module) or `./api/AvClient` (CommonJS) |
 
 Under `nodenext`, the nearest `package.json`'s `"type"` decides whether the client is checked as an ES module or as
 CommonJS. Vite's `tsconfig.json`, which only lists `references`, defers to the referenced project that includes the
@@ -78,29 +89,25 @@ client (`tsconfig.app.json`). The validate step type-checks the client in your p
 
 A project with no `tsconfig.json` is refused: the generated client is TypeScript, and JavaScript projects are not
 supported yet.
-- **The `.env` cascade** is read from the current directory before the config is evaluated, highest precedence first:
-  the process environment, `.env.<mode>.local`, `.env.<mode>`, `.env.local`, `.env`; `mode` is `NODE_ENV`, or
-  `development`. The config reads it through `env("NAME")`; `process.env` is never written.
-- **Content the generator did not produce** in `AvClient.ts` or `generated/` is listed and you are asked before it is
-  overwritten or removed — including what a killed run left in the `generated/` it moved aside. `--yes` answers yes.
-  Where nobody can answer — stdin is not a terminal, as in CI — the run is refused and nothing is touched. A cancelled
-  or refused run still prints every warning it raised.
 
 ### What a run guarantees
 
-- **A failed run leaves the previous output exactly as it was.** The whole tree is written to a staging directory inside
-  `generateAt`, validated there as one program, and only then moved into place. A run killed part-way is repaired by the
-  next run that writes, before it writes anything. A first run that fails removes the directories it created.
-- **The validate step is a real type check** when your project has the optional peer `typescript` (5.5 to 6) — it is
-  resolved from your project, so `npx @aventara/client@pilot init` type-checks too — under a consumer's strictest plausible
-  settings and with nothing outside the tree resolvable. Without it — or under
-  TypeScript 7, which has no classic compiler API to check with — the check degrades to a parse with Node's own
-  TypeScript parser, and says so loudly in one warning; it is never skipped, and the client is still written. The peer
-  range has no upper bound, so a frontend on TypeScript 7 installs it; your own `tsc` checks the tree when it compiles.
-- **Determinism.** Two runs over one ClientContract write the same bytes; deleting the client and regenerating it gives
-  the same bytes. Nothing volatile — no timestamp, generator version, host or path — is emitted.
-- **Failure is a sentence.** A refusal is one line and exit code 1, with no stack; anything the run warned about before
-  it stopped is printed first. A stack means a defect in the generator.
+A failed run leaves the previous output exactly as it was. The whole tree is written to a staging directory inside
+`generateAt`, validated there as one program, and only then moved into place. A run killed part-way is repaired by the
+next run that writes, before it writes anything. A first run that fails removes the directories it created.
+
+The validate step is a real type check when your project has the optional peer `typescript` (5.5 to 6). It is resolved
+from your project, so `npx @aventara/client@rc init` type-checks too, under a consumer's strictest plausible settings
+and with nothing outside the tree resolvable. Without it, or under TypeScript 7 (which has no classic compiler API to
+check with), the check falls back to a parse with Node's own TypeScript parser and says so in one warning. It is never
+skipped, and the client is still written. The peer range has no upper bound, so a frontend on TypeScript 7 installs
+it; your own `tsc` checks the tree when it compiles.
+
+Two runs over one ClientContract write the same bytes, and deleting the client and regenerating it gives the same
+bytes. Nothing volatile (no timestamp, generator version, host or path) is emitted.
+
+A refusal is one line and exit code 1, with no stack; anything the run warned about before it stopped is printed
+first. A stack means a defect in the generator.
 
 ## Calling the API
 
@@ -113,22 +120,22 @@ const one: User = await avClient.User.find.unique({ where: { id } });
 const maybe = await avClient.User.find.first({ where }); // User | null — a miss is null
 ```
 
-- **`avClient`** is the default export: the client of the deployment the tree was generated from.
-  `new AvClient({ entrypoint, fetch })` makes another — `entrypoint` for a deployment serving **exactly the same**
-  ClientContract (tests, SSR), `fetch` for a custom fetch.
-- **One property per Resource**, one per family under it, one per advertised variant: only what the ClientContract
-  advertises exists, in the type and at runtime. A Resource named like one of the client's own members (`tx`,
-  `transaction`, `then`, `constructor`, `Object.prototype`'s names) is reached as `<name>Model`, with one warning; its
-  wire name is unchanged.
-- **A call resolves to the data**: the record, a list, a count; a first-style miss (`A1001`) is `null`. Every other
-  outcome throws — the `FrameworkError` subclass of its code (`NotFoundError` for a strict-unique miss,
-  `ContractMismatchError` for a stale client, …), or `TransportError` when no framework answer arrived.
-- **Values are application values**: `bigint`, `Date`, `Uint8Array`, the client's `Decimal`, JSON values as they are.
-  Arguments are encoded and results revived for you; a value that cannot be read throws `TransportError`.
-- **Per-call options** (`CallOptions`), never sent in the body: `signal` (an abort rejects with what `fetch` rejected
+- `avClient` is the default export: the client of the deployment the tree was generated from.
+  `new AvClient({ entrypoint, fetch })` makes another. `entrypoint` is for a deployment serving exactly the same
+  ClientContract (tests, SSR), and `fetch` is for a custom fetch.
+- The client has one property per Resource, one per family under it, and one per advertised variant. Only what the
+  ClientContract advertises exists, in the type and at runtime. A Resource named like one of the client's own members
+  (`tx`, `transaction`, `then`, `constructor`, `Object.prototype`'s names) is reached as `<name>Model`, with one
+  warning; its wire name is unchanged.
+- A call resolves to the data: the record, a list, a count. A first-style miss (`A1001`) is `null`. Every other
+  outcome throws the `AvError` subclass of its code (`AvNotFoundError` for a strict-unique miss,
+  `AvContractMismatchError` for a stale client, …), or `AvTransportError` when no framework answer arrived.
+- Values are application values: `bigint`, `Date`, `Uint8Array`, the client's `AvDecimal`, JSON values as they are.
+  Arguments are encoded and results revived for you; a value that cannot be read throws `AvTransportError`.
+- Per-call options (`AvCallOptions`) are never sent in the body: `signal` (an abort rejects with what `fetch` rejected
   with), `headers` (the framework's own identity headers are refused), and `requestId`, sent as `Aventara-Request-Id`
   and winning over that header in `headers`.
-- **Named types** (`User`, `UserWhere`, `UserUniqueWhere`, `UserOrderBy`, `UserCreateData`, `UserUpdateData`,
+- The named types (`User`, `UserWhere`, `UserUniqueWhere`, `UserOrderBy`, `UserCreateData`, `UserUpdateData`,
   `UserSelect`, `UserInclude`) are named exports, each only when the operation it reads is advertised. A name that would
   clash walks the rename ladder (`User` beside a Resource `UserWhere` becomes `UserModel`), one warning each.
 
@@ -143,17 +150,37 @@ const profile = avClient.tx.Profile.create.one({ data: { bio: "…", userId: cre
 const [user, row] = await avClient.transaction([created, profile]);
 ```
 
+A `$ref` stands for one field of an earlier step's result. It may be written in a step's data at any depth (a field's
+value, the key a relation's `$connect`, `$disconnect`, `$set`, `$connectOrCreate` or `$upsert` names, the `where` of a
+nested `$update` or `$delete`, and the data `$create`, `$update` and `$upsert` nest), in its `cursor`, and anywhere in
+its `where`, `AND`/`OR`/`NOT` and relation filters included. A projection's nested `where` and `orderBy` take none:
+
+```ts
+const post = avClient.tx.Post.create.one({ data: { title: "Hi", author: { $connect: { id: created.$ref("id") } } } });
+const mine = avClient.tx.Post.find.many({ where: { OR: [{ authorId: created.$ref("id") }, { title: { startsWith: created.$ref("email") } }] } });
+```
+
+Its source field must have the same type as where it is written:
+
+- for a filter's value, `equals` and `not`, a nullable source only where the field is nullable, and a `null` then
+  matches the rows where the field is unset, as a literal `null` does;
+- for a unique key, a `cursor`, a comparison or a text operator, a non-null source;
+- for `in`, `notIn`, `hasEvery` and `hasSome`, a list field;
+- for `has`, one value.
+
+A mismatch is a type error, and the server refuses it before anything runs (`A2007`/`V1011`).
+
 `avClient.tx.…` builds a handle and sends nothing. `avClient.transaction([...])` sends the plan once and resolves one
 result per handle, typed, in order; a failing step throws its error with `cause.operation` naming the step. `$ref` binds
 to the handle's position in the list it runs with. Two mistakes are refused before anything is sent, as core refuses
-them in process: one handle twice (`ValidationError`, `A2004`/`V1001`), and a `$ref` to a handle not in the list
-(`ValidationError`, `A2007`/`V1010`). A handle is plain data: any client of the same generated tree may run it.
+them in process: one handle twice (`AvValidationError`, `A2004`/`V1001`), and a `$ref` to a handle not in the list
+(`AvValidationError`, `A2007`/`V1010`). A handle is plain data: any client of the same generated tree may run it.
 
 ## Custom fetch and authentication
 
-`fetch` is typed as **your platform's own `fetch`** when your `lib` declares one (DOM, `@types/node`), so the platform
-`fetch` is accepted without a cast; with neither, a structural fetch type stands in. The client never adds headers of its
-own beyond the protocol's; authentication is a custom fetch:
+`fetch` is typed as your platform's own `fetch` when your `lib` declares one (DOM, `@types/node`), so the platform
+`fetch` is accepted without a cast; with neither, a structural fetch type stands in. The client adds no headers of its
+own beyond the protocol's, so authentication goes in a custom fetch:
 
 ```ts
 const client = new AvClient({
@@ -161,107 +188,116 @@ const client = new AvClient({
 });
 ```
 
-The platform `fetch` is read when a call is made, not when the client is imported, so importing the client never fails
-where there is none — a call does, saying why. An entrypoint carrying credentials is refused when the config is
+The platform `fetch` is read when a call is made, not when the client is imported. Importing the client never fails
+where there is no `fetch`; a call does, saying why. An entrypoint carrying credentials is refused when the config is
 resolved.
 
 ## Up to date
 
-A rerun asks the deployment conditionally (`If-None-Match`, the ClientContract hash of the output it
-finds — only when that output is intact and its carrier re-verifies). On `304 Not Modified` it re-emits from that
-stored ClientContract with **this** generator and **this** entrypoint: identical bytes print
+A rerun asks the deployment conditionally (`If-None-Match`, the ClientContract hash of the output it finds), but only
+when that output is intact and its carrier re-verifies. On `304 Not Modified` it re-emits from that stored
+ClientContract with this generator and this entrypoint. Identical bytes print
 `avclient: up to date: … nothing was written.` and exit 0; otherwise the output is replaced, and the line says
 `the ClientContract is unchanged; the generator or the entrypoint changed`.
 
 ## What is emitted
 
 Every file opens with a banner stating that it is generated and must not be edited, and with the Biome suppressions a
-generated file needs — emitted, not configured, so the output stays correct in a repository whose formatter nobody here
-chose. The `.d.ts` files are core's copied declarations under `generated/derivation/` and the named types in
-`generated/types.d.ts`; the `.ts` sources carry their own types.
-
-- `AvClient.ts` — the entry point you import: `avClient` (the default export), `AvClient`, `AvClientOptions`,
-  `CallOptions`, `Fetch`, `Operation`, the named Resource types, the enums, `Decimal`, `FrameworkError` and its
-  subclasses, `TransportError`, and the types `Cause`, `ValidationIssue`, `OperationCode` and `ValidationCode`.
-- `generated/client.ts` — the typed client: the class `AvClient`, `AvClientOptions`, `CallOptions` and the ready
-  instance `avClient`; every argument and result type an instantiation of core's own derivation.
-- `generated/contract.ts` — the ClientContract the client was generated against: its served canonical bytes, verbatim,
+generated file needs. They are emitted rather than configured, so the output stays correct whatever formatter the
+repository uses. The `.d.ts` files are core's copied declarations under `generated/derivation/`
+and the named types in `generated/types.d.ts`; the `.ts` sources carry their own types.
+
+- `AvClient.ts`: the entry point you import: `avClient` (the default export), `AvClient`, `AvClientOptions`,
+  `AvCallOptions`, `AvFetch`, `AvOperation`, the named Resource types, the enums, `AvDecimal`, `AvError` and its
+  subclasses, `AvTransportError`, and the types `AvCause`, `AvValidationIssue`, `AvOperationCode` and `AvValidationCode`.
+- `generated/client.ts`: the typed client: the class `AvClient`, `AvClientOptions`, `AvCallOptions` and the ready
+  instance `avClient`. Every argument and result type is an instantiation of core's own derivation.
+- `generated/contract.ts`: the ClientContract the client was generated against, its served canonical bytes verbatim,
   as the type `ClientContractShape` (no runtime byte).
-- `generated/derivation/` — `@aventara/core`'s published declarations of the argument/result derivation and the
-  call grammar, copied byte for byte (bannered, source-map trailer dropped): the generated types are core's own.
-- `generated/enums.ts` — each enum as a union type and a same-named `as const` object.
-- `generated/metadata.ts` — the ClientContract hash and protocol version the client is bound to, and the entrypoint it
-  was generated from, its default deployment (an entrypoint carrying credentials is refused at resolution).
-- `generated/runtime/codec.ts` — the nine scalars' wire codecs, and the request-body serializer.
-- `generated/runtime/decimal.ts` — the framework's `Decimal`: a constructor, `toString` and `toJSON`.
-- `generated/runtime/descriptor.ts` — what the runtime reads of the contract: the result fields it revives and the
+- `generated/derivation/`: `@aventara/core`'s published declarations of the argument/result derivation and the call
+  grammar, copied byte for byte (bannered, source-map trailer dropped), so the generated types are core's own.
+- `generated/enums.ts`: each enum as a union type and a same-named `as const` object.
+- `generated/metadata.ts`: the ClientContract hash and protocol version the client is bound to, and the entrypoint it
+  was generated from, which is its default deployment (an entrypoint carrying credentials is refused at resolution).
+- `generated/runtime/codec.ts`: the nine scalars' wire codecs, and the request-body serializer.
+- `generated/runtime/decimal.ts`: the framework's `AvDecimal`, with a constructor, `toString` and `toJSON`.
+- `generated/runtime/descriptor.ts`: what the runtime reads of the contract: the result fields it revives and the
   relations it follows (the decode table), and the advertised operations.
-- `generated/runtime/errors.ts` — `FrameworkError`, its subclasses by code class (`AuthError`, `ConflictError`,
-  `ContractMismatchError`, `InternalError`, `NotFoundError`, `ProtocolError`, `ValidationError`), `TransportError`, and
-  the code unions, emitted from core's code arrays rather than retyped.
-- `generated/runtime/fingerprint.ts` — the operation fingerprint (RFC 8785 canonical JSON, SHA-256,
-  base64url), dependency-free and pinned to core's; emitted only when transactions are `interactive`.
-- `generated/runtime/transaction.ts` — `avClient.tx`'s deferred handles and `avClient.transaction`'s plan assembly,
-  refusals and one POST to `/_transactions`; emitted only when transactions are `interactive`.
-- `generated/runtime/transport.ts` — one POST per operation with the identity headers, and the response read by the
-  protocol's rule; arguments encoded by value, results revived by the decode table, the platform's own `fetch` type accepted.
-  Its `execute` primitive is module-private: no public file re-exports it; `AvClient`'s methods wrap it.
-- `generated/types.d.ts` — the named Resource types, as a declaration file (`User`, `UserWhere`,
-  `UserUniqueWhere`, `UserOrderBy`, `UserCreateData`, `UserUpdateData`, `UserSelect`, `UserInclude`), each only when
-  its operation is advertised.
-
-The tree is self-contained: every import in it names a file in it, so it compiles with nothing else installed. Names a TypeScript
-declaration cannot carry as-is (a reserved word, a name the runtime owns, an enum sharing a Resource's name) are
-renamed, with one warning each; the wire name is kept.
+- `generated/runtime/errors.ts`: `AvError`, its subclasses by code class (`AvAuthError`, `AvConflictError`,
+  `AvContractMismatchError`, `AvInternalError`, `AvNotFoundError`, `AvProtocolError`, `AvValidationError`),
+  `AvTransportError`, and the code unions, emitted from core's code arrays instead of retyped.
+- `generated/runtime/field-check.evaluator.ts`: core's own field-check evaluator, copied byte for byte with its
+  imports pointed at `generated/derivation/`. Emitted only when the ClientContract carries a check (a field's
+  `validators`, or a check on a Json Shape node).
+- `generated/runtime/field-validators.ts`: the ClientContract's checks as data, and the walk that runs them on an
+  operation's arguments before anything is sent. A failure throws the server's `A2004` with the same issues. A check
+  the client cannot judge exactly as the server would is left to the server. Emitted only when the ClientContract
+  carries a check.
+- `generated/runtime/fingerprint.ts`: the operation fingerprint (RFC 8785 canonical JSON, SHA-256, base64url),
+  dependency-free and pinned to core's. Emitted only when transactions are `interactive`.
+- `generated/runtime/transaction.ts`: `avClient.tx`'s deferred handles and `avClient.transaction`'s plan assembly,
+  refusals and one POST to `/_transactions`. Emitted only when transactions are `interactive`.
+- `generated/runtime/transport.ts`: one POST per operation with the identity headers, and the response read by the
+  protocol's rule. Arguments are encoded by value, results revived by the decode table, and the platform's own `fetch`
+  type is accepted. Its `execute` primitive is module-private: no public file re-exports it, and `AvClient`'s methods
+  wrap it.
+- `generated/types.d.ts`: the named Resource types, as a declaration file (`User`, `UserWhere`, `UserUniqueWhere`,
+  `UserOrderBy`, `UserCreateData`, `UserUpdateData`, `UserSelect`, `UserInclude`), each only when its operation is
+  advertised.
+
+The tree is self-contained: every import in it names a file in it, so it compiles with nothing else installed. Names a
+TypeScript declaration cannot carry as-is (a reserved word, a name the runtime owns, an enum sharing a Resource's name)
+are renamed, with one warning each; the wire name is kept.
 
 ## What a generated client is bound to
 
-A generated client is bound to the **exact ClientContract hash and protocol version** it was generated from. Both are
-in `generated/metadata.ts` and both are sent on every request (`Aventara-Protocol-Version`, `Aventara-Contract-Hash`).
-A deployment whose ClientContract differs refuses the request with `A2005`, which the client throws as
-`ContractMismatchError`.
+A generated client is bound to the exact ClientContract hash and protocol version it was generated from. Both are in
+`generated/metadata.ts`, and both are sent on every request (`Aventara-Protocol-Version`, `Aventara-Contract-Hash`). A
+deployment whose ClientContract differs refuses the request with `A2005`, which the client throws as
+`AvContractMismatchError`.
 
-The hash covers everything the deployment advertises, not only its schema: two deployments of one schema can advertise
+The hash covers everything the deployment advertises, not only its schema. Two deployments of one schema can advertise
 different ClientContracts, and a client generated against one is refused by the other. Whatever the cause, the remedy
-is the same — **generate against the deployment the client will call, and regenerate when it changes.**
+is the same: generate against the deployment the client will call, and regenerate when it changes.
 
-That holds for an operation the deployment **no longer advertises**, too: the server checks the client's
-identity before it routes, so a stale client calling a removed operation also hears `A2005` and throws
-`ContractMismatchError`. A response that is not a framework envelope at all — a host's own 404 for a path it does not
-mount — is a `TransportError`, which names no remedy: nothing in it says the client is stale.
+The same holds for an operation the deployment no longer advertises. The server checks the client's identity before it
+routes, so a stale client calling a removed operation also hears `A2005` and throws `AvContractMismatchError`. A
+response that is not a framework envelope at all, such as a host's own 404 for a path it does not mount, is an
+`AvTransportError`. It names no remedy, because nothing in it says the client is stale.
 
-The embedded entrypoint is a **default**: `new AvClient({ entrypoint })` may point a client at another deployment, and
-doing so re-binds nothing — the ClientContract hash still decides whether that deployment accepts the client.
+The embedded entrypoint is a default. `new AvClient({ entrypoint })` may point a client at another deployment without
+re-binding anything: the ClientContract hash still decides whether that deployment accepts the client.
 
 ## Type-checking cost in a consumer
 
-A consumer pays for the calls it type-checks, not for the schema, under `skipLibCheck: true` (the common default):
-the named types (`generated/types.d.ts`) and core's derivation are declaration files checked only where read. Under
+Under `skipLibCheck: true` (the common default), a consumer pays for the calls it type-checks, not for the schema: the
+named types (`generated/types.d.ts`) and core's derivation are declaration files checked only where read. Under
 `skipLibCheck: false` every named type is resolved where it is declared, so the cost grows with the number of
 Resources.
 
 ## Before 1.0
 
-- **The `Aventara` wire prefix** of the protocol's headers (`Aventara-Protocol-Version`, `Aventara-Contract-Hash`,
-  `Aventara-Request-Id`) may still change before the first stable release. It is one constant in the generated
-  `generated/runtime/transport.ts`; regenerating picks up a change.
+The `Aventara` wire prefix of the protocol's headers (`Aventara-Protocol-Version`, `Aventara-Contract-Hash`,
+`Aventara-Request-Id`) may still change before the first stable release. It is one constant in the generated
+`generated/runtime/transport.ts`, and regenerating picks up a change.
 
 ## Known issues
 
-- **The generator read the wrong `tsconfig.json`.** In a monorepo or a non-standard layout, the nearest
-  `tsconfig.json` above `generateAt` may not be the one your project compiles the client with, and the client's
-  imports or module format then do not match your compiler (`Cannot find module './generated/client.js'`, an
-  extension your bundler will not resolve). Name the right one in `framework.client.ts`, relative to the config file:
+The generator can read the wrong `tsconfig.json`. In a monorepo or a non-standard layout, the nearest `tsconfig.json`
+above `generateAt` may not be the one your project compiles the client with. The client's imports or module format then
+do not match your compiler (`Cannot find module './generated/client.js'`, or an extension your bundler will not
+resolve). Name the right one in `framework.client.ts`, relative to the config file:
 
-  ```ts
-  export default defineClientConfig({
-  	entrypoint: env("AVENTARA_API_URL"),
-  	generateAt: "./src/api",
-  	tsconfigFile: "./tsconfig.app.json",
-  });
-  ```
+```ts
+export default defineClientConfig({
+	entrypoint: env("AVENTARA_API_URL"),
+	generateAt: "./src/api",
+	tsconfigFile: "./tsconfig.app.json",
+});
+```
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/cli/command.parser.d.ts

@@ -1,6 +1,6 @@
 export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .js, .mjs, .cjs, .mts,\n                              .cts) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
 export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.ts (or .js, .mjs, .cjs, .mts, .cts) in the current directory,\nfetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its\ngenerateAt directory, its imports spelled as the project's tsconfig.json says.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
-export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.ts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.ts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
+export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.ts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.ts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  --verbose                      Show the install's output as it runs.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
 export type ClientInitCommand = {
     readonly command: "init";
     readonly given: Readonly<Partial<Record<"entrypoint" | "envVar" | "generateAt" | "packageManager", string>>>;
@@ -8,6 +8,8 @@ export type ClientInitCommand = {
     readonly skipInstall: boolean;
     readonly skipGenerate: boolean;
     readonly yes: boolean;
+    /** Streams the install's output. */
+    readonly verbose?: boolean;
 };
 /** What the command line asked for. */
 export type CliCommand = {
@@ -20,11 +22,11 @@ export type CliCommand = {
     readonly yes: boolean;
 } | ClientInitCommand;
 /** The command line cannot be understood. A refusal: one sentence, exit 1. */
-export declare class CliCommandError extends Error {
-    readonly name = "CliCommandError";
+export declare class AvCliCommandError extends Error {
+    readonly name = "AvCliCommandError";
 }
 /**
- * @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `init …`,
+ * @throws AvCliCommandError when `argv` is not `generate [--yes|-y]`, `init …`,
  *   `--help`/`-h` or `--version`/`-v`.
  */
 export declare function parseCliCommand(argv: readonly string[]): CliCommand;

package/dist/cli/command.parser.js

@@ -69,19 +69,20 @@ Options:
   --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]
   --skip-install                 Print the install instead of running it.
   --skip-generate                Do not generate now.
+  --verbose                      Show the install's output as it runs.
   -y, --yes                      Accept every default, and replace differing content.
 
 On a terminal every unanswered question is asked; anywhere else, pass its flag
 or --yes, or the run stops before writing anything.
 `;
-export class CliCommandError extends Error {
-    name = "CliCommandError";
+export class AvCliCommandError extends Error {
+    name = "AvCliCommandError";
 }
 export function parseCliCommand(argv) {
     const [command, ...rest] = argv;
     const help = "run `avclient --help` for usage.";
     if (command === undefined) {
-        throw new CliCommandError(`a command is required; ${help}`);
+        throw new AvCliCommandError(`a command is required; ${help}`);
     }
     if (command === "--help" || command === "-h") {
         return { command: "help" };
@@ -97,7 +98,7 @@ export function parseCliCommand(argv) {
         return parseInit(rest, help);
     }
     if (command !== "generate") {
-        throw new CliCommandError(`unknown command ${JSON.stringify(command)}; ${help}`);
+        throw new AvCliCommandError(`unknown command ${JSON.stringify(command)}; ${help}`);
     }
     let yes = false;
     for (const argument of rest) {
@@ -105,7 +106,7 @@ export function parseCliCommand(argv) {
             yes = true;
             continue;
         }
-        throw new CliCommandError(`unexpected argument ${JSON.stringify(argument)}: generate takes only --yes, ` +
+        throw new AvCliCommandError(`unexpected argument ${JSON.stringify(argument)}: generate takes only --yes, ` +
             `everything else it needs is in ${CLIENT_CONFIG_FILE}; ${help}`);
     }
     return { command: "generate", yes };
@@ -132,24 +133,29 @@ function parseInit(argv, help) {
         yes: false,
     };
     const seen = new Set();
+    let verbose = false;
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
+        if (argument === "--verbose" && !verbose) {
+            verbose = true;
+            continue;
+        }
         const equals = argument.indexOf("=");
         const flag = equals === -1 ? argument : argument.slice(0, equals);
         const inline = equals === -1 ? undefined : argument.slice(equals + 1);
         const value = INIT_VALUES[flag];
         const toggle = INIT_SWITCHES[flag];
         if (value === undefined && toggle === undefined) {
-            throw new CliCommandError(`unexpected argument ${JSON.stringify(argument)} for init; ${help}`);
+            throw new AvCliCommandError(`unexpected argument ${JSON.stringify(argument)} for init; ${help}`);
         }
         const canonical = toggle === "yes" ? "--yes" : flag;
         if (seen.has(canonical)) {
-            throw new CliCommandError(`${canonical} was given twice; ${help}`);
+            throw new AvCliCommandError(`${canonical} was given twice; ${help}`);
         }
         seen.add(canonical);
         if (toggle !== undefined) {
             if (inline !== undefined) {
-                throw new CliCommandError(`${canonical} takes no value; ${help}`);
+                throw new AvCliCommandError(`${canonical} takes no value; ${help}`);
             }
             switches[toggle] = true;
             continue;
@@ -157,7 +163,7 @@ function parseInit(argv, help) {
         const taken = inline ?? argv[index + 1];
         if (taken === undefined ||
             (inline === undefined && taken.startsWith("-"))) {
-            throw new CliCommandError(`${canonical} takes a value; ${help}`);
+            throw new AvCliCommandError(`${canonical} takes a value; ${help}`);
         }
         if (inline === undefined) {
             index += 1;
@@ -165,7 +171,12 @@ function parseInit(argv, help) {
         given[value] = taken;
     }
     if (switches.noEnvVar && given.envVar !== undefined) {
-        throw new CliCommandError(`--env-var and --no-env-var contradict each other; ${help}`);
+        throw new AvCliCommandError(`--env-var and --no-env-var contradict each other; ${help}`);
     }
-    return { command: "init", given, ...switches };
+    return {
+        command: "init",
+        given,
+        ...switches,
+        ...(verbose ? { verbose: true } : {}),
+    };
 }

package/dist/cli/generate.command.d.ts

@@ -1,5 +1,6 @@
 import type { ProcessEnvInput } from "../config/env.cascade.js";
 import type { CommandRunner } from "../init/command.runner.js";
+import { type ProgressMode, type StepReporter } from "./step.reporter.js";
 /** What `runCli` reads and writes instead of the process globals. */
 export interface CliIo {
     readonly cwd: string;
@@ -14,11 +15,15 @@ export interface CliIo {
     readonly ask?: (prompt: string) => Promise<string>;
     /** Runs a command with stdout piped (`init`'s install); a child process by default. */
     readonly run?: CommandRunner;
+    /** How the steps are shown on stderr; none when omitted. */
+    readonly progress?: ProgressMode;
 }
+/** How many steps a generation shows: the config, the contract, the emission, the write. */
+export declare const GENERATION_STEPS = 4;
 /**
  * `avclient generate` — the generation, the generateAt rule's question, and the
  * report. Shared by `init`, which generates once the project is set up.
  *
  * @throws whatever the generation raises; the caller renders it.
  */
-export declare function runGenerate(io: CliIo, yes: boolean): Promise<number>;
+export declare function runGenerate(io: CliIo, yes: boolean, reporter?: StepReporter): Promise<number>;