@aventara/build 1.0.0-rc.4 → 1.0.0-rc.9

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # @aventara/build
 
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- 99278e4: `aventara-build` reads a Next.js project's files from `src/aventara/` and, with `--client`, writes its browser client.
+
+  - A project whose `package.json` depends on `@aventara/next` keeps its configuration and adapter in
+    `src/aventara/config.ts` and `src/aventara/adapter.ts`; the build runs them there, and a configuration that imports no
+    Resource tree has its generated files in `src/aventara/generated/`. Every other project keeps
+    `src/aventara.config.ts` and `src/aventara.adapter.ts`, unchanged. A missing file is named with where the project's
+    host keeps it, and a project depending on both `@aventara/nest` and `@aventara/next` is refused in one sentence.
+  - `aventara-build --client` also writes the browser client from the ClientContract it has just compiled, with no
+    running server: `src/aventara/client.ts` and the client's modules under `src/aventara/generated/`, the same modules
+    `avclient generate` writes for that ClientContract except that the entrypoint is the app's own `api` on the page's
+    origin (`/api`) and the regenerate instructions. Its imports are spelled as the project's `tsconfig.json` says, and nothing it writes imports
+    `@aventara/client`.
+  - `src/aventara/client.ts` exports `avClient` and `avHydrate`, and re-exports every name `avclient generate`'s
+    `AvClient.ts` exports besides its default (`AvClient`, the Resource types, the enums, `AvDecimal`, the error
+    classes), so `import { AvDecimal } from "@/aventara/client"` works. The generated files and the contract-mismatch
+    error say to regenerate with `aventara-build --client` (the project's `aventara:prepare` script). `avClient` calls the API from the browser; a call made
+    on the server (a Client Component rendering there) rejects with one sentence pointing to `@/aventara/server` and
+    `@/aventara/universal`, and sends nothing. `avHydrate` revives data `avDehydrate` sends from the server: tagged
+    dates, `bigint`s, byte arrays and decimals become `Date`, `bigint`, `Uint8Array` and the client's own `AvDecimal`,
+    for TanStack Query's `deserializeData` or an SWR `fallback`.
+  - `aventara-build --check --client` checks those files too: a missing or stale one, or one an earlier ClientContract's
+    client left, exits 1 naming it. `--client` is refused in a NestJS project, whose frontends keep using
+    `avclient generate`, which is unchanged.
+  - `@aventara/client` gains an `@aventara/client/internal` entry, which `@aventara/build` reads the generator through.
+    It is not public API.
+
+- 8c40b81: `aventara new` and `aventara init` now scaffold Next.js apps.
+
+  - `aventara new <name> --host next` runs `create-next-app@latest` (TypeScript, the App Router under `src/`, the `@/*`
+    alias, no install of its own), then the same `init` steps, then the install. create-next-app asks its own questions
+    on your terminal; with `--yes` it takes its defaults. Its own flags go after `--`, as they are:
+    `aventara new my-app --host next --yes -- --tailwind`. `--skip-git` becomes its `--disable-git`. Without a terminal,
+    `--yes` is required. `--host` defaults to `nest`: a NestJS project is scaffolded exactly as before.
+  - `aventara init` tells the host by `package.json`: `@nestjs/core` is NestJS 12, `next` is Next.js 16, and a project
+    that depends on both or neither is refused in one sentence, with nothing written. A Next.js app needs `src/app/`
+    and the `@/*` → `./src/*` path in `tsconfig.json`, and no ORM yet.
+  - In a Next.js app, init writes `src/aventara/config.ts`, `src/aventara/adapter.ts`, `src/aventara/server.ts`
+    (`Aventara()`, exporting `handlers`, `avClient`, `avApp` and `ready`), `src/app/api/[...aventara]/route.ts`,
+    `src/instrumentation.ts` (awaiting `ready()` on the Node.js runtime) and `src/prisma.ts`, with Prisma's schema and
+    config. `aventara:prepare` ends with `aventara-build --client` and runs on `postinstall` and `prebuild`; the files it
+    generates (`src/aventara/generated/`, `src/aventara/client.ts`, `src/aventara/universal.ts`) are added to
+    `.gitignore`. An instrumentation file of your own is never replaced: the lines to add are printed.
+  - Each host package now declares its project layout in its manifest (`"aventara": { "host": … }`). The CLI scaffolds
+    from it and `aventara-build` reads its paths from it, so the two always agree.
+
+- 33493e4: `@/aventara/universal` and `avDehydrate`: data prefetched on the server keeps its values in the browser.
+
+  - `aventara-build --client` also writes `src/aventara/universal.ts`. Its `avClient` has the same types as
+    `@/aventara/client`'s and runs on both sides: in the browser it calls the app's `/api`; on the server it answers the
+    same request in process, with the request's `state`, so a `Date`, a `bigint` or a decimal comes back the same on
+    either side. It needs `src/instrumentation.ts` to await `ready()`; on a server where nothing ran it, a call is
+    refused with one sentence naming `instrumentation.ts` and `ready()`. Each call first awaits Next's `io()`, as
+    `@aventara/next`'s `avClient` does, so under Cache Components a page's call runs at request time, never while
+    `next build` prerenders it (the page needs `<Suspense>`, `"use cache"` or `export const instant = false`). Like
+    the other generated files, it imports nothing from `@aventara/client` or `@aventara/next` (only `io` from
+    `next/cache`), and `aventara-build --check --client` checks it.
+  - `ready()` now also registers the in-process path the universal `avClient` takes on the server.
+  - `@aventara/next` exports `avDehydrate`. It turns each `Date`, `bigint`, `Uint8Array` and decimal in a result into a
+    tagged plain object that React can pass from a Server Component to a Client Component, where `avHydrate` from
+    `@/aventara/client` turns it back. Use it as TanStack Query's `dehydrate(queryClient, { serializeData: avDehydrate })`
+    with `deserializeData: avHydrate` on the browser's `QueryClient`, or on an SWR `fallback`.
+
+- Updated dependencies [99278e4]
+- Updated dependencies [205a379]
+- Updated dependencies [a0bb05e]
+- Updated dependencies [86ab319]
+- Updated dependencies [fdf52e6]
+  - @aventara/client@1.0.0-rc.9
+  - @aventara/core@1.0.0-rc.9
+
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- 1c8e4ee: `aventara-build --check` says what changed when the prebuilt Contracts file is stale, in the same words as the
+  `AVENTARA_PREBUILT_STALE` warning at startup. Before, anything outside a single Resource read "an input that belongs
+  to no single Resource, the core version or the file format changed". Now it names the versions or the inputs:
+
+  ```text
+  aventara-build: src/generated/aventara/contracts.generated.ts is stale: it was built by @aventara/core 1.0.0-rc.7, and this is 1.0.0-rc.8. Run aventara-build (npm run aventara:prepare) and deploy the file it writes.
+  aventara-build: src/generated/aventara/contracts.generated.ts is stale: Resource User changed and the configuration or model outside the Resources changed since it was written. Run aventara-build (npm run aventara:prepare) and deploy the file it writes.
+  ```
+
+  It also names a file format or protocol version that differs, the Resources that are new or gone, and a file that
+  no longer reads as a prebuilt Contracts file.
+
+- Updated dependencies [1c8e4ee]
+  - @aventara/core@1.0.0-rc.8
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [f917c1c]
+  - @aventara/core@1.0.0-rc.7
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- Updated dependencies [1cf72e0]
+  - @aventara/core@1.0.0-rc.6
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- Updated dependencies [4795ff1]
+- Updated dependencies [9e178ca]
+  - @aventara/core@1.0.0-rc.5
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/README.md

@@ -100,15 +100,50 @@ diagnostic is printed with its path and documentation link, nothing is written,
 Because the build runs `src/aventara.config.ts`, everything it imports runs at build time too. Keep its top level free of
 side effects (no connection, no request). A value read from `process.env` is read when the build runs.
 
+## Next.js projects
+
+A project whose `package.json` depends on `@aventara/next` keeps everything Aventara in one folder, `src/aventara/`. The
+build runs `src/aventara/config.ts` and `src/aventara/adapter.ts` there instead of `src/aventara.config.ts` and
+`src/aventara.adapter.ts`, and a configuration that imports no Resource tree has its files in `src/aventara/generated/`.
+Every other project keeps the paths above.
+
+### `--client`
+
+```bash
+aventara-build --client
+```
+
+In a Next.js project, `--client` also writes the browser client, from the ClientContract the build has just compiled,
+so no running server is needed:
+
+| File | What it holds |
+|---|---|
+| `src/aventara/client.ts` | `avClient`, the typed client calling the app's own `api` (`/api`) from the browser, and `avHydrate`; and every name `avclient generate`'s `AvClient.ts` exports besides its default: `AvClient`, the Resource types, the enums, `AvDecimal` and the error classes |
+| `src/aventara/universal.ts` | `avClient` for both sides: in the browser it calls the app's own `api`, on the server it calls the app in process, through what `ready()` from `@aventara/next` registers in `src/instrumentation.ts`, with that request's state |
+| `src/aventara/generated/` (the client's modules) | the same modules `avclient generate` writes for the same ClientContract, but with the app's own `api` as the entrypoint, and saying to regenerate them with `aventara-build --client` |
+
+Import it as `@/aventara/client` in Client Components, and `@/aventara/universal` in code that runs on both sides (a
+TanStack Query `queryFn` prefetched on the server, for example). The files import nothing from `@aventara/client` or
+`@aventara/next`, so the app needs no generator at run time. `avClient` calls the API from the browser only: a call made on the server, while a
+Client Component renders there, is refused with a sentence pointing to `@/aventara/server` and `@/aventara/universal`.
+The universal `avClient` answers the same values on both sides; on a server where `ready()` has not run, a call is
+refused with a sentence naming `src/instrumentation.ts` and `ready()`. `avHydrate` revives data `avDehydrate` sent from the server (dates, `bigint`s, byte arrays and decimals, a decimal as
+the client's own `AvDecimal`), for TanStack Query's `deserializeData` or an SWR `fallback`.
+
+`avclient generate` stays the way to generate a client for a separate frontend. In a NestJS project `--client` is
+refused.
+
 ## `--check`
 
 ```bash
 aventara-build --check
+aventara-build --check --client
 ```
 
 Writes nothing. It exits 0 when the three files on disk are the ones a build would write now, and 1 on the first that is
-missing or stale, naming it (and, for the Contracts, the Resources whose configuration or model changed). Run it in CI
-before a deploy.
+missing or stale, naming it (and, for the Contracts, the Resources whose configuration or model changed). With
+`--client`, the browser client's files are checked too, after the Contracts: a missing or stale file, or one an earlier
+ClientContract's client left, exits 1. Run it in CI before a deploy.
 
 ## Using the file
 

package/dist/cli.js

@@ -1,20 +1,23 @@
 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 { findProjectModules, loadProjectModules, PROJECT_MODULES, } from "./project/project-modules.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 --check    write nothing; exit 1 when one is missing or stale
+  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:
 
@@ -28,36 +31,50 @@ Run it from the project's root. It writes, in this order:
 
 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 src/generated/aventara/.
+src/generated), else to ${PROJECT_LAYOUTS.nest.generated}/ (${PROJECT_LAYOUTS.next.generated}/
+in a Next.js project).
 
-It runs ${PROJECT_MODULES.config}.ts (the configuration, its
-\`aventaraConfig\` export or its default, without \`adapter\`) and
-${PROJECT_MODULES.adapter}.ts (its default export: the adapter's
-description, 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.
+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. 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 };
-}
-function listed(names) {
-    return names.length < 2
-        ? names.join("")
-        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+    return { check, client };
 }
 function counted(count) {
     return `${count} Resource${count === 1 ? "" : "s"}`;
@@ -82,9 +99,14 @@ export async function runBuild(argv, projectDirectory, output) {
         return 0;
     }
     try {
-        const { check } = parse(argv);
-        const files = findProjectModules(projectDirectory);
-        const generated = resolveGeneratedFiles(projectDirectory, files.configFile);
+        const { check, client } = parse(argv);
+        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))));
@@ -133,13 +155,40 @@ export async function runBuild(argv, projectDirectory, output) {
         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);
+        const contracts = await checkContractsFile(projectDirectory, generated.contracts, compiled, project.internal.prebuiltFileChanges);
         if (contracts.kind === "fresh") {
-            output.stdout(`aventara-build: ${generated.resources}, ${generated.computedFields} and ${generated.contracts} are up to date.`);
+            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({
@@ -147,18 +196,7 @@ export async function runBuild(argv, projectDirectory, output) {
             deploy: true,
             what: contracts.kind === "missing"
                 ? "is missing"
-                : `is stale: ${[
-                    ...(contracts.resources.length === 0
-                        ? []
-                        : [
-                            `the inputs of ${listed(contracts.resources)} changed since it was written`,
-                        ]),
-                    ...(contracts.shared
-                        ? [
-                            "an input that belongs to no single Resource, the core version or the file format changed",
-                        ]
-                        : []),
-                ].join("; ")}`,
+                : `is stale: ${contracts.changes.join("; ")}`,
         }));
         return 1;
     }

package/dist/client/client-file.js

@@ -0,0 +1,328 @@
+import { readdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { AvClientConfigError, AvGeneratedNameError, acceptClientContract, 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: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown {
+	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\`, once \`io()\` lets it run, rejected instead of run when \`refusal()\` names why. */
+function guarded(call: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown {
+	return (...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. */
+function guardedTree(tree: object): object {
+	const copy: Record<string, unknown> = Object.create(Object.getPrototypeOf(tree) as object | null);
+	for (const [key, value] of Object.entries(tree)) {
+		copy[key] = typeof value === "function" ? guarded(value as (...args: unknown[]) => unknown) : guardedTree(value as object);
+	}
+	return Object.freeze(copy);
+}
+
+/**
+ * The client with every call that sends a request guarded; \`tx\` builds
+ * deferred operations and sends nothing, so it is kept as it is.
+ */
+function guardedClient(client: AvClient): AvClient {
+	const copy: AvClient = Object.create(AvClient.prototype) as AvClient;
+	for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(client))) {
+		const value: unknown = descriptor.value;
+		Object.defineProperty(copy, key, {
+			...descriptor,
+			value:
+				key === "tx"
+					? value
+					: typeof value === "function"
+						? guarded(value as (...args: unknown[]) => unknown)
+						: guardedTree(value as object),
+		});
+	}
+	return copy;
+}
+`;
+function entrySource(style) {
+    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")}
+/** 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;
+}
+
+${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(new AvClient());
+
+/** 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) {
+    const from = (module) => JSON.stringify(importSpecifier(module, style));
+    return `${ENTRY_BANNER}
+
+import { io } from ${JSON.stringify(style.importFileExtension === "" ? "next/cache" : "next/cache.js")};
+import { AvClient } from ${from(`./${GENERATED_DIRECTORY}/client`)};
+import type { AvFetch } from ${from(`./${GENERATED_DIRECTORY}/runtime/transport`)};
+
+/** 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;
+}
+
+/** In the browser, the platform's fetch; on the server, the in-process path. */
+function universalFetch(...request: unknown[]): unknown {
+	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);
+}
+
+${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 = guardedClient(new AvClient({ fetch: universalFetch as AvFetch }));
+`;
+}
+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 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) },
+            {
+                file: `${layout.folder}/${layout.universal}`,
+                text: universalSource(style),
+            },
+            ...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",
+        };
+}

package/dist/contracts/contracts-file.js

@@ -5,7 +5,7 @@ import { readGeneratedFile, writeGeneratedFile, } from "../project/generated-fil
 export function writeContractsFile(projectDirectory, contractsFile, compiled) {
     return writeGeneratedFile(projectDirectory, contractsFile, compiled.source);
 }
-export async function checkContractsFile(projectDirectory, contractsFile, compiled) {
+export async function checkContractsFile(projectDirectory, contractsFile, compiled, changesOf) {
     const file = path.join(projectDirectory, contractsFile);
     const text = readGeneratedFile(projectDirectory, contractsFile);
     if (text === undefined) {
@@ -15,9 +15,21 @@ export async function checkContractsFile(projectDirectory, contractsFile, compil
         return { kind: "fresh" };
     }
     const previous = await previousContracts(projectDirectory, file);
-    return previous === undefined
-        ? { kind: "stale", resources: [], shared: true }
-        : difference(previous, compiled.prebuilt);
+    if (previous === undefined) {
+        return {
+            kind: "stale",
+            changes: ["it could not be read as a prebuilt Contracts file"],
+        };
+    }
+    const changes = changesOf(previous, compiled.prebuilt);
+    return {
+        kind: "stale",
+        changes: changes.length > 0
+            ? changes
+            : [
+                "its text is not what this build writes, though it records the same core version, file format and inputs",
+            ],
+    };
 }
 async function previousContracts(projectDirectory, file) {
     const jiti = createJiti(pathToFileURL(path.join(projectDirectory, "package.json")).href, { moduleCache: false, fsCache: false, interopDefault: false });
@@ -31,21 +43,3 @@ async function previousContracts(projectDirectory, file) {
         return undefined;
     }
 }
-function difference(previous, current) {
-    const before = previous.fingerprints.resources;
-    const after = current.fingerprints.resources;
-    const resources = [
-        ...new Set([...Object.keys(before), ...Object.keys(after)]),
-    ]
-        .filter((name) => before[name] !== after[name])
-        .sort();
-    const shared = previous.fingerprints.shared !== current.fingerprints.shared ||
-        previous.core !== current.core ||
-        previous.protocol !== current.protocol ||
-        previous.format !== current.format;
-    return {
-        kind: "stale",
-        resources,
-        shared: shared || resources.length === 0,
-    };
-}

package/dist/contracts/prebuilt-contracts.compiler.js

@@ -31,12 +31,14 @@ function diagnosticLines(diagnostics) {
 export async function compilePrebuiltContracts(project) {
     const { core, internal, config, description } = project;
     let contracts;
+    let api;
     try {
         const framework = await core.createFramework({
             ...config,
             adapter: buildTimeAdapter(description),
         });
         contracts = framework.contracts;
+        api = framework.api;
     }
     catch (error) {
         if (error instanceof core.AvConstructionError) {
@@ -45,5 +47,10 @@ export async function compilePrebuiltContracts(project) {
         throw error;
     }
     const prebuilt = await internal.prebuiltContractsOf(description.model, config, contracts);
-    return { prebuilt, source: internal.emitPrebuiltContracts(prebuilt) };
+    return {
+        prebuilt,
+        source: internal.emitPrebuiltContracts(prebuilt),
+        client: contracts.client,
+        api,
+    };
 }

package/dist/project/generated-files.resolver.js

@@ -28,12 +28,15 @@ function treeSpecifier(source) {
     }
     return undefined;
 }
-export function resolveGeneratedFiles(projectDirectory, configFile) {
+export function resolveGeneratedFiles(projectDirectory, configFile, defaultDirectory = DEFAULT_DIRECTORY) {
+    const fallback = defaultDirectory === DEFAULT_DIRECTORY
+        ? DEFAULT_GENERATED_FILES
+        : filesIn(defaultDirectory);
     const configPath = path.join(projectDirectory, configFile);
     const source = ts.createSourceFile(configPath, readFileSync(configPath, "utf8"), ts.ScriptTarget.Latest, false);
     const specifier = treeSpecifier(source);
     if (specifier === undefined) {
-        return DEFAULT_GENERATED_FILES;
+        return fallback;
     }
     const module = path.resolve(path.dirname(configPath), specifier);
     const directory = path.relative(projectDirectory, path.dirname(module));
@@ -44,5 +47,5 @@ export function resolveGeneratedFiles(projectDirectory, configFile) {
     return inside &&
         path.basename(module).replace(/\.[cm]?[jt]s$/, "") === TREE_MODULE
         ? filesIn(directory.split(path.sep).join("/"))
-        : DEFAULT_GENERATED_FILES;
+        : fallback;
 }

package/dist/project/host.catalog.generated.js

@@ -0,0 +1,32 @@
+export const HOST_CATALOG = [
+    {
+        "alias": "nest",
+        "label": "NestJS",
+        "package": "@aventara/nest",
+        "framework": {
+            "package": "@nestjs/core",
+            "range": "^12.0.0"
+        },
+        "layout": {
+            "config": "src/aventara.config",
+            "adapter": "src/aventara.adapter",
+            "generated": "src/generated/aventara"
+        }
+    },
+    {
+        "alias": "next",
+        "label": "Next.js",
+        "package": "@aventara/next",
+        "framework": {
+            "package": "next",
+            "range": ">=16.4 <17"
+        },
+        "layout": {
+            "config": "src/aventara/config",
+            "adapter": "src/aventara/adapter",
+            "generated": "src/aventara/generated",
+            "client": "src/aventara/client.ts",
+            "universal": "src/aventara/universal.ts"
+        }
+    }
+];

package/dist/project/project-layout.resolver.js

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { AvBuildError } from "../build.error.js";
+import { HOST_CATALOG } from "./host.catalog.generated.js";
+const FALLBACK_HOST = "nest";
+function clientLayoutOf(entry) {
+    const { client, universal } = entry.layout;
+    if (client === undefined && universal === undefined) {
+        return undefined;
+    }
+    if (client === undefined ||
+        universal === undefined ||
+        path.posix.dirname(client) !== path.posix.dirname(universal)) {
+        throw new AvBuildError(`${entry.package} declares its browser client at ${client ?? "nowhere"} and its universal entry at ${universal ?? "nowhere"}; the build writes both into one folder, so a host declares both, side by side.`);
+    }
+    return {
+        folder: path.posix.dirname(client),
+        entry: path.posix.basename(client),
+        universal: path.posix.basename(universal),
+    };
+}
+function layoutOf(entry) {
+    const client = clientLayoutOf(entry);
+    return {
+        host: entry.alias,
+        described: entry.alias === FALLBACK_HOST
+            ? `a ${entry.label} project`
+            : `a ${entry.label} project (it depends on ${entry.package})`,
+        config: entry.layout.config,
+        adapter: entry.layout.adapter,
+        generated: entry.layout.generated,
+        ...(client === undefined ? {} : { client }),
+    };
+}
+export const PROJECT_LAYOUTS = Object.fromEntries(HOST_CATALOG.map((entry) => [entry.alias, layoutOf(entry)]));
+const DEPENDENCY_LISTS = ["dependencies", "devDependencies"];
+function hostsOf(projectDirectory) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(projectDirectory, "package.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const lists = DEPENDENCY_LISTS.map((list) => typeof manifest === "object" && manifest !== null
+        ? manifest[list]
+        : undefined);
+    return HOST_CATALOG.filter((entry) => lists.some((list) => typeof list === "object" &&
+        list !== null &&
+        Object.hasOwn(list, entry.package)));
+}
+export function resolveProjectLayout(projectDirectory) {
+    const hosts = hostsOf(projectDirectory);
+    if (hosts.length > 1) {
+        throw new AvBuildError(`${projectDirectory}/package.json depends on both ${hosts.map((host) => host.package).join(" and ")}, so it is not clear where the configuration and the adapter are. A project hosts its framework in one of them; remove the other.`);
+    }
+    const [host] = hosts;
+    return PROJECT_LAYOUTS[host === undefined ? FALLBACK_HOST : host.alias];
+}

package/dist/project/project-modules.loader.js

@@ -5,18 +5,14 @@ import { createJiti } from "jiti";
 import { AvBuildError } from "../build.error.js";
 const EXTENSIONS = [".js", ".ts", ".mjs", ".cjs", ".mts", ".cts"];
 const EXTENSIONS_AS_LISTED = [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
-export const PROJECT_MODULES = {
-    config: "src/aventara.config",
-    adapter: "src/aventara.adapter",
-};
 const CONFIG_EXPORTS = ["aventaraConfig", "default"];
-function projectFile(projectDirectory, module) {
+function projectFile(projectDirectory, module, layout) {
     const present = EXTENSIONS.map((extension) => `${module}${extension}`).filter((file) => statSync(path.join(projectDirectory, file), {
         throwIfNoEntry: false,
     })?.isFile() === true);
     if (present.length === 0) {
         const [first, ...others] = EXTENSIONS_AS_LISTED;
-        throw new AvBuildError(`no ${module}${first}, ${others.slice(0, -1).join(", ")} or ${others.at(-1)} in ${projectDirectory}. Run aventara-build from the project's root (the aventara:prepare script does).`);
+        throw new AvBuildError(`no ${module}${first}, ${others.slice(0, -1).join(", ")} or ${others.at(-1)} in ${projectDirectory}, where ${layout.described} keeps it. Run aventara-build from the project's root (the aventara:prepare script does).`);
     }
     if (present.length > 1) {
         throw new AvBuildError(`${present.slice(0, -1).join(", ")} and ${present.at(-1)} are all ${module}; keep one and delete the other${present.length > 2 ? "s" : ""}.`);
@@ -99,10 +95,10 @@ async function projectCore(jiti) {
         throw new AvBuildError(`@aventara/core could not be loaded from the project (${error instanceof Error ? error.message.split("\n", 1)[0] : String(error)}); install it beside @aventara/build.`, { cause: error });
     }
 }
-export function findProjectModules(projectDirectory) {
+export function findProjectModules(projectDirectory, layout) {
     return {
-        configFile: projectFile(projectDirectory, PROJECT_MODULES.config),
-        adapterFile: projectFile(projectDirectory, PROJECT_MODULES.adapter),
+        configFile: projectFile(projectDirectory, layout.config, layout),
+        adapterFile: projectFile(projectDirectory, layout.adapter, layout),
     };
 }
 export async function loadProjectModules(projectDirectory, { configFile, adapterFile }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/build",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.9",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Compiles an Aventara application's Contracts at build time, for serverless and edge cold starts.",
   "type": "module",
@@ -16,21 +16,23 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@aventara/client": "1.0.0-rc.9",
     "jiti": "2.7.0"
   },
   "peerDependencies": {
-    "@aventara/core": "1.0.0-rc.4",
+    "@aventara/core": "1.0.0-rc.9",
     "typescript": ">=5.7.0 <7"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/core": "1.0.0-rc.4",
+    "@aventara/core": "1.0.0-rc.9",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },
   "scripts": {
+    "prebuild": "node ../../scripts/build/host-catalog.generator.ts --out src/project/host.catalog.generated.ts",
     "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",