@aventara/client 0.1.0-pilot.0 → 0.1.0-pilot.2

package/README.md

@@ -11,7 +11,7 @@ server by construction, and that agreement is gated over both pilot schemas.
 ## Setting up a frontend: `avclient init`
 
 ```bash
-npx @aventara/client init      # in your frontend project
+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:
@@ -23,7 +23,7 @@ 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`, the variable into `.env` (only with a variable), `"avclient:generate": "avclient
+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
@@ -50,10 +50,34 @@ 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.
+
+### 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
+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:
+
+| Your tsconfig | The client's own imports | You import it as |
+|---|---|---|
+| `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) |
+
+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
+client (`tsconfig.app.json`). The validate step type-checks the client in your project's resolution and module format.
+
+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.
@@ -67,9 +91,11 @@ npx avclient generate [--yes]
 - **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` is installed, under a consumer's
-  strictest plausible settings and with nothing outside the tree resolvable. Without it, the check degrades to a parse
-  with Node's own TypeScript parser, and says so loudly — it is never skipped.
+- **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
@@ -78,7 +104,7 @@ npx avclient generate [--yes]
 ## Calling the API
 
 ```ts
-import avClient, { AvClient, type User, type UserWhere } from "./api/AvClient";
+import avClient, { AvClient, type User, type UserWhere } from "./api/AvClient"; // as you import your own files
 
 const where: UserWhere = { email: { equals: "ada@example.com" } };
 const users = await avClient.User.find.many({ where, select: ["id", "email", { posts: { select: ["$count"] } }] });
@@ -165,21 +191,21 @@ chose. The `.d.ts` files are core's copied declarations under `generated/derivat
 - `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 (§6.2), and the request-body serializer.
+- `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 of §14.4 (RFC 8785 canonical JSON, SHA-256,
+- `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 §13.5's
-  rule; arguments encoded by value, results revived by the decode table, the platform's own `fetch` type accepted.
+- `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` — §15.6's named Resource types, as a declaration file (`User`, `UserWhere`,
+- `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.
 
@@ -198,10 +224,9 @@ A deployment whose ClientContract differs refuses the request with `A2005`, whic
 
 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.** (This closes
-the generator's half of follow-up row F-801, by the architect's decision to state the binding rather than its causes.)
+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 (F-716, closed): the server checks the client's
+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.
@@ -209,59 +234,34 @@ mount — is a `TransportError`, which names no remedy: nothing in it says the c
 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.
 
-## Phase 12's deliverables
-
-| Phase 12 deliverable | Status |
-|---|---|
-| `avclient generate` CLI (bin `avclient`, R3) | Delivered, with `--yes` and the foreign-content question. |
-| `.env` loading | Delivered: the five-file cascade, no dependency. |
-| Deployed `/_contract` fetch | Delivered: conditional on the output it finds (`If-None-Match`, `304` → "up to date" only when re-emission is byte-identical). |
-| Protocol compatibility validation | Delivered: the supported-version set, and the hash recomputed with core's function and compared — never trusted as delivered. |
-| ClientContract structure validation | Delivered, by core's `validateClientContractStructure`. |
-| Deterministic named type generation | Delivered: §15.6's named types as aliases over core's derivation, the rename ladder keeping every derived name free. |
-| Resource operation methods, the client class and the default singleton | Delivered: `AvClient` and `avClient`, one method per advertised operation (P4: the runtime's list equals the type grammar's keys over both pilots). |
-| Projection inference | Delivered: core's own call grammar — the caller's `select`/`include` literal inferred. Facts the capability model cannot state yet are unstated on both sides alike: **F-809**, **F-812**, **F-813**, **F-818** no longer block the client. |
-| Deferred transaction builder | Delivered, iff the ClientContract advertises `interactive`; core's Contract-derived `Operation<T>` (**F-701**, closed) types each handle. |
-| Transport runtime emitted into output | Delivered, including the stale-client mechanism (**F-716**, closed: server-side). |
-| Scalar codecs | Delivered: all nine scalars of §6.2, encoded by value, revived by a decode table. |
-| Typed framework and transport errors | Delivered. |
-| Contract version and hash embedded into output | Delivered (`generated/metadata.ts`), with the resolved entrypoint as the default (§15.2). |
-| Atomic temp → validate → replace | Delivered. |
-| Generated-file ownership banners | Delivered. |
-| No runtime import from `@aventara/client` | Delivered, and gated: nothing outside the tree, `@aventara/core` included. |
-| Availability readers | Read through core's `isOperationVariantAvailable` (**F-820**, closed). Not hand-rolled here. |
-
-### Phase 12's exit gate
-
-- *"Delete the generated client, regenerate it from the same contract, and obtain equivalent output"* — **passed, and
-  strengthened to byte-identical**, through the packed bin against a real HTTP server, with the callable surface, core's
-  derivation and the transaction runtime in the tree.
-- *"A generated test application compiles without depending on server source types"* — **passed, and run**: a
-  throwaway project where neither `@aventara/core` nor `@aventara/client` can resolve generates its client from a
-  running host, compiles a program against it with `tsc`, and runs it — scalars revived, an enum, a `$count` envelope, a
-  transaction with a `$ref`, a `NotFoundError`, an abort, and `ContractMismatchError` after the host's contract changes.
-
-### Type-checking cost in a consumer
+## 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 (**F-839**): about 204,000 for the same
+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.
 
-### Known seams, to be closed when their owners land
-
-- **The envelope check** — "did a framework envelope arrive?" — is the emitted transport's own, pinned to core's
-  `AvProtocol.isOperationResponse` over every corpus row.
-- **Specification edits owed to the specification owner** are listed in follow-up row F-838: the names (`avClient`,
-  `AvClient`, `CallOptions`), the emitted tree's layout, the forms map, credentials, "up to date".
-- **The end-to-end and ownership gates read a gitignored file by path:** the SQLite pilot's discovery artifact,
-  `packages/prisma7-adapter/generated/artifact/sqlite.artifact.ts`, which exists only after the adapter's generate step
-  has run (`pnpm typecheck` runs it). This package takes no dependency on the adapter.
-- **The `Aventara` wire prefix** of the identity headers must be frozen before the first external release (§12.4). It is
-  one constant in `generated/runtime/transport.ts`, so the freeze is a one-line change.
-- **A tarball from `npm pack` is not a releasable artifact** while `@aventara/core` is spelled `workspace:*`, and does
-  not install outside this workspace (F-808, Phase 13). Do not validate a pilot against one.
+## 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.
+
+## 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:
+
+  ```ts
+  export default defineClientConfig({
+  	entrypoint: env("AVENTARA_API_URL"),
+  	generateAt: "./src/api",
+  	tsconfigFile: "./tsconfig.app.json",
+  });
+  ```
 
 ## License
 

package/dist/avclient.bin.js

@@ -1,15 +1,5 @@
 #!/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

@@ -1,12 +1,16 @@
 /**
- * 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).
+ * 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 in the current directory,\n                              fetch <entrypoint>/_contract, and write AvClient.ts\n                              and generated/ into its generateAt directory.\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\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 init`'s command line (R4, Q16 rows 12–15). */
+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 type ClientInitCommand = {
     readonly command: "init";
     readonly given: Readonly<Partial<Record<"entrypoint" | "envVar" | "generateAt" | "packageManager", string>>>;
@@ -16,8 +20,13 @@ export type ClientInitCommand = {
     readonly yes: boolean;
 };
 /** What the command line asked for. */
-export type CliCommand = {
+export type CliCommand = 
+/** `--help`; with `topic`, `avclient <topic> --help` (pilot.1). */
+{
     readonly command: "help";
+    readonly topic?: "generate" | "init";
+} | {
+    readonly command: "version";
 } | {
     readonly command: "generate";
     readonly yes: boolean;
@@ -26,5 +35,8 @@ export type CliCommand = {
 export declare class CliCommandError extends Error {
     readonly name = "CliCommandError";
 }
-/** @throws CliCommandError when `argv` is not `generate [--yes|-y]`, `--help` or `-h`. */
+/**
+ * @throws CliCommandError 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

@@ -1,17 +1,12 @@
 import { 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} in the current directory,
-                              fetch <entrypoint>/_contract, and write AvClient.ts
-                              and generated/ into its generateAt directory.
+  avclient generate [--yes]   Read ${CLIENT_CONFIG_FILE} (or .js, .mjs, .cjs, .mts,
+                              .cts) in the current directory, fetch
+                              <entrypoint>/_contract, and write AvClient.ts and
+                              generated/ into its generateAt directory, its imports
+                              spelled as the project's tsconfig.json says.
   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.
@@ -24,6 +19,8 @@ Usage:
       --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.
+  avclient --version, -v      Print this generator's version and exit 0.
 
 Options:
   -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the
@@ -40,11 +37,46 @@ current directory, highest precedence first: the process environment,
 .env.<mode>.local, .env.<mode>, .env.local, .env — where mode is NODE_ENV, or
 "development".
 `;
-/** The command line cannot be understood. A refusal: one sentence, exit 1. */
+export const GENERATE_USAGE = `Usage: avclient generate [--yes]
+
+Read ${CLIENT_CONFIG_FILE} (or .js, .mjs, .cjs, .mts, .cts) in the current directory,
+fetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its
+generateAt directory, its imports spelled as the project's tsconfig.json says.
+
+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".
+`;
+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.
+`;
 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.";
@@ -54,6 +86,13 @@ export function parseCliCommand(argv) {
     if (command === "--help" || command === "-h") {
         return { command: "help" };
     }
+    if (command === "--version" || command === "-v") {
+        return { command: "version" };
+    }
+    if ((command === "init" || command === "generate") &&
+        (rest.includes("--help") || rest.includes("-h"))) {
+        return { command: "help", topic: command };
+    }
     if (command === "init") {
         return parseInit(rest, help);
     }

package/dist/cli/generate.command.js

@@ -1,11 +1,5 @@
 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,

package/dist/cli/generation-failure.renderer.js

@@ -6,22 +6,9 @@ import { GeneratedNameError } from "../emit/name.deriver.js";
 import { ClientInitNotConfirmedError, ClientInitStepError, } from "../init/client-init.errors.js";
 import { ClientInitAnswerError, ClientInitUnansweredError, } from "../init/client-init.questions.js";
 import { ClientProjectRefusedError } from "../init/client-project.inspector.js";
-import { UnsupportedTypeScriptError } from "../output/output.validator.js";
 import { OutputWriteError, warningsRaisedBeforeDefect, } from "../output/output.writer.js";
 import { CliCommandError } from "./command.parser.js";
 import { renderWarningLines } from "./warning.renderer.js";
-/**
- * How a failed generation reaches the person running it (M3, the adapter CLI's
- * precedent): a refusal is a sentence and a non-zero exit code, never a stack — a
- * stack printed over it buries the sentence that says what to do. Anything else is
- * a defect and keeps its stack.
- *
- * A refusal that stopped a run part-way carries what the run said before it —
- * a crash recovered, a name renamed — and those lines come first, in the order a
- * success prints them, so nothing the run did goes unreported because it failed.
- * A defect's come first too, then its stack, whole.
- */
-/** Every error the generator raises on purpose. One list, read by `instanceof`. */
 const REFUSALS = [
     CliCommandError,
     ClientConfigError,
@@ -30,7 +17,6 @@ const REFUSALS = [
     ContractProtocolError,
     GeneratedNameError,
     OutputWriteError,
-    UnsupportedTypeScriptError,
     ClientInitAnswerError,
     ClientInitUnansweredError,
     ClientProjectRefusedError,
@@ -41,8 +27,6 @@ export function renderGenerationFailure(error) {
     if (REFUSALS.some((refusal) => error instanceof refusal)) {
         const carried = error instanceof OutputWriteError ? error.warnings : [];
         return {
-            // A refused contract carries its own (plan §7); the other refusals are 1,
-            // the adapter CLI's precedent (M3).
             exitCode: error instanceof ContractProtocolError ? error.exitCode : 1,
             text: `${renderWarningLines(carried)}avclient: ${error.message}\n`,
         };

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

@@ -13,7 +13,10 @@ export interface GenerationSuccessReport {
     readonly stderr: string;
 }
 export declare function renderGenerationSuccess(result: ClientGenerated): GenerationSuccessReport;
-/** Nothing written (Phase 12-rest Q6): the deployment's ClientContract and these bytes are what is there. */
+/**
+ * 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/generation-success.renderer.js

@@ -10,32 +10,19 @@ export function renderGenerationSuccess(result) {
         stderr: renderWarningLines(result.warnings),
     };
 }
-/** Nothing written (Phase 12-rest Q6): the deployment's ClientContract and these bytes are what is there. */
 export function renderUpToDate(result) {
     return {
         stdout: `avclient: up to date: ${result.generateAt} already holds this deployment's client; nothing was written.\n`,
         stderr: renderWarningLines(result.warnings),
     };
 }
-/**
- * What the person running the generator is told before being asked: every path
- * in `AvClient.ts` and `generated/` that the generator did not produce, which
- * proceeding overwrites or removes.
- */
 export function renderForeignContentWarning(found) {
     return (`${WARNING_LINE_PREFIX}${found.foreign.join(", ")} in ${found.generateAt} ` +
         `${found.foreign.length === 1 ? "was" : "were"} not generated by @aventara/client, ` +
         "and generating will overwrite or remove " +
         `${found.foreign.length === 1 ? "it" : "them"}.\n`);
 }
-/** The question; answered yes, generation proceeds. */
 export const FOREIGN_CONTENT_QUESTION = "avclient: overwrite them and generate? [y/N] ";
-/**
- * Nobody confirmed: nothing was touched. One sentence naming what to sort out —
- * and, where nobody could have been asked, the flag that answers yes — after
- * every warning the run raised before it stopped, so a cancelled run's renames
- * are reported as a refused one's are.
- */
 export function renderForeignContentCancellation(found, asked) {
     const them = found.foreign.length === 1 ? "it" : "them";
     return `${renderWarningLines(found.warnings)}${asked

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

@@ -2,8 +2,7 @@
  * 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 (measured
- * in `@aventara/cli`'s S5; the same rule there, P7).
+ * interface per question, or `readline/promises`' `question`, drops it.
  */
 export type TerminalPrompter = {
     readonly ask: (prompt: string) => Promise<string>;

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

@@ -1,8 +1,8 @@
 /**
  * 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 (S7b's report: the degraded check used to say it twice).
- * Shared by a success and a refusal, so a warning reads the same either way.
+ * 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: ";

package/dist/cli/warning.renderer.js

@@ -1,12 +1,4 @@
-/**
- * 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 (S7b's report: the degraded check used to say it twice).
- * Shared by a success and a refusal, so a warning reads the same either way.
- */
-/** The prefix every warning line opens with. */
 export const WARNING_LINE_PREFIX = "avclient: warning: ";
-/** One newline-terminated line per warning, in the order given; empty for none. */
 export function renderWarningLines(warnings) {
     return warnings
         .map((warning) => `${WARNING_LINE_PREFIX}${warning}\n`)

package/dist/cli.d.ts

@@ -1,22 +1,14 @@
 import { type CliIo } from "./cli/generate.command.js";
 export type { CliIo } from "./cli/generate.command.js";
 /**
- * `avclient` — the generator's bin (`avclient generate`), S7b.
- *
- * It parses the command line, runs §15.3's pipeline (`generate.ts`) in the
- * current directory, and owns the terminal: the success line goes to stdout,
- * every warning the run returned to stderr in the run's order, and a failure
- * through the refusal renderer — a refusal is one sentence and exit 1 with no
- * stack (M3), anything else is a defect and keeps its stack.
- *
- * It is also the one place that ASKS (architect, 2026-10-04): 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.
+ * 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>;

package/dist/cli.js

@@ -1,33 +1,23 @@
-import { parseCliCommand, USAGE } from "./cli/command.parser.js";
+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 { createTerminalPrompter } from "./cli/terminal.prompter.js";
+import { AVENTARA_CLIENT_GENERATOR_VERSION } from "./index.js";
 import { runClientInit } from "./init/client-init.orchestrator.js";
 import { runCommand } from "./init/command.runner.js";
-/**
- * `avclient` — the generator's bin (`avclient generate`), S7b.
- *
- * It parses the command line, runs §15.3's pipeline (`generate.ts`) in the
- * current directory, and owns the terminal: the success line goes to stdout,
- * every warning the run returned to stderr in the run's order, and a failure
- * through the refusal renderer — a refusal is one sentence and exit 1 with no
- * stack (M3), anything else is a defect and keeps its stack.
- *
- * It is also the one place that ASKS (architect, 2026-10-04): 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 async function runCli(argv, io) {
     try {
         const command = parseCliCommand(argv);
         if (command.command === "help") {
-            io.stdout(USAGE);
+            io.stdout(command.topic === undefined
+                ? USAGE
+                : command.topic === "init"
+                    ? INIT_USAGE
+                    : GENERATE_USAGE);
+            return 0;
+        }
+        if (command.command === "version") {
+            io.stdout(`${AVENTARA_CLIENT_GENERATOR_VERSION}\n`);
             return 0;
         }
         if (command.command === "init") {
@@ -41,12 +31,6 @@ export async function runCli(argv, io) {
         return failure.exitCode;
     }
 }
-/**
- * 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 async function runFromProcess() {
     const terminal = createTerminalPrompter();
     try {