@aventara/client 0.1.0-pilot.3 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,222 @@
+# @aventara/client
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- First release candidate of Aventara 1.0. The public API is now considered stable; changes before 1.0.0 are possible
+  based on feedback.
+
+### Minor Changes
+
+- 24ffbab: A `Json` field can now have a type. Build its shape with `AvZ` from the new entry `@aventara/core/json` and declare it
+  on the field: `fields: { Post: { meta: { json: AvZ.object({ title: AvZ.string() }) } } }`. `framework.application`,
+  `framework.client`, `appTx`/`clientTx` and the generated client then read and write the field as that type instead of
+  generic JSON, and every write to it — create, update, upsert, nested writes and transaction steps, a value taken from
+  an earlier step included — is checked before the database is asked: a value out of shape is refused with `A2004` and
+  one issue per problem at its exact path (`V1000` missing key, `V1001` wrong type, `V1002` outside an enum or literal,
+  `V1004` integer out of range, `V1005` unknown key). Shapes are types only and their objects are closed; reads and
+  filters are never checked. Only a field the adapter discovered as `Json` takes a shape, and a Zod schema is not
+  accepted. The shape is part of the ClientContract (as JSON Schema), so declaring or changing one changes its hash:
+  regenerate the client. `@aventara/core` now depends on `zod` (`^4.6.5`), which only `@aventara/core/json` loads. The
+  shape types `AvZShape`, `AvZObject`, `AvZOptional` and `AvZNullable` are exported too, so a project that emits
+  declarations can export a shape or a configuration holding one.
+- 24ffbab: Transaction steps can now reference earlier results in `$connect`, `$disconnect`, `$set`, `$connectOrCreate`'s `where`,
+  a `cursor`, a unique `where`, anywhere in a filter, and at any depth of nested relation writes. The generated client binds a `$ref` wherever a step's arguments
+  hold one, and its types accept one exactly where the server does: of the field's own type, nullable only for a filter's
+  equality on a nullable field, a list field for `in`, `notIn`, `hasEvery` and `hasSome`. Regenerate the client to use them.
+- 24ffbab: `aventara new`, `aventara init`, `avclient init` and `avclient generate` show their steps while they work, so a long
+  install never looks hung: on a terminal, `[3/4] Installing dependencies (npm install)` with a spinner and the seconds so
+  far, then `✓` or `✗` and its time; in a pipe, in CI or with `NO_COLOR`, one plain line per step (`… done (12.4s)`),
+  with no control sequence. A closing line gives the total time. The steps go to stderr; stdout keeps the results and the
+  next steps. The output of `nest new` and of the install is shown only when it fails, as before, or as it runs with the
+  new `--verbose`.
+- 24ffbab: A nested `$update` or `$delete` through a to-many relation filters plain fields only on Prisma 7, and Aventara now says
+  so up front: a relation filter in its `where` — `{ posts: { $update: { where: { category: { name: "x" } }, … } } }`, at
+  any depth, under `AND`/`OR`/`NOT` too — is refused with `A2004` / `V1006` before the database is asked, and is a type
+  error in `framework.application`, `framework.client`, `appTx`/`clientTx` and the generated client. Before, it reached
+  Prisma and fail as `A3001`. A to-one relation's nested filter keeps relation filters. The limit is stated by the adapter
+  in the Contract (`nestedWriteFilter: "scalar"`), so the ClientContract hash changes: regenerate the client.
+
+### Patch Changes
+
+- 24ffbab: Each package ships its `CHANGELOG.md`, so the release notes are in the installed package beside the README.
+- 24ffbab: **Behaviour changes:** server-side calls now copy what you pass them. `framework.application`, `framework.client`,
+  `framework.execute`, `framework.executeTransaction` and the `appTx`/`clientTx` builders read your arguments once, when
+  you call them, into plain data the framework owns; validation, guards, pipes, computed values and the adapter see only
+  that copy, so changing or revoking your object afterwards (an Immer draft after `produce`) no longer affects the
+  operation. A live Proxy (Vue `reactive`, MobX) still works.
+
+  A value that cannot be read — a revoked Proxy, a getter that throws — or that is not plain data — a class instance or a
+  `Map`; `Date`, `Decimal` and `Uint8Array` are fine — is now refused as your request's error: `A2004` with one `V1001` at
+  the value's path (`["arguments", …]`, or `["operations", i, "args", …]` with `cause.operation` in a transaction), before
+  any guard, pipe or adapter runs. Before, it was `A3000` (an internal error) or, from `appTx`/`clientTx`, a `TypeError`
+  thrown at the builder call; a builder now never throws, and `framework.transaction([...])` answers the refusal. The same
+  holds for a `framework.execute` / `executeTransaction` request object that cannot be read. Two answers change for
+  inputs that were never supported: a class instance where an object of arguments belongs (`where`, `data`, …) was
+  accepted or failed as `A3000`, and is now refused; inherited, non-enumerable and symbol keys are dropped, as JSON drops
+  them.
+
+  New optional root setting `misuse` (types `FrameworkMisuseSink`, `FrameworkMisuseEvent`), beside `diagnostics`: it
+  receives one event per refused value — its `kind` (`"unreadable-value"` or `"non-plain-value"`), the `path` the caller
+  received, and the operation's `origin`, `resource`, `family`, `variant` and transaction step (`operation`) when they
+  could be read — never the value itself. It cannot change a response; an error it throws or a promise it rejects is
+  ignored. `diagnostics` keeps receiving only unexpected failures.
+
+  HTTP requests are not copied again: a body the protocol parses from raw content is already plain data.
+
+  The generated client reads your arguments through one guard too: a value that cannot be read is refused with a
+  `TypeError` naming where (`… the value at /where/id could not be read.`) before anything is sent, and a `tx` builder
+  never throws — `transaction([...])` rejects with that error instead. Regenerate the client to pick this up.
+
+- 032f792: The generated client's `transaction([...])` refuses an entry that is not one of its `tx` handles, or one handle
+  placed twice, with the path core answers for it: `["operations", i]`, the entry itself (was `["operation"]`).
+  Regenerate the client to pick this up.
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [24ffbab]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies
+- Updated dependencies [a973e89]
+- Updated dependencies [a973e89]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [1e65e9a]
+- Updated dependencies [24ffbab]
+- Updated dependencies [2d00ad7]
+- Updated dependencies [384a50c]
+- Updated dependencies [d43d1cc]
+- Updated dependencies [3f98749]
+- Updated dependencies [032f792]
+- Updated dependencies [dbe6961]
+  - @aventara/core@1.0.0-rc.0
+
+## 0.1.0-pilot.4
+
+### Patch Changes
+
+- f37dcd6: The documentation shipped with the package — the comments an editor shows on hover, and the README — now describes
+  what each export does, how to use it, what it returns and what it throws. Notes about how the package was built and
+  why are no longer part of what is published.
+- Updated dependencies [f37dcd6]
+  - @aventara/core@0.1.0-pilot.4
+
+## 0.1.0-pilot.3
+
+### Patch Changes
+
+- 0c4b352: `avclient init` adds `.env` to the frontend's `.gitignore` whenever it puts the entrypoint variable in `.env`: Vite's
+  `.gitignore` lists only `*.local`, so the `.env` init wrote was committed. The file is only appended to — every line
+  kept, nothing added when `.env` is already listed — and created where the project has none, as `aventara init` does on
+  the server. The generated client itself is still committed.
+- ac1ae3a: `avclient init` refuses a project with no `tsconfig.json` before it writes or installs anything. 0.1.0-pilot.2 wrote
+  `framework.client.ts`, the `.env` entry, the script and the devDependency, ran the install, and only then had the first
+  generation refuse the JavaScript project. The check is the one `avclient generate` makes — the same search from
+  `generateAt` up, the same sentence — and it runs once the questions are answered, before anything is written.
+- c34e65d: `avclient init` and `avclient generate` no longer print Node's `ExperimentalWarning: stripTypeScriptTypes is an
+experimental feature`. With your project's `typescript` the output is type-checked and Node's parser is never called;
+  without it, the degraded check still parses with Node's parser and says so in its own warning, and only that one Node
+  warning is held back while it parses.
+- 5ab40b2: The generated client is type-checked with your project's own `typescript`, resolved from `generateAt`, not with one
+  installed beside `@aventara/client`. Run through `npx @aventara/client init`, the generator lives in npm's cache, where
+  its optional peer is never installed, so 0.1.0-pilot.2 warned "`typescript` could not be resolved … NOT type-checked"
+  and reported `(checked: syntax)` in a project that had TypeScript. It now reports `(checked: types)`. The degraded check
+  runs only when the project has no `typescript`, or one it cannot check with: TypeScript 7 (no classic compiler API), or
+  one older than 5.5, the peer range's floor — each said in its own warning.
+  - @aventara/core@0.1.0-pilot.3
+
+## 0.1.0-pilot.2
+
+### Patch Changes
+
+- 80527cf: The generated client is still TypeScript source — `AvClient.ts` and `generated/` — compiled by your own toolchain, but
+  its internal imports are now written the way your project imports its own files, read from your `tsconfig.json` by
+  Prisma 7's rules: extensionless under `moduleResolution: "bundler"` (Next.js with Turbopack or webpack) or `module: "commonjs"`,
+  `.js` under `nodenext` (NestJS 12), `.ts` with `allowImportingTsExtensions` (Vite's react-ts template, Node's type
+  stripping). So
+  Next.js 16's Turbopack, which could not resolve 0.1.0-pilot.1's client, builds it, and you import it as you import your
+  own files: `./api/AvClient`, `./api/AvClient.js` in a `nodenext` ES module project, `./api/AvClient.ts` where your
+  imports name `.ts` files. A project with no
+  `tsconfig.json` is refused with a sentence saying so: JavaScript projects are not supported yet. The client also
+  type-checks under `"strict": false` (the tsconfig Next.js writes itself), where 0.1.0-pilot.1's transport did not.
+
+  The config is loaded the way Prisma 7 loads `prisma.config.ts` (c12 over jiti): `framework.client.ts` — or `.mts`,
+  `.cts`, `.js`, `.mjs`, `.cjs`, in ES module or CommonJS syntax, in any project. `avclient init` writes
+  `framework.client.ts`; a 0.1.0-pilot.1 `framework.client.mts` keeps working and is reused. Two config files are refused.
+
+- e69e88d: The published packages are written for the people who use them. The JavaScript ships without comments; the type
+  declarations keep their documentation, and it, the error messages, the protocol fixtures' labels and the comments in a
+  generated client no longer carry the project's internal development notes.
+- ab58424: A pipe's output is checked against the server's own rules before it reaches the adapter. The request is validated
+  against the caller's Contract; after each pipe, the arguments are validated against the Core Contract (plus fields the
+  caller's scope adds), so a pipe may still write what the caller cannot — a field the client Contract hides, such as a
+  password hash — but not what the server cannot store. A refusal is the new internal code `A3004 PIPE_OUTPUT_INVALID` (HTTP
+  500). The caller receives only the generic `A server pipeline produced invalid arguments.`, like every internal
+  failure; the pipe (`pipes[i]` and its function name), the operation, the offending field and its V-code go to the
+  diagnostics sink as a `PipeOutputError`, and `@aventara/nest` writes them into its error log line. Nothing reaches the
+  adapter. This holds for operations and transaction steps alike (a plan answers with `cause.operation`). Generated
+  clients map `A3004` to `InternalError`; the protocol fixtures in `@aventara/testing` include an `A3004` row.
+- 0ec37d4: `avclient --version` (and `-v`) prints the generator's version and exits 0, and `aventara` now accepts `-v` beside
+  `--version`, so both bins answer the same two flags.
+- Updated dependencies [c2a3b7c]
+- Updated dependencies [e69e88d]
+- Updated dependencies [ab58424]
+- Updated dependencies [23937f8]
+  - @aventara/core@0.1.0-pilot.2
+
+## 0.1.0-pilot.1
+
+### Patch Changes
+
+- d5bd6eb: A CommonJS frontend works. `npm init -y` writes `"type": "commonjs"`, under which Node read `framework.client.ts` as
+  CommonJS and `avclient generate` stopped with "Cannot use import statement outside a module". `avclient init` now writes
+  `framework.client.mts`, an ES module in every project, and moves an existing `framework.client.ts` to it (asking first if
+  it was edited). `avclient generate` reads `framework.client.mts`, still reads `framework.client.ts`, refuses in one
+  sentence when both are present, and tells a `.ts` that fails to evaluate to rename itself.
+- 4a12683: TypeScript 7 no longer blocks a frontend. The optional `typescript` peer is `>=5.5.0` with no upper bound, so `npm i`
+  in a project on `typescript` 7.x no longer fails with `ERESOLVE`. Under a `typescript` without the classic compiler API
+  (`createProgram`), `avclient generate` no longer refuses: it degrades to the syntax check with one warning naming the
+  version, and writes the client — which then type-checks under the project's own `tsc` 7.
+- 799346e: The package READMEs (each package's npm page) are rewritten for the people who use the packages. The Prisma 7
+  adapter's README now states the actual behaviour of a to-many relation or `$count` projected on
+  `update.many`/`create.many`: a validation refusal, `A2004` with `V1008`, before any statement runs (it said `A3001`).
+  Every install or run command names the `@pilot` dist-tag.
+- 88408be: `--help` (and `-h`) works after a command: `aventara new --help`, `aventara init --help`, `avclient init --help` and
+  `avclient generate --help` print that command's usage and exit 0, instead of refusing "unknown flag --help". Nothing
+  else on the line is read or run.
+- Updated dependencies [a45f8a8]
+- Updated dependencies [799346e]
+  - @aventara/core@0.1.0-pilot.1
+
+## 0.1.0-pilot.0
+
+### Minor Changes
+
+- First pilot release of `@aventara/client`, the development-time client generator, bin `avclient`.
+
+  - `avclient init` sets up a frontend — `framework.client.ts`, the `.env` entry, the `avclient:generate` script and an
+    exact `@aventara/client` devDependency — then installs and generates.
+  - `avclient generate` reads the server's ClientContract and writes a standalone typed client that your application
+    imports; the generated code needs no `@aventara/client` at runtime. A client generated for an older contract fails
+    with a message telling you to run `avclient generate`. Messages are prefixed `avclient:`.
+  - The client's entrypoint follows the server's rule: `"api"`, `"/api/"` and `"//api//"` all mean `"/api"`, and a mount
+    path holding a backslash, a `.` segment, a non-ASCII character, a `%` or another character not allowed in a URL path
+    segment is refused rather than silently rewritten.
+  - `bigint`, `decimal`, `datetime` and `bytes` travel in the server's wire forms, and only canonical base64 is accepted
+    for `bytes`.
+  - At this release the `typescript` peer is `>=5.5.0 <7`, and TypeScript 7 is refused in one sentence (0.1.0-pilot.1
+    lifts this).
+
+### Patch Changes
+
+- Updated dependencies
+  - @aventara/core@0.1.0-pilot.0

package/README.md

@@ -6,12 +6,12 @@ client is the product: it imports nothing from this package, or from `@aventara/
 
 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, and that agreement is gated over both pilot schemas.
+server by construction.
 
 ## 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:
@@ -26,7 +26,9 @@ It asks — or takes from flags, or with `--yes` takes every default — four th
 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
+not answer leaves the files 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, 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. The generated tree is meant to be
 committed: regenerating it needs a running server.
 
@@ -92,7 +94,7 @@ supported yet.
   `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
+  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 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
@@ -143,6 +145,22 @@ 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, and 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), 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
@@ -210,11 +228,9 @@ chose. The `.d.ts` files are core's copied declarations under `generated/derivat
   `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. That is gated twice in this package's tests — once
-lexically, once by compiling the tree alone where nothing outside it can resolve — and each gate catches a planted
-import of `@aventara/core` or `@aventara/client` on its own. 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.
+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
 
@@ -237,11 +253,10 @@ doing so re-binds nothing — the ClientContract hash still decides whether that
 
 ## 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),
-where the named types (`generated/types.d.ts`) and core's derivation are declaration files checked only where read:
-about 33,000 instantiations for a 50-Resource schema and seven typed calls. Under `skipLibCheck: false` every named type
-is resolved where it is declared, about 2,900 instantiations per Resource: about 204,000 for the same
-program, the 500,000 line near 150 Resources.
+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
+`skipLibCheck: false` every named type is resolved where it is declared, so the cost grows with the number of
+Resources.
 
 ## Before 1.0
 

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

@@ -1,16 +1,6 @@
-/**
- * The `avclient` command line: one command, its one flag, and help. Everything the
- * generator needs is in `framework.client.ts` and the `.env` cascade, so
- * `generate` takes no flag that would duplicate a config member — a second source
- * of the same fact. `--yes` is not one: it answers the one question the generator
- * asks.
- */
 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";
-/** `avclient generate --help` (pilot.1): that command's usage alone. */
 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";
-/** `avclient init --help` (pilot.1): that command's usage alone. */
-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";
-/** `avclient init`'s command line. */
+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>>>;
@@ -18,11 +8,11 @@ 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 = 
-/** `--help`; with `topic`, `avclient <topic> --help` (pilot.1). */
-{
+export type CliCommand = {
     readonly command: "help";
     readonly topic?: "generate" | "init";
 } | {

package/dist/cli/command.parser.js

@@ -69,6 +69,7 @@ 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
@@ -132,8 +133,13 @@ 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);
@@ -167,5 +173,10 @@ function parseInit(argv, help) {
     if (switches.noEnvVar && given.envVar !== undefined) {
         throw new CliCommandError(`--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>;

package/dist/cli/generate.command.js

@@ -1,14 +1,24 @@
 import { generateClient } from "../generate.js";
 import { FOREIGN_CONTENT_QUESTION, renderForeignContentCancellation, renderForeignContentWarning, renderGenerationSuccess, renderUpToDate, } from "./generation-success.renderer.js";
-export async function runGenerate(io, yes) {
+import { createStepReporter, } from "./step.reporter.js";
+export const GENERATION_STEPS = 4;
+export async function runGenerate(io, yes, reporter) {
+    const progress = reporter ??
+        createStepReporter({
+            write: io.stderr,
+            mode: io.progress ?? "off",
+            total: GENERATION_STEPS,
+        });
     const outcome = await generateClient({
         directory: io.cwd,
         processEnv: io.env,
         overrideForeign: yes,
+        step: progress.step,
     });
     if (outcome.kind === "up-to-date") {
         const report = renderUpToDate(outcome);
         io.stderr(report.stderr);
+        progress.finish("avclient", "done");
         io.stdout(report.stdout);
         return 0;
     }
@@ -30,6 +40,7 @@ export async function runGenerate(io, yes) {
     }
     const report = renderGenerationSuccess(result);
     io.stderr(report.stderr);
+    progress.finish("avclient", "done");
     io.stdout(report.stdout);
     return 0;
 }

package/dist/cli/generation-success.renderer.d.ts

@@ -13,10 +13,6 @@ export interface GenerationSuccessReport {
     readonly stderr: string;
 }
 export declare function renderGenerationSuccess(result: ClientGenerated): GenerationSuccessReport;
-/**
- * Nothing written: the deployment's ClientContract and these bytes are what is
- * there.
- */
 export declare function renderUpToDate(result: ClientUpToDate): GenerationSuccessReport;
 /**
  * What the person running the generator is told before being asked: every path

package/dist/cli/step.reporter.d.ts

@@ -0,0 +1,31 @@
+export type ProgressMode = "live" | "plain" | "off";
+/** `live` only on a terminal that is not CI and accepts control sequences. */
+export declare function progressModeOf(isTTY: boolean | undefined, env: Readonly<Record<string, string | undefined>>): Exclude<ProgressMode, "off">;
+export type StepReporterOptions = {
+    /** Where the lines go: the tool's stderr, so its stdout stays its result. */
+    readonly write: (text: string) => void;
+    readonly mode: ProgressMode;
+    /** How many steps this run takes, for `[n/total]`. */
+    readonly total: number;
+    /** Each child's output streams between a step's start and end lines. */
+    readonly verbose?: boolean;
+    /** Milliseconds now; `Date.now` by default. */
+    readonly now?: () => number;
+    /** Redraw interval of the live line, in milliseconds. */
+    readonly interval?: number;
+};
+export type StepReporter = {
+    /**
+     * Runs one step under its numbered line. Its outcome — `done`, or `failed`
+     * when `body` throws — ends the line; the error is rethrown unchanged.
+     */
+    readonly step: <T>(title: string, body: () => Promise<T> | T) => Promise<T>;
+    /** Streams a child's output, in `verbose` mode only. */
+    readonly output: (chunk: string) => void;
+    /** The closing line: `<prefix>: <what> in <time>.` */
+    readonly finish: (prefix: string, what: string) => void;
+    readonly verbose: boolean;
+};
+/** `12.4s`, or `1m 02s` from a minute. */
+export declare function formatElapsed(milliseconds: number): string;
+export declare function createStepReporter(options: StepReporterOptions): StepReporter;

package/dist/cli/step.reporter.js

@@ -0,0 +1,87 @@
+export function progressModeOf(isTTY, env) {
+    const ci = env.CI;
+    if (isTTY !== true ||
+        (ci !== undefined && ci !== "" && ci !== "0" && ci !== "false") ||
+        (env.NO_COLOR !== undefined && env.NO_COLOR !== "") ||
+        env.TERM === "dumb") {
+        return "plain";
+    }
+    return "live";
+}
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CLEAR_LINE = "\r\u001b[2K";
+const GREEN = (text) => `\u001b[32m${text}\u001b[39m`;
+const RED = (text) => `\u001b[31m${text}\u001b[39m`;
+const DIM = (text) => `\u001b[2m${text}\u001b[22m`;
+export function formatElapsed(milliseconds) {
+    const seconds = milliseconds / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(1)}s`;
+    }
+    const whole = Math.round(seconds);
+    return `${Math.floor(whole / 60)}m ${String(whole % 60).padStart(2, "0")}s`;
+}
+export function createStepReporter(options) {
+    const now = options.now ?? Date.now;
+    const started = now();
+    const verbose = options.verbose === true && options.mode !== "off";
+    const mode = verbose ? "plain" : options.mode;
+    let index = 0;
+    const step = async (title, body) => {
+        index += 1;
+        const label = `[${index}/${options.total}] ${title}`;
+        const at = now();
+        const elapsed = () => formatElapsed(now() - at);
+        if (mode === "off") {
+            return await body();
+        }
+        if (mode === "plain") {
+            options.write(verbose ? `${label}…\n` : `${label}… `);
+            try {
+                const value = await body();
+                options.write(verbose ? `${label}… done (${elapsed()})\n` : `done (${elapsed()})\n`);
+                return value;
+            }
+            catch (error) {
+                options.write(verbose
+                    ? `${label}… failed (${elapsed()})\n`
+                    : `failed (${elapsed()})\n`);
+                throw error;
+            }
+        }
+        let frame = 0;
+        const draw = () => {
+            const seconds = Math.floor((now() - at) / 1000);
+            options.write(`${CLEAR_LINE}${SPINNER[frame % SPINNER.length]} ${label}…${seconds > 0 ? DIM(` ${seconds}s`) : ""}`);
+            frame += 1;
+        };
+        draw();
+        const timer = setInterval(draw, options.interval ?? 80);
+        timer.unref?.();
+        try {
+            const value = await body();
+            clearInterval(timer);
+            options.write(`${CLEAR_LINE}${GREEN("✓")} ${label} ${DIM(elapsed())}\n`);
+            return value;
+        }
+        catch (error) {
+            clearInterval(timer);
+            options.write(`${CLEAR_LINE}${RED("✗")} ${label} ${DIM(elapsed())}\n`);
+            throw error;
+        }
+    };
+    return {
+        step,
+        output: (chunk) => {
+            if (verbose) {
+                options.write(chunk);
+            }
+        },
+        finish: (prefix, what) => {
+            if (mode !== "off") {
+                options.write(`${prefix}: ${what} in ${formatElapsed(now() - started)}.\n`);
+            }
+        },
+        verbose,
+    };
+}

package/dist/cli/terminal.prompter.d.ts

@@ -1,9 +1,3 @@
-/**
- * The terminal's questions — `generate`'s yes/no and `init`'s wizard — over one
- * `node:readline` interface whose lines are **queued**: a line typed (or piped
- * into a pseudo-terminal) before its question is kept for it, where a fresh
- * interface per question, or `readline/promises`' `question`, drops it.
- */
 export type TerminalPrompter = {
     readonly ask: (prompt: string) => Promise<string>;
     readonly confirm: (question: string) => Promise<boolean>;

package/dist/cli/warning.renderer.d.ts

@@ -1,9 +1,3 @@
-/**
- * How one warning reaches the person running the generator: its own stderr line,
- * under the CLI's one prefix. Warnings carry no prefix of their own, so the line
- * says "warning" once. Shared by a success and a refusal, so a warning reads the
- * same either way.
- */
 /** The prefix every warning line opens with. */
 export declare const WARNING_LINE_PREFIX = "avclient: warning: ";
 /** One newline-terminated line per warning, in the order given; empty for none. */

package/dist/cli.d.ts

@@ -1,21 +1,5 @@
 import { type CliIo } from "./cli/generate.command.js";
 export type { CliIo } from "./cli/generate.command.js";
-/**
- * It is also the one place that ASKS: when content the generator did not produce
- * stands in `AvClient.ts` or `generated/`, the paths are listed and the person is
- * asked whether to overwrite them. `--yes` answers for them. Where nobody can
- * answer — stdin is not a terminal — it never asks and never overrides: it
- * refuses, naming `--yes`. Cancelled or refused, nothing was touched, the run's
- * warnings are printed before the sentence, and the exit code is 1. A killed run's
- * leftovers are looked at before the question, so the answer — and `--yes` —
- * covers what it hid as well.
- */
 /** Runs one command line; resolves to the exit code. Never throws. */
 export declare function runCli(argv: readonly string[], io: CliIo): Promise<number>;
-/**
- * Runs `avclient` over this process — its arguments, its terminal, its exit
- * code. Called by the bin's entry (`avclient.bin.ts`) once the Node guard has
- * admitted this Node; importing this module runs nothing, which is what lets
- * `runCli` be tested in process.
- */
 export declare function runFromProcess(): Promise<void>;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { GENERATE_USAGE, INIT_USAGE, parseCliCommand, USAGE, } from "./cli/command.parser.js";
 import { runGenerate } from "./cli/generate.command.js";
 import { renderGenerationFailure } from "./cli/generation-failure.renderer.js";
+import { progressModeOf } from "./cli/step.reporter.js";
 import { createTerminalPrompter } from "./cli/terminal.prompter.js";
 import { AVENTARA_CLIENT_GENERATOR_VERSION } from "./index.js";
 import { runClientInit } from "./init/client-init.orchestrator.js";
@@ -47,6 +48,7 @@ export async function runFromProcess() {
             confirm: terminal.confirm,
             ask: terminal.ask,
             run: runCommand,
+            progress: progressModeOf(process.stderr.isTTY, process.env),
         });
     }
     finally {