@aventara/cli 1.0.0-rc.12 → 1.0.0-rc.14

package/CHANGELOG.md

@@ -1,5 +1,204 @@
 # @aventara/cli
 
+## 1.0.0-rc.14
+
+### Patch Changes
+
+- 1c5eaa3: The agent skill's stage order in `reference/stages.md` now lists every stage `SKILL.md` and the pipelines docs list: policy admission before the guards, the policy write check after the re-check, and output validation before the response. It says where a nested write's targets run their guards, field pipes, validators and write compute (after the top-level operation's stages of the same kind), lists the check of a value compute set in a field the caller's layer hides (`A3000`), and gives the `forceTransaction` order in full: framework validation and policy admission before `BEGIN`, the policy write check and output validation inside the transaction.
+
+  The error catalog's `A4000` and `A4001` entries now state the whole rule for a `state` that rejects with an authentication library's refusal: the envelope it answers, that nothing of the library's error is sent and nothing goes to `diagnostics`, which shapes are not a refusal (`500 A3000`), and every route, MCP tool call and in-process call it applies to.
+
+- 0895a93: `avDehydrate` and `avHydrate` are typed: data handed from a Server Component to a Client Component as props keeps its type, with no cast.
+
+  - `avDehydrate(data)` (`@aventara/next`) returns an `AvDehydrated<T>` for data of type `T`, and `avHydrate(value)` (`@/aventara/client`) of an `AvDehydrated<T>` returns the `T`, its `Date`, `bigint`, `Uint8Array` and `AvDecimal` values included. Type an SWR `fallback` prop `AvDehydrated<T>` and pass `avHydrate(fallback)` to `SWRConfig` as it is.
+  - `AvDehydrated<T>` is new, exported by `@aventara/next` and by the `src/aventara/client.ts` that `aventara-build --client` writes; the two are one type. It is opaque: a plain object, the data itself, or the dehydrated form of another type is a compile error where an `AvDehydrated<T>` is expected.
+  - A Resource or enum named `AvDehydrated` or `avHydrate` is now emitted under a renamed identifier (`AvDehydratedModel`, `avHydrateModel`), with a warning, as other names the generated client owns are. Before, `src/aventara/client.ts`'s own declaration hid a Resource type of that name, which could not be imported from it.
+  - Read data you dehydrate through `@/aventara/universal`: `@/aventara/server` types a decimal as core's `AvDecimal`, while `avHydrate` revives it as the browser client's.
+  - Pass `avHydrate(fallback)` to `SWRConfig`, never the dehydrated value itself: SWR's `fallback` is typed `any`, so the compiler cannot catch it.
+  - `avHydrate` still takes `unknown` and returns `unknown`; `avDehydrate` of an `unknown` value returns an `AvDehydrated<unknown>`. `serializeData: avDehydrate` and `deserializeData: avHydrate` in TanStack Query are written as before.
+  - The agent skills show the SWR props pattern typed, with no cast. The frontend skill's refresh line no longer names `npx`, and says a file you edited is kept with a warning naming it, and replaced with `--force`.
+
+- ec0d332: `avclient skill` no longer ends with "the client skill is up to date" after keeping a file you edited: it says the skill is up to date apart from what the warnings above name, as `aventara skill` does. The server skill now says what the frontend skill holds: a `SKILL.md` with `reference/client.md`'s content, and `reference/client-setup.md`.
+
+## 1.0.0-rc.13
+
+### Patch Changes
+
+- 6c3e25c: `AvZ.oneOf(["USD", "EUR"])` is a string field validator for a closed set of values. It builds an anchored pattern of
+  the values, each one's pattern syntax escaped (`"C++"` and `"a.b"` match only themselves), so the Contract gains no
+  new check: the generated client runs it like any `AvZ.regex`, and the field's type stays `string`. A refused value
+  answers `V1003` with the message `Value must be one of "USD", "EUR".` rather than the pattern. An empty list, or a
+  value that is not a string, is refused when the check is built, and the types refuse both. When the types should name
+  the set as a union, use a Prisma `enum`: Aventara carries it into the Contract and the generated client as a literal
+  union.
+- 33419de: `aventara new` and `aventara init` now work inside a monorepo. Inside a git repository, `aventara new` gives the project no `.git` of its own (`nest new --skip-git`, create-next-app `--disable-git`). Under a pnpm workspace, the scaffold's `allowBuilds` go into the root's `pnpm-workspace.yaml` (confirmed like any change to existing content), the install runs at the root, and the project gets no workspace file or lockfile of its own; a warning says when the root's `packages` do not match the new folder.
+
+  `aventara new --skip-lint` leaves out `nest new`'s oxlint and prettier (their files, scripts and devDependencies). Inside a workspace whose root has its own Biome, ESLint or Prettier configuration, a one-line hint suggests it.
+
+  `aventara new` and `aventara init` print the Aventara version they pin, and, when the registry's `rc` or `latest` tag names a newer one, that version and a command that takes it (`pnpm --config.minimum-release-age=0 dlx …`; naming the exact version alone does not pass a delay you set yourself). A release-age delay (pnpm 11 and later default to one day) is the usual reason `@rc` or `@latest` resolves an older CLI. The lookup runs once the command passes its checks, reads the `@aventara` registry's tags only, with a short timeout, and prints nothing more when offline. The frontend's next step now names `@aventara/client` at the CLI's exact version instead of a dist-tag.
+
+  Inside a pnpm workspace, a folder with its own `pnpm-workspace.yaml` is treated as its own root; the root's `allowBuilds` is edited only for a member its `packages` match, only when something is missing, and only when the file is plain YAML the CLI reads exactly, with `allowBuilds` as a block of `name: true` or `name: false` entries (otherwise nothing is written and the lines to add are printed); the edit is read back and refused if any entry already there would change, keeping explicit `false` entries, comments and CRLF line endings.
+
+- 5cdc922: The agent skill spells its commands for the project's package manager: `pnpm run aventara:prepare`, `pnpm exec tsc`
+  and `pnpm dlx @aventara/cli@… skill` in a pnpm project, the npm forms otherwise. `aventara new` and `aventara init` use
+  the package manager they install with. `aventara skill` reads the nearest lockfile, up to the repository's root, so a
+  server app inside a pnpm workspace gets the pnpm forms. When the nearest lockfile is neither npm's nor pnpm's (a yarn
+  or bun one), or there is none, it uses the package manager that ran it if that is pnpm, and npm's forms otherwise; the
+  CLI supports npm and pnpm only. `reference/errors.md` follows too.
+
+  The skill's guidance also covers more of what agents got wrong:
+
+  - A rule that reads the database is re-checked in `hooks.before` under `forceTransaction`, or made the write's own
+    condition with `update.first`: a guard runs before the transaction opens, so its check can be stale at commit. A new
+    compare-and-set recipe shows it.
+  - Nest guards, interceptors and pipes (`APP_GUARD`, Passport's `AuthGuard`, `@nestjs/throttler`) never run on
+    Aventara's routes; only `app.use` middleware does. There is no built-in rate limit.
+  - Logic that is not one of a model's operations still belongs in your own Nest controller or service.
+  - `ctx` calls and `ctx.$args` are typed without configuration: narrow with a type guard there, never cast.
+  - A computed value a validator refuses answers `500 A3000` when the caller's layer hides the field.
+  - `forceTransaction` needs `transactionsStyle: "interactive"`; `maxTransactionOperations` counts reads too.
+  - New sections: scalars (wire forms, `bigint` and `Date` from a controller), the adapter's transaction options and
+    the SQLite and PostgreSQL differences, server surfaces (`application`, `serverClient`, `client`, the three `Tx`
+    builders), testing (Nest testing module, `framework.client`, `framework.clientTx`, `createFakeAdapter`), the query
+    language next to Prisma's, Resource transaction stages with an example, deploying, the full stage order, what
+    changes the contract hash, `diagnostics` behind an `A3000`, and where the full docs are for agents.
+  - The recipes no longer break on a `String` id.
+
+- 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.
+
+- 2aaa27d: A stage's `ctx` create no longer has to write a field that the root's or the `application` overlay's `compute.create`
+  fills. A `ctx` call runs that compute, and the generated types already state which fields it fills (the
+  `computed-fields.generated.ts` file `aventara-build` writes), so `ctx.Payment.create.one({ data })` type-checks without
+  the computed `employeeId`. A field that only the `client` or `agent` overlay computes is still required, because that
+  compute does not run for a `ctx` call. A model whose types state no computed fields keeps every requirement. The agent
+  skill says so.
+- 2aaa27d: Exemptions take one more value, `"read"`, on a field and on a Resource's `fields`. It names every read capability of
+  the field that the layer above offers: a scalar's `select`, `filter`, `order` and `orderNulls`, a relation's `select`,
+  `include`, `filter`, `order`, `pagination` and `reducers`. On `fields` it applies to every field of the Resource.
+
+  - Under `exposed: false` it exposes reading and no write, so a read-only Resource no longer needs every field listed:
+    `Category: { operations: { find: true }, fields: "read" }`.
+  - Under `exposed: true` it hides reading and keeps the writes, which is the write-only field:
+    `passwordHash: "read"`.
+
+  It compiles to the same Contracts as the capability lists it stands for, hash included. Like every exemption it only
+  narrows: it never brings back a capability the layer above hid, and naming a field the layer above hid is refused as
+  before. `fields: "read"` names relations too, so a relation into a Resource the layer leaves out still fails with
+  `COMPILER_DANGLING_RELATION`. The agent skill documents it.
+
+  Read-only now means no nested write either. A relation does not write rows of a Resource its layer cannot write: one
+  that creates nothing (no create or upsert operation, and no field writable on create) takes no `$create`,
+  `$connectOrCreate` or `$upsert`; one that updates nothing (no update or upsert operation, and no field writable on
+  update) takes no `$update` or `$upsert`; one with no delete operation takes no `$delete`. The fields count with the
+  operations for creates and updates, so a Resource whose create operation is hidden but whose fields stay writable on
+  create is still created through its parent. Relation fields count too, even link-only (`$connect`): if a Resource must
+  create nothing, hide its relations' `create` as well. This holds however the Resource was made read-only, `"read"` or listed
+  capabilities, and also when it has no required field, where a nested `$create: {}` was accepted before. `$connect`,
+  `$disconnect` and `$set` stay.
+
+  What happens follows the layer's `exposed`. Under `exposed: false` the relation's directives are the ones the layer
+  grants (by `true` on the Resource or the field, by the relation's `create` or `update`, or by naming the directive), so
+  such a grant is refused at startup with `COMPILER_READ_ONLY_NESTED_WRITE`: let the relation only link,
+  `author: { select: true, create: ["$connect"] }`. Under `exposed: true` the relation inherits its directives, so they
+  are dropped from it and startup succeeds; a call that sends one gets `V1006`, or "Relation … is not writable during
+  update." when the relation's update had nothing else. Dropping one can leave another Resource with nothing writable, and
+  the nested writes into it go the same way. A layer with `exposed: false` below that names a dropped directive, or grants
+  a member that was removed, is refused with `COMPILER_READ_ONLY_NESTED_WRITE`.
+
+  A configuration under `exposed: true` that hides a Resource's deletes, or every way to create or update it, therefore
+  serves Contracts with fewer directives on the relations into it, and its ClientContract hash changes: regenerate the
+  frontend client. Such a configuration was refused at startup before when a hidden field was required, and otherwise
+  accepted nested creates.
+
+- 6c3e25c: Field validators now judge every value the caller sent before write compute, and each value once. A value the caller
+  sent is judged after the guards, the pipes and its field pipes, before any compute stage runs, and that includes a
+  field that has a `compute.create` or `compute.update` stage of its own. After compute, only a value compute set or
+  changed is judged: a field the caller left out that compute filled, or a caller's value compute replaced. A compute
+  stage that returns `undefined` or the caller's own value changes nothing, so that value is not judged again. The order
+  is now guards → pipes → validators of the caller's values → write compute → validators of what compute set or changed
+  → hooks.
+
+  A compute stage never sees a value its own validators refuse. A caller value that also breaks a compute stage (a
+  quantity that overflows a total, an unknown currency code handed to `Intl.NumberFormat`) answered `500 A3000` before
+  this release; it now answers `422 A2004` with the issue at the field, and no compute stage runs. A bad caller value is
+  refused even when compute would have replaced it: before this release that value was dropped silently. Codes and
+  issue shapes are unchanged. One answer no longer mixes the two kinds: when a caller value is refused, the computed
+  values are not judged yet. In a transaction plan or a forced call, every literal value is judged before the
+  transaction opens; a resolved `$ref` value and a value a Resource transaction pipe changed are judged at their step,
+  before write compute. The agent skill's stage order says so.
+
+- 6c3e25c: A field the configuration adds (`lifecycle: ["VIRTUAL"]`) with `nullable: false` is now a create requirement, like the
+  adapter's own non-null columns: in each layer that lets a caller write it at create, and where no `compute.create` (the
+  root's or that layer's) fills it, it joins the Contract's `createRequirements.required`. A create without it answers
+  `422 A2004` with `V1000` at the field, before any guard runs, and `framework.application`, `framework.client` and the
+  generated client type it as required. A layer that hides the field creates without it, and an update is unchanged. A
+  nullable added field stays optional. A `compute.create` stage that fills such a field and returns `undefined` answers
+  `500 A3000` with an `AvComputedValueError` in the `diagnostics` sink, as it does for a required database column, and
+  nothing is written.
+
+  This changes the Client Contract, and so its hash, for every configuration with such a field: regenerate the frontend
+  client. A configuration that sent a `nullable: false` virtual input only sometimes must now send it on every create, or
+  state it `nullable: true`.
+
+- 5571ebb: `aventara new --host next` runs `create-next-app@16` instead of `@latest`, so a new Next.js major cannot scaffold an
+  app outside `@aventara/next`'s supported range.
+
+  The newest-release lookup of `aventara new` and `aventara init` now asks the registry npm would install
+  `@aventara/cli` from, also when `aventara` runs on its own rather than through npm or pnpm: the `@aventara:registry`
+  setting, then `registry`, from the environment, the project's `.npmrc` or your user `.npmrc`. Only those two settings
+  are read from the files; nothing else in them, auth tokens included, is read or printed. A `${…}` variable in the
+  project's `.npmrc` is not expanded (that value is skipped), and a file that is not a regular file or is over 64 KiB is
+  skipped. The lookup keeps its short
+  timeout and still says nothing when it cannot reach the registry.
+
+- 73aa797: A generated client takes three hooks, one function each: `new AvClient({ onCall, onSuccess, onError })`. They see
+  every call the client makes: an operation, a cached read, a transaction (once, whatever its steps) and a `$access`
+  call, as an `AvCall` (its `kind`, its `label`, the operation's `resource`, `family` and `variant` or the `$access`
+  verb, and its `requestId` when it sends one; never its arguments).
+
+  - `onCall(call)` runs when the call is made, before it is sent and before grouping. It may return, or resolve to,
+    `AvCallAdditions` for that call's request: `headers`, `credentials`, `cache`, `keepalive`, `priority` and
+    `referrerPolicy`. A header the client sets itself (`Content-Type`, `Accept`, the three `Aventara-*` headers), in
+    its canonical or lower-case spelling, and `method`, `body`, `signal`, `redirect` and `mode` are type errors, each
+    typed as the sentence that refuses it. At runtime such a header in any spelling, a name that is not a valid header
+    name and a value no request can carry (a line break, a control character, or a character outside Latin-1) are dropped with a warning (code
+    `AVENTARA_CLIENT_HOOK_HEADER_DROPPED`), once per header name for each `onCall`. The call's own `headers` option
+    wins over `onCall`'s.
+  - Calls share one `POST /_all` only when their additions are equal (in any order). An async `onCall` holds back only
+    its own call: the call is sent when it settles, with the calls queued then. Calls group when their `onCall` settles
+    together with equal additions; an `onCall` doing its own I/O per call sends each call alone, and one awaiting a
+    shared in-flight promise (cleared once it settles) keeps them in one `/_all`. A hanging `onCall` stalls only its own call, an abort settles that call at once (a `$access` call too), and a
+    call made from inside a hook never waits on the call that ran it.
+  - `onSuccess(call, result)` and `onError(call, error)` are sinks, typed as returning `void`, so any function fits
+    (an async one, `() => router.push("/login")`). What they return is ignored, an async one is not awaited, and the caller gets the same value or rejection, never delayed. `onError`
+    sees a refusal, a validation error, a transport failure and an abort, sent alone or inside an Operation Set.
+  - A hook that throws or rejects is reported once as an `AventaraWarning` (code `AVENTARA_CLIENT_HOOK_THREW`, or
+    `console.warn` where there is no `process.emitWarning`), naming the hook and the call, and skipped. A hook's failure, a value that cannot be read included, never reaches
+    the call, the calls sent with it or the process.
+
+  `fetch` stays a transport swap: it must return the `Response` unread. A token every call needs now goes in `onCall`,
+  read through one shared in-flight promise so the calls still group; the skill and the README say so.
+
+- e6495a0: The agent skills cover more of this release. The server skill says that a `state` rejecting with a `401` or `403`
+  status answers `A4000` or `A4001`, that `forceTransaction` also runs under `transactionsStyle: "server"` (the way to
+  keep forced writes atomic without client plans), that an enum field takes no validator, and how SQLite's one
+  connection makes a plain operation wait for an open transaction (`AVENTARA_PRISMA_SQLITE_TRANSACTION_JOINED`, the
+  `driver` check). It no longer says that a `ctx` create must write a field the root's or the `application` overlay's
+  `compute.create` fills. The client guide, in both skills, adds `AvCall` and `AvCallAdditions` for typing a hook, that
+  a hanging `onCall` stalls only its own call, the `AVENTARA_CLIENT_OPTIONS_NO_DEFAULT` warning, the refusal of an
+  entrypoint carrying credentials, and how a client of your own computes a transaction step's `fingerprint` with
+  `AvProtocol.fingerprint`.
+
+- a9260d2: The agent skills cover what an agent needs without opening `node_modules`:
+
+  - The frontend skill (`avclient skill`) now explains what a call returns (`Date`, `bigint`, `AvDecimal`, `Uint8Array`), which error class each code throws (`AvTransportError` included), `error.cause.issues` for form errors, transactions with `$ref`, and a new `reference/client-setup.md`: `framework.client.ts` (`defineClientConfig`, `env`, `AVENTARA_API_URL`, `generateAt`), regenerating after the server changed, `avclient generate --yes` in CI, and the stale-client error (`A2005`, `AvContractMismatchError`). It also links the docs for agents.
+  - The server skill (`aventara skill`) adds `reference/avz.md` (every `AvZ` check and Json shape builder, `AvZ.infer`) and covers the `policy` and `access` keys, MCP token claims in `ctx.$state.mcp.claims`, the Next.js `state` example, `avDehydrate`/`avHydrate` and server transactions in Next.js, testing with `createFakeAdapter` (what `execute` receives and returns), switching the database or driver, `ctx.$sql`, `ctx.$transaction` and `ctx.$transport`, the compute stage types, and the `AVENTARA_PREBUILT_STALE` fallback.
+  - With `@aventara/access` installed, the skill now says to write Access's own skill with `avaccess skill` (`npx avaccess skill`, or `pnpm exec avaccess skill`).
+  - Corrected: a write-only field is written `"read"` everywhere; a field pipe or compute stage that returns `undefined` keeps the value; a read compute may be a plain function and gets `field`, `value`, `record` and `ctx`.
+  - `CONFIG_FORBIDDEN_IN_OVERLAY` in the error catalog now names `managedElsewhere` as well as a field `definition`.
+
 ## 1.0.0-rc.12
 
 ### Patch Changes
@@ -22,7 +221,7 @@
   compound identifier goes with any one of its fields, and the generated client and the server façades no longer offer
   it. A layer that keeps a unique variant with no filterable identifier left fails at startup with
   `COMPILER_MISSING_IDENTIFIER`, as hiding the identifier already did: under `exposed: false`, pick `id: ["select",
-  "filter"]`, not `id: ["select"]`, to keep `find.unique`. The agent skill's Pick example says so.
+"filter"]`, not `id: ["select"]`, to keep `find.unique`. The agent skill's Pick example says so.
 
 ## 1.0.0-rc.11
 

package/README.md

@@ -26,7 +26,7 @@ without `.env` (it is in `.gitignore`). No commit is made, and one line says why
 
 ### `aventara new <name> --host next`
 
-Runs `create-next-app@latest <name> --ts --app --src-dir --import-alias "@/*" --use-<npm|pnpm> --skip-install`, then
+Runs `create-next-app@16 <name> --ts --app --src-dir --import-alias "@/*" --use-<npm|pnpm> --skip-install`, then
 `aventara init`'s pipeline over the new app, then the install. create-next-app asks its own questions on your terminal;
 with `--yes` it takes its defaults instead (and is given `--yes` too), which is also what a run with no terminal needs.
 Its own flags go after `--`, as they are: `aventara new my-app --host next --yes -- --tailwind --eslint`. `--skip-git`

package/dist/apply/conflict.confirmer.js

@@ -10,7 +10,10 @@ export async function confirmConflicts(conflicts, consent) {
     }
     const them = conflicts.length === 1 ? "it" : "them";
     if (!consent.prompter.interactive) {
-        throw new AvConflictsNotConfirmedError(`not initializing, and nothing was touched: ${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content and nobody can be asked (stdin is not a terminal); run \`aventara init --yes\` to replace ${them}`);
+        const rerun = consent.command === "init"
+            ? "run `aventara init --yes`"
+            : "run `aventara new` again with `--yes`";
+        throw new AvConflictsNotConfirmedError(`not ${consent.command === "init" ? "initializing" : "creating the project"}, and nothing was touched: ${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content and nobody can be asked (stdin is not a terminal); ${rerun} to replace ${them}`);
     }
     consent.prompter.say(`aventara: warning: ${conflictWarning(conflicts)}.`);
     const answer = await consent.prompter.ask({

package/dist/apply/lint-tooling.stripper.js

@@ -0,0 +1,32 @@
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+const FILES = [".oxlintrc.json", ".prettierrc"];
+const SCRIPTS = ["lint", "format"];
+const DEV_DEPENDENCIES = ["oxlint", "oxlint-tsgolint", "prettier"];
+export function stripLintTooling(directory) {
+    const removed = [];
+    for (const file of FILES) {
+        try {
+            rmSync(path.join(directory, file));
+            removed.push(file);
+        }
+        catch {
+        }
+    }
+    const manifestFile = path.join(directory, "package.json");
+    const manifest = JSON.parse(readFileSync(manifestFile, "utf8"));
+    for (const [field, names] of [
+        ["scripts", SCRIPTS],
+        ["devDependencies", DEV_DEPENDENCIES],
+    ]) {
+        const record = manifest[field];
+        for (const name of names) {
+            if (record !== undefined && name in record) {
+                delete record[name];
+                removed.push(`package.json's ${field}["${name}"]`);
+            }
+        }
+    }
+    writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+    return removed;
+}

package/dist/apply/manifest.merger.js

@@ -1,3 +1,4 @@
+import { readPnpmWorkspace, } from "./pnpm-workspace.reader.js";
 function sorted(record) {
     return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
 }
@@ -33,6 +34,9 @@ export function mergePackageManifest(text, changes, replaceConflicts) {
         }
         scripts[name] = command;
     }
+    for (const [name, command] of Object.entries(changes.defaults)) {
+        scripts[name] ??= command;
+    }
     for (const [name, { from, to }] of Object.entries(changes.rewrites)) {
         const existing = scripts[name];
         if (existing === undefined || existing === to) {
@@ -99,31 +103,70 @@ export function mergeGitignore(text, additions) {
         conflicts: [],
     };
 }
+export function allowBuildsLines(names) {
+    return ["allowBuilds:", allowBuildsEntries(names)].join("\n");
+}
+export function allowBuildsGuidance(text, names) {
+    return text !== undefined &&
+        /^(?:\?[ ]*)?(?:allowBuilds|"allowBuilds"|'allowBuilds')[ ]*(?::|$)/m.test(text.replace(/^\uFEFF/, ""))
+        ? `add whichever of these are missing under your \`allowBuilds:\` (an explicit \`false\` is yours to keep):\n${allowBuildsEntries(names)}`
+        : `allow these packages' install scripts in it:\n${allowBuildsLines(names)}`;
+}
+export function allowBuildsEntries(names) {
+    return names.map((name) => `  ${quotedYamlKey(name)}: true`).join("\n");
+}
+function quotedYamlKey(name) {
+    return /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(name) ? name : `"${name}"`;
+}
+function onlyInserted(before, after, added) {
+    const was = before.allowBuilds?.entries ?? new Map();
+    const now = after.allowBuilds?.entries;
+    if (after.bom !== before.bom ||
+        after.eol !== before.eol ||
+        now === undefined ||
+        now.size !== was.size + added.length ||
+        [...was].some(([name, value]) => now.get(name) !== value) ||
+        added.some((name) => was.has(name) || now.get(name) !== true)) {
+        return false;
+    }
+    const inserted = added.length + (before.allowBuilds === undefined ? 1 : 0);
+    const at = before.allowBuilds === undefined
+        ? before.lines.length
+        : before.allowBuilds.end;
+    const kept = [
+        ...after.lines.slice(0, at),
+        ...after.lines.slice(at + inserted),
+    ];
+    return (after.lines.length === before.lines.length + inserted &&
+        kept.every((line, index) => line === before.lines[index]));
+}
 export function mergePnpmWorkspace(text, packages) {
-    const quoted = (name) => /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(name) ? name : `"${name}"`;
-    const lines = text === undefined || text === ""
-        ? []
-        : text.replace(/\n$/, "").split("\n");
-    const header = lines.findIndex((line) => /^allowBuilds:\s*$/.test(line));
-    const present = new Set();
-    if (header !== -1) {
-        for (let at = header + 1; at < lines.length && /^\s+\S/.test(lines[at]); at += 1) {
-            const name = /^\s+["']?([^"':]+)["']?\s*:/.exec(lines[at])?.[1];
-            if (name !== undefined) {
-                present.add(name);
-            }
-        }
+    const unsafe = (why) => ({
+        text: text ?? "",
+        conflicts: [],
+        added: [],
+        unsafe: why,
+    });
+    const reading = readPnpmWorkspace(text ?? "");
+    if ("unsafe" in reading) {
+        return unsafe(reading.unsafe);
     }
-    const missing = packages.filter((name) => !present.has(name));
+    const { document } = reading;
+    const block = document.allowBuilds;
+    const missing = [...new Set(packages)].filter((name) => block?.entries.has(name) !== true);
     if (missing.length === 0 && text !== undefined) {
-        return { text, conflicts: [] };
-    }
-    const entries = missing.map((name) => `  ${quoted(name)}: true`);
-    if (header === -1) {
-        lines.push("allowBuilds:", ...entries);
+        return { text, conflicts: [], added: [] };
     }
-    else {
-        lines.splice(header + 1, 0, ...entries);
+    const indent = block?.indent ?? "  ";
+    const entries = missing.map((name) => `${indent}${quotedYamlKey(name)}: true`);
+    const { lines } = document;
+    const merged = block === undefined
+        ? [...lines, "allowBuilds:", ...entries]
+        : [...lines.slice(0, block.end), ...entries, ...lines.slice(block.end)];
+    const after = `${document.bom ? "\uFEFF" : ""}${merged.join(document.eol)}${document.eol}`;
+    const check = readPnpmWorkspace(after);
+    if ("unsafe" in check || !onlyInserted(document, check.document, missing)) {
+        return unsafe("adding to its allowBuilds would not keep it valid");
     }
-    return { text: `${lines.join("\n")}\n`, conflicts: [] };
+    return { text: after, conflicts: [], added: missing };
 }

package/dist/apply/pnpm-workspace.reader.js

@@ -0,0 +1,179 @@
+const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_-]*):(?=[ ]|$)(.*)$/;
+const ENTRY = /^([ ]+)(?:"([^"\\]*)"|'([^']*)'|([A-Za-z0-9_][A-Za-z0-9@/._-]*)):[ ]+(true|false)(?:[ ]+#.*)?[ ]*$/;
+const NOT_A_STRING = /^(?:true|false|null|yes|no|on|off|y|n|[0-9][0-9._a-fA-FoOxX+-]*)$/i;
+const DOUBLE_QUOTED = /^"(?:[^"\\]|\\.)*"[ ]*(?:#.*)?$/;
+const SINGLE_QUOTED = /^'(?:[^']|'')*'[ ]*(?:#.*)?$/;
+function flowClosesOnItsLine(value) {
+    let depth = 0;
+    let quote;
+    for (let at = 0; at < value.length; at += 1) {
+        const char = value[at];
+        if (quote !== undefined) {
+            if (quote === '"' && char === "\\") {
+                at += 1;
+            }
+            else if (char === quote) {
+                quote = undefined;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+        }
+        else if (char === "[" || char === "{") {
+            depth += 1;
+        }
+        else if (char === "]" || char === "}") {
+            depth -= 1;
+            if (depth === 0) {
+                return /^[ ]*(?:#.*)?$/.test(value.slice(at + 1));
+            }
+        }
+    }
+    return false;
+}
+const PROPERTY = /^(?:&[^ ,[\]{}]+|!(?:<[^>]*>|[^ ]*))(?:[ ]+|$)/;
+function endsOnItsLine(inline) {
+    let value = inline;
+    for (let property = PROPERTY.exec(value); property !== null;) {
+        value = value.slice(property[0].length);
+        property = PROPERTY.exec(value);
+    }
+    switch (value[0]) {
+        case '"':
+            return DOUBLE_QUOTED.test(value);
+        case "'":
+            return SINGLE_QUOTED.test(value);
+        case "[":
+        case "{":
+            return flowClosesOnItsLine(value);
+        default:
+            return true;
+    }
+}
+export function readPnpmWorkspace(text) {
+    const unsafe = (why) => ({ unsafe: why });
+    const bom = text.startsWith("\uFEFF");
+    const body = bom ? text.slice(1) : text;
+    if (body.includes("\uFEFF")) {
+        return unsafe("it holds a byte-order mark after its start");
+    }
+    const crlf = body.includes("\r\n");
+    if (crlf ? /\r(?!\n)|(?<!\r)\n/.test(body) : body.includes("\r")) {
+        return unsafe("it mixes line endings");
+    }
+    const lines = body === "" ? [] : body.replace(/\r?\n$/, "").split(/\r?\n/);
+    const keys = new Set();
+    let current;
+    let started = false;
+    let directive = false;
+    let header;
+    let inBlock = false;
+    let end;
+    let indent;
+    const entries = new Map();
+    for (const [at, line] of lines.entries()) {
+        const number = at + 1;
+        if (/^[ ]*\t/.test(line)) {
+            return unsafe(`line ${number} indents with a tab`);
+        }
+        if (/^[ ]*(?:#.*)?$/.test(line)) {
+            continue;
+        }
+        if (line.startsWith(" ")) {
+            if (current === undefined) {
+                return unsafe(`line ${number} is indented before any top-level key`);
+            }
+            if (!inBlock) {
+                continue;
+            }
+            const entry = ENTRY.exec(line);
+            const name = entry?.[2] ?? entry?.[3] ?? entry?.[4];
+            if (entry === null ||
+                name === undefined ||
+                (entry[4] !== undefined && NOT_A_STRING.test(name))) {
+                return unsafe(`line ${number} in its allowBuilds is not a \`name: true\` or \`name: false\` entry`);
+            }
+            if (indent !== undefined && entry[1] !== indent) {
+                return unsafe("its allowBuilds entries are not at one indentation");
+            }
+            if (entries.has(name)) {
+                return unsafe(`its allowBuilds states ${name} more than once`);
+            }
+            indent = entry[1];
+            entries.set(name, entry[5] === "true");
+            end = at + 1;
+            continue;
+        }
+        inBlock = false;
+        if (line.startsWith("%")) {
+            if (started) {
+                return unsafe(`line ${number} is a directive after the document's start`);
+            }
+            directive = true;
+            continue;
+        }
+        if (/^---(?:[ ]|$)/.test(line)) {
+            if (started) {
+                return unsafe("it holds more than one YAML document");
+            }
+            if (!/^---[ ]*(?:#.*)?$/.test(line)) {
+                return unsafe(`line ${number} has content after its \`---\``);
+            }
+            started = true;
+            directive = false;
+            continue;
+        }
+        if (/^\.\.\.(?:[ ]|$)/.test(line)) {
+            return unsafe(`line ${number} ends the document (\`...\`)`);
+        }
+        if (directive) {
+            return unsafe("its directive is not followed by `---`");
+        }
+        started = true;
+        if (/^-(?:[ ]|$)/.test(line)) {
+            if (current === undefined || current.inline) {
+                return unsafe(`line ${number} is a sequence item outside a key's value`);
+            }
+            if (current.name === "allowBuilds") {
+                return unsafe("its allowBuilds is not a block of one entry per line");
+            }
+            continue;
+        }
+        const key = TOP_LEVEL_KEY.exec(line);
+        if (key === null) {
+            return unsafe(`its line ${number}, \`${line.trim()}\`, is not a plain top-level key`);
+        }
+        const name = key[1];
+        const value = key[2].trim();
+        const inline = value !== "" && !value.startsWith("#");
+        if (keys.has(name)) {
+            return unsafe(`it states ${name} more than once`);
+        }
+        keys.add(name);
+        if (inline && !endsOnItsLine(value)) {
+            return unsafe(`line ${number}'s value continues past its line`);
+        }
+        if (name === "allowBuilds") {
+            if (inline) {
+                return unsafe("its allowBuilds is not a block of one entry per line");
+            }
+            header = at;
+            end = at + 1;
+            inBlock = true;
+        }
+        current = { name, inline };
+    }
+    if (directive) {
+        return unsafe("its directive is not followed by `---`");
+    }
+    return {
+        document: {
+            bom,
+            eol: crlf ? "\r\n" : "\n",
+            lines,
+            allowBuilds: header === undefined
+                ? undefined
+                : { header, end: end, indent, entries },
+        },
+    };
+}

package/dist/cli.js

@@ -2,7 +2,10 @@ import { readFileSync } from "node:fs";
 import { AvConflictsNotConfirmedError } from "./apply/conflict.confirmer.js";
 import { ADAPTER_CATALOG } from "./catalog/adapter.catalog.generated.js";
 import { AvCliCommandError, commandUsage, parseCliCommand, usage, } from "./command/command.parser.js";
+import { detectPackageManager } from "./project/package-manager.detector.js";
 import { AvProjectRefusedError } from "./project/project.inspector.js";
+import { registryNewestRelease, releaseLines, } from "./release/newest-release.reader.js";
+import { npmRegistryOf } from "./release/npm-registry.resolver.js";
 import { runCommand } from "./run/command.runner.js";
 import { AvInstallFailedError, runInit } from "./run/init.orchestrator.js";
 import { runNew } from "./run/new.orchestrator.js";
@@ -43,11 +46,21 @@ export async function runCli(argv, io) {
         if (command.command === "skill") {
             return runSkill(command, {
                 directory: io.cwd,
+                env: io.env,
                 stdout: io.stdout,
                 stderr: io.stderr,
                 cliVersion: ownVersion(),
             });
         }
+        const scaffoldCommand = command.command;
+        const release = () => releaseLines({
+            pinned: ownVersion(),
+            command: scaffoldCommand,
+            packageManager: detectPackageManager({
+                userAgent: io.env.npm_config_user_agent,
+            }),
+            read: io.newestRelease,
+        });
         if (command.command === "init") {
             return await runInit(command, {
                 directory: io.cwd,
@@ -59,6 +72,7 @@ export async function runCli(argv, io) {
                 catalog: io.catalog ?? ADAPTER_CATALOG,
                 aventaraVersion: ownVersion(),
                 progressMode: io.progress ?? "off",
+                release,
             });
         }
         return await runNew(command, {
@@ -71,6 +85,7 @@ export async function runCli(argv, io) {
             catalog: io.catalog ?? ADAPTER_CATALOG,
             aventaraVersion: ownVersion(),
             progressMode: io.progress ?? "off",
+            release,
         });
     }
     catch (error) {
@@ -102,6 +117,7 @@ export async function runFromProcess() {
             },
             prompter,
             progress: progressModeOf(process.stderr.isTTY, process.env),
+            newestRelease: registryNewestRelease(npmRegistryOf({ cwd: process.cwd(), env: process.env })),
         });
     }
     finally {

package/dist/command/command.parser.js

@@ -16,6 +16,12 @@ const OPTIONS = [
         commands: ["new"],
         summary: "create no git repository (passed to nest new)",
     },
+    {
+        flag: "--skip-lint",
+        key: "skipLint",
+        commands: ["new"],
+        summary: "leave out nest new's linter and formatter (oxlint, prettier, their files and scripts)",
+    },
     {
         flag: "--yes",
         alias: "-y",
@@ -236,6 +242,7 @@ export function parseCliCommand(argv) {
         given,
         skipInstall: options.skipInstall === true,
         skipGit: options.skipGit === true,
+        ...(options.skipLint === true ? { skipLint: true } : {}),
         yes: options.yes === true,
         ...(options.verbose === true ? { verbose: true } : {}),
         ...(host === undefined ? {} : { host }),