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

package/dist/emit/transaction.emitter.js

@@ -0,0 +1,438 @@
+/**
+ * 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() {
+    return [
+        { path: "runtime/fingerprint.ts", source: FINGERPRINT_MODULE },
+        { path: "runtime/transaction.ts", source: TRANSACTION_MODULE },
+    ];
+}
+const FINGERPRINT_MODULE = `/**
+ * The v1 operation fingerprint (§14.4): 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
+ * computeOperationFingerprint.
+ */
+
+/** One plan node, its arguments already in wire form. */
+export interface FingerprintNode {
+	readonly resource: string;
+	readonly family: string;
+	readonly variant: string;
+	readonly args: unknown;
+}
+
+/**
+ * The node's fingerprint, or null when its arguments are not canonical JSON — a
+ * lone surrogate, a non-finite number — exactly when core cannot compute one
+ * either; the server then answers the operation itself.
+ */
+export function fingerprintOf(node: FingerprintNode): string | null {
+	let canonical: string;
+	try {
+		canonical = canonicalJson({
+			resource: node.resource,
+			family: node.family,
+			variant: node.variant,
+			args: node.args,
+		});
+	} catch {
+		return null;
+	}
+	return "fp1:" + base64Url(sha256(utf8(canonical)).subarray(0, 16));
+}
+
+/** RFC 8785: JavaScript's own number and string spelling, keys in UTF-16 code-unit order. */
+export function canonicalJson(value: unknown): string {
+	if (value === null) {
+		return "null";
+	}
+	if (typeof value === "boolean") {
+		return value ? "true" : "false";
+	}
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new TypeError("A non-finite number is not canonical JSON.");
+		}
+		return JSON.stringify(value);
+	}
+	if (typeof value === "string") {
+		assertWellFormed(value);
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return "[" + value.map((entry: unknown) => canonicalJson(entry)).join(",") + "]";
+	}
+	if (typeof value !== "object") {
+		throw new TypeError("A " + typeof value + " is not canonical JSON.");
+	}
+	const prototype: unknown = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new TypeError("A non-plain object is not canonical JSON.");
+	}
+	const record = value as Readonly<Record<string, unknown>>;
+	const keys = Object.keys(record).sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+	return (
+		"{" +
+		keys
+			.map((key) => {
+				assertWellFormed(key);
+				return JSON.stringify(key) + ":" + canonicalJson(record[key]);
+			})
+			.join(",") +
+		"}"
+	);
+}
+
+function assertWellFormed(text: string): void {
+	for (let index = 0; index < text.length; index += 1) {
+		const unit = text.charCodeAt(index);
+		if (unit >= 0xd800 && unit <= 0xdbff) {
+			const next = text.charCodeAt(index + 1);
+			if (!(next >= 0xdc00 && next <= 0xdfff)) {
+				throw new TypeError("A lone surrogate is not canonical JSON.");
+			}
+			index += 1;
+		} else if (unit >= 0xdc00 && unit <= 0xdfff) {
+			throw new TypeError("A lone surrogate is not canonical JSON.");
+		}
+	}
+}
+
+/** UTF-8 of well-formed text. */
+function utf8(text: string): Uint8Array {
+	const bytes: number[] = [];
+	for (const character of text) {
+		const point = character.codePointAt(0) ?? 0;
+		if (point < 0x80) {
+			bytes.push(point);
+		} else if (point < 0x800) {
+			bytes.push(0xc0 | (point >> 6), 0x80 | (point & 63));
+		} else if (point < 0x10000) {
+			bytes.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 63), 0x80 | (point & 63));
+		} else {
+			bytes.push(0xf0 | (point >> 18), 0x80 | ((point >> 12) & 63), 0x80 | ((point >> 6) & 63), 0x80 | (point & 63));
+		}
+	}
+	return new Uint8Array(bytes);
+}
+
+const ROUND = new Uint32Array([
+	0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+	0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+	0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+	0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+	0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+	0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+	0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+	0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotate(word: number, bits: number): number {
+	return (word >>> bits) | (word << (32 - bits));
+}
+
+/** FIPS 180-4 SHA-256. */
+export function sha256(message: Uint8Array): Uint8Array {
+	const blocks = Math.ceil((message.length + 9) / 64);
+	const padded = new Uint8Array(blocks * 64);
+	padded.set(message);
+	padded[message.length] = 0x80;
+	const bits = message.length * 8;
+	const view = new DataView(padded.buffer);
+	view.setUint32(padded.length - 8, Math.floor(bits / 0x100000000));
+	view.setUint32(padded.length - 4, bits >>> 0);
+	const state = new Uint32Array([
+		0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+	]);
+	const schedule = new Uint32Array(64);
+	for (let block = 0; block < blocks; block += 1) {
+		for (let index = 0; index < 64; index += 1) {
+			if (index < 16) {
+				schedule[index] = view.getUint32(block * 64 + index * 4);
+			} else {
+				const early = schedule[index - 15] ?? 0;
+				const late = schedule[index - 2] ?? 0;
+				const sigma0 = rotate(early, 7) ^ rotate(early, 18) ^ (early >>> 3);
+				const sigma1 = rotate(late, 17) ^ rotate(late, 19) ^ (late >>> 10);
+				schedule[index] = ((schedule[index - 16] ?? 0) + sigma0 + (schedule[index - 7] ?? 0) + sigma1) >>> 0;
+			}
+		}
+		let [a, b, c, d, e, f, g, h] = state as unknown as [number, number, number, number, number, number, number, number];
+		for (let index = 0; index < 64; index += 1) {
+			const sum1 = rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25);
+			const choose = (e & f) ^ (~e & g);
+			const first = (h + sum1 + choose + (ROUND[index] ?? 0) + (schedule[index] ?? 0)) >>> 0;
+			const sum0 = rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22);
+			const majority = (a & b) ^ (a & c) ^ (b & c);
+			const second = (sum0 + majority) >>> 0;
+			h = g;
+			g = f;
+			f = e;
+			e = (d + first) >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = (first + second) >>> 0;
+		}
+		const words = [a, b, c, d, e, f, g, h];
+		for (let index = 0; index < 8; index += 1) {
+			state[index] = ((state[index] ?? 0) + (words[index] ?? 0)) >>> 0;
+		}
+	}
+	const digest = new Uint8Array(32);
+	const output = new DataView(digest.buffer);
+	for (let index = 0; index < 8; index += 1) {
+		output.setUint32(index * 4, state[index] ?? 0);
+	}
+	return digest;
+}
+
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** RFC 4648 §5 base64url, unpadded. */
+function base64Url(bytes: Uint8Array): string {
+	let text = "";
+	for (let index = 0; index < bytes.length; index += 3) {
+		const remaining = bytes.length - index;
+		const group = ((bytes[index] ?? 0) << 16) | ((bytes[index + 1] ?? 0) << 8) | (bytes[index + 2] ?? 0);
+		text += BASE64URL_ALPHABET.charAt((group >> 18) & 63) + BASE64URL_ALPHABET.charAt((group >> 12) & 63);
+		if (remaining > 1) {
+			text += BASE64URL_ALPHABET.charAt((group >> 6) & 63);
+		}
+		if (remaining > 2) {
+			text += BASE64URL_ALPHABET.charAt(group & 63);
+		}
+	}
+	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";
+
+/**
+ * The deferred transaction builder and runner (§14), 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
+ * 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).
+ */
+
+/** What a handle defers. */
+interface DeferredRecord {
+	readonly resource: string;
+	readonly family: string;
+	readonly variant: string;
+	readonly args: unknown;
+}
+
+/** What a \`$ref\` placeholder stands for until the plan is assembled. */
+interface Placeholder {
+	readonly source: object;
+	readonly field: string;
+}
+
+type MutableRecord = Record<string, unknown>;
+
+/** One §14.2 wire node, its arguments in wire form. */
+interface PlanNode {
+	readonly resource: string;
+	readonly family: string;
+	readonly variant: string;
+	readonly args: unknown;
+	readonly fingerprint: string | null;
+}
+
+/** One DA-3 container: a mutation-data record and its path inside the arguments. */
+interface Container {
+	readonly path: readonly (string | number)[];
+	readonly record: Readonly<Record<string, unknown>>;
+}
+
+const HANDLES = new WeakMap<object, DeferredRecord>();
+const PLACEHOLDERS = new WeakMap<object, Placeholder>();
+
+function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return false;
+	}
+	const prototype: unknown = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+/** The argument keys holding DA-3 reference positions: the top-level mutation data. */
+function referenceKeys(family: string): readonly string[] {
+	return family === "create" || family === "update" ? ["data"] : family === "upsert" ? ["create", "update"] : [];
+}
+
+function containers(family: string, args: unknown): readonly Container[] {
+	if (!isPlainRecord(args)) {
+		return [];
+	}
+	return referenceKeys(family).flatMap((key): Container[] => {
+		const value = args[key];
+		if (Array.isArray(value)) {
+			return value.flatMap((entry: unknown, index) => (isPlainRecord(entry) ? [{ path: [key, index], record: entry }] : []));
+		}
+		return isPlainRecord(value) ? [{ path: [key], record: value }] : [];
+	});
+}
+
+/** \`args\` with each DA-3 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;
+	}
+	const result: MutableRecord = { ...args };
+	for (const key of referenceKeys(family)) {
+		const value = args[key];
+		if (Array.isArray(value)) {
+			result[key] = value.map((entry: unknown, index) => (isPlainRecord(entry) ? rebuild({ path: [key, index], record: entry }) : entry));
+		} else if (isPlainRecord(value)) {
+			result[key] = rebuild({ path: [key], record: value });
+		}
+	}
+	return result;
+}
+
+/**
+ * Defers one operation into a handle (§14.1): nothing is sent. Its DA-3
+ * 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.
+ */
+export function deferOperation(resource: string, family: string, variant: string, args: unknown): object {
+	const handle: object = Object.freeze({
+		$ref: (field: string): object => {
+			const placeholder = Object.freeze({ $ref: Object.freeze({ path: Object.freeze([field]) }) });
+			PLACEHOLDERS.set(placeholder, { source: handle, field });
+			return placeholder;
+		},
+	});
+	HANDLES.set(handle, {
+		resource,
+		family,
+		variant,
+		args: replaceContainers(family, args, ({ record }) => ({ ...record })),
+	});
+	return handle;
+}
+
+/** What core answers in process for a plan entry it cannot run (A2004 / V1001). */
+function entryRefusal(operation: number, message: string): FrameworkError {
+	const cause: Cause = {
+		message: "Transaction plan failed framework validation.",
+		issues: [{ path: ["operation"], code: "V1001", message }],
+		operation,
+	};
+	return frameworkErrorOf("A2004", cause);
+}
+
+/**
+ * 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
+ * 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\`).
+ */
+export async function runTransaction(
+	connection: TransportConnection,
+	steps: unknown,
+	options: CallOptions = {},
+): Promise<unknown[]> {
+	if (!Array.isArray(steps)) {
+		throw frameworkErrorOf("A2004", {
+			message: "Transaction plan failed framework validation.",
+			issues: [{ path: ["operations"], code: "V1001", message: "Transaction operations must be a list of deferred operations." }],
+		});
+	}
+	const records: DeferredRecord[] = [];
+	const positions = new Map<object, number>();
+	for (const [index, entry] of steps.entries()) {
+		const record = typeof entry === "object" && entry !== null ? HANDLES.get(entry) : undefined;
+		if (record === undefined) {
+			throw entryRefusal(index, "Operation must be a deferred operation built by this client's tx.");
+		}
+		if (positions.has(entry)) {
+			throw entryRefusal(index, "Deferred operation appears more than once in this transaction.");
+		}
+		positions.set(entry, index);
+		records.push(record);
+	}
+	for (const [index, record] of records.entries()) {
+		for (const { path, record: container } of containers(record.family, record.args)) {
+			for (const [field, value] of Object.entries(container)) {
+				const placeholder = typeof value === "object" && value !== null ? PLACEHOLDERS.get(value) : undefined;
+				if (placeholder !== undefined && !positions.has(placeholder.source)) {
+					throw frameworkErrorOf("A2007", {
+						message: "Operation arguments failed framework validation.",
+						issues: [
+							{
+								path: ["operations", index, "args", ...path, field, "$ref"],
+								code: "V1010",
+								message: "Transaction reference names an operation that is not in this transaction.",
+							},
+						],
+						operation: index,
+					});
+				}
+			}
+		}
+	}
+
+	// Bound lazily, as core binds them: 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>();
+	const nodeAt = (index: number): PlanNode => {
+		const built = nodes.get(index);
+		if (built !== undefined) {
+			return built;
+		}
+		const record = records[index] as DeferredRecord;
+		const bound = replaceContainers(record.family, record.args, ({ record: container }) => {
+			const copy: MutableRecord = { ...container };
+			for (const [field, value] of Object.entries(container)) {
+				const placeholder = typeof value === "object" && value !== null ? PLACEHOLDERS.get(value) : undefined;
+				if (placeholder !== undefined) {
+					const operation = positions.get(placeholder.source) as number;
+					copy[field] = { $ref: { operation, fingerprint: nodeAt(operation).fingerprint, path: [placeholder.field] } };
+				}
+			}
+			return copy;
+		});
+		const args: unknown = JSON.parse(serializeWireBody(encodeArguments(bound)));
+		const node: PlanNode = {
+			resource: record.resource,
+			family: record.family,
+			variant: record.variant,
+			args,
+			fingerprint: fingerprintOf({ resource: record.resource, family: record.family, variant: record.variant, args }),
+		};
+		nodes.set(index, node);
+		return node;
+	};
+	return executePlan(
+		connection,
+		{ operations: records.map((_, index) => nodeAt(index)) },
+		records.map((record) => record.resource),
+		options,
+	);
+}
+`;

package/dist/generate.d.ts

@@ -0,0 +1,123 @@
+import type { AbsolutePath } from "./config/client-config.interface.js";
+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";
+/**
+ * §15.3's generation pipeline, as one call (S7b):
+ *
+ *   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.
+ *
+ * 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;
+    /** A snapshot of the process environment. Never mutated. */
+    readonly processEnv: ProcessEnvInput;
+    /**
+     * Overwrite or remove content in `AvClient.ts` and `generated/` that the
+     * generator did not produce, without asking (the CLI's `--yes`). Otherwise
+     * finding any ends the run with `ForeignOutputContent` before anything is
+     * written.
+     */
+    readonly overrideForeign?: boolean;
+    /** Injected for tests; the platform `fetch` otherwise. */
+    readonly fetch?: ContractFetch;
+    /** The `typescript` optional peer; the installed one by default (Q6). */
+    readonly resolveTypeScript?: TypeScriptResolver;
+}
+export interface ClientGenerated {
+    readonly kind: "generated";
+    /** The shared directory the client was generated into. */
+    readonly generateAt: AbsolutePath;
+    /** The files written, in the tree's order. */
+    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 (Q6).
+     */
+    readonly contractUnchanged: boolean;
+    /**
+     * Everything the run has to say without failing, in a fixed order: the
+     * emission's rename notices, then the validator's degraded-check warning, then
+     * the writer's crash-recovery and cleanup notices.
+     */
+    readonly warnings: readonly string[];
+}
+/**
+ * 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.
+ */
+export interface ForeignOutputContent {
+    readonly kind: "foreign-content";
+    readonly generateAt: AbsolutePath;
+    /**
+     * Relative to `generateAt`, POSIX-separated, in code-unit order — including
+     * what a killed run left in the `generated/` it moved aside, named where its
+     * recovery puts it back.
+     */
+    readonly foreign: readonly string[];
+    /**
+     * What the run said before it stopped here — the emission's rename notices —
+     * for whoever stops it for good to report. `proceed` returns them again, first
+     * among its own.
+     */
+    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
+ * (Phase 12-rest Q6): nothing was written.
+ */
+export interface ClientUpToDate {
+    readonly kind: "up-to-date";
+    readonly generateAt: AbsolutePath;
+    /** The files already there, in the tree's order. */
+    readonly files: readonly EmittedFilePath[];
+    /** The emission's rename notices: still true of the output. */
+    readonly warnings: readonly string[];
+}
+export type ClientGenerationOutcome = ClientGenerated | ClientUpToDate | ForeignOutputContent;
+/**
+ * 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 declare function generateClient(input: ClientGenerationInput): Promise<ClientGenerationOutcome>;

package/dist/generate.js

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+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 { 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 { 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"));
+    }
+    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,
+        processEnv: input.processEnv,
+    });
+    const loaded = await loadClientConfigFile(input.directory);
+    const config = resolveClientConfig({
+        config: loaded.config,
+        cascade,
+        configDirectory: path.dirname(loaded.file),
+    });
+    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);
+    if (notModified &&
+        (await ownedOutputMatches(config.generateAt, emission.tree))) {
+        return {
+            kind: "up-to-date",
+            generateAt: config.generateAt,
+            files: emission.tree.map((file) => file.path),
+            warnings: emission.warnings,
+        };
+    }
+    const write = async (overrideForeign) => {
+        const written = await writeClientOutput(input.resolveTypeScript === undefined
+            ? { emission, generateAt: config.generateAt, overrideForeign }
+            : {
+                emission,
+                generateAt: config.generateAt,
+                overrideForeign,
+                resolveTypeScript: input.resolveTypeScript,
+            });
+        return {
+            kind: "generated",
+            generateAt: written.generateAt,
+            files: emission.tree.map((file) => file.path),
+            checked: written.checked,
+            contractUnchanged: notModified,
+            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)
+            : precedeDefect(error, emission.warnings);
+    });
+    if (foreign.length === 0 || input.overrideForeign === true) {
+        return write(foreign);
+    }
+    return {
+        kind: "foreign-content",
+        generateAt: config.generateAt,
+        foreign,
+        warnings: emission.warnings,
+        proceed: () => write(foreign),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 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/index.js

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,6 @@
+/** R4, §15.2 — the `framework.client.ts` `avclient init` writes: developer-owned, read by `avclient generate`. */
+export declare function clientConfigSource(input: {
+    readonly entrypoint: string;
+    readonly envVar: string | undefined;
+    readonly generateAt: string;
+}): string;