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

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.mts` and the generated client — is `@aventara/client`'s (`npx @aventara/client@pilot init`).
 
 ## `aventara new <name>`
 
@@ -58,6 +58,7 @@ 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 |
+| `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 |
 | `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 |
@@ -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/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,40 @@
+/**
+ * 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('/')
+      .expect(200)
+      .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);
+    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/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") {

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

@@ -17,8 +17,11 @@ export type ScaffoldCommand = {
     /** Accepts each unanswered question's default and confirms overwrites (R5). */
     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;

package/dist/command/command.parser.js

@@ -48,21 +48,43 @@ function usageLines(command) {
         .map(([left, right]) => `    ${left.padEnd(width)}  ${right}`)
         .join("\n");
 }
+/** What each command does, in one line: the top-level usage and its own. */
+const SUMMARY = {
+    new: "Create a NestJS project with Aventara (nest new, then init).",
+    init: "Add Aventara to the NestJS 12 project in this directory.",
+};
+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
+or --yes, or the run stops before writing anything.
+`;
+/** `aventara <command> --help` (pilot.1): that command's usage alone. */
+export function commandUsage(command) {
+    return `Usage: ${SYNOPSIS[command]}
+
+${SUMMARY[command]}
+
+Options:
+${usageLines(command)}
+
+${ASKED}`;
+}
 export const USAGE = `aventara — scaffold an Aventara server on NestJS.
 
 Usage:
-  aventara new <name> [options]   Create a NestJS project with Aventara (nest new, then init).
+  ${SYNOPSIS.new}   ${SUMMARY.new}
 ${usageLines("new")}
 
-  aventara init [options]         Add Aventara to the NestJS 12 project in this directory.
+  ${SYNOPSIS.init}         ${SUMMARY.init}
 ${usageLines("init")}
 
   aventara --help                 Print this and exit 0.
+  aventara <command> --help       Print that command's usage and exit 0.
   aventara --version              Print this CLI's version and exit 0.
 
-On a terminal every unanswered question is asked; anywhere else, pass its flag
-or --yes, or the run stops before writing anything.
-`;
+${ASKED}`;
 /** @throws CliCommandError when `argv` is not a command this CLI has. */
 export function parseCliCommand(argv) {
     const [command, ...rest] = argv;
@@ -78,6 +100,9 @@ export function parseCliCommand(argv) {
     if (command !== "new" && command !== "init") {
         throw new CliCommandError(`unknown command ${JSON.stringify(command)}: the commands are new and init; ${HELP}`);
     }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        return { command: "help", topic: command };
+    }
     const questions = QUESTIONS[command];
     const given = {};
     const options = {};

package/dist/plan/project.planner.d.ts

@@ -1,6 +1,6 @@
 import type { CatalogEntry } from "../catalog/catalog-entry.interface.js";
 import { type ProjectInspection } from "../project/project.inspector.js";
-import type { OrmScaffold } from "../templates/template.registry.js";
+import { type OrmScaffold } from "../templates/template.registry.js";
 import type { PackageManager } from "../wizard/wizard.questions.js";
 /**
  * §4.1's `plan`: everything `aventara init` will write, decided before anything
@@ -49,4 +49,11 @@ export type PlanInput = {
     /** Said before the write, beside the planner's own. */
     readonly warnings?: readonly string[];
 };
+/**
+ * pilot.1 — the frontend's first command, as the developer can run it: the
+ * package manager's own one-off runner (`npx` or `pnpm dlx`), and — while this
+ * CLI is a prerelease — its dist-tag, so the client comes from the same release
+ * (`0.1.0-pilot.1` → `@aventara/client@pilot`). A release has no tag to name.
+ */
+export declare function frontendInitCommand(packageManager: PackageManager, cliVersion: string): string;
 export declare function planInit(input: PlanInput): ProjectPlan;

package/dist/plan/project.planner.js

@@ -1,6 +1,8 @@
 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 { APP_MODULE, } from "../project/project.inspector.js";
+import { SCAFFOLD_ENTRYPOINT, } from "../templates/template.registry.js";
 /**
  * §4.1's `plan`: everything `aventara init` will write, decided before anything
  * is written — the files, the anchored `app.module.ts` edit (or the printed
@@ -59,6 +61,17 @@ function writeOf(path, before, after) {
             },
         ];
 }
+/**
+ * pilot.1 — the frontend's first command, as the developer can run it: the
+ * package manager's own one-off runner (`npx` or `pnpm dlx`), and — while this
+ * CLI is a prerelease — its dist-tag, so the client comes from the same release
+ * (`0.1.0-pilot.1` → `@aventara/client@pilot`). A release has no tag to name.
+ */
+export function frontendInitCommand(packageManager, cliVersion) {
+    const tag = /^\d+\.\d+\.\d+-([0-9A-Za-z-]+)/.exec(cliVersion)?.[1];
+    const runner = packageManager === "pnpm" ? "pnpm dlx" : "npx";
+    return `${runner} @aventara/client${tag === undefined ? "" : `@${tag}`} init`;
+}
 export function planInit(input) {
     const { inspection, scaffold, packageManager } = input;
     const conflicts = new Set();
@@ -119,6 +132,16 @@ export function planInit(input) {
     if (edit.kind === "edited") {
         keeping.push(...writeOf(APP_MODULE, appModule, edit.text));
         replacing.push(...writeOf(APP_MODULE, appModule, edit.text));
+        // pilot.1: Nest's own e2e spec also asks for the contract — only when
+        // AventaraModule was wired in, so the test proves what it claims.
+        const spec = input.read(E2E_SPEC);
+        const tested = spec === undefined
+            ? undefined
+            : spliceContractTest(spec, SCAFFOLD_ENTRYPOINT);
+        if (tested !== undefined) {
+            keeping.push(...writeOf(E2E_SPEC, spec, tested));
+            replacing.push(...writeOf(E2E_SPEC, spec, tested));
+        }
     }
     else {
         instructions = wiringInstructions(wiring);
@@ -172,7 +195,7 @@ export function planInit(input) {
                 ]
                 : []),
             `Start the server: ${run} run start:dev`,
-            "In your frontend: npx @aventara/client init",
+            `In your frontend: ${frontendInitCommand(packageManager, input.aventaraVersion)}`,
         ],
     };
 }

package/dist/templates/prisma7/prisma7.templates.d.ts

@@ -1,6 +1,6 @@
 import type { PackageManifest } from "../../apply/manifest.merger.js";
 import type { ClientShape, ExportReference } from "../../project/service.detector.js";
-import type { OrmProjectFacts, OrmScaffold, ReuseInput, ScaffoldInput } from "../template.registry.js";
+import { type OrmProjectFacts, type OrmScaffold, type ReuseInput, type ScaffoldInput } from "../template.registry.js";
 declare function scaffold(input: ScaffoldInput): OrmScaffold;
 declare function reuse(input: ReuseInput): OrmScaffold;
 declare function readProject(directory: string, manifest: PackageManifest): OrmProjectFacts;

package/dist/templates/prisma7/prisma7.templates.js

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { lowestVersionOf } from "../../catalog/range.reader.js";
+import { SCAFFOLD_ENTRYPOINT, } from "../template.registry.js";
 /**
  * The `prisma7` entry's templates (D7): Prisma 7 knowledge as text the CLI
  * writes and reads, keyed by the providers `@aventara/prisma7-adapter`
@@ -141,7 +142,7 @@ function aventaraConfig(input) {
         " */",
         `export async function aventaraConfig(prisma: ${service}) {`,
         "  return {",
-        "    entrypoint: '/api',",
+        `    entrypoint: '${SCAFFOLD_ENTRYPOINT}',`,
         "    adapter: await createPrismaAdapter({",
         input.service.clientMember === undefined
             ? "      client: prisma,"

package/dist/templates/template.registry.d.ts

@@ -28,6 +28,11 @@ export type ProviderTemplate = {
     readonly nativeBuilds: readonly string[];
 };
 export type ModuleKind = "esm" | "cjs";
+/**
+ * The entrypoint every scaffold mounts the protocol at: written into
+ * `src/aventara.config.ts`, and tested by the e2e spec (pilot.1).
+ */
+export declare const SCAFFOLD_ENTRYPOINT = "/api";
 /** What a template set is asked to scaffold. */
 export type ScaffoldInput = {
     readonly entry: CatalogEntry;

package/dist/templates/template.registry.js

@@ -1,4 +1,9 @@
 import { PRISMA7_TEMPLATES } from "./prisma7/prisma7.templates.js";
+/**
+ * The entrypoint every scaffold mounts the protocol at: written into
+ * `src/aventara.config.ts`, and tested by the e2e spec (pilot.1).
+ */
+export const SCAFFOLD_ENTRYPOINT = "/api";
 export const TEMPLATE_REGISTRY = {
     prisma7: PRISMA7_TEMPLATES,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/cli",
-  "version": "0.1.0-pilot.0",
+  "version": "0.1.0-pilot.1",
   "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",