@aventara/build 1.0.0-rc.11 → 1.0.0-rc.13

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @aventara/build
 
+## 1.0.0-rc.13
+
+### Minor Changes
+
+- a4569dd: In a Next.js project, `aventara-build --client` gives the browser client hooks from `src/aventara/client-options.ts`
+  (or `.js`; another extension is refused by name): its default export, `{ onCall, onSuccess, onError }`, typed with
+  `satisfies Pick<AvClientOptions, "onCall" | "onSuccess" | "onError">` (`AvClientOptions` from `@/aventara/client`).
+  `@/aventara/client` and `@/aventara/universal` import it and give its hooks to every client they make, the browser's
+  one and each call's own on the server; without the file both are written as before. The entries keep their own
+  `fetch`, `grouping` and entrypoint: in the file those are type errors naming the entry, and are ignored at run time.
+  The file is bundled into the browser too, so it holds no secret and imports nothing server-only. On the server
+  `onCall`'s headers reach the in-process request, while its state still comes from the request being served.
+  The hooks read the default export when they run, never when the entries load, so the file may import from
+  `@/aventara/client` (an error class); a file with no default export leaves the client working without hooks, with one
+  warning (`AVENTARA_CLIENT_OPTIONS_NO_DEFAULT`). `@/aventara/server` is not an `AvClient` and takes no hooks. Adding or removing the file makes `--check` find both
+  entries stale.
+
+### Patch Changes
+
+- 5c65195: `aventara new` and `aventara init` now add a `typecheck` script, so a monorepo's `turbo typecheck` reaches the new project: `tsc --noEmit` in a NestJS project, `next typegen && tsc --noEmit` in a Next.js one. A `typecheck` script the project already has is kept as it is. The agent skill's "Before you finish" runs it.
+
+  `aventara-build` no longer leaves a project whose `tsc` reports `Type 'AvModel' does not satisfy the constraint 'AvAdapterModel'` in every Resource file, which hid the real error. A run that fails (or is interrupted) now changes no generated file, the Next.js browser client included: each keeps what the last successful run wrote. The failure prints before the run's other lines. Each file is replaced in one step, and a second run started while one is writing the same project is refused. When the configuration's computed fields cannot be read and the project does not type-check (read as `tsc -p .` reads it), the build prints those type errors first and keeps `computed-fields.generated.ts` as it was, instead of rewriting it to state nothing. A file that does state nothing (a configuration that is not a literal) now types its model correctly. If you see that cascade from an older build, run `aventara:prepare` again and fix the first error it prints.
+
+- Updated dependencies [6c3e25c]
+- Updated dependencies [33419de]
+- Updated dependencies [2aaa27d]
+- Updated dependencies [f3b291f]
+- Updated dependencies [2aaa27d]
+- Updated dependencies [e4e8abd]
+- Updated dependencies [e662048]
+- Updated dependencies [f3b291f]
+- Updated dependencies [f3b291f]
+- Updated dependencies [6c3e25c]
+- Updated dependencies [6c3e25c]
+- Updated dependencies [73aa797]
+- Updated dependencies [a6cebba]
+- Updated dependencies [e6495a0]
+- Updated dependencies [a708188]
+- Updated dependencies [a9260d2]
+  - @aventara/core@1.0.0-rc.13
+  - @aventara/client@1.0.0-rc.13
+
+## 1.0.0-rc.12
+
+### Patch Changes
+
+- Updated dependencies [afd5eda]
+- Updated dependencies [fdeee8a]
+  - @aventara/client@1.0.0-rc.12
+  - @aventara/core@1.0.0-rc.12
+
 ## 1.0.0-rc.11
 
 ### Patch Changes

package/README.md

@@ -77,8 +77,11 @@ configuration's TypeScript type, after it wrote the tree, and writes them to `co
 adapter's discovery artifact imports that file as its sibling (its generate step is given `--config src/aventara.config.ts`), so a
 variant's guards, pipes and filters, which run before compute, may leave exactly those fields out of a create. Where the
 configuration is not a literal (a wide `AvConfig` annotation, a conditional spread), the build prints where and the
-file states nothing (`null`): those stages may then leave any create field out. A server warns
-`AVENTARA_STALE_GENERATED_TYPES` at startup when the configuration computes other fields than the file says.
+file states nothing (`null`): those stages may then leave any create field out. When the configuration is not read and
+the configuration or a Resource file it imports does not type-check either, the build prints those type errors first
+(the project read as `tsc -p .` reads it) and leaves the file as it was: fix them, or write the configuration `as const`,
+whichever kept it from being read. `--check` then exits 1: the file cannot be judged until they are fixed. A server warns `AVENTARA_STALE_GENERATED_TYPES` at startup when the
+configuration computes other fields than the file says.
 
 ### The Contracts
 
@@ -95,7 +98,15 @@ description holds, and writes `src/generated/aventara/contracts.generated.ts`, w
 keep it out of git, as the scaffold's `.gitignore` does, and never edit it.
 
 A configuration that a server would refuse at startup fails the build instead: every `CONFIG_…` and `COMPILER_…`
-diagnostic is printed with its path and documentation link, nothing is written, and the command exits 1.
+diagnostic is printed with its path and documentation link, and the command exits 1. A run that fails, for this or any
+other reason (Ctrl-C included), prints why before anything else and changes no generated file, the browser client's
+included: each keeps what the last run that succeeded wrote (a fresh project gets none). Each file is replaced in one
+step, never left half-written, and one run at a time writes a project's files: a second, started while the first
+writes, is refused (the lock is `node_modules/.cache/aventara-build/build.lock`; a dead run's is taken over).
+
+`Type 'AvModel' does not satisfy the constraint 'AvAdapterModel'` in every Resource file means the generated files and
+your configuration are out of step: `aventara:prepare` failed or has not run since a change. Run it, and fix the first
+error it prints.
 
 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.
@@ -136,6 +147,38 @@ The universal `avClient` answers the same values on both sides; on a server wher
 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`.
 
+### The client's hooks: `src/aventara/client-options.ts`
+
+To give the browser client hooks (`onCall`, `onSuccess`, `onError`, see `@aventara/client`'s README), export them from
+`src/aventara/client-options.ts` (or `.js`; any other extension, `.tsx` and `.mts` included, is refused, since the
+entries must import it under webpack and Turbopack alike):
+
+```ts
+import type { AvClientOptions } from "@/aventara/client";
+
+export default {
+	onCall: () => ({ headers: { "X-Tenant": "acme" } }),
+	onError: (call, error) => console.warn(call.label, error),
+} satisfies Pick<AvClientOptions, "onCall" | "onSuccess" | "onError">;
+```
+
+- When the file is there, `client.ts` and `universal.ts` import it and give its default export's hooks to every
+  `AvClient` they make: the browser's one, and on the server the one each `@/aventara/universal` call gets. Without
+  the file they are written as before.
+- The hooks read the file's default export when they run, never when the entries load, so the file may import from
+  `@/aventara/client` (an error class for `instanceof`). A file with no default export leaves the client working
+  without hooks, with one warning (`AVENTARA_CLIENT_OPTIONS_NO_DEFAULT`).
+- The entries keep their own `fetch` and `grouping`, and the default entrypoint: a `fetch`, `grouping` or
+  `entrypoint` in the file is a type error naming the entry that sets it, and is ignored at run time.
+- The file is bundled into the browser too, since `client.ts` imports it. Import nothing server-only into it and keep
+  no secret there; when a hook must act differently on the server, branch on `typeof window`.
+- On the server, `@/aventara/universal` calls the app in process: `onCall`'s headers reach that request, but its
+  state is seeded from the request being served, as every server call's is, so a header added there signs no one in.
+  In the browser they are on the HTTP request, where your `state` reads them like any other header.
+- `@/aventara/server`'s `avClient` is the Framework's own in-process client, not an `AvClient`: the file does not reach
+  it.
+- Adding or removing the file changes both entries: run the build again (`--check` finds them stale).
+
 `avclient generate` stays the way to generate a client for a separate frontend. In a NestJS project `--client` is
 refused.
 

package/dist/cli.js

@@ -1,16 +1,18 @@
 import path from "node:path";
+import ts from "typescript";
 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 { checkContractsFile } from "./contracts/contracts-file.js";
 import { compilePrebuiltContracts } from "./contracts/prebuilt-contracts.compiler.js";
-import { readGeneratedFile, writeGeneratedFile, } from "./project/generated-file.js";
+import { acquireBuildLock } from "./project/build.lock.js";
+import { generatedFileBatch, readGeneratedFile, } 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 { importSuffixOf, projectCompilerOptions, projectSourceFiles, } 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.
@@ -91,6 +93,36 @@ function counted(count) {
 function wrote(written, file, detail) {
     return `aventara-build: ${written === "written" ? "wrote" : "unchanged:"} ${file}${detail === undefined ? "" : ` (${detail})`}.`;
 }
+function defectText(error) {
+    return (error instanceof Error && error.stack) || String(error);
+}
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+function restoreOnSignal(undo) {
+    const stop = () => {
+        for (const signal of SIGNALS) {
+            process.removeListener(signal, onSignal);
+        }
+    };
+    const onSignal = (signal) => {
+        stop();
+        undo();
+        process.kill(process.pid, signal);
+    };
+    for (const signal of SIGNALS) {
+        process.once(signal, onSignal);
+    }
+    return stop;
+}
+const LISTED_TYPE_ERRORS = 10;
+function typeErrors(projectDirectory, errors) {
+    const listed = ts.formatDiagnostics(errors.slice(0, LISTED_TYPE_ERRORS), {
+        getCanonicalFileName: (file) => file,
+        getCurrentDirectory: () => projectDirectory,
+        getNewLine: () => "\n",
+    });
+    const more = errors.length - LISTED_TYPE_ERRORS;
+    return `${listed.trimEnd()}${more > 0 ? `\n(+${more} more)` : ""}`;
+}
 function checked(projectDirectory, file, text, stale) {
     const current = readGeneratedFile(projectDirectory, file);
     return current === undefined
@@ -99,8 +131,8 @@ function checked(projectDirectory, file, text, stale) {
             ? 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" : ""}.`;
+function refusal({ file, what, deploy, remedy }) {
+    return `aventara-build: ${file} ${what}. ${remedy ?? `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")) {
@@ -108,12 +140,30 @@ export async function runBuild(argv, projectDirectory, output) {
         return 0;
     }
     let restoreEnv;
+    const lines = [];
+    const note = (text) => {
+        lines.push({ text });
+    };
+    const noteWrite = (text) => {
+        lines.push({ text, write: true });
+    };
+    const batch = generatedFileBatch(projectDirectory);
+    let failed = false;
+    let releaseLock;
+    let stopSignals;
     try {
         const { check, client } = parse(argv);
+        if (!check) {
+            releaseLock = acquireBuildLock(projectDirectory);
+            stopSignals = restoreOnSignal(() => {
+                batch.restore();
+                releaseLock?.();
+            });
+        }
         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).`);
+            note(`aventara-build: environment from ${listed(env.loaded)} (a variable already set keeps its value).`);
         }
         const layout = resolveProjectLayout(projectDirectory);
         const clientLayout = client ? layout.client : undefined;
@@ -126,7 +176,7 @@ export async function runBuild(argv, projectDirectory, output) {
         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.`);
+            note(`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");
@@ -136,25 +186,41 @@ export async function runBuild(argv, projectDirectory, output) {
             }
         }
         else {
-            output.stdout(wrote(writeGeneratedFile(projectDirectory, generated.resources, tree), generated.resources, counted(found.definitions.length)));
+            noteWrite(wrote(batch.write(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;
-            }
+        const hadComputed = readGeneratedFile(projectDirectory, generated.computedFields) !==
+            undefined;
+        if (check && !hadComputed) {
+            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, {
+        if (!check && !hadComputed) {
+            batch.write(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 reading = readConfigComputedFields(path.join(projectDirectory, files.configFile), options, found.program, projectSourceFiles(projectDirectory));
+        if (reading.kind === "ill-typed") {
+            output.stderr(`aventara-build: computed fields not read from ${files.configFile}: ${reading.reason}. It does not type-check either: if these errors are what kept it from being read, fix them; if not, write the configuration \`as const\` there.${hadComputed ? ` ${generated.computedFields} keeps what it said.` : ""}\n${typeErrors(projectDirectory, reading.errors)}`);
+        }
+        const kept = reading.kind === "ill-typed" && hadComputed;
+        const statement = reading.kind === "ill-typed"
+            ? { kind: "unread", reason: reading.reason }
+            : reading;
+        const computed = emitComputedFieldsModule(files.configFile, statement);
+        if (kept && check) {
+            output.stderr(refusal({
+                file: generated.computedFields,
+                what: "cannot be checked while the configuration does not type-check",
+                remedy: "Fix the type errors listed above; running aventara-build changes nothing until then.",
+            }));
+            return 1;
+        }
+        if (kept) {
+            noteWrite(wrote("unchanged", generated.computedFields));
+        }
+        else 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));
@@ -162,9 +228,9 @@ export async function runBuild(argv, projectDirectory, output) {
             }
         }
         else {
-            output.stdout(wrote(writeGeneratedFile(projectDirectory, generated.computedFields, computed), generated.computedFields));
+            noteWrite(wrote(batch.write(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.`);
+                note(`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);
@@ -178,17 +244,17 @@ export async function runBuild(argv, projectDirectory, output) {
                 canonicalText: (contract) => project.internal.canonicalizeContract(contract),
             });
         if (!check) {
-            output.stdout(wrote(writeContractsFile(projectDirectory, generated.contracts, compiled), generated.contracts, counted(resources)));
+            noteWrite(wrote(batch.write(generated.contracts, compiled.source), generated.contracts, counted(resources)));
             if (browserClient !== undefined) {
                 for (const warning of browserClient.warnings) {
-                    output.stdout(`aventara-build: ${warning}`);
+                    note(`aventara-build: ${warning}`);
                 }
-                const written = writeBrowserClient(projectDirectory, browserClient);
+                const written = writeBrowserClient(projectDirectory, browserClient, batch);
                 for (const file of written.removed) {
-                    output.stdout(`aventara-build: removed ${file}, which this ClientContract's browser client no longer has.`);
+                    note(`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}`));
+                noteWrite(wrote(written.write, `${entry?.file}, ${universal?.file} and ${browserClient.tree}/`, `the browser client, calling ${browserClient.entrypoint === "" ? "/" : browserClient.entrypoint}`));
             }
             return 0;
         }
@@ -201,7 +267,7 @@ export async function runBuild(argv, projectDirectory, output) {
                 output.stderr(refusal(stale));
                 return 1;
             }
-            output.stdout(browserClient === undefined
+            note(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;
@@ -216,14 +282,25 @@ export async function runBuild(argv, projectDirectory, output) {
         return 1;
     }
     catch (error) {
-        if (error instanceof AvBuildError) {
-            output.stderr(`aventara-build: ${error.message}`);
-            return 1;
+        failed = true;
+        const unrestored = batch.restore();
+        output.stderr(error instanceof AvBuildError
+            ? `aventara-build: ${error.message}`
+            : defectText(error));
+        for (const { file, error: cause } of unrestored) {
+            output.stderr(`aventara-build: ${file} could not be put back as it was (${cause instanceof Error ? cause.message : String(cause)}); run aventara-build again.`);
         }
-        throw error;
+        return 1;
     }
     finally {
+        stopSignals?.();
+        releaseLock?.();
         restoreEnv?.();
+        for (const line of lines) {
+            if (!(failed && line.write === true)) {
+                output.stdout(line.text);
+            }
+        }
     }
 }
 export async function runFromProcess() {
@@ -234,7 +311,7 @@ export async function runFromProcess() {
         });
     }
     catch (error) {
-        process.stderr.write(`${(error instanceof Error && error.stack) || String(error)}\n`);
+        process.stderr.write(`${defectText(error)}\n`);
         process.exitCode = 1;
     }
 }

package/dist/client/client-file.js

@@ -1,8 +1,9 @@
-import { readdirSync, rmSync } from "node:fs";
+import { readdirSync, statSync } 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";
+import { readGeneratedFile, } from "../project/generated-file.js";
+import { optionalProjectFile } from "../project/project-modules.loader.js";
 export const REGENERATE = "`aventara-build --client` (the project's `aventara:prepare` script)";
 const ENTRY_BANNER = [
     "// biome-ignore-all format: generated output",
@@ -87,7 +88,69 @@ function guardedClient(template: AvClient): AvClient {
 	return copy;
 }
 `;
-function entrySource(style, accessVerbs) {
+export const CLIENT_OPTIONS_MODULE = "client-options";
+const NO_DEFAULT_KEY = "aventara.build.client-options.no-default";
+const OPTIONS_NO_DEFAULT_WARNING = "AVENTARA_CLIENT_OPTIONS_NO_DEFAULT";
+export const NO_DEFAULT_WARNING = "src/aventara/client-options has no default export: the client runs without hooks. Export them as its default: export default { onCall, onSuccess, onError }.";
+const CLIENT_OPTIONS_EXTENSIONS = [".ts", ".js"];
+function optionsSpecifier(file, style) {
+    const base = `./${CLIENT_OPTIONS_MODULE}`;
+    if (path.extname(file) === ".ts") {
+        return importSpecifier(base, style);
+    }
+    return style.importFileExtension === "" ? base : `${base}.js`;
+}
+const ownedOption = (name) => JSON.stringify(`Error: src/aventara/client-options sets onCall, onSuccess and onError only; @/aventara/client sets ${name}`);
+const HOOKS_SOURCE = `/** What src/aventara/client-options exports by default: the client's hooks. This module sets the rest. */
+type ClientOptions = Pick<AvClientOptions, "onCall" | "onSuccess" | "onError"> & {
+	readonly fetch?: ${ownedOption("fetch")};
+	readonly grouping?: ${ownedOption("grouping")};
+	readonly entrypoint?: ${ownedOption("entrypoint")};
+};
+
+/** The options module's default export, checked: the hooks, and nothing this module sets; none at all is fine. */
+type CheckedDefault<D extends ClientOptions | undefined> = D;
+type OptionsDefault = CheckedDefault<typeof optionsModule extends { readonly default: infer D } ? D : undefined>;
+
+/** The process-wide mark that the missing default export was reported. */
+const NO_DEFAULT_REPORTED = Symbol.for(${JSON.stringify(NO_DEFAULT_KEY)});
+
+/** The options module's default export, read when a hook runs; a missing one is reported once. */
+function clientOptions(): ClientOptions | undefined {
+	const options: unknown = (optionsModule as unknown as { readonly default?: unknown }).default;
+	if (typeof options === "object" && options !== null) {
+		return options as ClientOptions & OptionsDefault;
+	}
+	const holder = globalThis as { [key: symbol]: unknown };
+	if (holder[NO_DEFAULT_REPORTED] !== true) {
+		holder[NO_DEFAULT_REPORTED] = true;
+		const platform = globalThis as {
+			readonly process?: { readonly emitWarning?: (message: string, options: { readonly type: string; readonly code: string }) => void };
+			readonly console?: { warn(message: string): void };
+		};
+		const message = ${JSON.stringify(NO_DEFAULT_WARNING)};
+		if (typeof platform.process?.emitWarning === "function") {
+			platform.process.emitWarning(message, { type: "AventaraWarning", code: ${JSON.stringify(OPTIONS_NO_DEFAULT_WARNING)} });
+		} else {
+			platform.console?.warn("AventaraWarning: " + message);
+		}
+	}
+	return undefined;
+}
+
+/** The hooks every client this module makes runs, on either side: the options module's, read when each runs. */
+const HOOKS: Pick<AvClientOptions, "onCall" | "onSuccess" | "onError"> = {
+	onCall: (call) => clientOptions()?.onCall?.(call),
+	onSuccess: (call, result) => clientOptions()?.onSuccess?.(call, result),
+	onError: (call, error) => clientOptions()?.onError?.(call, error),
+};
+`;
+function optionsImport(options) {
+    return options === undefined
+        ? ""
+        : `import * as optionsModule from ${JSON.stringify(options)};\n`;
+}
+function entrySource(style, accessVerbs, options) {
     const from = (module) => JSON.stringify(importSpecifier(module, style));
     const { tagKey, valueKey, objectTag, scalarTags } = HYDRATION_FORMAT;
     const tagged = [...scalarTags, objectTag]
@@ -95,9 +158,9 @@ function entrySource(style, accessVerbs) {
         .join(" | ");
     return `${ENTRY_BANNER}
 
-import { AvClient } from ${from(`./${GENERATED_DIRECTORY}/client`)};
+import { AvClient${options === undefined ? "" : ", type AvClientOptions"} } from ${from(`./${GENERATED_DIRECTORY}/client`)};
 import { type AvBuiltInScalar, decodeScalar } from ${from(`./${GENERATED_DIRECTORY}/runtime/codec`)};
-
+${optionsImport(options)}
 ${clientEntryReExports(style, "type", accessVerbs)}
 /** What a call made on the server is refused with. */
 const SERVER_CALL = ${JSON.stringify(SERVER_CALL_REFUSAL)};
@@ -117,8 +180,8 @@ function refusal(): string | undefined {
 
 type Call = (...args: unknown[]) => unknown;
 
-/** The one client every call is made on. */
-const CLIENT = new AvClient();
+${options === undefined ? "" : HOOKS_SOURCE + "\n"}/** The one client every call is made on. */
+const CLIENT = new AvClient(${options === undefined ? "" : "{ ...HOOKS }"});
 
 /** The client a call made here and now is made on: the one client. */
 function current(): AvClient {
@@ -197,15 +260,15 @@ export function avHydrate(dehydrated: unknown): unknown {
 }
 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) {
+function universalSource(style, accessVerbs, options) {
     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 { AvClient${options === undefined ? "" : ", type AvClientOptions"} } from ${from(`./${GENERATED_DIRECTORY}/client`)};
 import type { AvFetch } from ${from(`./${GENERATED_DIRECTORY}/runtime/transport`)};
-
+${optionsImport(options)}
 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. */
@@ -242,8 +305,8 @@ async function universalFetch(...request: unknown[]): Promise<unknown> {
 
 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 });
+${options === undefined ? "" : HOOKS_SOURCE + "\n"}/** The browser's one client, whose calls are grouped, and the shape \`avClient\` copies. */
+const BROWSER = new AvClient({ ${options === undefined ? "" : "...HOOKS, "}fetch: universalFetch as AvFetch });
 
 /**
  * The client a call made here and now is made on: the browser's one; on the
@@ -252,7 +315,7 @@ const BROWSER = new AvClient({ fetch: universalFetch as AvFetch });
  * 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;
+	return onServer() ? new AvClient({ ${options === undefined ? "" : "...HOOKS, "}fetch: universalFetch as AvFetch, grouping: false }) : BROWSER;
 }
 
 /** On the server, the calls each avLazy made in the request being rendered (React's \`cache\`). */
@@ -369,6 +432,19 @@ export async function emitBrowserClient(projectDirectory, layout, source) {
         moduleFormat: style.moduleFormat,
     }, REGENERATE));
     const accessVerbs = accessVerbsOf(acceptance.contract).length > 0;
+    const optionsModule = `${layout.folder}/${CLIENT_OPTIONS_MODULE}`;
+    const optionsFile = [".tsx", ".jsx"]
+        .map((extension) => `${optionsModule}${extension}`)
+        .find((file) => statSync(path.join(projectDirectory, file), {
+        throwIfNoEntry: false,
+    })?.isFile() === true) ?? optionalProjectFile(projectDirectory, optionsModule);
+    if (optionsFile !== undefined &&
+        !CLIENT_OPTIONS_EXTENSIONS.includes(path.extname(optionsFile))) {
+        throw new AvBuildError(`${optionsFile} is not read: the client's options module is ${layout.folder}/${CLIENT_OPTIONS_MODULE}.ts or .js, the two the entries import under every Next.js bundler; rename it.`);
+    }
+    const options = optionsFile === undefined
+        ? undefined
+        : optionsSpecifier(optionsFile, style);
     const decoder = new TextDecoder();
     const tree = emission.tree
         .filter((file) => file.path.startsWith(`${GENERATED_DIRECTORY}/`))
@@ -380,11 +456,11 @@ export async function emitBrowserClient(projectDirectory, layout, source) {
         files: [
             {
                 file: `${layout.folder}/${layout.entry}`,
-                text: entrySource(style, accessVerbs),
+                text: entrySource(style, accessVerbs, options),
             },
             {
                 file: `${layout.folder}/${layout.universal}`,
-                text: universalSource(style, accessVerbs),
+                text: universalSource(style, accessVerbs, options),
             },
             ...tree,
         ],
@@ -413,16 +489,16 @@ function leftovers(projectDirectory, client) {
     return filesUnder(projectDirectory, client.tree).filter((file) => !written.has(file) &&
         carriesGeneratedOwnership(readGeneratedFile(projectDirectory, file) ?? ""));
 }
-export function writeBrowserClient(projectDirectory, client) {
+export function writeBrowserClient(projectDirectory, client, writer) {
     let write = "unchanged";
     for (const { file, text } of client.files) {
-        if (writeGeneratedFile(projectDirectory, file, text) === "written") {
+        if (writer.write(file, text) === "written") {
             write = "written";
         }
     }
     const removed = leftovers(projectDirectory, client);
     for (const file of removed) {
-        rmSync(path.join(projectDirectory, file));
+        writer.remove(file);
     }
     return { write: removed.length > 0 ? "written" : write, removed };
 }
@@ -435,7 +511,7 @@ export function checkBrowserClient(projectDirectory, client) {
         if (current !== text) {
             return {
                 file,
-                what: "is stale: the ClientContract or the project's module settings changed since it was written",
+                what: `is stale: the ClientContract, the project's module settings or its ${CLIENT_OPTIONS_MODULE} module (added or removed) changed since it was written`,
             };
         }
     }

package/dist/computed/computed-fields-file.js

@@ -22,7 +22,10 @@ export function emitComputedFieldsModule(configFile, reading) {
             `// Not read: ${reading.reason.replaceAll("\n", " ")}. The stages that run before compute may leave any`,
             "// create field out; write the configuration `as const` there to have it read.",
             "export const computedFields = null;",
-            ...type,
+            "",
+            "// What an adapter's discovery artifact carries on its model's type for the stages that run before compute:",
+            "// nothing, so they may leave any create field out.",
+            "export type AvComputedFields = undefined;",
         ].join("\n")}\n`;
     }
     return `${[

package/dist/computed/computed-fields.reader.js

@@ -6,10 +6,13 @@ const AGENT_PARENTS = ["root", "application", "client"];
 const PHASES = ["create", "update"];
 class NotExact extends Error {
 }
-export function readConfigComputedFields(configFile, options, oldProgram) {
+export function readConfigComputedFields(configFile, options, oldProgram, projectFiles = []) {
     const file = path.resolve(configFile);
     const program = ts.createProgram({
-        rootNames: [file],
+        rootNames: [
+            file,
+            ...projectFiles.filter((name) => path.resolve(name) !== file),
+        ],
         options: { ...options, noEmit: true, skipLibCheck: true },
         ...(oldProgram === undefined ? {} : { oldProgram }),
     });
@@ -44,11 +47,35 @@ export function readConfigComputedFields(configFile, options, oldProgram) {
     }
     catch (error) {
         if (error instanceof NotExact) {
-            return { kind: "unread", reason: error.message };
+            const errors = configurationErrors(program, file, options);
+            return errors.length > 0
+                ? { kind: "ill-typed", reason: error.message, errors }
+                : { kind: "unread", reason: error.message };
         }
         throw error;
     }
 }
+function configurationErrors(program, file, options) {
+    const reached = new Set(ts
+        .createProgram({
+        rootNames: [file],
+        options: { ...options, noEmit: true, skipLibCheck: true },
+        oldProgram: program,
+    })
+        .getSourceFiles()
+        .map((source) => path.resolve(source.fileName)));
+    return program
+        .getSourceFiles()
+        .filter((source) => reached.has(path.resolve(source.fileName)) &&
+        !source.isDeclarationFile &&
+        !program.isSourceFileFromExternalLibrary(source) &&
+        !source.fileName.includes("/node_modules/"))
+        .flatMap((source) => [
+        ...program.getSyntacticDiagnostics(source),
+        ...program.getSemanticDiagnostics(source),
+    ])
+        .filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+}
 function computedFieldsOfType(checker, config) {
     assertExact(checker, config, "the configuration");
     const overlays = Object.fromEntries(LAYERS.map((layer) => {

package/dist/contracts/contracts-file.js

@@ -1,10 +1,7 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
-import { readGeneratedFile, writeGeneratedFile, } from "../project/generated-file.js";
-export function writeContractsFile(projectDirectory, contractsFile, compiled) {
-    return writeGeneratedFile(projectDirectory, contractsFile, compiled.source);
-}
+import { readGeneratedFile } from "../project/generated-file.js";
 export async function checkContractsFile(projectDirectory, contractsFile, compiled, changesOf) {
     const file = path.join(projectDirectory, contractsFile);
     const text = readGeneratedFile(projectDirectory, contractsFile);

package/dist/project/build.lock.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { AvBuildError } from "../build.error.js";
+const STALE_AFTER_MS = 10 * 60 * 1000;
+export function buildLockFileOf(projectDirectory) {
+    return path.join(projectDirectory, "node_modules", ".cache", "aventara-build", "build.lock");
+}
+function running(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function liveHolder(lock) {
+    try {
+        const holder = Number.parseInt(readFileSync(lock, "utf8"), 10);
+        const age = Date.now() - statSync(lock).mtimeMs;
+        return Number.isInteger(holder) &&
+            holder !== process.pid &&
+            age < STALE_AFTER_MS &&
+            running(holder)
+            ? holder
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function acquireBuildLock(projectDirectory) {
+    const lock = buildLockFileOf(projectDirectory);
+    const shown = path.relative(projectDirectory, lock);
+    const unwritable = (error) => {
+        const { code, path: at } = error;
+        const where = at === undefined
+            ? ""
+            : ` at ${path.relative(projectDirectory, at) || "."}`;
+        return new AvBuildError(`this project's lock file ${shown} cannot be written (${code ?? String(error)}${where}). Make node_modules a writable folder (the package manager's install makes one) and run it again.`);
+    };
+    try {
+        mkdirSync(path.dirname(lock), { recursive: true });
+    }
+    catch (error) {
+        throw unwritable(error);
+    }
+    const held = `${process.pid} ${randomUUID()}`;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            writeFileSync(lock, held, { flag: "wx" });
+            return () => {
+                try {
+                    if (readFileSync(lock, "utf8") === held) {
+                        rmSync(lock, { force: true });
+                    }
+                }
+                catch {
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw unwritable(error);
+            }
+        }
+        const holder = liveHolder(lock);
+        if (holder !== undefined) {
+            throw new AvBuildError(`another aventara-build (process ${holder}) is writing this project's generated files. Run it again when that one has finished, or delete ${shown} if no build is running.`);
+        }
+        try {
+            rmSync(lock, { force: true });
+        }
+        catch (error) {
+            throw unwritable(error);
+        }
+    }
+    throw new AvBuildError("another aventara-build took this project's lock at the same moment. Run it again.");
+}

package/dist/project/generated-file.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 export function readGeneratedFile(projectDirectory, file) {
     try {
@@ -8,12 +8,96 @@ export function readGeneratedFile(projectDirectory, file) {
         return undefined;
     }
 }
+export function replaceFile(target, text, rename = renameSync) {
+    const temporary = `${target}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temporary, text);
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                rename(temporary, target);
+                return;
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") {
+                    throw error;
+                }
+                if (attempt === RENAME_ATTEMPTS) {
+                    writeFileSync(target, text);
+                    rmSync(temporary, { force: true });
+                    return;
+                }
+                Atomics.wait(PAUSE, 0, 0, RENAME_PAUSE_MS);
+            }
+        }
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+const RENAME_ATTEMPTS = 5;
+const RENAME_PAUSE_MS = 50;
+const PAUSE = new Int32Array(new SharedArrayBuffer(4));
 export function writeGeneratedFile(projectDirectory, file, text) {
     if (readGeneratedFile(projectDirectory, file) === text) {
         return "unchanged";
     }
     const target = path.join(projectDirectory, file);
     mkdirSync(path.dirname(target), { recursive: true });
-    writeFileSync(target, text);
+    replaceFile(target, text);
     return "written";
 }
+export function generatedFileBatch(projectDirectory) {
+    const before = new Map();
+    const made = [];
+    const remember = (file) => {
+        if (!before.has(file)) {
+            before.set(file, readGeneratedFile(projectDirectory, file));
+        }
+    };
+    return {
+        write: (file, text) => {
+            if (readGeneratedFile(projectDirectory, file) === text) {
+                return "unchanged";
+            }
+            remember(file);
+            const missing = [];
+            for (let folder = path.dirname(path.join(projectDirectory, file)); !existsSync(folder) && folder !== path.dirname(folder); folder = path.dirname(folder)) {
+                missing.unshift(folder);
+            }
+            made.push(...missing);
+            return writeGeneratedFile(projectDirectory, file, text);
+        },
+        remove: (file) => {
+            remember(file);
+            rmSync(path.join(projectDirectory, file), { force: true });
+        },
+        restore: () => {
+            const failures = [];
+            for (const [file, text] of before) {
+                const target = path.join(projectDirectory, file);
+                try {
+                    if (text === undefined) {
+                        rmSync(target, { force: true });
+                    }
+                    else {
+                        mkdirSync(path.dirname(target), { recursive: true });
+                        replaceFile(target, text);
+                    }
+                }
+                catch (error) {
+                    failures.push({ file, error });
+                }
+            }
+            for (const folder of [...made].reverse()) {
+                try {
+                    rmdirSync(folder);
+                }
+                catch {
+                }
+            }
+            return failures;
+        },
+    };
+}

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

@@ -7,19 +7,23 @@ const EXTENSIONS = [".js", ".ts", ".mjs", ".cjs", ".mts", ".cts"];
 const EXTENSIONS_AS_LISTED = [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
 const SERVER_MARKERS = { "server-only": {} };
 const CONFIG_EXPORTS = ["aventaraConfig", "default"];
-function projectFile(projectDirectory, module, layout) {
+export function optionalProjectFile(projectDirectory, module) {
     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}, 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" : ""}.`);
     }
     return present[0];
 }
+function projectFile(projectDirectory, module, layout) {
+    const file = optionalProjectFile(projectDirectory, module);
+    if (file === undefined) {
+        const [first, ...others] = EXTENSIONS_AS_LISTED;
+        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).`);
+    }
+    return file;
+}
 async function evaluate(jiti, projectDirectory, file) {
     try {
         return await jiti.import(path.join(projectDirectory, file));

package/dist/project/tsconfig.reader.js

@@ -22,6 +22,18 @@ export function projectCompilerOptions(projectDirectory) {
     }
     return ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(tsconfig)).options;
 }
+export function projectSourceFiles(projectDirectory) {
+    assertClassicCompilerApi();
+    const tsconfig = ts.findConfigFile(projectDirectory, ts.sys.fileExists, "tsconfig.json");
+    if (tsconfig === undefined) {
+        return [];
+    }
+    const read = ts.readConfigFile(tsconfig, ts.sys.readFile);
+    return read.error === undefined
+        ? ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(tsconfig))
+            .fileNames
+        : [];
+}
 export function importSuffixOf(options, directory) {
     if (options.allowImportingTsExtensions === true ||
         options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/build",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.13",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Compiles an Aventara application's Contracts at build time, for serverless and edge cold starts.",
   "type": "module",
@@ -16,18 +16,18 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/client": "1.0.0-rc.11",
+    "@aventara/client": "1.0.0-rc.13",
     "jiti": "2.7.0"
   },
   "peerDependencies": {
-    "@aventara/core": "1.0.0-rc.11",
+    "@aventara/core": "1.0.0-rc.13",
     "typescript": ">=5.7.0 <7"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/core": "1.0.0-rc.11",
+    "@aventara/core": "1.0.0-rc.13",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },