@aventara/client 0.0.0-stage → 0.1.0-pilot.1

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright 2026 Mohamed Ragheb
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/LICENSE-ADDITIONAL-PERMISSION.md

@@ -0,0 +1,9 @@
+# Additional Permission — Aventara
+
+Copyright 2026 Mohamed Ragheb
+
+In addition to the permissions of the PolyForm Shield License 1.0.0 in `LICENSE`, the licensor grants the following additional permission:
+
+The Noncompete section applies only to providing a product that competes with the software itself — the Aventara framework, its packages and its tooling. Providing a product that competes with any other product the licensor or its affiliates provide using the software is a permitted purpose.
+
+This additional permission only adds to your permissions; it does not restrict or replace any term of `LICENSE`.

package/README.md

@@ -1,3 +1,235 @@
-# Temporary Holding Version
+# `@aventara/client`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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.
+
+## Setting up a frontend: `avclient init`
+
+```bash
+npx @aventara/client@pilot init      # in your frontend project; pnpm: pnpm dlx @aventara/client@pilot init
+```
+
+It asks — or takes from flags, or with `--yes` takes every default — four things, and writes the setup:
+
+| Flag | Question | Default |
+|---|---|---|
+| `--entrypoint <url>` | The server's framework entrypoint | `http://localhost:3000/api` |
+| `--env-var <NAME>` / `--no-env-var` | Read it from this variable, or write it as a literal | `AVENTARA_API_URL` |
+| `--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.mts`, 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.
+
+## Generating a client
+
+Install it as a dev dependency (or let `avclient init` do it), then add `framework.client.mts` to the directory you run
+the generator from:
+
+```ts
+import { defineClientConfig, env } from "@aventara/client";
+
+export default defineClientConfig({
+	entrypoint: env("AVENTARA_API_URL"),
+	generateAt: "./src/api",
+});
+```
+
+and run:
+
+```text
+npx avclient generate [--yes]
+```
+
+**Why `.mts`.** `npm init -y` writes `"type": "commonjs"`, and under it Node reads a `.ts` file as CommonJS — the
+config's `import` would stop the run. A `.mts` file is an ES module in every project. A `framework.client.ts` written
+before 0.1.0-pilot.1 is still read; with both files present the generator refuses, and `avclient init` moves the old one
+to `framework.client.mts` (asking first if you edited it).
+
+- **`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 `.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 the optional peer `typescript` (5.5 to 6) is installed, 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.
+
+## Calling the API
+
+```ts
+import avClient, { AvClient, type User, type UserWhere } from "./api/AvClient";
+
+const where: UserWhere = { email: { equals: "ada@example.com" } };
+const users = await avClient.User.find.many({ where, select: ["id", "email", { posts: { select: ["$count"] } }] });
+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
+  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`,
+  `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.
+
+## Transactions
+
+When the ClientContract advertises `interactive` transactions, the client has `avClient.tx` and `avClient.transaction`
+(otherwise neither exists):
+
+```ts
+const created = avClient.tx.User.create.one({ data: { email: "ada@example.com" }, select: ["id"] });
+const profile = avClient.tx.Profile.create.one({ data: { bio: "…", userId: created.$ref("id") } });
+const [user, row] = await avClient.transaction([created, profile]);
+```
+
+`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.
+
+## 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:
+
+```ts
+const client = new AvClient({
+	fetch: (input, init) => fetch(input, { ...init, headers: { ...init?.headers, Authorization: `Bearer ${token}` } }),
+});
+```
+
+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
+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
+`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,
+  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
+  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. 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.
+
+## 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`.
+
+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.**
+
+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 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.
+
+## 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.
+
+## 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.
+
+## 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`.

package/dist/avclient.bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/avclient.bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { refuseUnsupportedNode } from "./node-version.guard.js";
+/**
+ * `avclient`'s entry, what the manifest's `bin` names (F-855). It always runs — no
+ * `import.meta.main` — and checks this Node against the package's
+ * `engines.node` before it loads anything else: the program is imported only
+ * once the guard admits this Node, so an older Node meets one sentence and exit
+ * 1, never a silent exit 0 or a parse error from a module it cannot run.
+ *
+ * A promise chain rather than a top-level `await`, which Node 12 cannot parse:
+ * this file is read by the Nodes the package does not support.
+ */
+if (!refuseUnsupportedNode("avclient", new URL("../package.json", import.meta.url))) {
+    void import("./cli.js").then((program) => program.runFromProcess());
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The `avclient` command line: one command, its one flag, and help. Everything
+ * the generator needs is in `framework.client.ts` and the `.env` cascade (§15.2),
+ * 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 (architect, 2026-10-04).
+ */
+export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.mts (or framework.client.ts) in the\n                              current directory, fetch <entrypoint>/_contract, and\n                              write AvClient.ts and generated/ into its generateAt\n                              directory.\n  avclient init [options]     Set up this frontend: write framework.client.mts, 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.mts 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\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.mts 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.mts (or framework.client.ts) in the current directory, fetch\n<entrypoint>/_contract, and write AvClient.ts and generated/ into its generateAt\ndirectory.\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.mts, 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.mts 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 (R4, Q16 rows 12–15). */
+export type ClientInitCommand = {
+    readonly command: "init";
+    readonly given: Readonly<Partial<Record<"entrypoint" | "envVar" | "generateAt" | "packageManager", string>>>;
+    readonly noEnvVar: boolean;
+    readonly skipInstall: boolean;
+    readonly skipGenerate: boolean;
+    readonly yes: boolean;
+};
+/** What the command line asked for. */
+export type CliCommand = 
+/** `--help`; with `topic`, `avclient <topic> --help` (pilot.1). */
+{
+    readonly command: "help";
+    readonly topic?: "generate" | "init";
+} | {
+    readonly command: "generate";
+    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";
+}
+/** @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `--help` or `-h`. */
+export declare function parseCliCommand(argv: readonly string[]): CliCommand;

package/dist/cli/command.parser.js

@@ -0,0 +1,177 @@
+import { CLIENT_CONFIG_FILE, LEGACY_CLIENT_CONFIG_FILE, } from "../config/config.loader.js";
+/**
+ * The `avclient` command line: one command, its one flag, and help. Everything
+ * the generator needs is in `framework.client.ts` and the `.env` cascade (§15.2),
+ * 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 (architect, 2026-10-04).
+ */
+export const USAGE = `avclient — generate a typed Aventara client from a deployed ClientContract.
+
+Usage:
+  avclient generate [--yes]   Read ${CLIENT_CONFIG_FILE} (or ${LEGACY_CLIENT_CONFIG_FILE}) in the
+                              current directory, fetch <entrypoint>/_contract, and
+                              write AvClient.ts and generated/ into its generateAt
+                              directory.
+  avclient init [options]     Set up this frontend: write ${CLIENT_CONFIG_FILE}, the
+                              .env entry, the avclient:generate script and the
+                              @aventara/client devDependency; install; generate.
+      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].
+      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].
+      --no-env-var            Write it into ${CLIENT_CONFIG_FILE} as a literal.
+      --generate-at <dir>     Where the client goes [./src/api].
+      --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.
+      -y, --yes               Accept every default, and replace differing content.
+  avclient --help             Print this and exit 0.
+  avclient <command> --help   Print that command's usage and exit 0.
+
+Options:
+  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
+              generator did not produce, without asking. Without it, such content
+              is listed and you are asked; where nobody can answer (stdin is not a
+              terminal, as in CI), the run is refused and nothing is touched.
+
+The generator owns AvClient.ts and generated/ in generateAt, and nothing else
+there: your own files beside them are never read, moved or removed. Generated
+files are replaced on every run; do not edit them.
+
+Before ${CLIENT_CONFIG_FILE} is evaluated, the .env cascade is read from the
+current directory, highest precedence first: the process environment,
+.env.<mode>.local, .env.<mode>, .env.local, .env — where mode is NODE_ENV, or
+"development".
+`;
+/** `avclient generate --help` (pilot.1): that command's usage alone. */
+export const GENERATE_USAGE = `Usage: avclient generate [--yes]
+
+Read ${CLIENT_CONFIG_FILE} (or ${LEGACY_CLIENT_CONFIG_FILE}) in the current directory, fetch
+<entrypoint>/_contract, and write AvClient.ts and generated/ into its generateAt
+directory.
+
+Options:
+  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
+              generator did not produce, without asking. Without it, such content
+              is listed and you are asked; where nobody can answer (stdin is not a
+              terminal, as in CI), the run is refused and nothing is touched.
+
+The generator owns AvClient.ts and generated/ in generateAt, and nothing else
+there: your own files beside them are never read, moved or removed.
+
+Before the config is evaluated, the .env cascade is read from the current
+directory, highest precedence first: the process environment, .env.<mode>.local,
+.env.<mode>, .env.local, .env — where mode is NODE_ENV, or "development".
+`;
+/** `avclient init --help` (pilot.1): that command's usage alone. */
+export const INIT_USAGE = `Usage: avclient init [options]
+
+Set up this frontend: write ${CLIENT_CONFIG_FILE}, the .env entry, the avclient:generate
+script and the @aventara/client devDependency; install; generate.
+
+Options:
+  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].
+  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].
+  --no-env-var                   Write it into ${CLIENT_CONFIG_FILE} as a literal.
+  --generate-at <dir>            Where the client goes [./src/api].
+  --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.
+  -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.
+`;
+/** The command line cannot be understood. A refusal: one sentence, exit 1. */
+export class CliCommandError extends Error {
+    name = "CliCommandError";
+}
+/** @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `--help` or `-h`. */
+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}`);
+    }
+    if (command === "--help" || command === "-h") {
+        return { command: "help" };
+    }
+    if ((command === "init" || command === "generate") &&
+        (rest.includes("--help") || rest.includes("-h"))) {
+        return { command: "help", topic: command };
+    }
+    if (command === "init") {
+        return parseInit(rest, help);
+    }
+    if (command !== "generate") {
+        throw new CliCommandError(`unknown command ${JSON.stringify(command)}; ${help}`);
+    }
+    let yes = false;
+    for (const argument of rest) {
+        if ((argument === "--yes" || argument === "-y") && !yes) {
+            yes = true;
+            continue;
+        }
+        throw new CliCommandError(`unexpected argument ${JSON.stringify(argument)}: generate takes only --yes, ` +
+            `everything else it needs is in ${CLIENT_CONFIG_FILE}; ${help}`);
+    }
+    return { command: "generate", yes };
+}
+const INIT_VALUES = {
+    "--entrypoint": "entrypoint",
+    "--env-var": "envVar",
+    "--generate-at": "generateAt",
+    "--package-manager": "packageManager",
+};
+const INIT_SWITCHES = {
+    "--no-env-var": "noEnvVar",
+    "--skip-install": "skipInstall",
+    "--skip-generate": "skipGenerate",
+    "--yes": "yes",
+    "-y": "yes",
+};
+function parseInit(argv, help) {
+    const given = {};
+    const switches = {
+        noEnvVar: false,
+        skipInstall: false,
+        skipGenerate: false,
+        yes: false,
+    };
+    const seen = new Set();
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        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}`);
+        }
+        const canonical = toggle === "yes" ? "--yes" : flag;
+        if (seen.has(canonical)) {
+            throw new CliCommandError(`${canonical} was given twice; ${help}`);
+        }
+        seen.add(canonical);
+        if (toggle !== undefined) {
+            if (inline !== undefined) {
+                throw new CliCommandError(`${canonical} takes no value; ${help}`);
+            }
+            switches[toggle] = true;
+            continue;
+        }
+        const taken = inline ?? argv[index + 1];
+        if (taken === undefined ||
+            (inline === undefined && taken.startsWith("-"))) {
+            throw new CliCommandError(`${canonical} takes a value; ${help}`);
+        }
+        if (inline === undefined) {
+            index += 1;
+        }
+        given[value] = taken;
+    }
+    if (switches.noEnvVar && given.envVar !== undefined) {
+        throw new CliCommandError(`--env-var and --no-env-var contradict each other; ${help}`);
+    }
+    return { command: "init", given, ...switches };
+}

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

@@ -0,0 +1,24 @@
+import type { ProcessEnvInput } from "../config/env.cascade.js";
+import type { CommandRunner } from "../init/command.runner.js";
+/** What `runCli` reads and writes instead of the process globals. */
+export interface CliIo {
+    readonly cwd: string;
+    readonly env: ProcessEnvInput;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    /** Whether someone can answer a question: stdin is a terminal. */
+    readonly interactive: boolean;
+    /** Asks `question`; resolves true for yes. Called only when `interactive`. */
+    readonly confirm: (question: string) => Promise<boolean>;
+    /** Asks for a line; resolves with what was typed. Called only when `interactive` (`init`). */
+    readonly ask?: (prompt: string) => Promise<string>;
+    /** Runs a command with stdout piped (`init`'s install); a child process by default. */
+    readonly run?: CommandRunner;
+}
+/**
+ * `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>;

package/dist/cli/generate.command.js

@@ -0,0 +1,41 @@
+import { generateClient } from "../generate.js";
+import { FOREIGN_CONTENT_QUESTION, renderForeignContentCancellation, renderForeignContentWarning, renderGenerationSuccess, renderUpToDate, } from "./generation-success.renderer.js";
+/**
+ * `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 async function runGenerate(io, yes) {
+    const outcome = await generateClient({
+        directory: io.cwd,
+        processEnv: io.env,
+        overrideForeign: yes,
+    });
+    if (outcome.kind === "up-to-date") {
+        const report = renderUpToDate(outcome);
+        io.stderr(report.stderr);
+        io.stdout(report.stdout);
+        return 0;
+    }
+    let result;
+    if (outcome.kind === "foreign-content") {
+        if (!io.interactive) {
+            io.stderr(renderForeignContentCancellation(outcome, false));
+            return 1;
+        }
+        io.stderr(renderForeignContentWarning(outcome));
+        if (!(await io.confirm(FOREIGN_CONTENT_QUESTION))) {
+            io.stderr(renderForeignContentCancellation(outcome, true));
+            return 1;
+        }
+        result = await outcome.proceed();
+    }
+    else {
+        result = outcome;
+    }
+    const report = renderGenerationSuccess(result);
+    io.stderr(report.stderr);
+    io.stdout(report.stdout);
+    return 0;
+}