@aventara/cli 1.0.0-rc.8 → 1.0.0-rc.9

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @aventara/cli
 
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- a0bb05e: The agent skill that `aventara new`, `aventara init` and `aventara skill` write has a new section, "Calling the API over
+  HTTP", with a working curl example: the operation path uses the model's name as written in the Prisma schema
+  (`/api/_resources/User/create/one`), every request sends the `Aventara-Protocol-Version: 1` and
+  `Aventara-Contract-Hash` headers (the hash comes from `GET /api/_contract`), and a create's body is `{ "data": … }`. It
+  lists the answers each mistake gets. The printed next steps point to it. To refresh the skill in an existing
+  project, run `aventara skill`.
+- 8c40b81: `aventara new` and `aventara init` now scaffold Next.js apps.
+
+  - `aventara new <name> --host next` runs `create-next-app@latest` (TypeScript, the App Router under `src/`, the `@/*`
+    alias, no install of its own), then the same `init` steps, then the install. create-next-app asks its own questions
+    on your terminal; with `--yes` it takes its defaults. Its own flags go after `--`, as they are:
+    `aventara new my-app --host next --yes -- --tailwind`. `--skip-git` becomes its `--disable-git`. Without a terminal,
+    `--yes` is required. `--host` defaults to `nest`: a NestJS project is scaffolded exactly as before.
+  - `aventara init` tells the host by `package.json`: `@nestjs/core` is NestJS 12, `next` is Next.js 16, and a project
+    that depends on both or neither is refused in one sentence, with nothing written. A Next.js app needs `src/app/`
+    and the `@/*` → `./src/*` path in `tsconfig.json`, and no ORM yet.
+  - In a Next.js app, init writes `src/aventara/config.ts`, `src/aventara/adapter.ts`, `src/aventara/server.ts`
+    (`Aventara()`, exporting `handlers`, `avClient`, `avApp` and `ready`), `src/app/api/[...aventara]/route.ts`,
+    `src/instrumentation.ts` (awaiting `ready()` on the Node.js runtime) and `src/prisma.ts`, with Prisma's schema and
+    config. `aventara:prepare` ends with `aventara-build --client` and runs on `postinstall` and `prebuild`; the files it
+    generates (`src/aventara/generated/`, `src/aventara/client.ts`, `src/aventara/universal.ts`) are added to
+    `.gitignore`. An instrumentation file of your own is never replaced: the lines to add are printed.
+  - Each host package now declares its project layout in its manifest (`"aventara": { "host": … }`). The CLI scaffolds
+    from it and `aventara-build` reads its paths from it, so the two always agree.
+
+- 501b832: `aventara new --host next` and `aventara init` in a Next.js app add `serverExternalPackages: ["@aventara/core",
+  "@aventara/prisma7-adapter"]` to `next.config.ts`, so Node.js loads them once per server process: every route and
+  page shares one core, one Framework and one Prisma client. The line goes into create-next-app's config, or any config
+  whose `const nextConfig = {` object has no `serverExternalPackages`; an app with no config gets a `next.config.ts`. A
+  config that already names `serverExternalPackages`, or is written another way, is never changed, even with `--yes`:
+  the line to add is printed, with a warning. The agent skill's Next.js section says to keep it.
+- The agent skill's Next.js section says what a page that calls `avClient` or `avApp` needs under Cache Components
+  (create-next-app's default): the calling component inside `<Suspense>` (or a `loading.tsx`), `"use cache"` on the
+  function that makes the call, or `export const instant = false`.
+
 ## 1.0.0-rc.8
 
 1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.

package/README.md

@@ -1,11 +1,12 @@
 # `@aventara/cli`
 
-The `aventara` command: it scaffolds an Aventara server on NestJS 12.
+The `aventara` command: it scaffolds an Aventara server on NestJS 12 or Next.js 16.
 
 ```bash
 npm i -g @aventara/cli@rc  # or run it once: npx @aventara/cli@rc <command>
 aventara new my-api           # a new NestJS project with Aventara
-aventara init                 # Aventara added to the NestJS 12 project in this directory
+aventara new my-app --host next   # a new Next.js app with Aventara (create-next-app, then init)
+aventara init                 # Aventara added to the NestJS 12 or Next.js 16 project in this directory
 aventara skill                # refresh the agent skill for the installed @aventara/core
 ```
 
@@ -23,9 +24,22 @@ without `.env` (it is in `.gitignore`). No commit is made, and one line says why
 `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 new <name> --host next`
+
+Runs `create-next-app@latest <name> --ts --app --src-dir --import-alias "@/*" --use-<npm|pnpm> --skip-install`, then
+`aventara init`'s pipeline over the new app, then the install. create-next-app asks its own questions on your terminal;
+with `--yes` it takes its defaults instead (and is given `--yes` too), which is also what a run with no terminal needs.
+Its own flags go after `--`, as they are: `aventara new my-app --host next --yes -- --tailwind --eslint`. `--skip-git`
+becomes its `--disable-git`. `--host` defaults to `nest`.
+
 ## `aventara init`
 
-Runs inside an existing NestJS 12 project. It refuses a directory with no `package.json`, another Nest major,
+Runs inside an existing NestJS 12 or Next.js 16 project, telling them apart by `package.json`: `@nestjs/core` is
+NestJS, `next` is Next.js, and a project depending on both or neither is refused in one sentence. A Next.js app must use
+the App Router under `src/app/` and map `@/*` to `./src/*` in `tsconfig.json` (as create-next-app writes it), and have
+no ORM yet. The rest of this section is NestJS's; a Next.js app gets [its own files](#what-it-writes-in-a-nextjs-app).
+
+In a NestJS project, it refuses another Nest major,
 TypeScript 7, a yarn-only lockfile, or a project already initialized.
 
 In a project with no ORM yet, the ORM and the database are asked (or taken from the flags), and everything below is
@@ -46,6 +60,7 @@ possible answer is shown, not asked.
 | Flag | Question | Default |
 |---|---|---|
 | `<name>` (`new` only) | The project directory. | required |
+| `--host <nest\|next>` (`new` only) | The framework to build on; `init` reads it from `package.json`. Not asked. | `nest` |
 | `--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 package manager. | the lockfile's, else the one that launched the CLI, else npm |
@@ -55,6 +70,7 @@ possible answer is shown, not asked.
 | `--skip-git` (`new`) | Passed to `nest new`. | |
 | `-y`, `--yes` | Accept every unanswered default, and replace existing content that differs. | |
 | `--verbose` | Show the output of `nest new` and the install as they run. | |
+| `-- <args>` (`new --host next`) | Passed to create-next-app as they are, after its own. | |
 
 While it works, each step is shown on stderr, such as `[3/4] Installing dependencies (npm install)`. On a terminal it
 has a spinner and the seconds so far; in a pipe, in CI (`CI`) or with `NO_COLOR` it is one plain line per step
@@ -81,6 +97,28 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 | `.claude/skills/aventara/` (`SKILL.md`, `reference/*.md`, `.aventara-skill.json`): the agent skill your AI coding agent reads | Aventara's: `aventara skill` refreshes it, and keeps a file you changed unless `--force` |
 | `AGENTS.md`: an Aventara section between `<!-- aventara:start -->` and `<!-- aventara:end -->`, appended to an existing file | you, except the marked section |
 
+### What it writes in a Next.js app
+
+Everything Aventara is in one folder, `src/aventara/`, at the paths `@aventara/next` declares and `aventara-build`
+reads.
+
+| Path | Owner afterwards |
+|---|---|
+| `prisma/schema.prisma`, `prisma.config.ts` | you (as in a NestJS project) |
+| `src/prisma.ts`: `prisma()`, the app's one Prisma client with the driver adapter, made on first use and kept across `next dev` reloads | you |
+| `src/aventara/config.ts`: `aventaraConfig`, as in a NestJS project, logging through `console.error` | you |
+| `src/aventara/adapter.ts`: the adapter's description | you |
+| `src/aventara/server.ts`: `Aventara({ ...aventaraConfig, adapter, prebuilt, state })` exporting `handlers`, `avClient`, `avApp` and `ready`; `@/aventara/server` | you |
+| `src/app/api/[...aventara]/route.ts`: every method of `handlers` | you |
+| `src/instrumentation.ts`: awaits `ready()` on the Node.js runtime, so a bad configuration stops `next start`. An instrumentation file of yours is never replaced, even with `--yes`: the lines to add are printed | you |
+| `next.config.ts`: `serverExternalPackages: ["@aventara/core", "@aventara/prisma7-adapter"]` added to its configuration object, so Node.js loads them once per server process (one core and one Prisma client for every route and page). Added to create-next-app's config, or to any whose `const nextConfig = {` object has no `serverExternalPackages`; written as a new `next.config.ts` when the app has none. A config that already names `serverExternalPackages`, or is written another way, is never changed, even with `--yes`: the line to add is printed | you |
+| `package.json`: `@aventara/core`, `@aventara/next`, the adapter and `@aventara/build` at this CLI's version, `server-only`, Prisma at `7.10.0`; `aventara:prepare` (ending in `aventara-build --client`), run by `postinstall` and `prebuild` | you |
+| `.env` (`DATABASE_URL`), `.gitignore` (`/src/generated/`, `/dev.db*`, `/src/aventara/generated/`, `/src/aventara/client.ts`, `/src/aventara/universal.ts`, `.env`) | you |
+| `src/aventara/client.ts`, `src/aventara/universal.ts`, `src/aventara/generated/` | generated by `aventara:prepare`; never edit |
+
+No CORS (the browser calls the same origin), no Pages Router, no proxy, and no MCP route: an `mcp` endpoint you add on
+Next.js needs `authorization`. Next steps: `npx prisma db push`, then `npm run dev`.
+
 ### Next steps it prints
 
 ```bash

package/dist/catalog/host-entry.interface.js

@@ -0,0 +1,10 @@
+import { HOST_CATALOG } from "./host.catalog.generated.js";
+import { lowestMajorOf } from "./range.reader.js";
+export const HOSTS = HOST_CATALOG;
+export const DEFAULT_HOST = "nest";
+export function hostOf(alias) {
+    return HOST_CATALOG.find((entry) => entry.alias === alias);
+}
+export function frameworkMajorOf(host) {
+    return lowestMajorOf(host.framework.range);
+}

package/dist/catalog/host.catalog.generated.js

@@ -0,0 +1,32 @@
+export const HOST_CATALOG = [
+    {
+        "alias": "nest",
+        "label": "NestJS",
+        "package": "@aventara/nest",
+        "framework": {
+            "package": "@nestjs/core",
+            "range": "^12.0.0"
+        },
+        "layout": {
+            "config": "src/aventara.config",
+            "adapter": "src/aventara.adapter",
+            "generated": "src/generated/aventara"
+        }
+    },
+    {
+        "alias": "next",
+        "label": "Next.js",
+        "package": "@aventara/next",
+        "framework": {
+            "package": "next",
+            "range": ">=16.4 <17"
+        },
+        "layout": {
+            "config": "src/aventara/config",
+            "adapter": "src/aventara/adapter",
+            "generated": "src/aventara/generated",
+            "client": "src/aventara/client.ts",
+            "universal": "src/aventara/universal.ts"
+        }
+    }
+];

package/dist/command/command.parser.js

@@ -1,3 +1,4 @@
+import { DEFAULT_HOST, HOSTS } from "../catalog/host-entry.interface.js";
 import { INIT_FLAG_QUESTIONS, NEW_QUESTIONS, ormAliasesSentence, } from "../wizard/wizard.questions.js";
 export class AvCliCommandError extends Error {
     name = "AvCliCommandError";
@@ -34,6 +35,23 @@ const QUESTIONS = {
     init: INIT_FLAG_QUESTIONS,
 };
 const HELP = "run `aventara --help` for usage";
+const HOST_FLAG = "--host";
+export function hostAliasesSentence() {
+    const hosts = HOSTS.map((host) => `${host.alias} (${host.label}, ${host.package})`);
+    return `--host takes ${hosts.length <= 1
+        ? hosts.join("")
+        : `${hosts.slice(0, -1).join(", ")} or ${hosts[hosts.length - 1]}`}`;
+}
+const NEW_ONLY_ROWS = [
+    [
+        `${HOST_FLAG} <${HOSTS.map((host) => host.alias).join("|")}>`,
+        `the framework to build on; ${DEFAULT_HOST} when omitted`,
+    ],
+    [
+        "-- <args>",
+        "passed as they are to the project generator (create-next-app, with --host next)",
+    ],
+];
 function flagUsage(question, catalog) {
     const accepted = question.accepts?.(catalog);
     return `${question.flag} ${accepted === undefined
@@ -52,6 +70,7 @@ function usageLines(command, catalog) {
             `${option.alias === undefined ? "" : `${option.alias}, `}${option.flag}`,
             option.summary,
         ]),
+        ...(command === "new" ? NEW_ONLY_ROWS : []),
     ];
     const width = Math.max(...rows.map(([left]) => left.length));
     return rows
@@ -59,8 +78,8 @@ function usageLines(command, catalog) {
         .join("\n");
 }
 const SUMMARY = {
-    new: "Create a NestJS project with Aventara (nest new, then init).",
-    init: "Add Aventara to the NestJS 12 project in this directory.",
+    new: "Create a project with Aventara (nest new or create-next-app, then init).",
+    init: `Add Aventara to the ${HOSTS.map((host) => host.label).join(" or ")} project in this directory.`,
 };
 const SYNOPSIS = {
     new: "aventara new <name> [options]",
@@ -94,7 +113,7 @@ ${usageLines(command, catalog)}
 ${asked(catalog)}`;
 }
 export function usage(catalog) {
-    return `aventara — scaffold an Aventara server on NestJS.
+    return `aventara — scaffold an Aventara server on ${HOSTS.map((host) => host.label).join(" or ")}.
 
 Usage:
   ${SYNOPSIS.new}   ${SUMMARY.new}
@@ -134,10 +153,19 @@ export function parseCliCommand(argv) {
     const questions = QUESTIONS[command];
     const given = {};
     const options = {};
+    let host;
+    let passthrough;
     const seen = new Set();
     const positional = questions.find((question) => !question.flag.startsWith("--"));
     for (let index = 0; index < rest.length; index += 1) {
         const argument = rest[index];
+        if (argument === "--") {
+            if (command !== "new") {
+                throw new AvCliCommandError(`aventara ${command} passes nothing on: arguments after -- go to aventara new's project generator; ${HELP}`);
+            }
+            passthrough = rest.slice(index + 1);
+            break;
+        }
         if (!argument.startsWith("-")) {
             if (positional === undefined || given[positional.id] !== undefined) {
                 throw new AvCliCommandError(`unexpected argument ${JSON.stringify(argument)}: aventara ${command} takes ${positional === undefined ? "no" : "one"} positional argument; ${HELP}`);
@@ -148,6 +176,28 @@ export function parseCliCommand(argv) {
         const equals = argument.indexOf("=");
         const flag = equals === -1 ? argument : argument.slice(0, equals);
         const inline = equals === -1 ? undefined : argument.slice(equals + 1);
+        if (flag === HOST_FLAG) {
+            if (command !== "new") {
+                throw new AvCliCommandError(`${HOST_FLAG} is a flag of aventara new, not aventara ${command}: init reads the host from package.json; ${HELP}`);
+            }
+            if (host !== undefined) {
+                throw new AvCliCommandError(`${HOST_FLAG} was given twice; ${HELP}`);
+            }
+            const value = inline ?? rest[index + 1];
+            if (value === undefined ||
+                (inline === undefined && value.startsWith("-"))) {
+                throw new AvCliCommandError(`${HOST_FLAG} takes a value; ${HELP}`);
+            }
+            if (inline === undefined) {
+                index += 1;
+            }
+            const alias = value.trim().toLowerCase();
+            if (!HOSTS.some((candidate) => candidate.alias === alias)) {
+                throw new AvCliCommandError(`there is no Aventara host for ${JSON.stringify(value)}; ${hostAliasesSentence()}; ${HELP}`);
+            }
+            host = alias;
+            continue;
+        }
         const question = questions.find((candidate) => candidate.flag === flag);
         const option = OPTIONS.find((candidate) => candidate.flag === flag || candidate.alias === flag);
         const canonical = question?.flag ?? option?.flag ?? flag;
@@ -188,6 +238,8 @@ export function parseCliCommand(argv) {
         skipGit: options.skipGit === true,
         yes: options.yes === true,
         ...(options.verbose === true ? { verbose: true } : {}),
+        ...(host === undefined ? {} : { host }),
+        ...(passthrough === undefined ? {} : { passthrough }),
     };
 }
 function parseSkillCommand(rest) {

package/dist/plan/host-plan.interface.js

@@ -0,0 +1 @@
+export const PREPARE_SCRIPT = "aventara:prepare";

package/dist/plan/nest-host.planner.js

@@ -0,0 +1,131 @@
+import { spliceAppModule, wiringInstructions, } from "../apply/app-module.anchor.js";
+import { E2E_SPEC, spliceContractTest } from "../apply/e2e-spec.anchor.js";
+import { CORS_ORIGINS_VARIABLE, MAIN_FILE, mainCorsInstructions, SCAFFOLD_CORS_ORIGINS, spliceMainCors, } from "../apply/main-cors.anchor.js";
+import { hostOf } from "../catalog/host-entry.interface.js";
+import { APP_MODULE, } from "../project/project.inspector.js";
+import { SCAFFOLD_API, } from "../templates/template.registry.js";
+import { PREPARE_SCRIPT, } from "./host-plan.interface.js";
+const PREPARED_SCRIPTS = [
+    "build",
+    "start",
+    "start:dev",
+    "start:debug",
+];
+const START_SCRIPTS = {
+    start: { from: "nest start", to: "nest start --env-file .env" },
+    "start:dev": {
+        from: "nest start --watch",
+        to: "nest start --watch --env-file .env",
+    },
+    "start:debug": {
+        from: "nest start --debug --watch",
+        to: "nest start --debug --watch --env-file .env",
+    },
+    "start:prod": {
+        from: "node dist/main",
+        to: "node --env-file-if-exists=.env dist/main",
+    },
+};
+const E2E_SCRIPTS = {
+    esm: {
+        from: "vitest run --config ./vitest.config.e2e.ts",
+        to: "node --env-file-if-exists=.env ./node_modules/vitest/vitest.mjs run --config ./vitest.config.e2e.ts",
+    },
+    cjs: {
+        from: "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config ./test/jest-e2e.json",
+        to: "node --env-file-if-exists=.env --experimental-vm-modules ./node_modules/jest/bin/jest.js --config ./test/jest-e2e.json",
+    },
+};
+const NEST = hostOf("nest");
+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 planNestHost(builder, input) {
+    const { inspection, scaffold, packageManager } = input;
+    const wiring = {
+        imports: [
+            `import { AventaraModule } from '${NEST.package}';`,
+            ...scaffold.appModule.imports,
+        ],
+        entries: scaffold.appModule.entries,
+    };
+    const appModule = builder.read(APP_MODULE);
+    const edit = input.wiringByHand !== undefined
+        ? { kind: "not-anchored", reason: input.wiringByHand }
+        : appModule === undefined
+            ? {
+                kind: "not-anchored",
+                reason: `there is no ${APP_MODULE}`,
+            }
+            : spliceAppModule(appModule, wiring);
+    if (edit.kind === "edited") {
+        builder.write(APP_MODULE, appModule, edit.text);
+        const spec = builder.read(E2E_SPEC);
+        const tested = spec === undefined ? undefined : spliceContractTest(spec, SCAFFOLD_API);
+        if (tested !== undefined) {
+            builder.write(E2E_SPEC, spec, tested);
+        }
+    }
+    else {
+        builder.instruct(wiringInstructions(wiring));
+        builder.warn(`${APP_MODULE} was not edited: ${edit.reason}; add AventaraModule by hand, as printed below`);
+    }
+    const main = builder.read(MAIN_FILE);
+    const cors = main === undefined
+        ? { kind: "not-anchored", reason: `there is no ${MAIN_FILE}` }
+        : spliceMainCors(main);
+    if (cors.kind === "edited") {
+        builder.write(MAIN_FILE, main, cors.text);
+    }
+    else if (cors.kind === "configured") {
+        builder.warn(`${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") {
+        builder.instruct(mainCorsInstructions());
+        builder.warn(`${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 = builder.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 run = packageManager === "pnpm" ? "pnpm" : "npm";
+    return {
+        dependencies: { [NEST.package]: input.aventaraVersion },
+        build: "aventara-build",
+        scripts: Object.fromEntries(PREPARED_SCRIPTS.map((script) => [
+            `pre${script}`,
+            `${packageManager} run ${PREPARE_SCRIPT}`,
+        ])),
+        rewrites: inspection.usesNestConfig
+            ? {}
+            : {
+                ...START_SCRIPTS,
+                "test:e2e": E2E_SCRIPTS[inspection.moduleKind],
+            },
+        ...(corsWanted
+            ? {
+                envEntry: {
+                    key: CORS_ORIGINS_VARIABLE,
+                    value: SCAFFOLD_CORS_ORIGINS,
+                },
+            }
+            : {}),
+        gitignore: [],
+        nextSteps: [
+            ...(inspection.usesNestConfig
+                ? [
+                    "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/plan/next-host.planner.js

@@ -0,0 +1,133 @@
+import { hostOf } from "../catalog/host-entry.interface.js";
+import { SERVER_IMPORT } from "../templates/next-server.entry.js";
+import { SCAFFOLD_API } from "../templates/template.registry.js";
+import { PREPARE_SCRIPT, } from "./host-plan.interface.js";
+const NEXT = hostOf("next");
+export const ROUTE_FILE = `src/app${SCAFFOLD_API}/[...aventara]/route.ts`;
+export const INSTRUMENTATION_FILE = "src/instrumentation.ts";
+const INSTRUMENTATION_FILES = [INSTRUMENTATION_FILE, "src/instrumentation.js"];
+const SERVER_ONLY = { "server-only": "0.0.1" };
+function routeFile() {
+    return [
+        `import { handlers } from "${SERVER_IMPORT}";`,
+        "",
+        "// Aventara's API under the configuration's `api` path. Every method is exported,",
+        "// so one an operation does not take is answered by Aventara (405 with Allow).",
+        "export const { GET, POST, PUT, PATCH, DELETE } = handlers;",
+        "",
+    ].join("\n");
+}
+const REGISTER_BODY = [
+    '  if (process.env.NEXT_RUNTIME === "nodejs") {',
+    `    const { ready } = await import("${SERVER_IMPORT}");`,
+    "    await ready();",
+    "  }",
+];
+function instrumentationFile() {
+    return [
+        "/**",
+        " * Next.js calls register() once, when the server starts. On the Node.js runtime",
+        " * it builds Aventara's framework, so a bad configuration stops `next start` and",
+        " * the first request finds it ready.",
+        " */",
+        "export async function register() {",
+        ...REGISTER_BODY,
+        "}",
+        "",
+    ].join("\n");
+}
+const NEXT_CONFIG_FILES = [
+    "next.config.ts",
+    "next.config.mts",
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.cjs",
+];
+const CONFIG_OPENING = /^const nextConfig(?:: NextConfig)? = \{\n/m;
+function externalLines(packages, indent) {
+    return [
+        `${indent}// Loaded by Node.js once per server process, not bundled into each layer:`,
+        `${indent}// one Aventara core and one Prisma client, shared by every route and page.`,
+        `${indent}serverExternalPackages: [${packages.map((name) => JSON.stringify(name)).join(", ")}],`,
+    ];
+}
+function newNextConfig(packages) {
+    return [
+        'import type { NextConfig } from "next";',
+        "",
+        "const nextConfig: NextConfig = {",
+        ...externalLines(packages, "  "),
+        "};",
+        "",
+        "export default nextConfig;",
+        "",
+    ].join("\n");
+}
+export function withServerExternals(text, packages) {
+    if (text.includes("serverExternalPackages")) {
+        return packages.every((name) => text.includes(JSON.stringify(name)))
+            ? text
+            : undefined;
+    }
+    const opening = CONFIG_OPENING.exec(text);
+    if (opening === null) {
+        return undefined;
+    }
+    const at = opening.index + opening[0].length;
+    const indent = /^[ \t]+/.exec(text.slice(at))?.[0] ?? "  ";
+    return `${text.slice(0, at)}${externalLines(packages, indent).join("\n")}\n${text.slice(at)}`;
+}
+export function planNextHost(builder, input) {
+    builder.file(ROUTE_FILE, routeFile());
+    const existing = INSTRUMENTATION_FILES.find((file) => builder.read(file) !== undefined);
+    const wanted = instrumentationFile();
+    if (existing === undefined) {
+        builder.file(INSTRUMENTATION_FILE, wanted);
+    }
+    else if (builder.read(existing) !== wanted) {
+        builder.instruct([
+            `Add Aventara's startup to register() in ${existing}:`,
+            "",
+            ...REGISTER_BODY,
+            "",
+        ].join("\n"));
+        builder.warn(`${existing} is yours, so it was left as it is; add the lines printed below to its register()`);
+    }
+    const configFile = NEXT_CONFIG_FILES.find((file) => builder.read(file) !== undefined);
+    if (configFile === undefined) {
+        builder.file(NEXT_CONFIG_FILES[0], newNextConfig(input.externalPackages));
+    }
+    else {
+        const before = builder.read(configFile);
+        const after = withServerExternals(before, input.externalPackages);
+        if (after === undefined) {
+            builder.instruct([
+                `Add Aventara's server packages to the configuration object in ${configFile} (merge them into serverExternalPackages if it has one):`,
+                "",
+                ...externalLines(input.externalPackages, "  "),
+                "",
+            ].join("\n"));
+            builder.warn(`${configFile} is yours, so it was left as it is; add the serverExternalPackages line printed below to it`);
+        }
+        else {
+            builder.write(configFile, before, after);
+        }
+    }
+    const { layout } = NEXT;
+    const run = input.packageManager === "pnpm" ? "pnpm" : "npm";
+    return {
+        dependencies: {
+            [NEXT.package]: input.aventaraVersion,
+            ...SERVER_ONLY,
+        },
+        build: "aventara-build --client",
+        scripts: { prebuild: `${input.packageManager} run ${PREPARE_SCRIPT}` },
+        rewrites: {},
+        gitignore: [
+            `/${layout.generated}/`,
+            ...(layout.client === undefined ? [] : [`/${layout.client}`]),
+            ...(layout.universal === undefined ? [] : [`/${layout.universal}`]),
+        ],
+        nextSteps: [`Start the app: ${run} run dev`],
+    };
+}