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

package/src/config-command.js

@@ -0,0 +1,100 @@
+"use strict";
+
+// The `config` command's one section so far: `portfolio`.
+//
+// `init` only ever adds this section when it is missing (init-config.js);
+// reconfiguring what is already there is this file's job instead, and it works
+// the opposite way on purpose -- it always asks, offering what is already
+// configured as each default, and always rewrites the keys it asked about.
+//
+// A second configurable section extends this the same way a second kind
+// extended init-config.js's slots: its own question list, its own current()
+// reader and its own writer, called from the same `config` command. Nothing here
+// is written as a registry ahead of that need -- there is exactly one section
+// today, and one small module reads more easily than an abstraction for a
+// second case that does not exist yet.
+
+const YAML = require("yaml");
+const { ConfigError } = require("./config");
+
+const PATH_STRATEGIES = ["target-prefix", "none"];
+
+/** The portfolio section's questions, in the order they are asked. */
+const QUESTIONS = [
+    {
+        key: "paths", flag: "--portfolio-paths",
+        text: "Path prefix strategy for a portfolio: target-prefix or none",
+        check: (v) => (PATH_STRATEGIES.includes(v) ? null : `use ${PATH_STRATEGIES.join(" or ")}`),
+    },
+    {
+        key: "location", flag: "--portfolio-location",
+        text: "Where a portfolio's generated bundle root lands, as a directory beside bundles/",
+        check: (v) => (v.trim() ? null : "it may not be empty"),
+    },
+];
+
+/**
+ * Resolves the portfolio section's values: a flag always wins. At a terminal,
+ * each question shows `current`'s value for it in brackets -- the section's own,
+ * if it has one, or the documented default when it does not -- and Enter keeps
+ * it; without a terminal, that same value is taken as given, exactly as if it
+ * had been typed.
+ *
+ * @param {object} options
+ * @param {object} [options.given] values given as flags, by key; never asked
+ * @param {object} options.current the value each question defaults to
+ * @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 resolved values, one per question
+ * @throws {ConfigError} when a flag's value is invalid
+ */
+async function resolvePortfolioValues({ given = {}, current, ask = null, tell = () => {} } = {}) {
+    const values = {};
+    for (const question of QUESTIONS) {
+        const flagged = given[question.key];
+        if (flagged !== undefined) {
+            const problem = question.check(flagged);
+            if (problem) throw new ConfigError(`${question.flag} ${problem}`);
+            values[question.key] = flagged;
+            continue;
+        }
+        const fallback = current[question.key];
+        if (!ask) {
+            values[question.key] = fallback;
+            continue;
+        }
+        const prompt = `${question.text} [${fallback}]: `;
+        for (;;) {
+            const text = (await ask(prompt)).trim();
+            if (!text) {
+                values[question.key] = fallback;
+                break;
+            }
+            const problem = question.check(text);
+            if (!problem) {
+                values[question.key] = text;
+                break;
+            }
+            tell(problem);
+        }
+    }
+    return values;
+}
+
+/**
+ * Writes `values` into apionly.yaml's portfolio section, wholesale for the keys
+ * asked about and untouched everywhere else: a hand-set portfolio.openapi.tags,
+ * for one, is not something `config portfolio` asked about, so it survives.
+ * YAML.parseDocument, never a parse and restringify -- the file's comments, and
+ * every value this did not ask about, are not this command's to change.
+ *
+ * @returns {string} the edited text
+ */
+function writePortfolioSection(text, values) {
+    const doc = YAML.parseDocument(text);
+    doc.setIn(["portfolio", "openapi", "paths"], values.paths);
+    doc.setIn(["portfolio", "location"], values.location);
+    return doc.toString();
+}
+
+module.exports = { resolvePortfolioValues, writePortfolioSection, QUESTIONS };

package/src/config.js

@@ -12,8 +12,52 @@ const YAML = require("yaml");
 const CONFIG_NAME = "apionly.yaml";
 const SUPPORTED_SCHEMA_VERSION = 1;
 
+// The keys allowed at the levels of apionly.yaml that have a fixed shape. `channels`
+// and `toolchain` are deliberately absent: a channel's settings depend on its type,
+// and a tool's name is whatever the author calls it, so neither has a closed
+// vocabulary to check against. Everywhere else, a key nothing reads is far more
+// often a typo or a bad indent than a value nobody has used yet -- see checkKeys.
+const ROOT_KEYS = [
+    "schemaVersion", "sources", "defaults", "build", "reports", "lint",
+    "distribution", "channels", "targets", "toolchain", "portfolio",
+];
+const SOURCES_KEYS = ["root", "openapi", "asyncapi"];
+const DEFAULTS_KEYS = ["openapi", "asyncapi", "placeholders"];
+const DEFAULTS_KIND_KEYS = { openapi: ["lint", "outputName", "fragmentPaths"], asyncapi: ["lint", "outputName", "fragmentPaths"] };
+const PLACEHOLDERS_KEYS = ["strict"];
+const BUILD_KEYS = ["staging", "dist"];
+const REPORTS_KEYS = ["lint"];
+const LINT_KEYS = ["unreferenced"];
+const DISTRIBUTION_KEYS = ["root", "layout"];
+const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile"];
+const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
+const PORTFOLIO_KEYS = ["openapi", "security", "location"];
+const PORTFOLIO_OPENAPI_KEYS = ["paths", "operationIds", "tags"];
+
+// What every portfolio setting is when apionly.yaml says nothing: safe for the
+// ordinary case (a gateway routing /<target>/** to each service), and named rather
+// than boolean, so a third strategy can be added later without breaking the schema.
+// Because a portfolio is regenerated on every build, none of this needs a migration
+// when it changes -- the next build simply produces a different portfolio.
+const PORTFOLIO_DEFAULTS = Object.freeze({
+    openapi: Object.freeze({ paths: "target-prefix", operationIds: "target-prefix", tags: "reconcile" }),
+    security: "push-down",
+    location: "portfolios",
+});
+const PATH_STRATEGIES = ["target-prefix", "none"];
+
 class ConfigError extends Error {}
 
+/** Refuses a key `obj` has that is not in `allowed`, naming the key and where it is. */
+function checkKeys(obj, allowed, where) {
+    if (!obj || typeof obj !== "object") return;
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            throw new ConfigError(`unknown key '${key}' in ${where}`);
+        }
+    }
+}
+
 // Walk up from `startDir` looking for apionly.yaml, so the CLI can be run from
 // anywhere inside the specification repository.
 function locate(startDir) {
@@ -57,10 +101,38 @@ function load(configPath) {
         );
     }
 
+    checkKeys(parsed, ROOT_KEYS, CONFIG_NAME);
+
     const root = path.dirname(configPath);
     const sources = parsed.sources || {};
+    checkKeys(sources, SOURCES_KEYS, "sources");
     requireString(sources.root, "sources.root");
 
+    const defaults = parsed.defaults || {};
+    checkKeys(defaults, DEFAULTS_KEYS, "defaults");
+    for (const kind of ["openapi", "asyncapi"]) {
+        if (defaults[kind]) checkKeys(defaults[kind], DEFAULTS_KIND_KEYS[kind], `defaults.${kind}`);
+    }
+    if (defaults.placeholders) checkKeys(defaults.placeholders, PLACEHOLDERS_KEYS, "defaults.placeholders");
+
+    const build = parsed.build || {};
+    checkKeys(build, BUILD_KEYS, "build");
+    const reports = parsed.reports || {};
+    checkKeys(reports, REPORTS_KEYS, "reports");
+    const lint = parsed.lint || {};
+    checkKeys(lint, LINT_KEYS, "lint");
+    if (parsed.distribution) checkKeys(parsed.distribution, DISTRIBUTION_KEYS, "distribution");
+
+    const portfolio = parsed.portfolio || {};
+    checkKeys(portfolio, PORTFOLIO_KEYS, "portfolio");
+    if (portfolio.openapi) checkKeys(portfolio.openapi, PORTFOLIO_OPENAPI_KEYS, "portfolio.openapi");
+    const pathStrategy = portfolio.openapi && portfolio.openapi.paths;
+    if (pathStrategy !== undefined && !PATH_STRATEGIES.includes(pathStrategy)) {
+        throw new ConfigError(
+            `portfolio.openapi.paths must be ${PATH_STRATEGIES.join(" or ")}, not ${JSON.stringify(pathStrategy)}`
+        );
+    }
+
     const targets = parsed.targets;
     if (!targets || typeof targets !== "object" || Object.keys(targets).length === 0) {
         throw new ConfigError(`${configPath} declares no targets`);
@@ -72,14 +144,84 @@ function load(configPath) {
         if (!target || typeof target !== "object") {
             throw new ConfigError(`target '${name}' is not a mapping`);
         }
+        checkKeys(target, TARGET_KEYS, `targets.${name}`);
         const kinds = ["openapi", "asyncapi"].filter((k) => target[k]);
         if (kinds.length === 0) {
             throw new ConfigError(
                 `target '${name}' declares neither an openapi nor an asyncapi bundle`
             );
         }
+
+        // A portfolio is a catalogue, never a contract of its own: declaring an
+        // aggregate for one kind means the target IS a portfolio, so it must
+        // aggregate every kind it declares, and it is never published.
+        const aggregateKinds = kinds.filter((k) => target[k].aggregate !== undefined);
+        if (aggregateKinds.length > 0 && aggregateKinds.length !== kinds.length) {
+            const bundled = kinds.find((k) => target[k].aggregate === undefined);
+            throw new ConfigError(
+                `target '${name}' aggregates ${aggregateKinds[0]} but has a hand-written bundle for ${bundled}; ` +
+                "a target may not mix an aggregate with a hand-written bundle across kinds -- a hand-written " +
+                "AsyncAPI portfolio is an ordinary bundle, not an aggregate that happens to look like one"
+            );
+        }
+        if (aggregateKinds.length > 0 && target.publish === true) {
+            throw new ConfigError(
+                `target '${name}' declares an aggregate; it is never published, whatever publish says. ` +
+                "Prefixed operation ids match no member's, transcribed classes would not match a member's " +
+                "either, and a portfolio's version answers no useful question, since it moves whenever " +
+                "anything anywhere moves. A combined surface that genuinely needs publishing is a bundle " +
+                "somebody authors deliberately, with its own owner and version -- author one instead."
+            );
+        }
+
         for (const kind of kinds) {
-            requireString(target[kind].bundle, `targets.${name}.${kind}.bundle`);
+            checkKeys(target[kind], TARGET_KIND_KEYS, `targets.${name}.${kind}`);
+            if (target[kind].aggregate !== undefined) {
+                if (target[kind].bundle !== undefined) {
+                    throw new ConfigError(
+                        `target '${name}' declares both aggregate and bundle for ${kind}; an aggregate is ` +
+                        "generated whole, so it needs no hand-written bundle root"
+                    );
+                }
+                const members = target[kind].aggregate;
+                if (!Array.isArray(members) || members.length === 0) {
+                    throw new ConfigError(`targets.${name}.${kind}.aggregate must list at least one target`);
+                }
+                if (members.includes(name)) {
+                    throw new ConfigError(`target '${name}' aggregates itself`);
+                }
+            } else {
+                requireString(target[kind].bundle, `targets.${name}.${kind}.bundle`);
+                if (target[kind].info !== undefined) {
+                    throw new ConfigError(`targets.${name}.${kind}.info only applies to an aggregate`);
+                }
+            }
+        }
+    }
+
+    // Every member an aggregate lists is checked by name, and a member that is
+    // itself an aggregate is refused outright: it has no hand-written bundle for
+    // the generator to read, and reading its *generated* one would mean generating
+    // aggregates in dependency order, which nothing here attempts. Because an
+    // aggregate can only ever reach a hand-written bundle this way, refusing that
+    // one step also catches every transitive self-reference, not only the direct
+    // one the loop above already refused.
+    for (const [name, target] of Object.entries(targets)) {
+        for (const kind of ["openapi", "asyncapi"].filter((k) => target[k] && target[k].aggregate !== undefined)) {
+            for (const member of target[kind].aggregate) {
+                const memberTarget = targets[member];
+                if (!memberTarget || memberTarget[kind] === undefined) {
+                    throw new ConfigError(
+                        `target '${name}': aggregate member '${member}' declares no ${kind} bundle`
+                    );
+                }
+                if (memberTarget[kind].aggregate !== undefined) {
+                    throw new ConfigError(
+                        `target '${name}' aggregates '${member}', which is itself an aggregate; ` +
+                        "nesting is not supported"
+                    );
+                }
+            }
         }
     }
 
@@ -88,13 +230,14 @@ function load(configPath) {
         root,
         schemaVersion: parsed.schemaVersion,
         sources,
-        defaults: parsed.defaults || {},
+        defaults,
         toolchain: parsed.toolchain || {},
-        build: parsed.build || {},
-        reports: parsed.reports || {},
-        lint: parsed.lint || {},
+        build,
+        reports,
+        lint,
         distribution: parsed.distribution || null,
         channels: parsed.channels || {},
+        portfolio,
         targets,
 
         // --- derived accessors, so callers never re-derive a path themselves ---
@@ -148,19 +291,79 @@ function load(configPath) {
         targetsFor(kind) {
             return Object.keys(this.targets).filter((t) => this.targets[t][kind]);
         },
+        // Whether this target is itself an aggregate, for any kind it declares.
+        // load() already refuses a target that aggregates one kind and hand-writes
+        // another, so any one kind answers for the whole target.
+        isAggregate(target) {
+            return ["openapi", "asyncapi"].some((k) => this.targets[target][k] && this.targets[target][k].aggregate !== undefined);
+        },
         // A target with `publish: false` is a documentation view rather than a
         // contract any one project implements: built and linted, never shipped.
+        // An aggregate is never published either, whether or not it says so --
+        // load() already refuses the one case that would contradict this, `publish:
+        // true` alongside an aggregate, so nothing here needs to re-check that.
         isPublished(target) {
-            return this.targets[target].publish !== false;
+            return this.targets[target].publish !== false && !this.isAggregate(target);
         },
         // A target's bundle root in a staged tree: the build's own, unless another
-        // staged copy is named.
+        // staged copy is named. Only a hand-written bundle has one; an aggregate's
+        // generated root is aggregatePath(), below.
         bundlePath(target, kind, stagingRoot = this.stagingRoot(kind)) {
             return path.join(
                 stagingRoot,
                 requireString(this.sources[kind], `sources.${kind}`),
                 this.targets[target][kind].bundle);
         },
+        // Where an aggregate's generated bundle root lands in a staged tree: outside
+        // bundles/, at the same depth, so every $ref a member contributes -- carried
+        // over verbatim -- still resolves. The path is the tool's to decide, not the
+        // author's: an aggregate declares its members and its info, never where its
+        // generated root lands.
+        aggregatePath(target, kind, stagingRoot = this.stagingRoot(kind)) {
+            return path.join(
+                stagingRoot,
+                requireString(this.sources[kind], `sources.${kind}`),
+                this.portfolioLocation(),
+                `${target}_${kind}_structure.yaml`);
+        },
+        // Where a target's document root sits in a staged tree, hand-written or
+        // generated -- whichever this target is.
+        bundleRootPath(target, kind, stagingRoot = this.stagingRoot(kind)) {
+            return this.isAggregate(target)
+                ? this.aggregatePath(target, kind, stagingRoot)
+                : this.bundlePath(target, kind, stagingRoot);
+        },
+        // The path prefix strategy an OpenAPI portfolio merges its members' paths
+        // and operation ids with: `target-prefix` (the default) for a gateway
+        // routing /<target>/** to each service, `none` where routing is by host and
+        // a prefixed path would exist nowhere.
+        portfolioPathStrategy() {
+            return (this.portfolio.openapi && this.portfolio.openapi.paths) || PORTFOLIO_DEFAULTS.openapi.paths;
+        },
+        // How a portfolio's operation ids are told apart: currently always prefixed
+        // with the target, the same way paths are -- named, like every portfolio
+        // setting, so a second strategy can be added later without a breaking change.
+        portfolioOperationIdStrategy() {
+            return (this.portfolio.openapi && this.portfolio.openapi.operationIds) || PORTFOLIO_DEFAULTS.openapi.operationIds;
+        },
+        // How two members contributing the same tag name are merged: `reconcile`,
+        // today the only mode -- an identical body merges silently, a differing one
+        // merges too, reported, with the first contributing member's body winning.
+        portfolioTagStrategy() {
+            return (this.portfolio.openapi && this.portfolio.openapi.tags) || PORTFOLIO_DEFAULTS.openapi.tags;
+        },
+        // How a portfolio merges root-level `security`: `push-down`, today the only
+        // mode -- each member's root security becomes each of its own contributed
+        // operations' security, so the portfolio never has to say something false
+        // about any one of them. See the Security section of the README.
+        portfolioSecurityStrategy() {
+            return this.portfolio.security || PORTFOLIO_DEFAULTS.security;
+        },
+        // The directory an aggregate's generated bundle root lands in, sibling to
+        // bundles/, at the same depth under each kind's own source tree.
+        portfolioLocation() {
+            return this.portfolio.location || PORTFOLIO_DEFAULTS.location;
+        },
         // 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.

package/src/init-config.js

@@ -0,0 +1,135 @@
+"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.
+ *
+ * `portfolio`, unlike a kind, is never added on its own account: whether a
+ * library is about to have more than one target, and so whether the question is
+ * even asked, is the caller's decision, made once, before this runs -- give the
+ * strategies it resolved here to have the section written with them, or leave
+ * this out entirely to leave the section alone, present or not.
+ *
+ * @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
+ * @param {{paths: string, location: string}} [portfolio] the portfolio section to
+ *     add, with every strategy resolved, when it is missing; omitted, the section
+ *     is never considered at all, whether or not the file already has one
+ * @returns {{text: string, added: string[]}} the edited text, and the slots added, in
+ *     the order scaffold() declares them, portfolio last; `added` is empty, and
+ *     `text` is `text` itself, when nothing was missing.
+ */
+function addMissingConfig(text, v, portfolio) {
+    const doc = YAML.parseDocument(text);
+    const added = [];
+
+    // Not every file that differs is a library with a kind missing. One with a YAML
+    // error cannot be edited at all -- parseDocument does not throw on one, it just
+    // records it, and a document with errors refuses to be stringified back. One that
+    // does not even declare sources.root, whatever it parses to, is not an apionly.yaml
+    // this can complete either way; force, or a person, is what either file needs.
+    if (doc.errors.length > 0 || !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));
+        }
+    }
+
+    if (portfolio && !doc.hasIn(["portfolio"])) {
+        doc.setIn(["portfolio"], {
+            openapi: { paths: portfolio.paths, operationIds: "target-prefix", tags: "reconcile" },
+            security: "push-down",
+            location: portfolio.location,
+        });
+        added.push("portfolio");
+    }
+
+    return added.length === 0 ? { text, added } : { text: doc.toString(), added };
+}
+
+module.exports = { addMissingConfig };

package/src/init.js

@@ -15,6 +15,7 @@
 const fs = require("fs");
 const path = require("path");
 const YAML = require("yaml");
+const { addMissingConfig } = require("./init-config");
 
 /** Every value the scaffold is written from, as it is when nobody chooses otherwise. */
 const DEFAULTS = Object.freeze({
@@ -307,17 +308,39 @@ 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.
  *
- * @returns {{rel: string, status: "missing"|"identical"|"differs"}[]}
+ * 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.
+ *
+ * @param {{paths: string, location: string}} [portfolio] the portfolio section to
+ *     add when apionly.yaml lacks one; see addMissingConfig for what it does with it
+ * @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) {
+function plan(targetDir, files, values, portfolio) {
     return Object.entries(files).map(([rel, content]) => {
         const file = path.join(targetDir, rel);
         if (!fs.existsSync(file)) return { rel, status: "missing" };
-        const same = normalised(fs.readFileSync(file, "utf8")) === normalised(content);
+        const onDisk = fs.readFileSync(file, "utf8");
+        if (rel === CONFIG_FILE && values) {
+            const completed = addMissingConfig(onDisk, { ...DEFAULTS, ...values }, portfolio);
+            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" };
     });
 }
@@ -327,13 +350,31 @@ function plan(targetDir, files) {
  *
  * 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.
+ * 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.
+ *
+ * `portfolio`, given, is added the same way, as one more slot: whether the
+ * library is about to have more than one target -- and so whether this is worth
+ * asking about at all -- is decided before init is called, not here.
  */
-function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } = {}) {
+function init(targetDir, { values = DEFAULTS, force = false, log = () => {}, portfolio = null } = {}) {
     const files = scaffold(values);
-    const report = { created: [], overwritten: [], identical: [], differing: [] };
-
-    for (const { rel, status } of plan(targetDir, files)) {
+    const report = { created: [], overwritten: [], identical: [], differing: [], updated: [] };
+    const updates = [];
+
+    for (const { rel, status, added, text } of plan(targetDir, files, values, portfolio)) {
+        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;
@@ -350,6 +391,7 @@ function init(targetDir, { values = DEFAULTS, force = false, log = () => {} } =
 
     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] };