@arc-e-tect/api-only-publisher 0.6.1 → 0.7.0

package/README.adoc

@@ -6,7 +6,7 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.6.1
+:api-only-publisher-version: 0.7.0
 
 image:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml/badge.svg[Vulnerability Scan,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml]
 image:https://img.shields.io/npm/v/@arc-e-tect/api-only-publisher[npm,link=https://www.npmjs.com/package/@arc-e-tect/api-only-publisher]
@@ -42,6 +42,8 @@ It is the producer half of a pair.
 The consumer half, the link:../api-only-subscriber/README.adoc[API-Only Subscriber →], fetches a published document into an implementation project and verifies that it has not drifted.
 The two are coupled only by the published artifact and its manifest; neither knows anything else about the other.
 
+The link:../api-only-transcriberj/README.adoc[API-Only TranscriberJ →] builds on what the Subscriber fetched: it generates Java classes for contract tests from the published document, named after the fragments the Publisher stamps into it with `x-fragment-path`.
+
 A *target* is whatever gets its own contract document: a microservice, a modular monolith, a backend-for-frontend, or a documentation aggregate spanning all of them.
 It need not be a deployable, which is why this is not called `services`.
 
@@ -136,8 +138,9 @@ However the Publisher itself is started, it fetches them with `npx`, at the vers
 |===
 |Command |Purpose
 
-|`init [dir] [--force]`
-|Scaffold `apionly.yaml` and a reference directory layout that builds as it stands.
+|`init [dir] [--yes] [--force] [value flags]`
+|Scaffold `apionly.yaml` and a reference directory layout that builds as it stands: OpenAPI, AsyncAPI or both.
+At a terminal it asks for each value first, as <<init,Scaffolding a library §>> describes.
 
 |`build [--target <t>]... [--pre-release <ids>] [--openapi\|--asyncapi]`
 |Stage, substitute placeholders, bundle, stamp each published target's version, and lint.
@@ -178,6 +181,101 @@ npm run apionly -- publish --target orders --pre-release rc.1
 npm run apionly -- changed --since origin/main --quiet
 ----
 
+[#init]
+== Scaffolding a library
+
+`init` writes a library that builds, lints and publishes as it stands, from a handful of values: which kinds of document it holds, its target's name, the API's title and so on.
+
+[source,console,subs="attributes+"]
+----
+npx @arc-e-tect/api-only-publisher@{api-only-publisher-version} init my-api-library
+----
+
+At a terminal it asks for each value, showing the default in brackets; Enter takes it.
+An answer that would break the build later is refused, and the question asked again.
+
+[source,text]
+----
+Kinds of document: openapi, asyncapi or both [openapi]: both
+Target name [example-service]: Customer_Orders
+'Customer_Orders' is not a target name: use lowercase letters and digits, in words joined by single hyphens, starting with a letter, such as customer-orders
+Target name [example-service]: customer-orders
+API title [Example API]: Customer Orders API
+Initial contract version [0.1.0]:
+...
+----
+
+Where nobody is watching -- no terminal, as in CI, a script or an AI assistant -- it asks nothing and takes the defaults, as it always has.
+`--yes` (or `-y`) does the same at a terminal.
+
+[cols="2,2,3", options="header"]
+|===
+|Question |Flag |Default, and what is accepted
+
+|Kinds of document
+|`--openapi`, `--asyncapi`; both flags for both
+|`openapi`. The library's trees and targets follow from it.
+
+|Target name
+|`--target <name>`
+|`example-service`. Lowercase kebab-case: a lowercase letter first, then lowercase letters and digits, in words joined by single hyphens -- `orders`, `customer-orders`, `orders-v2`.
+The name becomes file names, a properties key, a Maven artifactId, a git tag and, through the Subscriber, a Gradle task name, which treats `-`, `_` and `.` alike; one separator keeps two targets from claiming one task.
+
+|API title
+|`--title <text>`
+|`Example API`. Any text.
+
+|Initial contract version
+|`--contract-version <version>`
+|`0.1.0`. A semantic release version, not a pre-release: it goes in the target's version file.
+
+|Contact name
+|`--contact-name <text>`
+|`Example Team`.
+
+|Contact URL
+|`--contact-url <url>`
+|`https://example.invalid`. An http or https URL.
+
+|Licence
+|`--license <spdx-id>`
+|`Apache-2.0`. An SPDX identifier; the URL of a well-known licence follows from it.
+
+|Licence URL
+|`--license-url <url>`
+|Asked only for a licence whose URL the tool does not know, and then required.
+
+|Production server URL
+|`--server-url <url>`
+|`https://api.example.invalid`. Asked only for a library with OpenAPI.
+
+|Broker host
+|`--broker-host <host[:port]>`
+|`kafka:9092`. Asked only for a library with AsyncAPI.
+|===
+
+A flag always wins: its question is not asked, and an invalid value, or a flag for a kind the library does not hold, stops `init` before it writes anything.
+
+What each kind of library gets::
+* *OpenAPI*: the OpenAPI tree under `specs/openapi/`, its target, and `.redocly.yaml`, the lint rules Redocly applies.
+`apionly.yaml` holds no `asyncapi` keys.
+* *AsyncAPI*: the AsyncAPI tree under `specs/asyncapi/` -- a channel, a message and its payload -- and its target.
+`apionly.yaml` holds no `openapi` keys, and there is no `.redocly.yaml` or Redocly pin: an AsyncAPI document is bundled and validated with the AsyncAPI CLI alone.
+* *Both*: both trees, one target building both documents, and one schema they share: `specs/openapi/components/common/schemas/ExampleIdV1.yaml`, which the HTTP response and the event payload both refer to.
+That is the library's convention in miniature -- a definition used by both protocols is one fragment -- and why the whole source root is staged together (<<what-build-does,What `build` does §>>).
+
+What it reports::
+`init` never overwrites what is there unless told to, and says for every file what it did:
++
+[horizontal]
+`created`:: The file was not there, and is now.
+`identical`:: The file was there, and matches what `init` would write, ignoring line endings and final newlines.
+`differs`:: The file was there, and does not match: where the library has diverged from the scaffold, usually on purpose.
+It is left alone.
+`overwrote`:: The file differed, and `--force` replaced it.
++
+At a terminal, `--force` first lists the files that differ and asks once whether to overwrite them; without a terminal, or with `--yes`, it overwrites them without asking.
+
 [#what-build-does]
 == What `build` does
 
@@ -199,6 +297,7 @@ An OpenAPI document's components each carry the path of the fragment they came f
 A `publish: false` target keeps the version its source declares.
 
 . **Lint** the finished document, so a broken fragment surfaces against the target it actually affects.
+`build` prints the linter's output only when the lint fails, and writes no report; to see warnings, and to write each document's report under `reports.lint`, run `lint`.
 
 [#versions]
 == Versions
@@ -295,7 +394,7 @@ Declare the members and the aggregate's own identity:
 portfolio:
   publish: false
   asyncapi:
-    bundle: portfolio_asyncapi_structure.yaml
+    bundle: bundles/portfolio_asyncapi_structure.yaml
     aggregate:
       - orders
       - payments
@@ -369,20 +468,25 @@ Adapting the tool to another project means editing configuration.
 
 [source,yaml]
 ----
+# The version of this file's own format -- which keys apionly.yaml has and what
+# they mean -- not of any API. This Publisher understands 1, and refuses others.
 schemaVersion: 1
 
 sources:
   root: specs          # staged wholesale; the kinds share fragments
-  openapi: openapi
+  openapi: openapi     # each kind's directory under root; bundle paths start here
   asyncapi: asyncapi
 
 defaults:
   openapi:
     lint: .redocly.yaml
+    # The file name of every built OpenAPI document: build/dist/<target>/openapi.yaml.
+    # The Subscriber looks for exactly this name.
     outputName: openapi.yaml
     fragmentPaths: true  # x-fragment-path on every component; the default
   asyncapi:
-    outputName: asyncapi.yaml
+    outputName: asyncapi.yaml  # as for OpenAPI: build/dist/<target>/asyncapi.yaml
+    fragmentPaths: true  # x-fragment-path on every fragment; the default
   placeholders:
     strict: true       # an unresolved {{token}} fails the build
 
@@ -408,17 +512,36 @@ targets:
     # versionFile: versions/orders.properties
     #              default: orders.bundle.properties beside the first bundle root
     openapi:
-      bundle: bundles/orders.yaml
+      # The bundle root the document is built from, relative to specs/openapi/.
+      # It is built into build/dist/orders/openapi.yaml, named by outputName.
+      bundle: bundles/orders_openapi_structure.yaml
     asyncapi:
-      bundle: orders_asyncapi.yaml
+      # Relative to specs/asyncapi/; built into build/dist/orders/asyncapi.yaml.
+      bundle: bundles/orders_asyncapi_structure.yaml
   portfolio:
     publish: false     # built and linted, never published
     openapi:
-      bundle: bundles/portfolio.yaml
+      bundle: bundles/portfolio_openapi_structure.yaml
 ----
 
 `targets` is the single source of truth for what gets built.
 
+A target's `bundle` and a kind's `outputName` are the two ends of one build: the bundle root is what a document is built *from*, in the library, and `outputName` is what it is built *to*, in `<build.dist>/<target>/`.
+Every target's document of one kind has the same `outputName`; keep the defaults, `openapi.yaml` and `asyncapi.yaml`, because the Subscriber looks for exactly those names.
+
+[#bundle-roots]
+=== Where bundle roots go
+
+Put every bundle root in a `bundles/` directory of its kind's source directory, named `<target>_<kind>_structure.yaml`: `specs/openapi/bundles/orders_openapi_structure.yaml` and `specs/asyncapi/bundles/orders_asyncapi_structure.yaml`.
+The `init` scaffold lays out its bundle roots this way, for each kind it writes.
+
+* A bundle root is a table of contents rather than a fragment, and a `bundles/` directory keeps the two apart.
+* The name says which target and which kind, so the two roots of one target are never confused, in the tree or in a review.
+* The version file's default place is beside the target's first bundle root (<<versions,Versions §>>), so it lands in `bundles/` too.
+
+The Publisher does not require it: a bundle path is any path relative to the kind's source directory.
+A bundle root moved into or out of `bundles/` needs its relative `$ref`s adjusted by one `../`, since they resolve against the file's own directory; the built document is otherwise the same.
+
 [#pinning-the-bundlers]
 === Pinning the bundlers
 
@@ -463,6 +586,11 @@ Any other YAML file under the source root counts.
 [#version-stamping]
 === Version stamping edits one scalar
 
+Stamping sets `info.version` in the *built* document, `<build.dist>/<target>/<outputName>`, after bundling.
+The value it replaces comes from the bundle root's `info` block, written in the bundle root or `$ref`'d from a fragment, which the bundler puts into the document: every bundle root therefore needs an `info` block with a `version`, conventionally `0.0.0`.
+The `init` scaffold's bundle root refers to `specs/openapi/shared/info.yaml`, which declares `version: 0.0.0`.
+The version that replaces it is the target's version file's (<<versions,Versions §>>).
+
 `info.version` is located structurally and that one scalar is spliced.
 It is deliberately not a re-serialisation: re-emitting a document reformats everything around the edit, because the AsyncAPI CLI wraps long descriptions at a width no YAML emitter reproduces.
 Splicing keeps every other byte exactly as the bundler wrote it.
@@ -492,12 +620,14 @@ It is how the API-Only TranscriberJ ties generated code to the fragment it came
 It is on by default, for both specification kinds.
 `defaults.openapi.fragmentPaths: false` and `defaults.asyncapi.fragmentPaths: false` turn it off, each for its own kind.
 
-How it is done::
+How it is done, for OpenAPI::
 The bundler is not told anything; it is shown stamped fragments, in copies of the staged tree under `<build.staging>/fragment-paths/<target>/`.
 The first bundle is built with every fragment stamped, to learn which fragments become components.
 The second, the one that is published, is built with only those stamped.
 So a document differs from one built with `fragmentPaths: false` by exactly one line per component, and in no other byte.
 The cost is a second bundler run per OpenAPI target.
++
+An AsyncAPI target is stamped differently, in one run and with every fragment stamped, because its bundler inlines rather than hoists: <<fragment-paths-asyncapi,AsyncAPI, where the bundler inlines rather than hoists §>> describes it.
 
 What stops the build::
 A fragment that writes `x-fragment-path` itself: the Publisher sets that key and nothing else may.
@@ -540,7 +670,9 @@ A stamp in the built document that names no file in the library, which would mea
 [#fragment-path-versions]
 ==== What a change to `x-fragment-path` means for a contract's version
 
-Semantic versioning describes the contract, so the version follows from what a change does to the contract's promises:
+Semantic versioning describes the contract, so the version follows from what a change does to the contract's promises.
+The Publisher does not decide it: it stamps whatever the target's version file declares.
+Choosing the next version is the API designer's responsibility, and this table is their guideline:
 
 [cols="2,1,3", options="header"]
 |===
@@ -594,11 +726,11 @@ In order of what usually needs changing:
 |The lint rules
 |`defaults.openapi.lint`
 
-|Whether components carry `x-fragment-path`
-|`defaults.openapi.fragmentPaths`, defaulting to `true`
+|Whether built documents carry `x-fragment-path`
+|`defaults.openapi.fragmentPaths` and `defaults.asyncapi.fragmentPaths`, each defaulting to `true`
 
 |Where lint reports go
-|`reports.lint`, defaulting to `build/reports/lint/<target>/<kind>.txt`
+|`reports.lint`, a directory, defaulting to `build/reports/lint`: each document's report is `<target>/<kind>.txt` in it, beside `unreferenced.txt`
 
 |Where built documents go
 |`build.dist`
@@ -623,6 +755,14 @@ A library with no `{{token}}` anywhere simply has nothing substituted.
 The tool does not police them.
 `changed` tells a release which targets a commit altered, and every manifest records the closure hash of what was published, so the hooks a diff gate would need already exist, but the gate itself is deliberately not built.
 
+[IMPORTANT]
+.The API designer defines the contract's version, not the Publisher
+====
+The Publisher reads a target's version from its version file and stamps it; it refuses a version that is not a semantic release version, and nothing else.
+It never works out a version from what changed, and never checks that a version matches the change.
+Whether a change is major, minor or patch is the API designer's decision, and so is its consequence: raising the version in the target's version file.
+====
+
 A breaking change is declared where it is made: the major version in the target's version file changes in the same commit as the fragments it breaks.
 A specification library should write down its own policy for what counts as breaking.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/cli.js

@@ -5,7 +5,8 @@ const path = require("path");
 
 const { loadFrom, ConfigError } = require("./config");
 const { build, prepare, BuildError } = require("./pipeline");
-const { init } = require("./init");
+const { init, scaffold, plan } = require("./init");
+const { resolveValues } = require("./init-questions");
 const { PlaceholderError } = require("./placeholders");
 const { VersionError } = require("./version");
 const { forTargets, ClosureError } = require("./closure");
@@ -20,7 +21,11 @@ const { unreferenced } = require("./unreferenced");
 const USAGE = `api-only-publisher -- build and distribute API description documents
 
 Usage:
-  api-only-publisher init [dir] [--force]
+  api-only-publisher init [dir] [--yes] [--force] [--openapi] [--asyncapi] [--target <name>]
+                          [--title <text>] [--contract-version <version>]
+                          [--contact-name <text>] [--contact-url <url>]
+                          [--license <spdx-id>] [--license-url <url>]
+                          [--server-url <url>] [--broker-host <host[:port]>]
   api-only-publisher build [--target <name>]... [--pre-release <ids>] [--openapi|--asyncapi]
   api-only-publisher lint  [--target <name>]...
   api-only-publisher targets
@@ -37,7 +42,16 @@ Options:
                     rc.1, to each target's version.
   --openapi         Only build OpenAPI documents.
   --asyncapi        Only build AsyncAPI documents.
-  --force           init only: overwrite files that already exist.
+  --force           init only: overwrite files that differ from the scaffold;
+                    at a terminal, after listing them and asking once.
+  -y, --yes         init only: ask nothing, even at a terminal; take the defaults
+                    for every value no flag gives. Without a terminal, init never asks.
+  --openapi, --asyncapi
+                    init: the kinds of document the library holds; both flags for both.
+  --target <name>   init: the target's name, in lowercase kebab-case.
+  --title, --contract-version, --contact-name, --contact-url, --license,
+  --license-url, --server-url, --broker-host
+                    init only: the value of that question; a flag always wins.
   --since <ref>     changed only: the git ref to compare the working tree against.
   --out <dir>       pack/publish/split: where to write.
   --channel <name>  publish only: repeat for several. Default: every configured channel.
@@ -55,6 +69,12 @@ function parseArgs(argv) {
     const options = {
         targets: [], kinds: null, preRelease: null, quiet: false, force: false,
         dir: process.cwd(), since: null, out: null, channels: null, by: "kind",
+        yes: false, init: {},
+    };
+    const INIT_VALUES = {
+        "--title": "title", "--contract-version": "contractVersion", "--contact-name": "contactName",
+        "--contact-url": "contactUrl", "--license": "license", "--license-url": "licenseUrl",
+        "--server-url": "serverUrl", "--broker-host": "brokerHost",
     };
     const positional = [];
 
@@ -83,7 +103,12 @@ function parseArgs(argv) {
             case "-C": options.dir = path.resolve(next()); break;
             case "-q": case "--quiet": options.quiet = true; break;
             case "-h": case "--help": options.help = true; break;
+            case "-y": case "--yes": options.yes = true; break;
             default:
+                if (INIT_VALUES[arg]) {
+                    options.init[INIT_VALUES[arg]] = next();
+                    break;
+                }
                 if (arg.startsWith("-")) throw new ConfigError(`unrecognized option '${arg}'`);
                 positional.push(arg);
         }
@@ -106,7 +131,59 @@ function versionsOf(config, names, preRelease) {
     return new Map(names.map((target) => [target, versionOf(config, target, { preRelease })]));
 }
 
-async function main(argv) {
+/** The kinds --openapi and --asyncapi name, in the order the scaffold writes them. */
+function initKinds(kinds) {
+    return kinds ? ["openapi", "asyncapi"].filter((kind) => kinds.includes(kind)) : undefined;
+}
+
+/**
+ * Scaffolds a library. At a terminal, and without --yes, it asks for every value no
+ * flag gives; anywhere else it takes the defaults, as it always has.
+ *
+ * @param {object} io where a terminal is: `interactive`, and the `input` and `output`
+ *     streams to ask on; process.stdin and process.stdout unless the caller says otherwise
+ */
+async function runInit(options, positional, io, log) {
+    if (options.targets.length > 1) {
+        throw new ConfigError(`init scaffolds one target; --target was given ${options.targets.length} times`);
+    }
+    const dir = path.resolve(options.dir, positional[1] || ".");
+    const input = io.input || process.stdin;
+    const output = io.output || process.stdout;
+    const interactive = io.interactive !== undefined ? io.interactive : Boolean(input.isTTY && output.isTTY);
+    const given = { ...options.init, target: options.targets[0], kinds: initKinds(options.kinds) };
+    for (const key of Object.keys(given)) if (given[key] === undefined) delete given[key];
+
+    const terminal = interactive && !options.yes
+        ? require("node:readline/promises").createInterface({ input, output })
+        : null;
+    try {
+        const values = await resolveValues({
+            given,
+            ask: terminal && ((question) => terminal.question(question)),
+            tell: (message) => output.write(`${message}\n`),
+        });
+        log(`Scaffolding a specification library in ${dir}`);
+        let force = options.force;
+        if (terminal && force) {
+            // Asked, --force means "after showing me": it overwrites what differs only
+            // once the list has been seen and agreed to.
+            const differing = plan(dir, scaffold(values)).filter((entry) => entry.status === "differs");
+            if (differing.length > 0) {
+                output.write(`These files differ from the scaffold:\n${differing.map((d) => `  ${d.rel}\n`).join("")}`);
+                const answer = await terminal.question(`Overwrite these ${differing.length} file(s)? [y/N] `);
+                force = /^y(es)?$/i.test(answer.trim());
+            }
+        }
+        init(dir, { values, force, log });
+        log(`\nNext: api-only-publisher build -C ${dir}`);
+    } finally {
+        if (terminal) terminal.close();
+    }
+    return 0;
+}
+
+async function main(argv, io = {}) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
 
@@ -117,13 +194,7 @@ async function main(argv) {
 
     const log = options.quiet ? () => {} : (message) => console.log(message);
 
-    if (command === "init") {
-        const dir = path.resolve(options.dir, positional[1] || ".");
-        log(`Scaffolding a specification library in ${dir}`);
-        init(dir, { force: options.force, log });
-        log(`\nNext: api-only-publisher build -C ${dir}`);
-        return 0;
-    }
+    if (command === "init") return runInit(options, positional, io, log);
 
     const config = loadFrom(options.dir);
     const targets = options.targets.length > 0 ? options.targets : null;

package/src/config.js

@@ -161,8 +161,9 @@ function load(configPath) {
                 requireString(this.sources[kind], `sources.${kind}`),
                 this.targets[target][kind].bundle);
         },
-        // Whether built documents of this kind carry x-fragment-path on each
-        // component. On unless turned off; OpenAPI only.
+        // Whether built documents of this kind carry x-fragment-path: on each
+        // component of an OpenAPI document, on each fragment of an AsyncAPI one.
+        // On unless turned off, for both kinds.
         fragmentPaths(kind) {
             if (kind !== "openapi" && kind !== "asyncapi") return false;
             const configured = (this.defaults[kind] || {}).fragmentPaths;

package/src/init-questions.js

@@ -0,0 +1,186 @@
+"use strict";
+
+// The values `init` scaffolds from: asked for at a terminal, taken from flags, or
+// defaulted -- in that order of precedence, a flag always winning.
+//
+// Nothing here reads input. The caller hands in `ask`, a function that shows a
+// question and resolves to the answer, which is how the CLI connects a terminal
+// and how the tests connect a script; without one, nobody is asked.
+
+const { DEFAULTS } = require("./init");
+const { ConfigError } = require("./config");
+const { parse } = require("./version-policy");
+
+/** SPDX identifiers whose licence text has a well-known URL, so it need not be asked for. */
+const LICENSE_URLS = Object.freeze({
+    "Apache-2.0": "https://www.apache.org/licenses/LICENSE-2.0.html",
+    "MIT": "https://opensource.org/license/mit",
+    "BSD-2-Clause": "https://opensource.org/license/bsd-2-clause",
+    "BSD-3-Clause": "https://opensource.org/license/bsd-3-clause",
+    "MPL-2.0": "https://www.mozilla.org/en-US/MPL/2.0/",
+    "EPL-2.0": "https://www.eclipse.org/legal/epl-2.0/",
+    "GPL-3.0-only": "https://www.gnu.org/licenses/gpl-3.0.html",
+    "LGPL-3.0-only": "https://www.gnu.org/licenses/lgpl-3.0.html",
+});
+
+// A target name becomes a file name, a properties key, a Maven artifactId, a git tag
+// and, through the Subscriber, a Gradle task name -- which treats -, _ and . alike, so
+// only one of them may separate words, or two targets could claim one task.
+const TARGET = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+function checkTarget(value) {
+    return TARGET.test(value) ? null
+        : "use lowercase letters and digits, in words joined by single hyphens, starting with a letter, " +
+          "such as customer-orders";
+}
+
+function checkVersion(value) {
+    let version;
+    try {
+        version = parse(value);
+    } catch (error) {
+        return "it is not a semantic version, such as 0.1.0";
+    }
+    return version.prerelease ? "a contract starts at a release version, not a pre-release" : null;
+}
+
+function checkUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol === "http:" || url.protocol === "https:") return null;
+    } catch (error) {
+        // Not a URL at all; reported below like any other.
+    }
+    return "it is not an http or https URL";
+}
+
+function checkHost(value) {
+    return /^[A-Za-z0-9.-]+(:\d{1,5})?$/.test(value) ? null : "give a host, optionally with a port, such as kafka:9092";
+}
+
+function checkText(value) {
+    return value.trim() ? null : "it may not be empty";
+}
+
+/** The kinds a library holds, from what someone typed; null when it names none. */
+function parseKinds(text) {
+    switch (text.trim().toLowerCase()) {
+        case "openapi": return ["openapi"];
+        case "asyncapi": return ["asyncapi"];
+        case "both": return ["openapi", "asyncapi"];
+        default: return null;
+    }
+}
+
+const hasOpenapi = (v) => v.kinds.includes("openapi");
+const hasAsyncapi = (v) => v.kinds.includes("asyncapi");
+
+/**
+ * The questions, in the order they are asked. `when` says whether a question applies
+ * to the values chosen so far; `flag` is the command-line option that answers it.
+ */
+const QUESTIONS = [
+    {
+        key: "kinds", flag: "--openapi/--asyncapi", text: "Kinds of document: openapi, asyncapi or both",
+        show: (kinds) => (kinds.length === 2 ? "both" : kinds[0]),
+        read: (text) => {
+            const kinds = parseKinds(text);
+            return kinds ? { value: kinds } : { problem: `'${text}' is not openapi, asyncapi or both` };
+        },
+    },
+    { key: "target", flag: "--target", text: "Target name", check: checkTarget, name: "a target name" },
+    { key: "title", flag: "--title", text: "API title", check: checkText, name: "a title" },
+    { key: "contractVersion", flag: "--contract-version", text: "Initial contract version", check: checkVersion, name: "a release version" },
+    { key: "contactName", flag: "--contact-name", text: "Contact name", check: checkText, name: "a contact name" },
+    { key: "contactUrl", flag: "--contact-url", text: "Contact URL", check: checkUrl },
+    { key: "license", flag: "--license", text: "Licence, as an SPDX identifier", check: checkText, name: "a licence" },
+    {
+        key: "licenseUrl", flag: "--license-url", text: "Licence URL", check: checkUrl,
+        derive: (v) => LICENSE_URLS[v.license],
+    },
+    { key: "serverUrl", flag: "--server-url", text: "Production server URL", check: checkUrl, when: hasOpenapi },
+    { key: "brokerHost", flag: "--broker-host", text: "Broker host, with its port", check: checkHost, when: hasAsyncapi, name: "a broker host" },
+];
+
+/** Reads an answer to a question: the value, or what is wrong with it. */
+function read(question, text) {
+    if (question.read) return question.read(text);
+    const problem = question.check(text);
+    if (!problem) return { value: text };
+    // "'x' is not a target name: use ..." reads better than "'x': use ...", where a
+    // question names what it asks for; "it is not ..." reasons stand on their own.
+    return { problem: problem.startsWith("it ") ? `'${text}' ${problem.slice(3)}` : `'${text}' is not ${question.name}: ${problem}` };
+}
+
+/**
+ * Works out every value `init` scaffolds from.
+ *
+ * @param {object} options
+ * @param {object} [options.given] values given as flags, by key; they are never asked
+ * @param {function(string): Promise<string>} [options.ask] shows a question, resolves to the answer
+ * @param {function(string): void} [options.tell] shows why an answer was refused
+ * @returns {Promise<object>} the values, as DEFAULTS has them
+ * @throws {ConfigError} when a flag's value is invalid, or does not apply to the kinds chosen
+ */
+async function resolveValues({ given = {}, ask = null, tell = () => {} } = {}) {
+    const values = {};
+    for (const question of QUESTIONS) {
+        const applies = !question.when || question.when({ ...DEFAULTS, ...values });
+        const flagged = given[question.key];
+        if (!applies) {
+            if (flagged !== undefined) {
+                throw new ConfigError(`${question.flag} applies only to a library with ${
+                    question.key === "serverUrl" ? "OpenAPI" : "AsyncAPI"}`);
+            }
+            continue;
+        }
+        if (flagged !== undefined) {
+            if (question.key === "kinds") {
+                values.kinds = flagged;
+                continue;
+            }
+            const answer = read(question, flagged);
+            if (answer.problem) throw new ConfigError(`${question.flag} ${answer.problem}`);
+            values[question.key] = answer.value;
+            continue;
+        }
+        // A question that derives its value is not asked when it can be derived -- a known
+        // licence brings its URL -- and has no default when it cannot: one must be given.
+        const fallback = question.derive ? question.derive({ ...DEFAULTS, ...values }) : DEFAULTS[question.key];
+        if (question.derive && fallback !== undefined) {
+            values[question.key] = fallback;
+            continue;
+        }
+        if (!ask) {
+            if (fallback === undefined) {
+                throw new ConfigError(`--license ${values.license} has no known URL: give one with --license-url`);
+            }
+            values[question.key] = fallback;
+            continue;
+        }
+        const prompt = fallback === undefined ? `${question.text}: `
+            : `${question.text} [${question.show ? question.show(fallback) : fallback}]: `;
+        for (;;) {
+            const text = (await ask(prompt)).trim();
+            if (!text && fallback !== undefined) {
+                values[question.key] = fallback;
+                break;
+            }
+            if (!text) {
+                tell(`${values.license} is not a licence this tool knows the URL of: give it`);
+                continue;
+            }
+            const answer = read(question, text);
+            if (!answer.problem) {
+                values[question.key] = answer.value;
+                break;
+            }
+            tell(answer.problem);
+        }
+    }
+    return { ...DEFAULTS, ...values };
+}
+
+module.exports = {
+    resolveValues, checkTarget, checkVersion, checkUrl, checkHost, parseKinds, QUESTIONS, LICENSE_URLS,
+};

package/src/init.js

@@ -6,58 +6,85 @@
 // layout below is the one the library documentation describes; a project that
 // starts from it inherits the common/<product> split, the shared info block with
 // placeholder snippets, and a configuration that already builds.
+//
+// What it writes follows from a handful of values -- which kinds of document the
+// library holds, the target's name, the API's title and so on -- that
+// init-questions.js asks for at a terminal and defaults everywhere else. This file
+// only turns values into files and writes them; it never reads input itself.
 
 const fs = require("fs");
 const path = require("path");
+const YAML = require("yaml");
 
-const CONFIG = `# apionly.yaml
-#
-# Declares what this library builds, from where, and where each document goes.
-
-schemaVersion: 1
-
-sources:
-  root: specs
-  openapi: openapi
-  asyncapi: asyncapi
-
-defaults:
-  openapi:
-    lint: .redocly.yaml
-    outputName: openapi.yaml
-  asyncapi:
-    outputName: asyncapi.yaml
-  placeholders:
-    # Fail the build on a {{token}} with no matching Markdown file, rather than
-    # emitting a marker into a published contract.
-    strict: true
-
-build:
-  staging: build/staging
-  dist: dist
-
-toolchain:
-  redocly: "@redocly/cli@2.52.0"
-  asyncapi: "@asyncapi/cli@6.0.2"
-
-targets:
-  example-service:
-    openapi:
-      bundle: bundles/example-service_openapi_structure.yaml
-`;
+/** Every value the scaffold is written from, as it is when nobody chooses otherwise. */
+const DEFAULTS = Object.freeze({
+    kinds: Object.freeze(["openapi"]),
+    target: "example-service",
+    title: "Example API",
+    contractVersion: "0.1.0",
+    contactName: "Example Team",
+    contactUrl: "https://example.invalid",
+    license: "Apache-2.0",
+    licenseUrl: "https://www.apache.org/licenses/LICENSE-2.0.html",
+    serverUrl: "https://api.example.invalid",
+    brokerHost: "kafka:9092",
+});
+
+/** A value as a YAML scalar: plain where YAML reads it back unchanged, quoted where it would not. */
+function scalar(value) {
+    return YAML.stringify(value, { lineWidth: 0 }).trimEnd();
+}
 
-const INFO = `title: Example API
+function config(v) {
+    const openapi = v.kinds.includes("openapi");
+    const asyncapi = v.kinds.includes("asyncapi");
+    const lines = [
+        "# apionly.yaml",
+        "#",
+        "# Declares what this library builds, from where, and where each document goes.",
+        "",
+        "schemaVersion: 1",
+        "",
+        "sources:",
+        "  root: specs",
+    ];
+    if (openapi) lines.push("  openapi: openapi");
+    if (asyncapi) lines.push("  asyncapi: asyncapi");
+    lines.push("", "defaults:");
+    if (openapi) lines.push("  openapi:", "    lint: .redocly.yaml", "    outputName: openapi.yaml");
+    if (asyncapi) lines.push("  asyncapi:", "    outputName: asyncapi.yaml");
+    lines.push(
+        "  placeholders:",
+        "    # Fail the build on a {{token}} with no matching Markdown file, rather than",
+        "    # emitting a marker into a published contract.",
+        "    strict: true",
+        "",
+        "build:",
+        "  staging: build/staging",
+        "  dist: dist",
+        "",
+        "toolchain:",
+    );
+    if (openapi) lines.push('  redocly: "@redocly/cli@2.52.0"');
+    if (asyncapi) lines.push('  asyncapi: "@asyncapi/cli@6.0.2"');
+    lines.push("", "targets:", `  ${v.target}:`);
+    if (openapi) lines.push("    openapi:", `      bundle: bundles/${v.target}_openapi_structure.yaml`);
+    if (asyncapi) lines.push("    asyncapi:", `      bundle: bundles/${v.target}_asyncapi_structure.yaml`);
+    return lines.join("\n") + "\n";
+}
+
+const info = (v) => `title: ${scalar(v.title)}
 version: 0.0.0
 description: |
   What this API is for.
 
   {{conventions}}
 contact:
-  name: Example Team
-  url: https://example.invalid
+  name: ${scalar(v.contactName)}
+  url: ${scalar(v.contactUrl)}
 license:
-  name: Apache-2.0
-  url: https://www.apache.org/licenses/LICENSE-2.0.html
+  name: ${scalar(v.license)}
+  url: ${scalar(v.licenseUrl)}
 `;
 
 const CONVENTIONS = `## Conventions
@@ -68,7 +95,7 @@ with whatever your own API consumers need to know up front -- pagination, status
 codes, error shapes.
 `;
 
-const SERVERS = `- url: https://api.example.invalid
+const servers = (v) => `- url: ${scalar(v.serverUrl)}
   description: Production.
 `;
 
@@ -117,7 +144,9 @@ content:
         - status
 `;
 
-const PATH_FRAGMENT = `get:
+// With AsyncAPI beside it, the examples are identified by a schema both protocols
+// share; on its own, the OpenAPI scaffold stays as small as it always was.
+const pathFragment = (shared) => `get:
   operationId: listExamples
   summary: List examples.
   responses:
@@ -128,11 +157,17 @@ const PATH_FRAGMENT = `get:
           schema:
             type: array
             items:
-              type: string
+${shared ? "              $ref: '../../components/common/schemas/ExampleIdV1.yaml'" : "              type: string"}
     '400':
       $ref: '../../components/common/responses/errors/InvalidRequestProblemV1.yaml'
 `;
 
+const EXAMPLE_ID = `# One definition, two protocols: the HTTP response and the event both refer to this
+# fragment, so an example's identifier means the same thing wherever it appears.
+type: string
+description: An example's identifier.
+`;
+
 const REDOCLY = `# Lint rules for this library.
 #
 # 'recommended' is Redocly's own baseline. Narrow or widen it as the library
@@ -147,44 +182,177 @@ dist/
 node_modules/
 `;
 
-const VERSION = `# The version of the example-service contract, for every document it builds.
+const version = (v) => `# The version of the ${v.target} contract, for every document it builds.
 # Semantic: major for a breaking change, minor for an additive one, patch for
 # anything else. Change it in the same commit as the fragments it describes.
-version=0.1.0
+version=${v.contractVersion}
+`;
+
+// The AsyncAPI bundle root holds its operations itself: they point into the document
+// with #/channels/..., which only resolves in the file that contains it.
+const asyncBundle = (v) => `asyncapi: 3.1.0
+info:
+  title: ${scalar(v.title)}
+  version: 0.0.0
+  description: |
+    The events this API publishes.
+
+    {{conventions}}
+  contact:
+    name: ${scalar(v.contactName)}
+    url: ${scalar(v.contactUrl)}
+  license:
+    name: ${scalar(v.license)}
+    url: ${scalar(v.licenseUrl)}
+defaultContentType: application/json
+servers:
+  production:
+    host: ${scalar(v.brokerHost)}
+    protocol: kafka
+    description: Production.
+channels:
+  examplesV1:
+    $ref: '../channels/example/ExamplesV1.yaml'
+operations:
+  publishExampleCreated:
+    action: send
+    channel:
+      $ref: '#/channels/examplesV1'
+    summary: Publish an ExampleCreated event when an example is created.
+    messages:
+      - $ref: '#/channels/examplesV1/messages/exampleCreated'
+`;
+
+const CHANNEL = `address: examples.v1
+title: Examples
+description: Events about examples.
+messages:
+  exampleCreated:
+    $ref: '../../messages/example/ExampleCreatedMessageV1.yaml'
+`;
+
+const MESSAGE = `name: ExampleCreated
+title: An example was created.
+contentType: application/json
+payload:
+  $ref: '../../components/example/schemas/ExampleCreatedEventV1.yaml'
 `;
 
-const FILES = {
-    "apionly.yaml": CONFIG,
-    ".redocly.yaml": REDOCLY,
-    ".gitignore": GITIGNORE,
-    "specs/openapi/shared/info.yaml": INFO,
-    "specs/openapi/shared/conventions.md": CONVENTIONS,
-    "specs/openapi/shared/servers.yaml": SERVERS,
-    "specs/openapi/bundles/example-service_openapi_structure.yaml": BUNDLE,
-    "specs/openapi/bundles/example-service.bundle.properties": VERSION,
-    "specs/openapi/paths/example/ExamplesV1.yaml": PATH_FRAGMENT,
-    "specs/openapi/components/common/security/BearerAuth.yaml": SECURITY_SCHEME,
-    "specs/openapi/components/common/responses/errors/InvalidRequestProblemV1.yaml": PROBLEM,
-};
-
-function init(targetDir, { force = false, log = () => {} } = {}) {
-    const created = [];
-    const skipped = [];
-
-    for (const [rel, content] of Object.entries(FILES)) {
+const event = (shared) => `type: object
+description: An example was created.
+required:
+  - id
+  - occurredAt
+properties:
+  id:
+${shared
+        ? "    # The OpenAPI tree's schema: an event and an HTTP response mean one identifier.\n" +
+          "    $ref: '../../../../openapi/components/common/schemas/ExampleIdV1.yaml'"
+        : "    type: string\n    description: The example's identifier."}
+  occurredAt:
+    type: string
+    format: date-time
+    description: When the example was created.
+`;
+
+/**
+ * The files a library of these values starts with, keyed by their path relative to it.
+ *
+ * @param {object} values the values, as DEFAULTS has them
+ * @returns {Object<string, string>}
+ */
+function scaffold(values = DEFAULTS) {
+    const v = { ...DEFAULTS, ...values };
+    const openapi = v.kinds.includes("openapi");
+    const asyncapi = v.kinds.includes("asyncapi");
+    const both = openapi && asyncapi;
+    const files = { "apionly.yaml": config(v) };
+    if (openapi) files[".redocly.yaml"] = REDOCLY;
+    files[".gitignore"] = GITIGNORE;
+
+    if (openapi) {
+        Object.assign(files, {
+            "specs/openapi/shared/info.yaml": info(v),
+            "specs/openapi/shared/conventions.md": CONVENTIONS,
+            "specs/openapi/shared/servers.yaml": servers(v),
+            [`specs/openapi/bundles/${v.target}_openapi_structure.yaml`]: BUNDLE,
+            [`specs/openapi/bundles/${v.target}.bundle.properties`]: version(v),
+            "specs/openapi/paths/example/ExamplesV1.yaml": pathFragment(both),
+            "specs/openapi/components/common/security/BearerAuth.yaml": SECURITY_SCHEME,
+            "specs/openapi/components/common/responses/errors/InvalidRequestProblemV1.yaml": PROBLEM,
+        });
+        if (both) files["specs/openapi/components/common/schemas/ExampleIdV1.yaml"] = EXAMPLE_ID;
+    }
+    if (asyncapi) {
+        // The version file sits beside the target's first bundle root: the OpenAPI one
+        // when there is one. The conventions snippet is found anywhere under specs/.
+        if (!openapi) {
+            files[`specs/asyncapi/bundles/${v.target}.bundle.properties`] = version(v);
+            files["specs/asyncapi/shared/conventions.md"] = CONVENTIONS;
+        }
+        Object.assign(files, {
+            [`specs/asyncapi/bundles/${v.target}_asyncapi_structure.yaml`]: asyncBundle(v),
+            "specs/asyncapi/channels/example/ExamplesV1.yaml": CHANNEL,
+            "specs/asyncapi/messages/example/ExampleCreatedMessageV1.yaml": MESSAGE,
+            "specs/asyncapi/components/example/schemas/ExampleCreatedEventV1.yaml": event(both),
+        });
+    }
+    return files;
+}
+
+const FILES = scaffold(DEFAULTS);
+
+/** Text as a comparison sees it: line endings and final newlines are not differences. */
+function normalised(text) {
+    return text.replace(/\r\n?/g, "\n").replace(/\n+$/, "");
+}
+
+/**
+ * What writing these files would do to each: create it, leave it because it is
+ * identical, or find it different from what would be written.
+ *
+ * @returns {{rel: string, status: "missing"|"identical"|"differs"}[]}
+ */
+function plan(targetDir, files) {
+    return Object.entries(files).map(([rel, content]) => {
         const file = path.join(targetDir, rel);
-        if (fs.existsSync(file) && !force) {
-            skipped.push(rel);
+        if (!fs.existsSync(file)) return { rel, status: "missing" };
+        const same = normalised(fs.readFileSync(file, "utf8")) === normalised(content);
+        return { rel, status: same ? "identical" : "differs" };
+    });
+}
+
+/**
+ * Writes the scaffold of these values into a directory, and reports each file.
+ *
+ * A file that is not there is created. One that is there already is left alone,
+ * reported as identical to what would have been written or as differing from it;
+ * with `force`, one that differs is overwritten.
+ */
+function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } = {}) {
+    const files = scaffold(values);
+    const report = { created: [], overwritten: [], identical: [], differing: [] };
+
+    for (const { rel, status } of plan(targetDir, files)) {
+        if (status === "identical") {
+            report.identical.push(rel);
+            continue;
+        }
+        if (status === "differs" && !force) {
+            report.differing.push(rel);
             continue;
         }
+        const file = path.join(targetDir, rel);
         fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, content);
-        created.push(rel);
+        fs.writeFileSync(file, files[rel]);
+        (status === "missing" ? report.created : report.overwritten).push(rel);
     }
 
-    for (const rel of created) log(`  created  ${rel}`);
-    for (const rel of skipped) log(`  exists   ${rel} (left alone; --force overwrites)`);
-    return { created, skipped };
+    for (const rel of report.created) log(`  created    ${rel}`);
+    for (const rel of report.overwritten) log(`  overwrote  ${rel}`);
+    for (const rel of report.identical) log(`  identical  ${rel}`);
+    for (const rel of report.differing) log(`  differs    ${rel} (left alone; --force overwrites)`);
+    return { ...report, skipped: [...report.identical, ...report.differing] };
 }
 
-module.exports = { init, FILES };
+module.exports = { init, scaffold, plan, FILES, DEFAULTS };