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

package/dist/emit/scalar.codec.js

@@ -1,58 +1,6 @@
 import { BUILT_IN_SCALARS } from "@aventara/core";
 import { AvProtocol } from "@aventara/core/protocol";
-/**
- * The scalar codecs of §6.2, as the generated client carries them in
- * `runtime/codec.ts`.
- *
- * # Keyed on `BuiltInScalar` alone
- *
- * §6.2's table is fixed by PROTOCOL VERSION, not carried in the Contract: the
- * scalar registry is a key registry (`{ builtin: true }`) and scalars carry no
- * position qualifier [M10]. So the codec reads no field, no capability and no
- * operation descriptor — the caller names the scalar, and the codec converts one
- * value. Walking a Resource's fields to find which scalar a value is belongs to
- * the method surface, below Phase 12-partial's boundary.
- *
- * 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. The TYPE of a scalar's
- * application form and wire form is Phase 9's `ScalarValueType` and its `Forms`
- * maps (architect decision Q3 = 3a); declaring a second scalar→type map here
- * would be a parallel source of that fact. When the boundary lifts, the methods
- * that call these codecs carry the types.
- *
- * # What the emitted codec promises
- *
- * - `encodeScalar`/`decodeScalar` convert between the generated runtime value
- *   and the JSON wire value of §6.2, and `decodeScalar(s, encodeScalar(s, v))`
- *   equals `v` for every scalar.
- * - `null` passes through both: it is explicit, and whether a field admits it is
- *   the field's nullability, which the server validates (§6.2).
- * - `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 (§6.2), with the path to the offending member.
- * - Wire grammars are the server's, read from core — `AvProtocol.scalarFormats`
- *   (C2, R7) — 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 (zero pad bits, like the server's — C1). Base64 is written
- *   out rather than delegated to `atob`/`btoa`, so the module needs neither a DOM
- *   nor a Node global (§15.7, U5).
- */
-/**
- * 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.
- */
+import { moduleSpecifierWriter, } from "./module-style.interface.js";
 export function wireGrammarLiteral(scalar) {
     return `/${AvProtocol.scalarFormats[scalar]}/`;
 }
@@ -99,11 +47,12 @@ const SCALAR_CODEC_SOURCES = {
         decode: `(wire) => copyJson("wire", wire, [], new Set())`,
     },
 };
-const CODEC_MODULE_HEAD = `import { Decimal } from "./decimal.js";
-import type { FieldDecoding } from "./descriptor.js";
+function codecModuleHead(from) {
+    return `import { Decimal } from ${from("./decimal")};
+import type { FieldDecoding } from ${from("./descriptor")};
 
 /**
- * The scalar codecs of Aventara protocol version 1 (§6.2): one per built-in
+ * The scalar codecs of Aventara protocol version 1: one per built-in
  * scalar, converting between the generated runtime value and the JSON wire value.
  * A value is never wrapped per field — the Contract names the scalar, so the
  * caller says which scalar a value is.
@@ -114,6 +63,7 @@ import type { FieldDecoding } from "./descriptor.js";
  * wire form is refused with a TypeError, never coerced.
  */
 `;
+}
 const CODEC_MODULE_BODY = `
 interface ScalarCodec {
 	/** The generated runtime value to its JSON wire value. */
@@ -360,7 +310,7 @@ export function decodeScalar(scalar: BuiltInScalar, wire: unknown): unknown {
 /**
  * The JSON text of a request body whose scalars are already encoded. Every
  * undefined property is stripped, at every depth — an optional property is
- * omitted, never sent — and null is kept as the explicit value it is (§6.2).
+ * omitted, never sent — and null is kept as the explicit value it is.
  * Anything else that is not JSON-safe is refused rather than coerced: it means a
  * value escaped its scalar codec.
  */
@@ -370,7 +320,7 @@ export function serializeWireBody(body: unknown): string {
 
 /**
  * An operation's arguments with every scalar in its wire form, read off each
- * value's runtime class (Phase 12-rest Q15 = a, the server's encode mirrored): a
+ * value's runtime class: a
  * bigint, a Date, a Decimal or a Uint8Array is encoded wherever it stands — a
  * filter operand, a data value, a cursor — and plain objects and arrays are
  * walked. Every other value is left for serializeWireBody, which refuses what is
@@ -417,7 +367,7 @@ export type DecodeTable = {
 
 /**
  * An operation's result with every scalar in its runtime form, read off the decode
- * table (P1): a number (a count), null, and the data of a Resource the table
+ * table: a number (a count), null, and the data of a Resource the table
  * does not name pass through; a list is a list of
  * records, anything else is one record of \`resource\`. In a record, a field the
  * table names is revived — each item of a list field — a relation recurses with
@@ -426,7 +376,7 @@ export type DecodeTable = {
  * \`{ count }\` — the three shapes the derivation gives it.
  *
  * @throws TypeError when a value is not the wire form its field's scalar takes —
- *   which the transport answers as a TransportError (architect, 2026-10-04).
+ *   which the transport answers as a TransportError.
  */
 export function decodeResult(table: DecodeTable, resource: string, value: unknown): unknown {
 	// A Resource the table does not name has nothing to revive: its data passes.
@@ -474,13 +424,7 @@ function decodeField(table: DecodeTable, decoding: FieldDecoding, value: unknown
 	return value;
 }
 `;
-/**
- * `runtime/codec.ts`: the `BuiltInScalar` union and the codec table in core's
- * `BUILT_IN_SCALARS` order, the helpers the codecs share, and the three
- * functions the generated transport calls. Nothing here is re-exported from the
- * tree's `AvClient.ts`: the codec is the runtime's, not the consumer's.
- */
-export function emitScalarCodecModule() {
+export function emitScalarCodecModule(style) {
     const union = BUILT_IN_SCALARS.map((scalar) => `\t| ${JSON.stringify(scalar)}`).join("\n");
     const table = BUILT_IN_SCALARS.map((scalar) => {
         const { encode, decode } = SCALAR_CODEC_SOURCES[scalar];
@@ -488,8 +432,8 @@ export function emitScalarCodecModule() {
     }).join("\n");
     return {
         path: "runtime/codec.ts",
-        source: CODEC_MODULE_HEAD +
-            "\n/** The built-in scalars of the protocol (§6.1). */\n" +
+        source: codecModuleHead(moduleSpecifierWriter(style)) +
+            "\n/** The built-in scalars of the protocol. */\n" +
             `export type BuiltInScalar =\n${union};\n` +
             CODEC_MODULE_BODY +
             "\nconst SCALAR_CODECS: { readonly [S in BuiltInScalar]: ScalarCodec } = {\n" +

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

@@ -1,17 +1,9 @@
 import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
 /**
- * The transaction builder and runner (§14; Phase 12-rest S6, Q13, Q14, P3):
- * `runtime/fingerprint.ts` and `runtime/transaction.ts`, emitted iff the
- * ClientContract advertises `interactive` transactions (P3) — `client.ts` wires
- * them to `avClient.tx` and `avClient.transaction`.
- *
- * Both are fixed by protocol version, not by the Contract, and mirror core's own
- * seams: the plan is assembled as `transactions/transaction-plan-assembler.ts`
- * assembles it — handles as pure data, a `$ref` bound lazily to its source
- * handle's position in the list it runs with, the two refusals core answers in
- * process (Q13) — and each node's fingerprint is core's
- * `computeOperationFingerprint` over the node's WIRE arguments (§14.4), computed
- * here by an emitted JCS and SHA-256 (Q14: `crypto.subtle` is absent from a
- * browser page served over plain http from a non-localhost host).
+ * 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(): readonly EmittedModule[];
+export declare function emitTransactionModules(style: ClientModuleStyle): readonly EmittedModule[];

package/dist/emit/transaction.emitter.js

@@ -1,29 +1,18 @@
-/**
- * The transaction builder and runner (§14; Phase 12-rest S6, Q13, Q14, P3):
- * `runtime/fingerprint.ts` and `runtime/transaction.ts`, emitted iff the
- * ClientContract advertises `interactive` transactions (P3) — `client.ts` wires
- * them to `avClient.tx` and `avClient.transaction`.
- *
- * Both are fixed by protocol version, not by the Contract, and mirror core's own
- * seams: the plan is assembled as `transactions/transaction-plan-assembler.ts`
- * assembles it — handles as pure data, a `$ref` bound lazily to its source
- * handle's position in the list it runs with, the two refusals core answers in
- * process (Q13) — and each node's fingerprint is core's
- * `computeOperationFingerprint` over the node's WIRE arguments (§14.4), computed
- * here by an emitted JCS and SHA-256 (Q14: `crypto.subtle` is absent from a
- * browser page served over plain http from a non-localhost host).
- */
-export function emitTransactionModules() {
+import { moduleSpecifierWriter, } from "./module-style.interface.js";
+export function emitTransactionModules(style) {
     return [
         { path: "runtime/fingerprint.ts", source: FINGERPRINT_MODULE },
-        { path: "runtime/transaction.ts", source: TRANSACTION_MODULE },
+        {
+            path: "runtime/transaction.ts",
+            source: transactionModuleSource(moduleSpecifierWriter(style)),
+        },
     ];
 }
 const FINGERPRINT_MODULE = `/**
- * The v1 operation fingerprint (§14.4): RFC 8785 canonical JSON of
+ * 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 (Q14), and pinned byte for byte to core's
+ * Dependency-free, and pinned byte for byte to core's
  * computeOperationFingerprint.
  */
 
@@ -220,18 +209,19 @@ function base64Url(bytes: Uint8Array): string {
 	return text;
 }
 `;
-const TRANSACTION_MODULE = `import { encodeArguments, serializeWireBody } from "./codec.js";
-import { type Cause, type FrameworkError, frameworkErrorOf } from "./errors.js";
-import { fingerprintOf } from "./fingerprint.js";
-import { type CallOptions, executePlan, type TransportConnection } from "./transport.js";
+function transactionModuleSource(from) {
+    return `import { encodeArguments, serializeWireBody } from ${from("./codec")};
+import { type Cause, type FrameworkError, frameworkErrorOf } from ${from("./errors")};
+import { fingerprintOf } from ${from("./fingerprint")};
+import { type CallOptions, executePlan, type TransportConnection } from ${from("./transport")};
 
 /**
- * The deferred transaction builder and runner (§14), as core assembles a plan
+ * The deferred transaction builder and runner, as core assembles a plan
  * in process (transaction-plan-assembler.ts): \`avClient.tx\` defers an operation
  * into a handle — pure data, no request — and \`avClient.transaction\` binds a
- * list of handles into the one §14.2 plan, sends it once, and resolves one
+ * 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
- * this generated tree may run it (Q13, a plan ruling).
+ * this generated tree may run it.
  */
 
 /** What a handle defers. */
@@ -250,7 +240,7 @@ interface Placeholder {
 
 type MutableRecord = Record<string, unknown>;
 
-/** One §14.2 wire node, its arguments in wire form. */
+/** One wire node of a transaction plan, its arguments in wire form. */
 interface PlanNode {
 	readonly resource: string;
 	readonly family: string;
@@ -259,7 +249,7 @@ interface PlanNode {
 	readonly fingerprint: string | null;
 }
 
-/** One DA-3 container: a mutation-data record and its path inside the arguments. */
+/** One reference container: a mutation-data record and its path inside the arguments. */
 interface Container {
 	readonly path: readonly (string | number)[];
 	readonly record: Readonly<Record<string, unknown>>;
@@ -276,7 +266,7 @@ function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown
 	return prototype === Object.prototype || prototype === null;
 }
 
-/** The argument keys holding DA-3 reference positions: the top-level mutation data. */
+/** The argument keys holding reference positions: the top-level mutation data. */
 function referenceKeys(family: string): readonly string[] {
 	return family === "create" || family === "update" ? ["data"] : family === "upsert" ? ["create", "update"] : [];
 }
@@ -294,7 +284,7 @@ function containers(family: string, args: unknown): readonly Container[] {
 	});
 }
 
-/** \`args\` with each DA-3 container replaced by \`rebuild\`, cloning only the containing path. */
+/** \`args\` with each reference container replaced by \`rebuild\`, cloning only the containing path. */
 function replaceContainers(family: string, args: unknown, rebuild: (container: Container) => MutableRecord): unknown {
 	if (!isPlainRecord(args)) {
 		return args;
@@ -312,7 +302,7 @@ function replaceContainers(family: string, args: unknown, rebuild: (container: C
 }
 
 /**
- * Defers one operation into a handle (§14.1): nothing is sent. Its DA-3
+ * Defers one operation into a handle: nothing is sent. Its reference
  * containers are copied now, so a later change to the caller's data cannot move
  * a reference — and a handle can reference only handles built before it.
  */
@@ -345,8 +335,8 @@ function entryRefusal(operation: number, message: string): FrameworkError {
 
 /**
  * Binds \`steps\` into the plan, sends it once, and resolves one decoded result per
- * step (§14.1). Refused before anything is sent, with what core answers in
- * process (Q13): a list that is not one, an entry that is not a handle of this
+ * step. Refused before anything is sent, with what core answers in
+ * process: a list that is not one, an entry that is not a handle of this
  * generated client, one handle twice (ValidationError A2004 / V1001 at
  * ["operation"]); a reference to a handle not in the list (ValidationError A2007 /
  * V1010 at its \`$ref\`).
@@ -436,3 +426,4 @@ export async function runTransaction(
 	);
 }
 `;
+}

package/dist/generate.d.ts

@@ -4,35 +4,19 @@ 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";
 /**
- * §15.3's generation pipeline, as one call (S7b):
+ * The cascade is a returned record, never written into `process.env`: the config
+ * reaches it through `env("NAME")`.
  *
- *   load env + config            S2  — `.env` cascade, then `framework.client.ts`
- *   → GET <entrypoint>/_contract S3 — conditional on the output's carrier (Q6):
- *     `304` and identical bytes → "up to date", nothing written
- *   → validate protocol support, ClientContract structure, advertised hash   S3
- *   → emit                       S4–S6 — enums, metadata, codecs, errors, transport
- *   → emit into a temporary directory, validate, atomically replace          S7
- *
- * Only what exists above Phase 12-partial's boundary is emitted: no Resource
- * method, no projection, no transaction builder — those read capabilities and
- * operation descriptors (plan §1).
- *
- * The cascade is resolved BEFORE the config is evaluated, as §15.2 orders it, so
- * an unreadable or malformed `.env` is reported even when the config would also
- * fail. The cascade is a returned record, never written into `process.env` (S2):
- * the config reaches it through `env("NAME")`.
- *
- * Output goes to `generateAt`: `AvClient.ts` and `generated/`, nothing else
- * there touched (architect, 2026-10-04). Content in those two the generator did
- * not produce is never overwritten unasked: the run returns
- * `ForeignOutputContent` instead, and the caller decides.
+ * 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.
+ * 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. */
@@ -48,7 +32,7 @@ export interface ClientGenerationInput {
     readonly overrideForeign?: boolean;
     /** Injected for tests; the platform `fetch` otherwise. */
     readonly fetch?: ContractFetch;
-    /** The `typescript` optional peer; the installed one by default (Q6). */
+    /** The `typescript` optional peer; the installed one by default. */
     readonly resolveTypeScript?: TypeScriptResolver;
 }
 export interface ClientGenerated {
@@ -61,8 +45,8 @@ export interface ClientGenerated {
     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 (Q6).
+     * output was generated against — and the output was still replaced, because this
+     * generator or this entrypoint emits other bytes.
      */
     readonly contractUnchanged: boolean;
     /**
@@ -74,10 +58,9 @@ export interface ClientGenerated {
 }
 /**
  * The run found content in `AvClient.ts` or `generated/` the generator did not
- * produce, and stopped before writing anything (architect, 2026-10-04). 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.
+ * 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";
@@ -98,8 +81,8 @@ export interface ForeignOutputContent {
 }
 /**
  * The deployment serves the ClientContract the output was generated against, and
- * this generator, with this entrypoint, emits exactly the bytes already there
- * (Phase 12-rest Q6): nothing was written.
+ * this generator, with this entrypoint, emits exactly the bytes already there:
+ * nothing was written.
  */
 export interface ClientUpToDate {
     readonly kind: "up-to-date";

package/dist/generate.js

@@ -3,39 +3,23 @@ import path from "node:path";
 import { loadClientConfigFile } from "./config/config.loader.js";
 import { resolveClientConfig } from "./config/config.resolver.js";
 import { resolveEnvCascade, } from "./config/env.cascade.js";
+import { resolveModuleStyle } from "./config/module-style.resolver.js";
 import { loadClientContractSince } from "./contract/contract.loader.js";
 import { emitClientTree } from "./emit/client-tree.emitter.js";
 import { parseContractCarrier } from "./emit/contract-carrier.emitter.js";
-import { GENERATED_DIRECTORY, } from "./emit/emitted-tree.interface.js";
+import { CLIENT_ENTRY_FILE, CONTRACT_CARRIER_MODULE, GENERATED_DIRECTORY, } from "./emit/emitted-tree.interface.js";
 import { findForeignOutputContent, OutputWriteError, ownedOutputMatches, precedeDefect, writeClientOutput, } from "./output/output.writer.js";
-/**
- * The ClientContract the output in `generateAt` holds, when its owned entries
- * are intact — nothing in them the generator did not produce — and its carrier
- * parses back and re-verifies (Q4, Q6); otherwise undefined, and the GET is
- * unconditional. A failure to inspect is no carrier: the run's own inspection,
- * later, reports it.
- */
 async function storedContract(generateAt) {
     try {
         if ((await findForeignOutputContent(generateAt)).length > 0) {
             return undefined;
         }
-        return await parseContractCarrier(await readFile(path.join(generateAt, GENERATED_DIRECTORY, "contract.ts"), "utf8"));
+        return await parseContractCarrier(await readFile(path.join(generateAt, GENERATED_DIRECTORY, CONTRACT_CARRIER_MODULE), "utf8"));
     }
     catch {
         return undefined;
     }
 }
-/**
- * Generates the client the project's config describes — or, when content the
- * generator did not produce stands in its way and `overrideForeign` is not set,
- * says what it is and writes nothing.
- *
- * @throws a refusal (`EnvFileError`, `ClientConfigError`, `ContractTransportError`,
- *   `ContractProtocolError`, `GeneratedNameError`, `OutputWriteError`) whose
- *   message is the whole diagnosis; the previous output is intact. Anything else
- *   is a defect.
- */
 export async function generateClient(input) {
     const cascade = resolveEnvCascade({
         directory: input.directory,
@@ -47,10 +31,20 @@ export async function generateClient(input) {
         cascade,
         configDirectory: path.dirname(loaded.file),
     });
+    const style = resolveModuleStyle({
+        generateAt: config.generateAt,
+        entryFile: path.join(config.generateAt, CLIENT_ENTRY_FILE),
+        ...(config.tsconfigFile === undefined
+            ? {}
+            : { tsconfigFile: config.tsconfigFile }),
+    });
     const { contract, notModified } = await loadClientContractSince(input.fetch === undefined
         ? { entrypoint: config.entrypoint }
         : { entrypoint: config.entrypoint, fetch: input.fetch }, await storedContract(config.generateAt));
-    const emission = emitClientTree(contract, config.entrypoint);
+    const emission = emitClientTree(contract, config.entrypoint, {
+        importFileExtension: style.importFileExtension,
+        moduleFormat: style.moduleFormat,
+    });
     if (notModified &&
         (await ownedOutputMatches(config.generateAt, emission.tree))) {
         return {
@@ -78,8 +72,6 @@ export async function generateClient(input) {
             warnings: written.warnings,
         };
     };
-    // A structural refusal or a defect here comes after the emission's renames
-    // were raised; it carries them, as the writer's own do.
     const foreign = await findForeignOutputContent(config.generateAt).catch((error) => {
         throw error instanceof OutputWriteError
             ? error.precededBy(emission.warnings)

package/dist/index.js

@@ -1,8 +1,3 @@
 import { readFileSync } from "node:fs";
-/**
- * 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.
- */
 export const AVENTARA_CLIENT_GENERATOR_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 export { defineClientConfig, env } from "./config/config.resolver.js";

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

@@ -1,8 +1,10 @@
 /**
- * R4, §15.2 — the config `avclient init` writes: developer-owned, read by
- * `avclient generate`. `file` names it in its own comment line: the
- * `framework.client.mts` it writes, or — to recognize what pilot.0 wrote —
- * `framework.client.ts`.
+ * `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;

package/dist/init/client-config.template.js

@@ -1,22 +1,19 @@
 import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
-/** The package the written config imports its two functions from. */
 const CLIENT_PACKAGE = "@aventara/client";
-/**
- * R4, §15.2 — the config `avclient init` writes: developer-owned, read by
- * `avclient generate`. `file` names it in its own comment line: the
- * `framework.client.mts` it writes, or — to recognize what pilot.0 wrote —
- * `framework.client.ts`.
- */
 export function clientConfigSource(input, file = CLIENT_CONFIG_FILE) {
+    const names = input.envVar === undefined
+        ? "defineClientConfig"
+        : "defineClientConfig, env";
+    const commonJs = file.endsWith(".cjs");
     return [
-        // The specifier is spliced in, not written after `from`, so this module's own
-        // shipped JavaScript does not read as importing the package it names.
-        input.envVar === undefined
-            ? `import { defineClientConfig } from ${JSON.stringify(CLIENT_PACKAGE)};`
-            : `import { defineClientConfig, env } from ${JSON.stringify(CLIENT_PACKAGE)};`,
+        commonJs
+            ? `const { ${names} } = require(${JSON.stringify(CLIENT_PACKAGE)});`
+            : `import { ${names} } from ${JSON.stringify(CLIENT_PACKAGE)};`,
         "",
         `// ${file}: where the Aventara server is, and where its typed client goes.`,
-        "export default defineClientConfig({",
+        commonJs
+            ? "module.exports = defineClientConfig({"
+            : "export default defineClientConfig({",
         input.envVar === undefined
             ? `\tentrypoint: ${JSON.stringify(input.entrypoint)},`
             : `\tentrypoint: env(${JSON.stringify(input.envVar)}),`,

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

@@ -1,9 +1,6 @@
-/** `avclient init`'s refusals after the questions: each one sentence, exit 1. */
-/** Nobody confirmed replacing existing content. A refusal: nothing was touched. */
 export class ClientInitNotConfirmedError extends Error {
     name = "ClientInitNotConfirmedError";
 }
-/** A step after the write failed. Reported with what to run; the files are kept. */
 export class ClientInitStepError extends Error {
     name = "ClientInitStepError";
 }

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

@@ -8,13 +8,6 @@ import { GENERATE_SCRIPT, planClientInit } from "./client-init.planner.js";
 import { resolveClientInitAnswers } from "./client-init.questions.js";
 import { inspectClientProject } from "./client-project.inspector.js";
 import { runCommand } from "./command.runner.js";
-/**
- * R4 — `avclient init`, the whole frontend setup, in the order every wizard of
- * this item keeps: inspect, ask, plan, confirm, and only then write; then the
- * install (N6) and, unless skipped, the first generation through the very path
- * `avclient generate` takes. A refusal before the write leaves the project as
- * it was; a failure after it says what to run next, and keeps the files.
- */
 const MANIFEST = new URL("../../package.json", import.meta.url);
 function ownVersion() {
     return JSON.parse(readFileSync(MANIFEST, "utf8"))
@@ -35,7 +28,6 @@ export async function runClientInit(command, io) {
     });
     const clientVersion = ownVersion();
     const plan = planClientInit({ project, answers, clientVersion });
-    // The generateAt rule (architect, 2026-10-04; R5).
     if (plan.conflicts.length > 0 && !command.yes) {
         const them = plan.conflicts.length === 1 ? "it" : "them";
         const has = plan.conflicts.length === 1 ? "has" : "have";
@@ -68,7 +60,7 @@ export async function runClientInit(command, io) {
         cwd: io.cwd,
     });
     if (installed.code !== 0) {
-        throw new ClientInitStepError(`\`${install}\` exited with code ${installed.code} after ${CLIENT_CONFIG_FILE} was written; fix what it reports and run \`${install}\` again:\n${installed.stderr.trimEnd()}`);
+        throw new ClientInitStepError(`\`${install}\` exited with code ${installed.code} after ${project.configFile ?? CLIENT_CONFIG_FILE} was written; fix what it reports and run \`${install}\` again:\n${installed.stderr.trimEnd()}`);
     }
     if (command.skipGenerate) {
         io.stdout(`Next: with the server running, ${answers.packageManager} run ${GENERATE_SCRIPT}\n`);

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

@@ -1,13 +1,5 @@
 import type { ClientInitAnswers } from "./client-init.questions.js";
 import type { ClientProject } from "./client-project.inspector.js";
-/**
- * §4.5 — what `avclient init` writes, decided before anything is: the config
- * file, the `.env` entry (only with a variable), the `avclient:generate` script
- * and the exact devDependency (N6) — each computed with existing content kept
- * and replaced, and every **conflict** (content it did not produce) named for
- * the generateAt rule.
- */
-/** R4: the script a frontend regenerates its client with. */
 export declare const GENERATE_SCRIPT = "avclient:generate";
 /** One change to a project file: its new content, or `undefined` to remove it. */
 export type ClientInitWrite = {
@@ -22,6 +14,6 @@ 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 (N6). */
+    /** This package's own version: the devDependency is pinned to it exactly. */
     readonly clientVersion: string;
 }): ClientInitPlan;

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

@@ -1,13 +1,5 @@
-import { CLIENT_CONFIG_FILE, LEGACY_CLIENT_CONFIG_FILE, } from "../config/config.loader.js";
+import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
 import { clientConfigSource } from "./client-config.template.js";
-/**
- * §4.5 — what `avclient init` writes, decided before anything is: the config
- * file, the `.env` entry (only with a variable), the `avclient:generate` script
- * and the exact devDependency (N6) — each computed with existing content kept
- * and replaced, and every **conflict** (content it did not produce) named for
- * the generateAt rule.
- */
-/** R4: the script a frontend regenerates its client with. */
 export const GENERATE_SCRIPT = "avclient:generate";
 const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
 function unquoted(value) {
@@ -29,23 +21,13 @@ export function planClientInit(input) {
             replacing.push({ path, content: replaced });
         }
     };
-    const config = clientConfigSource(answers);
-    const existingConfig = project.read(CLIENT_CONFIG_FILE);
-    // pilot.1: a `framework.client.ts` is moved to `framework.client.mts` — two
-    // configs would make `avclient generate` refuse. The one pilot.0 wrote for
-    // these answers moves without asking; anything else is a conflict.
-    const legacyConfig = project.read(LEGACY_CLIENT_CONFIG_FILE);
-    if (legacyConfig !== undefined) {
-        if (legacyConfig !== clientConfigSource(answers, LEGACY_CLIENT_CONFIG_FILE)) {
-            conflicts.push(`${LEGACY_CLIENT_CONFIG_FILE} (replaced by ${CLIENT_CONFIG_FILE})`);
-        }
-        keeping.push({ path: LEGACY_CLIENT_CONFIG_FILE, content: undefined });
-        replacing.push({ path: LEGACY_CLIENT_CONFIG_FILE, content: undefined });
-    }
+    const configFile = project.configFile ?? CLIENT_CONFIG_FILE;
+    const config = clientConfigSource(answers, configFile);
+    const existingConfig = project.read(configFile);
     if (existingConfig !== undefined && existingConfig !== config) {
-        conflicts.push(CLIENT_CONFIG_FILE);
+        conflicts.push(configFile);
     }
-    add(CLIENT_CONFIG_FILE, existingConfig, existingConfig ?? config, config);
+    add(configFile, existingConfig, existingConfig ?? config, config);
     if (answers.envVar !== undefined) {
         const before = project.read(".env");
         const lines = before === undefined || before === ""