@aventara/cli 0.1.0-pilot.4 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,345 @@
+# @aventara/cli
+
+## 1.0.0-rc.1
+
+### Patch Changes
+
+- 7e3d06f: Breaking: the configuration has a new shape. Every layer (the root, `application` and `client`) now holds the
+  same six keys: `exposed`, `transactionsStyle`, `limits`, `pipelines`, `resources` and `exemptions`. Everything about
+  one Resource lives under `resources.<Resource>`: its fields, and each field's `definition` and `pipelines`. The old
+  keys are refused when the framework starts, with a message that names where each one moved:
+
+  | Before (rc.0)                                           | Now (rc.1)                                                                          |
+  | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+  | `fields: { Post: { url: { type, nullable, … } } }`      | `resources: { Post: { fields: { url: { definition: { type, nullable, … } } } } }`   |
+  | `behaviors: { Post: { fields: { slug: { create } } } }` | `resources: { Post: { fields: { slug: { pipelines: { compute: { create } } } } } }` |
+  | `transactions: "none"`                                  | `transactionsStyle: "none"`                                                         |
+  | `restrictions`                                          | `exposed` + `exemptions` (see below)                                                |
+  | `@aventara/core/json`                                   | `@aventara/core/avz`                                                                |
+
+  Before:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactions: "interactive",
+    fields: {
+      Post: {
+        url: {
+          type: { scalar: "string" },
+          nullable: false,
+          list: false,
+          lifecycle: ["VIRTUAL"],
+        },
+      },
+    },
+    behaviors: {
+      Post: {
+        fields: {
+          url: {
+            read: {
+              dependsOn: ["slug"],
+              compute: ({ record }) => `/p/${record.slug}`,
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  After:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactionsStyle: "interactive",
+    resources: {
+      Post: {
+        fields: {
+          url: {
+            definition: {
+              type: { scalar: "string" },
+              nullable: false,
+              list: false,
+              lifecycle: ["VIRTUAL"],
+              format: "url",
+            },
+            pipelines: {
+              compute: {
+                read: {
+                  dependsOn: ["slug"],
+                  compute: ({ record }) => `/p/${record.slug}`,
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  What else changed:
+
+  - A field is defined at the root only. A `definition` in `application` or `client` is refused
+    (`CONFIG_FORBIDDEN_IN_OVERLAY`). Define the field
+    at the root; `application` and `client` can still add compute stages to it.
+  - Computed values chain. When the root and an overlay both compute a field, the root's stage runs first and the
+    overlay's receives its result as `value`. A stage can no longer be turned off with `false`. Returning `undefined`
+    keeps the current value. An upsert computes its create branch with `compute.create` and its update branch with
+    `compute.update`.
+  - A discovered field keeps the adapter's facts. On a field the adapter discovered you may restate its own `type`,
+    `nullable` and `list`, and give a Json field its shape (`definition.json`). Setting a different type, any `format`
+    or any `capabilities` on it is refused. `format` is for fields you add, and it must be one of zod's named string
+    formats (`"email"`, `"url"`, `"uuid"`, …); any other name is a type error and refused at startup.
+  - A misplaced key is a type error. In a configuration written inline in `createFramework({ ... })` or
+    `AventaraModule.forRoot`, a key that has no place there (a typo, an old key, `compute` on a relation field, a field
+    name neither your schema nor the root has) is now a type error at that key, and still refused at startup.
+  - A Resource whose name starts with `$` is refused at startup (`$` names are the framework's).
+  - The Json shape builder moved from `@aventara/core/json` to `@aventara/core/avz`. Change the import; `AvZ` is
+    the same.
+
+  `exposed` and `exemptions`, which replace `restrictions`, have their own entry.
+
+- 6317811: Breaking: `exposed` and `exemptions` replace `restrictions`. Every layer (the root, `application` and `client`)
+  says what it exposes with two keys: `exposed`, the layer's default, and `exemptions`, the entries that are the
+  opposite of it.
+
+  - `exposed: true` (the root's default) exposes everything the layer above offers, and `exemptions` lists what to
+    hide. `exposed: false` exposes nothing, and `exemptions` lists the only things to expose.
+  - In `exemptions`, `true` exempts an entry whole, `false` and `[]` exempt nothing, a list exempts the listed
+    entries one level down, and an object goes one level deeper. A Resource takes `true`, `false` or
+    `{ operations, fields }`. Operations are nested: `operations: { find: ["many"], update: { unique: true } }`.
+    A field takes a list of capability names, or an object per capability whose token lists name filter operators,
+    directives, reducers or pagination kinds.
+  - A list now always means "exempt these". rc.0's `filter: ["equals"]` meant "keep only `equals`"; under
+    `exposed: true` the same intent is the list of the operators to remove.
+  - Overlays only narrow. `application` and `client` start from the root's view. An overlay can no longer bring
+    back what the root hid (rc.0's `hidden: false`); that is now refused at startup, and the message names the other
+    overlay to hide it in instead. Expose an entry at the root and hide it in the overlay that must not see it.
+  - An overlay that sets `exemptions` must also set its own `exposed`.
+  - Relation positions are the adapter's: an exemption can no longer narrow where a relation is projected or written.
+  - A unique operation (`find.unique`, `update.unique`, `delete.unique`, `upsert.unique`) needs an identifier. Picking
+    one without the identifier's fields, or hiding every identifier while one stays exposed, is refused at startup
+    with `COMPILER_MISSING_IDENTIFIER` instead of the operation silently disappearing.
+
+  Every name in `exemptions` must exist, in both styles: a Resource, field, family, variant, capability or token the
+  adapter does not offer is refused at startup with its path (`COMPILER_UNKNOWN_RESOURCE`, `COMPILER_UNKNOWN_FIELD`,
+  `COMPILER_UNAVAILABLE_OPERATION`, `COMPILER_UNAVAILABLE_CAPABILITY`), and in a configuration written inline in
+  `createFramework({ ... })` it is a type error first. Under `exposed: true`, hiding in an overlay what the root
+  already hid does nothing.
+
+  Before (rc.0):
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    restrictions: {
+      User: {
+        fields: {
+          passwordHash: { hidden: true },
+          email: { capabilities: { filter: ["equals"] } },
+        },
+      },
+    },
+    client: {
+      restrictions: {
+        AuditLog: { hidden: true },
+        Post: { operations: { delete: { unique: false } } },
+      },
+    },
+  });
+  ```
+
+  After (rc.1):
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    // The root: `exposed` defaults to true, so these are hidden from every origin.
+    exemptions: {
+      resources: {
+        User: {
+          fields: {
+            passwordHash: true,
+            email: { filter: ["contains", "startsWith"] }, // remove every operator but `equals`
+          },
+        },
+      },
+    },
+    client: {
+      exposed: true,
+      exemptions: {
+        resources: {
+          AuditLog: true,
+          Post: { operations: { delete: ["unique"] } },
+        },
+      },
+    },
+  });
+  ```
+
+  Or expose only what a frontend calls:
+
+  ```ts
+    client: {
+      exposed: false,
+      exemptions: {
+        resources: {
+          Post: {
+            operations: { find: ["many", "unique"], create: ["one"] },
+            fields: { id: ["select"], title: ["select", "create"], body: ["select", "create"] },
+          },
+        },
+      },
+    },
+  ```
+
+  `aventara init` and `aventara new` now write `exposed: true` into `src/aventara.config.ts`, with a comment that
+  links the exposure documentation.
+
+- 9c52482: A `$connect` to a row that does not exist now answers `404 A2003` (not found), the same as reading a missing row.
+  Before, it answered `422 A2004`. This covers a to-one `$connect` in `create`, `update` and `upsert`, a to-many
+  `$connect`, and the same writes inside a transaction plan, where `cause.operation` names the step. The message is
+  unchanged: "The operation's arguments referenced a record that does not exist." On `update.first`, the same mistake
+  answered `A2014` before, as if the row had changed underneath; it now answers `A2003` too, and a duplicate unique value
+  written through `update.first` answers `409 A2008` instead of `A3001`.
+
+  Clearer top-level messages for an unknown Resource or operation. `A2001` now says "The requested Resource is not
+  available." and `A2002` says "The requested operation is not available on this Resource.", instead of "Operation
+  arguments failed framework validation.", which stays the message of `A2004`, `A2007` and `A2009`. A transaction step
+  whose operation is outside the standard grammar now carries the same issue message as a single call, naming the
+  operation and the Resource (for example `Operation "dance.one" is not available on Resource "posts".`), instead of
+  "Operation is not part of the standard operation grammar."
+
+  A `$ref` with no `fingerprint` is `V1000` (required value missing) and answers `422 A2004`. Before, it was `V1017`
+  (fingerprint mismatch) under `A2007`. A fingerprint that is present but wrong is still `V1017`.
+
+  `aventara init` and `aventara new` link to the documentation at https://aventara-framework.vercel.app. The old
+  address redirects, so links already written into projects keep working.
+
+- 8db76e7: `aventara new` and `aventara init` write a `diagnostics` sink into `src/aventara.config.ts`. When something fails
+  inside the server, the caller gets a plain 500 and the Nest log said only which request failed; the raw error went to
+  a sink the scaffold did not set. Now the sink logs the raw error with its stack through Nest's `Logger` (context
+  `Aventara`), at error level, right after that line. Replace it with your own reporter when you have one.
+
+- `aventara new` and `aventara init` write `api: '/api'` into `src/aventara.config.ts` (the root key was renamed from
+  `entrypoint`).
+
+## 1.0.0-rc.0
+
+### Major Changes
+
+- First release candidate of Aventara 1.0. The public API is now considered stable; changes before 1.0.0 are possible
+  based on feedback.
+
+### Minor Changes
+
+- 24ffbab: `aventara new`, `aventara init`, `avclient init` and `avclient generate` show their steps while they work, so a long
+  install never looks hung: on a terminal, `[3/4] Installing dependencies (npm install)` with a spinner and the seconds so
+  far, then `✓` or `✗` and its time; in a pipe, in CI or with `NO_COLOR`, one plain line per step (`… done (12.4s)`),
+  with no control sequence. A closing line gives the total time. The steps go to stderr; stdout keeps the results and the
+  next steps. The output of `nest new` and of the install is shown only when it fails, as before, or as it runs with the
+  new `--verbose`.
+
+### Patch Changes
+
+- 24ffbab: Each package ships its `CHANGELOG.md`, so the release notes are in the installed package beside the README.
+- 24ffbab: `aventara new` prints its next steps last — after the initial commit and the closing line — so they are what is on
+  screen when it ends, in a terminal and in a pipe alike.
+
+## 0.1.0-pilot.4
+
+### Patch Changes
+
+- f37dcd6: `@aventara/cli` ships no type declarations: it is a command, run with `npx` or installed globally, and has no API to
+  import.
+- f37dcd6: `aventara new` and `aventara init` add `prebuild`, `prestart`, `prestart:dev` and `prestart:debug` scripts that run
+  `aventara:prepare`, so after a change to `schema.prisma` the next `npm run start:dev` (or `build`, `start`,
+  `start:debug`) regenerates the Prisma client and the discovery artifact before the server compiles — no reinstall
+  needed. npm and pnpm both run these hooks. On an existing project, `aventara init` treats a `prebuild` or `prestart*`
+  script you already have as a conflict, like any other script: kept unless you confirm, replaced with `--yes`.
+
+  The scaffold's rate-limiting note in `src/main.ts` links to the docs:
+  `https://aventara-docs.vercel.app/docs/limits-and-safety#rate-limiting`.
+
+## 0.1.0-pilot.3
+
+### Patch Changes
+
+- d8c128b: `aventara new` and `aventara init` turn CORS on in `src/main.ts`, so a browser frontend on another port can call the
+  API — 0.1.0-pilot.2's scaffold had none, and a browser's preflight got the protocol's answer instead. Right after
+  `const app = await NestFactory.create(AppModule);` they add `app.enableCors({ origin: … })` with the comma-separated
+  origins in `CORS_ORIGINS`, and write `CORS_ORIGINS="http://localhost:5173,http://localhost:3001"` into the `.env` they
+  write. Unset or empty, CORS is **off** (`origin: false`), never open to every origin. A `main.ts` that already
+  configures CORS is left as it is, with a warning; one without that line is not edited, and the lines are printed. Over an
+  existing Prisma setup, whose `.env` init never writes, adding `CORS_ORIGINS` is printed as a next step. Nest's
+  `enableCors` reaches Aventara's routes on Express and Fastify alike: preflights naming the `Aventara-*` headers are
+  allowed, and the calls answered with the origin.
+- 05d39e8: `aventara new` ends with the project's first git commit, `Initial Aventara Scaffold`: every scaffolded file and the
+  install's lockfile, never `.env` (it is in `.gitignore`). 0.1.0-pilot.2 left a repository with nothing committed. Where
+  a commit cannot or should not be made the run still succeeds, saying why in one line: git is not installed, git has no
+  `user.name`/`user.email`, or the directory `new` ran in is already inside a git repository (a monorepo), where no
+  commit is made in either repository. `--skip-git` creates no repository and makes no commit; `aventara init` never
+  commits.
+- 6755a1f: `aventara --help`, `aventara new --help` and `aventara init --help` list the values `--orm`, `--db` and
+  `--package-manager` take, read from the adapter catalog: `--orm <prisma7>`, `--db <sqlite|postgresql>`,
+  `--package-manager <npm|pnpm>`. A refused `--orm` now names the values it takes — "`--orm takes prisma7 (Prisma 7,
+@aventara/prisma7-adapter)`" — where 0.1.0-pilot.2 said "available: Prisma 7", which is not a value the flag accepts.
+- 2afc651: The `main.ts` lines `aventara new` and `aventara init` add now end with a commented-out, platform-level rate limiter
+  and a short note on why: `@nestjs/throttler` is a Nest guard and does not run on Aventara's routes, while Express
+  middleware does. Uncommented (after `npm i express-rate-limit` and its import), it limits the protocol's routes and
+  answers `429` past the limit. Nothing is installed or enabled by default.
+- `CORS_ORIGINS="http://localhost:5173,http://localhost:3001"` is appended to the project's existing `.env` too — over an existing Prisma setup as well — every other line kept, and never when a line already sets `CORS_ORIGINS`; only a reused setup with no `.env` gets it as a printed next step.
+- `--orm` takes an adapter's alias, `prisma7` (Prisma 7, `@aventara/prisma7-adapter`), declared in the adapter's manifest and listed by `--help`; `prisma@7` and `prisma` are no longer accepted.
+
+## 0.1.0-pilot.2
+
+### Patch Changes
+
+- aa65a0c: `aventara new` and `aventara init` add `.env` to the project's `.gitignore` whenever they write the `DATABASE_URL`
+  entry into `.env`. The file is only appended to: existing lines are kept, and nothing is added when `.env` is already
+  listed.
+- e69e88d: The published packages are written for the people who use them. The JavaScript ships without comments; the type
+  declarations keep their documentation, and it, the error messages, the protocol fixtures' labels and the comments in a
+  generated client no longer carry the project's internal development notes.
+- 0ec37d4: `avclient --version` (and `-v`) prints the generator's version and exits 0, and `aventara` now accepts `-v` beside
+  `--version`, so both bins answer the same two flags.
+
+## 0.1.0-pilot.1
+
+### Patch Changes
+
+- 7714ef3: The scaffold's e2e test now proves Aventara is mounted. `aventara new` and `aventara init` add a `GET /api/_contract`
+  → 200 test to Nest's `test/app.e2e-spec.ts`, right after its `GET /` test (ESM and CommonJS), when AventaraModule was
+  added and the spec is Nest's own; a spec of the developer's own is left untouched.
+- 7f2b5d4: The frontend next step is now a command that runs as printed: `pnpm dlx` under pnpm (not `npx`), and, while the CLI is a
+  prerelease, the client's dist-tag read from the CLI's own version — `npx @aventara/client@pilot init` for
+  0.1.0-pilot.N — so a frontend gets the client from the same release instead of nothing (`@aventara/client` has no
+  `latest`).
+- 799346e: The package READMEs (each package's npm page) are rewritten for the people who use the packages. The Prisma 7
+  adapter's README now states the actual behaviour of a to-many relation or `$count` projected on
+  `update.many`/`create.many`: a validation refusal, `A2004` with `V1008`, before any statement runs (it said `A3001`).
+  Every install or run command names the `@pilot` dist-tag.
+- e58aebf: The READMEs show how to call the API by hand: a copy-pasteable `curl` that fetches `/api/_contract` and sends a
+  `find.many` with both identity headers, and runs as printed against a scaffolded server. They also say that
+  Resource keys are the model names as written (`/_resources/User/…`, `avClient.User.find.many`), and that list results are
+  `readonly` arrays (`readonly User[]`).
+- 88408be: `--help` (and `-h`) works after a command: `aventara new --help`, `aventara init --help`, `avclient init --help` and
+  `avclient generate --help` print that command's usage and exit 0, instead of refusing "unknown flag --help". Nothing
+  else on the line is read or run.
+
+## 0.1.0-pilot.0
+
+### Minor Changes
+
+- b65a4f8: New package: `@aventara/cli`, bin `aventara`. `aventara new <name>` runs the pinned `nest new` and adds Aventara;
+  `aventara init` adds Aventara to an existing NestJS 12 project — the Prisma 7 schema, config and service when there is
+  no ORM yet, or the developer's own Prisma setup reused and never written. Every question has a flag; `--yes` accepts the
+  defaults; a non-interactive run without the answers refuses before writing anything. The ORMs and databases on offer
+  come from the adapter packages' own manifests.

package/README.md

@@ -3,13 +3,13 @@
 The `aventara` command: it scaffolds an Aventara server on NestJS 12.
 
 ```bash
-npm i -g @aventara/cli@pilot  # or run it once: npx @aventara/cli@pilot <command>
+npm i -g @aventara/cli@rc  # or run it once: npx @aventara/cli@rc <command>
 aventara new my-api           # a new NestJS project with Aventara
 aventara init                 # Aventara added to the NestJS 12 project in this directory
 ```
 
-It is run once, globally or through `npx`; it is not a dependency of the projects it writes. The frontend's side —
-`framework.client.ts` and the generated client — is `@aventara/client`'s (`npx @aventara/client@pilot init`).
+It is run once, globally or through `npx`; it is not a dependency of the projects it writes. The frontend's side
+(`framework.client.ts` and the generated client) belongs to `@aventara/client` (`npx @aventara/client@rc init`).
 
 ## `aventara new <name>`
 
@@ -17,22 +17,24 @@ Runs the pinned `nest new` (`npx -y @nestjs/cli@12.0.8 new …`, or `pnpm dlx
 `src/app.module.ts` is what that version writes, then runs exactly `aventara init`'s pipeline over the new project and
 installs it. A directory that exists and is not empty is refused before anything runs.
 
-Once installed, the project gets its first git commit, `Initial Aventara Scaffold` — the lockfile in it, `.env` not
-(it is in `.gitignore`). No commit is made, and one line says why, when git is not installed, when git has no
+Once installed, the project gets its first git commit, `Initial Aventara Scaffold`, with the lockfile in it and
+without `.env` (it is in `.gitignore`). No commit is made, and one line says why, when git is not installed, when git has no
 `user.name`/`user.email`, or when the directory is already inside a git repository (a monorepo: commit it there).
 `--skip-git` makes no repository and no commit.
 
 ## `aventara init`
 
-Runs inside an existing **NestJS 12** project (refused: no `package.json`, another Nest major, TypeScript 7, a yarn-only
-lockfile, a project already initialized).
+Runs inside an existing NestJS 12 project. It refuses a directory with no `package.json`, another Nest major,
+TypeScript 7, a yarn-only lockfile, or a project already initialized.
 
-- **No ORM yet:** the ORM and the database are asked (or taken from the flags), and everything below is written.
-- **Prisma already there:** the installed Prisma must be one an Aventara adapter supports — today Prisma 7, `^7.10.0`,
-  SQLite or PostgreSQL, a driver adapter, the `prisma-client` generator — or the run is refused in one sentence, with
-  nothing written. Your schema, Prisma config and service are **reused and never written**, and your `.env` only gains
-  a `CORS_ORIGINS` line at its end when it has none; init finds the class extending `PrismaClient` and the module
-  exporting it, or asks.
+In a project with no ORM yet, the ORM and the database are asked (or taken from the flags), and everything below is
+written.
+
+In a project that already uses Prisma, the installed Prisma must be one an Aventara adapter supports, or the run is
+refused in one sentence with nothing written. Today that is Prisma 7 (`^7.10.0`) on SQLite or PostgreSQL, with a driver
+adapter and the `prisma-client` generator. Your schema, Prisma config and service are reused and never written, and
+your `.env` only gains a `CORS_ORIGINS` line at its end when it has none. Init finds the class extending `PrismaClient`
+and the module exporting it, or asks.
 
 ### Questions and flags
 
@@ -42,15 +44,20 @@ possible answer is shown, not asked.
 
 | Flag | Question | Default |
 |---|---|---|
-| `<name>` (`new` only) | The project directory. | — (required) |
+| `<name>` (`new` only) | The project directory. | required |
 | `--orm <alias>` | The ORM, as an adapter's alias: `prisma7` (Prisma 7, `@aventara/prisma7-adapter`). `--help` lists the aliases that exist. | the only one there is |
 | `--db <provider>` | The database: the adapter's providers (`sqlite`, `postgresql`). | `sqlite` |
-| `--package-manager <npm\|pnpm>` | — | the lockfile's, else the one that launched the CLI, else npm |
+| `--package-manager <npm\|pnpm>` | The package manager. | the lockfile's, else the one that launched the CLI, else npm |
 | `--prisma-service <path#Export>` (`init`) | Your Prisma service, when more than one, or none, is found. | the one found; none → write `src/prisma.service.ts` |
 | `--prisma-module <path#Export>` (`init`) | The Nest module that provides and exports it. | the one found |
 | `--skip-install` | Write the files; print the install instead of running it. | |
 | `--skip-git` (`new`) | Passed to `nest new`. | |
-| `-y`, `--yes` | Accept every unanswered default **and** replace existing content that differs. | |
+| `-y`, `--yes` | Accept every unanswered default, and replace existing content that differs. | |
+| `--verbose` | Show the output of `nest new` and the install as they run. | |
+
+While it works, each step is shown on stderr, such as `[3/4] Installing dependencies (npm install)`. On a terminal it
+has a spinner and the seconds so far; in a pipe, in CI (`CI`) or with `NO_COLOR` it is one plain line per step
+(`… done (12.4s)`). The output of `nest new` and the install is shown only if it fails, or with `--verbose`.
 
 Existing content that differs from what would be written (a `.env` key, a script, a file) is listed, and replaced only
 when you confirm, or with `--yes`; where nobody can be asked, the run stops and touches nothing.
@@ -59,28 +66,28 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 
 | Path | Owner afterwards |
 |---|---|
-| `prisma/schema.prisma` — `prisma-client` generating into `src/generated/prisma`, a `User` model | you |
-| `prisma.config.ts` — loads `.env` itself (Prisma does not) | you |
-| `src/prisma.service.ts` — `PrismaService` extending the client with the driver adapter, refusing a missing `DATABASE_URL` before the server listens; `PrismaModule` | you |
-| `src/aventara.config.ts` — `aventaraConfig(prisma)`: the entrypoint (`/api`), and the restrictions and pipelines you add | you |
-| `src/app.module.ts` — one edit: the imports, `PrismaModule` and `AventaraModule.forRootAsync({ … })`; printed instead when the file is not the shape expected | you |
-| `test/app.e2e-spec.ts` — one edit: a `GET /api/_contract` → 200 test after Nest's `GET /` test; left alone when the file is not Nest's | you |
-| `src/main.ts` — one edit after `NestFactory.create`: `app.enableCors(…)` for the comma-separated origins in `CORS_ORIGINS`, and CORS off when it is unset or empty, then a commented-out platform-level rate limiter (`express-rate-limit`; Nest's `@nestjs/throttler` is a guard, which does not run on Aventara's routes); left alone when the file already configures CORS, printed when it has no such line | you |
+| `prisma/schema.prisma`: `prisma-client` generating into `src/generated/prisma`, a `User` model | you |
+| `prisma.config.ts`: loads `.env` itself (Prisma does not) | you |
+| `src/prisma.service.ts`: `PrismaService` extending the client with the driver adapter, refusing a missing `DATABASE_URL` before the server listens; `PrismaModule` | you |
+| `src/aventara.config.ts`: `aventaraConfig(prisma)`: the `api` mount path (`/api`), a `diagnostics` sink that logs the raw error of a server failure, with its stack, through Nest's `Logger`, and the `exposed`/`exemptions`, `pipelines` and `resources` you add | you |
+| `src/app.module.ts`: one edit that adds the imports, `PrismaModule` and `AventaraModule.forRootAsync({ … })`; printed instead when the file is not the shape expected | you |
+| `test/app.e2e-spec.ts`: one edit that adds a `GET /api/_contract` → 200 test after Nest's `GET /` test; left alone when the file is not Nest's | you |
+| `src/main.ts`: one edit after `NestFactory.create`: `app.enableCors(…)` for the comma-separated origins in `CORS_ORIGINS`, and CORS off when it is unset or empty, then a commented-out platform-level rate limiter (`express-rate-limit`; Nest's `@nestjs/throttler` is a guard, which does not run on Aventara's routes); left alone when the file already configures CORS, printed when it has no such line | you |
 | `.env` (`DATABASE_URL`, and `CORS_ORIGINS="http://localhost:5173,http://localhost:3001"` appended unless a line sets it), `.gitignore` (`/src/generated/`, `/dev.db*`, `.env`) | you |
-| `package.json` — `@aventara/*` at this CLI's version, `prisma`, `@prisma/client` and the driver at `7.10.0`; `aventara:prepare`, run by `postinstall` and by `prebuild`, `prestart`, `prestart:dev` and `prestart:debug`, and the `.env` on the start scripts and `test:e2e` (`--env-file`, `--env-file-if-exists`) | you |
-| `pnpm-workspace.yaml` (pnpm only) — `allowBuilds` for Prisma's and SQLite's install scripts | you |
-| `src/generated/prisma/**`, `src/generated/aventara/discovery.artifact.ts` | **generated** by `aventara:prepare` (run on every install, build and start, so a schema change needs only a restart); never edit |
+| `package.json`: `@aventara/*` at this CLI's version, `prisma`, `@prisma/client` and the driver at `7.10.0`; `aventara:prepare`, run by `postinstall` and by `prebuild`, `prestart`, `prestart:dev` and `prestart:debug`, and the `.env` on the start scripts and `test:e2e` (`--env-file`, `--env-file-if-exists`) | you |
+| `pnpm-workspace.yaml` (pnpm only): `allowBuilds` for Prisma's and SQLite's install scripts | you |
+| `src/generated/prisma/**`, `src/generated/aventara/discovery.artifact.ts` | generated by `aventara:prepare` (run on every install, build and start, so a schema change needs only a restart); never edit |
 
 ### Next steps it prints
 
 ```bash
 npx prisma db push          # create the tables (init never touches a database); pnpm: pnpm exec prisma db push
 npm run start:dev           # GET http://localhost:3000/api/_contract
-npx @aventara/client@pilot init   # in your frontend; pnpm: pnpm dlx @aventara/client@pilot init
+npx @aventara/client@rc init   # in your frontend; pnpm: pnpm dlx @aventara/client@rc init
 ```
 
 The frontend command is the package manager's own runner (`npx`, or `pnpm dlx` under pnpm) and, while the CLI is a
-prerelease, carries its dist-tag (`@pilot`), so the client comes from the same release.
+prerelease, carries its dist-tag (`@rc`), so the client comes from the same release.
 
 With PostgreSQL, set `DATABASE_URL` in `.env` first (init writes Prisma's placeholder, and never asks for a secret).
 
@@ -106,23 +113,29 @@ curl -s -X POST http://localhost:3000/api/_resources/User/find/many \
 Leave out an identity header and the answer is `400 A2000`, naming the header that is missing. The hash changes
 whenever the schema or the configuration does: fetch it again, and regenerate the client.
 
-- **Resource keys are the model names, as written.** `model User` is `User` everywhere: on the wire
-  (`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
-  lower-cased or pluralized.
-- **Results are read-only.** A list result is a `readonly` array: type it `readonly User[]`, not `User[]` —
-  `const users: readonly User[] = await avClient.User.find.many({});`.
+Resource keys are the model names, as written. `model User` is `User` everywhere: on the wire
+(`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
+lower-cased or pluralized.
+
+Results are read-only. A list result is a `readonly` array, so type it `readonly User[]`:
+`const users: readonly User[] = await avClient.User.find.many({});`.
 
 ## Supported
 
-NestJS 12; Node `^22.18.0 || >=24.2.0` (on any other Node the bin refuses in one sentence naming that range;
-on Node 22 use npm ≥ 11 — Node 22's bundled npm 10 cannot install Nest 12's own scaffold; a CommonJS project's jest
-e2e needs Node ≥ 24.9, Nest's and Jest's limit); npm and pnpm (yarn is not supported); ESM and
-CommonJS projects; Prisma 7 (`^7.10.0`) on SQLite and PostgreSQL. The ORMs, majors, databases and drivers on offer are
-**generated** from the Aventara adapter packages that exist (`src/catalog/adapter.catalog.generated.ts`), never listed
-by hand: a future
-`@aventara/prisma8-adapter` appears by existing.
+- NestJS 12.
+- Node `^22.18.0 || >=24.2.0`. On any other Node the bin refuses in one sentence naming that range. On Node 22 use
+  npm ≥ 11, because Node 22's bundled npm 10 cannot install Nest 12's own scaffold. A CommonJS project's jest e2e needs
+  Node ≥ 24.9, which is Nest's and Jest's limit.
+- npm and pnpm. Yarn is not supported.
+- ESM and CommonJS projects.
+- Prisma 7 (`^7.10.0`) on SQLite and PostgreSQL.
+
+The ORMs, majors, databases and drivers on offer are generated from the Aventara adapter packages that exist
+(`src/catalog/adapter.catalog.generated.ts`), never listed by hand, so a future `@aventara/prisma8-adapter` appears
+once it exists.
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/apply/conflict.confirmer.js

@@ -1,5 +1,5 @@
-export class ConflictsNotConfirmedError extends Error {
-    name = "ConflictsNotConfirmedError";
+export class AvConflictsNotConfirmedError extends Error {
+    name = "AvConflictsNotConfirmedError";
 }
 export function conflictWarning(conflicts) {
     return `${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content, and initializing will replace ${conflicts.length === 1 ? "it" : "them"}`;
@@ -10,7 +10,7 @@ export async function confirmConflicts(conflicts, consent) {
     }
     const them = conflicts.length === 1 ? "it" : "them";
     if (!consent.prompter.interactive) {
-        throw new ConflictsNotConfirmedError(`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}`);
+        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}`);
     }
     consent.prompter.say(`aventara: warning: ${conflictWarning(conflicts)}.`);
     const answer = await consent.prompter.ask({
@@ -19,6 +19,6 @@ export async function confirmConflicts(conflicts, consent) {
         defaultValue: "N",
     });
     if (!/^y(?:es)?$/i.test(answer.trim())) {
-        throw new ConflictsNotConfirmedError(`cancelled, and nothing was touched; run again and answer yes to replace ${them}`);
+        throw new AvConflictsNotConfirmedError(`cancelled, and nothing was touched; run again and answer yes to replace ${them}`);
     }
 }

package/dist/cli.js

@@ -1,22 +1,23 @@
 import { readFileSync } from "node:fs";
-import { ConflictsNotConfirmedError } from "./apply/conflict.confirmer.js";
+import { AvConflictsNotConfirmedError } from "./apply/conflict.confirmer.js";
 import { ADAPTER_CATALOG } from "./catalog/adapter.catalog.generated.js";
-import { CliCommandError, commandUsage, parseCliCommand, usage, } from "./command/command.parser.js";
-import { ProjectRefusedError } from "./project/project.inspector.js";
+import { AvCliCommandError, commandUsage, parseCliCommand, usage, } from "./command/command.parser.js";
+import { AvProjectRefusedError } from "./project/project.inspector.js";
 import { runCommand } from "./run/command.runner.js";
-import { InstallFailedError, runInit } from "./run/init.orchestrator.js";
+import { AvInstallFailedError, runInit } from "./run/init.orchestrator.js";
 import { runNew } from "./run/new.orchestrator.js";
-import { UnansweredQuestionsError, } from "./wizard/answer.resolver.js";
-import { createReadlinePrompter, WizardCancelledError, } from "./wizard/readline.prompter.js";
-import { WizardAnswerError } from "./wizard/wizard.questions.js";
+import { progressModeOf } from "./run/step.reporter.js";
+import { AvUnansweredQuestionsError, } from "./wizard/answer.resolver.js";
+import { AvWizardCancelledError, createReadlinePrompter, } from "./wizard/readline.prompter.js";
+import { AvWizardAnswerError } from "./wizard/wizard.questions.js";
 const REFUSALS = [
-    CliCommandError,
-    WizardAnswerError,
-    UnansweredQuestionsError,
-    WizardCancelledError,
-    ProjectRefusedError,
-    ConflictsNotConfirmedError,
-    InstallFailedError,
+    AvCliCommandError,
+    AvWizardAnswerError,
+    AvUnansweredQuestionsError,
+    AvWizardCancelledError,
+    AvProjectRefusedError,
+    AvConflictsNotConfirmedError,
+    AvInstallFailedError,
 ];
 const MANIFEST = new URL("../package.json", import.meta.url);
 function ownVersion() {
@@ -47,6 +48,7 @@ export async function runCli(argv, io) {
                 runner: io.runner ?? runCommand,
                 catalog: io.catalog ?? ADAPTER_CATALOG,
                 aventaraVersion: ownVersion(),
+                progressMode: io.progress ?? "off",
             });
         }
         return await runNew(command, {
@@ -58,6 +60,7 @@ export async function runCli(argv, io) {
             runner: io.runner ?? runCommand,
             catalog: io.catalog ?? ADAPTER_CATALOG,
             aventaraVersion: ownVersion(),
+            progressMode: io.progress ?? "off",
         });
     }
     catch (error) {
@@ -85,6 +88,7 @@ export async function runFromProcess() {
                 process.stderr.write(text);
             },
             prompter,
+            progress: progressModeOf(process.stderr.isTTY, process.env),
         });
     }
     finally {