@aventara/cli 0.0.0-stage → 0.1.0-pilot.0

package/dist/project/source.scanner.js

@@ -0,0 +1,134 @@
+/**
+ * A lexical view of TypeScript source — enough to find decorators, classes,
+ * imports and brackets **in code**, never inside a comment, a string or a
+ * template literal's text — with no compiler: `aventara new` runs before
+ * anything (TypeScript included) is installed in the project, and the CLI
+ * carries no TypeScript of its own. Shared by the anchored `app.module.ts` edit
+ * and the detection of a developer's ORM service.
+ */
+/** For each character: is it code (not inside a comment, string or template text)? */
+export function codeMask(text) {
+    const code = new Array(text.length).fill(true);
+    /** Open template literals' brace depths: `${` re-enters code until its `}`. */
+    const templates = [];
+    let braces = 0;
+    let index = 0;
+    const mark = (from, to) => {
+        for (let at = from; at < to && at < text.length; at += 1) {
+            code[at] = false;
+        }
+    };
+    const templateText = (from) => {
+        // Scans template text from `from` until "`" (closes) or "${" (re-enters code).
+        let at = from;
+        while (at < text.length) {
+            if (text[at] === "\\") {
+                at += 2;
+                continue;
+            }
+            if (text[at] === "`") {
+                mark(from, at + 1);
+                return at + 1;
+            }
+            if (text[at] === "$" && text[at + 1] === "{") {
+                mark(from, at + 2);
+                templates.push(braces);
+                braces += 1;
+                return at + 2;
+            }
+            at += 1;
+        }
+        mark(from, at);
+        return at;
+    };
+    while (index < text.length) {
+        const char = text[index];
+        const next = text[index + 1];
+        if (char === "/" && next === "/") {
+            const end = text.indexOf("\n", index);
+            const stop = end === -1 ? text.length : end;
+            mark(index, stop);
+            index = stop;
+        }
+        else if (char === "/" && next === "*") {
+            const end = text.indexOf("*/", index + 2);
+            const stop = end === -1 ? text.length : end + 2;
+            mark(index, stop);
+            index = stop;
+        }
+        else if (char === "'" || char === '"') {
+            let at = index + 1;
+            while (at < text.length && text[at] !== char && text[at] !== "\n") {
+                at += text[at] === "\\" ? 2 : 1;
+            }
+            mark(index, at + 1);
+            index = at + 1;
+        }
+        else if (char === "`") {
+            index = templateText(index);
+        }
+        else if (char === "{") {
+            braces += 1;
+            index += 1;
+        }
+        else if (char === "}") {
+            braces -= 1;
+            if (templates.length > 0 && templates[templates.length - 1] === braces) {
+                templates.pop();
+                code[index] = false;
+                index = templateText(index + 1);
+            }
+            else {
+                index += 1;
+            }
+        }
+        else {
+            index += 1;
+        }
+    }
+    return code;
+}
+/** Every index where `token` starts in code. */
+export function codeIndexes(text, code, token) {
+    const found = [];
+    for (const match of text.matchAll(token)) {
+        if (code[match.index]) {
+            found.push(match.index);
+        }
+    }
+    return found;
+}
+export const OPENERS = {
+    "(": ")",
+    "[": "]",
+    "{": "}",
+};
+/** The index of the bracket closing the one at `open`, counting code brackets only. */
+export function closing(text, code, open) {
+    const stack = [];
+    for (let at = open; at < text.length; at += 1) {
+        if (!code[at]) {
+            continue;
+        }
+        const char = text[at];
+        if (OPENERS[char] !== undefined) {
+            stack.push(OPENERS[char]);
+        }
+        else if (char === ")" || char === "]" || char === "}") {
+            if (stack.pop() !== char) {
+                return -1;
+            }
+            if (stack.length === 0) {
+                return at;
+            }
+        }
+    }
+    return -1;
+}
+export function nextCode(text, code, from) {
+    let at = from;
+    while (at < text.length && (!code[at] || /\s/.test(text[at]))) {
+        at += 1;
+    }
+    return at;
+}

package/dist/run/command.runner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The one external process seam (§4.2): a command, its arguments, a working
+ * directory. Its stdout is always **piped**, never inherited — `nest new` asks a
+ * question it has no flag for when its stdout is a terminal (B25) — and both
+ * streams are collected, so a failure can be reported with what it said.
+ */
+export type CommandResult = {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export type CommandRunner = (command: string, args: readonly string[], options: {
+    readonly cwd: string;
+}) => Promise<CommandResult>;
+export declare const runCommand: CommandRunner;

package/dist/run/command.runner.js

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process";
+export const runCommand = (command, args, options) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+        stderr += chunk;
+    });
+    child.once("error", reject);
+    child.once("close", (code) => {
+        resolve({ code: code ?? 1, stdout, stderr });
+    });
+});

package/dist/run/init.orchestrator.d.ts

@@ -0,0 +1,29 @@
+import type { AdapterCatalog } from "../catalog/catalog-entry.interface.js";
+import type { ScaffoldCommand } from "../command/command.parser.js";
+import { type Prompter } from "../wizard/answer.resolver.js";
+import type { CommandRunner } from "./command.runner.js";
+/**
+ * `aventara init` in §4.1's order — inspect, ask, plan, confirm, and only then
+ * write and install. Every step before the write reads; so a refusal anywhere
+ * before it leaves the project exactly as it was. A failure after it (the
+ * install) names the command, its exit code and what to re-run; nothing is
+ * rolled back.
+ */
+export type InitIo = {
+    readonly directory: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly prompter: Prompter;
+    readonly runner: CommandRunner;
+    readonly catalog: AdapterCatalog;
+    /** This CLI's own version (D1). */
+    readonly aventaraVersion: string;
+    /** Next steps that come before init's own (`new`'s `cd <name>`). */
+    readonly firstSteps?: readonly string[];
+};
+/** The install step failed after the files were written. Reported, exit 1. */
+export declare class InstallFailedError extends Error {
+    readonly name = "InstallFailedError";
+}
+export declare function runInit(command: ScaffoldCommand, io: InitIo): Promise<number>;

package/dist/run/init.orchestrator.js

@@ -0,0 +1,222 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { confirmConflicts } from "../apply/conflict.confirmer.js";
+import { matchInstalledOrm, matchOrmSetup, } from "../catalog/catalog.matcher.js";
+import { planInit } from "../plan/project.planner.js";
+import { detectPackageManager } from "../project/package-manager.detector.js";
+import { inspectProject, ProjectRefusedError, } from "../project/project.inspector.js";
+import { scanServices } from "../project/service.detector.js";
+import { templatesFor, } from "../templates/template.registry.js";
+import { resolveAnswers } from "../wizard/answer.resolver.js";
+import { INIT_QUESTIONS, REUSE_QUESTIONS, } from "../wizard/wizard.questions.js";
+/** The install step failed after the files were written. Reported, exit 1. */
+export class InstallFailedError extends Error {
+    name = "InstallFailedError";
+}
+export async function runInit(command, io) {
+    const inspection = inspectProject(io.directory, io.catalog);
+    const read = (file) => {
+        try {
+            return readFileSync(path.join(io.directory, file), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const detectedPackageManager = detectPackageManager({
+        lockfile: inspection.lockfile,
+        userAgent: io.env.npm_config_user_agent,
+    });
+    const prepared = inspection.orm.kind === "present"
+        ? await prepareReuse(command, io, inspection, detectedPackageManager)
+        : await prepareFresh(command, io, inspection, detectedPackageManager);
+    const { entry, provider, scaffold, packageManager } = prepared;
+    const plan = planInit({
+        inspection,
+        entry,
+        scaffold,
+        packageManager,
+        aventaraVersion: io.aventaraVersion,
+        skipInstall: command.skipInstall,
+        read,
+        ...(prepared.wiringByHand === undefined
+            ? {}
+            : { wiringByHand: prepared.wiringByHand }),
+        warnings: prepared.warnings,
+    });
+    await confirmConflicts(plan.conflicts, {
+        yes: command.yes,
+        prompter: io.prompter,
+    });
+    const writes = plan.conflicts.length === 0 ? plan.keeping : plan.replacing;
+    // The only file I/O (§4.1 `apply`).
+    for (const write of writes) {
+        const target = path.join(io.directory, write.path);
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, write.content);
+    }
+    for (const warning of plan.warnings) {
+        io.stderr(`aventara: warning: ${warning}.\n`);
+    }
+    io.stdout(`aventara: initialized ${io.directory} for ${entry.orm.label} ${entry.orm.major} on ${provider}: ${writes
+        .map((write) => `${write.change === "create" ? "created" : "updated"} ${write.path}`)
+        .join(", ")}.\n`);
+    if (plan.instructions !== undefined) {
+        io.stdout(`${plan.instructions}\n`);
+    }
+    if (!command.skipInstall) {
+        io.stdout(`aventara: running ${packageManager} install…\n`);
+        const installed = await io.runner(packageManager, ["install"], {
+            cwd: io.directory,
+        });
+        if (installed.code !== 0) {
+            throw new InstallFailedError(`\`${packageManager} install\` exited with code ${installed.code} after the files were written; fix what it reports and run \`${packageManager} install\` again:\n${installed.stderr.trimEnd()}`);
+        }
+    }
+    io.stdout(`Next:\n${[...(io.firstSteps ?? []), ...plan.nextSteps].map((step, index) => `  ${index + 1}. ${step}`).join("\n")}\n`);
+    return 0;
+}
+/** S6 — no ORM: the ORM and database are asked, and the entry's templates write it all. */
+async function prepareFresh(command, io, inspection, detectedPackageManager) {
+    const answers = await resolveAnswers(INIT_QUESTIONS, {
+        given: command.given,
+        yes: command.yes,
+        prompter: io.prompter,
+        context: { catalog: io.catalog, detectedPackageManager },
+    });
+    const { orm: entry, db, packageManager } = answers;
+    if (entry === undefined || db === undefined || packageManager === undefined) {
+        throw new Error("the init questions settled without an ORM, database and package manager");
+    }
+    return {
+        entry,
+        provider: db,
+        packageManager,
+        scaffold: templatesFor(entry).scaffold({
+            entry,
+            provider: db,
+            moduleKind: inspection.moduleKind,
+            packageManager,
+        }),
+        warnings: [],
+    };
+}
+/** The installed version of `name`, looked up the way Node resolves it: upward from the project. */
+function installedVersion(directory, name) {
+    let current = directory;
+    for (;;) {
+        const manifest = path.join(current, "node_modules", name, "package.json");
+        if (existsSync(manifest)) {
+            const version = JSON.parse(readFileSync(manifest, "utf8")).version;
+            return typeof version === "string" ? version : undefined;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+/**
+ * S7 — the ORM is already set up (R6, R7): the catalog entry is matched against
+ * what is installed, the setup against what the entry declares, and the
+ * developer's own service is found or asked for. Nothing of theirs is written.
+ */
+async function prepareReuse(command, io, inspection, detectedPackageManager) {
+    const dependencies = [
+        ...Object.keys(inspection.manifest.dependencies ?? {}),
+        ...Object.keys(inspection.manifest.devDependencies ?? {}),
+    ];
+    const verdict = matchInstalledOrm(io.catalog, {
+        dependencies,
+        installedVersion: (name) => installedVersion(io.directory, name),
+        installCommand: `${detectedPackageManager} install`,
+    });
+    if (verdict.kind === "refused") {
+        throw new ProjectRefusedError(verdict.sentence);
+    }
+    const { entry } = verdict;
+    const templates = templatesFor(entry);
+    const facts = templates.readProject(io.directory, inspection.manifest);
+    const problem = matchOrmSetup(entry, facts);
+    if (problem !== undefined) {
+        throw new ProjectRefusedError(problem);
+    }
+    const provider = facts.provider;
+    if (facts.clientOutput === undefined) {
+        throw new ProjectRefusedError(`this project's ${facts.generator} generator block in ${facts.schema} has no output, and the generate step reads the client from it; give it one, such as ../src/generated/${entry.orm.family}`);
+    }
+    // A flag naming the ORM or database must name what the project has.
+    for (const [flag, given, found] of [
+        ["--orm", command.given.orm, `${entry.orm.family}@${entry.orm.major}`],
+        ["--db", command.given.db, provider],
+    ]) {
+        if (given !== undefined &&
+            given.trim().toLowerCase() !== found &&
+            !(flag === "--orm" && given.trim().toLowerCase() === entry.orm.family)) {
+            throw new ProjectRefusedError(`${flag} ${given} does not match this project, which already uses ${found}`);
+        }
+    }
+    const scan = scanServices(io.directory, templates.clientShape(facts));
+    const answers = await resolveAnswers(REUSE_QUESTIONS, {
+        given: command.given,
+        yes: command.yes,
+        prompter: io.prompter,
+        context: {
+            catalog: io.catalog,
+            detectedPackageManager,
+            services: {
+                scan,
+                clientClass: templates.clientShape(facts).clientClass,
+                newService: templates.newService.service,
+                newModule: templates.newService.module,
+                newServiceFileExists: existsSync(path.join(io.directory, templates.newService.service.file)),
+                label: entry.orm.label,
+            },
+        },
+    });
+    const { service, module, packageManager } = answers;
+    if (service === undefined ||
+        module === undefined ||
+        packageManager === undefined) {
+        throw new Error("the reuse questions settled without a service, module and package manager");
+    }
+    // Q16-21: beside the client's output, unless that output contains it (the adapter refuses that).
+    const preferred = "src/generated/aventara/discovery.artifact.ts";
+    const artifact = `${preferred}/`.startsWith(`${facts.clientOutput}/`)
+        ? "src/aventara/discovery.artifact.ts"
+        : preferred;
+    const warnings = [
+        ...(facts.clientOutput.startsWith("src/")
+            ? []
+            : [
+                `the ${entry.orm.label} client is generated into ${facts.clientOutput}, outside src/, which nest build does not compile (B6); your build is your own, and init does not change it`,
+            ]),
+        ...(service.clientMember === undefined
+            ? []
+            : [
+                `${service.file}#${service.exportName} holds its client in .${service.clientMember} instead of extending ${templates.clientShape(facts).clientClass}, so src/aventara.config.ts passes ${service.exportName}.${service.clientMember}`,
+            ]),
+    ];
+    return {
+        entry,
+        provider,
+        packageManager,
+        scaffold: templates.reuse({
+            entry,
+            facts: { ...facts, provider, clientOutput: facts.clientOutput },
+            moduleKind: inspection.moduleKind,
+            packageManager,
+            service,
+            module,
+            writeService: service.isNew,
+            artifact,
+        }),
+        ...(service.clientMember === undefined
+            ? {}
+            : {
+                wiringByHand: `${service.exportName} holds its ${entry.orm.label} client instead of extending it`,
+            }),
+        warnings,
+    };
+}

package/dist/run/new.orchestrator.d.ts

@@ -0,0 +1,21 @@
+import type { ScaffoldCommand } from "../command/command.parser.js";
+import { type InitIo } from "./init.orchestrator.js";
+/**
+ * `aventara new <name>` (R2, D1): the pinned `nest new`, then **exactly**
+ * `aventara init`'s pipeline over the fresh project, with the wizard's answers
+ * carried in — so every `new` run exercises the anchored edit, the merges and
+ * the templates `init` uses.
+ *
+ * Nest authors its own scaffold (D1): the CLI never writes Nest's files. Its
+ * output is pinned by digest (B24), so a `@nestjs/cli` that writes something
+ * else stops the run before anything of Aventara's is written over it.
+ */
+/** D1: the `nest new` this CLI was measured against (B1, B24). */
+export declare const NEST_CLI = "@nestjs/cli@12.0.8";
+/** B24: `src/app.module.ts` as `@nestjs/cli` 12.0.8 writes it — the anchored edit's file. */
+export declare const NEST_APP_MODULE_SHA256 = "fe98c4cd2552342272494652287c02e4ef58db3072fcb18513ea831c60f85778";
+export type NewIo = Omit<InitIo, "directory"> & {
+    /** Where `new` creates the project directory. */
+    readonly cwd: string;
+};
+export declare function runNew(command: ScaffoldCommand, io: NewIo): Promise<number>;

package/dist/run/new.orchestrator.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { detectPackageManager } from "../project/package-manager.detector.js";
+import { ProjectRefusedError } from "../project/project.inspector.js";
+import { resolveAnswers } from "../wizard/answer.resolver.js";
+import { NEW_QUESTIONS } from "../wizard/wizard.questions.js";
+import { InstallFailedError, runInit, } from "./init.orchestrator.js";
+/**
+ * `aventara new <name>` (R2, D1): the pinned `nest new`, then **exactly**
+ * `aventara init`'s pipeline over the fresh project, with the wizard's answers
+ * carried in — so every `new` run exercises the anchored edit, the merges and
+ * the templates `init` uses.
+ *
+ * Nest authors its own scaffold (D1): the CLI never writes Nest's files. Its
+ * output is pinned by digest (B24), so a `@nestjs/cli` that writes something
+ * else stops the run before anything of Aventara's is written over it.
+ */
+/** D1: the `nest new` this CLI was measured against (B1, B24). */
+export const NEST_CLI = "@nestjs/cli@12.0.8";
+/** B24: `src/app.module.ts` as `@nestjs/cli` 12.0.8 writes it — the anchored edit's file. */
+export const NEST_APP_MODULE_SHA256 = "fe98c4cd2552342272494652287c02e4ef58db3072fcb18513ea831c60f85778";
+/** The command that runs a package from the registry once, per package manager (B11, B21). */
+function oneOff(packageManager) {
+    return packageManager === "pnpm" ? ["pnpm", ["dlx"]] : ["npx", ["-y"]];
+}
+export async function runNew(command, io) {
+    const answers = await resolveAnswers(NEW_QUESTIONS, {
+        given: command.given,
+        yes: command.yes,
+        prompter: io.prompter,
+        context: {
+            catalog: io.catalog,
+            detectedPackageManager: detectPackageManager({
+                userAgent: io.env.npm_config_user_agent,
+            }),
+        },
+    });
+    const { name, orm, db, packageManager } = answers;
+    if (name === undefined ||
+        orm === undefined ||
+        db === undefined ||
+        packageManager === undefined) {
+        throw new Error("the new questions settled without every answer");
+    }
+    const directory = path.join(io.cwd, name);
+    if (existsSync(directory) && readdirSync(directory).length > 0) {
+        throw new ProjectRefusedError(`aventara new creates ${directory}, which already exists and is not empty; choose another name, or run aventara init inside an existing project`);
+    }
+    // stdout piped by the runner (B25): on a terminal, nest new asks the module
+    // system, with no flag to answer it; piped, it asks nothing and writes ESM.
+    const [runner, prefix] = oneOff(packageManager);
+    const args = [
+        ...prefix,
+        NEST_CLI,
+        "new",
+        name,
+        "--package-manager",
+        packageManager,
+        "--skip-install",
+        "--no-observe",
+        ...(command.skipGit ? ["--skip-git"] : []),
+    ];
+    io.stdout(`aventara: running ${runner} ${args.join(" ")}…\n`);
+    const created = await io.runner(runner, args, { cwd: io.cwd });
+    if (created.code !== 0) {
+        throw new InstallFailedError(`\`${runner} ${args.join(" ")}\` exited with code ${created.code}, and nothing of Aventara's was written; fix what it reports and run aventara new again:\n${created.stderr.trimEnd()}`);
+    }
+    const appModule = path.join(directory, "src", "app.module.ts");
+    const digest = existsSync(appModule)
+        ? createHash("sha256").update(readFileSync(appModule)).digest("hex")
+        : "(absent)";
+    if (digest !== NEST_APP_MODULE_SHA256) {
+        throw new InstallFailedError(`nest new's output changed: ${appModule} is not what ${NEST_CLI} writes (sha256 ${digest}), so nothing of Aventara's was written over it; run aventara init inside ${directory} to add Aventara to it`);
+    }
+    return runInit({
+        command: "init",
+        given: {
+            orm: `${orm.orm.family}@${orm.orm.major}`,
+            db,
+            packageManager,
+        },
+        skipInstall: command.skipInstall,
+        skipGit: false,
+        // A fresh project: there is nothing of the developer's to confirm over.
+        yes: true,
+    }, { ...io, directory, firstSteps: [`Enter the project: cd ${name}`] });
+}

package/dist/templates/prisma7/prisma7.templates.d.ts

@@ -0,0 +1,34 @@
+import type { PackageManifest } from "../../apply/manifest.merger.js";
+import type { ClientShape, ExportReference } from "../../project/service.detector.js";
+import type { OrmProjectFacts, OrmScaffold, ReuseInput, ScaffoldInput } from "../template.registry.js";
+declare function scaffold(input: ScaffoldInput): OrmScaffold;
+declare function reuse(input: ReuseInput): OrmScaffold;
+declare function readProject(directory: string, manifest: PackageManifest): OrmProjectFacts;
+declare function clientShape(facts: OrmProjectFacts): ClientShape;
+export declare const PRISMA7_TEMPLATES: {
+    readonly providers: {
+        readonly sqlite: {
+            readonly driverClass: "PrismaBetterSqlite3";
+            readonly driverOptions: "{ url }";
+            readonly databaseUrl: "file:./dev.db";
+            readonly gitignore: readonly ["/dev.db*"];
+            readonly nativeBuilds: readonly ["@prisma/engines", "better-sqlite3", "prisma"];
+        };
+        readonly postgresql: {
+            readonly driverClass: "PrismaPg";
+            readonly driverOptions: "{ connectionString: url }";
+            readonly databaseUrl: "postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public";
+            readonly gitignore: readonly [];
+            readonly nativeBuilds: readonly ["@prisma/engines", "prisma"];
+        };
+    };
+    readonly scaffold: typeof scaffold;
+    readonly readProject: typeof readProject;
+    readonly clientShape: typeof clientShape;
+    readonly newService: {
+        readonly service: ExportReference;
+        readonly module: ExportReference;
+    };
+    readonly reuse: typeof reuse;
+};
+export {};