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

package/dist/apply/manifest.merger.js

@@ -0,0 +1,139 @@
+/**
+ * The merges `aventara init` makes into files a project already has —
+ * `package.json`, `.env`, `.gitignore`, `pnpm-workspace.yaml` — each answering
+ * the merged text and the **conflicts**: values already there that differ from
+ * what would be written (the `generateAt` rule's "content the tool did not
+ * produce"). A value already equal to what would be written is no change (P3);
+ * a conflict is replaced only once confirmed (`conflict.confirmer.ts`), so each
+ * merge is computed with conflicts both kept and replaced.
+ */
+function sorted(record) {
+    return Object.fromEntries(Object.entries(record).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+}
+/** `package.json`, in npm's own layout: two-space JSON, dependencies sorted. */
+export function mergePackageManifest(text, changes, replaceConflicts) {
+    const manifest = JSON.parse(text);
+    const conflicts = [];
+    for (const field of ["dependencies", "devDependencies"]) {
+        const current = {
+            ...(manifest[field] ?? {}),
+        };
+        for (const [name, version] of Object.entries(changes[field])) {
+            const existing = current[name];
+            if (existing !== undefined && existing !== version) {
+                conflicts.push(`package.json's ${field}["${name}"] (${existing})`);
+                if (!replaceConflicts) {
+                    continue;
+                }
+            }
+            current[name] = version;
+        }
+        manifest[field] = sorted(current);
+    }
+    const scripts = {
+        ...(manifest.scripts ?? {}),
+    };
+    for (const [name, command] of Object.entries(changes.scripts)) {
+        const existing = scripts[name];
+        if (existing !== undefined && existing !== command) {
+            conflicts.push(`package.json's scripts["${name}"]`);
+            if (!replaceConflicts) {
+                continue;
+            }
+        }
+        scripts[name] = command;
+    }
+    for (const [name, { from, to }] of Object.entries(changes.rewrites)) {
+        const existing = scripts[name];
+        if (existing === undefined || existing === to) {
+            continue;
+        }
+        if (existing !== from) {
+            conflicts.push(`package.json's scripts["${name}"]`);
+            if (!replaceConflicts) {
+                continue;
+            }
+        }
+        scripts[name] = to;
+    }
+    manifest.scripts = scripts;
+    return { text: `${JSON.stringify(manifest, null, 2)}\n`, conflicts };
+}
+const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
+function unquoted(value) {
+    const quote = value[0];
+    return (quote === '"' || quote === "'") && value.endsWith(quote)
+        ? value.slice(1, -1)
+        : value;
+}
+/** `.env`: a missing key is appended as `KEY="value"`, after a final newline (B5). */
+export function mergeEnvFile(text, entries, replaceConflicts) {
+    const lines = text === undefined || text === ""
+        ? []
+        : text.replace(/\n$/, "").split("\n");
+    const conflicts = [];
+    for (const [key, value] of Object.entries(entries)) {
+        const at = lines.findIndex((line) => ENV_LINE.exec(line)?.[1] === key);
+        const line = `${key}="${value}"`;
+        if (at === -1) {
+            lines.push(line);
+            continue;
+        }
+        const existing = unquoted(ENV_LINE.exec(lines[at])?.[2] ?? "");
+        if (existing === value) {
+            continue;
+        }
+        conflicts.push(`.env's ${key}`);
+        if (replaceConflicts) {
+            lines[at] = line;
+        }
+    }
+    return { text: `${lines.join("\n")}\n`, conflicts };
+}
+/** `.gitignore`: missing lines appended, nothing else touched. */
+export function mergeGitignore(text, additions) {
+    const lines = text === undefined || text === ""
+        ? []
+        : text.replace(/\n$/, "").split("\n");
+    const missing = additions.filter((line) => !lines.some((present) => present.trim() === line));
+    return {
+        text: missing.length === 0 && text !== undefined
+            ? text
+            : `${[...lines, ...missing].join("\n")}\n`,
+        conflicts: [],
+    };
+}
+/**
+ * `pnpm-workspace.yaml`'s `allowBuilds:` (B9: pnpm 12 refuses install scripts
+ * until they are allowed — what `pnpm approve-builds` writes). Keys missing
+ * under an existing `allowBuilds:` are added there; otherwise the block is
+ * appended.
+ */
+export function mergePnpmWorkspace(text, packages) {
+    const quoted = (name) => /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(name) ? name : `"${name}"`;
+    const lines = text === undefined || text === ""
+        ? []
+        : text.replace(/\n$/, "").split("\n");
+    const header = lines.findIndex((line) => /^allowBuilds:\s*$/.test(line));
+    const present = new Set();
+    if (header !== -1) {
+        for (let at = header + 1; at < lines.length && /^\s+\S/.test(lines[at]); at += 1) {
+            const name = /^\s+["']?([^"':]+)["']?\s*:/.exec(lines[at])?.[1];
+            if (name !== undefined) {
+                present.add(name);
+            }
+        }
+    }
+    const missing = packages.filter((name) => !present.has(name));
+    if (missing.length === 0 && text !== undefined) {
+        return { text, conflicts: [] };
+    }
+    const entries = missing.map((name) => `  ${quoted(name)}: true`);
+    if (header === -1) {
+        lines.push("allowBuilds:", ...entries);
+    }
+    else {
+        lines.splice(header + 1, 0, ...entries);
+    }
+    return { text: `${lines.join("\n")}\n`, conflicts: [] };
+}

package/dist/aventara.bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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, commandUsage, 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(command.topic === undefined ? USAGE : commandUsage(command.topic));
+            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,36 @@
+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 = 
+/** `--help`; with `topic`, `aventara <topic> --help` (pilot.1). */
+{
+    readonly command: "help";
+    readonly topic?: ScaffoldCommandName;
+} | {
+    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";
+}
+/** `aventara <command> --help` (pilot.1): that command's usage alone. */
+export declare function commandUsage(command: ScaffoldCommandName): string;
+export declare const USAGE: string;
+/** @throws CliCommandError when `argv` is not a command this CLI has. */
+export declare function parseCliCommand(argv: readonly string[]): CliCommand;