@aventara/build 1.0.0-rc.14 → 1.0.0-rc.15

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @aventara/build
 
+## 1.0.0-rc.15
+
+### Patch Changes
+
+- aab6d72: The client `avclient generate` writes now passes a default `biome check` as written, on Biome 2.4.0 and later (Biome's default rules; an opt-in rule or assist such as `useSortedKeys` is not covered): every generated file opens with `biome-ignore-all` lines for formatting, lint and import order (`organizeImports`), core's copied declarations have a blank line after their imports, the copied field-check evaluator carries no line suppression that the file-wide one makes unused, and each file ends without a final line break, which Biome 2.4.0 to 2.4.10 reported on every file under `biome-ignore-all format`. `aventara-build`'s own files pass too, in NestJS and Next.js projects: `resources.generated.ts`, `computed-fields.generated.ts` and `contracts.generated.ts` now open with the same suppressions and end without a final line break, and `--client`'s `src/aventara/client.ts` and `src/aventara/universal.ts` are written the same way. The discovery artifact `aventara-prisma7-generate` writes passes too. A file an earlier version wrote is reported stale by `aventara-build --check` and replaced by the next run. A client `avclient generate` wrote before is replaced on its next run. The client skill now says the generated files need no exclusion under Biome's default rules, and how to skip them in another linter or formatter.
+- bf98da7: A pipeline stage's types now know the root's field definitions. `aventara-build` writes `src/generated/aventara/config-facts.generated.ts` after it compiles the Contracts, and the discovery artifact puts it on the model's type:
+
+  - A Json field the root shapes reads as its shape in a stage's `ctx` calls, in `tx` and in compute's read-only `ctx`: `ctx.Product.find.many({ select: ["name"] })` types `name` as `{ ar: string; en: string }`. A read gives the shape's own type, the same as `framework.application`'s.
+  - A `VIRTUAL` field the root adds is in a variant's typed `ctx.$args` (`ctx.$args.data.tenderedMinor`), and a `ctx` create must write a non-null added input it can create.
+  - A variant's hooks and interceptors are told resolved arguments: their `ctx.$args` holds no `$ref` (an `AvTransactionReference`), since references are resolved before they run. Guards, pipes and filters still may see one.
+  - A write takes a shaped Json value read-only, deep, on every surface (`framework.application`, `ctx`, the generated client too), so a frozen value, such as a stage's `ctx.$args`, fits as well as a mutable one.
+  - A compute stage on a shaped Json field returns the shape's type. A compute stage on an added field returns the type its generated fact states, read from the model instead of the configuration. Without the generated file, its return is not typed.
+
+  The server warns at startup (`AVENTARA_STALE_GENERATED_TYPES`) when the configuration's definitions differ from the ones the generated types were written with, naming each field. It is the same one warning as for stale computed fields: one stale build gives one warning, with a paragraph for each part that is stale, including a facts file it cannot read. `aventara-build --check` also fails on a stale file. Run `aventara:prepare` after you change a `definition`.
+
+  The discovery artifact's format is now 5: regenerate it with `aventara:prepare` (an artifact of format 4 is refused, as before). The Json Shape type emitter the client generator uses now lives in `@aventara/core`; the generated clients are unchanged. The CLI's agent skill says this in `SKILL.md` and `reference/stages.md`.
+
+- `aventara-build` no longer logs `unchanged:` for `computed-fields.generated.ts` when it keeps that file because the configuration does not type-check: it logs `kept (configuration does not type-check): <file>`, after the type errors, since the kept file may be an earlier version's. The exit code is unchanged (0), so the `postinstall` that runs `aventara:prepare` still completes; fix the errors, then run `aventara:prepare` again.
+- Updated dependencies [aab6d72]
+- Updated dependencies [bf98da7]
+- Updated dependencies [f8cd860]
+- Updated dependencies [8a64af2]
+- Updated dependencies [548881c]
+- Updated dependencies [62fa91f]
+  - @aventara/client@1.0.0-rc.15
+  - @aventara/core@1.0.0-rc.15
+
 ## 1.0.0-rc.14
 
 ### Patch Changes

package/README.md

@@ -17,7 +17,7 @@ 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
+Run it from the project's root. It writes four 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
@@ -27,6 +27,7 @@ configuration that imports no tree keeps `src/generated/aventara/`.
 |---|---|
 | `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 |
+| `config-facts.generated.ts` | `configFacts`: the Json shapes and the fields the root's definitions add, read off the compiled Contracts; the discovery artifact puts them on the model's type, so a pipeline stage's `ctx` and `ctx.$args` know them |
 | `contracts.generated.ts` | `aventaraContracts` (typed `AvPrebuiltContracts`): the compiled Contracts |
 
 ### The Resource tree
@@ -189,7 +190,7 @@ 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
+Writes nothing. It exits 0 when the four 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). 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.

package/dist/cli.js

@@ -6,6 +6,7 @@ import { readConfigComputedFields } from "./computed/computed-fields.reader.js";
 import { emitComputedFieldsModule } from "./computed/computed-fields-file.js";
 import { checkContractsFile } from "./contracts/contracts-file.js";
 import { compilePrebuiltContracts } from "./contracts/prebuilt-contracts.compiler.js";
+import { emitConfigFactsModule, emitUnreadConfigFactsModule, } from "./facts/config-facts-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";
@@ -18,7 +19,7 @@ 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                    write the four 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
 
@@ -29,10 +30,13 @@ Run it from the project's root. It writes, in this order:
       ${RESOURCES_GLOB} export, one \`resources\` tree per layer;
   ${DEFAULT_GENERATED_FILES.computedFields}
       which fields the configuration computes, read off its type;
+  ${DEFAULT_GENERATED_FILES.configFacts}
+      the Json shapes and the fields the configuration's definitions add,
+      read off the compiled Contracts, which pipeline stages' types read;
   ${DEFAULT_GENERATED_FILES.contracts}
       the compiled Contracts, \`aventaraContracts\`.
 
-All three go to the directory the configuration imports \`aventaraResources\`
+All four go to the directory the configuration imports \`aventaraResources\`
 from (src/aventara/ when \`aventara init\` found the ORM's client generated into
 src/generated), else to ${PROJECT_LAYOUTS.nest.generated}/ (${PROJECT_LAYOUTS.next.generated}/
 in a Next.js project).
@@ -188,6 +192,14 @@ export async function runBuild(argv, projectDirectory, output) {
         else {
             noteWrite(wrote(batch.write(generated.resources, tree), generated.resources, counted(found.definitions.length)));
         }
+        const hadFacts = readGeneratedFile(projectDirectory, generated.configFacts) !== undefined;
+        if (check && !hadFacts) {
+            output.stderr(refusal({ file: generated.configFacts, what: "is missing" }));
+            return 1;
+        }
+        if (!check && !hadFacts) {
+            batch.write(generated.configFacts, emitUnreadConfigFactsModule(files.configFile, "the build has not compiled the Contracts yet"));
+        }
         const hadComputed = readGeneratedFile(projectDirectory, generated.computedFields) !==
             undefined;
         if (check && !hadComputed) {
@@ -218,7 +230,7 @@ export async function runBuild(argv, projectDirectory, output) {
             return 1;
         }
         if (kept) {
-            noteWrite(wrote("unchanged", generated.computedFields));
+            noteWrite(`aventara-build: kept (configuration does not type-check): ${generated.computedFields}.`);
         }
         else if (check) {
             const stale = checked(projectDirectory, generated.computedFields, computed, "the fields the configuration computes changed since it was written");
@@ -236,6 +248,17 @@ 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 facts = emitConfigFactsModule(files.configFile, project.internal.configFactsOf(compiled.core), project.internal);
+        if (check) {
+            const stale = checked(projectDirectory, generated.configFacts, facts, "the Json shapes or the fields the configuration's definitions add changed since it was written");
+            if (stale !== undefined) {
+                output.stderr(refusal(stale));
+                return 1;
+            }
+        }
+        else {
+            noteWrite(wrote(batch.write(generated.configFacts, facts), generated.configFacts));
+        }
         const browserClient = clientLayout === undefined
             ? undefined
             : await emitBrowserClient(projectDirectory, clientLayout, {
@@ -268,8 +291,8 @@ export async function runBuild(argv, projectDirectory, output) {
                 return 1;
             }
             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.`);
+                ? `aventara-build: ${generated.resources}, ${generated.computedFields}, ${generated.configFacts} and ${generated.contracts} are up to date.`
+                : `aventara-build: ${generated.resources}, ${generated.computedFields}, ${generated.configFacts}, ${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({

package/dist/client/client-file.js

@@ -8,6 +8,7 @@ export const REGENERATE = "`aventara-build --client` (the project's `aventara:pr
 const ENTRY_BANNER = [
     "// biome-ignore-all format: generated output",
     "// biome-ignore-all lint: generated output",
+    "// biome-ignore-all assist/source/organizeImports: generated output",
     "/* !!! Generated by @aventara/build. Do not edit. !!! */",
     `/* Regenerate with ${REGENERATE}. */`,
 ].join("\n");
@@ -145,6 +146,9 @@ const HOOKS: Pick<AvClientOptions, "onCall" | "onSuccess" | "onError"> = {
 	onError: (call, error) => clientOptions()?.onError?.(call, error),
 };
 `;
+function withoutFinalLineBreak(text) {
+    return text.replace(/\n+$/, "");
+}
 function optionsImport(options) {
     return options === undefined
         ? ""
@@ -158,9 +162,9 @@ function entrySource(style, accessVerbs, options) {
         .join(" | ");
     return `${ENTRY_BANNER}
 
-import { AvClient${options === undefined ? "" : ", type AvClientOptions"} } from ${from(`./${GENERATED_DIRECTORY}/client`)};
+${optionsImport(options)}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)};
@@ -284,10 +288,9 @@ function universalSource(style, accessVerbs, options) {
 
 import { io } from ${JSON.stringify(style.importFileExtension === "" ? "next/cache" : "next/cache.js")};
 import { cache } from "react";
-import { AvClient${options === undefined ? "" : ", type AvClientOptions"} } from ${from(`./${GENERATED_DIRECTORY}/client`)};
-import type { AvFetch } from ${from(`./${GENERATED_DIRECTORY}/runtime/transport`)};
-${optionsImport(options)}
+${optionsImport(options)}import { AvClient${options === undefined ? "" : ", type AvClientOptions"} } from ${from(`./${GENERATED_DIRECTORY}/client`)};
 import { avLazy as lazyCall } from ${from(`./${GENERATED_DIRECTORY}/runtime/operation-set`)};
+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)});
@@ -474,11 +477,11 @@ export async function emitBrowserClient(projectDirectory, layout, source) {
         files: [
             {
                 file: `${layout.folder}/${layout.entry}`,
-                text: entrySource(style, accessVerbs, options),
+                text: withoutFinalLineBreak(entrySource(style, accessVerbs, options)),
             },
             {
                 file: `${layout.folder}/${layout.universal}`,
-                text: universalSource(style, accessVerbs, options),
+                text: withoutFinalLineBreak(universalSource(style, accessVerbs, options)),
             },
             ...tree,
         ],

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

@@ -9,7 +9,12 @@ function literal(computedFields) {
     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 header = [
+        "// biome-ignore-all format: generated output",
+        "// biome-ignore-all lint: generated output",
+        "// biome-ignore-all assist/source/organizeImports: generated output",
+        `// Generated by aventara-build from the type of ${configFile}. Do not edit: regenerate it (aventara:prepare).`,
+    ].join("\n");
     const type = [
         "",
         "// What an adapter's discovery artifact carries on its model's type for the stages that run before compute.",
@@ -26,7 +31,7 @@ export function emitComputedFieldsModule(configFile, reading) {
             "// 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`;
+        ].join("\n")}`;
     }
     return `${[
         header,
@@ -36,5 +41,5 @@ export function emitComputedFieldsModule(configFile, reading) {
         "// 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`;
+    ].join("\n")}`;
 }

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

@@ -51,6 +51,7 @@ export async function compilePrebuiltContracts(project) {
         prebuilt,
         source: internal.emitPrebuiltContracts(prebuilt),
         client: contracts.client,
+        core: contracts.core,
         api,
     };
 }

package/dist/facts/config-facts-file.js

@@ -0,0 +1,50 @@
+const key = (name) => JSON.stringify(name);
+function shapeTypes(json, jsonSchemaType) {
+    const resources = Object.keys(json);
+    if (resources.length === 0) {
+        return "Record<never, never>";
+    }
+    const blocks = resources.map((resource) => {
+        const fields = json[resource] ?? {};
+        const members = Object.keys(fields).map((field) => `\t\t\treadonly ${key(field)}: ${jsonSchemaType(fields[field])};`);
+        return `\t\treadonly ${key(resource)}: {\n${members.join("\n")}\n\t\t};`;
+    });
+    return `{\n${blocks.join("\n")}\n\t}`;
+}
+const headerOf = (configFile) => [
+    "// biome-ignore-all format: generated output",
+    "// biome-ignore-all lint: generated output",
+    "// biome-ignore-all assist/source/organizeImports: generated output",
+    `// Generated by aventara-build from the Contracts compiled from ${configFile}. Do not edit: regenerate it (aventara:prepare).`,
+].join("\n");
+export function emitUnreadConfigFactsModule(configFile, reason) {
+    return `${[
+        headerOf(configFile),
+        "",
+        `// Not read: ${reason.replaceAll("\n", " ")}. Pipeline stages see the model's own fields:`,
+        "// Json fields unshaped, no field the configuration adds.",
+        "export const configFacts = null;",
+        "",
+        "// What an adapter's discovery artifact carries on its model's type for pipeline stages' ctx and arguments:",
+        "// nothing.",
+        "export type AvConfigFacts = undefined;",
+    ].join("\n")}`;
+}
+export function emitConfigFactsModule(configFile, facts, writers) {
+    const literal = JSON.stringify(JSON.parse(writers.canonicalJson(facts)), null, "\t");
+    return `${[
+        headerOf(configFile),
+        "",
+        "// The Json shapes and added fields the root's definitions state: per Resource, each shaped field's JSON Schema",
+        "// and each added field's Contract field. The framework compares it with the configuration at startup and warns",
+        "// when they differ.",
+        `export const configFacts = ${literal} as const;`,
+        "",
+        "// What an adapter's discovery artifact carries on its model's type for pipeline stages' ctx and arguments:",
+        "// each added field, and each shaped Json field's value type.",
+        "export type AvConfigFacts = {",
+        '\treadonly added: (typeof configFacts)["added"];',
+        `\treadonly json: ${shapeTypes(facts.json, writers.jsonSchemaType)};`,
+        "};",
+    ].join("\n")}`;
+}

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

@@ -8,6 +8,7 @@ function filesIn(directory) {
     return {
         resources: `${directory}/${TREE_MODULE}.ts`,
         computedFields: `${directory}/computed-fields.generated.ts`,
+        configFacts: `${directory}/config-facts.generated.ts`,
         contracts: `${directory}/contracts.generated.ts`,
     };
 }

package/dist/resources/resources-file.js

@@ -18,13 +18,24 @@ function localNames(definitions) {
 export function emitResourcesModule(projectDirectory, resourcesFile, definitions, suffix) {
     const file = path.join(projectDirectory, resourcesFile);
     const names = localNames(definitions);
-    const imports = definitions.map((definition, index) => {
+    const imports = definitions
+        .map((definition, index) => {
         const local = names[index];
         const imported = definition.exportName === local
             ? local
             : `${definition.exportName} as ${local}`;
-        return `import { ${imported} } from ${JSON.stringify(relativeSpecifier(file, path.join(projectDirectory, definition.file), suffix))};`;
-    });
+        const specifier = relativeSpecifier(file, path.join(projectDirectory, definition.file), suffix);
+        return {
+            specifier,
+            line: `import { ${imported} } from ${JSON.stringify(specifier)};`,
+        };
+    })
+        .sort((left, right) => left.specifier < right.specifier
+        ? -1
+        : left.specifier > right.specifier
+            ? 1
+            : 0)
+        .map(({ line }) => line);
     const layers = DEFINITION_LAYERS.flatMap((layer) => {
         const spreads = definitions.flatMap((definition, index) => definition.layers.includes(layer)
             ? [`...${names[index]}.${layer}`]
@@ -36,6 +47,9 @@ export function emitResourcesModule(projectDirectory, resourcesFile, definitions
             : [];
     });
     return `${[
+        "// biome-ignore-all format: generated output",
+        "// biome-ignore-all lint: generated output",
+        "// biome-ignore-all assist/source/organizeImports: generated output",
         `// Generated by aventara-build from ${RESOURCES_GLOB}. Do not edit: regenerate it (aventara:prepare).`,
         ...imports,
         "",
@@ -44,5 +58,5 @@ export function emitResourcesModule(projectDirectory, resourcesFile, definitions
         "export const aventaraResources = {",
         ...layers,
         "} as const;",
-    ].join("\n")}\n`;
+    ].join("\n")}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/build",
-  "version": "1.0.0-rc.14",
+  "version": "1.0.0-rc.15",
   "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.14",
+    "@aventara/client": "1.0.0-rc.15",
     "jiti": "2.7.0"
   },
   "peerDependencies": {
-    "@aventara/core": "1.0.0-rc.14",
+    "@aventara/core": "1.0.0-rc.15",
     "typescript": ">=5.7.0 <7"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/core": "1.0.0-rc.14",
+    "@aventara/core": "1.0.0-rc.15",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },