@aventara/cli 0.1.0-pilot.1 → 0.1.0-pilot.3

package/dist/run/init.orchestrator.js

@@ -9,7 +9,6 @@ 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";
 }
@@ -49,7 +48,6 @@ export async function runInit(command, io) {
         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 });
@@ -76,7 +74,6 @@ export async function runInit(command, io) {
     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,
@@ -101,7 +98,6 @@ async function prepareFresh(command, io, inspection, detectedPackageManager) {
         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 (;;) {
@@ -117,11 +113,6 @@ function installedVersion(directory, name) {
         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 ?? {}),
@@ -146,14 +137,11 @@ async function prepareReuse(command, io, inspection, detectedPackageManager) {
     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}`],
+        ["--orm", command.given.orm, entry.alias],
         ["--db", command.given.db, provider],
     ]) {
-        if (given !== undefined &&
-            given.trim().toLowerCase() !== found &&
-            !(flag === "--orm" && given.trim().toLowerCase() === entry.orm.family)) {
+        if (given !== undefined && given.trim().toLowerCase() !== found) {
             throw new ProjectRefusedError(`${flag} ${given} does not match this project, which already uses ${found}`);
         }
     }
@@ -181,7 +169,6 @@ async function prepareReuse(command, io, inspection, detectedPackageManager) {
         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"
@@ -190,7 +177,7 @@ async function prepareReuse(command, io, inspection, detectedPackageManager) {
         ...(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`,
+                `the ${entry.orm.label} client is generated into ${facts.clientOutput}, outside src/, which nest build does not compile; your build is your own, and init does not change it`,
             ]),
         ...(service.clientMember === undefined
             ? []

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

@@ -1,18 +1,17 @@
 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.
+ * `aventara new <name>`: 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
+ * — and, after the install, the project's first commit (`scaffold.committer.ts`,
+ * pilot.3).
  *
- * 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.
+ * Nest authors its own scaffold: the CLI never writes Nest's files. Its output is
+ * pinned by digest, 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. */

package/dist/run/new.orchestrator.js

@@ -6,21 +6,9 @@ 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). */
+import { commitScaffold, gitSurroundings } from "./scaffold.committer.js";
 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"]];
 }
@@ -47,8 +35,9 @@ export async function runNew(command, io) {
     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 surroundings = command.skipGit
+        ? undefined
+        : await gitSurroundings(io.runner, io.cwd);
     const [runner, prefix] = oneOff(packageManager);
     const args = [
         ...prefix,
@@ -73,16 +62,19 @@ export async function runNew(command, io) {
     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({
+    const initialized = await runInit({
         command: "init",
         given: {
-            orm: `${orm.orm.family}@${orm.orm.major}`,
+            orm: orm.alias,
             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}`] });
+    if (initialized === 0 && surroundings !== undefined) {
+        io.stdout(`aventara: ${await commitScaffold(io.runner, directory, surroundings, io.cwd)}.\n`);
+    }
+    return initialized;
 }

package/dist/run/scaffold.committer.d.ts

@@ -0,0 +1,28 @@
+import type { CommandRunner } from "./command.runner.js";
+/**
+ * pilot.3 — `aventara new` ends with one commit of the whole scaffold, the
+ * install's lockfile included, under one fixed message. `.env` is not in it: the
+ * scaffold's `.gitignore` lists it (Nest's own does too). `init` never commits:
+ * the project is the developer's.
+ *
+ * Never a failure: where a commit cannot or should not be made, one line says why
+ * and the run still succeeds —
+ * - git is not installed;
+ * - the directory `new` ran in is inside a git work tree already (a monorepo): the
+ *   project belongs to that repository, and gets no commit of its own;
+ * - git has no `user.name` and `user.email` to commit as. `--skip-git` (passed to
+ *   `nest new`, which then initializes no repository) makes no commit and says
+ *   nothing.
+ *
+ * git runs through the one process seam, `CommandRunner`.
+ */
+export declare const INITIAL_COMMIT_MESSAGE = "Initial Aventara Scaffold";
+/** Where `new` runs, as git sees it — read BEFORE `nest new` initializes a repository. */
+export type GitSurroundings = "no-git" | "inside-work-tree" | "outside";
+/** Whether git is installed, and whether `directory` lies in a work tree. */
+export declare function gitSurroundings(runner: CommandRunner, directory: string): Promise<GitSurroundings>;
+/**
+ * Commits the project in `directory` as its first commit, or says why not: the
+ * line to print, without the `aventara: ` prefix or the final period.
+ */
+export declare function commitScaffold(runner: CommandRunner, directory: string, surroundings: GitSurroundings, enclosing: string): Promise<string>;

package/dist/run/scaffold.committer.js

@@ -0,0 +1,53 @@
+import { realpathSync } from "node:fs";
+export const INITIAL_COMMIT_MESSAGE = "Initial Aventara Scaffold";
+function isMissingCommand(error) {
+    return (error instanceof Error &&
+        error.code === "ENOENT");
+}
+export async function gitSurroundings(runner, directory) {
+    try {
+        const answered = await runner("git", ["rev-parse", "--is-inside-work-tree"], { cwd: directory });
+        return answered.code === 0 && answered.stdout.trim() === "true"
+            ? "inside-work-tree"
+            : "outside";
+    }
+    catch (error) {
+        if (isMissingCommand(error)) {
+            return "no-git";
+        }
+        throw error;
+    }
+}
+export async function commitScaffold(runner, directory, surroundings, enclosing) {
+    if (surroundings === "no-git") {
+        return "no initial commit: git is not installed";
+    }
+    if (surroundings === "inside-work-tree") {
+        return `no initial commit: ${enclosing} is inside a git repository already; commit the project there`;
+    }
+    const git = (args) => runner("git", args, { cwd: directory });
+    for (const key of ["user.name", "user.email"]) {
+        const set = await git(["config", key]);
+        if (set.code !== 0 || set.stdout.trim() === "") {
+            return "no initial commit: git has no user.name and user.email set; set them, then commit the project yourself";
+        }
+    }
+    const top = await git(["rev-parse", "--show-toplevel"]);
+    if (top.code !== 0 ||
+        realpathSync(top.stdout.trim()) !== realpathSync(directory)) {
+        const initialized = await git(["init", "-q"]);
+        if (initialized.code !== 0) {
+            return `no initial commit: \`git init\` exited with code ${initialized.code}: ${initialized.stderr.trim()}`;
+        }
+    }
+    for (const args of [
+        ["add", "-A"],
+        ["commit", "-q", "-m", INITIAL_COMMIT_MESSAGE],
+    ]) {
+        const ran = await git(args);
+        if (ran.code !== 0) {
+            return `no initial commit: \`git ${args.join(" ")}\` exited with code ${ran.code}: ${ran.stderr.trim()}`;
+        }
+    }
+    return `committed the scaffold: "${INITIAL_COMMIT_MESSAGE}"`;
+}

package/dist/templates/docs.links.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where the public documentation lives: the one base every link the scaffold
+ * writes into a project starts from. A placeholder until the docs domain is
+ * settled; changing it changes only comments in the files the CLI writes.
+ */
+export declare const DOCS_BASE_URL = "https://<docs-domain>";
+/** The documentation's rate-limiting section, linked from the scaffold's `main.ts`. */
+export declare const RATE_LIMITING_DOCS = "https://<docs-domain>/docs/limits-and-safety#rate-limiting";

package/dist/templates/docs.links.js

@@ -0,0 +1,2 @@
+export const DOCS_BASE_URL = "https://<docs-domain>";
+export const RATE_LIMITING_DOCS = `${DOCS_BASE_URL}/docs/limits-and-safety#rate-limiting`;

package/dist/templates/prisma7/prisma7.templates.js

@@ -2,21 +2,8 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { lowestVersionOf } from "../../catalog/range.reader.js";
 import { SCAFFOLD_ENTRYPOINT, } from "../template.registry.js";
-/**
- * The `prisma7` entry's templates (D7): Prisma 7 knowledge as text the CLI
- * writes and reads, keyed by the providers `@aventara/prisma7-adapter`
- * declares. Every value that is an adapter fact — the ORM package, the driver
- * per provider, the generator, the generate bin, the version floor — is read
- * from the catalog entry handed in, not restated here.
- *
- * The texts follow the Nest scaffold's formatting (prettier, `singleQuote`,
- * `trailingComma: "all"`, B1), so the project's own `format` script leaves them
- * as they are.
- */
-/** The generated client goes under `src`, where `nest build` compiles it (B6). */
 const CLIENT_OUTPUT = "src/generated/prisma";
 const SCHEMA = "prisma/schema.prisma";
-/** B5: the Prisma CLI loads either name, and `prisma7.config.ts` wins when both exist. */
 const CONFIG_FILES = ["prisma7.config.ts", "prisma.config.ts"];
 const DRIVER_PREFIX = "@prisma/adapter-";
 const NEW_SERVICE = {
@@ -33,19 +20,16 @@ const PROVIDERS = {
         driverOptions: "{ url }",
         databaseUrl: "file:./dev.db",
         gitignore: ["/dev.db*"],
-        // B9: pnpm 12 refuses these install scripts until they are allowed.
         nativeBuilds: ["@prisma/engines", "better-sqlite3", "prisma"],
     },
     postgresql: {
         driverClass: "PrismaPg",
         driverOptions: "{ connectionString: url }",
-        // `prisma init`'s own placeholder (B5); printed in the next steps, never asked (Q16-8).
         databaseUrl: "postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public",
         gitignore: [],
         nativeBuilds: ["@prisma/engines", "prisma"],
     },
 };
-/** A relative import specifier from `from` (a project file) to `to` (a project path, no extension). */
 function specifier(from, to, js) {
     const relative = path.posix.relative(path.posix.dirname(from), to);
     return `${relative.startsWith(".") ? relative : `./${relative}`}${js}`;
@@ -62,7 +46,6 @@ function schema(input) {
         `  provider = "${input.provider}"`,
         "}",
         "",
-        // R12: Prisma's `--with-model` starter (B5).
         "model User {",
         "  id    Int     @id @default(autoincrement())",
         "  email String  @unique",
@@ -71,7 +54,6 @@ function schema(input) {
         "",
     ].join("\n");
 }
-/** `prisma.config.ts` (Q16-19). Prisma does not load `.env` itself (B5). */
 function prismaConfig() {
     return [
         "import { existsSync } from 'node:fs';",
@@ -94,7 +76,6 @@ function prismaConfig() {
         "",
     ].join("\n");
 }
-/** The developer-owned service (P2: `extends PrismaClient`, so `client: prisma`). */
 function prismaService(input) {
     const provider = PROVIDERS[input.provider];
     const driver = input.entry.drivers[input.provider];
@@ -126,7 +107,6 @@ function prismaService(input) {
         "",
     ].join("\n");
 }
-/** `src/aventara.config.ts` (R8, Q16-17): the framework's configuration. */
 function aventaraConfig(input) {
     const file = "src/aventara.config.ts";
     const service = input.service.exportName;
@@ -222,7 +202,6 @@ function scaffold(input) {
         ],
         env: { DATABASE_URL: provider.databaseUrl },
         gitignore: ["/src/generated/", ...provider.gitignore],
-        // D1, D9: exactly the version floor the adapter declares; never bare `prisma`.
         dependencies: { [input.entry.orm.package]: floor, [driver]: floor },
         devDependencies: { prisma: floor },
         prepare: prepare({
@@ -270,7 +249,6 @@ function reuse(input) {
                 }),
             },
         ],
-        // R6: the developer's Prisma files, `.env` key and versions are theirs.
         env: {},
         gitignore: [`/${path.posix.dirname(input.artifact)}/`],
         dependencies: {},
@@ -287,9 +265,6 @@ function reuse(input) {
         nextSteps: [],
     };
 }
-/* ------------------------------------------------------------------ *
- * Reading an existing Prisma 7 setup (R6)                              *
- * ------------------------------------------------------------------ */
 function schemaLocation(directory, manifest) {
     for (const config of CONFIG_FILES) {
         const file = path.join(directory, config);
@@ -305,7 +280,6 @@ function schemaLocation(directory, manifest) {
         ? path.posix.normalize(prisma.schema)
         : SCHEMA;
 }
-/** The `.prisma` files of a schema path: the file, or every file in a schema folder. */
 function schemaFiles(directory, schemaPath) {
     const full = path.join(directory, schemaPath);
     if (!existsSync(full)) {
@@ -343,7 +317,6 @@ function readProject(directory, manifest) {
         for (const block of blocks(text, "generator")) {
             const declared = setting(block, "provider");
             const output = setting(block, "output");
-            // The client generator, not a second generator (a zod or docs one) beside it.
             if (generator === undefined || /^prisma-client/.test(declared ?? "")) {
                 generator = declared;
                 clientOutput =

package/dist/templates/template.registry.d.ts

@@ -3,14 +3,11 @@ import type { CatalogEntry, EntryId, ProviderOf } from "../catalog/catalog-entry
 import type { ClientShape, ExportReference } from "../project/service.detector.js";
 import type { PackageManager } from "../wizard/wizard.questions.js";
 /**
- * D7 — what the CLI writes for an ORM lives here as text, keyed by catalog id;
- * the adapter itself runs only through its bin.
- *
  * The registry is **total** in both directions, and both are checked before a
  * project is ever scaffolded:
- * - at compile time, over the generated catalog's literal type: an entry with
- *   no template set, or a template set missing a provider its adapter declares,
- *   does not type-check;
+ * - at compile time, over the generated catalog's literal type: an entry with no
+ *   template set, or a template set missing a provider its adapter declares, does
+ *   not type-check;
  * - at build time, by the catalog generator: a templates directory with no
  *   adapter, or an adapter with no templates directory, fails the build.
  */
@@ -20,11 +17,11 @@ export type ProviderTemplate = {
     readonly driverClass: string;
     /** The driver class's constructor argument, given the connection string as `url`. */
     readonly driverOptions: string;
-    /** The `DATABASE_URL` line's value; a placeholder where it cannot be known (Q16-8). */
+    /** The `DATABASE_URL` line's value; a placeholder where it cannot be known. */
     readonly databaseUrl: string;
     /** `.gitignore` lines this provider's files need (a SQLite database file). */
     readonly gitignore: readonly string[];
-    /** Packages whose install scripts pnpm must be allowed to run (B9). */
+    /** Packages whose install scripts pnpm must be allowed to run. */
     readonly nativeBuilds: readonly string[];
 };
 export type ModuleKind = "esm" | "cjs";
@@ -48,7 +45,7 @@ export type ScaffoldInput = {
  * `aventara:prepare` and `postinstall` script names) is the planner's.
  */
 export type OrmScaffold = {
-    /** New, developer-owned files (§4.3). */
+    /** New, developer-owned files. */
     readonly files: readonly {
         readonly path: string;
         readonly content: string;
@@ -58,7 +55,7 @@ export type OrmScaffold = {
     readonly gitignore: readonly string[];
     readonly dependencies: Readonly<Record<string, string>>;
     readonly devDependencies: Readonly<Record<string, string>>;
-    /** The command `aventara:prepare` runs (D7: the adapter only through its bin). */
+    /** The command `aventara:prepare` runs. */
     readonly prepare: string;
     /** What the anchored `app.module.ts` edit adds: import lines, and `imports:` entries. */
     readonly appModule: {
@@ -66,13 +63,13 @@ export type OrmScaffold = {
         readonly entries: readonly string[];
     };
     readonly nativeBuilds: readonly string[];
-    /** The ORM's next steps, after the install and before the server starts (R11). */
+    /** The ORM's next steps, after the install and before the server starts. */
     readonly nextSteps: readonly string[];
 };
 /**
- * What a project's existing ORM setup states, read by the entry's templates
- * (R6) — the ORM's own file layout is template knowledge (D7); judging it
- * against the catalog is the matcher's (`catalog.matcher.ts`).
+ * What a project's existing ORM setup states, read by the entry's templates — the
+ * ORM's own file layout is template knowledge; judging it against the catalog is
+ * the matcher's (`catalog.matcher.ts`).
  */
 export type OrmProjectFacts = {
     /** The schema the generate step reads, relative to the project root. */
@@ -84,7 +81,7 @@ export type OrmProjectFacts = {
     /** The driver-adapter packages the project depends on. */
     readonly drivers: readonly string[];
 };
-/** Reusing a project's ORM setup (R6): its schema, its output, its service. */
+/** Reusing a project's ORM setup: its schema, its output, its service. */
 export type ReuseInput = {
     readonly entry: CatalogEntry;
     readonly facts: OrmProjectFacts & {
@@ -107,7 +104,6 @@ export type TemplateSet<I extends EntryId> = {
     readonly providers: {
         readonly [P in ProviderOf<I>]: ProviderTemplate;
     };
-    /** A project with no ORM: everything §4.3 lists. */
     readonly scaffold: (input: ScaffoldInput) => OrmScaffold;
     /** Reads an existing setup's facts; `undefined` when there is none to read. */
     readonly readProject: (directory: string, manifest: PackageManifest) => OrmProjectFacts;
@@ -118,7 +114,7 @@ export type TemplateSet<I extends EntryId> = {
         readonly service: ExportReference;
         readonly module: ExportReference;
     };
-    /** A project with the ORM already set up: no ORM file written or edited (R6). */
+    /** A project with the ORM already set up: no ORM file written or edited. */
     readonly reuse: (input: ReuseInput) => OrmScaffold;
 };
 export type TemplateRegistry = {

package/dist/templates/template.registry.js

@@ -1,13 +1,8 @@
 import { PRISMA7_TEMPLATES } from "./prisma7/prisma7.templates.js";
-/**
- * The entrypoint every scaffold mounts the protocol at: written into
- * `src/aventara.config.ts`, and tested by the e2e spec (pilot.1).
- */
 export const SCAFFOLD_ENTRYPOINT = "/api";
 export const TEMPLATE_REGISTRY = {
     prisma7: PRISMA7_TEMPLATES,
 };
-/** The template set for `entry` — every catalog entry has one (checked at build). */
 export function templatesFor(entry) {
     const set = TEMPLATE_REGISTRY[entry.id];
     if (set === undefined) {

package/dist/wizard/answer.resolver.d.ts

@@ -1,26 +1,24 @@
 import type { AnyWizardQuestion, QuestionId, WizardAnswers, WizardContext } from "./wizard.questions.js";
 /**
- * R5 — how each question gets its answer, in this order:
- *
  * 1. **its flag**, validated by the question (a bad value is refused, never
  *    re-asked);
- * 2. **the only choice there is** (N3): shown on a terminal with no keypress;
+ * 2. **the only choice there is**: shown on a terminal with no keypress;
  * 3. **`--yes`**: the question's default, when it has one;
  * 4. **the prompt**, when someone can answer (stdin is a terminal);
  * 5. otherwise the question is **unanswered**, and once every question has been
  *    tried the run refuses in one sentence naming exactly those flags.
  *
  * `--yes` comes before the prompt because it means "accept each unanswered
- * question's default" (R5 + R2), on a terminal as much as anywhere; a question
- * with no default (`new`'s `<name>`) is still asked on a terminal.
+ * question's default", on a terminal as much as anywhere; a question with no
+ * default (`new`'s `<name>`) is still asked on a terminal.
  */
-/** The seam to a person (B26): `node:readline/promises` on a terminal, a script in specs. */
+/** The seam to a person: `node:readline/promises` on a terminal, a script in specs. */
 export type Prompter = {
     /** Whether someone can answer: stdin is a terminal. */
     readonly interactive: boolean;
     /** Asks once; resolves with what was typed, `""` for Enter alone. */
     readonly ask: (request: PromptRequest) => Promise<string>;
-    /** Says one line without asking (N3, and why an answer was not accepted). */
+    /** Says one line without asking. */
     readonly say: (line: string) => void;
 };
 export type PromptRequest = {

package/dist/wizard/answer.resolver.js

@@ -1,9 +1,7 @@
 import { WizardAnswerError } from "./wizard.questions.js";
-/** Nobody can answer and some questions are unanswered. A refusal: one sentence. */
 export class UnansweredQuestionsError extends Error {
     name = "UnansweredQuestionsError";
 }
-/** `--db <sqlite|postgresql>`, or `<name>` for the positional. */
 function flagSpelling(question, context) {
     if (!question.flag.startsWith("--")) {
         return question.flag;
@@ -18,7 +16,6 @@ function listed(items) {
         ? items.join("")
         : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
 }
-/** The refusal sentence: the unanswered flags, exactly, and `--yes` for those with a default. */
 function unansweredSentence(missing, yes) {
     const defaulted = missing.filter((item) => item.defaulted);
     const yesClause = !yes && defaulted.length > 0
@@ -51,12 +48,6 @@ async function prompt(question, context, prompter) {
         }
     }
 }
-/**
- * Settles `questions` in order, each later question seeing the earlier answers.
- *
- * @throws WizardAnswerError when a flag's value is not an answer.
- * @throws UnansweredQuestionsError when nobody can answer and something is unanswered.
- */
 export async function resolveAnswers(questions, sources) {
     const answered = {};
     const missing = [];
@@ -65,7 +56,6 @@ export async function resolveAnswers(questions, sources) {
             ...sources.context,
             answered: answered,
         };
-        // A question that depends on one left unanswered cannot be asked yet.
         if (question.after !== undefined &&
             answered[question.after] === undefined) {
             missing.push({ spelling: question.flag, defaulted: false });

package/dist/wizard/readline.prompter.d.ts

@@ -1,13 +1,11 @@
 import type { Readable, Writable } from "node:stream";
 import type { Prompter } from "./answer.resolver.js";
 /**
- * P6, B26 — the {@link Prompter} over `node:readline`: no prompt dependency.
- *
- * Lines are **queued** as they arrive and handed to questions in order. A
- * terminal delivers whatever was typed ahead of a question — and a script piping
- * answers into a pseudo-terminal delivers them all at once — and readline drops
- * a line nobody is waiting for. Measured: with `readline/promises`' `question`,
- * three answers piped into `script(1)` reached the first question only.
+ * Lines are **queued** as they arrive and handed to questions in order. A terminal
+ * delivers whatever was typed ahead of a question — and a script piping answers
+ * into a pseudo-terminal delivers them all at once — and readline drops a line
+ * nobody is waiting for. Measured: with `readline/promises`' `question`, three
+ * answers piped into `script(1)` reached the first question only.
  */
 /** Input ended while a question was open: the person closed the wizard. A refusal. */
 export declare class WizardCancelledError extends Error {

package/dist/wizard/readline.prompter.js

@@ -1,14 +1,4 @@
 import { createInterface } from "node:readline";
-/**
- * P6, B26 — the {@link Prompter} over `node:readline`: no prompt dependency.
- *
- * Lines are **queued** as they arrive and handed to questions in order. A
- * terminal delivers whatever was typed ahead of a question — and a script piping
- * answers into a pseudo-terminal delivers them all at once — and readline drops
- * a line nobody is waiting for. Measured: with `readline/promises`' `question`,
- * three answers piped into `script(1)` reached the first question only.
- */
-/** Input ended while a question was open: the person closed the wizard. A refusal. */
 export class WizardCancelledError extends Error {
     name = "WizardCancelledError";
 }