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

package/dist/emit/emitted-tree.interface.d.ts

@@ -1,57 +1,14 @@
-/**
- * The generator's output as a VALUE before it is a filesystem effect.
- * Byte-equality is therefore testable without touching disk, and temp → validate →
- * replace is a property of the writer alone rather than of every emitter.
- */
 import type { ClientModuleStyle } from "./module-style.interface.js";
-/**
- * The output layout: the consumer names a directory, `generateAt`, which is SHARED
- * — they may keep their own files there. The generator owns exactly two entries in
- * it:
- *
- * - `AvClient.ts`, the entry point a consumer imports;
- * - `generated/`, every other module, owned and replaced whole.
- *
- * The tree is TypeScript source that the developer's own toolchain compiles like
- * their own files — `tsc`, Next.js (Turbopack or webpack), Vite, `tsx`, Node's
- * type stripping. pilot.1's tree always spelled its internal imports NodeNext's
- * way (`./generated/client.js`), which a bundler that does not map `.js` back to
- * `.ts` (Turbopack) and plain Node could not follow. Now those specifiers are the
- * project's: extensionless, `.js` or `.ts`, as its `tsconfig.json` decides
- * (`module-style.interface.ts`, Prisma 7's rules). A consumer imports the entry as
- * they import their own files — `./api/AvClient`, `./api/AvClient.js` or
- * `./api/AvClient.ts`.
- */
 /** The entry point, at the root of `generateAt`. */
 export declare const CLIENT_ENTRY_FILE = "AvClient.ts";
-/** The files the generator owns at the root of `generateAt`. */
 export declare const CLIENT_ENTRY_FILES: readonly ["AvClient.ts"];
 /** One of the entry point's files. */
 export type ClientEntryFile = (typeof CLIENT_ENTRY_FILES)[number];
-/**
- * Entry files an unreleased build of this generator wrote — JavaScript beside
- * declarations, never published. Each is the generator's only while it carries
- * the ownership line: a generation removes it then, so no stale `AvClient.mjs`
- * is left beside the `AvClient.ts` it was replaced by. One without the line is
- * the developer's file, and nothing reads, refuses on or removes it. (pilot.0's
- * and pilot.1's entry is `AvClient.ts` itself, replaced in place.)
- */
 export declare const LEGACY_CLIENT_ENTRY_FILES: readonly string[];
 /** The directory holding every other emitted module, under `generateAt`. */
 export declare const GENERATED_DIRECTORY = "generated";
-/**
- * One of core's published declaration files, copied under `generated/derivation/`
- * at its path relative to core's `dist`.
- */
 export type DerivationModulePath = `derivation/${string}.d.ts`;
-/**
- * Relative to `generated/`, POSIX-separated.
- */
 export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/fingerprint.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
-/**
- * The carrier: the ClientContract the tree was generated against, under
- * `generated/` — the module a rerun reads back to ask for a `304`.
- */
 export declare const CONTRACT_CARRIER_MODULE = "contract.ts";
 /** A path in the emitted tree: relative to `generateAt`, POSIX-separated. */
 export type EmittedFilePath = typeof CLIENT_ENTRY_FILE | `${typeof GENERATED_DIRECTORY}/${GeneratedModulePath}`;
@@ -65,17 +22,7 @@ export interface EmittedFile {
     readonly path: EmittedFilePath;
     readonly bytes: Uint8Array;
 }
-/**
- * Every file one generation emits, in UTF-16 code-unit order of `path`, each path
- * once — `AvClient.ts` first, then `generated/**`. Replaced, never merged:
- * `generated/` whole, `AvClient.ts` as one file.
- */
 export type EmittedTree = readonly EmittedFile[];
-/**
- * What emission yields: the tree, and the diagnostics a run raised without
- * failing — today, one line per renamed name (`name.deriver.ts`). Returned rather
- * than printed, so the code that owns the terminal decides where they go.
- */
 export interface ClientEmission {
     readonly tree: EmittedTree;
     /** The project's spelling the tree was emitted in, and is validated in. */

package/dist/emit/enum.emitter.d.ts

@@ -1,24 +1,4 @@
 import type { ClientContract } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type EmittedNames } from "./name.deriver.js";
-/**
- * `enums.ts`: per enum, a string-literal union type and a same-named `as const`
- * object:
- *
- * ```ts
- * export type Role = "ADMIN" | "USER";
- * export const Role = { ADMIN: "ADMIN", USER: "USER" } as const;
- * ```
- *
- * The type is what every later emitter references; the object gives a consumer a
- * value to name a member by and to enumerate. Both are declared under the enum's
- * emitted identifier, which differs from its contract name only when the name was
- * renamed (`name.deriver.ts`). The values are the wire values and are never
- * renamed.
- *
- * Enums come in the order `names` gives them — UTF-16 code units of the contract
- * name — so the key order a contract arrives in never reaches the bytes. An enum's
- * VALUES keep their declared order, in the type and in the object: that order is
- * meaning, and canonical form keeps it too.
- */
 export declare function emitEnumsModule(contract: Pick<ClientContract, "enums">, names: EmittedNames): EmittedModule;

package/dist/emit/module-specifier.scanner.d.ts

@@ -1,9 +1,3 @@
-/**
- * Which modules a file names, read without `typescript`: the derivation's copy
- * walks core's declaration closure by it (`derivation.emitter.ts`), and the output
- * validator checks by it that every module the emitted tree names is a file of the
- * tree, spelled the project's way — with or without a compiler.
- */
 export interface ScannedModule {
     /**
      * Every module specifier: a `from` clause's, a side-effect `import`'s, and an
@@ -13,13 +7,4 @@ export interface ScannedModule {
     /** Whether the file carries a `/// <reference …/>` directive. */
     readonly references: boolean;
 }
-/**
- * The specifiers one module names — a declaration file or JavaScript — read by a
- * small lexer rather than by `typescript` (an optional peer, absent from a
- * consumer's install): comments, string literals, template literals and
- * regular-expression literals are skipped as units, so text inside them is never
- * mistaken for an import. Agrees with TypeScript's own pre-processor over core's
- * closure (`derivation.emitter.spec.ts`) and over every emitted file
- * (`module-specifier.scanner.spec.ts`).
- */
 export declare function scanModuleSpecifiers(text: string): ScannedModule;

package/dist/emit/module-style.interface.d.ts

@@ -1,12 +1,3 @@
-/**
- * How the generated client's modules are spelled for the project that compiles
- * them. The client is TypeScript source — `.ts` files — and the developer's own
- * toolchain compiles it like their own files, so the relative specifiers by which
- * its modules name each other, and the module format they are checked in, follow
- * that project's rules. The names and the rules are Prisma 7's `prisma-client`
- * generator's (`importFileExtension`, `moduleFormat`), inferred from the project's
- * `tsconfig.json` (`config/module-style.resolver.ts`).
- */
 /**
  * The extension a relative import inside the generated client is written with:
  *
@@ -42,12 +33,6 @@ export interface ClientModuleStyle {
  * the module it imports.
  */
 export type ExtensionlessModulePath = `./${string}` | `../${string}`;
-/**
- * The specifier a generated module imports `module` by, in this style. One rule
- * for every target, `.ts` source and `.d.ts` declaration alike: TypeScript
- * resolves an extensionless, a `.js` and a `.ts` specifier to either (measured
- * under `nodenext` and `bundler`, TypeScript 5.9, 6 and 7).
- */
 export declare function importSpecifier(module: ExtensionlessModulePath, style: Pick<ClientModuleStyle, "importFileExtension">): string;
 /**
  * Writes the quoted specifier an emitted `import`/`export … from` names a

package/dist/emit/name.deriver.d.ts

@@ -1,56 +1,6 @@
 import { type ClientContract, type OperationFamily } from "@aventara/core";
 /**
  * Name derivation and the rename ladder for the emitted tree.
- *
- * The name the server uses — the wire name a Resource is addressed by — is kept
- * beside it unchanged (`EmittedName.contractName`), so a later emitter that sends
- * a request reads that, never the identifier. Every rename is one warning line on
- * the result; generation does not print.
- *
- * A name is unusable as-is when it is not an identifier, is a reserved word, is a
- * predefined type's name, is a name the generated runtime owns, or — an enum only
- * — is also a Resource's name. Its ladder is tried in order and the first rung
- * that is usable AND free of every other emitted name (verbatim or renamed) wins:
- *
- * - Resource `X`: `XModel` → `ResourceX` → `X_` → `_X` → `_X_` → refused;
- * - enum `X`: `XEnum` → `EnumX` → `X_` → refused.
- *
- * Only a name whose whole ladder is unusable or taken is refused, in one sentence
- * — and a name no rename can repair, which is refused without trying a rung: the
- * empty name. Every rung of its ladder is a bare affix (`Model`, `Enum`, `_`) that
- * names nothing on the server, so "renaming" it would invent an identifier rather
- * than repair one.
- *
- * # Determinism
- *
- * The same Contract always yields the same names, whatever order its keys arrive
- * in: every name usable as-is is claimed first (so a usable name is never
- * displaced by another's rename), then Resources are renamed, then enums, each
- * registry in UTF-16 code-unit order of its contract names. An enum sharing a
- * Resource's name walks its ladder and the Resource keeps the name.
- *
- * # One namespace
- *
- * Names are case-sensitive.
- *
- * A Resource's base name is taken at the first rung — its own name first, when
- * usable — where the base AND every name derived from it are free of every other
- * emitted name: `User` beside a Resource `UserWhere` walks to `UserModel`, one
- * warning. Derived names a Resource claims are claimed for good, so a later
- * Resource or enum never takes one. The generated modules that declare these names
- * use no global type a Resource could shadow (`types.d.ts` imports two helpers,
- * which are reserved).
- *
- * A Resource is reached as a property of the client, named by its contract name. A
- * contract name equal to one of the client's own members ({@link
- * CLIENT_MEMBER_NAMES}) walks the Resource ladder for its PROPERTY only, one
- * warning; the wire name, and the TypeScript type names, are unaffected.
- *
- * Reads registry KEYS and which operations are advertised. No capability member.
- */
-/**
- * A Contract name equal to one of them walks its rename ladder. In UTF-16
- * code-unit order.
  */
 export declare const RESERVED_EMITTED_NAMES: readonly string[];
 export interface ResourceNamedType {
@@ -63,15 +13,6 @@ export interface ResourceNamedType {
 export declare const RESOURCE_NAMED_TYPES: readonly ResourceNamedType[];
 /** The named types a Resource with `operations` gets: those whose operation it advertises. */
 export declare function namedTypesOf(operations: unknown): readonly ResourceNamedType[];
-/**
- * The client's own members, which a Resource property must not shadow: `tx` and
- * `transaction` (reserved whether or not the contract advertises transactions, so
- * a property never moves with `transactions`), `then` — a client with a `then` is
- * a thenable, and `await` would call it — and every name `Object.prototype`
- * carries in ES2022, `constructor` among them. Fixed here, not read from the
- * running Node, so the output never moves with the generator's runtime. In UTF-16
- * code-unit order.
- */
 export declare const CLIENT_MEMBER_NAMES: readonly string[];
 /** One Contract name and the TypeScript identifier the tree declares it under. */
 export interface EmittedName {
@@ -80,7 +21,6 @@ export interface EmittedName {
     /** The identifier the emitted TypeScript declares; `contractName` unless renamed. */
     readonly identifier: string;
 }
-/** A Resource's property on the client: its contract name unless a member owns it. */
 export interface EmittedProperty {
     /** The name the server uses. Never renamed. */
     readonly contractName: string;
@@ -95,11 +35,6 @@ export interface EmittedNames {
     readonly resources: readonly EmittedName[];
     /** Each Resource's client property, in UTF-16 code-unit order of `contractName`. */
     readonly properties: readonly EmittedProperty[];
-    /**
-     * One line per renamed name, in UTF-16 code-unit order of the contract name, a
-     * Resource before an enum of the same name. Returned, never printed: the caller
-     * that owns the terminal decides where diagnostics go.
-     */
     readonly warnings: readonly string[];
 }
 /** Whether `text` is an IdentifierName — the rule above, for every emitter. */
@@ -116,10 +51,4 @@ export declare class GeneratedNameError extends Error {
     readonly name = "GeneratedNameError";
     constructor(problems: readonly string[]);
 }
-/**
- * `value` as an object-literal key that makes it an OWN property: bare when it is
- * an IdentifierName (reserved words included — a property name may be one), a
- * string literal otherwise — except `__proto__`, which bare or quoted sets the
- * prototype instead (measured on Node 24), so it is computed.
- */
 export declare function ownPropertyKey(value: string): string;

package/dist/emit/named-type.emitter.d.ts

@@ -2,24 +2,4 @@ import type { ClientContract } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 import { type EmittedNames } from "./name.deriver.js";
-/**
- * Each is an ALIAS over the copied derivation — `ResourceRecord` /
- * `ResourceArgument`, declared in `client.ts` — never a walked-out literal type:
- * the derivation stays one. A Resource is addressed by its contract name, a string
- * literal type, so nothing here depends on how it was renamed.
- *
- * The module declares no name but these, and uses no global type a Resource named
- * like one could shadow.
- *
- * TypeScript resolves a type alias where it is DECLARED, so a consumer pays for
- * every Resource's named types whether it uses them or not — measured ≈2,800
- * instantiations per Resource. Emitted as `types.d.ts`, they cost nothing under
- * `skipLibCheck: true` (the common default) until used, and the same as a `.ts`
- * under `skipLibCheck: false`. It is live, not a dead declaration: nothing else
- * declares these names, and no `types.ts` sits beside it to shadow it
- * (`client-tree.emitter.spec.ts`). Only types are declared here, so nothing a
- * bundler needs lives in it; `AvClient.ts` re-exports it by `export type *`
- * (TypeScript 5.0, inside the 5.5 peer floor) — an `export *` would survive to the
- * JavaScript and import a `types.js` that does not exist.
- */
 export declare function emitNamedTypesModule(contract: ClientContract, names: EmittedNames, style: ClientModuleStyle): EmittedModule;

package/dist/emit/runtime.emitter.d.ts

@@ -2,59 +2,9 @@ import { type ClientContract } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
-/**
- * The runtime modules the generated client carries: `metadata.ts`, the
- * framework `Decimal`, the outcome codes and error classes, and the transport
- * here; the scalar codec in `scalar.codec.ts`.
- */
-/**
- * Bundled with the client and imported from nothing: its public type is its own,
- * never an ORM's.
- *
- * It holds the decimal string it was made from, digit for digit, and does no
- * arithmetic — the surface is core's `Decimal` (a string constructor and
- * `toString`) plus `toJSON`, so a value means the same on both sides of the wire.
- * A proven decimal library may later sit behind it; none is needed to carry
- * digits.
- *
- * No `equals`, no arithmetic. The request body never relies on it:
- * `serializeWireBody` refuses an unencoded Decimal regardless, so a value the
- * codec did not encode cannot slip onto the wire through `toJSON`.
- *
- * The grammar is core's `Decimal` grammar, read from `AvProtocol.scalarFormats`
- * and emitted by value. Unlike core's, the constructor refuses a non-string
- * outright: a pattern test coerces its argument, so `5` would otherwise pass as
- * `"5"` and be kept as a number.
- */
 export declare function emitDecimalModule(): EmittedModule;
-/**
- * `metadata.ts` — what this client was generated against: the ClientContract hash
- * and the protocol version, and the resolved entrypoint as the client's default.
- * Nothing else: no driver, no timestamp, no generator version, no host path —
- * anything a re-run over the same inputs could change breaks byte-equality. The
- * entrypoint is an input like the contract: changing it regenerates different
- * bytes and leaves the hash alone, and it never carries credentials.
- *
- * The hash and the version are what every operation request sends, from
- * `runtime/transport.ts`; all three are internal — `AvClient.ts` exports none.
- */
 export declare function emitMetadataModule(protocol: ClientContract["protocol"], entrypoint: ClientEntrypoint): EmittedModule;
-/**
- * The `FrameworkError` subclasses the generated runtime declares, in UTF-16
- * code-unit order — names the root namespace reserves (`name.deriver.ts`).
- */
 export declare const FRAMEWORK_ERROR_CLASS_NAMES: readonly string[];
 export declare function errorsModuleExports(): readonly string[];
-/**
- * Exported beyond what `AvClient.ts` re-exports: the two arrays,
- * `OperationErrorCode` and `frameworkErrorOf`, which `runtime/transport.ts` reads.
- */
 export declare function emitErrorsModule(): EmittedModule;
-/**
- * It reads no capability and no operation descriptor; the caller names the
- * operation.
- *
- * Fetch and AbortSignal are the platform's, reached through the structural types
- * below so the module compiles with neither DOM nor Node types.
- */
 export declare function emitTransportModule(style: ClientModuleStyle): EmittedModule;

package/dist/emit/runtime.emitter.js

@@ -54,7 +54,7 @@ export function emitMetadataModule(protocol, entrypoint) {
 const FRAMEWORK_ERROR_CLASSES = {
     AuthError: "The caller is not authenticated, or is not permitted to run the operation.",
     ConflictError: "The operation conflicted with stored state, and nothing was written. A2008 fails the same way if sent again; A2013 and A2014 may succeed if sent again, and no retry is automatic.",
-    ContractMismatchError: "This client was generated against a ClientContract other than the one the server serves (invariant 15). Regenerate it with `avclient generate`.",
+    ContractMismatchError: "This client was generated against a ClientContract other than the one the server serves. Regenerate it with `avclient generate`.",
     InternalError: "The server failed. Nothing in its cause is actionable; the diagnostics are in the server's logs.",
     NotFoundError: "A strict unique target does not exist.",
     ProtocolError: "The request was not one the server could route or interpret: an unknown Resource or operation, a protocol version it does not speak, or a body, media type, size or method it refuses.",
@@ -250,18 +250,17 @@ import {
  *
  * # A stale client
  *
- * A client generated against an older ClientContract must fail hard and say to
- * regenerate (cross-phase invariant 15). The server is what knows: it checks the
- * identity this transport sends BEFORE it routes, so a request
- * under a stale hash — to an operation the deployment still advertises, or to
- * one it no longer does — is answered 409 A2005, which throws
- * ContractMismatchError naming the remedy. Nothing here guesses: a response that
- * is not a framework envelope — a host's own 404 for a path it does not mount —
- * is a TransportError, and names no remedy, because nothing in it says this
- * client is stale.
+ * A client generated against an older ClientContract fails hard and says to
+ * regenerate. The server checks the identity this transport sends before it
+ * routes, so a request under a stale hash, to an operation the deployment still
+ * advertises or to one it no longer does, is answered 409 A2005, which throws
+ * ContractMismatchError naming the remedy. A response that is not a framework
+ * envelope, such as a host's own 404 for a path it does not mount, is a
+ * TransportError and names no remedy, because nothing in it says this client is
+ * stale.
  */
 
-/** The wire prefix of the identity headers, in one place: its freeze is a one-line change. */
+/** The wire prefix of the identity headers, in one place. */
 const WIRE_PREFIX = ${JSON.stringify(IDENTITY_HEADERS.prefix)};
 
 /** The headers the framework owns on every operation request. */
@@ -333,12 +332,7 @@ export interface CallOptions {
 
 type SuccessCode = Exclude<OperationCode, OperationErrorCode>;
 
-/**
- * A framework envelope, read and checked — told apart by \`outcome\`, a string
- * discriminant, rather than by \`cause\` being null: without \`strictNullChecks\`
- * (\`strict: false\`, which Next.js writes into a tsconfig it creates) null
- * narrows nothing, and the client must type-check under the consumer's settings.
- */
+/** A framework envelope, read and checked, told apart by \`outcome\`. */
 type Envelope =
 	| { readonly outcome: "data"; readonly code: SuccessCode; readonly data: unknown }
 	| { readonly outcome: "failure"; readonly code: OperationErrorCode; readonly cause: Cause };
@@ -453,8 +447,7 @@ function decoded<T>(operation: string, status: number, decode: () => T): T {
 
 /**
  * Settles one response by the protocol's rule: the envelope's data, still in wire form,
- * which the caller decodes by the decode table. A decode failure's mode is
- * decided:
+ * which the caller decodes by the decode table.
  * A scalar in \`data\` that fails to decode, inside an otherwise valid envelope, throws TransportError
  * — not a FrameworkError, because the server reported no failure; the response is
  * one this client cannot read, which is what TransportError means.

package/dist/emit/scalar.codec.d.ts

@@ -1,45 +1,6 @@
 import { AvProtocol } from "@aventara/core/protocol";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
-/**
- * # Keyed on `BuiltInScalar` alone
- *
- * So the codec reads no field, no capability and no operation descriptor — the
- * caller names the scalar, and the codec converts one value.
- *
- * One source for the scalar set: the emitted `BuiltInScalar` union and the emitted
- * table both come from core's `BUILT_IN_SCALARS`, in its order, and {@link
- * SCALAR_CODEC_SOURCES} is a mapped type over core's `BuiltInScalar` — a scalar
- * the protocol adds is a compile error here until its codec is written.
- *
- * # Untyped on purpose
- *
- * Every codec is `unknown → unknown`, checked at runtime. When the boundary lifts,
- * the methods that call these codecs carry the types.
- *
- * # What the emitted codec promises
- *
- * - `null` passes through both: it is explicit, and whether a field admits it is
- *   the field's nullability, which the server validates.
- * - `undefined` is never a value: an optional property is omitted, and
- *   `serializeWireBody` strips every `undefined` property before transport.
- * - A value outside a scalar's runtime or wire form is refused with a `TypeError`
- *   naming the scalar — never coerced. A `json` value carrying a `BigInt`, `Date`,
- *   `Uint8Array`, `Decimal`, function, symbol or `undefined` is refused, with the
- *   path to the offending member.
- * - Wire grammars are the server's, read from core — `AvProtocol.scalarFormats` —
- *   and emitted by value as regular-expression literals ({@link
- *   wireGrammarLiteral}): bigint `-?(0|[1-9]\d*)`, datetime exactly
- *   `toISOString()`'s form, bytes RFC 4648 base64 with the standard alphabet and
- *   padding, canonical. Base64 is written out rather than delegated to
- *   `atob`/`btoa`, so the module needs neither a DOM nor a Node global.
- */
-/**
- * The regular-expression literal of one of core's wire grammars, as emitted
- * source: `/<source>/`, the grammar's own text. The sources are anchored,
- * flagless and carry a `/` only inside a character class, which core's
- * `av-protocol.spec.ts` pins, so the literal is the grammar itself.
- */
 export declare function wireGrammarLiteral(scalar: keyof typeof AvProtocol.scalarFormats): string;
 /**
  * `runtime/codec.ts`: the `BuiltInScalar` union and the codec table in core's

package/dist/emit/transaction.emitter.d.ts

@@ -1,9 +1,3 @@
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
-/**
- * The transaction builder and runner: `runtime/fingerprint.ts` and
- * `runtime/transaction.ts`, emitted iff the ClientContract advertises
- * `interactive` transactions — `client.ts` wires them to `avClient.tx` and
- * `avClient.transaction`.
- */
 export declare function emitTransactionModules(style: ClientModuleStyle): readonly EmittedModule[];

package/dist/emit/transaction.emitter.js

@@ -12,8 +12,7 @@ const FINGERPRINT_MODULE = `/**
  * The v1 operation fingerprint: RFC 8785 canonical JSON of
  * { resource, family, variant, args } over the WIRE-form arguments, its UTF-8
  * bytes hashed with SHA-256, the first 16 bytes in base64url, prefixed "fp1:".
- * Dependency-free, and pinned byte for byte to core's
- * computeOperationFingerprint.
+ * Dependency-free; the same bytes the server computes.
  */
 
 /** One plan node, its arguments already in wire form. */
@@ -216,8 +215,7 @@ import { fingerprintOf } from ${from("./fingerprint")};
 import { type CallOptions, executePlan, type TransportConnection } from ${from("./transport")};
 
 /**
- * The deferred transaction builder and runner, as core assembles a plan
- * in process (transaction-plan-assembler.ts): \`avClient.tx\` defers an operation
+ * The deferred transaction builder and runner: \`avClient.tx\` defers an operation
  * into a handle — pure data, no request — and \`avClient.transaction\` binds a
  * list of handles into one transaction plan, sends it once, and resolves one
  * result per handle in list order. A handle has no connection, so any client of
@@ -386,7 +384,7 @@ export async function runTransaction(
 		}
 	}
 
-	// Bound lazily, as core binds them: a node's references need their source's
+	// Bound lazily: a node's references need their source's
 	// fingerprint, so each node is built once, on first need, wherever its source
 	// stands in the list — the server, not this client, refuses a later one.
 	const nodes = new Map<number, PlanNode>();

package/dist/generate.d.ts

@@ -3,21 +3,6 @@ import { type ProcessEnvInput } from "./config/env.cascade.js";
 import type { ContractFetch } from "./contract/contract.fetcher.js";
 import { type EmittedFilePath } from "./emit/emitted-tree.interface.js";
 import type { OutputCheck, TypeScriptResolver } from "./output/output.validator.js";
-/**
- * The cascade is a returned record, never written into `process.env`: the config
- * reaches it through `env("NAME")`.
- *
- * Output goes to `generateAt`: `AvClient.ts` and `generated/`, nothing else there
- * touched. Content in those two the generator did not produce is never overwritten
- * unasked: the run returns `ForeignOutputContent` instead, and the caller decides.
- *
- * Every failure is thrown, every diagnostic that is not a failure is returned:
- * this function prints nothing and asks nothing. `cli.ts` owns the terminal. A
- * refusal raised after a warning (`OutputWriteError`) carries the warnings raised
- * before it, and so does `ForeignOutputContent`; a defect is rethrown as itself,
- * its warnings kept beside it (`warningsRaisedBeforeDefect`). No run's warnings
- * are lost because it stopped.
- */
 export interface ClientGenerationInput {
     /** The project directory: where `framework.client.ts` and the `.env` files are. */
     readonly directory: string;
@@ -30,9 +15,7 @@ export interface ClientGenerationInput {
      * written.
      */
     readonly overrideForeign?: boolean;
-    /** Injected for tests; the platform `fetch` otherwise. */
     readonly fetch?: ContractFetch;
-    /** The `typescript` optional peer; the installed one by default. */
     readonly resolveTypeScript?: TypeScriptResolver;
 }
 export interface ClientGenerated {
@@ -43,11 +26,6 @@ export interface ClientGenerated {
     readonly files: readonly EmittedFilePath[];
     /** How deeply the output was validated before it replaced the previous one. */
     readonly checked: OutputCheck;
-    /**
-     * The deployment answered `304` — the ClientContract is the one the previous
-     * output was generated against — and the output was still replaced, because this
-     * generator or this entrypoint emits other bytes.
-     */
     readonly contractUnchanged: boolean;
     /**
      * Everything the run has to say without failing, in a fixed order: the
@@ -56,12 +34,6 @@ export interface ClientGenerated {
      */
     readonly warnings: readonly string[];
 }
-/**
- * The run found content in `AvClient.ts` or `generated/` the generator did not
- * produce, and stopped before writing anything. Whoever owns the terminal asks;
- * `proceed` writes the emission already made — no second fetch — overwriting or
- * removing exactly `foreign`, through the same temp → validate → replace path.
- */
 export interface ForeignOutputContent {
     readonly kind: "foreign-content";
     readonly generateAt: AbsolutePath;
@@ -79,11 +51,6 @@ export interface ForeignOutputContent {
     readonly warnings: readonly string[];
     proceed(): Promise<ClientGenerated>;
 }
-/**
- * The deployment serves the ClientContract the output was generated against, and
- * this generator, with this entrypoint, emits exactly the bytes already there:
- * nothing was written.
- */
 export interface ClientUpToDate {
     readonly kind: "up-to-date";
     readonly generateAt: AbsolutePath;

package/dist/index.d.ts

@@ -1,8 +1,4 @@
-/**
- * This package's version, read from its own manifest — the `package.json` every
- * tarball carries beside `dist/` — so a release's `changeset version` is the one
- * statement of it.
- */
+/** The version of `@aventara/client`. */
 export declare const AVENTARA_CLIENT_GENERATOR_VERSION: string;
 export type { ClientConfigInput, ConfigValue, EnvReference, } from "./config/client-config.interface.js";
 export { defineClientConfig, env } from "./config/config.resolver.js";

package/dist/init/client-config.template.d.ts

@@ -1,11 +1,3 @@
-/**
- * `file` names it in its own comment line: the `framework.client.ts` it writes, or
- * the project's own config of another extension, which init reuses rather than add
- * a second (two configs make `avclient generate` refuse). A `.cjs` one is written
- * in CommonJS — `require` and `module.exports` — the syntax its extension
- * promises; every other one in ES module syntax, which the loader reads in any of
- * them.
- */
 export declare function clientConfigSource(input: {
     readonly entrypoint: string;
     readonly envVar: string | undefined;

package/dist/init/client-init.orchestrator.js

@@ -2,7 +2,9 @@ import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { runGenerate } from "../cli/generate.command.js";
 import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
+import { resolveModuleStyle } from "../config/module-style.resolver.js";
 import { ContractTransportError } from "../contract/contract.fetcher.js";
+import { CLIENT_ENTRY_FILE } from "../emit/emitted-tree.interface.js";
 import { ClientInitNotConfirmedError, ClientInitStepError, } from "./client-init.errors.js";
 import { GENERATE_SCRIPT, planClientInit } from "./client-init.planner.js";
 import { resolveClientInitAnswers } from "./client-init.questions.js";
@@ -26,6 +28,11 @@ export async function runClientInit(command, io) {
         detectedPackageManager: project.lockfile ??
             (userAgent?.split("/")[0] === "pnpm" ? "pnpm" : "npm"),
     });
+    const generateAt = path.resolve(io.cwd, answers.generateAt);
+    resolveModuleStyle({
+        generateAt,
+        entryFile: path.join(generateAt, CLIENT_ENTRY_FILE),
+    });
     const clientVersion = ownVersion();
     const plan = planClientInit({ project, answers, clientVersion });
     if (plan.conflicts.length > 0 && !command.yes) {

package/dist/init/client-init.planner.d.ts

@@ -14,6 +14,5 @@ export type ClientInitPlan = {
 export declare function planClientInit(input: {
     readonly project: ClientProject;
     readonly answers: ClientInitAnswers;
-    /** This package's own version: the devDependency is pinned to it exactly. */
     readonly clientVersion: string;
 }): ClientInitPlan;

package/dist/init/client-init.planner.js

@@ -47,6 +47,16 @@ export function planClientInit(input) {
             replaced[at] = line;
         }
         add(".env", before, `${kept.join("\n")}\n`, `${replaced.join("\n")}\n`);
+        const ignore = project.read(".gitignore");
+        const ignored = (ignore ?? "")
+            .split("\n")
+            .some((line) => line.trim() === ".env");
+        if (!ignored) {
+            const appended = ignore === undefined || ignore === ""
+                ? ".env\n"
+                : `${ignore.endsWith("\n") ? ignore : `${ignore}\n`}.env\n`;
+            add(".gitignore", ignore, appended, appended);
+        }
     }
     const manifest = (replace) => {
         const parsed = JSON.parse(project.manifestText);