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

package/README.md

@@ -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,10 +65,11 @@ 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*`, `.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 |
+| `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); never edit |
+| `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
 
@@ -107,7 +114,7 @@ whenever the schema or the configuration does: fetch it again, and regenerate th
 
 ## Supported
 
-NestJS 12; Node `^22.18.0 || >=24.2.0` (measured; on any other Node the bin refuses in one sentence naming that range;
+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

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

@@ -36,6 +36,12 @@ export type ManifestChanges = {
 export declare function mergePackageManifest(text: string, changes: ManifestChanges, replaceConflicts: boolean): Merge;
 /** `.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;
 /**

package/dist/apply/manifest.merger.js

@@ -79,6 +79,14 @@ export function mergeEnvFile(text, entries, replaceConflicts) {
     }
     return { text: `${lines.join("\n")}\n`, conflicts };
 }
+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 === ""
         ? []

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,6 +1,7 @@
 export const ADAPTER_CATALOG = [
     {
         "id": "prisma7",
+        "alias": "prisma7",
         "adapterPackage": "@aventara/prisma7-adapter",
         "orm": {
             "family": "prisma",

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

@@ -14,6 +14,11 @@ export type CatalogEntry = {
      * 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: {

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, commandUsage, 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,10 @@ export async function runCli(argv, io) {
     try {
         const command = parseCliCommand(argv);
         if (command.command === "help") {
-            io.stdout(command.topic === undefined ? USAGE : commandUsage(command.topic));
+            const catalog = io.catalog ?? ADAPTER_CATALOG;
+            io.stdout(command.topic === undefined
+                ? usage(catalog)
+                : commandUsage(command.topic, catalog));
             return 0;
         }
         if (command.command === "version") {

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

@@ -1,3 +1,4 @@
+import type { AdapterCatalog } from "../catalog/catalog-entry.interface.js";
 import { type QuestionId } from "../wizard/wizard.questions.js";
 /**
  * The `aventara` command line: `new <name>` and `init`, each question's flag from
@@ -30,7 +31,8 @@ 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;
+export declare function commandUsage(command: ScaffoldCommandName, catalog: AdapterCatalog): string;
+/** `aventara --help`: both commands, each flag with the values `catalog` offers. */
+export declare function usage(catalog: AdapterCatalog): string;
 /** @throws CliCommandError when `argv` is not a command this CLI has. */
 export declare function parseCliCommand(argv: readonly string[]): CliCommand;

package/dist/command/command.parser.js

@@ -1,4 +1,4 @@
-import { INIT_FLAG_QUESTIONS, NEW_QUESTIONS, } from "../wizard/wizard.questions.js";
+import { INIT_FLAG_QUESTIONS, NEW_QUESTIONS, ormAliasesSentence, } from "../wizard/wizard.questions.js";
 export class CliCommandError extends Error {
     name = "CliCommandError";
 }
@@ -28,12 +28,18 @@ const QUESTIONS = {
     init: INIT_FLAG_QUESTIONS,
 };
 const HELP = "run `aventara --help` for usage";
-function usageLines(command) {
+function flagUsage(question, catalog) {
+    const accepted = question.accepts?.(catalog);
+    return `${question.flag} ${accepted === undefined
+        ? (question.placeholder ?? "<value>")
+        : `<${accepted.join("|")}>`}`;
+}
+function usageLines(command, catalog) {
     const rows = [
         ...QUESTIONS[command]
             .filter((question) => question.flag.startsWith("--"))
             .map((question) => [
-            `${question.flag} ${question.placeholder ?? "<value>"}`,
+            flagUsage(question, catalog),
             `${question.label}; asked when omitted`,
         ]),
         ...OPTIONS.filter((option) => option.commands.includes(command)).map((option) => [
@@ -54,33 +60,38 @@ const SYNOPSIS = {
     new: "aventara new <name> [options]",
     init: "aventara init [options]",
 };
-const ASKED = `On a terminal every unanswered question is asked; anywhere else, pass its flag
+function asked(catalog) {
+    return `${ormAliasesSentence(catalog)}.
+On a terminal every unanswered question is asked; anywhere else, pass its flag
 or --yes, or the run stops before writing anything.
 `;
-export function commandUsage(command) {
+}
+export function commandUsage(command, catalog) {
     return `Usage: ${SYNOPSIS[command]}
 
 ${SUMMARY[command]}
 
 Options:
-${usageLines(command)}
+${usageLines(command, catalog)}
 
-${ASKED}`;
+${asked(catalog)}`;
 }
-export const USAGE = `aventara — scaffold an Aventara server on NestJS.
+export function usage(catalog) {
+    return `aventara — scaffold an Aventara server on NestJS.
 
 Usage:
   ${SYNOPSIS.new}   ${SUMMARY.new}
-${usageLines("new")}
+${usageLines("new", catalog)}
 
   ${SYNOPSIS.init}         ${SUMMARY.init}
-${usageLines("init")}
+${usageLines("init", catalog)}
 
   aventara --help                 Print this and exit 0.
   aventara <command> --help       Print that command's usage and exit 0.
   aventara --version, -v          Print this CLI's version and exit 0.
 
-${ASKED}`;
+${asked(catalog)}`;
+}
 export function parseCliCommand(argv) {
     const [command, ...rest] = argv;
     if (command === undefined) {

package/dist/plan/project.planner.js

@@ -1,9 +1,16 @@
 import { spliceAppModule, wiringInstructions, } from "../apply/app-module.anchor.js";
 import { E2E_SPEC, spliceContractTest } from "../apply/e2e-spec.anchor.js";
-import { mergeEnvFile, mergeGitignore, mergePackageManifest, mergePnpmWorkspace, } from "../apply/manifest.merger.js";
+import { CORS_ORIGINS_VARIABLE, MAIN_FILE, mainCorsInstructions, SCAFFOLD_CORS_ORIGINS, spliceMainCors, } from "../apply/main-cors.anchor.js";
+import { appendEnvEntryIfAbsent, mergeEnvFile, mergeGitignore, mergePackageManifest, mergePnpmWorkspace, } from "../apply/manifest.merger.js";
 import { APP_MODULE, } from "../project/project.inspector.js";
 import { SCAFFOLD_ENTRYPOINT, } from "../templates/template.registry.js";
 export const PREPARE_SCRIPT = "aventara:prepare";
+const PREPARED_SCRIPTS = [
+    "build",
+    "start",
+    "start:dev",
+    "start:debug",
+];
 const START_SCRIPTS = {
     start: { from: "nest start", to: "nest start --env-file .env" },
     "start:dev": {
@@ -118,6 +125,31 @@ export function planInit(input) {
         instructions = wiringInstructions(wiring);
         warnings.push(`${APP_MODULE} was not edited: ${edit.reason}; add AventaraModule by hand, as printed below`);
     }
+    const main = input.read(MAIN_FILE);
+    const cors = main === undefined
+        ? { kind: "not-anchored", reason: `there is no ${MAIN_FILE}` }
+        : spliceMainCors(main);
+    if (cors.kind === "edited") {
+        keeping.push(...writeOf(MAIN_FILE, main, cors.text));
+        replacing.push(...writeOf(MAIN_FILE, main, cors.text));
+    }
+    else if (cors.kind === "configured") {
+        warnings.push(`${MAIN_FILE} already configures CORS, so it was left as it is; a browser frontend on another origin is answered only if that configuration allows it`);
+    }
+    else if (cors.kind === "not-anchored") {
+        instructions = [instructions, mainCorsInstructions()]
+            .filter((text) => text !== undefined)
+            .join("\n");
+        warnings.push(`${MAIN_FILE} was not edited: ${cors.reason}; add CORS by hand, as printed below`);
+    }
+    const corsWanted = cors.kind !== "configured";
+    const scaffoldWritesEnv = Object.keys(scaffold.env).length > 0;
+    const env = input.read(".env");
+    const corsStep = corsWanted && !scaffoldWritesEnv && env === undefined
+        ? [
+            `Let a browser frontend call the server: add ${CORS_ORIGINS_VARIABLE}="${SCAFFOLD_CORS_ORIGINS}" to .env (unset, CORS stays off)`,
+        ]
+        : [];
     const versions = {
         [CORE]: input.aventaraVersion,
         [NEST_HOST]: input.aventaraVersion,
@@ -129,6 +161,10 @@ export function planInit(input) {
         scripts: {
             [PREPARE_SCRIPT]: scaffold.prepare,
             postinstall: `${packageManager} run ${PREPARE_SCRIPT}`,
+            ...Object.fromEntries(PREPARED_SCRIPTS.map((script) => [
+                `pre${script}`,
+                `${packageManager} run ${PREPARE_SCRIPT}`,
+            ])),
         },
         rewrites: inspection.usesNestConfig
             ? {}
@@ -137,15 +173,23 @@ export function planInit(input) {
                 "test:e2e": E2E_SCRIPTS[inspection.moduleKind],
             },
     }, replace));
-    const env = input.read(".env");
-    const writesEnv = Object.keys(scaffold.env).length > 0;
-    if (writesEnv) {
-        both(".env", env, (replace) => mergeEnvFile(env, scaffold.env, replace));
+    if (scaffoldWritesEnv || (corsWanted && env !== undefined)) {
+        both(".env", env, (replace) => {
+            const merged = scaffoldWritesEnv
+                ? mergeEnvFile(env, scaffold.env, replace)
+                : { text: env ?? "", conflicts: [] };
+            return corsWanted
+                ? {
+                    text: appendEnvEntryIfAbsent(merged.text, CORS_ORIGINS_VARIABLE, SCAFFOLD_CORS_ORIGINS),
+                    conflicts: merged.conflicts,
+                }
+                : merged;
+        });
     }
     const gitignore = input.read(".gitignore");
     both(".gitignore", gitignore, () => mergeGitignore(gitignore, [
         ...scaffold.gitignore,
-        ...(writesEnv ? [".env"] : []),
+        ...(scaffoldWritesEnv ? [".env"] : []),
     ]));
     if (packageManager === "pnpm" && scaffold.nativeBuilds.length > 0) {
         const workspace = input.read("pnpm-workspace.yaml");
@@ -168,6 +212,7 @@ export function planInit(input) {
                     "The start scripts were left as they are: @nestjs/config loads .env, so make sure it does before Prisma connects.",
                 ]
                 : []),
+            ...corsStep,
             `Start the server: ${run} run start:dev`,
             `In your frontend: ${frontendInitCommand(packageManager, input.aventaraVersion)}`,
         ],

package/dist/run/init.orchestrator.js

@@ -138,12 +138,10 @@ async function prepareReuse(command, io, inspection, detectedPackageManager) {
         throw new ProjectRefusedError(`this project's ${facts.generator} generator block in ${facts.schema} has no output, and the generate step reads the client from it; give it one, such as ../src/generated/${entry.orm.family}`);
     }
     for (const [flag, given, found] of [
-        ["--orm", command.given.orm, `${entry.orm.family}@${entry.orm.major}`],
+        ["--orm", command.given.orm, entry.alias],
         ["--db", command.given.db, provider],
     ]) {
-        if (given !== undefined &&
-            given.trim().toLowerCase() !== found &&
-            !(flag === "--orm" && given.trim().toLowerCase() === entry.orm.family)) {
+        if (given !== undefined && given.trim().toLowerCase() !== found) {
             throw new ProjectRefusedError(`${flag} ${given} does not match this project, which already uses ${found}`);
         }
     }

package/dist/run/new.orchestrator.d.ts

@@ -3,7 +3,9 @@ import { type InitIo } from "./init.orchestrator.js";
 /**
  * `aventara new <name>`: the pinned `nest new`, then **exactly** `aventara init`'s
  * pipeline over the fresh project, with the wizard's answers carried in — so every
- * `new` run exercises the anchored edit, the merges and the templates `init` uses.
+ * `new` run exercises the anchored edit, the merges and the templates `init` uses
+ * — and, after the install, the project's first commit (`scaffold.committer.ts`,
+ * pilot.3).
  *
  * Nest authors its own scaffold: the CLI never writes Nest's files. Its output is
  * pinned by digest, so a `@nestjs/cli` that writes something else stops the run

package/dist/run/new.orchestrator.js

@@ -6,6 +6,7 @@ import { ProjectRefusedError } from "../project/project.inspector.js";
 import { resolveAnswers } from "../wizard/answer.resolver.js";
 import { NEW_QUESTIONS } from "../wizard/wizard.questions.js";
 import { InstallFailedError, runInit, } from "./init.orchestrator.js";
+import { commitScaffold, gitSurroundings } from "./scaffold.committer.js";
 export const NEST_CLI = "@nestjs/cli@12.0.8";
 export const NEST_APP_MODULE_SHA256 = "fe98c4cd2552342272494652287c02e4ef58db3072fcb18513ea831c60f85778";
 function oneOff(packageManager) {
@@ -34,6 +35,9 @@ export async function runNew(command, io) {
     if (existsSync(directory) && readdirSync(directory).length > 0) {
         throw new ProjectRefusedError(`aventara new creates ${directory}, which already exists and is not empty; choose another name, or run aventara init inside an existing project`);
     }
+    const surroundings = command.skipGit
+        ? undefined
+        : await gitSurroundings(io.runner, io.cwd);
     const [runner, prefix] = oneOff(packageManager);
     const args = [
         ...prefix,
@@ -58,10 +62,10 @@ export async function runNew(command, io) {
     if (digest !== NEST_APP_MODULE_SHA256) {
         throw new InstallFailedError(`nest new's output changed: ${appModule} is not what ${NEST_CLI} writes (sha256 ${digest}), so nothing of Aventara's was written over it; run aventara init inside ${directory} to add Aventara to it`);
     }
-    return runInit({
+    const initialized = await runInit({
         command: "init",
         given: {
-            orm: `${orm.orm.family}@${orm.orm.major}`,
+            orm: orm.alias,
             db,
             packageManager,
         },
@@ -69,4 +73,8 @@ export async function runNew(command, io) {
         skipGit: false,
         yes: true,
     }, { ...io, directory, firstSteps: [`Enter the project: cd ${name}`] });
+    if (initialized === 0 && surroundings !== undefined) {
+        io.stdout(`aventara: ${await commitScaffold(io.runner, directory, surroundings, io.cwd)}.\n`);
+    }
+    return initialized;
 }

package/dist/run/scaffold.committer.d.ts

@@ -0,0 +1,28 @@
+import type { CommandRunner } from "./command.runner.js";
+/**
+ * pilot.3 — `aventara new` ends with one commit of the whole scaffold, the
+ * install's lockfile included, under one fixed message. `.env` is not in it: the
+ * scaffold's `.gitignore` lists it (Nest's own does too). `init` never commits:
+ * the project is the developer's.
+ *
+ * Never a failure: where a commit cannot or should not be made, one line says why
+ * and the run still succeeds —
+ * - git is not installed;
+ * - the directory `new` ran in is inside a git work tree already (a monorepo): the
+ *   project belongs to that repository, and gets no commit of its own;
+ * - git has no `user.name` and `user.email` to commit as. `--skip-git` (passed to
+ *   `nest new`, which then initializes no repository) makes no commit and says
+ *   nothing.
+ *
+ * git runs through the one process seam, `CommandRunner`.
+ */
+export declare const INITIAL_COMMIT_MESSAGE = "Initial Aventara Scaffold";
+/** Where `new` runs, as git sees it — read BEFORE `nest new` initializes a repository. */
+export type GitSurroundings = "no-git" | "inside-work-tree" | "outside";
+/** Whether git is installed, and whether `directory` lies in a work tree. */
+export declare function gitSurroundings(runner: CommandRunner, directory: string): Promise<GitSurroundings>;
+/**
+ * Commits the project in `directory` as its first commit, or says why not: the
+ * line to print, without the `aventara: ` prefix or the final period.
+ */
+export declare function commitScaffold(runner: CommandRunner, directory: string, surroundings: GitSurroundings, enclosing: string): Promise<string>;

package/dist/run/scaffold.committer.js

@@ -0,0 +1,53 @@
+import { realpathSync } from "node:fs";
+export const INITIAL_COMMIT_MESSAGE = "Initial Aventara Scaffold";
+function isMissingCommand(error) {
+    return (error instanceof Error &&
+        error.code === "ENOENT");
+}
+export async function gitSurroundings(runner, directory) {
+    try {
+        const answered = await runner("git", ["rev-parse", "--is-inside-work-tree"], { cwd: directory });
+        return answered.code === 0 && answered.stdout.trim() === "true"
+            ? "inside-work-tree"
+            : "outside";
+    }
+    catch (error) {
+        if (isMissingCommand(error)) {
+            return "no-git";
+        }
+        throw error;
+    }
+}
+export async function commitScaffold(runner, directory, surroundings, enclosing) {
+    if (surroundings === "no-git") {
+        return "no initial commit: git is not installed";
+    }
+    if (surroundings === "inside-work-tree") {
+        return `no initial commit: ${enclosing} is inside a git repository already; commit the project there`;
+    }
+    const git = (args) => runner("git", args, { cwd: directory });
+    for (const key of ["user.name", "user.email"]) {
+        const set = await git(["config", key]);
+        if (set.code !== 0 || set.stdout.trim() === "") {
+            return "no initial commit: git has no user.name and user.email set; set them, then commit the project yourself";
+        }
+    }
+    const top = await git(["rev-parse", "--show-toplevel"]);
+    if (top.code !== 0 ||
+        realpathSync(top.stdout.trim()) !== realpathSync(directory)) {
+        const initialized = await git(["init", "-q"]);
+        if (initialized.code !== 0) {
+            return `no initial commit: \`git init\` exited with code ${initialized.code}: ${initialized.stderr.trim()}`;
+        }
+    }
+    for (const args of [
+        ["add", "-A"],
+        ["commit", "-q", "-m", INITIAL_COMMIT_MESSAGE],
+    ]) {
+        const ran = await git(args);
+        if (ran.code !== 0) {
+            return `no initial commit: \`git ${args.join(" ")}\` exited with code ${ran.code}: ${ran.stderr.trim()}`;
+        }
+    }
+    return `committed the scaffold: "${INITIAL_COMMIT_MESSAGE}"`;
+}

package/dist/templates/docs.links.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where the public documentation lives: the one base every link the scaffold
+ * writes into a project starts from. A placeholder until the docs domain is
+ * settled; changing it changes only comments in the files the CLI writes.
+ */
+export declare const DOCS_BASE_URL = "https://<docs-domain>";
+/** The documentation's rate-limiting section, linked from the scaffold's `main.ts`. */
+export declare const RATE_LIMITING_DOCS = "https://<docs-domain>/docs/limits-and-safety#rate-limiting";

package/dist/templates/docs.links.js

@@ -0,0 +1,2 @@
+export const DOCS_BASE_URL = "https://aventara-docs.vercel.app";
+export const RATE_LIMITING_DOCS = `${DOCS_BASE_URL}/docs/limits-and-safety#rate-limiting`;

package/dist/wizard/wizard.questions.d.ts

@@ -56,7 +56,7 @@ export type WizardContext = {
     readonly services?: ServiceContext;
 };
 export type Choice = {
-    /** What the flag takes and the prompt accepts, e.g. `prisma@7`. */
+    /** What the flag takes and the prompt accepts, e.g. `prisma7`. */
     readonly value: string;
     /** How it is shown, e.g. `Prisma 7`. */
     readonly label: string;
@@ -77,6 +77,11 @@ export type WizardQuestion<K extends QuestionId> = {
     readonly after?: QuestionId;
     /** The answers on offer, or `undefined` for free text. */
     readonly choices: (context: WizardContext) => readonly Choice[] | undefined;
+    /**
+     * Every value its flag takes before anything is answered — what `--help`
+     * lists (pilot.3); absent for free text. From the catalog, never a literal.
+     */
+    readonly accepts?: (catalog: AdapterCatalog) => readonly string[];
     /** The answer `--yes` (or Enter at the prompt) takes; `undefined` when there is none. */
     readonly defaultFor: (context: WizardContext) => string | undefined;
     /** @throws WizardAnswerError when `raw` is not an answer to this question. */
@@ -87,7 +92,15 @@ export type WizardQuestion<K extends QuestionId> = {
 export type AnyWizardQuestion = {
     readonly [K in QuestionId]: WizardQuestion<K>;
 }[QuestionId];
+/**
+ * What `--orm` takes: each adapter's alias, with what it is — the refusal's words,
+ * and the usage's.
+ */
+export declare function ormAliasesSentence(catalog: AdapterCatalog): string;
 export declare const NAME_QUESTION: WizardQuestion<"name">;
+/**
+ * The prompt keeps the family-then-major order; every answer is an alias.
+ */
 export declare const ORM_QUESTION: WizardQuestion<"orm">;
 export declare const DB_QUESTION: WizardQuestion<"db">;
 export declare const PACKAGE_MANAGER_QUESTION: WizardQuestion<"packageManager">;

package/dist/wizard/wizard.questions.js

@@ -6,14 +6,19 @@ export class WizardAnswerError extends Error {
 function ormLabel(entry) {
     return `${entry.orm.label} ${entry.orm.major}`;
 }
-function available(catalog) {
-    return catalog
-        .map((entry) => `${ormLabel(entry)} (${entry.adapterPackage})`)
-        .join(", ");
+function listed(items) {
+    return items.length <= 1
+        ? items.join("")
+        : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+}
+function families(catalog) {
+    return [...new Set(catalog.map((entry) => entry.orm.family))];
+}
+export function ormAliasesSentence(catalog) {
+    return `--orm takes ${listed(ormChoices(catalog).map((entry) => `${entry.alias} (${ormLabel(entry)}, ${entry.adapterPackage})`))}`;
 }
 function ormChoices(catalog) {
-    const families = [...new Set(catalog.map((entry) => entry.orm.family))];
-    return families.flatMap((family) => catalog
+    return families(catalog).flatMap((family) => catalog
         .filter((entry) => entry.orm.family === family)
         .sort((left, right) => right.orm.major - left.orm.major));
 }
@@ -38,24 +43,16 @@ export const ORM_QUESTION = {
     flag: "--orm",
     label: "ORM",
     choices: (context) => ormChoices(context.catalog).map((entry) => ({
-        value: `${entry.orm.family}@${entry.orm.major}`,
+        value: entry.alias,
         label: ormLabel(entry),
     })),
-    defaultFor: (context) => context.catalog.length === 1
-        ? `${context.catalog[0]?.orm.family}@${context.catalog[0]?.orm.major}`
-        : undefined,
+    accepts: (catalog) => ormChoices(catalog).map((entry) => entry.alias),
+    defaultFor: (context) => context.catalog.length === 1 ? context.catalog[0]?.alias : undefined,
     parse: (raw, context) => {
-        const [family, major, ...rest] = raw.trim().toLowerCase().split("@");
-        const offered = ormChoices(context.catalog).filter((entry) => entry.orm.family === family);
-        if (rest.length > 0 || offered.length === 0) {
-            throw new WizardAnswerError(`there is no Aventara adapter for the ORM ${JSON.stringify(raw)}; available: ${available(context.catalog)}`);
-        }
-        if (major === undefined) {
-            return offered[0];
-        }
-        const entry = offered.find((candidate) => String(candidate.orm.major) === major);
+        const alias = raw.trim().toLowerCase();
+        const entry = context.catalog.find((candidate) => candidate.alias === alias);
         if (entry === undefined) {
-            throw new WizardAnswerError(`there is no Aventara adapter for ${offered[0]?.orm.label} ${major}; available: ${available(context.catalog)}`);
+            throw new WizardAnswerError(`there is no Aventara adapter for the ORM ${JSON.stringify(raw)}; ${ormAliasesSentence(context.catalog)}`);
         }
         return entry;
     },
@@ -77,6 +74,9 @@ export const DB_QUESTION = {
         value: provider,
         label: provider,
     })),
+    accepts: (catalog) => [
+        ...new Set(catalog.flatMap((entry) => entry.providers)),
+    ],
     defaultFor: (context) => requireOrm(context).providers[0],
     parse: (raw, context) => {
         const orm = requireOrm(context);
@@ -93,6 +93,7 @@ export const PACKAGE_MANAGER_QUESTION = {
     flag: "--package-manager",
     label: "Package manager",
     choices: () => PACKAGE_MANAGERS.map((manager) => ({ value: manager, label: manager })),
+    accepts: () => PACKAGE_MANAGERS,
     defaultFor: (context) => context.detectedPackageManager,
     parse: (raw) => {
         const manager = PACKAGE_MANAGERS.find((candidate) => candidate === raw.trim().toLowerCase());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/cli",
-  "version": "0.1.0-pilot.2",
+  "version": "0.1.0-pilot.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Scaffolds an Aventara server: `aventara new` for a new NestJS project, `aventara init` for an existing one.",
   "type": "module",
@@ -23,7 +23,7 @@
   },
   "scripts": {
     "prebuild": "node scripts/adapter-catalog.generator.ts",
-    "build": "tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
+    "build": "tsc -p tsconfig.json --removeComments --declaration false",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src scripts"