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

package/README.md

@@ -80,18 +80,53 @@ bootstrap error instead of rejecting; pass `abortOnError: false` to `NestFactory
 
 **Nest's testing module works.** `Test.createTestingModule({ imports: [AppModule] }).compile()` builds the providers
 before any HTTP platform exists; the module waits for the one `createNestApplication()` supplies, and still refuses an
-unsupported platform before the application listens (ADR 0011's amendment). A testing module initialized with no
+unsupported platform before the application listens. A testing module initialized with no
 application at all is refused at `init()`, as a platform of `none`.
 
 **Nothing to shut down.** The module owns no resource. Your Prisma provider closes its own client — in its
 `onModuleDestroy`, with `app.enableShutdownHooks()` for signals.
 
+## Calling it by hand
+
+Against the shape `aventara init` writes — the entrypoint `/api`, a Prisma `User` model:
+
+<!-- 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({});`.
+
 ## What runs on a protocol route
 
 The protocol's routes are platform routes, registered from the module's `configure()`, one per
 `protocol.surface()` entry — every advertised operation, `GET <entrypoint>/_contract`, and `POST
 <entrypoint>/_transactions` only when the ClientContract advertises `interactive` — plus the absence handler for the
-rest of `<entrypoint>/_*`. The framework's validation is outermost:
+rest of `<entrypoint>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
+own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `logger: false` silences it like any other):
+
+```text
+[Nest] LOG [AventaraModule] Aventara mounted 10 operations at /api (+ GET /api/_contract, POST /api/_transactions)
+```
+
+The framework's validation is outermost:
 
 | | Express | Fastify |
 |---|---|---|
@@ -128,8 +163,7 @@ protocol; set the entrypoint to where you want it, and point the generated clien
 - **Express routing is case-insensitive** by default, so it also answers the protocol under, say, `/API/_contract`;
   Fastify's is not. That is Express's own `case sensitive routing` setting, off by default, and yours to change.
 - **Express answers `500 A3000`** to a protocol route requested with a percent-encoding a generated client never sends
-  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. A known divergence (register
-  F-843).
+  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. A known divergence.
 - On Express the response carries Express's `X-Powered-By` header; `app.disable("x-powered-by")` removes it.
 
 ## License

package/dist/protocol-host.factory.d.ts

@@ -1,5 +1,6 @@
 import type { Framework } from "@aventara/core";
 import type { AbstractHttpAdapter } from "@nestjs/core";
+import type { SurfaceRoute } from "./protocol-route.table.js";
 /** The protocol, bound once at startup, and the one call that mounts it. */
 export type ProtocolHost = {
     readonly mount: () => void;
@@ -11,6 +12,13 @@ export type ProtocolHost = {
  * routes are mounted later, from the module's `configure()` (Q5).
  */
 export declare function createProtocolHost(adapter: AbstractHttpAdapter | undefined, framework: Framework): ProtocolHost;
+/**
+ * What one mount registered, read off `protocol.surface()`: the operation
+ * count under the entrypoint, then each framework route by method and path —
+ * e.g. `Aventara mounted 5 operations at /api (+ GET /api/_contract, POST
+ * /api/_transactions)`.
+ */
+export declare function mountedLine(routes: readonly SurfaceRoute[], entrypoint: string): string;
 /** What `AventaraModule` holds: a host, perhaps waiting for its platform, and the check that it has one. */
 export type PendingProtocolHost = ProtocolHost & {
     /** Throws when no platform arrived, or the one that did is refused. */

package/dist/protocol-host.factory.js

@@ -1,4 +1,5 @@
 import { AvProtocol } from "@aventara/core/protocol";
+import { Logger } from "@nestjs/common";
 import { createExpressProtocolHost } from "./express-protocol.mounter.js";
 import { createFastifyProtocolHost, } from "./fastify-protocol.mounter.js";
 import { checkedPlatform, } from "./host-bootstrap.validator.js";
@@ -18,7 +19,33 @@ const PLATFORM_MOUNTERS = {
  */
 export function createProtocolHost(adapter, framework) {
     const platform = checkedPlatform(adapter?.getType());
-    return PLATFORM_MOUNTERS[platform](adapter, AvProtocol.bind(framework), framework.entrypoint, framework.contracts.client.limits.maxRequestBytes);
+    const binding = AvProtocol.bind(framework);
+    const host = PLATFORM_MOUNTERS[platform](adapter, binding, framework.entrypoint, framework.contracts.client.limits.maxRequestBytes);
+    return {
+        mount: () => {
+            host.mount();
+            MOUNT_LOGGER.log(mountedLine(binding.surface(), framework.entrypoint));
+        },
+    };
+}
+/**
+ * pilot.1 — the protocol's routes are platform routes, which Nest's
+ * `RouterExplorer` never logs; this is the one line that says they exist.
+ * Through Nest's `Logger`, so the application's logger settings govern it.
+ */
+const MOUNT_LOGGER = new Logger("AventaraModule");
+/**
+ * What one mount registered, read off `protocol.surface()`: the operation
+ * count under the entrypoint, then each framework route by method and path —
+ * e.g. `Aventara mounted 5 operations at /api (+ GET /api/_contract, POST
+ * /api/_transactions)`.
+ */
+export function mountedLine(routes, entrypoint) {
+    const operations = routes.filter((route) => route.kind === "operation");
+    const framework = routes
+        .filter((route) => route.kind !== "operation")
+        .map((route) => `${route.method} ${entrypoint}${route.path}`);
+    return `Aventara mounted ${operations.length} ${operations.length === 1 ? "operation" : "operations"} at ${entrypoint === "" ? "/" : entrypoint} (+ ${framework.join(", ")})`;
 }
 /**
  * N1 (plan B23) — a host for an application whose HTTP adapter may arrive after

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/nest",
-  "version": "0.1.0-pilot.0",
+  "version": "0.1.0-pilot.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "NestJS host integration for Aventara.",
   "type": "module",
@@ -21,7 +21,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.0"
+    "@aventara/core": "0.1.0-pilot.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
@@ -31,8 +31,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/prisma7-adapter": "0.1.0-pilot.0",
-    "@aventara/testing": "0.1.0-pilot.0",
+    "@aventara/prisma7-adapter": "0.1.0-pilot.1",
+    "@aventara/testing": "0.1.0-pilot.1",
     "@nestjs/common": "^12.1.2",
     "@nestjs/core": "^12.1.2",
     "@nestjs/platform-express": "^12.1.2",