@aventara/cli 0.1.0-pilot.1 → 0.1.0-pilot.3

package/README.md

@@ -9,7 +9,7 @@ aventara init                 # Aventara added to the NestJS 12 project in this
 ```
 
 It is run once, globally or through `npx`; it is not a dependency of the projects it writes. The frontend's side —
-`framework.client.mts` and the generated client — is `@aventara/client`'s (`npx @aventara/client@pilot init`).
+`framework.client.ts` and the generated client — is `@aventara/client`'s (`npx @aventara/client@pilot init`).
 
 ## `aventara new <name>`
 
@@ -17,6 +17,11 @@ 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
+`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
@@ -25,8 +30,9 @@ lockfile, 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, `.env` and service are **reused and never written**; init finds the class
-  extending `PrismaClient` and the module exporting it, or asks.
+  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.
 
 ### Questions and flags
 
@@ -37,7 +43,7 @@ possible answer is shown, not asked.
 | Flag | Question | Default |
 |---|---|---|
 | `<name>` (`new` only) | The project directory. | — (required) |
-| `--orm <family>@<major>` | The ORM, from the adapters that exist (`prisma@7`; `prisma` = its newest). | the only one there is |
+| `--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 |
 | `--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` |
@@ -59,7 +65,8 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 | `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 |
-| `.env` (`DATABASE_URL`), `.gitignore` (`/src/generated/`, `/dev.db*`) | 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`, `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 |

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.js

@@ -1,17 +1,4 @@
-/**
- * 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 const E2E_SPEC = "test/app.e2e-spec.ts";
-/** `nest new`'s `GET /` test, byte for byte: the anchor. */
 const ROOT_TEST = `  it('/ (GET)', () => {
     return request(app.getHttpServer())
       .get('/')
@@ -19,10 +6,6 @@ const ROOT_TEST = `  it('/ (GET)', () => {
       .expect('Hello World!');
   });
 `;
-/**
- * `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 function spliceContractTest(spec, entrypoint) {
     const path = `${entrypoint}/_contract`;
     const at = spec.indexOf(ROOT_TEST);

package/dist/apply/main-cors.anchor.d.ts

@@ -0,0 +1,50 @@
+/**
+ * pilot.3 — the scaffold turns CORS on in `src/main.ts` for the origins listed in
+ * `CORS_ORIGINS`, so a browser frontend on another port (Vite's 5173, a Next.js
+ * dev server on 3001) can call the protocol:
+ *
+ * const corsOrigins = (process.env.CORS_ORIGINS ?? '')…filter(Boolean);
+ * app.enableCors({ origin: corsOrigins.length > 0 ? corsOrigins : false });
+ *
+ * followed by a commented-out platform-level rate limiter.
+ *
+ * **Unset or empty is OFF, never open.** The `cors` package Nest's Express
+ * platform uses — and `@fastify/cors` — answer `Access-Control-Allow-Origin: *`
+ * when given no origin, so the list is never passed through as it is: no origin is
+ * `false`, CORS disabled.
+ *
+ * Like the `app.module.ts` edit, this one is anchored and never reformats: the
+ * lines are inserted after the one statement that creates the application — `const
+ * app = await NestFactory.create(…);`, found in code exactly once — through its
+ * own variable. A `main.ts` that already configures CORS (`enableCors`, or a
+ * `cors` option given to `NestFactory.create`) is the developer's decision and is
+ * left as it is; one with no such statement is not edited, and the lines are
+ * printed instead.
+ */
+/** The variable the inserted lines read. */
+export declare const CORS_ORIGINS_VARIABLE = "CORS_ORIGINS";
+/** What the scaffold's `.env` lists: Vite's dev server, and a Next.js one beside Nest's 3000. */
+export declare const SCAFFOLD_CORS_ORIGINS = "http://localhost:5173,http://localhost:3001";
+/** The main file `nest new` writes. */
+export declare const MAIN_FILE = "src/main.ts";
+export type MainCorsEdit = 
+/** The lines were inserted. */
+{
+    readonly kind: "edited";
+    readonly text: string;
+}
+/** The lines are already there: a previous run's edit. */
+ | {
+    readonly kind: "present";
+}
+/** The developer configures CORS: nothing is changed. */
+ | {
+    readonly kind: "configured";
+} | {
+    readonly kind: "not-anchored";
+    readonly reason: string;
+};
+/** Splices the CORS lines into `text`, or says why they are not. */
+export declare function spliceMainCors(text: string): MainCorsEdit;
+/** What to add by hand when there is no anchor. */
+export declare function mainCorsInstructions(): string;

package/dist/apply/main-cors.anchor.js

@@ -0,0 +1,60 @@
+import { codeIndexes, codeMask } from "../project/source.scanner.js";
+import { RATE_LIMITING_DOCS } from "../templates/docs.links.js";
+export const CORS_ORIGINS_VARIABLE = "CORS_ORIGINS";
+export const SCAFFOLD_CORS_ORIGINS = "http://localhost:5173,http://localhost:3001";
+export const MAIN_FILE = "src/main.ts";
+function corsLines(app, indent) {
+    return [
+        `// The browser origins allowed to call this server: ${CORS_ORIGINS_VARIABLE} in .env,`,
+        "// comma-separated. Unset or empty, CORS stays off.",
+        `const corsOrigins = (process.env.${CORS_ORIGINS_VARIABLE} ?? '')`,
+        "  .split(',')",
+        "  .map((origin) => origin.trim())",
+        "  .filter(Boolean);",
+        `${app}.enableCors({ origin: corsOrigins.length > 0 ? corsOrigins : false });`,
+        ...RATE_LIMIT_LINES(app),
+    ]
+        .map((line) => `${indent}${line}`)
+        .join("\n");
+}
+function RATE_LIMIT_LINES(app) {
+    return [
+        "// Rate limiting: @nestjs/throttler is a Nest guard and does not run on Aventara's",
+        "// routes; a platform-level limiter does. `npm i express-rate-limit`, import",
+        "// { rateLimit } from 'express-rate-limit', pick your limits and uncomment below.",
+        `// See: ${RATE_LIMITING_DOCS}`,
+        `// ${app}.use(rateLimit({ windowMs: 60_000, limit: 100 }));`,
+    ];
+}
+const CREATE = /^([ \t]*)(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*await\s+NestFactory\.create\b[^;]*;[ \t]*$/gm;
+export function spliceMainCors(text) {
+    const code = codeMask(text);
+    const creates = [...text.matchAll(CREATE)].filter((match) => code[match.index + match[1].length]);
+    const create = creates.length === 1 ? creates[0] : undefined;
+    if (create !== undefined) {
+        const lines = corsLines(create[2], create[1]);
+        if (text.includes(lines)) {
+            return { kind: "present" };
+        }
+    }
+    if (codeIndexes(text, code, /\benableCors\b/g).length > 0 ||
+        creates.some((match) => /\bcors\s*:/.test(match[0]))) {
+        return { kind: "configured" };
+    }
+    if (create === undefined) {
+        return {
+            kind: "not-anchored",
+            reason: creates.length === 0
+                ? "it has no `const app = await NestFactory.create(…);` line"
+                : `it has ${creates.length} \`NestFactory.create\` lines, not one`,
+        };
+    }
+    const end = create.index + create[0].length;
+    return {
+        kind: "edited",
+        text: `${text.slice(0, end)}\n${corsLines(create[2], create[1])}${text.slice(end)}`,
+    };
+}
+export function mainCorsInstructions() {
+    return `Add to ${MAIN_FILE}, after the application is created:\n${corsLines("app", "  ")}`;
+}

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,18 @@ 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;
+/**
+ * pilot.3 — `.env`: `KEY="value"` appended after a final newline when no line sets
+ * `key`; a line that does is the developer's, never a conflict, and nothing else
+ * is reordered or rewritten.
+ */
+export declare function appendEnvEntryIfAbsent(text: string | undefined, key: string, value: string): string;
 /** `.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,14 @@ export function mergeEnvFile(text, entries, replaceConflicts) {
     }
     return { text: `${lines.join("\n")}\n`, conflicts };
 }
-/** `.gitignore`: missing lines appended, nothing else touched. */
+export function appendEnvEntryIfAbsent(text, key, value) {
+    const current = text ?? "";
+    if (current.split("\n").some((line) => ENV_LINE.exec(line)?.[1] === key)) {
+        return current;
+    }
+    const separator = current === "" || current.endsWith("\n") ? "" : "\n";
+    return `${current}${separator}${key}="${value}"\n`;
+}
 export function mergeGitignore(text, additions) {
     const lines = text === undefined || text === ""
         ? []
@@ -103,12 +99,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.d.ts

@@ -1,5 +1,6 @@
 export declare const ADAPTER_CATALOG: readonly [{
     readonly id: "prisma7";
+    readonly alias: "prisma7";
     readonly adapterPackage: "@aventara/prisma7-adapter";
     readonly orm: {
         readonly family: "prisma";

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

@@ -1,10 +1,7 @@
-// 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",
+        "alias": "prisma7",
         "adapterPackage": "@aventara/prisma7-adapter",
         "orm": {
             "family": "prisma",

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

@@ -1,16 +1,24 @@
 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;
+    /**
+     * `aventara.adapter.alias`, e.g. `prisma7`: what `--orm` takes. Always
+     * `<orm><major>`, the generator refuses any other.
+     */
+    readonly alias: string;
     /** The adapter package a project installs, e.g. `@aventara/prisma7-adapter`. */
     readonly adapterPackage: string;
     readonly orm: {
@@ -23,17 +31,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;