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

package/src/aggregate.js

@@ -2,19 +2,40 @@
 
 // Generated aggregate bundles.
 //
-// A portfolio view of the OpenAPI surface is just another bundle root: every
-// path body already lives in a $ref'd fragment, so a whole-landscape table of
-// contents costs one hand-written file that duplicates no contract text.
+// A portfolio view used to be a hand-written OpenAPI bundle root: every path body
+// already lives in a $ref'd fragment, so a whole-landscape table of contents cost
+// one file that duplicated no contract text. It can be written that way, but it
+// does not follow that it should be: nothing stopped it silently falling behind
+// the members it was meant to list, the moment a service grew an endpoint and
+// nobody remembered the table of contents was a second place to add it.
 //
-// AsyncAPI cannot be written that way. Its operations use document-root pointers
-// -- `channel: {$ref: '#/channels/auditV1'}` -- and `#` resolves against whatever
+// AsyncAPI never had the choice. Its operations use document-root pointers --
+// `channel: {$ref: '#/channels/auditV1'}` -- and `#` resolves against whatever
 // file contains it, so moving an operation into a fragment breaks it. A
 // hand-written async portfolio would therefore have to copy every operation
 // verbatim, and that copy would start rotting the moment a member changed.
 //
-// So it is generated instead: the aggregate's bundle root is synthesised into the
+// So both are generated: the aggregate's bundle root is synthesised into the
 // staged tree from its members, immediately before bundling. Nothing is
 // duplicated in the source, and the view cannot fall behind its members.
+//
+// Generation happens in two passes, because a member's bundle root is read
+// *before* it is bundled -- staging only copies and substitutes placeholders --
+// and at that point almost everything in it is still a $ref pointer, not the
+// content behind it:
+//
+//   Pass 1, here, merges what is visible unresolved: paths and security schemes
+//   are keyed by a map key that is already there in the bundle root, and a
+//   member's own root-level `security` is written inline, never $ref'd. OpenAPI
+//   paths are prefixed with the member's target at this pass, because that is a
+//   plain string rewrite of the key -- it needs nothing resolved.
+//
+//   Pass 2, in pipeline.js, runs on the aggregate's own bundled output, once
+//   every $ref -- the members' and its own -- has been resolved. Only then are an
+//   operation's id, and whether it already sets its own `security`, visible at
+//   all, so that is where operation ids are prefixed, root security is pushed
+//   down onto the operations it reaches, and repeated tags are reconciled by the
+//   name inside them, which a $ref pointer to a tag fragment never shows.
 
 const fs = require("fs");
 const path = require("path");
@@ -22,40 +43,128 @@ const YAML = require("yaml");
 
 class AggregateError extends Error {}
 
+const HTTP_METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
 /**
  * Merge one section of a member's document into the aggregate.
  *
+ * Three modes, for three different expectations of what a repeated key means:
+ *
+ * `unique` (the default) treats a repeated key as ambiguous ownership, whatever
+ * it says -- ordinary for a channel, an operation or a path, where one of two
+ * identical definitions silently not appearing in the aggregate is exactly the
+ * kind of mistake this is here to catch.
+ *
  * `agree` marks sections where members are expected to say the same thing.
  * Several services publishing to one broker all declare that broker, and that is
  * the ordinary case rather than a conflict -- so an identical definition merges
  * silently and only a genuine disagreement is an error.
  *
- * Everywhere else a repeated key is an error even when the definitions match,
- * because it makes ownership ambiguous: two members both defining a channel means
- * one of them would silently not appear in the aggregate.
+ * `reconcile` is for a section where members are expected to sometimes *disagree*
+ * without either being wrong -- a shared tag two members describe slightly
+ * differently is an inconsistency to fix, not a defect to fail the build over.
+ * An identical repeat merges silently, like `agree`; a differing one merges too,
+ * with the first contributing member's value kept and the disagreement reported,
+ * rather than failing the build.
+ *
+ * @returns {Array<{section: string, key: string, winner: string, loser: string}>}
+ *     one entry per reconciled disagreement, always empty outside `reconcile` mode
  */
-function mergeSection(into, from, section, member, seen, { agree = false } = {}) {
-    if (!from[section]) return;
+function mergeSection(into, from, section, member, seen, { mode = "unique", label = section } = {}) {
+    const reconciled = [];
+    if (!from[section]) return reconciled;
     for (const [key, value] of Object.entries(from[section])) {
         const previous = seen[section] && seen[section][key];
         if (previous) {
             const identical = JSON.stringify(into[section][key]) === JSON.stringify(value);
-            if (!agree || !identical) {
-                throw new AggregateError(
-                    `aggregate: '${member}' ${agree && !identical ? "disagrees about" : "redefines"} ` +
-                    `${section}.${key}, already contributed by '${previous}'. ` +
-                    (agree
-                        ? "Members may share a server, but not define it differently."
-                        : "Rename it, or leave it out of the aggregate.")
-                );
+            if (identical) {
+                if (mode === "unique") {
+                    throw new AggregateError(
+                        `aggregate: '${member}' redefines ${label}.${key}, already contributed by '${previous}'. ` +
+                        "Rename it, or leave it out of the aggregate."
+                    );
+                }
+                continue;
+            }
+            if (mode === "reconcile") {
+                reconciled.push({ section, key, winner: previous, loser: member });
+                continue;
             }
-            continue;
+            throw new AggregateError(
+                `aggregate: '${member}' ${mode === "agree" ? "disagrees about" : "redefines"} ` +
+                `${label}.${key}, already contributed by '${previous}'. ` +
+                (mode === "agree"
+                    ? "Members may share a server, but not define it differently."
+                    : "Rename it, or leave it out of the aggregate.")
+            );
         }
         into[section] = into[section] || {};
         into[section][key] = value;
         seen[section] = seen[section] || {};
         seen[section][key] = member;
     }
+    return reconciled;
+}
+
+/** Merges every sub-map of `components` present in `from`, `mode` for each. */
+function mergeComponents(into, from, member, seen, mode) {
+    if (!from.components) return;
+    into.components = into.components || {};
+    seen.components = seen.components || {};
+    for (const sub of Object.keys(from.components)) {
+        into.components[sub] = into.components[sub] || {};
+        seen.components[sub] = seen.components[sub] || {};
+        mergeSection(into.components, from.components, sub, member, seen.components, { mode, label: `components.${sub}` });
+    }
+}
+
+function requireMember(config, target, kind, member) {
+    if (!config.targets[member] || !config.targets[member][kind]) {
+        throw new AggregateError(`target '${target}': aggregate member '${member}' declares no ${kind} bundle`);
+    }
+    if (config.targets[member][kind].aggregate !== undefined) {
+        throw new AggregateError(
+            `target '${target}': aggregate member '${member}' is itself an aggregate; nesting is not supported`
+        );
+    }
+}
+
+function memberDocument(config, target, kind, member) {
+    requireMember(config, target, kind, member);
+    const file = path.join(config.stagingDir(kind), config.targets[member][kind].bundle);
+    if (!fs.existsSync(file)) {
+        throw new AggregateError(`aggregate member '${member}': bundle root not found at ${file}`);
+    }
+    return YAML.parse(fs.readFileSync(file, "utf8"));
+}
+
+function membersOf(config, target, kind) {
+    const members = config.targets[target][kind].aggregate;
+    if (!Array.isArray(members) || members.length === 0) {
+        throw new AggregateError(`target '${target}': ${kind}.aggregate must list at least one target`);
+    }
+    return members;
+}
+
+/** The aggregate's own identity: its own info, or a generated stand-in naming its members. */
+function aggregateInfo(spec, target, members, forKind) {
+    return spec.info || {
+        title: `${target} (aggregate)`,
+        version: "0.0.0",
+        description: forKind === "asyncapi"
+            ? `Every event contract published across ${members.join(", ")}.`
+            : `Every API published across ${members.join(", ")}.`,
+    };
+}
+
+function writeGenerated(out, members, content) {
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(
+        out,
+        `# GENERATED by api-only-publisher from: ${members.join(", ")}\n` +
+        "# Do not edit, and do not commit: it is rebuilt into the staging tree on every build.\n" +
+        YAML.stringify(content)
+    );
 }
 
 /**
@@ -65,54 +174,169 @@ function mergeSection(into, from, section, member, seen, { agree = false } = {})
  */
 function generateAsyncApi(config, target, { log = () => {} } = {}) {
     const spec = config.targets[target].asyncapi;
-    const members = spec.aggregate;
-    if (!Array.isArray(members) || members.length === 0) {
-        throw new AggregateError(`target '${target}': asyncapi.aggregate must list at least one target`);
-    }
+    const members = membersOf(config, target, "asyncapi");
 
     const merged = { asyncapi: null, info: null, servers: {}, channels: {}, operations: {} };
     const seen = {};
 
     for (const member of members) {
-        if (!config.targets[member] || !config.targets[member].asyncapi) {
-            throw new AggregateError(
-                `target '${target}': aggregate member '${member}' declares no asyncapi bundle`
-            );
-        }
-        const file = path.join(config.stagingDir("asyncapi"), config.targets[member].asyncapi.bundle);
-        if (!fs.existsSync(file)) {
-            throw new AggregateError(`aggregate member '${member}': bundle root not found at ${file}`);
-        }
-        const doc = YAML.parse(fs.readFileSync(file, "utf8"));
+        const doc = memberDocument(config, target, "asyncapi", member);
 
         merged.asyncapi = merged.asyncapi || doc.asyncapi;
-        mergeSection(merged, doc, "servers", member, seen, { agree: true });
+        mergeSection(merged, doc, "servers", member, seen, { mode: "agree" });
         mergeSection(merged, doc, "channels", member, seen);
         mergeSection(merged, doc, "operations", member, seen);
     }
 
-    // The aggregate's own identity, not any member's.
-    merged.info = spec.info || {
-        title: `${target} (aggregate)`,
-        version: "0.0.0",
-        description: `Every event contract published across ${members.join(", ")}.`,
-    };
+    merged.info = aggregateInfo(spec, target, members, "asyncapi");
 
-    const out = path.join(config.stagingDir("asyncapi"), spec.bundle);
-    fs.mkdirSync(path.dirname(out), { recursive: true });
-    fs.writeFileSync(
-        out,
-        `# GENERATED by api-only-publisher from: ${members.join(", ")}\n` +
-        `# Do not edit, and do not commit: it is rebuilt into the staging tree on every build.\n` +
-        YAML.stringify(merged)
-    );
+    const out = config.aggregatePath(target, "asyncapi");
+    writeGenerated(out, members, merged);
     log(`-- Generated aggregate ${path.basename(out)} from ${members.join(", ")}`);
     return out;
 }
 
+/**
+ * Synthesise an aggregate OpenAPI bundle root into the staged tree.
+ *
+ * Only what a member's bundle root holds unresolved: paths (prefixed, so keys are
+ * unique by construction -- see openapiPushDown for what happens to the
+ * operations behind them once they are resolved), servers, root-level security,
+ * and every `components.*` sub-map. Tags are carried over as whatever the member
+ * declared -- usually a list of $ref pointers -- and reconciled by name in
+ * openapiPushDown, once bundling has resolved them into `{name, ...}` objects a
+ * $ref pointer never shows.
+ *
+ * @returns {string} the path of the generated bundle root
+ */
+function generateOpenApi(config, target, { log = () => {} } = {}) {
+    const spec = config.targets[target].openapi;
+    const members = membersOf(config, target, "openapi");
+    const prefixPaths = config.portfolioPathStrategy() === "target-prefix";
+
+    const merged = { openapi: null, info: null, servers: {}, tags: [], paths: {}, components: {} };
+    const seen = {};
+    // Recorded here, in pass 1, because only here is it still known which member a
+    // path came from: once paths are merged, one document can no longer tell.
+    const owners = {};
+
+    for (const member of members) {
+        const doc = memberDocument(config, target, "openapi", member);
+
+        merged.openapi = merged.openapi || doc.openapi;
+        mergeSection(merged, doc, "servers", member, seen, { mode: "agree" });
+        mergeComponents(merged, doc, member, seen, "agree");
+        if (Array.isArray(doc.tags)) merged.tags.push(...doc.tags);
+
+        const prefixed = {};
+        for (const [rawPath, item] of Object.entries(doc.paths || {})) {
+            prefixed[prefixPaths ? `/${member}${rawPath}` : rawPath] = item;
+        }
+        mergeSection(merged, { paths: prefixed }, "paths", member, seen);
+        for (const finalPath of Object.keys(prefixed)) {
+            owners[finalPath] = { member, security: doc.security };
+        }
+    }
+    if (Object.keys(merged.components).length === 0) delete merged.components;
+    if (merged.tags.length === 0) delete merged.tags;
+
+    merged.info = aggregateInfo(spec, target, members, "openapi");
+
+    const out = config.aggregatePath(target, "openapi");
+    writeGenerated(out, members, merged);
+    log(`-- Generated aggregate ${path.basename(out)} from ${members.join(", ")}`);
+    return { out, owners };
+}
+
+const SECURITY_NOTE =
+    "Each member's own root-level `security` has been moved onto the operations it contributes " +
+    "-- see each operation's own `security`, and `components.securitySchemes` for what each scheme requires.";
+
+/**
+ * Pass 2: what generateOpenApi could not do until its own output was bundled.
+ * Run on `text` -- the aggregate's *bundled* document -- after every $ref, the
+ * members' and its own, has been resolved.
+ *
+ * - Every operation id is prefixed with its path's member, the same way the path
+ *   itself already was, so two members sharing an operation id -- coincidence,
+ *   not intent -- cannot collide in the portfolio.
+ * - Every member's root-level `security` -- explicit `[]` included -- becomes
+ *   every operation it contributes to's own `security`, unless the operation
+ *   already set one; the portfolio itself keeps no root `security`. See the
+ *   Security section of the README for why: union and intersection are both
+ *   unsound merges of a security requirement, and requiring every member to
+ *   agree would make a landscape where they legitimately differ unbuildable.
+ *   Where anything was pushed down, `info.description` and `x-security-note`
+ *   both say so -- a comment would not survive bundling, so neither carries this.
+ * - Two members contributing the same tag name are one tag; an identical body
+ *   merges silently, a differing one is reported and the first contributor's
+ *   body wins, deterministically.
+ *
+ * Edits the document in place -- `YAML.parseDocument`, never a parse and
+ * re-stringify -- so everything this pass does not touch keeps the bundler's own
+ * formatting exactly, the same reason version.js splices rather than re-emits.
+ *
+ * @returns {{text: string, reconciled: Array<{section: string, key: string}>}}
+ */
+function openapiPushDown(text, owners, { operationIdStrategy = "target-prefix" } = {}) {
+    const doc = YAML.parseDocument(text);
+    const plain = doc.toJS();
+    let pushedDown = false;
+
+    for (const [pathKey, item] of Object.entries(plain.paths || {})) {
+        const owner = owners[pathKey];
+        if (!owner || !item || typeof item !== "object") continue;
+        for (const httpMethod of HTTP_METHODS) {
+            const op = item[httpMethod];
+            if (!op || typeof op !== "object") continue;
+            if (op.operationId && operationIdStrategy === "target-prefix") {
+                doc.setIn(["paths", pathKey, httpMethod, "operationId"], `${pascalCase(owner.member)}${op.operationId}`);
+            }
+            if (op.security === undefined && owner.security !== undefined) {
+                doc.setIn(["paths", pathKey, httpMethod, "security"], owner.security);
+                pushedDown = true;
+            }
+        }
+    }
+
+    if (pushedDown) {
+        const description = doc.getIn(["info", "description"]);
+        doc.setIn(["info", "description"], description ? `${description}\n\n${SECURITY_NOTE}` : SECURITY_NOTE);
+        doc.setIn(["x-security-note"], SECURITY_NOTE);
+    }
+
+    const reconciled = [];
+    if (Array.isArray(plain.tags)) {
+        const byName = new Map();
+        const order = [];
+        for (const tag of plain.tags) {
+            const existing = byName.get(tag.name);
+            if (existing === undefined) {
+                byName.set(tag.name, tag);
+                order.push(tag.name);
+                continue;
+            }
+            if (JSON.stringify(existing) !== JSON.stringify(tag)) {
+                reconciled.push({ section: "tags", key: tag.name });
+            }
+            // The first contributor's body wins either way -- identical or not.
+        }
+        doc.setIn(["tags"], order.map((name) => byName.get(name)));
+    }
+
+    return { text: doc.toString(), reconciled };
+}
+
+/** A target name, in PascalCase: user-account -> UserAccount. */
+function pascalCase(target) {
+    return target.split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+
 function isAggregate(config, target, kind) {
     const spec = config.targets[target][kind];
     return Boolean(spec && spec.aggregate);
 }
 
-module.exports = { generateAsyncApi, isAggregate, AggregateError };
+module.exports = {
+    generateAsyncApi, generateOpenApi, openapiPushDown, isAggregate, mergeSection, pascalCase, AggregateError,
+};

package/src/cli.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 "use strict";
 
+const fs = require("fs");
 const path = require("path");
+const YAML = require("yaml");
 
 const { loadFrom, ConfigError } = require("./config");
 const { build, prepare, BuildError } = require("./pipeline");
 const { init, scaffold, plan } = require("./init");
 const { resolveValues } = require("./init-questions");
+const { resolvePortfolioValues, writePortfolioSection } = require("./config-command");
 const { PlaceholderError } = require("./placeholders");
 const { VersionError } = require("./version");
 const { forTargets, ClosureError } = require("./closure");
@@ -26,6 +29,8 @@ Usage:
                           [--contact-name <text>] [--contact-url <url>]
                           [--license <spdx-id>] [--license-url <url>]
                           [--server-url <url>] [--broker-host <host[:port]>]
+  api-only-publisher config [section] [--yes] [--portfolio-paths <target-prefix|none>]
+                            [--portfolio-location <dir>]
   api-only-publisher build [--target <name>]... [--pre-release <ids>] [--openapi|--asyncapi]
   api-only-publisher lint  [--target <name>]...
   api-only-publisher targets
@@ -44,14 +49,16 @@ Options:
   --asyncapi        Only build AsyncAPI documents.
   --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.
+  -y, --yes         init/config only: ask nothing, even at a terminal; take the
+                    current or default value for anything no flag gives.
   --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.
+  --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
+                    config 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.
@@ -69,13 +76,14 @@ 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: {},
+        yes: false, init: {}, config: {},
     };
     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 CONFIG_VALUES = { "--portfolio-paths": "paths", "--portfolio-location": "location" };
     const positional = [];
 
     for (let i = 0; i < argv.length; i++) {
@@ -109,6 +117,10 @@ function parseArgs(argv) {
                     options.init[INIT_VALUES[arg]] = next();
                     break;
                 }
+                if (CONFIG_VALUES[arg]) {
+                    options.config[CONFIG_VALUES[arg]] = next();
+                    break;
+                }
                 if (arg.startsWith("-")) throw new ConfigError(`unrecognized option '${arg}'`);
                 positional.push(arg);
         }
@@ -136,6 +148,28 @@ function initKinds(kinds) {
     return kinds ? ["openapi", "asyncapi"].filter((kind) => kinds.includes(kind)) : undefined;
 }
 
+/**
+ * Whether init should ask about the portfolio section this run: "ask", once the
+ * library is about to have more than one target -- there is nothing to aggregate
+ * with just one -- and it does not have a portfolio section yet; "present" the
+ * same way, but the section is already there, which init never changes, and
+ * reports rather than silently doing nothing about; "not-yet" while there is
+ * still only one target, which is not worth mentioning at all.
+ *
+ * @returns {"ask"|"present"|"not-yet"}
+ */
+function portfolioStatus(dir, target) {
+    const file = path.join(dir, "apionly.yaml");
+    if (!fs.existsSync(file)) return "not-yet";
+    const doc = YAML.parseDocument(fs.readFileSync(file, "utf8"));
+    if (doc.errors.length > 0) return "not-yet";
+    const targets = doc.get("targets", true);
+    const names = YAML.isMap(targets) ? new Set(targets.items.map((pair) => String(pair.key))) : new Set();
+    names.add(target);
+    if (names.size <= 1) return "not-yet";
+    return doc.hasIn(["portfolio"]) ? "present" : "ask";
+}
+
 /**
  * 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.
@@ -163,19 +197,36 @@ async function runInit(options, positional, io, log) {
             ask: terminal && ((question) => terminal.question(question)),
             tell: (message) => output.write(`${message}\n`),
         });
+
+        // Asked, or defaulted, the same way a kind's own questions are -- but only
+        // once there is something to aggregate. A section already there is never
+        // asked about or changed, and reported as present rather than passed over
+        // in silence.
+        const portfolioStatusThisRun = portfolioStatus(dir, values.target);
+        let portfolio = null;
+        if (portfolioStatusThisRun === "ask") {
+            portfolio = await resolvePortfolioValues({
+                given: options.config,
+                current: { paths: "target-prefix", location: "portfolios" },
+                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");
+            const differing = plan(dir, scaffold(values), values, portfolio).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 });
+        init(dir, { values, force, log, portfolio });
+        if (portfolioStatusThisRun === "present") log("  present    portfolio (already configured; init never changes it)");
         log(`\nNext: api-only-publisher build -C ${dir}`);
     } finally {
         if (terminal) terminal.close();
@@ -183,6 +234,50 @@ async function runInit(options, positional, io, log) {
     return 0;
 }
 
+const CONFIGURABLE_SECTIONS = ["portfolio"];
+
+/**
+ * Reconfigures a section of apionly.yaml. Unlike init, this always asks -- at a
+ * terminal, each question shows what is already configured, or the documented
+ * default when there is nothing yet, and Enter keeps it -- and always rewrites
+ * the keys it asked about, whatever else the section or the file holds.
+ */
+async function runConfig(options, positional, io, log) {
+    const section = positional[1];
+    if (section !== undefined && !CONFIGURABLE_SECTIONS.includes(section)) {
+        throw new ConfigError(
+            `'${section}' is not a configurable section; there is: ${CONFIGURABLE_SECTIONS.join(", ")}`
+        );
+    }
+    const config = loadFrom(options.dir);
+    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 terminal = interactive && !options.yes
+        ? require("node:readline/promises").createInterface({ input, output })
+        : null;
+    try {
+        for (const name of section ? [section] : CONFIGURABLE_SECTIONS) {
+            // The only configurable section today; a second one gets its own current
+            // values, its own given-flags and its own writer, called the same way.
+            const current = { paths: config.portfolioPathStrategy(), location: config.portfolioLocation() };
+            const given = { ...options.config };
+            for (const key of Object.keys(given)) if (given[key] === undefined) delete given[key];
+
+            const values = await resolvePortfolioValues({
+                given, current,
+                ask: terminal && ((question) => terminal.question(question)),
+                tell: (message) => output.write(`${message}\n`),
+            });
+            fs.writeFileSync(config.path, writePortfolioSection(fs.readFileSync(config.path, "utf8"), values));
+            log(`Configured ${name}: paths=${values.paths}, location=${values.location}`);
+        }
+    } finally {
+        if (terminal) terminal.close();
+    }
+    return 0;
+}
+
 async function main(argv, io = {}) {
     const { options, positional } = parseArgs(argv);
     const command = positional[0];
@@ -195,6 +290,7 @@ async function main(argv, io = {}) {
     const log = options.quiet ? () => {} : (message) => console.log(message);
 
     if (command === "init") return runInit(options, positional, io, log);
+    if (command === "config") return runConfig(options, positional, io, log);
 
     const config = loadFrom(options.dir);
     const targets = options.targets.length > 0 ? options.targets : null;
@@ -236,7 +332,6 @@ async function main(argv, io = {}) {
             // Lint without rebuilding, for fast local feedback on what is already
             // in dist/. Every selected document is linted even when one fails, so
             // one run reports every failure rather than only the first.
-            const fs = require("fs");
             const { lint } = require("./pipeline");
             const failures = [];
             let linted = 0;

package/src/closure.js

@@ -104,7 +104,7 @@ function forTargets(config, kinds = ["openapi", "asyncapi"], only = null) {
     for (const kind of kinds) {
         for (const target of config.targetsFor(kind)) {
             if (only && !only.includes(target)) continue;
-            const entry = config.bundlePath(target, kind);
+            const entry = config.bundleRootPath(target, kind);
             if (!fs.existsSync(entry)) {
                 throw new ClosureError(
                     `target '${target}': ${kind} bundle root not found at ${entry}; stage the tree first`