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

package/dist/command/command.parser.js

@@ -0,0 +1,163 @@
+import { INIT_FLAG_QUESTIONS, NEW_QUESTIONS, } from "../wizard/wizard.questions.js";
+/** The command line cannot be understood. A refusal: one sentence, exit 1. */
+export class CliCommandError extends Error {
+    name = "CliCommandError";
+}
+/** The options that are not wizard questions. */
+const OPTIONS = [
+    {
+        flag: "--skip-install",
+        key: "skipInstall",
+        commands: ["new", "init"],
+        summary: "write the files, and print the install command instead of running it",
+    },
+    {
+        flag: "--skip-git",
+        key: "skipGit",
+        commands: ["new"],
+        summary: "create no git repository (passed to nest new)",
+    },
+    {
+        flag: "--yes",
+        alias: "-y",
+        key: "yes",
+        commands: ["new", "init"],
+        summary: "accept every unanswered question's default, and confirm overwriting existing content",
+    },
+];
+const QUESTIONS = {
+    new: NEW_QUESTIONS,
+    init: INIT_FLAG_QUESTIONS,
+};
+const HELP = "run `aventara --help` for usage";
+function usageLines(command) {
+    const rows = [
+        ...QUESTIONS[command]
+            .filter((question) => question.flag.startsWith("--"))
+            .map((question) => [
+            `${question.flag} ${question.placeholder ?? "<value>"}`,
+            `${question.label}; asked when omitted`,
+        ]),
+        ...OPTIONS.filter((option) => option.commands.includes(command)).map((option) => [
+            `${option.alias === undefined ? "" : `${option.alias}, `}${option.flag}`,
+            option.summary,
+        ]),
+    ];
+    const width = Math.max(...rows.map(([left]) => left.length));
+    return rows
+        .map(([left, right]) => `    ${left.padEnd(width)}  ${right}`)
+        .join("\n");
+}
+/** What each command does, in one line: the top-level usage and its own. */
+const SUMMARY = {
+    new: "Create a NestJS project with Aventara (nest new, then init).",
+    init: "Add Aventara to the NestJS 12 project in this directory.",
+};
+const SYNOPSIS = {
+    new: "aventara new <name> [options]",
+    init: "aventara init [options]",
+};
+const ASKED = `On a terminal every unanswered question is asked; anywhere else, pass its flag
+or --yes, or the run stops before writing anything.
+`;
+/** `aventara <command> --help` (pilot.1): that command's usage alone. */
+export function commandUsage(command) {
+    return `Usage: ${SYNOPSIS[command]}
+
+${SUMMARY[command]}
+
+Options:
+${usageLines(command)}
+
+${ASKED}`;
+}
+export const USAGE = `aventara — scaffold an Aventara server on NestJS.
+
+Usage:
+  ${SYNOPSIS.new}   ${SUMMARY.new}
+${usageLines("new")}
+
+  ${SYNOPSIS.init}         ${SUMMARY.init}
+${usageLines("init")}
+
+  aventara --help                 Print this and exit 0.
+  aventara <command> --help       Print that command's usage and exit 0.
+  aventara --version              Print this CLI's version and exit 0.
+
+${ASKED}`;
+/** @throws CliCommandError when `argv` is not a command this CLI has. */
+export function parseCliCommand(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined) {
+        throw new CliCommandError(`a command is required: new or init; ${HELP}`);
+    }
+    if (command === "--help" || command === "-h") {
+        return { command: "help" };
+    }
+    if (command === "--version") {
+        return { command: "version" };
+    }
+    if (command !== "new" && command !== "init") {
+        throw new CliCommandError(`unknown command ${JSON.stringify(command)}: the commands are new and init; ${HELP}`);
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        return { command: "help", topic: command };
+    }
+    const questions = QUESTIONS[command];
+    const given = {};
+    const options = {};
+    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.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}`);
+            }
+            given[positional.id] = argument;
+            continue;
+        }
+        const equals = argument.indexOf("=");
+        const flag = equals === -1 ? argument : argument.slice(0, equals);
+        const inline = equals === -1 ? undefined : argument.slice(equals + 1);
+        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
+                ? `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}`);
+        }
+        if (seen.has(canonical)) {
+            throw new CliCommandError(`${canonical} was given twice; ${HELP}`);
+        }
+        seen.add(canonical);
+        if (question === undefined) {
+            if (inline !== undefined) {
+                throw new CliCommandError(`${canonical} takes no value; ${HELP}`);
+            }
+            options[option.key] = true;
+            continue;
+        }
+        const value = inline ?? rest[index + 1];
+        if (value === undefined ||
+            (inline === undefined && value.startsWith("-"))) {
+            throw new CliCommandError(`${canonical} takes a value; ${HELP}`);
+        }
+        if (inline === undefined) {
+            index += 1;
+        }
+        given[question.id] = value;
+    }
+    return {
+        command,
+        given,
+        skipInstall: options.skipInstall === true,
+        skipGit: options.skipGit === true,
+        yes: options.yes === true,
+    };
+}

package/dist/node-version.guard.d.ts

@@ -0,0 +1,8 @@
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export declare function nodeVersionRefusal(bin: string, packageName: string, range: string, version: string): string | undefined;
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export declare function refuseUnsupportedNode(bin: string, manifestUrl: URL): boolean;

package/dist/node-version.guard.js

@@ -0,0 +1,59 @@
+// biome-ignore lint/style/useNodejsImportProtocol: Node 14.0–14.13.0 resolves no "node:" specifier in an ES module, and this module runs on the Nodes the packages do not support.
+import { readFileSync } from "fs";
+function versionOf(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text);
+    if (match === null) {
+        throw new Error(`"${text}" is not a Node version`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const difference = left[index] - right[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+/**
+ * Whether `range` admits `version`. Reads `^x.y.z` (the same major, from the
+ * floor; majors ≥ 1) and `>=x.y.z`, joined by `||`; anything else throws rather
+ * than admit or refuse by guess.
+ */
+function admits(range, version) {
+    return range.split("||").some((part) => {
+        const comparator = /^\s*(\^|>=)(\d+\.\d+\.\d+)\s*$/.exec(part);
+        if (comparator === null) {
+            throw new Error(`engines.node "${range}": the bin's Node guard reads only "^x.y.z" and ">=x.y.z" joined by "||"`);
+        }
+        const floor = versionOf(comparator[2]);
+        return (compareVersions(version, floor) >= 0 &&
+            (comparator[1] === ">=" || version[0] === floor[0]));
+    });
+}
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export function nodeVersionRefusal(bin, packageName, range, version) {
+    return admits(range, versionOf(version))
+        ? undefined
+        : `${bin}: Node ${version} is not supported; ${packageName} needs Node ${range}.`;
+}
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export function refuseUnsupportedNode(bin, manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const range = manifest.engines === undefined ? undefined : manifest.engines.node;
+    if (range === undefined) {
+        throw new Error(`${manifest.name} declares no engines.node for its bin's Node guard`);
+    }
+    const refusal = nodeVersionRefusal(bin, manifest.name, range, process.version);
+    if (refusal === undefined) {
+        return false;
+    }
+    process.stderr.write(`${refusal}\n`);
+    process.exitCode = 1;
+    return true;
+}

package/dist/plan/project.planner.d.ts

@@ -0,0 +1,59 @@
+import type { CatalogEntry } from "../catalog/catalog-entry.interface.js";
+import { type ProjectInspection } from "../project/project.inspector.js";
+import { type OrmScaffold } from "../templates/template.registry.js";
+import type { PackageManager } from "../wizard/wizard.questions.js";
+/**
+ * §4.1's `plan`: everything `aventara init` will write, decided before anything
+ * is written — the files, the anchored `app.module.ts` edit (or the printed
+ * instructions), the merged manifests — and every **conflict**, computed both
+ * ways so the confirmation can choose. Pure apart from reading the files it
+ * would replace.
+ *
+ * What is Nest's (its default start scripts, `AventaraModule`'s import) and what
+ * is Aventara's (its packages at this CLI's version, D1; the `aventara:prepare`
+ * and `postinstall` scripts, Q16-22, D2) is decided here; what is the ORM's
+ * comes from its templates (D7).
+ */
+/** The name of the script that regenerates the ORM client and the discovery artifact (Q16-22). */
+export declare const PREPARE_SCRIPT = "aventara:prepare";
+export type PlannedWrite = {
+    readonly path: string;
+    readonly content: string;
+    /** `create` a new file, or `replace` one whose content changes. */
+    readonly change: "create" | "replace";
+};
+export type ProjectPlan = {
+    /** What is written when the conflicts are kept as they are. */
+    readonly keeping: readonly PlannedWrite[];
+    /** What is written once the conflicts are confirmed (`--yes`, or a yes). */
+    readonly replacing: readonly PlannedWrite[];
+    /** Existing content that differs from what would be written. */
+    readonly conflicts: readonly string[];
+    readonly warnings: readonly string[];
+    /** Printed when the anchored edit could not be made. */
+    readonly instructions: string | undefined;
+    readonly nextSteps: readonly string[];
+};
+export type PlanInput = {
+    readonly inspection: ProjectInspection;
+    readonly entry: CatalogEntry;
+    readonly scaffold: OrmScaffold;
+    readonly packageManager: PackageManager;
+    /** This CLI's version: every Aventara package is pinned to it (D1). */
+    readonly aventaraVersion: string;
+    readonly skipInstall: boolean;
+    /** The current text of a project file, or `undefined` when absent. */
+    readonly read: (file: string) => string | undefined;
+    /** The anchored edit is not attempted; the wiring is printed (a service holding its client, §4.4.4). */
+    readonly wiringByHand?: string;
+    /** Said before the write, beside the planner's own. */
+    readonly warnings?: readonly string[];
+};
+/**
+ * pilot.1 — the frontend's first command, as the developer can run it: the
+ * package manager's own one-off runner (`npx` or `pnpm dlx`), and — while this
+ * CLI is a prerelease — its dist-tag, so the client comes from the same release
+ * (`0.1.0-pilot.1` → `@aventara/client@pilot`). A release has no tag to name.
+ */
+export declare function frontendInitCommand(packageManager: PackageManager, cliVersion: string): string;
+export declare function planInit(input: PlanInput): ProjectPlan;

package/dist/plan/project.planner.js

@@ -0,0 +1,201 @@
+import { spliceAppModule, wiringInstructions, } from "../apply/app-module.anchor.js";
+import { E2E_SPEC, spliceContractTest } from "../apply/e2e-spec.anchor.js";
+import { 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";
+/**
+ * §4.1's `plan`: everything `aventara init` will write, decided before anything
+ * is written — the files, the anchored `app.module.ts` edit (or the printed
+ * instructions), the merged manifests — and every **conflict**, computed both
+ * ways so the confirmation can choose. Pure apart from reading the files it
+ * would replace.
+ *
+ * What is Nest's (its default start scripts, `AventaraModule`'s import) and what
+ * is Aventara's (its packages at this CLI's version, D1; the `aventara:prepare`
+ * and `postinstall` scripts, Q16-22, D2) is decided here; what is the ORM's
+ * comes from its templates (D7).
+ */
+/** The name of the script that regenerates the ORM client and the discovery artifact (Q16-22). */
+export const PREPARE_SCRIPT = "aventara:prepare";
+/** D3: `nest new`'s start scripts (B1), and what each becomes so `.env` reaches the server. */
+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",
+    },
+};
+/**
+ * F-853: `nest new`'s e2e script per module kind (B1, B28), and the same run with
+ * the `.env` the start scripts load — the e2e spec boots `AppModule`, whose
+ * service needs `DATABASE_URL`, and neither vitest nor jest loads `.env`.
+ */
+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";
+const CORE = "@aventara/core";
+function writeOf(path, before, after) {
+    return before === after
+        ? []
+        : [
+            {
+                path,
+                content: after,
+                change: before === undefined ? "create" : "replace",
+            },
+        ];
+}
+/**
+ * pilot.1 — the frontend's first command, as the developer can run it: the
+ * package manager's own one-off runner (`npx` or `pnpm dlx`), and — while this
+ * CLI is a prerelease — its dist-tag, so the client comes from the same release
+ * (`0.1.0-pilot.1` → `@aventara/client@pilot`). A release has no tag to name.
+ */
+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 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));
+    };
+    // The ORM's new files: identical content is no change (P3), other content a conflict.
+    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",
+            });
+        }
+    }
+    // The one edit to developer code (R2).
+    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));
+        // pilot.1: Nest's own e2e spec also asks for the contract — only when
+        // AventaraModule was wired in, so the test proves what it claims.
+        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));
+        }
+    }
+    else {
+        instructions = wiringInstructions(wiring);
+        warnings.push(`${APP_MODULE} was not edited: ${edit.reason}; add AventaraModule by hand, as printed below`);
+    }
+    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,
+        scripts: {
+            [PREPARE_SCRIPT]: scaffold.prepare,
+            // D2: the generated trees are ignored and rebuilt on every install.
+            postinstall: `${packageManager} run ${PREPARE_SCRIPT}`,
+        },
+        rewrites: inspection.usesNestConfig
+            ? {}
+            : {
+                ...START_SCRIPTS,
+                "test:e2e": E2E_SCRIPTS[inspection.moduleKind],
+            },
+    }, replace));
+    const env = input.read(".env");
+    if (Object.keys(scaffold.env).length > 0) {
+        both(".env", env, (replace) => mergeEnvFile(env, scaffold.env, replace));
+    }
+    const gitignore = input.read(".gitignore");
+    both(".gitignore", gitignore, () => mergeGitignore(gitignore, scaffold.gitignore));
+    if (packageManager === "pnpm" && scaffold.nativeBuilds.length > 0) {
+        const workspace = input.read("pnpm-workspace.yaml");
+        both("pnpm-workspace.yaml", workspace, () => mergePnpmWorkspace(workspace, scaffold.nativeBuilds));
+    }
+    const run = packageManager === "pnpm" ? "pnpm" : "npm";
+    return {
+        keeping,
+        replacing,
+        conflicts: [...conflicts],
+        warnings,
+        instructions,
+        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.",
+                ]
+                : []),
+            `Start the server: ${run} run start:dev`,
+            `In your frontend: ${frontendInitCommand(packageManager, input.aventaraVersion)}`,
+        ],
+    };
+}

package/dist/project/package-manager.detector.d.ts

@@ -0,0 +1,12 @@
+import type { PackageManager } from "../wizard/wizard.questions.js";
+/**
+ * Q16-5's default package manager: a lockfile says what a project already uses
+ * (`init`); otherwise the package manager that launched this CLI says what the
+ * developer uses — `npm_config_user_agent` is `npm/…` under `npx` and
+ * `npm exec`, `pnpm/…` under `pnpm dlx` and `pnpm exec`, and unset when the bin
+ * runs directly (B11); otherwise npm.
+ */
+export declare function detectPackageManager(signals: {
+    readonly lockfile?: PackageManager | undefined;
+    readonly userAgent?: string | undefined;
+}): PackageManager;

package/dist/project/package-manager.detector.js

@@ -0,0 +1,14 @@
+/**
+ * Q16-5's default package manager: a lockfile says what a project already uses
+ * (`init`); otherwise the package manager that launched this CLI says what the
+ * developer uses — `npm_config_user_agent` is `npm/…` under `npx` and
+ * `npm exec`, `pnpm/…` under `pnpm dlx` and `pnpm exec`, and unset when the bin
+ * runs directly (B11); otherwise npm.
+ */
+export function detectPackageManager(signals) {
+    if (signals.lockfile !== undefined) {
+        return signals.lockfile;
+    }
+    const launcher = signals.userAgent?.split("/")[0];
+    return launcher === "pnpm" ? "pnpm" : "npm";
+}

package/dist/project/project.inspector.d.ts

@@ -0,0 +1,38 @@
+import type { PackageManifest } from "../apply/manifest.merger.js";
+import type { AdapterCatalog, CatalogEntry } from "../catalog/catalog-entry.interface.js";
+import type { ModuleKind } from "../templates/template.registry.js";
+import type { PackageManager } from "../wizard/wizard.questions.js";
+/**
+ * §4.1's `inspect`: what `aventara init` needs to know about the project in the
+ * working directory, read before anything is asked or written — so every
+ * refusal here leaves the directory exactly as it was (it is a property of the
+ * order, not of a rollback).
+ */
+/** The project is not one `aventara init` serves. A refusal: one sentence, nothing written. */
+export declare class ProjectRefusedError extends Error {
+    readonly name = "ProjectRefusedError";
+}
+/** The ORM a project already has, by the catalog's family packages (R14, D10). */
+export type OrmPresence = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "present";
+    /** The family packages found among its dependencies. */
+    readonly packages: readonly string[];
+    /** The catalog entries whose family they belong to. */
+    readonly families: readonly CatalogEntry["orm"]["label"][];
+};
+export type ProjectInspection = {
+    readonly directory: string;
+    readonly manifest: PackageManifest;
+    readonly manifestText: string;
+    readonly moduleKind: ModuleKind;
+    /** The package manager the lockfile names, if exactly one does. */
+    readonly lockfile: PackageManager | undefined;
+    readonly orm: OrmPresence;
+    /** `@nestjs/config` loads `.env` itself, so the start scripts are left alone (P5). */
+    readonly usesNestConfig: boolean;
+};
+/** The file the anchored edit opens (R2). */
+export declare const APP_MODULE = "src/app.module.ts";
+export declare function inspectProject(directory: string, catalog: AdapterCatalog): ProjectInspection;

package/dist/project/project.inspector.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { lowestMajorOf } from "../catalog/range.reader.js";
+/**
+ * §4.1's `inspect`: what `aventara init` needs to know about the project in the
+ * working directory, read before anything is asked or written — so every
+ * refusal here leaves the directory exactly as it was (it is a property of the
+ * order, not of a rollback).
+ */
+/** The project is not one `aventara init` serves. A refusal: one sentence, nothing written. */
+export class ProjectRefusedError extends Error {
+    name = "ProjectRefusedError";
+}
+/** Nest 12 only (Phase 11 Q16). */
+const NEST_MAJOR = 12;
+/** D4: TypeScript 7 has no classic compiler API. */
+const FIRST_UNSUPPORTED_TYPESCRIPT = 7;
+/** The file the anchored edit opens (R2). */
+export const APP_MODULE = "src/app.module.ts";
+const LOCKFILES = [
+    ["package-lock.json", "npm"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+];
+function dependencyRange(manifest, name) {
+    return manifest.dependencies?.[name] ?? manifest.devDependencies?.[name];
+}
+function matchesFamily(pattern, name) {
+    return pattern.endsWith("*")
+        ? name.startsWith(pattern.slice(0, -1))
+        : name === pattern;
+}
+export function inspectProject(directory, catalog) {
+    const manifestPath = path.join(directory, "package.json");
+    if (!existsSync(manifestPath)) {
+        throw new ProjectRefusedError(`aventara init runs in a NestJS ${NEST_MAJOR} project, and there is no package.json in ${directory}`);
+    }
+    const manifestText = readFileSync(manifestPath, "utf8");
+    const manifest = JSON.parse(manifestText);
+    const nest = dependencyRange(manifest, "@nestjs/core");
+    if (nest === undefined) {
+        throw new ProjectRefusedError(`aventara init runs in a NestJS ${NEST_MAJOR} project, and this package.json has no @nestjs/core dependency`);
+    }
+    if (lowestMajorOf(nest) !== NEST_MAJOR) {
+        throw new ProjectRefusedError(`aventara init supports NestJS ${NEST_MAJOR} only, and this project depends on @nestjs/core ${nest}`);
+    }
+    const typescript = dependencyRange(manifest, "typescript");
+    const typescriptMajor = typescript === undefined ? undefined : lowestMajorOf(typescript);
+    if (typescriptMajor !== undefined &&
+        typescriptMajor >= FIRST_UNSUPPORTED_TYPESCRIPT) {
+        throw new ProjectRefusedError(`this project declares typescript ${typescript}, and TypeScript ${FIRST_UNSUPPORTED_TYPESCRIPT} has no classic compiler API for Aventara's generate steps to read types with; use TypeScript 6 or 5`);
+    }
+    const lockfiles = LOCKFILES.filter(([file]) => existsSync(path.join(directory, file))).map(([, manager]) => manager);
+    const known = lockfiles.filter((manager) => manager !== "yarn");
+    if (lockfiles.includes("yarn") && known.length === 0) {
+        throw new ProjectRefusedError("this project has only a yarn.lock, and aventara init supports npm and pnpm");
+    }
+    const appModule = path.join(directory, APP_MODULE);
+    if (existsSync(appModule) &&
+        /\bAventaraModule\b/.test(readFileSync(appModule, "utf8"))) {
+        throw new ProjectRefusedError(`this project is already initialized: ${APP_MODULE} uses AventaraModule`);
+    }
+    const dependencies = [
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.devDependencies ?? {}),
+    ];
+    const present = catalog.filter((entry) => entry.familyPackages.some((pattern) => dependencies.some((name) => matchesFamily(pattern, name))));
+    const orm = present.length === 0
+        ? { kind: "absent" }
+        : {
+            kind: "present",
+            packages: dependencies.filter((name) => present.some((entry) => entry.familyPackages.some((pattern) => matchesFamily(pattern, name)))),
+            families: [...new Set(present.map((entry) => entry.orm.label))],
+        };
+    return {
+        directory,
+        manifest,
+        manifestText,
+        moduleKind: manifest.type === "module" ? "esm" : "cjs",
+        lockfile: known.length === 1 ? known[0] : undefined,
+        orm,
+        usesNestConfig: dependencyRange(manifest, "@nestjs/config") !== undefined,
+    };
+}