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

package/CHANGELOG.md

@@ -0,0 +1,123 @@
+# @aventara/build
+
+## 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
+
+- 7c3b65f: Build-time Contracts for serverless and edge cold starts.
+
+  - New package `@aventara/build`, bin `aventara-build`, a development dependency. It runs `src/aventara.config.ts` and
+    `src/aventara.adapter.ts` without a database client, compiles the Contracts with the project's `@aventara/core` and
+    writes `src/generated/aventara/contracts.generated.ts` (`aventaraContracts`), which a serverless or edge entry passes
+    to `createFramework` as `prebuilt`. A configuration that startup would refuse fails the build with the same
+    `CONFIG_…`/`COMPILER_…` diagnostics. `aventara-build --check` writes nothing and exits 1 when the file is missing or
+    stale, naming the Resources that changed.
+  - `@aventara/prisma7-adapter`: `describePrismaAdapter({ discovery, provider, driver })` states the adapter's passive
+    facts (the model, the driver's transaction capability, the referential actions, the computed fields) with no client.
+    `createPrismaAdapter({ ...description, client })` builds the adapter from the same facts, and still checks the client
+    against the discovery artifact.
+  - `@aventara/cli`: the scaffold's `src/aventara.config.ts` exports the configuration as a plain value
+    (`export const aventaraConfig = { … } as const`) with no `adapter`. A new `src/aventara.adapter.ts` default-exports
+    `describePrismaAdapter(…)`, and `app.module.ts` joins the two:
+    `config: { ...aventaraConfig, adapter: await createPrismaAdapter({ ...adapter, client: prisma }) }`. The Nest server
+    still compiles its Contracts at startup and passes no `prebuilt`. `aventara:prepare` ends with `&& aventara-build`,
+    and `@aventara/build` is an exact development dependency.
+
+- 2b1b17e: `aventara-build`'s files no longer land inside a Prisma client generated into `src/generated`.
+
+  When `aventara init` reuses a project whose Prisma client is generated into `src/generated`, it already puts the
+  discovery artifact in `src/aventara/`, because `prisma generate` deletes every file in its output directory that it did
+  not write. `aventara-build` still wrote its three files to `src/generated/aventara/`, so each `prisma generate` deleted
+  them and the project stopped compiling until the next `aventara:prepare`. Now all of Aventara's generated files are
+  in one place.
+
+  - `@aventara/build`: `aventara-build` writes `resources.generated.ts`, `computed-fields.generated.ts` and
+    `contracts.generated.ts` to the directory the configuration imports `aventaraResources` from, so the tree is always
+    written where the configuration reads it. A configuration that imports no tree keeps `src/generated/aventara/`.
+    The files of a project whose client is generated anywhere else are the same bytes, in the same place.
+  - `@aventara/prisma7-adapter`: with `--config`, the artifact imports the computed fields from its sibling,
+    `./computed-fields.generated`, wherever `--out` puts it. `--config` is still required for that import and the step
+    still checks that the file exists, but the step no longer uses its location. A scaffold's artifact is unchanged.
+  - `@aventara/cli`: in that project, `src/aventara.config.ts` imports the tree from `./aventara/resources.generated`,
+    and `.gitignore` gets the one `/src/aventara/` line that covers all four files (no separate
+    `/src/generated/aventara/contracts.generated.ts` line). The agent skill says where the generated files are in
+    both cases.
+
+- 3813207: The Resource tree and the computed fields come from `aventara-build`.
+
+  - `@aventara/build`: before it compiles the Contracts, `aventara-build` writes two more files under
+    `src/generated/aventara/`. `resources.generated.ts` exports `aventaraResources`: every `defineResource(…)` result
+    that the files `src/resources/**/*.resource.ts` export, found by its type (never run), one `resources` tree per
+    layer, written as the plain spreads you wrote by hand (`root` always, `application`, `client` and `agent` when some
+    Resource has a block for them). Two definitions of one Resource stop the build, naming both. Imports are spelled as
+    the project spells its own. `computed-fields.generated.ts` exports `computedFields` and its type `AvComputedFields`:
+    which fields the configuration's write compute fills, read off its type after the tree exists, so a fresh install is
+    typed right on its first `aventara:prepare`. `--check` covers all three files. `typescript` (`>=5.7.0 <7`) is now a
+    peer dependency.
+  - `@aventara/prisma7-adapter`: the generate step no longer reads the configuration. With `--config`, the discovery
+    artifact imports `computedFields` and `AvComputedFields` from the file `aventara-build` writes beside the
+    configuration (`generated/aventara/computed-fields.generated.ts`); a `--config` file that does not exist is still
+    refused. `readConfigComputedFields`, `AvPrismaConfigReaderError` and `ConfigComputedFieldsReading` are removed from
+    `@aventara/prisma7-adapter/generate`, as are `PrismaGenerateToolchain.readComputedFields` and
+    `PrismaGenerateResult.computedFields`.
+  - `@aventara/cli`: the scaffold's `src/aventara.config.ts` takes its Resources from the tree,
+    `resources: aventaraResources.root`, so a new Resource file needs no configuration edit; the agent skill says so.
+
+- Updated dependencies [e3d03a7]
+- Updated dependencies [d10639a]
+- Updated dependencies [f67e68c]
+- Updated dependencies [708556c]
+- Updated dependencies [3a0dfca]
+- Updated dependencies [99169d2]
+- Updated dependencies [0fd2608]
+- Updated dependencies [154e440]
+- Updated dependencies [2fcffdb]
+  - @aventara/core@1.0.0-rc.4
+

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright 2026 Mohamed Ragheb
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/LICENSE-ADDITIONAL-PERMISSION.md

@@ -0,0 +1,9 @@
+# Additional Permission — Aventara
+
+Copyright 2026 Mohamed Ragheb
+
+In addition to the permissions of the PolyForm Shield License 1.0.0 in `LICENSE`, the licensor grants the following additional permission:
+
+The Noncompete section applies only to providing a product that competes with the software itself — the Aventara framework, its packages and its tooling. Providing a product that competes with any other product the licensor or its affiliates provide using the software is a permitted purpose.
+
+This additional permission only adds to your permissions; it does not restrict or replace any term of `LICENSE`.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# `@aventara/build`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `aventara-build` command compiles an Aventara application's Contracts when the project is built, so a serverless
+or edge function loads them at a cold start instead of compiling them. It is a development dependency: nothing in your
+deployed application imports it.
+
+```bash
+npm install --save-dev --save-exact @aventara/build@<your @aventara/core version>
+```
+
+`aventara new` and `aventara init` add it and run it from the project's `aventara:prepare` script, after the adapter's
+generate step:
+
+```text
+aventara-prisma7-generate … && aventara-build
+```
+
+## What it reads and writes
+
+Run it from the project's root. It writes three files, in this order, each from what the one before wrote, so a fresh
+install is right on its first `aventara:prepare`. They go to the directory your configuration imports
+`aventaraResources` from, beside the discovery artifact: `src/generated/aventara/` normally, `src/aventara/` when
+`aventara init` found Prisma's client generated into `src/generated` (which `prisma generate` would empty). A
+configuration that imports no tree keeps `src/generated/aventara/`.
+
+| File | What it holds |
+|---|---|
+| `resources.generated.ts` | `aventaraResources`: every Resource your `src/resources/**/*.resource.ts` files define, one `resources` tree per layer |
+| `computed-fields.generated.ts` | `computedFields` (typed `AvComputedFields`): which fields the configuration's write compute fills, read off its type |
+| `contracts.generated.ts` | `aventaraContracts` (typed `AvPrebuiltContracts`): the compiled Contracts |
+
+### The Resource tree
+
+Each Resource's configuration lives in its own file under `src/resources/`, named `<name>.resource.ts`, as an exported
+`defineResource(...)` result. The build reads those files through TypeScript (it never runs them), takes every export
+whose type is a `defineResource` result, and writes the spreads you would otherwise write by hand:
+
+```ts
+// src/generated/aventara/resources.generated.ts (generated)
+import { post } from "../../resources/post.resource.js";
+import { session } from "../../resources/session.resource.js";
+
+export const aventaraResources = {
+  root: { ...post.root, ...session.root },
+  client: { ...post.client },
+} as const;
+```
+
+`root` is always there; `application`, `client` and `agent` only when some Resource gives that layer a block. The
+configuration takes the trees once, and a new Resource file needs no edit to it:
+
+```ts
+// src/aventara.config.ts
+import { aventaraResources } from "./generated/aventara/resources.generated.js";
+
+export const aventaraConfig = {
+  api: "/api",
+  exposed: true,
+  resources: aventaraResources.root,
+  client: { exposed: true, resources: aventaraResources.client },
+} as const;
+```
+
+Two files defining the same Resource stop the build, naming both: spread by hand, the later spread silently replaced
+the earlier block. The imports are spelled as your project spells its own, by the rule `avclient` follows for the client it writes:
+`.js` in an ES module under `nodenext`, none with `module: "commonjs"` or `moduleResolution: "bundler"`, `.ts` with
+`allowImportingTsExtensions`. One difference: a CommonJS package under `nodenext` (Nest's CommonJS scaffold) gets no
+suffix either, as the scaffold writes its own imports there, because these files import values and the jest such a
+project tests with resolves no `.js` specifier to a `.ts` file. The tree is the same expression you would write, so it
+costs the same type checking. The files matched are `src/resources/**/*.resource.ts`; the pattern is not configurable
+yet.
+
+### The computed fields
+
+The build reads which fields the configuration's `compute.create` and `compute.update` stages fill off the
+configuration's TypeScript type, after it wrote the tree, and writes them to `computed-fields.generated.ts`. The Prisma
+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.
+
+### The Contracts
+
+To compile the Contracts it runs two of your modules, in TypeScript or JavaScript, ES module or CommonJS:
+
+| File | What it must export |
+|---|---|
+| `src/aventara.config.ts` | `aventaraConfig` (or a default export): the configuration as a plain value, without `adapter` |
+| `src/aventara.adapter.ts` | a default export: the adapter's description, `describePrismaAdapter({ discovery, provider, driver })` for Prisma 7 |
+
+It compiles the four Contracts with your project's own `@aventara/core`, from the configuration and the model the
+description holds, and writes `src/generated/aventara/contracts.generated.ts`, whose export `aventaraContracts` is typed
+`AvPrebuiltContracts`. It never constructs a database client and never connects to a database. The file is generated:
+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.
+
+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.
+
+## `--check`
+
+```bash
+aventara-build --check
+```
+
+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.
+
+## Using the file
+
+Pass `aventaraContracts` as `prebuilt` where the framework is created, beside the adapter:
+
+```ts
+// a serverless or edge entry
+import { createFramework } from "@aventara/core";
+import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import adapter from "./aventara.adapter.js";
+import { aventaraConfig } from "./aventara.config.js";
+import { aventaraContracts } from "./generated/aventara/contracts.generated.js";
+import { prisma } from "./prisma.client.js";
+
+export const framework = await createFramework({
+  ...aventaraConfig,
+  adapter: await createPrismaAdapter({ ...adapter, client: prisma }),
+  prebuilt: aventaraContracts,
+});
+```
+
+The framework uses the file only when it was compiled by the same `@aventara/core`, for the same protocol, from the same
+configuration and model. Otherwise it ignores the whole file, compiles at startup as it would without one, and warns
+once with `AVENTARA_PREBUILT_STALE`, naming what changed. A stale file never serves a wrong Contract; it only costs the
+startup time the file was meant to save.
+
+A long-running server does not need the file. The Nest project `aventara new` writes compiles its Contracts at startup
+and passes no `prebuilt`.

package/dist/aventara-build.bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { refuseUnsupportedNode } from "./node-version.guard.js";
+if (!refuseUnsupportedNode("aventara-build", new URL("../package.json", import.meta.url))) {
+    void import("./cli.js").then((program) => program.runFromProcess());
+}

package/dist/build.error.js

@@ -0,0 +1,3 @@
+export class AvBuildError extends Error {
+    name = "AvBuildError";
+}

package/dist/cli.js

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { AvBuildError } from "./build.error.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 { 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
+
+Run it from the project's root. It writes, in this order:
+
+  ${DEFAULT_GENERATED_FILES.resources}
+      \`aventaraResources\`: every \`defineResource(…)\` result the files
+      ${RESOURCES_GLOB} export, one \`resources\` tree per layer;
+  ${DEFAULT_GENERATED_FILES.computedFields}
+      which fields the configuration computes, read off its type;
+  ${DEFAULT_GENERATED_FILES.contracts}
+      the compiled Contracts, \`aventaraContracts\`.
+
+All three go to the directory the configuration imports \`aventaraResources\`
+from (src/aventara/ when \`aventara init\` found the ORM's client generated into
+src/generated), else to src/generated/aventara/.
+
+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.
+
+A serverless or edge host passes the file's \`aventaraContracts\` to
+createFramework as \`prebuilt\`; a long-running server needs none.
+
+Options:
+  --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;
+    for (const argument of argv) {
+        if (argument === "--check") {
+            check = true;
+            continue;
+        }
+        throw new AvBuildError(`unknown argument \`${argument}\`.\n\n${USAGE}`);
+    }
+    return { check };
+}
+function counted(count) {
+    return `${count} Resource${count === 1 ? "" : "s"}`;
+}
+function wrote(written, file, detail) {
+    return `aventara-build: ${written === "written" ? "wrote" : "unchanged:"} ${file}${detail === undefined ? "" : ` (${detail})`}.`;
+}
+function checked(projectDirectory, file, text, stale) {
+    const current = readGeneratedFile(projectDirectory, file);
+    return current === undefined
+        ? { file, what: "is missing" }
+        : current === text
+            ? undefined
+            : { file, what: `is stale: ${stale}` };
+}
+function refusal({ file, what, deploy }) {
+    return `aventara-build: ${file} ${what}. Run aventara-build (npm run aventara:prepare)${deploy === true ? " and deploy the file it writes" : ""}.`;
+}
+export async function runBuild(argv, projectDirectory, output) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        output.stdout(USAGE);
+        return 0;
+    }
+    try {
+        const { check } = parse(argv);
+        const files = findProjectModules(projectDirectory);
+        const generated = resolveGeneratedFiles(projectDirectory, files.configFile);
+        const options = projectCompilerOptions(projectDirectory);
+        const found = readResourceDefinitions(projectDirectory, options);
+        const tree = emitResourcesModule(projectDirectory, generated.resources, found.definitions, importSuffixOf(options, path.dirname(path.join(projectDirectory, generated.resources))));
+        for (const file of found.withoutDefinition) {
+            output.stdout(`aventara-build: ${file} exports no defineResource(…) result; it is not in aventaraResources.`);
+        }
+        if (check) {
+            const stale = checked(projectDirectory, generated.resources, tree, "the Resource files changed since it was written");
+            if (stale !== undefined) {
+                output.stderr(refusal(stale));
+                return 1;
+            }
+        }
+        else {
+            output.stdout(wrote(writeGeneratedFile(projectDirectory, generated.resources, tree), generated.resources, counted(found.definitions.length)));
+        }
+        if (check) {
+            if (readGeneratedFile(projectDirectory, generated.computedFields) ===
+                undefined) {
+                output.stderr(refusal({ file: generated.computedFields, what: "is missing" }));
+                return 1;
+            }
+        }
+        else if (readGeneratedFile(projectDirectory, generated.computedFields) ===
+            undefined) {
+            writeGeneratedFile(projectDirectory, generated.computedFields, emitComputedFieldsModule(files.configFile, {
+                kind: "unread",
+                reason: "the build has not read the configuration yet",
+            }));
+        }
+        const reading = readConfigComputedFields(path.join(projectDirectory, files.configFile), options, found.program);
+        const computed = emitComputedFieldsModule(files.configFile, reading);
+        if (check) {
+            const stale = checked(projectDirectory, generated.computedFields, computed, "the fields the configuration computes changed since it was written");
+            if (stale !== undefined) {
+                output.stderr(refusal(stale));
+                return 1;
+            }
+        }
+        else {
+            output.stdout(wrote(writeGeneratedFile(projectDirectory, generated.computedFields, computed), generated.computedFields));
+            if (reading.kind === "unread") {
+                output.stdout(`aventara-build: computed fields not read from ${files.configFile}: ${reading.reason}. The stages before compute may leave any create field out; write the configuration \`as const\` there.`);
+            }
+        }
+        const project = await loadProjectModules(projectDirectory, files);
+        const compiled = await compilePrebuiltContracts(project);
+        const resources = Object.keys(compiled.prebuilt.fingerprints.resources).length;
+        if (!check) {
+            output.stdout(wrote(writeContractsFile(projectDirectory, generated.contracts, compiled), generated.contracts, counted(resources)));
+            return 0;
+        }
+        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.`);
+            return 0;
+        }
+        output.stderr(refusal({
+            file: generated.contracts,
+            deploy: true,
+            what: contracts.kind === "missing"
+                ? "is missing"
+                : `is stale: ${contracts.changes.join("; ")}`,
+        }));
+        return 1;
+    }
+    catch (error) {
+        if (error instanceof AvBuildError) {
+            output.stderr(`aventara-build: ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+}
+export async function runFromProcess() {
+    try {
+        process.exitCode = await runBuild(process.argv.slice(2), process.cwd(), {
+            stdout: (line) => process.stdout.write(`${line}\n`),
+            stderr: (line) => process.stderr.write(`${line}\n`),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`${String(error instanceof Error ? error.stack : error)}\n`);
+        process.exitCode = 1;
+    }
+}

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

@@ -0,0 +1,37 @@
+function literal(computedFields) {
+    const ordered = {
+        agent: computedFields.agent,
+        agentExtends: computedFields.agentExtends,
+        application: computedFields.application,
+        client: computedFields.client,
+        root: computedFields.root,
+    };
+    return JSON.stringify(ordered, null, "\t");
+}
+export function emitComputedFieldsModule(configFile, reading) {
+    const header = `// Generated by aventara-build from the type of ${configFile}. Do not edit: regenerate it (aventara:prepare).`;
+    const type = [
+        "",
+        "// What an adapter's discovery artifact carries on its model's type for the stages that run before compute.",
+        "export type AvComputedFields = typeof computedFields;",
+    ];
+    if (reading.kind === "unread") {
+        return `${[
+            header,
+            "",
+            `// 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,
+        ].join("\n")}\n`;
+    }
+    return `${[
+        header,
+        'import type { AvConfigComputedFields } from "@aventara/core";',
+        "",
+        "// Which fields the configuration's write compute fills (`compute.create`, `compute.update`), per layer and",
+        "// Resource. The framework compares it with the configuration at startup and warns when they differ.",
+        `export const computedFields = ${literal(reading.computedFields)} as const satisfies AvConfigComputedFields;`,
+        ...type,
+    ].join("\n")}\n`;
+}