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

package/dist/aventara.bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { refuseUnsupportedNode } from "./node-version.guard.js";
+/**
+ * `aventara`'s entry, what the manifest's `bin` names (F-855). It always runs — no
+ * `import.meta.main` — and checks this Node against the package's
+ * `engines.node` before it loads anything else: the program is imported only
+ * once the guard admits this Node, so an older Node meets one sentence and exit
+ * 1, never a silent exit 0 or a parse error from a module it cannot run.
+ *
+ * A promise chain rather than a top-level `await`, which Node 12 cannot parse:
+ * this file is read by the Nodes the package does not support.
+ */
+if (!refuseUnsupportedNode("aventara", new URL("../package.json", import.meta.url))) {
+    void import("./cli.js").then((program) => program.runFromProcess());
+}

package/dist/catalog/adapter.catalog.generated.d.ts

@@ -0,0 +1,19 @@
+export declare const ADAPTER_CATALOG: readonly [{
+    readonly id: "prisma7";
+    readonly adapterPackage: "@aventara/prisma7-adapter";
+    readonly orm: {
+        readonly family: "prisma";
+        readonly label: "Prisma";
+        readonly package: "@prisma/client";
+        readonly major: 7;
+    };
+    readonly range: "^7.10.0";
+    readonly familyPackages: readonly ["prisma", "@prisma/client", "@prisma/prisma7", "@prisma/orm-*"];
+    readonly providers: readonly ["sqlite", "postgresql"];
+    readonly drivers: {
+        readonly sqlite: "@prisma/adapter-better-sqlite3";
+        readonly postgresql: "@prisma/adapter-pg";
+    };
+    readonly generators: readonly ["prisma-client"];
+    readonly bin: "aventara-prisma7-generate";
+}];

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

@@ -0,0 +1,35 @@
+// biome-ignore-all format: generated output; these bytes are the catalog
+// biome-ignore-all lint: generated output
+/* !!! Generated by @aventara/cli's adapter-catalog generator from each adapter's manifest. Do not edit. !!! */
+/* Regenerate with `pnpm --filter @aventara/cli build` (its `prebuild`). */
+export const ADAPTER_CATALOG = [
+    {
+        "id": "prisma7",
+        "adapterPackage": "@aventara/prisma7-adapter",
+        "orm": {
+            "family": "prisma",
+            "label": "Prisma",
+            "package": "@prisma/client",
+            "major": 7
+        },
+        "range": "^7.10.0",
+        "familyPackages": [
+            "prisma",
+            "@prisma/client",
+            "@prisma/prisma7",
+            "@prisma/orm-*"
+        ],
+        "providers": [
+            "sqlite",
+            "postgresql"
+        ],
+        "drivers": {
+            "sqlite": "@prisma/adapter-better-sqlite3",
+            "postgresql": "@prisma/adapter-pg"
+        },
+        "generators": [
+            "prisma-client"
+        ],
+        "bin": "aventara-prisma7-generate"
+    }
+];

package/dist/catalog/catalog-entry.interface.d.ts

@@ -0,0 +1,46 @@
+import type { ADAPTER_CATALOG } from "./adapter.catalog.generated.js";
+/**
+ * One entry per Aventara adapter package that exists (R13, R14): what the CLI
+ * may offer and what it must refuse, every value traced to that adapter's own
+ * manifest — its `aventara.adapter` declaration, its `peerDependencies` and its
+ * `bin` (Q16-27). The entries are **generated** at this package's build by
+ * `scripts/adapter-catalog.generator.ts` into `adapter.catalog.generated.ts`
+ * and never edited (P9). The CLI holds no list of ORMs, majors, providers or
+ * drivers of its own.
+ */
+export type CatalogEntry = {
+    /** The adapter package's ORM stem, e.g. `prisma7` (Q16-33): the wizard's value and the templates' key. */
+    readonly id: string;
+    /** The adapter package a project installs, e.g. `@aventara/prisma7-adapter`. */
+    readonly adapterPackage: string;
+    readonly orm: {
+        /** `aventara.adapter.orm`, e.g. `prisma`: the family the wizard groups majors under. */
+        readonly family: string;
+        /** `aventara.adapter.ormLabel`, e.g. `Prisma`: how the wizard names the family. */
+        readonly label: string;
+        /** `aventara.adapter.ormPackage`, e.g. `@prisma/client`: whose installed version selects the entry. */
+        readonly package: string;
+        /** The one major `range` admits. */
+        readonly major: number;
+    };
+    /** `peerDependencies[orm.package]`: the ORM versions the adapter supports (D8). */
+    readonly range: string;
+    /** Packages that identify the ORM family in a project (D10, Q16-27). */
+    readonly familyPackages: readonly string[];
+    /** Database providers, in the adapter's order; the first is the default (R10). */
+    readonly providers: readonly string[];
+    /** Provider → the driver adapter package for it. */
+    readonly drivers: Readonly<Record<string, string>>;
+    /** The ORM generators whose output the adapter reads (B27). */
+    readonly generators: readonly string[];
+    /** The adapter's generate step: its one `bin` (Q16-30). */
+    readonly bin: string;
+};
+export type AdapterCatalog = readonly CatalogEntry[];
+/** The generated catalog's literal type: what the template registry is checked against. */
+export type Catalog = typeof ADAPTER_CATALOG;
+export type EntryId = Catalog[number]["id"];
+/** The providers one entry declares, as literals. */
+export type ProviderOf<I extends EntryId> = Extract<Catalog[number], {
+    readonly id: I;
+}>["providers"][number];

package/dist/catalog/catalog-entry.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/catalog/catalog.matcher.d.ts

@@ -0,0 +1,46 @@
+import type { AdapterCatalog, CatalogEntry } from "./catalog-entry.interface.js";
+/**
+ * R7, R13, R14, D10, P10 — which catalog entry serves a project that already
+ * has an ORM, decided from what is **installed** and what each adapter
+ * **declares**; this module holds no ORM, version or provider of its own.
+ *
+ * 1. The ORM family: the catalog entries whose family packages the project
+ *    depends on (a pattern ending in `*` is a prefix).
+ * 2. Its major: the installed version of the family's ORM package, never the
+ *    range in `package.json` (P10: `^7` can resolve to anything in 7, and a
+ *    stale lockfile to 6.x). Every other family package installed must be of
+ *    that same major — a Prisma 8 CLI or an `@prisma/orm-*` beside a Prisma 7
+ *    client is a project mid-migration, refused (D10).
+ * 3. The entry for that major, or a refusal naming what exists.
+ * 4. The installed version inside the entry's declared range.
+ * 5. Then what the project's ORM setup declares — provider, driver, generator —
+ *    against the entry's providers, drivers and generators.
+ *
+ * Every refusal is one sentence naming what was found and what the catalog
+ * offers. Nothing has been written when one is raised.
+ */
+export type MatchVerdict = {
+    readonly kind: "matched";
+    readonly entry: CatalogEntry;
+} | {
+    readonly kind: "refused";
+    readonly sentence: string;
+};
+export type InstalledOrm = {
+    /** The project's dependency names (dependencies and devDependencies). */
+    readonly dependencies: readonly string[];
+    /** The installed version of a package, or `undefined` when it is not installed. */
+    readonly installedVersion: (name: string) => string | undefined;
+    /** The command that installs the project's dependencies. */
+    readonly installCommand: string;
+};
+/** What the project's ORM setup states, read by the entry's templates. */
+export type OrmSetup = {
+    readonly provider: string | undefined;
+    readonly generator: string | undefined;
+    /** The driver-adapter packages the project depends on. */
+    readonly drivers: readonly string[];
+};
+export declare function matchInstalledOrm(catalog: AdapterCatalog, project: InstalledOrm): MatchVerdict;
+/** Step 5: the project's provider, driver and generator against what `entry` declares. */
+export declare function matchOrmSetup(entry: CatalogEntry, setup: OrmSetup): string | undefined;

package/dist/catalog/catalog.matcher.js

@@ -0,0 +1,83 @@
+import { satisfiesRange } from "./range.reader.js";
+function matches(pattern, name) {
+    return pattern.endsWith("*")
+        ? name.startsWith(pattern.slice(0, -1))
+        : name === pattern;
+}
+function majorOf(version) {
+    const major = /^(\d+)\./.exec(version)?.[1];
+    return major === undefined ? undefined : Number(major);
+}
+function available(catalog) {
+    return catalog
+        .map((entry) => `${entry.orm.label} ${entry.orm.major} (${entry.adapterPackage})`)
+        .join(", ");
+}
+export function matchInstalledOrm(catalog, project) {
+    const family = catalog.filter((entry) => entry.familyPackages.some((pattern) => project.dependencies.some((name) => matches(pattern, name))));
+    const first = family[0];
+    if (first === undefined) {
+        throw new Error("matchInstalledOrm is asked only about a project with an ORM");
+    }
+    const label = first.orm.label;
+    const ormPackage = first.orm.package;
+    const members = project.dependencies.filter((name) => first.familyPackages.some((pattern) => matches(pattern, name)));
+    const installed = members.map((name) => ({
+        name,
+        version: project.installedVersion(name),
+    }));
+    const missing = installed.filter((member) => member.version === undefined);
+    if (missing.length > 0) {
+        return {
+            kind: "refused",
+            sentence: `this project depends on ${missing.map((member) => member.name).join(", ")}, which ${missing.length === 1 ? "is" : "are"} not installed, so its ${label} version cannot be read; install first: ${project.installCommand}`,
+        };
+    }
+    const client = installed.find((member) => member.name === ormPackage);
+    const clientMajor = client?.version === undefined ? undefined : majorOf(client.version);
+    // D10: one major across the family. The first package off the client's major
+    // (or any, when there is no client) names the project's other major.
+    const off = installed.find((member) => member.name !== ormPackage &&
+        majorOf(member.version) !== clientMajor);
+    const decided = off ?? client;
+    if (decided === undefined) {
+        return {
+            kind: "refused",
+            sentence: `this project depends on ${members.join(", ")} but not on ${ormPackage}; available: ${available(catalog)}`,
+        };
+    }
+    const major = majorOf(decided.version);
+    const entry = family.find((candidate) => candidate.orm.major === major);
+    if (off !== undefined || entry === undefined) {
+        return {
+            kind: "refused",
+            sentence: `this project uses ${label} ${major} (${decided.name} ${decided.version}); there is no Aventara adapter for ${label} ${major}; available: ${available(catalog)}`,
+        };
+    }
+    if (!satisfiesRange(client?.version, entry.range)) {
+        return {
+            kind: "refused",
+            sentence: `this project has ${ormPackage} ${client?.version}, outside the ${entry.range} the ${label} ${entry.orm.major} adapter (${entry.adapterPackage}) supports; upgrade ${ormPackage}, the ${label} CLI and the driver adapter to that range`,
+        };
+    }
+    return { kind: "matched", entry };
+}
+/** Step 5: the project's provider, driver and generator against what `entry` declares. */
+export function matchOrmSetup(entry, setup) {
+    const name = `the ${entry.orm.label} ${entry.orm.major} adapter`;
+    if (setup.provider === undefined ||
+        !entry.providers.includes(setup.provider)) {
+        return `this project's schema uses the database ${JSON.stringify(setup.provider ?? "(none)")}, and ${name} supports ${entry.providers.join(" and ")}`;
+    }
+    if (setup.generator === undefined ||
+        !entry.generators.includes(setup.generator)) {
+        return `this project's schema generates its client with ${JSON.stringify(setup.generator ?? "(no generator)")}, and ${name} reads only the output of ${entry.generators.join(" and ")}; switch the generator block to it`;
+    }
+    const driver = entry.drivers[setup.provider];
+    if (!setup.drivers.includes(driver)) {
+        return setup.drivers.length === 0
+            ? `this project has no driver adapter for ${setup.provider}, which ${entry.orm.label} ${entry.orm.major} requires; ${name} supports ${driver}`
+            : `this project drives ${setup.provider} through ${setup.drivers.join(", ")}, and ${name} supports ${driver}`;
+    }
+    return undefined;
+}

package/dist/catalog/range.reader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reading a declared version range for the two facts the CLI needs from one:
+ * its lowest version (D1, D9: what `init` pins when it installs the ORM — the
+ * adapter's measured floor) and its lowest major (a project's declared Nest and
+ * TypeScript ranges, checked before anything is written).
+ */
+/** `^7.10.0` → `7.10.0`; `>=7.10.0 <8` → `7.10.0`. */
+export declare function lowestVersionOf(range: string): string;
+/** `^12.0.1` → 12; `~6.0.2` → 6; a range with no number (`latest`, `*`) → `undefined`. */
+export declare function lowestMajorOf(range: string): number | undefined;
+/**
+ * Whether an installed `version` is in a declared `range` (R7: the adapter's
+ * declaration decides support). Reads the comparator forms an adapter's peer
+ * range uses; a pre-release never satisfies (semver's rule for a range whose
+ * comparators carry none). Any other form is refused rather than guessed.
+ */
+export declare function satisfiesRange(version: string, range: string): boolean;

package/dist/catalog/range.reader.js

@@ -0,0 +1,77 @@
+/**
+ * Reading a declared version range for the two facts the CLI needs from one:
+ * its lowest version (D1, D9: what `init` pins when it installs the ORM — the
+ * adapter's measured floor) and its lowest major (a project's declared Nest and
+ * TypeScript ranges, checked before anything is written).
+ */
+const VERSION = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+/** `^7.10.0` → `7.10.0`; `>=7.10.0 <8` → `7.10.0`. */
+export function lowestVersionOf(range) {
+    const found = VERSION.exec(range);
+    if (found === null) {
+        throw new Error(`the range ${JSON.stringify(range)} states no version`);
+    }
+    return `${found[1]}.${found[2] ?? 0}.${found[3] ?? 0}`;
+}
+/** `^12.0.1` → 12; `~6.0.2` → 6; a range with no number (`latest`, `*`) → `undefined`. */
+export function lowestMajorOf(range) {
+    const found = VERSION.exec(range);
+    return found === null ? undefined : Number(found[1]);
+}
+const RELEASE = /^(\d+)\.(\d+)\.(\d+)$/;
+const COMPARATOR = /^(\^|>=|>|<=|<|=)?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+/**
+ * Whether an installed `version` is in a declared `range` (R7: the adapter's
+ * declaration decides support). Reads the comparator forms an adapter's peer
+ * range uses; a pre-release never satisfies (semver's rule for a range whose
+ * comparators carry none). Any other form is refused rather than guessed.
+ */
+export function satisfiesRange(version, range) {
+    const release = RELEASE.exec(version);
+    if (release === null) {
+        return false;
+    }
+    const candidate = [
+        Number(release[1]),
+        Number(release[2]),
+        Number(release[3]),
+    ];
+    const compare = (bound) => {
+        for (let index = 0; index < 3; index += 1) {
+            const difference = candidate[index] - bound[index];
+            if (difference !== 0) {
+                return difference;
+            }
+        }
+        return 0;
+    };
+    return range
+        .trim()
+        .split(/\s+/)
+        .every((comparator) => {
+        const parsed = COMPARATOR.exec(comparator);
+        if (parsed === null || (parsed[1] === "^" && parsed[2] === "0")) {
+            throw new Error(`the range ${JSON.stringify(range)} is not one the CLI reads`);
+        }
+        const bound = [
+            Number(parsed[2]),
+            Number(parsed[3] ?? 0),
+            Number(parsed[4] ?? 0),
+        ];
+        const order = compare(bound);
+        switch (parsed[1]) {
+            case "^":
+                return order >= 0 && candidate[0] === bound[0];
+            case ">=":
+                return order >= 0;
+            case ">":
+                return order > 0;
+            case "<=":
+                return order <= 0;
+            case "<":
+                return order < 0;
+            default:
+                return order === 0;
+        }
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,30 @@
+import type { AdapterCatalog } from "./catalog/catalog-entry.interface.js";
+import { type CommandRunner } from "./run/command.runner.js";
+import { type Prompter } from "./wizard/answer.resolver.js";
+/**
+ * `aventara` — the bin (R1): `new` and `init`. A refusal is one sentence on
+ * stderr and exit 1, never a stack; anything else is a defect and keeps its
+ * stack.
+ *
+ * `init` initializes the project in the working directory
+ * (`run/init.orchestrator.ts`); `new` creates one with the pinned `nest new` and
+ * then runs the same pipeline over it (`run/new.orchestrator.ts`).
+ */
+export type CliIo = {
+    /** The working directory: where `init` initializes and `new` creates. */
+    readonly cwd: 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;
+};
+export declare function runCli(argv: readonly string[], io: CliIo): Promise<number>;
+/**
+ * Runs `aventara` over this process — its arguments, its terminal, its exit
+ * code. Called by the bin's entry (`aventara.bin.ts`) once the Node guard has
+ * admitted this Node; importing this module runs nothing, which lets `runCli`
+ * be tested in process.
+ */
+export declare function runFromProcess(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { ConflictsNotConfirmedError } from "./apply/conflict.confirmer.js";
+import { ADAPTER_CATALOG } from "./catalog/adapter.catalog.generated.js";
+import { CliCommandError, parseCliCommand, USAGE, } from "./command/command.parser.js";
+import { ProjectRefusedError } from "./project/project.inspector.js";
+import { runCommand } from "./run/command.runner.js";
+import { InstallFailedError, runInit } from "./run/init.orchestrator.js";
+import { runNew } from "./run/new.orchestrator.js";
+import { UnansweredQuestionsError, } from "./wizard/answer.resolver.js";
+import { createReadlinePrompter, WizardCancelledError, } from "./wizard/readline.prompter.js";
+import { WizardAnswerError } from "./wizard/wizard.questions.js";
+const REFUSALS = [
+    CliCommandError,
+    WizardAnswerError,
+    UnansweredQuestionsError,
+    WizardCancelledError,
+    ProjectRefusedError,
+    ConflictsNotConfirmedError,
+    InstallFailedError,
+];
+const MANIFEST = new URL("../package.json", import.meta.url);
+function ownVersion() {
+    return JSON.parse(readFileSync(MANIFEST, "utf8"))
+        .version;
+}
+export async function runCli(argv, io) {
+    try {
+        const command = parseCliCommand(argv);
+        if (command.command === "help") {
+            io.stdout(USAGE);
+            return 0;
+        }
+        if (command.command === "version") {
+            io.stdout(`${ownVersion()}\n`);
+            return 0;
+        }
+        if (command.command === "init") {
+            return await runInit(command, {
+                directory: io.cwd,
+                env: io.env,
+                stdout: io.stdout,
+                stderr: io.stderr,
+                prompter: io.prompter,
+                runner: io.runner ?? runCommand,
+                catalog: io.catalog ?? ADAPTER_CATALOG,
+                aventaraVersion: ownVersion(),
+            });
+        }
+        return await runNew(command, {
+            cwd: io.cwd,
+            env: io.env,
+            stdout: io.stdout,
+            stderr: io.stderr,
+            prompter: io.prompter,
+            runner: io.runner ?? runCommand,
+            catalog: io.catalog ?? ADAPTER_CATALOG,
+            aventaraVersion: ownVersion(),
+        });
+    }
+    catch (error) {
+        if (REFUSALS.some((refusal) => error instanceof refusal)) {
+            io.stderr(`aventara: ${error.message}.\n`);
+            return 1;
+        }
+        io.stderr(`${String(error instanceof Error ? error.stack : error)}\n`);
+        return 1;
+    }
+}
+/**
+ * Runs `aventara` over this process — its arguments, its terminal, its exit
+ * code. Called by the bin's entry (`aventara.bin.ts`) once the Node guard has
+ * admitted this Node; importing this module runs nothing, which lets `runCli`
+ * be tested in process.
+ */
+export async function runFromProcess() {
+    const prompter = createReadlinePrompter({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        process.exitCode = await runCli(process.argv.slice(2), {
+            cwd: process.cwd(),
+            env: process.env,
+            stdout: (text) => {
+                process.stdout.write(text);
+            },
+            stderr: (text) => {
+                process.stderr.write(text);
+            },
+            prompter,
+        });
+    }
+    finally {
+        prompter.close();
+    }
+}

package/dist/command/command.parser.d.ts

@@ -0,0 +1,31 @@
+import { type QuestionId } from "../wizard/wizard.questions.js";
+/**
+ * The `aventara` command line (R1, R2, Q16): `new <name>` and `init`, each
+ * question's flag from the wizard's table, and the options that are not
+ * questions. Unknown, misplaced or repeated arguments are refused in one
+ * sentence; a flag's VALUE is the question's to judge, because what is valid
+ * (`--db`'s providers) depends on the catalog and on earlier answers.
+ */
+export type ScaffoldCommandName = "new" | "init";
+export type ScaffoldCommand = {
+    readonly command: ScaffoldCommandName;
+    /** Raw answers by question, from flags and `new`'s positional `<name>`. */
+    readonly given: Readonly<Partial<Record<QuestionId, string>>>;
+    readonly skipInstall: boolean;
+    /** `new` only: passed through to `nest new` (Q16-7). */
+    readonly skipGit: boolean;
+    /** Accepts each unanswered question's default and confirms overwrites (R5). */
+    readonly yes: boolean;
+};
+export type CliCommand = {
+    readonly command: "help";
+} | {
+    readonly command: "version";
+} | ScaffoldCommand;
+/** The command line cannot be understood. A refusal: one sentence, exit 1. */
+export declare class CliCommandError extends Error {
+    readonly name = "CliCommandError";
+}
+export declare const USAGE: string;
+/** @throws CliCommandError when `argv` is not a command this CLI has. */
+export declare function parseCliCommand(argv: readonly string[]): CliCommand;

package/dist/command/command.parser.js

@@ -0,0 +1,138 @@
+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");
+}
+export const USAGE = `aventara — scaffold an Aventara server on NestJS.
+
+Usage:
+  aventara new <name> [options]   Create a NestJS project with Aventara (nest new, then init).
+${usageLines("new")}
+
+  aventara init [options]         Add Aventara to the NestJS 12 project in this directory.
+${usageLines("init")}
+
+  aventara --help                 Print this and exit 0.
+  aventara --version              Print this CLI's version and exit 0.
+
+On a terminal every unanswered question is asked; anywhere else, pass its flag
+or --yes, or the run stops before writing anything.
+`;
+/** @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}`);
+    }
+    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;