@aventara/cli 1.0.0-rc.0 → 1.0.0-rc.10

package/README.md

@@ -1,15 +1,17 @@
 # `@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
 ```
 
-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@rc init`).
+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) belongs to `@aventara/client` (`npx @aventara/client@rc init`).
 
 ## `aventara new <name>`
 
@@ -17,22 +19,37 @@ 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
+Once installed, the project gets its first git commit, `Initial Aventara Scaffold`, with the lockfile in it and
+without `.env` (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 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 (refused: no `package.json`, another Nest major, TypeScript 7, a yarn-only
-lockfile, a project already initialized).
+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
+written.
 
-- **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 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.
+In a project that already uses Prisma, the installed Prisma must be one an Aventara adapter supports, or the run is
+refused in one sentence with nothing written. Today that is Prisma 7 (`^7.10.1`) on SQLite or PostgreSQL, with a driver
+adapter and the `prisma-client` generator. 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
 
@@ -42,20 +59,22 @@ possible answer is shown, not asked.
 
 | Flag | Question | Default |
 |---|---|---|
-| `<name>` (`new` only) | The project directory. | — (required) |
+| `<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 lockfile's, else the one that launched the CLI, else npm |
+| `--package-manager <npm\|pnpm>` | The package manager. | 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` |
 | `--prisma-module <path#Export>` (`init`) | The Nest module that provides and exports it. | the one found |
 | `--skip-install` | Write the files; print the install instead of running it. | |
 | `--skip-git` (`new`) | Passed to `nest new`. | |
-| `-y`, `--yes` | Accept every unanswered default **and** replace existing content that differs. | |
+| `-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 — `[3/4] Installing dependencies (npm install)` — with a spinner and the
-seconds so far on a terminal, or as one plain line per step (`… done (12.4s)`) in a pipe, in CI (`CI`) or with
-`NO_COLOR`; the output of `nest new` and the install is shown only if it fails, or with `--verbose`.
+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
+(`… done (12.4s)`). The output of `nest new` and the install is shown only if it fails, or with `--verbose`.
 
 Existing content that differs from what would be written (a `.env` key, a script, a file) is listed, and replaced only
 when you confirm, or with `--yes`; where nobody can be asked, the run stops and touches nothing.
@@ -64,17 +83,41 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 
 | Path | Owner afterwards |
 |---|---|
-| `prisma/schema.prisma` — `prisma-client` generating into `src/generated/prisma`, a `User` model | you |
-| `prisma.config.ts` — loads `.env` itself (Prisma does not) | you |
-| `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 |
-| `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 |
+| `prisma/schema.prisma`: `prisma-client` generating into `src/generated/prisma`, a `User` model | you |
+| `prisma.config.ts`: loads `.env` itself (Prisma does not) | you |
+| `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 `api` mount path (`/api`), a `diagnostics` sink that logs the raw error of a server failure, with its stack, through Nest's `Logger`, and the `exposed`/`exemptions`, `pipelines` and `resources` you add | you |
+| `src/app.module.ts`: one edit that adds the imports, `PrismaModule` and `AventaraModule.forRootAsync({ … })`; printed instead when the file is not the shape expected | you |
+| `test/app.e2e-spec.ts`: one edit that adds a `GET /api/_contract` → 200 test after Nest's `GET /` test; left alone when the file is not Nest's | 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, build and start, so a schema change needs only a restart); never edit |
+| `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, build and start, so a schema change needs only a restart); never edit |
+| `.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
 
@@ -111,23 +154,37 @@ curl -s -X POST http://localhost:3000/api/_resources/User/find/many \
 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({});`.
+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, so type it `readonly User[]`:
+`const users: readonly User[] = await avClient.User.find.many({});`.
+
+## `aventara skill`
+
+Writes the agent skill for the `@aventara/core` installed in the project in this directory: its version, and its
+`ERRORS.md` as `reference/errors.md`. It reads those files and runs none of the project's packages. A skill file it
+wrote before is replaced; one you changed is kept, with a warning, unless you pass `--force`. In `AGENTS.md` only the
+text between the Aventara markers is replaced (or the section appended), and `CLAUDE.md` is never written. Run it with
+the CLI at your `@aventara/core` version: `npx @aventara/cli@<version> skill`.
 
 ## Supported
 
-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
-**generated** from the Aventara adapter packages that exist (`src/catalog/adapter.catalog.generated.ts`), never listed
-by hand: a future
-`@aventara/prisma8-adapter` appears by existing.
+- NestJS 12.
+- Node `^22.23.4 || >=24.22.1`. On any other Node the bin refuses in one sentence naming that range. On Node 22 use
+  npm ≥ 11, because Node 22's bundled npm 10 cannot install Nest 12's own scaffold. A CommonJS project's jest e2e needs
+  Node ≥ 24.9, which is Nest's and Jest's limit.
+- npm and pnpm. Yarn is not supported.
+- ESM and CommonJS projects.
+- Prisma 7 (`^7.10.1`) 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, so a future `@aventara/prisma8-adapter` appears
+once it exists.
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/apply/conflict.confirmer.js

@@ -1,7 +1,7 @@
-export class ConflictsNotConfirmedError extends Error {
-    name = "ConflictsNotConfirmedError";
+export class AvConflictsNotConfirmedError extends Error {
+    name = "AvConflictsNotConfirmedError";
 }
-export function conflictWarning(conflicts) {
+function conflictWarning(conflicts) {
     return `${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content, and initializing will replace ${conflicts.length === 1 ? "it" : "them"}`;
 }
 export async function confirmConflicts(conflicts, consent) {
@@ -10,7 +10,7 @@ export async function confirmConflicts(conflicts, consent) {
     }
     const them = conflicts.length === 1 ? "it" : "them";
     if (!consent.prompter.interactive) {
-        throw new ConflictsNotConfirmedError(`not initializing, and nothing was touched: ${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content and nobody can be asked (stdin is not a terminal); run \`aventara init --yes\` to replace ${them}`);
+        throw new AvConflictsNotConfirmedError(`not initializing, and nothing was touched: ${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content and nobody can be asked (stdin is not a terminal); run \`aventara init --yes\` to replace ${them}`);
     }
     consent.prompter.say(`aventara: warning: ${conflictWarning(conflicts)}.`);
     const answer = await consent.prompter.ask({
@@ -19,6 +19,6 @@ export async function confirmConflicts(conflicts, consent) {
         defaultValue: "N",
     });
     if (!/^y(?:es)?$/i.test(answer.trim())) {
-        throw new ConflictsNotConfirmedError(`cancelled, and nothing was touched; run again and answer yes to replace ${them}`);
+        throw new AvConflictsNotConfirmedError(`cancelled, and nothing was touched; run again and answer yes to replace ${them}`);
     }
 }

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

@@ -9,7 +9,7 @@ export const ADAPTER_CATALOG = [
             "package": "@prisma/client",
             "major": 7
         },
-        "range": "^7.10.0",
+        "range": "^7.10.1",
         "familyPackages": [
             "prisma",
             "@prisma/client",

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

@@ -1,23 +1,25 @@
 import { readFileSync } from "node:fs";
-import { ConflictsNotConfirmedError } from "./apply/conflict.confirmer.js";
+import { AvConflictsNotConfirmedError } 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 { ProjectRefusedError } from "./project/project.inspector.js";
+import { AvCliCommandError, commandUsage, parseCliCommand, usage, } from "./command/command.parser.js";
+import { AvProjectRefusedError } from "./project/project.inspector.js";
 import { runCommand } from "./run/command.runner.js";
-import { InstallFailedError, runInit } from "./run/init.orchestrator.js";
+import { AvInstallFailedError, runInit } from "./run/init.orchestrator.js";
 import { runNew } from "./run/new.orchestrator.js";
+import { AvSkillRefusedError, runSkill } from "./run/skill.orchestrator.js";
 import { progressModeOf } from "./run/step.reporter.js";
-import { UnansweredQuestionsError, } from "./wizard/answer.resolver.js";
-import { createReadlinePrompter, WizardCancelledError, } from "./wizard/readline.prompter.js";
-import { WizardAnswerError } from "./wizard/wizard.questions.js";
+import { AvUnansweredQuestionsError, } from "./wizard/answer.resolver.js";
+import { AvWizardCancelledError, createReadlinePrompter, } from "./wizard/readline.prompter.js";
+import { AvWizardAnswerError } from "./wizard/wizard.questions.js";
 const REFUSALS = [
-    CliCommandError,
-    WizardAnswerError,
-    UnansweredQuestionsError,
-    WizardCancelledError,
-    ProjectRefusedError,
-    ConflictsNotConfirmedError,
-    InstallFailedError,
+    AvCliCommandError,
+    AvWizardAnswerError,
+    AvUnansweredQuestionsError,
+    AvWizardCancelledError,
+    AvProjectRefusedError,
+    AvConflictsNotConfirmedError,
+    AvInstallFailedError,
+    AvSkillRefusedError,
 ];
 const MANIFEST = new URL("../package.json", import.meta.url);
 function ownVersion() {
@@ -38,6 +40,14 @@ export async function runCli(argv, io) {
             io.stdout(`${ownVersion()}\n`);
             return 0;
         }
+        if (command.command === "skill") {
+            return runSkill(command, {
+                directory: io.cwd,
+                stdout: io.stdout,
+                stderr: io.stderr,
+                cliVersion: ownVersion(),
+            });
+        }
         if (command.command === "init") {
             return await runInit(command, {
                 directory: io.cwd,
@@ -65,10 +75,13 @@ export async function runCli(argv, io) {
     }
     catch (error) {
         if (REFUSALS.some((refusal) => error instanceof refusal)) {
-            io.stderr(`aventara: ${error.message}.\n`);
+            const { message } = error;
+            io.stderr(message.includes("\n")
+                ? `aventara: ${message.trimEnd()}\n`
+                : `aventara: ${message}.\n`);
             return 1;
         }
-        io.stderr(`${String(error instanceof Error ? error.stack : error)}\n`);
+        io.stderr(`${(error instanceof Error && error.stack) || String(error)}\n`);
         return 1;
     }
 }

package/dist/command/command.parser.js

@@ -1,6 +1,7 @@
+import { DEFAULT_HOST, HOSTS } from "../catalog/host-entry.interface.js";
 import { INIT_FLAG_QUESTIONS, NEW_QUESTIONS, ormAliasesSentence, } from "../wizard/wizard.questions.js";
-export class CliCommandError extends Error {
-    name = "CliCommandError";
+export class AvCliCommandError extends Error {
+    name = "AvCliCommandError";
 }
 const OPTIONS = [
     {
@@ -34,6 +35,23 @@ const QUESTIONS = {
     init: INIT_FLAG_QUESTIONS,
 };
 const HELP = "run `aventara --help` for usage";
+const HOST_FLAG = "--host";
+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]",
@@ -72,7 +91,18 @@ On a terminal every unanswered question is asked; anywhere else, pass its flag
 or --yes, or the run stops before writing anything.
 `;
 }
+const SKILL_SUMMARY = "Write or refresh the agent skill (.claude/skills/aventara/) and the Aventara section of AGENTS.md, for the installed @aventara/core.";
+const SKILL_USAGE = `Usage: aventara skill [options]
+
+${SKILL_SUMMARY}
+
+Options:
+    --force  also replace skill files you changed (AGENTS.md outside the Aventara section is never touched)
+`;
 export function commandUsage(command, catalog) {
+    if (command === "skill") {
+        return SKILL_USAGE;
+    }
     return `Usage: ${SYNOPSIS[command]}
 
 ${SUMMARY[command]}
@@ -83,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}
@@ -92,6 +122,8 @@ ${usageLines("new", catalog)}
   ${SYNOPSIS.init}         ${SUMMARY.init}
 ${usageLines("init", catalog)}
 
+  aventara skill [--force]       ${SKILL_SUMMARY}
+
   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.
@@ -101,7 +133,7 @@ ${asked(catalog)}`;
 export function parseCliCommand(argv) {
     const [command, ...rest] = argv;
     if (command === undefined) {
-        throw new CliCommandError(`a command is required: new or init; ${HELP}`);
+        throw new AvCliCommandError(`a command is required: new, init or skill; ${HELP}`);
     }
     if (command === "--help" || command === "-h") {
         return { command: "help" };
@@ -109,8 +141,11 @@ export function parseCliCommand(argv) {
     if (command === "--version" || command === "-v") {
         return { command: "version" };
     }
+    if (command === "skill") {
+        return parseSkillCommand(rest);
+    }
     if (command !== "new" && command !== "init") {
-        throw new CliCommandError(`unknown command ${JSON.stringify(command)}: the commands are new and init; ${HELP}`);
+        throw new AvCliCommandError(`unknown command ${JSON.stringify(command)}: the commands are new, init and skill; ${HELP}`);
     }
     if (rest.includes("--help") || rest.includes("-h")) {
         return { command: "help", topic: command };
@@ -118,13 +153,22 @@ 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 CliCommandError(`unexpected argument ${JSON.stringify(argument)}: aventara ${command} takes ${positional === undefined ? "no" : "one"} positional argument; ${HELP}`);
+                throw new AvCliCommandError(`unexpected argument ${JSON.stringify(argument)}: aventara ${command} takes ${positional === undefined ? "no" : "one"} positional argument; ${HELP}`);
             }
             given[positional.id] = argument;
             continue;
@@ -132,25 +176,47 @@ 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;
         if (question === undefined && option === undefined) {
             const elsewhere = ["new", "init"].filter((other) => QUESTIONS[other].some((candidate) => candidate.flag === flag));
-            throw new CliCommandError(elsewhere.length === 0
+            throw new AvCliCommandError(elsewhere.length === 0
                 ? `unknown flag ${flag}; ${HELP}`
                 : `${flag} is a flag of aventara ${elsewhere.join(" and ")}, not aventara ${command}; ${HELP}`);
         }
         if (option !== undefined && !option.commands.includes(command)) {
-            throw new CliCommandError(`${option.flag} is a flag of aventara ${option.commands.join(" and ")}, not aventara ${command}; ${HELP}`);
+            throw new AvCliCommandError(`${option.flag} is a flag of aventara ${option.commands.join(" and ")}, not aventara ${command}; ${HELP}`);
         }
         if (seen.has(canonical)) {
-            throw new CliCommandError(`${canonical} was given twice; ${HELP}`);
+            throw new AvCliCommandError(`${canonical} was given twice; ${HELP}`);
         }
         seen.add(canonical);
         if (question === undefined) {
             if (inline !== undefined) {
-                throw new CliCommandError(`${canonical} takes no value; ${HELP}`);
+                throw new AvCliCommandError(`${canonical} takes no value; ${HELP}`);
             }
             options[option.key] = true;
             continue;
@@ -158,7 +224,7 @@ export function parseCliCommand(argv) {
         const value = inline ?? rest[index + 1];
         if (value === undefined ||
             (inline === undefined && value.startsWith("-"))) {
-            throw new CliCommandError(`${canonical} takes a value; ${HELP}`);
+            throw new AvCliCommandError(`${canonical} takes a value; ${HELP}`);
         }
         if (inline === undefined) {
             index += 1;
@@ -172,5 +238,25 @@ 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) {
+    if (rest.includes("--help") || rest.includes("-h")) {
+        return { command: "help", topic: "skill" };
+    }
+    let force = false;
+    for (const argument of rest) {
+        if (argument !== "--force") {
+            throw new AvCliCommandError(argument.startsWith("-")
+                ? `unknown flag ${argument.split("=")[0]}; ${HELP}`
+                : `unexpected argument ${JSON.stringify(argument)}: aventara skill takes no positional argument; ${HELP}`);
+        }
+        if (force) {
+            throw new AvCliCommandError(`--force was given twice; ${HELP}`);
+        }
+        force = true;
+    }
+    return { command: "skill", force };
+}

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

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