@arc-e-tect/api-only-publisher 0.6.2 → 0.7.1

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.2
+:api-only-publisher-version: 0.7.1
 
 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,131 @@ 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.
+`updated`:: `apionly.yaml` was there, and lacked a kind's configuration; it does now.
+The message names every slot added -- see <<init-additive,Adding a kind to an existing library §>>.
+`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 still differ -- after any additive update apionly.yaml already got -- and asks once whether to overwrite them; without a terminal, or with `--yes`, it overwrites them without asking.
+
+[#init-additive]
+=== Adding a kind to an existing library
+
+Running `init` again, with a kind the library did not have, is how a library grows: the fragments the new kind needs, and the configuration that makes the build see them.
+
+*Files* stay create-only, as everywhere else in `init`: a fragment not written before is written now; one already there, however it now reads, is left alone -- even where the new kind changes what the scaffold would write for it, such as `specs/openapi/paths/example/ExamplesV1.yaml` once an AsyncAPI event comes to share its schema.
+
+*Configuration* is additive: whichever of `sources.<kind>`, `defaults.<kind>`, the kind's pin in `toolchain`, and `targets.<target>.<kind>` `apionly.yaml` lacks is added to it, in the position a library scaffolded with both kinds from the start would have it in.
+Every value, key and comment already in the file survives untouched, and a slot that is already there, however it reads, is never touched either -- not even to add something missing from *inside* it: a `defaults.openapi` with no `lint` is a choice, and `init` leaves it that way.
+
+[source,console]
+----
+$ api-only-publisher init . --yes --openapi --target orders
+  created    apionly.yaml
+  created    specs/openapi/...
+
+$ api-only-publisher init . --yes --openapi --asyncapi --target orders
+  created    specs/asyncapi/...
+  updated    apionly.yaml (added sources.asyncapi, defaults.asyncapi, toolchain.asyncapi, targets.orders.asyncapi)
+  differs    specs/openapi/paths/example/ExamplesV1.yaml (left alone; --force overwrites)
+----
+
+Nothing is asked before completing `apionly.yaml`: unlike `--force`, an additive update never discards anything, so there is nothing to confirm.
+Run `init` again with the same kinds, and it reports nothing left to add.
+
+`--force` is the other tool for an apionly.yaml that differs, and it does the opposite of the additive update: it reinitialises the file wholesale, exactly as a first run with these values would write it -- any target or key it holds that these values would not produce is gone, additive or not.
+Use it to discard a customisation on purpose; use a plain `init` to add a kind without touching anything else.
+
 [#what-build-does]
 == What `build` does
 
@@ -435,7 +563,7 @@ Every target's document of one kind has the same `outputName`; keep the defaults
 === 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 OpenAPI bundle root this way.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "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), 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/init-config.js

@@ -0,0 +1,115 @@
+"use strict";
+
+// Additively completing an apionly.yaml that already exists.
+//
+// `init` creates a file that is not there; this is the same rule applied to
+// configuration. When a kind's support is missing from an existing apionly.yaml --
+// in whole, because the library never had it, or in part, because a run was
+// interrupted between writing the fragments and writing the config for them -- the
+// slots it needs are added. What is already there, however it reads, is never
+// touched: a `defaults.openapi` block with no `lint` is a choice, not an absence.
+//
+// The unit added is a *slot*: one of the handful of places a kind's support in
+// apionly.yaml lives -- never a key inside one, which is why `slots()` below stops
+// at the map a kind occupies and goes no further into it.
+
+const YAML = require("yaml");
+
+/** Where a kind's tool is pinned in `toolchain`; the two kinds do not share a key name. */
+const TOOLCHAIN_KEY = { openapi: "redocly", asyncapi: "asyncapi" };
+const TOOLCHAIN_PIN = { openapi: "@redocly/cli@2.52.0", asyncapi: "@asyncapi/cli@6.0.2" };
+
+/**
+ * The slots scaffold(v) would fill for one kind, in the order config(v) declares them,
+ * each naming the sibling keys -- in the order to prefer -- a slot goes before when one
+ * of them is already there. `openapi` always precedes `asyncapi`, in every section that
+ * holds both; `asyncapi` precedes `placeholders`, the one section-closing key that is
+ * always there.
+ */
+function slotsFor(kind, v) {
+    const target = v.target;
+    if (kind === "openapi") {
+        return [
+            { path: ["sources"], key: "openapi", value: "openapi", before: ["asyncapi"] },
+            {
+                path: ["defaults"], key: "openapi", before: ["asyncapi", "placeholders"],
+                value: { lint: ".redocly.yaml", outputName: "openapi.yaml" },
+            },
+            { path: ["toolchain"], key: "redocly", value: TOOLCHAIN_PIN.openapi, before: ["asyncapi"] },
+            {
+                path: ["targets", target], key: "openapi", before: ["asyncapi"],
+                value: { bundle: `bundles/${target}_openapi_structure.yaml` },
+            },
+        ];
+    }
+    return [
+        { path: ["sources"], key: "asyncapi", value: "asyncapi", before: [] },
+        { path: ["defaults"], key: "asyncapi", value: { outputName: "asyncapi.yaml" }, before: ["placeholders"] },
+        { path: ["toolchain"], key: "asyncapi", value: TOOLCHAIN_PIN.asyncapi, before: [] },
+        {
+            path: ["targets", target], key: "asyncapi", before: [],
+            value: { bundle: `bundles/${target}_asyncapi_structure.yaml` },
+        },
+    ];
+}
+
+/** A slot's YAML path, dot-separated, as the report names it. */
+function slotName(slot) {
+    return [...slot.path, slot.key].join(".");
+}
+
+/**
+ * Sets `key: value` in the map at `parentPath`, before the first of `before` that is
+ * already a sibling there, or at the end when none is. Creates `parentPath` itself,
+ * as `Document#setIn` does, when it is not there yet -- there being nothing in a map
+ * that does not exist yet to come before.
+ */
+function place(doc, parentPath, key, value, before) {
+    const parent = doc.getIn(parentPath, true);
+    if (YAML.isMap(parent)) {
+        for (const candidate of before) {
+            const sibling = parent.items.find((pair) => String(pair.key) === candidate);
+            if (sibling) {
+                parent.items.splice(parent.items.indexOf(sibling), 0, doc.createPair(key, value));
+                return;
+            }
+        }
+    }
+    doc.setIn([...parentPath, key], value);
+}
+
+/**
+ * Adds to `text` -- an existing apionly.yaml -- whatever configuration slot
+ * scaffold(values) would write and this file lacks. Every value, key and comment
+ * already there survives unchanged; a slot already present, however it reads, is
+ * never touched, and neither is anything inside it.
+ *
+ * @param {string} text apionly.yaml, as it is on disk
+ * @param {object} v the values scaffold(values) was given, resolved: every value
+ *     DEFAULTS has, `values`' own where it gives one -- the shape scaffold() itself
+ *     works from, so a caller that already has that object need not rebuild it
+ * @returns {{text: string, added: string[]}} the edited text, and the slots added, in
+ *     the order scaffold() declares them; `added` is empty, and `text` is `text`
+ *     itself, when nothing was missing.
+ */
+function addMissingConfig(text, v) {
+    const doc = YAML.parseDocument(text);
+    const added = [];
+
+    // Not every file that differs is a library with a kind missing -- one that does not
+    // even declare sources.root is not an apionly.yaml this can complete, whatever it
+    // holds instead; force, or a person, is what that file needs.
+    if (!doc.hasIn(["sources", "root"])) return { text, added };
+
+    for (const kind of ["openapi", "asyncapi"].filter((k) => v.kinds.includes(k))) {
+        for (const slot of slotsFor(kind, v)) {
+            if (doc.hasIn([...slot.path, slot.key])) continue;
+            place(doc, slot.path, slot.key, slot.value, slot.before);
+            added.push(slotName(slot));
+        }
+    }
+
+    return added.length === 0 ? { text, added } : { text: doc.toString(), added };
+}
+
+module.exports = { addMissingConfig };

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,86 @@
 // 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 { addMissingConfig } = require("./init-config");
 
-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 +96,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 +145,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 +158,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 +183,212 @@ 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 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.
 `;
 
-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)) {
+/**
+ * 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+$/, "");
+}
+
+const CONFIG_FILE = "apionly.yaml";
+
+/**
+ * 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.
+ *
+ * apionly.yaml gets one more thing tried, ahead of "differs": whatever slot
+ * scaffold(values) would write and it lacks is added, in place, before the
+ * comparison that decides "identical" or "differs" -- so a file that is missing only
+ * a kind it never had is never reported as differing, and neither is one that is
+ * missing nothing at all. `values`, resolved as scaffold() resolves it, is what that
+ * completion is measured against; without it, apionly.yaml is compared as every
+ * other file is.
+ *
+ * @returns {{rel: string, status: "missing"|"identical"|"differs", added?: string[], text?: string}[]}
+ *     `added` and `text` -- the completed content -- are there only for apionly.yaml,
+ *     and only when something was missing from it.
+ */
+function plan(targetDir, files, values) {
+    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 onDisk = fs.readFileSync(file, "utf8");
+        if (rel === CONFIG_FILE && values) {
+            const completed = addMissingConfig(onDisk, { ...DEFAULTS, ...values });
+            if (completed.added.length > 0) {
+                const status = normalised(completed.text) === normalised(content) ? "identical" : "differs";
+                return { rel, status, added: completed.added, text: completed.text };
+            }
+        }
+        const same = normalised(onDisk) === 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, wholesale, as if this were the
+ * first time -- apionly.yaml included, whatever else it declares.
+ *
+ * Short of `force`, apionly.yaml gets one more chance: whatever configuration a
+ * missing kind needs and it lacks is added to it, leaving every value, key and
+ * comment already there exactly as it was. A kind already declared, however it
+ * reads, is never touched -- what is already there is not changed, only what is
+ * not there is added.
+ */
+function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } = {}) {
+    const files = scaffold(values);
+    const report = { created: [], overwritten: [], identical: [], differing: [], updated: [] };
+    const updates = [];
+
+    for (const { rel, status, added, text } of plan(targetDir, files, values)) {
+        if (added && !force) {
+            fs.writeFileSync(path.join(targetDir, rel), text);
+            report.updated.push(rel);
+            updates.push({ rel, added });
             continue;
         }
+        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, added } of updates) log(`  updated    ${rel} (added ${added.join(", ")})`);
+    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 };