@aventara/client 0.1.0-pilot.4 → 1.0.0-rc.0

package/dist/emit/descriptor.emitter.js

@@ -1,4 +1,4 @@
-import { isOperationVariantAvailable, } from "@aventara/core";
+import { isOperationVariantAvailable } from "@aventara/core/internal";
 import { ownPropertyKey } from "./name.deriver.js";
 const REVIVED_SCALARS = new Set([
     "bigint",

package/dist/emit/json-shape.emitter.d.ts

@@ -0,0 +1,16 @@
+import type { ClientContract } from "@aventara/core";
+type Schema = Readonly<Record<string, unknown>>;
+/**
+ * The TypeScript type a Json Shape schema describes, as source text.
+ *
+ * @throws Error on a schema outside the accepted forms — unreachable for a
+ *   ClientContract that passed the structure check.
+ */
+export declare function jsonSchemaType(schema: Schema): string;
+/**
+ * The type `client.ts` gives its derivation in place of the carrier when the
+ * contract shapes a Json field — the carrier with each shaped field's type — or
+ * `undefined` when it shapes none.
+ */
+export declare function shapedContractType(contract: ClientContract): string | undefined;
+export {};

package/dist/emit/json-shape.emitter.js

@@ -0,0 +1,88 @@
+const SCALAR_TYPES = {
+    string: "string",
+    number: "number",
+    integer: "number",
+    boolean: "boolean",
+    null: "null",
+};
+const plain = (text) => ({ text, union: false });
+function unionOf(members) {
+    return members.length === 1
+        ? members[0]
+        : { text: members.map((member) => member.text).join(" | "), union: true };
+}
+function operand(type) {
+    return type.union ? `(${type.text})` : type.text;
+}
+function emitted(schema) {
+    if (Object.hasOwn(schema, "const")) {
+        return plain(JSON.stringify(schema.const));
+    }
+    if (Array.isArray(schema.enum)) {
+        return unionOf(schema.enum.map((value) => plain(JSON.stringify(value))));
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const options = schema[keyword];
+        if (Array.isArray(options)) {
+            return unionOf(options.map((option) => emitted(option)));
+        }
+    }
+    const type = schema.type;
+    if (typeof type === "string" && Object.hasOwn(SCALAR_TYPES, type)) {
+        return plain(SCALAR_TYPES[type]);
+    }
+    if (type === "array") {
+        if (Array.isArray(schema.prefixItems)) {
+            return plain(`[${schema.prefixItems.map((item) => emitted(item).text).join(", ")}]`);
+        }
+        return plain(`${operand(emitted(schema.items))}[]`);
+    }
+    if (type === "object") {
+        const properties = schema.properties;
+        if (properties === undefined) {
+            return plain(`{ [key: string]: ${emitted(schema.additionalProperties).text} }`);
+        }
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const members = Object.keys(properties).map((key) => {
+            const member = emitted(properties[key]).text;
+            return required.has(key)
+                ? `${JSON.stringify(key)}: ${member}`
+                : `${JSON.stringify(key)}?: ${member} | undefined`;
+        });
+        return plain(members.length === 0 ? "{}" : `{ ${members.join("; ")} }`);
+    }
+    throw new Error(`a Json Shape schema outside the accepted forms reached the emitter: ${JSON.stringify(schema)}`);
+}
+export function jsonSchemaType(schema) {
+    return emitted(schema).text;
+}
+export function shapedContractType(contract) {
+    const order = (keys) => [...keys].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    const resources = order(Object.keys(contract.resources)).flatMap((resourceName) => {
+        const fields = contract.resources[resourceName]?.fields ?? {};
+        const shaped = order(Object.keys(fields)).flatMap((fieldName) => {
+            const field = fields[fieldName];
+            return field?.kind === "scalar" && field.json !== undefined
+                ? [
+                    `\t\t\t\treadonly ${JSON.stringify(fieldName)}: { readonly json: JsonFieldType<${jsonSchemaType(field.json)}> };\n`,
+                ]
+                : [];
+        });
+        return shaped.length === 0
+            ? []
+            : [
+                `\t\treadonly ${JSON.stringify(resourceName)}: {\n` +
+                    "\t\t\treadonly fields: {\n" +
+                    shaped.join("") +
+                    "\t\t\t};\n" +
+                    "\t\t};\n",
+            ];
+    });
+    return resources.length === 0
+        ? undefined
+        : "ClientContractShape & {\n" +
+            "\treadonly resources: {\n" +
+            resources.join("") +
+            "\t};\n" +
+            "}";
+}

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

@@ -1,4 +1,4 @@
-import { type ClientContract, type OperationFamily } from "@aventara/core";
+import type { ClientContract, OperationFamily } from "@aventara/core";
 /**
  * Name derivation and the rename ladder for the emitted tree.
  */

package/dist/emit/name.deriver.js

@@ -1,4 +1,4 @@
-import { isOperationVariantAvailable, } from "@aventara/core";
+import { isOperationVariantAvailable } from "@aventara/core/internal";
 import { FRAMEWORK_ERROR_CLASS_NAMES } from "./runtime.emitter.js";
 export const RESERVED_EMITTED_NAMES = [
     ...new Set([

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

@@ -1,4 +1,4 @@
-import { type ClientContract } from "@aventara/core";
+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";

package/dist/emit/runtime.emitter.js

@@ -1,4 +1,4 @@
-import { OPERATION_CODES, VALIDATION_CODES, } from "@aventara/core";
+import { OPERATION_CODES, VALIDATION_CODES } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
 import { entrypointHref } from "../config/config.resolver.js";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
@@ -227,7 +227,7 @@ const IDENTITY_HEADERS = (() => {
 })();
 function transportModuleSource(from) {
     return `import { CLIENT_CONTRACT_HASH, PROTOCOL_VERSION } from ${from("../metadata")};
-import { decodeResult, encodeArguments, serializeWireBody } from ${from("./codec")};
+import { decodeResult, encodeArguments, readArgument, serializeWireBody } from ${from("./codec")};
 import { DECODE_TABLE } from ${from("./descriptor")};
 import {
 	type Cause,
@@ -575,7 +575,7 @@ function issueOf(value: unknown): ValidationIssue | undefined {
 
 /** The arguments, refused unless they are an object: the body is always one. */
 function argumentObject(args: unknown): unknown {
-	if (!isRecord(args)) {
+	if (!readArgument([], () => isRecord(args))) {
 		throw new TypeError("An operation's arguments must be an object; send {} when there are none.");
 	}
 	return args;

package/dist/emit/scalar.codec.js

@@ -1,4 +1,4 @@
-import { BUILT_IN_SCALARS } from "@aventara/core";
+import { BUILT_IN_SCALARS } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 export function wireGrammarLiteral(scalar) {
@@ -331,31 +331,74 @@ export function encodeArguments(value: unknown): unknown {
 	return encodeValue(value, [], new Set());
 }
 
-function encodeValue(value: unknown, path: Path, ancestors: Set<object>): unknown {
-	if (typeof value === "bigint") {
-		return encodeScalar("bigint", value);
+/**
+ * One read of a caller's arguments. Every native read on them happens through it,
+ * here and in the transaction builder, so a value that cannot be read — a revoked
+ * Proxy (an Immer draft after produce), a throwing getter or trap — is refused at its
+ * path with a TypeError before anything is sent, never with the engine's own error.
+ */
+export function readArgument<T>(path: Path, read: () => T): T {
+	try {
+		return read();
+	} catch {
+		throw new TypeError(
+			"An operation's arguments must be readable plain data, and the value at " + pointerOf(path) + " could not be read.",
+		);
 	}
+}
+
+/** How encodeValue treats an object: a scalar's runtime class, a container, or neither. */
+function objectKind(value: object): "datetime" | "decimal" | "bytes" | "container" | "other" {
 	if (value instanceof Date) {
-		return encodeScalar("datetime", value);
+		return "datetime";
 	}
 	if (value instanceof Decimal) {
-		return encodeScalar("decimal", value);
+		return "decimal";
 	}
 	if (value instanceof Uint8Array) {
-		return encodeScalar("bytes", value);
+		return "bytes";
 	}
-	if (typeof value !== "object" || value === null || !isJsonContainer(value)) {
+	return isJsonContainer(value) ? "container" : "other";
+}
+
+function encodeValue(value: unknown, path: Path, ancestors: Set<object>): unknown {
+	if (typeof value === "bigint") {
+		return encodeScalar("bigint", value);
+	}
+	if (typeof value !== "object" || value === null) {
+		return value;
+	}
+	const kind = readArgument(path, () => objectKind(value));
+	if (kind === "other") {
 		return value;
 	}
+	if (kind !== "container") {
+		return encodeScalar(kind, value);
+	}
 	if (ancestors.has(value)) {
 		return refuseBody(path, "a cycle");
 	}
 	ancestors.add(value);
-	const copy = Array.isArray(value)
-		? value.map((item, index) => encodeValue(item, [...path, index], ancestors))
-		: Object.fromEntries(
-				Object.entries(value).map(([key, member]) => [key, encodeValue(member, [...path, key], ancestors)]),
-			);
+	let copy: unknown;
+	if (readArgument(path, () => Array.isArray(value))) {
+		const items = value as readonly unknown[];
+		const length = readArgument(path, () => items.length);
+		const list: unknown[] = [];
+		for (let index = 0; index < length; index += 1) {
+			const itemPath = [...path, index];
+			list.push(encodeValue(readArgument(itemPath, () => items[index]), itemPath, ancestors));
+		}
+		copy = list;
+	} else {
+		const record = value as Readonly<Record<string, unknown>>;
+		const members: [string, unknown][] = [];
+		for (const key of readArgument(path, () => Object.keys(record))) {
+			const memberPath = [...path, key];
+			members.push([key, encodeValue(readArgument(memberPath, () => record[key]), memberPath, ancestors)]);
+		}
+		// fromEntries defines each key, so "__proto__" stays an own key.
+		copy = Object.fromEntries(members);
+	}
 	ancestors.delete(value);
 	return copy;
 }

package/dist/emit/transaction.emitter.js

@@ -209,7 +209,7 @@ function base64Url(bytes: Uint8Array): string {
 }
 `;
 function transactionModuleSource(from) {
-    return `import { encodeArguments, serializeWireBody } from ${from("./codec")};
+    return `import { encodeArguments, readArgument, 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")};
@@ -222,12 +222,16 @@ import { type CallOptions, executePlan, type TransportConnection } from ${from("
  * this generated tree may run it.
  */
 
-/** What a handle defers. */
+/**
+ * What a handle defers — or why its arguments could not be read: the builder
+ * never throws into app code, and running the handle refuses it instead.
+ */
 interface DeferredRecord {
 	readonly resource: string;
 	readonly family: string;
 	readonly variant: string;
 	readonly args: unknown;
+	readonly unreadable?: TypeError;
 }
 
 /** What a \`$ref\` placeholder stands for until the plan is assembled. */
@@ -236,8 +240,6 @@ interface Placeholder {
 	readonly field: string;
 }
 
-type MutableRecord = Record<string, unknown>;
-
 /** One wire node of a transaction plan, its arguments in wire form. */
 interface PlanNode {
 	readonly resource: string;
@@ -247,10 +249,11 @@ interface PlanNode {
 	readonly fingerprint: string | null;
 }
 
-/** One reference container: a mutation-data record and its path inside the arguments. */
-interface Container {
+/** One placeholder an argument tree holds: where, the object itself, and its meaning. */
+interface PlaceholderSite {
 	readonly path: readonly (string | number)[];
-	readonly record: Readonly<Record<string, unknown>>;
+	readonly object: object;
+	readonly placeholder: Placeholder;
 }
 
 const HANDLES = new WeakMap<object, DeferredRecord>();
@@ -264,45 +267,73 @@ function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown
 	return prototype === Object.prototype || prototype === null;
 }
 
-/** 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"] : [];
-}
+const KEEP: unique symbol = Symbol("keep");
 
-function containers(family: string, args: unknown): readonly Container[] {
-	if (!isPlainRecord(args)) {
-		return [];
+/**
+ * Rebuilds an argument tree: every plain record and array is copied, every other
+ * value kept, and \`leaf\` may replace any value first (a placeholder, by identity).
+ * A placeholder is bound wherever the arguments hold one; the server answers a
+ * position that takes no reference. A container met again on its own ancestry is
+ * kept as it is; the codec refuses it.
+ */
+function rebuild(
+	value: unknown,
+	path: readonly (string | number)[],
+	leaf: (value: unknown, path: readonly (string | number)[]) => unknown,
+	ancestors: Set<object> = new Set(),
+): unknown {
+	const replaced = leaf(value, path);
+	if (replaced !== KEEP || typeof value !== "object" || value === null) {
+		return replaced === KEEP ? value : replaced;
 	}
-	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 }] : []));
+	const array = readArgument(path, () => Array.isArray(value));
+	if ((!array && !readArgument(path, () => isPlainRecord(value))) || ancestors.has(value)) {
+		return value;
+	}
+	ancestors.add(value);
+	let copy: unknown;
+	if (array) {
+		const items = value as readonly unknown[];
+		const length = readArgument(path, () => items.length);
+		const list: unknown[] = [];
+		for (let index = 0; index < length; index += 1) {
+			const itemPath = [...path, index];
+			list.push(rebuild(readArgument(itemPath, () => items[index]), itemPath, leaf, ancestors));
 		}
-		return isPlainRecord(value) ? [{ path: [key], record: value }] : [];
-	});
+		copy = list;
+	} else {
+		const record = value as Readonly<Record<string, unknown>>;
+		const members: [string, unknown][] = [];
+		for (const key of readArgument(path, () => Object.keys(record))) {
+			const memberPath = [...path, key];
+			members.push([key, rebuild(readArgument(memberPath, () => record[key]), memberPath, leaf, ancestors)]);
+		}
+		copy = Object.fromEntries(members);
+	}
+	ancestors.delete(value);
+	return copy;
 }
 
-/** \`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;
-	}
-	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 });
+/** Every placeholder \`args\` holds, with its path inside the arguments. */
+function placeholderSites(args: unknown): readonly PlaceholderSite[] {
+	const sites: PlaceholderSite[] = [];
+	rebuild(args, [], (value, path) => {
+		const placeholder = typeof value === "object" && value !== null ? PLACEHOLDERS.get(value) : undefined;
+		if (placeholder === undefined) {
+			return KEEP;
 		}
-	}
-	return result;
+		sites.push({ path, object: value as object, placeholder });
+		return value;
+	});
+	return sites;
 }
 
 /**
- * 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.
+ * Defers one operation into a handle: nothing is sent, and nothing is thrown.
+ * Its arguments 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.
+ * Arguments that cannot be read are kept as their refusal, which running the
+ * handle rejects with.
  */
 export function deferOperation(resource: string, family: string, variant: string, args: unknown): object {
 	const handle: object = Object.freeze({
@@ -312,12 +343,19 @@ export function deferOperation(resource: string, family: string, variant: string
 			return placeholder;
 		},
 	});
-	HANDLES.set(handle, {
-		resource,
-		family,
-		variant,
-		args: replaceContainers(family, args, ({ record }) => ({ ...record })),
-	});
+	let record: DeferredRecord;
+	try {
+		record = {
+			resource,
+			family,
+			variant,
+			args: rebuild(args, [], (value) => (typeof value === "object" && value !== null && PLACEHOLDERS.has(value) ? value : KEEP)),
+		};
+	} catch (error) {
+		// Only readArgument throws here: an argument that could not be read.
+		record = { resource, family, variant, args: {}, unreadable: error as TypeError };
+	}
+	HANDLES.set(handle, record);
 	return handle;
 }
 
@@ -325,7 +363,7 @@ export function deferOperation(resource: string, family: string, variant: string
 function entryRefusal(operation: number, message: string): FrameworkError {
 	const cause: Cause = {
 		message: "Transaction plan failed framework validation.",
-		issues: [{ path: ["operation"], code: "V1001", message }],
+		issues: [{ path: ["operations", operation], code: "V1001", message }],
 		operation,
 	};
 	return frameworkErrorOf("A2004", cause);
@@ -336,8 +374,9 @@ function entryRefusal(operation: number, message: string): FrameworkError {
  * 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\`).
+ * ["operations", i]: the entry itself); a reference to a handle not in the list (ValidationError A2007 /
+ * V1010 at its \`$ref\`); a handle whose arguments could not be read when it was
+ * built (the TypeError naming where).
  */
 export async function runTransaction(
 	connection: TransportConnection,
@@ -364,22 +403,22 @@ export async function runTransaction(
 		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,
-					});
-				}
+		if (record.unreadable !== undefined) {
+			throw record.unreadable;
+		}
+		for (const { path, placeholder } of placeholderSites(record.args)) {
+			if (!positions.has(placeholder.source)) {
+				throw frameworkErrorOf("A2007", {
+					message: "Operation arguments failed framework validation.",
+					issues: [
+						{
+							path: ["operations", index, "args", ...path, "$ref"],
+							code: "V1010",
+							message: "Transaction reference names an operation that is not in this transaction.",
+						},
+					],
+					operation: index,
+				});
 			}
 		}
 	}
@@ -394,17 +433,14 @@ export async function runTransaction(
 			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 references = new Map<object, unknown>();
+		for (const { object, placeholder } of placeholderSites(record.args)) {
+			const operation = positions.get(placeholder.source) as number;
+			references.set(object, { $ref: { operation, fingerprint: nodeAt(operation).fingerprint, path: [placeholder.field] } });
+		}
+		const bound = rebuild(record.args, [], (value) =>
+			typeof value === "object" && value !== null && references.has(value) ? references.get(value) : KEEP,
+		);
 		const args: unknown = JSON.parse(serializeWireBody(encodeArguments(bound)));
 		const node: PlanNode = {
 			resource: record.resource,

package/dist/generate.d.ts

@@ -1,6 +1,6 @@
 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 ContractFetch } from "./contract/contract.fetcher.js";
 import { type EmittedFilePath } from "./emit/emitted-tree.interface.js";
 import type { OutputCheck, TypeScriptResolver } from "./output/output.validator.js";
 export interface ClientGenerationInput {
@@ -17,7 +17,15 @@ export interface ClientGenerationInput {
     readonly overrideForeign?: boolean;
     readonly fetch?: ContractFetch;
     readonly resolveTypeScript?: TypeScriptResolver;
+    /**
+     * Runs each of the run's four phases — the config, the contract, the
+     * emission, the write — under a title, so whoever owns the terminal can show
+     * them (`cli/step.reporter.ts`); each phase simply runs when omitted.
+     */
+    readonly step?: GenerationStep;
 }
+/** Runs one phase of a generation under its title, resolving to what it returns. */
+export type GenerationStep = <T>(title: string, body: () => Promise<T> | T) => Promise<T>;
 export interface ClientGenerated {
     readonly kind: "generated";
     /** The shared directory the client was generated into. */

package/dist/generate.js

@@ -4,11 +4,13 @@ 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 { contractUrlOf, displayUrl, } from "./contract/contract.fetcher.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 { 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";
+const runPhase = async (_title, body) => await body();
 async function storedContract(generateAt) {
     try {
         if ((await findForeignOutputContent(generateAt)).length > 0) {
@@ -21,32 +23,42 @@ async function storedContract(generateAt) {
     }
 }
 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 style = resolveModuleStyle({
-        generateAt: config.generateAt,
-        entryFile: path.join(config.generateAt, CLIENT_ENTRY_FILE),
-        ...(config.tsconfigFile === undefined
-            ? {}
-            : { tsconfigFile: config.tsconfigFile }),
+    const step = input.step ?? runPhase;
+    const { config, style } = await step("Loading the client config", async () => {
+        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 style = resolveModuleStyle({
+            generateAt: config.generateAt,
+            entryFile: path.join(config.generateAt, CLIENT_ENTRY_FILE),
+            ...(config.tsconfigFile === undefined
+                ? {}
+                : { tsconfigFile: config.tsconfigFile }),
+        });
+        return { config, style };
     });
-    const { contract, notModified } = await loadClientContractSince(input.fetch === undefined
+    const { contract, notModified } = await step(`Fetching the ClientContract (${displayUrl(contractUrlOf(config.entrypoint))})`, async () => loadClientContractSince(input.fetch === undefined
         ? { entrypoint: config.entrypoint }
-        : { entrypoint: config.entrypoint, fetch: input.fetch }, await storedContract(config.generateAt));
-    const emission = emitClientTree(contract, config.entrypoint, {
-        importFileExtension: style.importFileExtension,
-        moduleFormat: style.moduleFormat,
+        : { entrypoint: config.entrypoint, fetch: input.fetch }, await storedContract(config.generateAt)));
+    const { emission, upToDate } = await step("Emitting the client", async () => {
+        const emission = emitClientTree(contract, config.entrypoint, {
+            importFileExtension: style.importFileExtension,
+            moduleFormat: style.moduleFormat,
+        });
+        return {
+            emission,
+            upToDate: notModified &&
+                (await ownedOutputMatches(config.generateAt, emission.tree)),
+        };
     });
-    if (notModified &&
-        (await ownedOutputMatches(config.generateAt, emission.tree))) {
+    if (upToDate) {
         return {
             kind: "up-to-date",
             generateAt: config.generateAt,
@@ -54,7 +66,7 @@ export async function generateClient(input) {
             warnings: emission.warnings,
         };
     }
-    const write = async (overrideForeign) => {
+    const writeInto = async (overrideForeign) => {
         const written = await writeClientOutput(input.resolveTypeScript === undefined
             ? { emission, generateAt: config.generateAt, overrideForeign }
             : {
@@ -72,6 +84,8 @@ export async function generateClient(input) {
             warnings: written.warnings,
         };
     };
+    const into = path.relative(input.directory, config.generateAt) || ".";
+    const write = (overrideForeign) => step(`Checking and writing the client into ${into}`, () => writeInto(overrideForeign));
     const foreign = await findForeignOutputContent(config.generateAt).catch((error) => {
         throw error instanceof OutputWriteError
             ? error.precededBy(emission.warnings)