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

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";
+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 AvCliCommandError(`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 AvCliCommandError(`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,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}`);
@@ -132,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;
@@ -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";

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");
+const ROUTE_FILE = `src/app${SCAFFOLD_API}/[...aventara]/route.ts`;
+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");
+}
+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`],
+    };
+}