@aventara/cli 0.1.0-pilot.0 → 0.1.0-pilot.2

package/README.md

@@ -3,13 +3,13 @@
 The `aventara` command: it scaffolds an Aventara server on NestJS 12.
 
 ```bash
-npm i -g @aventara/cli        # or run it once: npx @aventara/cli <command>
+npm i -g @aventara/cli@pilot  # or run it once: npx @aventara/cli@pilot <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 init`).
+`framework.client.ts` and the generated client — is `@aventara/client`'s (`npx @aventara/client@pilot init`).
 
 ## `aventara new <name>`
 
@@ -58,7 +58,8 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 | `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 |
-| `.env` (`DATABASE_URL`), `.gitignore` (`/src/generated/`, `/dev.db*`) | 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 |
+| `.env` (`DATABASE_URL`), `.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`, `postinstall`, 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); never edit |
@@ -68,16 +69,47 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 ```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 init   # in your frontend
+npx @aventara/client@pilot init   # in your frontend; pnpm: pnpm dlx @aventara/client@pilot 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.
+
 With PostgreSQL, set `DATABASE_URL` in `.env` first (init writes Prisma's placeholder, and never asks for a secret).
 
+### Calling it by hand
+
+With the server running, the starter `User` model answers at `/api`:
+
+<!-- pilot-gate:curl -->
+```bash
+# 1. The contract. Its protocol.hash is what every resource request sends as Aventara-Contract-Hash.
+HASH=$(curl -s http://localhost:3000/api/_contract | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).protocol.hash')
+
+# 2. find.many on User, with both identity headers.
+curl -s -X POST http://localhost:3000/api/_resources/User/find/many \
+  -H 'Content-Type: application/json' \
+  -H 'Aventara-Protocol-Version: 1' \
+  -H "Aventara-Contract-Hash: $HASH" \
+  -d '{}'
+# {"data":[],"code":"A1000","cause":null}
+```
+<!-- /pilot-gate:curl -->
+
+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({});`.
+
 ## Supported
 
-NestJS 12; Node `^22.18.0 || >=24.2.0` (measured; on any other Node the bin refuses in one sentence naming that range,
-F-855; on Node 22 use npm ≥ 11 — Node 22's bundled npm 10 cannot install Nest 12's own scaffold, F-854; a CommonJS
-project's jest e2e needs Node ≥ 24.9, Nest's and Jest's limit, F-856); npm and pnpm (yarn is not supported); ESM and
+NestJS 12; Node `^22.18.0 || >=24.2.0` (measured; 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

package/dist/apply/app-module.anchor.d.ts

@@ -1,15 +1,9 @@
 /**
- * R2 — the one edit `aventara init` makes to code the developer owns:
- * `src/app.module.ts` gains import lines and `imports:` entries for
- * `AventaraModule`, spliced at an **anchor** — the `imports: [ … ]` array of the
- * one `@Module({ … })` that decorates `AppModule`.
- *
- * The scan is string- and comment-aware (a `@Module(` or an `imports: [` inside
- * a comment, a string or a template literal is not code), and it never
- * reformats: everything outside the two insertion points keeps its bytes. When
- * the anchor is not found exactly once — two `@Module`s, a computed `imports`,
- * no `imports` at all — nothing is edited and the caller prints the lines to
- * add instead.
+ * The scan is string- and comment-aware (a `@Module(` or an `imports: [` inside a
+ * comment, a string or a template literal is not code), and it never reformats:
+ * everything outside the two insertion points keeps its bytes. When the anchor is
+ * not found exactly once — two `@Module`s, a computed `imports`, no `imports` at
+ * all — nothing is edited and the caller prints the lines to add instead.
  */
 export type AppModuleWiring = {
     /** Complete import declarations, one per line. */

package/dist/apply/app-module.anchor.js

@@ -1,16 +1,3 @@
-/**
- * R2 — the one edit `aventara init` makes to code the developer owns:
- * `src/app.module.ts` gains import lines and `imports:` entries for
- * `AventaraModule`, spliced at an **anchor** — the `imports: [ … ]` array of the
- * one `@Module({ … })` that decorates `AppModule`.
- *
- * The scan is string- and comment-aware (a `@Module(` or an `imports: [` inside
- * a comment, a string or a template literal is not code), and it never
- * reformats: everything outside the two insertion points keeps its bytes. When
- * the anchor is not found exactly once — two `@Module`s, a computed `imports`,
- * no `imports` at all — nothing is edited and the caller prints the lines to
- * add instead.
- */
 import { closing, codeIndexes, codeMask, nextCode, OPENERS, } from "../project/source.scanner.js";
 function indentOf(text, at) {
     const lineStart = text.lastIndexOf("\n", at - 1) + 1;
@@ -22,7 +9,6 @@ function indented(block, indent) {
         .map((line) => (line === "" ? line : `${indent}${line}`))
         .join("\n");
 }
-/** The local names a file's import declarations bind. */
 function importedNames(text, code) {
     const names = new Set();
     for (const at of codeIndexes(text, code, /^import\b/gm)) {
@@ -46,7 +32,6 @@ function importedNames(text, code) {
     }
     return names;
 }
-/** Splices `wiring` into `text` at the anchor, or says why there is no anchor. */
 export function spliceAppModule(text, wiring) {
     const code = codeMask(text);
     const decorators = codeIndexes(text, code, /@Module\s*\(/g);
@@ -74,7 +59,6 @@ export function spliceAppModule(text, wiring) {
         };
     }
     const objectEnd = closing(text, code, object);
-    // `imports` at the object's own level: not inside a nested bracket.
     let depth = 0;
     let key = -1;
     for (let at = object + 1; at < objectEnd; at += 1) {
@@ -116,7 +100,6 @@ export function spliceAppModule(text, wiring) {
     }
     const base = indentOf(text, key);
     const element = `${base}  `;
-    // An entry the developer already lists (their own `PrismaModule`) is not added twice.
     const listed = text.slice(array + 1, arrayEnd);
     const entries = wiring.entries
         .filter((entry) => {
@@ -125,8 +108,6 @@ export function spliceAppModule(text, wiring) {
             !new RegExp(`(^|[\\s,\\[])${name}\\s*,?\\s*($|\\])`, "m").test(listed));
     })
         .map((entry) => indented(entry, element));
-    // The last element needs a trailing comma: placed after its last code
-    // character, so a comment after it stays a comment.
     let lastCode = arrayEnd - 1;
     while (lastCode > array &&
         (!code[lastCode] || /\s/.test(text[lastCode]))) {
@@ -141,7 +122,6 @@ export function spliceAppModule(text, wiring) {
         ...entries,
     ];
     const spliced = `[\n${lines.join("\n")}\n${base}]`;
-    // The import lines go after the last import declaration.
     const declarations = codeIndexes(text, code, /^import\b/gm);
     let insertAt = 0;
     for (const declaration of declarations) {
@@ -149,8 +129,6 @@ export function spliceAppModule(text, wiring) {
         const lineEnd = text.indexOf("\n", end === -1 ? declaration : end);
         insertAt = lineEnd === -1 ? text.length : lineEnd + 1;
     }
-    // A name the file already imports is not imported twice: a wiring line keeps
-    // only the names still missing, and is dropped when none are.
     const imported = importedNames(text, code);
     const missing = wiring.imports.flatMap((line) => {
         const named = /^import\s+(type\s+)?\{([^}]*)\}(\s*from\s*.*)$/.exec(line);
@@ -174,7 +152,6 @@ export function spliceAppModule(text, wiring) {
         text: edited.slice(0, insertAt) + imports + edited.slice(insertAt),
     };
 }
-/** What to add by hand when there is no anchor. */
 export function wiringInstructions(wiring) {
     return [
         "Add to src/app.module.ts:",

package/dist/apply/conflict.confirmer.d.ts

@@ -1,13 +1,4 @@
 import type { Prompter } from "../wizard/answer.resolver.js";
-/**
- * The `generateAt` rule (architect, 2026-10-04; R5 makes it every wizard's
- * conflict rule; P7 — implemented here and in `@aventara/client`, which this
- * package does not import, in the same sentence shape): content the tool did not
- * produce is listed with a warning and replaced only once someone confirms;
- * `--yes` confirms in advance; where nobody can be asked (stdin is not a
- * terminal) the run cancels in one sentence naming `--yes`, exit 1, with
- * nothing touched.
- */
 /** Nobody confirmed replacing existing content. A refusal: nothing was touched. */
 export declare class ConflictsNotConfirmedError extends Error {
     readonly name = "ConflictsNotConfirmedError";

package/dist/apply/conflict.confirmer.js

@@ -1,24 +1,9 @@
-/**
- * The `generateAt` rule (architect, 2026-10-04; R5 makes it every wizard's
- * conflict rule; P7 — implemented here and in `@aventara/client`, which this
- * package does not import, in the same sentence shape): content the tool did not
- * produce is listed with a warning and replaced only once someone confirms;
- * `--yes` confirms in advance; where nobody can be asked (stdin is not a
- * terminal) the run cancels in one sentence naming `--yes`, exit 1, with
- * nothing touched.
- */
-/** Nobody confirmed replacing existing content. A refusal: nothing was touched. */
 export class ConflictsNotConfirmedError extends Error {
     name = "ConflictsNotConfirmedError";
 }
 export function conflictWarning(conflicts) {
     return `${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content, and initializing will replace ${conflicts.length === 1 ? "it" : "them"}`;
 }
-/**
- * Resolves when `conflicts` may be replaced; throws when they may not.
- *
- * @throws ConflictsNotConfirmedError
- */
 export async function confirmConflicts(conflicts, consent) {
     if (conflicts.length === 0 || consent.yes) {
         return;

package/dist/apply/e2e-spec.anchor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * pilot.1 — the scaffold's own e2e spec also proves the protocol is mounted.
+ *
+ * `nest new`'s `test/app.e2e-spec.ts` (`@nestjs/schematics` 12's template, ESM
+ * and CommonJS alike) tests `GET /` and nothing else. Like the `app.module.ts`
+ * edit, this one is anchored on Nest's exact text: the `/ (GET)` test is found
+ * exactly once, and a `GET <entrypoint>/_contract` test is added right after
+ * it, through the spec's own `app` and `request`. A spec that is not Nest's —
+ * the developer's own — is left as it is, and nothing is said: the test is a
+ * convenience, and the developer's tests are theirs.
+ */
+/** The e2e spec `nest new` writes. */
+export declare const E2E_SPEC = "test/app.e2e-spec.ts";
+/**
+ * `spec` with the contract test after Nest's `GET /` test, or `undefined` when
+ * the anchor is not there exactly once, or the contract test already is.
+ */
+export declare function spliceContractTest(spec: string, entrypoint: string): string | undefined;

package/dist/apply/e2e-spec.anchor.js

@@ -0,0 +1,23 @@
+export const E2E_SPEC = "test/app.e2e-spec.ts";
+const ROOT_TEST = `  it('/ (GET)', () => {
+    return request(app.getHttpServer())
+      .get('/')
+      .expect(200)
+      .expect('Hello World!');
+  });
+`;
+export function spliceContractTest(spec, entrypoint) {
+    const path = `${entrypoint}/_contract`;
+    const at = spec.indexOf(ROOT_TEST);
+    if (at === -1 ||
+        spec.indexOf(ROOT_TEST, at + 1) !== -1 ||
+        spec.includes(`'${path}'`)) {
+        return undefined;
+    }
+    const end = at + ROOT_TEST.length;
+    return `${spec.slice(0, end)}
+  it('${path} (GET)', () => {
+    return request(app.getHttpServer()).get('${path}').expect(200);
+  });
+${spec.slice(end)}`;
+}

package/dist/apply/manifest.merger.d.ts

@@ -1,11 +1,11 @@
 /**
  * The merges `aventara init` makes into files a project already has —
- * `package.json`, `.env`, `.gitignore`, `pnpm-workspace.yaml` — each answering
- * the merged text and the **conflicts**: values already there that differ from
- * what would be written (the `generateAt` rule's "content the tool did not
- * produce"). A value already equal to what would be written is no change (P3);
- * a conflict is replaced only once confirmed (`conflict.confirmer.ts`), so each
- * merge is computed with conflicts both kept and replaced.
+ * `package.json`, `.env`, `.gitignore`, `pnpm-workspace.yaml` — each answering the
+ * merged text and the **conflicts**: values already there that differ from what
+ * would be written (the `generateAt` rule's "content the tool did not produce"). A
+ * value already equal to what would be written is no change; a conflict is
+ * replaced only once confirmed (`conflict.confirmer.ts`), so each merge is
+ * computed with conflicts both kept and replaced.
  */
 export type Merge = {
     readonly text: string;
@@ -24,8 +24,8 @@ export type ManifestChanges = {
     /** Scripts to set; a different existing value is a conflict. */
     readonly scripts: Readonly<Record<string, string>>;
     /**
-     * Scripts to rewrite only from a known value (D3): `from` → `to`. Any other
-     * existing value is a conflict; an absent script is left absent.
+     * Scripts to rewrite only from a known value: `from` → `to`. Any other existing
+     * value is a conflict; an absent script is left absent.
      */
     readonly rewrites: Readonly<Record<string, {
         readonly from: string;
@@ -34,14 +34,12 @@ export type ManifestChanges = {
 };
 /** `package.json`, in npm's own layout: two-space JSON, dependencies sorted. */
 export declare function mergePackageManifest(text: string, changes: ManifestChanges, replaceConflicts: boolean): Merge;
-/** `.env`: a missing key is appended as `KEY="value"`, after a final newline (B5). */
+/** `.env`: a missing key is appended as `KEY="value"`, after a final newline. */
 export declare function mergeEnvFile(text: string | undefined, entries: Readonly<Record<string, string>>, replaceConflicts: boolean): Merge;
 /** `.gitignore`: missing lines appended, nothing else touched. */
 export declare function mergeGitignore(text: string | undefined, additions: readonly string[]): Merge;
 /**
- * `pnpm-workspace.yaml`'s `allowBuilds:` (B9: pnpm 12 refuses install scripts
- * until they are allowed — what `pnpm approve-builds` writes). Keys missing
- * under an existing `allowBuilds:` are added there; otherwise the block is
- * appended.
+ * Keys missing under an existing `allowBuilds:` are added there; otherwise the
+ * block is appended.
  */
 export declare function mergePnpmWorkspace(text: string | undefined, packages: readonly string[]): Merge;

package/dist/apply/manifest.merger.js

@@ -1,16 +1,6 @@
-/**
- * The merges `aventara init` makes into files a project already has —
- * `package.json`, `.env`, `.gitignore`, `pnpm-workspace.yaml` — each answering
- * the merged text and the **conflicts**: values already there that differ from
- * what would be written (the `generateAt` rule's "content the tool did not
- * produce"). A value already equal to what would be written is no change (P3);
- * a conflict is replaced only once confirmed (`conflict.confirmer.ts`), so each
- * merge is computed with conflicts both kept and replaced.
- */
 function sorted(record) {
     return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
 }
-/** `package.json`, in npm's own layout: two-space JSON, dependencies sorted. */
 export function mergePackageManifest(text, changes, replaceConflicts) {
     const manifest = JSON.parse(text);
     const conflicts = [];
@@ -66,7 +56,6 @@ function unquoted(value) {
         ? value.slice(1, -1)
         : value;
 }
-/** `.env`: a missing key is appended as `KEY="value"`, after a final newline (B5). */
 export function mergeEnvFile(text, entries, replaceConflicts) {
     const lines = text === undefined || text === ""
         ? []
@@ -90,7 +79,6 @@ export function mergeEnvFile(text, entries, replaceConflicts) {
     }
     return { text: `${lines.join("\n")}\n`, conflicts };
 }
-/** `.gitignore`: missing lines appended, nothing else touched. */
 export function mergeGitignore(text, additions) {
     const lines = text === undefined || text === ""
         ? []
@@ -103,12 +91,6 @@ export function mergeGitignore(text, additions) {
         conflicts: [],
     };
 }
-/**
- * `pnpm-workspace.yaml`'s `allowBuilds:` (B9: pnpm 12 refuses install scripts
- * until they are allowed — what `pnpm approve-builds` writes). Keys missing
- * under an existing `allowBuilds:` are added there; otherwise the block is
- * appended.
- */
 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 === ""

package/dist/aventara.bin.js

@@ -1,15 +1,5 @@
 #!/usr/bin/env node
 import { refuseUnsupportedNode } from "./node-version.guard.js";
-/**
- * `aventara`'s entry, what the manifest's `bin` names (F-855). It always runs — no
- * `import.meta.main` — and checks this Node against the package's
- * `engines.node` before it loads anything else: the program is imported only
- * once the guard admits this Node, so an older Node meets one sentence and exit
- * 1, never a silent exit 0 or a parse error from a module it cannot run.
- *
- * A promise chain rather than a top-level `await`, which Node 12 cannot parse:
- * this file is read by the Nodes the package does not support.
- */
 if (!refuseUnsupportedNode("aventara", new URL("../package.json", import.meta.url))) {
     void import("./cli.js").then((program) => program.runFromProcess());
 }

package/dist/catalog/adapter.catalog.generated.js

@@ -1,7 +1,3 @@
-// biome-ignore-all format: generated output; these bytes are the catalog
-// biome-ignore-all lint: generated output
-/* !!! Generated by @aventara/cli's adapter-catalog generator from each adapter's manifest. Do not edit. !!! */
-/* Regenerate with `pnpm --filter @aventara/cli build` (its `prebuild`). */
 export const ADAPTER_CATALOG = [
     {
         "id": "prisma7",

package/dist/catalog/catalog-entry.interface.d.ts

@@ -1,15 +1,18 @@
 import type { ADAPTER_CATALOG } from "./adapter.catalog.generated.js";
 /**
- * One entry per Aventara adapter package that exists (R13, R14): what the CLI
- * may offer and what it must refuse, every value traced to that adapter's own
- * manifest — its `aventara.adapter` declaration, its `peerDependencies` and its
- * `bin` (Q16-27). The entries are **generated** at this package's build by
- * `scripts/adapter-catalog.generator.ts` into `adapter.catalog.generated.ts`
- * and never edited (P9). The CLI holds no list of ORMs, majors, providers or
- * drivers of its own.
+ * One entry per Aventara adapter package that exists: what the CLI may offer and
+ * what it must refuse, every value traced to that adapter's own manifest — its
+ * `aventara.adapter` declaration, its `peerDependencies` and its `bin`. The
+ * entries are **generated** at this package's build by
+ * `scripts/adapter-catalog.generator.ts` into `adapter.catalog.generated.ts` and
+ * never edited. The CLI holds no list of ORMs, majors, providers or drivers of its
+ * own.
  */
 export type CatalogEntry = {
-    /** The adapter package's ORM stem, e.g. `prisma7` (Q16-33): the wizard's value and the templates' key. */
+    /**
+     * The adapter package's ORM stem, e.g. `prisma7`: the wizard's value and the
+     * templates' key.
+     */
     readonly id: string;
     /** The adapter package a project installs, e.g. `@aventara/prisma7-adapter`. */
     readonly adapterPackage: string;
@@ -23,17 +26,17 @@ export type CatalogEntry = {
         /** The one major `range` admits. */
         readonly major: number;
     };
-    /** `peerDependencies[orm.package]`: the ORM versions the adapter supports (D8). */
+    /** `peerDependencies[orm.package]`: the ORM versions the adapter supports. */
     readonly range: string;
-    /** Packages that identify the ORM family in a project (D10, Q16-27). */
+    /** Packages that identify the ORM family in a project. */
     readonly familyPackages: readonly string[];
-    /** Database providers, in the adapter's order; the first is the default (R10). */
+    /** Database providers, in the adapter's order; the first is the default. */
     readonly providers: readonly string[];
     /** Provider → the driver adapter package for it. */
     readonly drivers: Readonly<Record<string, string>>;
-    /** The ORM generators whose output the adapter reads (B27). */
+    /** The ORM generators whose output the adapter reads. */
     readonly generators: readonly string[];
-    /** The adapter's generate step: its one `bin` (Q16-30). */
+    /** The adapter's generate step: its one `bin`. */
     readonly bin: string;
 };
 export type AdapterCatalog = readonly CatalogEntry[];

package/dist/catalog/catalog.matcher.d.ts

@@ -1,23 +1,17 @@
 import type { AdapterCatalog, CatalogEntry } from "./catalog-entry.interface.js";
 /**
- * R7, R13, R14, D10, P10 — which catalog entry serves a project that already
- * has an ORM, decided from what is **installed** and what each adapter
- * **declares**; this module holds no ORM, version or provider of its own.
- *
- * 1. The ORM family: the catalog entries whose family packages the project
- *    depends on (a pattern ending in `*` is a prefix).
- * 2. Its major: the installed version of the family's ORM package, never the
- *    range in `package.json` (P10: `^7` can resolve to anything in 7, and a
- *    stale lockfile to 6.x). Every other family package installed must be of
- *    that same major — a Prisma 8 CLI or an `@prisma/orm-*` beside a Prisma 7
- *    client is a project mid-migration, refused (D10).
+ * 1. The ORM family: the catalog entries whose family packages the project depends
+ *    on (a pattern ending in `*` is a prefix).
+ * 2. Every other family package installed must be of that same major — a Prisma 8
+ *    CLI or an `@prisma/orm-*` beside a Prisma 7 client is a project
+ *    mid-migration, refused.
  * 3. The entry for that major, or a refusal naming what exists.
  * 4. The installed version inside the entry's declared range.
  * 5. Then what the project's ORM setup declares — provider, driver, generator —
  *    against the entry's providers, drivers and generators.
  *
- * Every refusal is one sentence naming what was found and what the catalog
- * offers. Nothing has been written when one is raised.
+ * Every refusal is one sentence naming what was found and what the catalog offers.
+ * Nothing has been written when one is raised.
  */
 export type MatchVerdict = {
     readonly kind: "matched";

package/dist/catalog/catalog.matcher.js

@@ -35,8 +35,6 @@ export function matchInstalledOrm(catalog, project) {
     }
     const client = installed.find((member) => member.name === ormPackage);
     const clientMajor = client?.version === undefined ? undefined : majorOf(client.version);
-    // D10: one major across the family. The first package off the client's major
-    // (or any, when there is no client) names the project's other major.
     const off = installed.find((member) => member.name !== ormPackage &&
         majorOf(member.version) !== clientMajor);
     const decided = off ?? client;
@@ -62,7 +60,6 @@ export function matchInstalledOrm(catalog, project) {
     }
     return { kind: "matched", entry };
 }
-/** Step 5: the project's provider, driver and generator against what `entry` declares. */
 export function matchOrmSetup(entry, setup) {
     const name = `the ${entry.orm.label} ${entry.orm.major} adapter`;
     if (setup.provider === undefined ||

package/dist/catalog/range.reader.d.ts

@@ -1,17 +1,11 @@
-/**
- * Reading a declared version range for the two facts the CLI needs from one:
- * its lowest version (D1, D9: what `init` pins when it installs the ORM — the
- * adapter's measured floor) and its lowest major (a project's declared Nest and
- * TypeScript ranges, checked before anything is written).
- */
 /** `^7.10.0` → `7.10.0`; `>=7.10.0 <8` → `7.10.0`. */
 export declare function lowestVersionOf(range: string): string;
 /** `^12.0.1` → 12; `~6.0.2` → 6; a range with no number (`latest`, `*`) → `undefined`. */
 export declare function lowestMajorOf(range: string): number | undefined;
 /**
- * Whether an installed `version` is in a declared `range` (R7: the adapter's
- * declaration decides support). Reads the comparator forms an adapter's peer
- * range uses; a pre-release never satisfies (semver's rule for a range whose
- * comparators carry none). Any other form is refused rather than guessed.
+ * Whether an installed `version` is in a declared `range`. Reads the comparator
+ * forms an adapter's peer range uses; a pre-release never satisfies (semver's rule
+ * for a range whose comparators carry none). Any other form is refused rather than
+ * guessed.
  */
 export declare function satisfiesRange(version: string, range: string): boolean;

package/dist/catalog/range.reader.js

@@ -1,11 +1,4 @@
-/**
- * Reading a declared version range for the two facts the CLI needs from one:
- * its lowest version (D1, D9: what `init` pins when it installs the ORM — the
- * adapter's measured floor) and its lowest major (a project's declared Nest and
- * TypeScript ranges, checked before anything is written).
- */
 const VERSION = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
-/** `^7.10.0` → `7.10.0`; `>=7.10.0 <8` → `7.10.0`. */
 export function lowestVersionOf(range) {
     const found = VERSION.exec(range);
     if (found === null) {
@@ -13,19 +6,12 @@ export function lowestVersionOf(range) {
     }
     return `${found[1]}.${found[2] ?? 0}.${found[3] ?? 0}`;
 }
-/** `^12.0.1` → 12; `~6.0.2` → 6; a range with no number (`latest`, `*`) → `undefined`. */
 export function lowestMajorOf(range) {
     const found = VERSION.exec(range);
     return found === null ? undefined : Number(found[1]);
 }
 const RELEASE = /^(\d+)\.(\d+)\.(\d+)$/;
 const COMPARATOR = /^(\^|>=|>|<=|<|=)?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
-/**
- * Whether an installed `version` is in a declared `range` (R7: the adapter's
- * declaration decides support). Reads the comparator forms an adapter's peer
- * range uses; a pre-release never satisfies (semver's rule for a range whose
- * comparators carry none). Any other form is refused rather than guessed.
- */
 export function satisfiesRange(version, range) {
     const release = RELEASE.exec(version);
     if (release === null) {

package/dist/cli.d.ts

@@ -2,9 +2,8 @@ import type { AdapterCatalog } from "./catalog/catalog-entry.interface.js";
 import { type CommandRunner } from "./run/command.runner.js";
 import { type Prompter } from "./wizard/answer.resolver.js";
 /**
- * `aventara` — the bin (R1): `new` and `init`. A refusal is one sentence on
- * stderr and exit 1, never a stack; anything else is a defect and keeps its
- * stack.
+ * `aventara` — the bin: `new` and `init`. A refusal is one sentence on stderr and
+ * exit 1, never a stack; anything else is a defect and keeps its stack.
  *
  * `init` initializes the project in the working directory
  * (`run/init.orchestrator.ts`); `new` creates one with the pinned `nest new` and

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { ConflictsNotConfirmedError } from "./apply/conflict.confirmer.js";
 import { ADAPTER_CATALOG } from "./catalog/adapter.catalog.generated.js";
-import { CliCommandError, parseCliCommand, USAGE, } from "./command/command.parser.js";
+import { CliCommandError, commandUsage, parseCliCommand, USAGE, } from "./command/command.parser.js";
 import { ProjectRefusedError } from "./project/project.inspector.js";
 import { runCommand } from "./run/command.runner.js";
 import { InstallFailedError, runInit } from "./run/init.orchestrator.js";
@@ -27,7 +27,7 @@ export async function runCli(argv, io) {
     try {
         const command = parseCliCommand(argv);
         if (command.command === "help") {
-            io.stdout(USAGE);
+            io.stdout(command.topic === undefined ? USAGE : commandUsage(command.topic));
             return 0;
         }
         if (command.command === "version") {
@@ -66,12 +66,6 @@ export async function runCli(argv, io) {
         return 1;
     }
 }
-/**
- * Runs `aventara` over this process — its arguments, its terminal, its exit
- * code. Called by the bin's entry (`aventara.bin.ts`) once the Node guard has
- * admitted this Node; importing this module runs nothing, which lets `runCli`
- * be tested in process.
- */
 export async function runFromProcess() {
     const prompter = createReadlinePrompter({
         input: process.stdin,

package/dist/command/command.parser.d.ts

@@ -1,10 +1,10 @@
 import { type QuestionId } from "../wizard/wizard.questions.js";
 /**
- * The `aventara` command line (R1, R2, Q16): `new <name>` and `init`, each
- * question's flag from the wizard's table, and the options that are not
- * questions. Unknown, misplaced or repeated arguments are refused in one
- * sentence; a flag's VALUE is the question's to judge, because what is valid
- * (`--db`'s providers) depends on the catalog and on earlier answers.
+ * The `aventara` command line: `new <name>` and `init`, each question's flag from
+ * the wizard's table, and the options that are not questions. Unknown, misplaced
+ * or repeated arguments are refused in one sentence; a flag's VALUE is the
+ * question's to judge, because what is valid (`--db`'s providers) depends on the
+ * catalog and on earlier answers.
  */
 export type ScaffoldCommandName = "new" | "init";
 export type ScaffoldCommand = {
@@ -12,13 +12,16 @@ export type ScaffoldCommand = {
     /** Raw answers by question, from flags and `new`'s positional `<name>`. */
     readonly given: Readonly<Partial<Record<QuestionId, string>>>;
     readonly skipInstall: boolean;
-    /** `new` only: passed through to `nest new` (Q16-7). */
+    /** `new` only: passed through to `nest new`. */
     readonly skipGit: boolean;
-    /** Accepts each unanswered question's default and confirms overwrites (R5). */
+    /** Accepts each unanswered question's default and confirms overwrites. */
     readonly yes: boolean;
 };
-export type CliCommand = {
+export type CliCommand = 
+/** `--help`; with `topic`, `aventara <topic> --help` (pilot.1). */
+{
     readonly command: "help";
+    readonly topic?: ScaffoldCommandName;
 } | {
     readonly command: "version";
 } | ScaffoldCommand;
@@ -26,6 +29,8 @@ export type CliCommand = {
 export declare class CliCommandError extends Error {
     readonly name = "CliCommandError";
 }
+/** `aventara <command> --help` (pilot.1): that command's usage alone. */
+export declare function commandUsage(command: ScaffoldCommandName): string;
 export declare const USAGE: string;
 /** @throws CliCommandError when `argv` is not a command this CLI has. */
 export declare function parseCliCommand(argv: readonly string[]): CliCommand;