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

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`],
+    };
+}

package/dist/plan/project.planner.js

@@ -1,43 +1,10 @@
-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 { appendEnvEntryIfAbsent, 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";
-export const PREPARE_SCRIPT = "aventara:prepare";
-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_HOST = "@aventara/nest";
+import { planAgentSkill, SKILL_DIRECTORY, } from "../skill/agent-skill.planner.js";
+import { PREPARE_SCRIPT, } from "./host-plan.interface.js";
+import { planNestHost } from "./nest-host.planner.js";
+import { planNextHost } from "./next-host.planner.js";
 const CORE = "@aventara/core";
+const BUILD = "@aventara/build";
 function writeOf(path, before, after) {
     return before === after
         ? []
@@ -49,172 +16,132 @@ function writeOf(path, before, after) {
             },
         ];
 }
-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 { inspection, hosted, packageManager } = input;
+    const { scaffold } = hosted;
     const conflicts = new Set();
     const keeping = [];
     const replacing = [];
     const warnings = [...(input.warnings ?? [])];
-    const both = (path, before, merge) => {
-        const kept = merge(false);
-        const replaced = merge(true);
-        for (const conflict of replaced.conflicts) {
-            conflicts.add(conflict);
-        }
-        keeping.push(...writeOf(path, before, kept.text));
-        replacing.push(...writeOf(path, before, replaced.text));
+    const instructions = [];
+    const builder = {
+        read: input.read,
+        file: (path, content) => {
+            const before = input.read(path);
+            if (before === undefined) {
+                keeping.push({ path, content, change: "create" });
+                replacing.push({ path, content, change: "create" });
+            }
+            else if (before !== content) {
+                conflicts.add(path);
+                replacing.push({ path, content, change: "replace" });
+            }
+        },
+        write: (path, before, after) => {
+            keeping.push(...writeOf(path, before, after));
+            replacing.push(...writeOf(path, before, after));
+        },
+        both: (path, before, merge) => {
+            const kept = merge(false);
+            const replaced = merge(true);
+            for (const conflict of replaced.conflicts) {
+                conflicts.add(conflict);
+            }
+            keeping.push(...writeOf(path, before, kept.text));
+            replacing.push(...writeOf(path, before, replaced.text));
+        },
+        warn: (warning) => {
+            warnings.push(warning);
+        },
+        instruct: (text) => {
+            instructions.push(text);
+        },
     };
     for (const file of scaffold.files) {
-        const before = input.read(file.path);
-        if (before === undefined) {
-            keeping.push({
-                path: file.path,
-                content: file.content,
-                change: "create",
-            });
-            replacing.push({
-                path: file.path,
-                content: file.content,
-                change: "create",
-            });
-        }
-        else if (before !== file.content) {
-            conflicts.add(file.path);
-            replacing.push({
-                path: file.path,
-                content: file.content,
-                change: "replace",
-            });
-        }
-    }
-    const wiring = {
-        imports: [
-            `import { AventaraModule } from '${NEST_HOST}';`,
-            ...scaffold.appModule.imports,
-        ],
-        entries: scaffold.appModule.entries,
-    };
-    const appModule = input.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);
-    let instructions;
-    if (edit.kind === "edited") {
-        keeping.push(...writeOf(APP_MODULE, appModule, edit.text));
-        replacing.push(...writeOf(APP_MODULE, appModule, edit.text));
-        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));
-        }
+        builder.file(file.path, file.content);
     }
-    else {
-        instructions = wiringInstructions(wiring);
-        warnings.push(`${APP_MODULE} was not edited: ${edit.reason}; add AventaraModule by hand, as printed below`);
-    }
-    const main = input.read(MAIN_FILE);
-    const cors = main === undefined
-        ? { kind: "not-anchored", reason: `there is no ${MAIN_FILE}` }
-        : spliceMainCors(main);
-    if (cors.kind === "edited") {
-        keeping.push(...writeOf(MAIN_FILE, main, cors.text));
-        replacing.push(...writeOf(MAIN_FILE, main, cors.text));
-    }
-    else if (cors.kind === "configured") {
-        warnings.push(`${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") {
-        instructions = [instructions, mainCorsInstructions()]
-            .filter((text) => text !== undefined)
-            .join("\n");
-        warnings.push(`${MAIN_FILE} was not edited: ${cors.reason}; add CORS by hand, as printed below`);
-    }
-    const corsWanted = cors.kind !== "configured";
+    const host = hosted.host === "nest"
+        ? planNestHost(builder, {
+            inspection,
+            scaffold: hosted.scaffold,
+            packageManager,
+            aventaraVersion: input.aventaraVersion,
+            ...(hosted.wiringByHand === undefined
+                ? {}
+                : { wiringByHand: hosted.wiringByHand }),
+        })
+        : planNextHost(builder, {
+            inspection,
+            packageManager,
+            aventaraVersion: input.aventaraVersion,
+            externalPackages: [CORE, input.entry.adapterPackage],
+        });
     const scaffoldWritesEnv = Object.keys(scaffold.env).length > 0;
-    const env = input.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 versions = {
-        [CORE]: input.aventaraVersion,
-        [NEST_HOST]: input.aventaraVersion,
-        [input.entry.adapterPackage]: input.aventaraVersion,
-    };
-    both("package.json", inspection.manifestText, (replace) => mergePackageManifest(inspection.manifestText, {
-        dependencies: { ...versions, ...scaffold.dependencies },
-        devDependencies: scaffold.devDependencies,
+    builder.both("package.json", inspection.manifestText, (replace) => mergePackageManifest(inspection.manifestText, {
+        dependencies: {
+            [CORE]: input.aventaraVersion,
+            ...host.dependencies,
+            [input.entry.adapterPackage]: input.aventaraVersion,
+            ...scaffold.dependencies,
+        },
+        devDependencies: {
+            [BUILD]: input.aventaraVersion,
+            ...scaffold.devDependencies,
+        },
         scripts: {
-            [PREPARE_SCRIPT]: scaffold.prepare,
+            [PREPARE_SCRIPT]: `${scaffold.prepare} && ${host.build}`,
             postinstall: `${packageManager} run ${PREPARE_SCRIPT}`,
-            ...Object.fromEntries(PREPARED_SCRIPTS.map((script) => [
-                `pre${script}`,
-                `${packageManager} run ${PREPARE_SCRIPT}`,
-            ])),
+            ...host.scripts,
         },
-        rewrites: inspection.usesNestConfig
-            ? {}
-            : {
-                ...START_SCRIPTS,
-                "test:e2e": E2E_SCRIPTS[inspection.moduleKind],
-            },
+        rewrites: host.rewrites,
     }, replace));
-    if (scaffoldWritesEnv || (corsWanted && env !== undefined)) {
-        both(".env", env, (replace) => {
+    const env = input.read(".env");
+    const { envEntry } = host;
+    if (scaffoldWritesEnv || (envEntry !== undefined && env !== undefined)) {
+        builder.both(".env", env, (replace) => {
             const merged = scaffoldWritesEnv
                 ? mergeEnvFile(env, scaffold.env, replace)
                 : { text: env ?? "", conflicts: [] };
-            return corsWanted
-                ? {
-                    text: appendEnvEntryIfAbsent(merged.text, CORS_ORIGINS_VARIABLE, SCAFFOLD_CORS_ORIGINS),
+            return envEntry === undefined
+                ? merged
+                : {
+                    text: appendEnvEntryIfAbsent(merged.text, envEntry.key, envEntry.value),
                     conflicts: merged.conflicts,
-                }
-                : merged;
+                };
         });
     }
     const gitignore = input.read(".gitignore");
-    both(".gitignore", gitignore, () => mergeGitignore(gitignore, [
+    builder.both(".gitignore", gitignore, () => mergeGitignore(gitignore, [
         ...scaffold.gitignore,
+        ...host.gitignore,
         ...(scaffoldWritesEnv ? [".env"] : []),
     ]));
     if (packageManager === "pnpm" && scaffold.nativeBuilds.length > 0) {
         const workspace = input.read("pnpm-workspace.yaml");
-        both("pnpm-workspace.yaml", workspace, () => mergePnpmWorkspace(workspace, scaffold.nativeBuilds));
+        builder.both("pnpm-workspace.yaml", workspace, () => mergePnpmWorkspace(workspace, scaffold.nativeBuilds));
     }
+    const skill = planAgentSkill({
+        read: input.read,
+        coreVersion: input.aventaraVersion,
+        force: false,
+    });
+    keeping.push(...skill.writes);
+    replacing.push(...skill.writes);
+    warnings.push(...skill.warnings);
     const run = packageManager === "pnpm" ? "pnpm" : "npm";
     return {
         keeping,
         replacing,
         conflicts: [...conflicts],
         warnings,
-        instructions,
+        instructions: instructions.length === 0 ? undefined : instructions.join("\n"),
         nextSteps: [
             ...(input.skipInstall
                 ? [`Install, which also runs ${PREPARE_SCRIPT}: ${run} install`]
                 : []),
             ...scaffold.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)}`,
+            ...host.nextSteps,
+            `Call the API with curl: see "Calling the API over HTTP" in ${SKILL_DIRECTORY}/SKILL.md`,
         ],
     };
 }