@heroiclands/package-build 22.0.2 → 22.1.0

package/engine/site-root.mjs

@@ -0,0 +1,165 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The files that belong to a deployment's **root** rather than to the rendered
+ * site.
+ *
+ * Hugo renders into `<out>/<package>/`, because the deployment carries the
+ * `/<package>/` prefix physically and the routing layer is a path-preserving
+ * pass-through. The directory that is *uploaded* is its parent, and Cloudflare
+ * Pages reads `_headers` and `_redirects` from there and nowhere else — a copy
+ * inside the prefix is published as a text file and never applied. Hugo owns
+ * everything under the prefix; this owns what sits beside it.
+ *
+ * **One implementation, because it is one policy.** What is indexable, where
+ * the prefix root sends a reader, and how long that answer is cached are
+ * decisions about the hosting rather than about any one package. Held in each
+ * consumer they are the same file with one constant changed, which is a file
+ * that drifts — and the drift is invisible, because nobody reads all of the
+ * copies at once.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The namespace the routing layer derives a package's origin in.
+ *
+ * `/<package>/` on the public host is proxied to
+ * `https://<package>.<suffix>/<package>/`, and {@link noindexHeaders} depends on
+ * that being a dedicated namespace.
+ *
+ * @type {string}
+ */
+export const ORIGIN_SUFFIX = "pkg.heroiclands.org";
+
+/**
+ * Where a package's landing is served, now that it is an addressed page.
+ *
+ * The site build emits the homepage at its own address rather than as the
+ * site root's `_index.md`, so the prefix root is a redirect to it.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The landing's path.
+ */
+export function landingPath(pkg) {
+    return `/${pkg}/homepage-root/`;
+}
+
+/**
+ * Suppress indexing of every address a deployment answers on but nobody
+ * advertises.
+ *
+ * Cloudflare Pages assigns three: the project's own `pages.dev`, a per-
+ * deployment `pages.dev`, and the custom domain the project carries so the
+ * routing layer has an origin to fetch. None is advertised, all answer with the
+ * same pages, and left alone they are indexed and compete with the canonical
+ * URL in search results.
+ *
+ * The third matters most: it is the address the routing layer fetches, so it is
+ * the host-assigned address a reader is most plausibly handed. The rules are
+ * **scoped to those hostnames**, which keeps this correct for anyone deploying
+ * the site under a domain of their own — there it is indexable, and only the
+ * host-assigned addresses are not.
+ *
+ * @returns {string[]} The header block's lines.
+ */
+export function noindexHeaders() {
+    return [
+        "https://:project.pages.dev/*",
+        "  X-Robots-Tag: noindex",
+        "",
+        "https://:version.:project.pages.dev/*",
+        "  X-Robots-Tag: noindex",
+        "",
+        `https://:package.${ORIGIN_SUFFIX}/*`,
+        "  X-Robots-Tag: noindex",
+        "",
+    ];
+}
+
+/**
+ * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ *
+ * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
+ * responses carry `location` and nothing else — and a 301 with no lifetime is
+ * cached by a browser indefinitely, on the most-linked URL there is. An hour
+ * keeps the 301's canonical signal without the permanence.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string[]} The header block's lines.
+ */
+export function cacheHeaders(pkg) {
+    return [
+        `/${pkg}/`,
+        "  Cache-Control: max-age=3600",
+        "",
+        `/${pkg}`,
+        "  Cache-Control: max-age=3600",
+        "",
+    ];
+}
+
+/**
+ * Both forms of the prefix root, because Pages matches the raw path.
+ *
+ * Redirect matching runs before any trailing-slash or `index.html` handling, so
+ * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
+ * other.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The `_redirects` file's contents.
+ */
+export function redirects(pkg) {
+    const to = landingPath(pkg);
+    return [`/${pkg}/   ${to}   301`, `/${pkg}    ${to}   301`, ""].join("\n");
+}
+
+/**
+ * The `_headers` file's contents.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The file's contents.
+ */
+export function headers(pkg) {
+    return [...noindexHeaders(), ...cacheHeaders(pkg)].join("\n");
+}
+
+/**
+ * Write `_headers` and `_redirects` beside the rendered site.
+ *
+ * @param {object} options - Options.
+ * @param {string} options.pkg - The content package name, which is also the
+ *   directory Hugo rendered into.
+ * @param {string} options.out - The directory that is deployed.
+ * @returns {{files: string[]}} The files written.
+ * @throws {Error} When no rendered site is there, which means the site build
+ *   has not run and writing root files would publish a deployment with nothing
+ *   under the prefix.
+ */
+export function writeSiteRoot({ pkg, out }) {
+    const root = path.resolve(out);
+    const rendered = path.join(root, pkg);
+    if (!fs.existsSync(path.join(rendered, "index.html"))) {
+        throw new Error(
+            `${out}/${pkg}/ holds no rendered site — build the site before its root files`,
+        );
+    }
+
+    const written = [];
+    for (const [name, body] of [
+        ["_headers", headers(pkg)],
+        ["_redirects", redirects(pkg)],
+    ]) {
+        const file = path.join(root, name);
+        fs.writeFileSync(file, body);
+        written.push(file);
+    }
+    return { files: written };
+}

package/engine/svg-theme.mjs

@@ -0,0 +1,140 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * A staged SVG follows the reader's colour scheme.
+ *
+ * An icon drawn as black line art disappears against a dark background, and
+ * Foundry themes its own chrome. So a shape that is explicitly black, or black
+ * by default because it declares no `fill`, gets a rule that paints it the
+ * ink colour for the scheme in use.
+ *
+ * **Named rather than pathed.** `packageBuild.assetTransform: svg-theme`
+ * reaches this module. Every package that themes its icons themes them the same
+ * way — the ink colours are the system's text tokens — so the transform is one
+ * implementation here rather than a copy in each consumer, where the copies
+ * drift and nobody sees all of them at once.
+ *
+ * @module
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Iron-gall ink, and cream against a dark ground.
+ *
+ * These mirror `--sohl-color-text-primary` in the system's
+ * `scss/abstracts/_tokens.scss`. Stated once here, so a token change is one
+ * edit rather than one per consuming repository.
+ *
+ * @type {string}
+ */
+const INK_LIGHT = "#211d16";
+
+/** @type {string} */
+const INK_DARK = "#ece3cf";
+
+/**
+ * The shapes a theme rule may repaint.
+ *
+ * Explicitly black, or black by default for want of a `fill`. A shape painted
+ * some other colour is deliberate — a white highlight in a two-tone badge — and
+ * repainting it would destroy the drawing.
+ *
+ * @type {string}
+ */
+const SELECTOR = [
+    '[fill="#000"]',
+    '[fill="#000000"]',
+    '[fill="black"]',
+    "path:not([fill])",
+    "rect:not([fill])",
+    "circle:not([fill])",
+    "ellipse:not([fill])",
+    "polygon:not([fill])",
+    "polyline:not([fill])",
+    "line:not([fill])",
+    "g:not([fill])",
+].join(",");
+
+/** @type {string} */
+const STYLE =
+    `<style>${SELECTOR}{fill:${INK_LIGHT}}` +
+    `@media(prefers-color-scheme:dark){${SELECTOR}{fill:${INK_DARK}}}</style>`;
+
+/**
+ * Every `style="…"` attribute, capturing its declarations.
+ *
+ * @type {RegExp}
+ */
+const STYLE_ATTR = /style\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+
+/**
+ * A `fill` *declaration* — the property itself, at the start or after a `;`.
+ *
+ * Deliberately not `\bfill\b`, which also matches `fill-rule`, `fill-opacity`
+ * and `paint-order: fill`, none of which set a colour.
+ *
+ * @type {RegExp}
+ */
+const FILL_DECL = /(?:^|;)\s*fill\s*:/i;
+
+/**
+ * Whether any shape sets its fill inline.
+ *
+ * @param {string} svg - The SVG source.
+ * @returns {boolean} Whether an inline `fill` declaration is present.
+ */
+function hasInlineFill(svg) {
+    for (const [, dq, sq] of svg.matchAll(STYLE_ATTR)) {
+        if (FILL_DECL.test(dq ?? sq ?? "")) return true;
+    }
+    return false;
+}
+
+/**
+ * The SVG with a scheme-aware fill rule, or unchanged where one cannot apply.
+ *
+ * Three files are returned as they are. One already carrying a
+ * `prefers-color-scheme` rule is themed — by this pass on an earlier run, or by
+ * its author — and re-theming it would stack rules. One with an inline `fill`
+ * cannot be themed at all, because an inline declaration beats a `<style>` rule
+ * and the result would be a half-recoloured icon, which is worse than an
+ * unthemed one. One with no `<svg>` element is not an SVG.
+ *
+ * @param {string} svg - The SVG source.
+ * @returns {string} The themed source, or the input unchanged.
+ */
+export function injectAdaptiveFill(svg) {
+    if (typeof svg !== "string") return svg;
+    if (svg.includes("prefers-color-scheme")) return svg;
+    if (hasInlineFill(svg)) return svg;
+
+    const open = svg.match(/<svg\b[^>]*>/i);
+    if (!open) return svg;
+
+    const at = open.index + open[0].length;
+    return svg.slice(0, at) + STYLE + svg.slice(at);
+}
+
+/**
+ * The staging hook: theme an SVG, and pass everything else through untouched.
+ *
+ * @param {string} sourcePath - The file being staged.
+ * @returns {string|null} The themed source, or `null` to stage the file as it
+ *   is — which is what every non-SVG asset gets.
+ */
+export function transform(sourcePath) {
+    if (!sourcePath.endsWith(".svg")) return null;
+    return injectAdaptiveFill(readFileSync(sourcePath, "utf8"));
+}

package/manifest.mjs

@@ -28,9 +28,10 @@
  *
  * - **Declared** — the `packageBuild.manifest` block, emitted unchanged, so a
  *   key Foundry adds in a later version needs no release of this package.
- * - **Derived** — the identity, the version, the release addresses, the
- *   compatibility ranges and the pack list. Declaring one of these is an error
- *   rather than an override: the authored copy would be silently overwritten.
+ * - **Derived** — the identity, the description, the version, the release
+ *   addresses, the compatibility ranges and the pack list. Declaring one of
+ *   these is an error rather than an override: the authored copy would be
+ *   silently overwritten.
  * - **Computed** — namespaced `flags` a repository works out for itself.
  *
  * **Nothing here invents an address.** The repository URL is read from
@@ -459,10 +460,10 @@ function withoutBuildKeys(entry) {
  *
  * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
  *   a key Foundry adds later needs no release of this package.
- * - **Derived** — the identity, the release addresses, the version, the Foundry
- *   and system compatibility ranges, and the pack list. These are refused if
- *   also declared: an authored copy would be overwritten and the two would
- *   disagree with nothing to say so.
+ * - **Derived** — the identity, the description, the release addresses, the
+ *   version, the Foundry and system compatibility ranges, and the pack list.
+ *   These are refused if also declared: an authored copy would be overwritten
+ *   and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
@@ -492,6 +493,10 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
             artifact,
         }),
     };
+    // Own-property presence, not just value, decides whether a key survives
+    // into `ordered` below — an explicit `undefined` would still occupy a slot
+    // in it. Set only when `package.json` actually declares one.
+    if (packageJson.description !== undefined) derived.description = packageJson.description;
     if (config.compatibility) derived.compatibility = config.compatibility;
 
     // `requiresSystem` is the gate half of the declare/require split. It

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.0.2",
+    "version": "22.1.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -147,6 +147,7 @@
         "markdown-it": "^15.0.0",
         "markdownlint-cli2": "^0.23.2",
         "prettier": "^3.9.6",
+        "smol-toml": "^1.7.0",
         "ssh2-sftp-client": "^12.1.1",
         "typescript": "^6.0.3",
         "unidecode": "^1.1.0",

package/stage.mjs

@@ -42,9 +42,10 @@ import path from "node:path";
 /**
  * Directories every HeroicLands repository regenerates and none commits.
  *
- * A repository adds its own — `sohl-thalorna` also clears the Hugo output
- * beneath `site/` — but these four are common to all of them because they come
- * from the shared toolchain rather than from any one package's layout.
+ * A repository adds its own through `packageBuild.clean.extra`, but these four
+ * are common to all of them because they come from the shared toolchain rather
+ * than from any one package's layout. Everything the site build writes — the
+ * Hugo source tree, Hugo's cache and the rendered site — is under `build/`.
  */
 export const BUILD_ARTIFACT_DIRS = Object.freeze(["build", ".vite", ".vitepress", ".rollup.cache"]);
 

package/types/config.d.mts

@@ -1,3 +1,77 @@
+/**
+ * Where a declared `assetTransform` is loaded from.
+ *
+ * A built-in name resolves to the module this package ships. Anything else is a
+ * path, resolved against the repository root the way it always was — so a
+ * consumer with a transform of its own is unaffected.
+ *
+ * @param {string} declared - The authored value.
+ * @param {string} rootDir - The repository root.
+ * @returns {string} An absolute path to import.
+ */
+export function resolveAssetTransform(declared: string, rootDir: string): string;
+/**
+ * `package.json`'s `homepage`, checked against the address it must be.
+ *
+ * A package's Foundry manifest already derives its own `url` from
+ * `contentPackage` (`packageHomepage` in `manifest.mjs`); `homepage` states
+ * the same address a second time, in `package.json`, for the generated Hugo
+ * configuration to read a `baseURL` from without knowing where each
+ * repository keeps its own site configuration.
+ *
+ * Required unconditionally: every package publishes a site, so there is no
+ * package this does not apply to.
+ *
+ * **Not called by {@link resolvePackageBuildConfig}.** Every packaging
+ * command — `clean`, `deploy`, `manifest` and the rest — resolves through it,
+ * and none of them reads `homepage`: the Foundry manifest's own `url` is
+ * `packageHomepage(contentPackage)`, independent of it. The right caller is
+ * whatever reads `homepage` to write a site's `baseURL`.
+ *
+ * @param {string|null} homepage - The resolved `package.json` `homepage`, or
+ *   `null` when none is declared.
+ * @param {string} contentPackage - The resolved `contentPackage`.
+ * @returns {void}
+ */
+export function checkHomepage(homepage: string | null, contentPackage: string): void;
+/**
+ * Resolve a package-build configuration from an already-loaded shared one.
+ *
+ * Separate from {@link loadPackageBuildConfig} because this half is pure: it
+ * reads no file and touches no environment, so the validation rules can be
+ * described directly by a test instead of through a fixture repository on
+ * disk. {@link loadPackageBuildConfig} is the same function with the loading
+ * put back.
+ *
+ * @param {object} shared - The resolved content configuration.
+ * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
+ * @throws {TypeError} When the reserved section declares something malformed.
+ */
+export function resolvePackageBuildConfig(shared: object): Readonly<PackageBuildConfig>;
+/**
+ * The repository's resolved package-build configuration.
+ *
+ * Read on call rather than at import, exactly as content-build resolves its
+ * own: importing a module of this package must not require a configuration to
+ * exist anywhere above it.
+ *
+ * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
+ * @throws {TypeError} When there is no configuration, or the reserved section
+ *   declares something malformed.
+ */
+export function loadPackageBuildConfig(): Readonly<PackageBuildConfig>;
+/**
+ * Manifest keys a repository may **not** declare, because the build derives
+ * them and would only overwrite what was written.
+ *
+ * Silently overwriting is the failure this list exists to prevent: a
+ * `version` typed into the configuration would look authoritative, sit there
+ * unread, and disagree with the shipped package forever. Declaring one is an
+ * error naming the key and where the value actually comes from.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
 /**
  * The resolved `packageBuild` section, every optional half filled in.
  *
@@ -65,43 +139,16 @@
  *   collections, as collection → source directory.
  */
 /**
- * Resolve a package-build configuration from an already-loaded shared one.
- *
- * Separate from {@link loadPackageBuildConfig} because this half is pure: it
- * reads no file and touches no environment, so the validation rules can be
- * described directly by a test instead of through a fixture repository on
- * disk. {@link loadPackageBuildConfig} is the same function with the loading
- * put back.
- *
- * @param {object} shared - The resolved content configuration.
- * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
- * @throws {TypeError} When the reserved section declares something malformed.
- */
-export function resolvePackageBuildConfig(shared: object): Readonly<PackageBuildConfig>;
-/**
- * The repository's resolved package-build configuration.
- *
- * Read on call rather than at import, exactly as content-build resolves its
- * own: importing a module of this package must not require a configuration to
- * exist anywhere above it.
- *
- * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
- * @throws {TypeError} When there is no configuration, or the reserved section
- *   declares something malformed.
- */
-export function loadPackageBuildConfig(): Readonly<PackageBuildConfig>;
-/**
- * Manifest keys a repository may **not** declare, because the build derives
- * them and would only overwrite what was written.
+ * The asset transforms this package ships, by the name a consumer writes.
  *
- * Silently overwriting is the failure this list exists to prevent: a
- * `version` typed into the configuration would look authoritative, sit there
- * unread, and disagree with the shipped package forever. Declaring one is an
- * error naming the key and where the value actually comes from.
+ * `packageBuild.assetTransform` takes either one of these names or a path to a
+ * module of the consumer's own. A name is the answer where every package wants
+ * the same behaviour — theming an icon to the reader's colour scheme is not a
+ * per-package decision, and a copy in each consumer is a copy that drifts.
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
+export const BUILT_IN_ASSET_TRANSFORMS: Readonly<Record<string, string>>;
 /**
  * One staging copy: a source path in the repository, and where it lands under
  * the staged package root.

package/types/content-config.d.mts

@@ -73,6 +73,7 @@ export namespace DEFAULT_PATHS {
     let unpack: "build/tmp/packs";
     let foreignCache: "build/cache/foreign";
     let metadataCache: "build/cache/metadata";
+    let navigationCache: "build/cache/navigation";
 }
 /**
  * The Foundry document types a compendium pack may hold. This is the set the
@@ -175,6 +176,20 @@ export const SITE_MODES: readonly ["homepage", "content"];
  * @type {symbol}
  */
 export const DERIVED_SYSTEM_VERSION: symbol;
+/**
+ * Hugo keys a repository may **not** declare under `site.hugo`, because the
+ * site build generates them and would only overwrite what was written.
+ *
+ * The same rule `DERIVED_MANIFEST_KEYS` states for the manifest, for the same
+ * reason: an authored `baseURL` would look authoritative, sit there unread,
+ * and disagree with the site forever. Each key names where its value comes
+ * from. A dotted key names a nested one, and covers everything beneath it —
+ * `params.brand` refuses `params.brand.logo` too — so `site.hugo` reaches only
+ * what the generator does not write.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_HUGO_KEYS: Readonly<Record<string, string>>;
 /**
  * How much of a package reaches the web.
  *
@@ -339,6 +354,11 @@ export type PathsInput = {
      *     only those supplying a catalogue.
      */
     metadataCache?: string | undefined;
+    /**
+     * Where the site navigation is fetched
+     *   to, for the generated Hugo menu.
+     */
+    navigationCache?: string | undefined;
 };
 /**
  * {@link PathsInput}, resolved to absolute paths against `rootDir`.
@@ -352,6 +372,7 @@ export type ResolvedPaths = {
     unpack: string;
     foreignCache: string;
     metadataCache: string;
+    navigationCache: string;
 };
 /**
  * The identity every compiled document's `_stats` block carries.
@@ -590,6 +611,22 @@ export type ContentBuildConfigInput = {
      *       package.
      */
     foundryPackage?: string | undefined;
+    /**
+     * `package.json`'s own `homepage` —
+     *             the site build's `baseURL`. Checked
+     *             by `checkHomepage` in
+     *             `config.mjs`.
+     */
+    homepage?: string | undefined;
+    /**
+     * `package.json`'s own `author`, in
+     * either of npm's forms.
+     */
+    author?: string | {
+        name: string;
+        email?: string;
+        url?: string;
+    } | undefined;
     /**
      * Whether the package is a system, a
      * module, or documentation — the kind
@@ -683,6 +720,22 @@ export type ContentBuildConfig = {
      * package, which ships no Foundry package.
      */
     foundryPackage: string | null;
+    /**
+     * `package.json`'s own `homepage`,
+     * checked by `checkHomepage` in
+     * `config.mjs`.
+     */
+    homepage: string | null;
+    /**
+     *                                     `package.json`'s own `author`, normalised
+     *                                     from either of npm's forms; `null` when
+     *                                     the package declares none.
+     */
+    author: Readonly<{
+        name: string;
+        email?: string;
+        url?: string;
+    }> | null;
     packageKind: PackageKind;
     /**
      * Derived, and **conditional**: the served

package/types/engine/site-build.d.mts

@@ -105,8 +105,8 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * has. Nothing is written at `/<package>/` itself: that becomes a redirect the
  * package's own repository authors, which is a routing fact rather than a page.
  *
- * @param {string} outRoot - The package's site root — the configured `site.out`,
- *   one level above the content mount.
+ * @param {string} outRoot - The package's site root — the content mount's
+ *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
@@ -379,26 +379,6 @@ export function resolveSitePass(name: string | undefined, options: object): {
     beforeLinks?: Function;
     afterLinks?: Function;
 };
-/**
- * The output root, having established that it is safe to delete.
- *
- * The whole tree is a build artifact and is wiped on every run, so this
- * resolution is the difference between clearing a build directory and clearing
- * the repository. An unset `site.out` resolves to `rootDir` itself, and the
- * wipe then deletes the working tree — which is not a hypothetical: it happened
- * while this module was being written, on a configuration that simply had no
- * `site` section yet.
- *
- * So the path is refused unless it is **strictly inside** the repository root.
- * Both failing shapes are ordinary rather than exotic — an absent setting, and a
- * `..` that climbs out — and neither should be recoverable by being careful.
- *
- * @param {string} rootDir - The repository root.
- * @param {string} out - The configured `site.out`.
- * @returns {string} The absolute output root.
- * @throws {Error} When it is unset, or is not below `rootDir`.
- */
-export function resolveOutputRoot(rootDir: string, out: string): string;
 /**
  * Builds a Hugo content tree from a content tree, and reports what it found.
  *
@@ -410,7 +390,6 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  * @param {object} [options] - Options.
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
- * @param {string} [options.outRoot] - Override the configured output mount.
  * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
  *   keyed by the note's absolute file, from
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
@@ -419,9 +398,8 @@ export function resolveOutputRoot(rootDir: string, out: string): string;
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
  */
-export function buildSite({ config, outRoot, sqlTables }?: {
+export function buildSite({ config, sqlTables }?: {
     config?: object | undefined;
-    outRoot?: string | undefined;
     sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;