@aventara/build 0.0.0-stage → 1.0.0-rc.11

package/dist/cli.js

@@ -0,0 +1,240 @@
+import path from "node:path";
+import { AvBuildError } from "./build.error.js";
+import { checkBrowserClient, emitBrowserClient, writeBrowserClient, } from "./client/client-file.js";
+import { readConfigComputedFields } from "./computed/computed-fields.reader.js";
+import { emitComputedFieldsModule } from "./computed/computed-fields-file.js";
+import { checkContractsFile, writeContractsFile, } from "./contracts/contracts-file.js";
+import { compilePrebuiltContracts } from "./contracts/prebuilt-contracts.compiler.js";
+import { readGeneratedFile, writeGeneratedFile, } from "./project/generated-file.js";
+import { DEFAULT_GENERATED_FILES, resolveGeneratedFiles, } from "./project/generated-files.resolver.js";
+import { applyProjectEnv } from "./project/project-env.loader.js";
+import { PROJECT_LAYOUTS, resolveProjectLayout, } from "./project/project-layout.resolver.js";
+import { findProjectModules, loadProjectModules, } from "./project/project-modules.loader.js";
+import { importSuffixOf, projectCompilerOptions, } from "./project/tsconfig.reader.js";
+import { RESOURCES_GLOB, readResourceDefinitions, } from "./resources/resource-definitions.reader.js";
+import { emitResourcesModule } from "./resources/resources-file.js";
+const USAGE = `aventara-build — compile this project's Aventara Contracts ahead of time.
+
+Usage:
+  aventara-build                    write the three files below
+  aventara-build --client           also write a Next.js app's browser client
+  aventara-build --check [--client] write nothing; exit 1 when one is missing or stale
+
+Run it from the project's root. It writes, in this order:
+
+  ${DEFAULT_GENERATED_FILES.resources}
+      \`aventaraResources\`: every \`defineResource(…)\` result the files
+      ${RESOURCES_GLOB} export, one \`resources\` tree per layer;
+  ${DEFAULT_GENERATED_FILES.computedFields}
+      which fields the configuration computes, read off its type;
+  ${DEFAULT_GENERATED_FILES.contracts}
+      the compiled Contracts, \`aventaraContracts\`.
+
+All three go to the directory the configuration imports \`aventaraResources\`
+from (src/aventara/ when \`aventara init\` found the ORM's client generated into
+src/generated), else to ${PROJECT_LAYOUTS.nest.generated}/ (${PROJECT_LAYOUTS.next.generated}/
+in a Next.js project).
+
+It runs the configuration (its \`aventaraConfig\` export or its default,
+without \`adapter\`) and the adapter's description (its default export, such
+as \`describePrismaAdapter({ discovery, provider, driver })\`), in TypeScript
+or JavaScript, and compiles the Contracts with the project's own
+@aventara/core. It never constructs a database client. Before it runs them it
+reads the project's .env files into the environment, as \`avclient generate\`
+does: a variable already set wins, then .env.<mode>.local, .env.<mode>,
+.env.local and .env (the mode is NODE_ENV, else development). Where they are
+depends on the project's host:
+
+  a Next.js project (its package.json depends on @aventara/next)
+      ${PROJECT_LAYOUTS.next.config}.ts and ${PROJECT_LAYOUTS.next.adapter}.ts
+  any other project (NestJS)
+      ${PROJECT_LAYOUTS.nest.config}.ts and ${PROJECT_LAYOUTS.nest.adapter}.ts
+
+With --client, a Next.js project also gets its browser client, written from
+the ClientContract just compiled: ${PROJECT_LAYOUTS.next.client.folder}/${PROJECT_LAYOUTS.next.client.entry}
+(\`avClient\`, calling the app's own \`api\` from the browser, and \`avHydrate\`),
+${PROJECT_LAYOUTS.next.client.folder}/${PROJECT_LAYOUTS.next.client.universal} (\`avClient\` for both sides: the app's \`api\`
+from the browser, the app in process on the server) and the client's modules
+under ${PROJECT_LAYOUTS.next.client.folder}/generated/.
+
+A serverless or edge host passes the file's \`aventaraContracts\` to
+createFramework as \`prebuilt\`; a long-running server needs none.
+
+Options:
+  --client    Also write the browser client (Next.js projects).
+  --check     Exit 1, writing nothing, when a file is missing or stale.
+  -h, --help  Print this and exit 0.`;
+function parse(argv) {
+    let check = false;
+    let client = false;
+    for (const argument of argv) {
+        if (argument === "--check") {
+            check = true;
+            continue;
+        }
+        if (argument === "--client") {
+            client = true;
+            continue;
+        }
+        throw new AvBuildError(`unknown argument \`${argument}\`.\n\n${USAGE}`);
+    }
+    return { check, client };
+}
+function listed(items) {
+    return items.length < 2
+        ? items.join("")
+        : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+function counted(count) {
+    return `${count} Resource${count === 1 ? "" : "s"}`;
+}
+function wrote(written, file, detail) {
+    return `aventara-build: ${written === "written" ? "wrote" : "unchanged:"} ${file}${detail === undefined ? "" : ` (${detail})`}.`;
+}
+function checked(projectDirectory, file, text, stale) {
+    const current = readGeneratedFile(projectDirectory, file);
+    return current === undefined
+        ? { file, what: "is missing" }
+        : current === text
+            ? undefined
+            : { file, what: `is stale: ${stale}` };
+}
+function refusal({ file, what, deploy }) {
+    return `aventara-build: ${file} ${what}. Run aventara-build (npm run aventara:prepare)${deploy === true ? " and deploy the file it writes" : ""}.`;
+}
+export async function runBuild(argv, projectDirectory, output) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        output.stdout(USAGE);
+        return 0;
+    }
+    let restoreEnv;
+    try {
+        const { check, client } = parse(argv);
+        const env = applyProjectEnv(projectDirectory);
+        restoreEnv = env.restore;
+        if (env.loaded.length > 0) {
+            output.stdout(`aventara-build: environment from ${listed(env.loaded)} (a variable already set keeps its value).`);
+        }
+        const layout = resolveProjectLayout(projectDirectory);
+        const clientLayout = client ? layout.client : undefined;
+        if (client && clientLayout === undefined) {
+            throw new AvBuildError(`--client writes the browser client of a Next.js project, and ${projectDirectory} is ${layout.described}. A separate frontend generates its client from the running server with \`avclient generate\`.`);
+        }
+        const files = findProjectModules(projectDirectory, layout);
+        const generated = resolveGeneratedFiles(projectDirectory, files.configFile, layout.generated);
+        const options = projectCompilerOptions(projectDirectory);
+        const found = readResourceDefinitions(projectDirectory, options);
+        const tree = emitResourcesModule(projectDirectory, generated.resources, found.definitions, importSuffixOf(options, path.dirname(path.join(projectDirectory, generated.resources))));
+        for (const file of found.withoutDefinition) {
+            output.stdout(`aventara-build: ${file} exports no defineResource(…) result; it is not in aventaraResources.`);
+        }
+        if (check) {
+            const stale = checked(projectDirectory, generated.resources, tree, "the Resource files changed since it was written");
+            if (stale !== undefined) {
+                output.stderr(refusal(stale));
+                return 1;
+            }
+        }
+        else {
+            output.stdout(wrote(writeGeneratedFile(projectDirectory, generated.resources, tree), generated.resources, counted(found.definitions.length)));
+        }
+        if (check) {
+            if (readGeneratedFile(projectDirectory, generated.computedFields) ===
+                undefined) {
+                output.stderr(refusal({ file: generated.computedFields, what: "is missing" }));
+                return 1;
+            }
+        }
+        else if (readGeneratedFile(projectDirectory, generated.computedFields) ===
+            undefined) {
+            writeGeneratedFile(projectDirectory, generated.computedFields, emitComputedFieldsModule(files.configFile, {
+                kind: "unread",
+                reason: "the build has not read the configuration yet",
+            }));
+        }
+        const reading = readConfigComputedFields(path.join(projectDirectory, files.configFile), options, found.program);
+        const computed = emitComputedFieldsModule(files.configFile, reading);
+        if (check) {
+            const stale = checked(projectDirectory, generated.computedFields, computed, "the fields the configuration computes changed since it was written");
+            if (stale !== undefined) {
+                output.stderr(refusal(stale));
+                return 1;
+            }
+        }
+        else {
+            output.stdout(wrote(writeGeneratedFile(projectDirectory, generated.computedFields, computed), generated.computedFields));
+            if (reading.kind === "unread") {
+                output.stdout(`aventara-build: computed fields not read from ${files.configFile}: ${reading.reason}. The stages before compute may leave any create field out; write the configuration \`as const\` there.`);
+            }
+        }
+        const project = await loadProjectModules(projectDirectory, files);
+        const compiled = await compilePrebuiltContracts(project);
+        const resources = Object.keys(compiled.prebuilt.fingerprints.resources).length;
+        const browserClient = clientLayout === undefined
+            ? undefined
+            : await emitBrowserClient(projectDirectory, clientLayout, {
+                client: compiled.client,
+                api: compiled.api,
+                canonicalText: (contract) => project.internal.canonicalizeContract(contract),
+            });
+        if (!check) {
+            output.stdout(wrote(writeContractsFile(projectDirectory, generated.contracts, compiled), generated.contracts, counted(resources)));
+            if (browserClient !== undefined) {
+                for (const warning of browserClient.warnings) {
+                    output.stdout(`aventara-build: ${warning}`);
+                }
+                const written = writeBrowserClient(projectDirectory, browserClient);
+                for (const file of written.removed) {
+                    output.stdout(`aventara-build: removed ${file}, which this ClientContract's browser client no longer has.`);
+                }
+                const [entry, universal] = browserClient.files;
+                output.stdout(wrote(written.write, `${entry?.file}, ${universal?.file} and ${browserClient.tree}/`, `the browser client, calling ${browserClient.entrypoint === "" ? "/" : browserClient.entrypoint}`));
+            }
+            return 0;
+        }
+        const contracts = await checkContractsFile(projectDirectory, generated.contracts, compiled, project.internal.prebuiltFileChanges);
+        if (contracts.kind === "fresh") {
+            const stale = browserClient === undefined
+                ? undefined
+                : checkBrowserClient(projectDirectory, browserClient);
+            if (stale !== undefined) {
+                output.stderr(refusal(stale));
+                return 1;
+            }
+            output.stdout(browserClient === undefined
+                ? `aventara-build: ${generated.resources}, ${generated.computedFields} and ${generated.contracts} are up to date.`
+                : `aventara-build: ${generated.resources}, ${generated.computedFields}, ${generated.contracts} and the browser client (${browserClient.files[0]?.file}, ${browserClient.files[1]?.file} and ${browserClient.tree}/) are up to date.`);
+            return 0;
+        }
+        output.stderr(refusal({
+            file: generated.contracts,
+            deploy: true,
+            what: contracts.kind === "missing"
+                ? "is missing"
+                : `is stale: ${contracts.changes.join("; ")}`,
+        }));
+        return 1;
+    }
+    catch (error) {
+        if (error instanceof AvBuildError) {
+            output.stderr(`aventara-build: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+    finally {
+        restoreEnv?.();
+    }
+}
+export async function runFromProcess() {
+    try {
+        process.exitCode = await runBuild(process.argv.slice(2), process.cwd(), {
+            stdout: (line) => process.stdout.write(`${line}\n`),
+            stderr: (line) => process.stderr.write(`${line}\n`),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${(error instanceof Error && error.stack) || String(error)}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/client/client-file.js

@@ -0,0 +1,449 @@
+import { readdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { AvClientConfigError, AvGeneratedNameError, acceptClientContract, accessVerbsOf, carriesGeneratedOwnership, clientEntryReExports, emitClientTree, GENERATED_DIRECTORY, HYDRATION_FORMAT, importSpecifier, resolveModuleStyle, sameOriginEntrypoint, } from "@aventara/client/internal";
+import { AvBuildError } from "../build.error.js";
+import { readGeneratedFile, writeGeneratedFile, } from "../project/generated-file.js";
+export const REGENERATE = "`aventara-build --client` (the project's `aventara:prepare` script)";
+const ENTRY_BANNER = [
+    "// biome-ignore-all format: generated output",
+    "// biome-ignore-all lint: generated output",
+    "/* !!! Generated by @aventara/build. Do not edit. !!! */",
+    `/* Regenerate with ${REGENERATE}. */`,
+].join("\n");
+export const SERVER_CALL_REFUSAL = "avClient from @/aventara/client runs in the browser only, and this call ran on the server, where a Client Component renders first: on the server, call avClient from @/aventara/server, or from @/aventara/universal for data the browser then hydrates.";
+const BROWSER_GUARD_SOURCE = `/** \`call\`, rejected instead of run when \`refusal()\` names why. */
+function guarded(call: Call): Call {
+	return (...args) => {
+		const refused = refusal();
+		return refused === undefined ? call(...args) : Promise.reject(new Error(refused));
+	};
+}
+`;
+const UNIVERSAL_GUARD_SOURCE = `/**
+ * Next.js's \`io()\`: while \`next build\` prerenders a page it waits, so a call
+ * there runs at request time, as any database read does; it resolves at once
+ * everywhere else. Next.js refuses it in an \`after()\` callback a page
+ * scheduled, where the render is over, and the call then runs at once.
+ */
+function ioFirst(): Promise<void> {
+	try {
+		return io();
+	} catch {
+		return Promise.resolve();
+	}
+}
+
+/**
+ * \`call\`, made at once when it may run (its request awaits \`io()\`); when
+ * \`refusal()\` names why it may not, made once \`io()\` lets it if it may run
+ * then, and rejected instead otherwise.
+ */
+function guarded(call: Call): Call {
+	return (...args) =>
+		refusal() === undefined
+			? call(...args)
+			: ioFirst().then(() => {
+					const refused = refusal();
+					return refused === undefined ? call(...args) : Promise.reject(new Error(refused));
+				});
+}
+`;
+const GUARD_SOURCE = `/**
+ * A frozen copy of one Resource's families, or one family's variants: each call
+ * guarded, and made on what \`at\` reads of the \`current()\` client.
+ */
+function guardedTree(tree: object, at: (client: AvClient) => unknown): object {
+	const copy: Record<string, unknown> = Object.create(Object.getPrototypeOf(tree) as object | null);
+	for (const [key, value] of Object.entries(tree)) {
+		const member = (client: AvClient): unknown => (at(client) as Readonly<Record<string, unknown>>)[key];
+		copy[key] =
+			typeof value === "function"
+				? guarded((...args) => (member(current()) as Call)(...args))
+				: guardedTree(value as object, member);
+	}
+	return Object.freeze(copy);
+}
+
+/**
+ * A client shaped as \`template\`, every call that sends a request guarded and
+ * made on the \`current()\` client; \`tx\` builds deferred operations and sends
+ * nothing, so the template's is kept as it is.
+ */
+function guardedClient(template: AvClient): AvClient {
+	const copy: AvClient = Object.create(AvClient.prototype) as AvClient;
+	for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(template))) {
+		const value: unknown = descriptor.value;
+		const member = (client: AvClient): unknown => (client as unknown as Readonly<Record<string, unknown>>)[key];
+		Object.defineProperty(copy, key, {
+			...descriptor,
+			value:
+				key === "tx"
+					? value
+					: typeof value === "function"
+						? guarded((...args) => (member(current()) as Call)(...args))
+						: guardedTree(value as object, member),
+		});
+	}
+	return copy;
+}
+`;
+function entrySource(style, accessVerbs) {
+    const from = (module) => JSON.stringify(importSpecifier(module, style));
+    const { tagKey, valueKey, objectTag, scalarTags } = HYDRATION_FORMAT;
+    const tagged = [...scalarTags, objectTag]
+        .map((tag) => JSON.stringify(tag))
+        .join(" | ");
+    return `${ENTRY_BANNER}
+
+import { AvClient } from ${from(`./${GENERATED_DIRECTORY}/client`)};
+import { type AvBuiltInScalar, decodeScalar } from ${from(`./${GENERATED_DIRECTORY}/runtime/codec`)};
+
+${clientEntryReExports(style, "type", accessVerbs)}
+/** What a call made on the server is refused with. */
+const SERVER_CALL = ${JSON.stringify(SERVER_CALL_REFUSAL)};
+
+/**
+ * Whether this code runs where the client's entrypoint, a path on the page's own
+ * origin, can be resolved: a page or a worker has a location, a server has none.
+ */
+function onServer(): boolean {
+	return (globalThis as { readonly location?: unknown }).location === undefined;
+}
+
+/** Why a call made here and now is refused; \`undefined\` when it may run. */
+function refusal(): string | undefined {
+	return onServer() ? SERVER_CALL : undefined;
+}
+
+type Call = (...args: unknown[]) => unknown;
+
+/** The one client every call is made on. */
+const CLIENT = new AvClient();
+
+/** The client a call made here and now is made on: the one client. */
+function current(): AvClient {
+	return CLIENT;
+}
+
+${BROWSER_GUARD_SOURCE}
+${GUARD_SOURCE}
+/**
+ * This app's client, calling its own origin's API from the browser. A call made
+ * on the server (while a Client Component renders there) rejects instead: on the
+ * server, import \`avClient\` from \`@/aventara/server\` or \`@/aventara/universal\`.
+ */
+export const avClient: AvClient = guardedClient(CLIENT);
+
+/** The key a dehydrated value's tag is under: \`{ ${JSON.stringify(tagKey)}: <scalar>, ${JSON.stringify(valueKey)}: <its wire form> }\`. */
+const TAG = ${JSON.stringify(tagKey)};
+
+/** The key a tagged value's wire form is under. */
+const VALUE = ${JSON.stringify(valueKey)};
+
+/** The tag of a plain object holding a ${JSON.stringify(tagKey)} key of its own, kept as data. */
+const OBJECT_TAG = ${JSON.stringify(objectTag)};
+
+/** The scalars a value may be tagged as. */
+const TAGGED_SCALARS: ReadonlySet<string> = new Set<AvBuiltInScalar>([${scalarTags.map((tag) => JSON.stringify(tag)).join(", ")}]);
+
+function isPlainObject(value: unknown): value is Readonly<Record<string, unknown>> {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	const prototype: unknown = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
+function revivedMembers(record: Readonly<Record<string, unknown>>): Record<string, unknown> {
+	return Object.fromEntries(Object.entries(record).map(([key, member]) => [key, avHydrate(member)]));
+}
+
+/**
+ * Revives data that \`avDehydrate\` (from \`@aventara/next\`) made safe to pass
+ * from the server to the browser: each tagged Date, bigint, Uint8Array and
+ * decimal becomes the value this client reads, a decimal this client's own
+ * AvDecimal.
+ * Arrays and plain objects are copied with their members revived; any other
+ * value is returned as it is. Give it to TanStack Query as \`deserializeData\`,
+ * or call it on an SWR \`fallback\`.
+ *
+ * @throws TypeError when a tagged value is not one avDehydrate writes.
+ */
+export function avHydrate(dehydrated: unknown): unknown {
+	if (Array.isArray(dehydrated)) {
+		return dehydrated.map((member: unknown) => avHydrate(member));
+	}
+	if (!isPlainObject(dehydrated)) {
+		return dehydrated;
+	}
+	if (!Object.hasOwn(dehydrated, TAG)) {
+		return revivedMembers(dehydrated);
+	}
+	const tag = dehydrated[TAG];
+	const wire = dehydrated[VALUE];
+	if (Object.keys(dehydrated).length === 2 && Object.hasOwn(dehydrated, VALUE)) {
+		if (tag === OBJECT_TAG && isPlainObject(wire)) {
+			return revivedMembers(wire);
+		}
+		if (typeof tag === "string" && TAGGED_SCALARS.has(tag)) {
+			return decodeScalar(tag as AvBuiltInScalar, wire);
+		}
+	}
+	throw new TypeError(
+		${JSON.stringify(`A value tagged ${JSON.stringify(tagKey)} must be { ${JSON.stringify(tagKey)}: ${tagged}, ${JSON.stringify(valueKey)}: its value }, as avDehydrate writes it.`)},
+	);
+}
+`;
+}
+export const UNIVERSAL_PATH_KEY = "aventara.next.universal";
+export const UNREGISTERED_REFUSAL = 'avClient from @/aventara/universal ran on the server, where it calls this app in process through what ready() registers, and nothing is registered: export register() from src/instrumentation.ts and, when process.env.NEXT_RUNTIME is "nodejs", await ready() from @/aventara/server there.';
+function universalSource(style, accessVerbs) {
+    const from = (module) => JSON.stringify(importSpecifier(module, style));
+    return `${ENTRY_BANNER}
+
+import { io } from ${JSON.stringify(style.importFileExtension === "" ? "next/cache" : "next/cache.js")};
+import { cache } from "react";
+import { AvClient } from ${from(`./${GENERATED_DIRECTORY}/client`)};
+import type { AvFetch } from ${from(`./${GENERATED_DIRECTORY}/runtime/transport`)};
+
+import { avLazy as lazyCall } from ${from(`./${GENERATED_DIRECTORY}/runtime/operation-set`)};
+
+/** The key the server's in-process path is registered under, on globalThis, by ready() from @aventara/next. */
+const SERVER_PATH = Symbol.for(${JSON.stringify(UNIVERSAL_PATH_KEY)});
+
+/** What a call made on a server where nothing is registered is refused with. */
+const UNREGISTERED = ${JSON.stringify(UNREGISTERED_REFUSAL)};
+
+/** Whether this code runs on the server: a page or a worker has a location, a server has none. */
+function onServer(): boolean {
+	return (globalThis as { readonly location?: unknown }).location === undefined;
+}
+
+/** The in-process path ready() registered on this server, or undefined. */
+function serverPath(): AvFetch | undefined {
+	const registered = (globalThis as { readonly [key: symbol]: unknown })[SERVER_PATH];
+	return typeof registered === "function" ? (registered as AvFetch) : undefined;
+}
+
+/** Why a call made here and now is refused; \`undefined\` when it may run. */
+function refusal(): string | undefined {
+	return onServer() && serverPath() === undefined ? UNREGISTERED : undefined;
+}
+
+/** Once Next's \`io()\` lets it: in the browser, the platform's fetch; on the server, the in-process path. */
+async function universalFetch(...request: unknown[]): Promise<unknown> {
+	await ioFirst();
+	const reach = onServer() ? serverPath() : (globalThis as { readonly fetch?: AvFetch }).fetch;
+	if (reach === undefined) {
+		throw new TypeError(onServer() ? UNREGISTERED : "No fetch is available here.");
+	}
+	return (reach as (...request: unknown[]) => unknown)(...request);
+}
+
+type Call = (...args: unknown[]) => unknown;
+
+/** The browser's one client, whose calls are grouped, and the shape \`avClient\` copies. */
+const BROWSER = new AvClient({ fetch: universalFetch as AvFetch });
+
+/**
+ * The client a call made here and now is made on: the browser's one; on the
+ * server, a client of the call's own with grouping off, so the call is sent
+ * alone, from the async context it was made in (the request's, or a scope
+ * nested in it), and shares no queue with any other call.
+ */
+function current(): AvClient {
+	return onServer() ? new AvClient({ fetch: universalFetch as AvFetch, grouping: false }) : BROWSER;
+}
+
+/** On the server, the calls each avLazy made in the request being rendered (React's \`cache\`). */
+const requestCalls = cache((): WeakMap<object, Promise<unknown>> => new WeakMap());
+
+/**
+ * Describe a call now, make it later: the tree's avLazy, which avClient.all
+ * accepts on either side. In the browser it makes the call once and keeps its
+ * answer. On the server it keeps one answer per request: inside a React
+ * request scope (a render), each request makes the call once, in its own
+ * context; where React keeps no request (a route handler, a Server Action),
+ * it keeps nothing, and each await makes the call again.
+ *
+ * @example const posts = avLazy(() => avClient.Post.find.many({}));
+ */
+export function avLazy<T>(run: () => PromiseLike<T>): Promise<T> {
+	const key = {};
+	return lazyCall(() => {
+		if (!onServer()) {
+			return run();
+		}
+		const calls = requestCalls();
+		const made = calls.get(key);
+		if (made !== undefined) {
+			return made as Promise<T>;
+		}
+		const call = Promise.resolve(run());
+		calls.set(key, call);
+		return call;
+	});
+}
+
+${UNIVERSAL_GUARD_SOURCE}
+${GUARD_SOURCE}
+/**
+ * This app's client, on the server and in the browser alike: in the browser it
+ * calls the app's own origin's API; on the server it calls the app in process,
+ * with the request's state, through what \`ready()\` registered at startup
+ * (\`src/instrumentation.ts\`). Its values are the same on both sides, so data
+ * prefetched on the server hydrates in the browser: pass it through
+ * \`avDehydrate\` (\`@aventara/next\`) and \`avHydrate\` (\`@/aventara/client\`).
+ */
+export const avClient: AvClient = ${accessVerbs ? "withServerAccess(" : ""}guardedClient(BROWSER)${accessVerbs ? ")" : ""};
+${accessVerbs ? SERVER_ACCESS_SOURCE : ""}`;
+}
+const UNIVERSAL_ACCESS_KEY = "aventara.next.universal.access";
+const SERVER_ACCESS_SOURCE = `
+/** The key ready() registers avClient.$access under, on globalThis, for the Access verbs on the server. */
+const SERVER_ACCESS = Symbol.for(${JSON.stringify(UNIVERSAL_ACCESS_KEY)});
+
+type AccessVerb = (...args: unknown[]) => unknown;
+
+/** \`$access\`: \`can\` as it is; each Access verb, on the server, through what ready() registered. */
+function serverAccess(verbs: Readonly<Record<string, AccessVerb>>): object {
+	const routed: Record<string, AccessVerb> = {};
+	for (const [name, verb] of Object.entries(verbs)) {
+		routed[name] =
+			name === "can"
+				? verb
+				: (...args) => {
+						if (!onServer()) {
+							return verb(...args);
+						}
+						const registered = (globalThis as { readonly [key: symbol]: unknown })[SERVER_ACCESS] as
+							| Readonly<Record<string, unknown>>
+							| undefined;
+						const server = registered?.[name];
+						return typeof server === "function"
+							? ioFirst().then(() => (server as AccessVerb)(...args))
+							: Promise.reject(new Error(UNREGISTERED));
+					};
+	}
+	return Object.freeze(routed);
+}
+
+/** The client with its \`$access\` routed by \`serverAccess\`. */
+function withServerAccess(client: AvClient): AvClient {
+	const copy: AvClient = Object.create(AvClient.prototype) as AvClient;
+	for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(client))) {
+		Object.defineProperty(
+			copy,
+			key,
+			key === "$access" ? { ...descriptor, value: serverAccess(descriptor.value as Readonly<Record<string, AccessVerb>>) } : descriptor,
+		);
+	}
+	return copy;
+}
+`;
+function refusedAsBuild(step) {
+    try {
+        return step();
+    }
+    catch (error) {
+        if (error instanceof AvClientConfigError ||
+            error instanceof AvGeneratedNameError) {
+            throw new AvBuildError(`the browser client cannot be written: ${error.message}`, { cause: error });
+        }
+        throw error;
+    }
+}
+export async function emitBrowserClient(projectDirectory, layout, source) {
+    const acceptance = await acceptClientContract(JSON.parse(source.canonicalText(source.client)));
+    if (!acceptance.accepted) {
+        throw new AvBuildError(`the ClientContract this build compiled was refused by the client generator: ${acceptance.message}`);
+    }
+    const folder = path.join(projectDirectory, layout.folder);
+    const style = refusedAsBuild(() => resolveModuleStyle({
+        generateAt: folder,
+        entryFile: path.join(folder, layout.entry),
+    }));
+    const entrypoint = refusedAsBuild(() => sameOriginEntrypoint(source.api));
+    const emission = refusedAsBuild(() => emitClientTree(acceptance.contract, entrypoint, {
+        importFileExtension: style.importFileExtension,
+        moduleFormat: style.moduleFormat,
+    }, REGENERATE));
+    const accessVerbs = accessVerbsOf(acceptance.contract).length > 0;
+    const decoder = new TextDecoder();
+    const tree = emission.tree
+        .filter((file) => file.path.startsWith(`${GENERATED_DIRECTORY}/`))
+        .map((file) => ({
+        file: `${layout.folder}/${file.path}`,
+        text: decoder.decode(file.bytes),
+    }));
+    return {
+        files: [
+            {
+                file: `${layout.folder}/${layout.entry}`,
+                text: entrySource(style, accessVerbs),
+            },
+            {
+                file: `${layout.folder}/${layout.universal}`,
+                text: universalSource(style, accessVerbs),
+            },
+            ...tree,
+        ],
+        tree: `${layout.folder}/${GENERATED_DIRECTORY}`,
+        entrypoint: entrypoint.path,
+        warnings: emission.warnings,
+    };
+}
+function filesUnder(projectDirectory, directory) {
+    const root = path.join(projectDirectory, directory);
+    try {
+        return readdirSync(root, { recursive: true, withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => `${directory}/${path
+            .relative(root, path.join(entry.parentPath, entry.name))
+            .split(path.sep)
+            .join("/")}`)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function leftovers(projectDirectory, client) {
+    const written = new Set(client.files.map(({ file }) => file));
+    return filesUnder(projectDirectory, client.tree).filter((file) => !written.has(file) &&
+        carriesGeneratedOwnership(readGeneratedFile(projectDirectory, file) ?? ""));
+}
+export function writeBrowserClient(projectDirectory, client) {
+    let write = "unchanged";
+    for (const { file, text } of client.files) {
+        if (writeGeneratedFile(projectDirectory, file, text) === "written") {
+            write = "written";
+        }
+    }
+    const removed = leftovers(projectDirectory, client);
+    for (const file of removed) {
+        rmSync(path.join(projectDirectory, file));
+    }
+    return { write: removed.length > 0 ? "written" : write, removed };
+}
+export function checkBrowserClient(projectDirectory, client) {
+    for (const { file, text } of client.files) {
+        const current = readGeneratedFile(projectDirectory, file);
+        if (current === undefined) {
+            return { file, what: "is missing" };
+        }
+        if (current !== text) {
+            return {
+                file,
+                what: "is stale: the ClientContract or the project's module settings changed since it was written",
+            };
+        }
+    }
+    const [left] = leftovers(projectDirectory, client);
+    return left === undefined
+        ? undefined
+        : {
+            file: left,
+            what: "is left from an earlier ClientContract's browser client",
+        };
+}