@heroiclands/package-build 25.6.2 → 25.6.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 25.6.3
+
+**Rendering and sites**
+
+- Build a preview at another address with `site build --base-url` and serve its images from another asset root with `--assets`. Pages, links, script fonts and search use the preview prefix, while the package's authored configuration stays unchanged.
+
 ## 25.6.2
 
 **Languages and scripts**

package/bin/content-commands.mjs

@@ -46,7 +46,12 @@ import log from "loglevel";
 import prefix from "loglevel-plugin-prefix";
 import { readStdin } from "../engine/read-stdin.mjs";
 import { compilePacks, cleanPacks, unpackPacks } from "../engine/compendiums.mjs";
-import { compilesFoundryDocuments, publishesContentPages, siteBase } from "../content-config.mjs";
+import {
+    compilesFoundryDocuments,
+    publishesContentPages,
+    siteBase,
+    siteBuildConfig,
+} from "../content-config.mjs";
 import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { buildPdf, listBookAssets } from "../engine/pdf-build.mjs";
 import { summaryLines } from "../engine/pdf-coverage.mjs";
@@ -115,7 +120,7 @@ import {
 } from "../engine/encoding-lexicon.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
 import { lintProse, scoreProseTree } from "../engine/readability-lint.mjs";
-import { loadPackageBuildConfig } from "../config.mjs";
+import { checkHomepage, loadPackageBuildConfig } from "../config.mjs";
 import {
     emitContentIndex,
     prepareContentIndex,
@@ -520,7 +525,7 @@ function withIndexPreflight(command, shouldCheck = () => true) {
         handler: async (argv) => {
             let config;
             try {
-                config = loadPackConfig();
+                config = argv[CONTENT_CONFIG] ?? loadPackConfig();
                 if (shouldCheck(config, argv)) cachedMetadataIndexes(config);
             } catch (err) {
                 if (config) {
@@ -2279,9 +2284,11 @@ function siteCommand() {
         builder: (yargs) =>
             yargs
                 .command(
-                    withIndexPreflight(
-                        withBodyPreflight(siteBuildCommand()),
-                        publishesContentPages,
+                    withSiteBuildConfig(
+                        withIndexPreflight(
+                            withBodyPreflight(siteBuildCommand()),
+                            publishesContentPages,
+                        ),
                     ),
                 )
                 .command(
@@ -2294,6 +2301,29 @@ function siteCommand() {
     };
 }
 
+/** Apply runtime site settings before the index and body preflights. */
+function withSiteBuildConfig(command) {
+    const handler = command.handler;
+    return {
+        ...command,
+        handler: async (argv) => {
+            if (argv.baseUrl === undefined && argv.assets === undefined) return handler(argv);
+            try {
+                const authored = argv[CONTENT_CONFIG] ?? loadPackConfig();
+                checkHomepage(authored.homepage, authored.contentPackage, authored.site.base);
+                const config = siteBuildConfig(authored, {
+                    baseUrl: argv.baseUrl,
+                    assets: argv.assets,
+                });
+                return await handler({ ...argv, [CONTENT_CONFIG]: config });
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * Report what the layouts, or the build's section gate, found about a site.
  *
@@ -2342,10 +2372,21 @@ function siteBuildCommand() {
         command: "build",
         describe: "Render the content tree as a website and index it for search",
         builder: (yargs) =>
-            yargs.option("out", {
-                type: "string",
-                describe: `The directory that is deployed (default: ${DEPLOY_ROOT})`,
-            }),
+            yargs
+                .option("out", {
+                    type: "string",
+                    describe: `The directory that is deployed (default: ${DEPLOY_ROOT})`,
+                })
+                .option("base-url", {
+                    type: "string",
+                    requiresArg: true,
+                    describe: "Absolute HTTP(S) site URL for this build, ending in /",
+                })
+                .option("assets", {
+                    type: "string",
+                    requiresArg: true,
+                    describe: "Absolute HTTP(S) asset root for this build",
+                }),
         handler: async (argv) => {
             try {
                 const config = argv[CONTENT_CONFIG] ?? loadPackConfig();

package/content-config.mjs

@@ -228,6 +228,78 @@ export function siteBase(config) {
     return config.site.base || `/${config.contentPackage}/`;
 }
 
+/**
+ * Apply validated runtime site URLs to a resolved configuration, without changing it.
+ * The caller checks the authored homepage before applying these build options.
+ *
+ * @param {ContentBuildConfig} config - The resolved authored configuration.
+ * @param {object} options - Runtime options.
+ * @param {string} [options.baseUrl] - Absolute HTTP(S) site URL ending in `/`.
+ * @param {string} [options.assets] - Absolute HTTP(S) asset root.
+ * @returns {ContentBuildConfig} The effective configuration, frozen.
+ */
+export function siteBuildConfig(config, { baseUrl, assets }) {
+    if (baseUrl === undefined && assets === undefined) return config;
+    const homepage = baseUrl === undefined ? config.homepage : buildUrl(baseUrl, "--base-url").href;
+    const base =
+        baseUrl === undefined ? config.site.base : normalizeSiteBase(new URL(homepage).pathname);
+    const assetRoot =
+        assets === undefined ?
+            config.site.assets
+        :   normalizeSiteAssets(buildUrl(assets, "--assets").href);
+    checkSiteSitemaps(config.site.sitemaps, base, config.contentPackage);
+    return Object.freeze({
+        ...config,
+        homepage,
+        site: Object.freeze({ ...config.site, base, assets: assetRoot }),
+    });
+}
+
+/**
+ * A runtime web root must survive URL joining and mapping to a local directory.
+ *
+ * @param {string} value - The command-line value.
+ * @param {string} option - The option naming it.
+ * @returns {URL} The checked URL.
+ */
+function buildUrl(value, option) {
+    // URL parsing consumes both literal and escaped dot segments.
+    const rawPath = /^https?:\/\/[^/?#]+([^?#]*)/i.exec(value)?.[1] ?? "";
+    if (
+        rawPath.includes("%") ||
+        rawPath.split("/").some((segment) => segment === "." || segment === "..")
+    ) {
+        throw new TypeError(
+            `${option} must use a plain path without percent escapes or dot segments`,
+        );
+    }
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        throw new TypeError(`${option} must be an absolute HTTP(S) URL`);
+    }
+    if (
+        !/^https?:\/\/[^/]+/i.test(value) ||
+        /[\s\\]/.test(value) ||
+        !["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        value.includes("?") ||
+        value.includes("#") ||
+        url.pathname.includes("//") ||
+        url.pathname.includes("%")
+    ) {
+        throw new TypeError(
+            `${option} must be an absolute HTTP(S) URL with a plain path and no credentials, query or fragment`,
+        );
+    }
+    if (option === "--base-url" && !url.pathname.endsWith("/")) {
+        throw new TypeError(`${option} must end with /`);
+    }
+    return url;
+}
+
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *
@@ -1874,6 +1946,23 @@ function packageSiteList(value, field, contentPackage) {
     );
 }
 
+/**
+ * @param {readonly string[]} sitemaps - The configured package sitemaps.
+ * @param {string} base - The site path.
+ * @param {string} contentPackage - The package id.
+ * @returns {void}
+ */
+function checkSiteSitemaps(sitemaps, base, contentPackage) {
+    if (sitemaps.length && base !== "/") {
+        fail(
+            "site.sitemaps",
+            "names the package sites a sitemap index lists, and a sitemap index and " +
+                "`robots.txt` belong at the root of an origin; this site is served at " +
+                `\`${base || `/${contentPackage}/`}\`, so declare \`site.base: /\` or drop the key`,
+        );
+    }
+}
+
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
@@ -1939,14 +2028,7 @@ function normalizeSite(value, contentPackage) {
     const base = normalizeSiteBase(input.base);
     const search = optionalBoolean(input.search, "site.search", true);
     const sitemaps = packageSiteList(input.sitemaps, "site.sitemaps", contentPackage);
-    if (sitemaps.length && base !== "/") {
-        fail(
-            "site.sitemaps",
-            "names the package sites a sitemap index lists, and a sitemap index and " +
-                "`robots.txt` belong at the root of an origin; this site is served at " +
-                `\`${base || `/${contentPackage}/`}\`, so declare \`site.base: /\` or drop the key`,
-        );
-    }
+    checkSiteSitemaps(sitemaps, base, contentPackage);
     const mergeIndexes = packageSiteList(input.mergeIndexes, "site.mergeIndexes", contentPackage);
     if (mergeIndexes.length && !search) {
         fail(

package/docs/api.md

@@ -2193,20 +2193,21 @@ const config = defineConfig({
 });
 ```
 
-| Export                     | Signature                          | Returns                                                    | Use it when                                                                                                                                                                                                                              |
-| -------------------------- | ---------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `defineConfig`             | `defineConfig(config)`             | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                      |
-| `PACKAGE_KINDS`            | `const PACKAGE_KINDS`              | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two) |
-| `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`         | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                     |
-| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`               | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                      |
-| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`          | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                           |
-| `compilesFoundryDocuments` | `compilesFoundryDocuments(config)` | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                   |
-| `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`        | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                |
-| `DEFAULT_PATHS`            | `const DEFAULT_PATHS`              | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                        |
-| `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`     | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                |
-| `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`     | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
-| `publishesContentPages`    | `publishesContentPages(config)`    | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                  |
-| `siteBase`                 | `siteBase(config)`                 | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                          |
+| Export                     | Signature                                      | Returns                                                    | Use it when                                                                                                                                                                                                                              |
+| -------------------------- | ---------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineConfig`             | `defineConfig(config)`                         | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                      |
+| `PACKAGE_KINDS`            | `const PACKAGE_KINDS`                          | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two) |
+| `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`                     | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                     |
+| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`                           | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                      |
+| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`                      | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                           |
+| `compilesFoundryDocuments` | `compilesFoundryDocuments(config)`             | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                   |
+| `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`                    | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                |
+| `DEFAULT_PATHS`            | `const DEFAULT_PATHS`                          | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                        |
+| `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`                 | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                |
+| `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`                 | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
+| `publishesContentPages`    | `publishesContentPages(config)`                | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                  |
+| `siteBase`                 | `siteBase(config)`                             | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                          |
+| `siteBuildConfig`          | `siteBuildConfig(config, { baseUrl, assets })` | `ContentBuildConfig`                                       | applying optional runtime site URLs to a frozen effective configuration; the caller first validates the authored homepage with `checkHomepage`; the CLI uses it before index/body preflight                                              |
 
 ## `./config`
 

package/docs/commands.md

@@ -2685,7 +2685,7 @@ it for search.
 **SYNOPSIS**
 
 ```
-package-build site build [--out <dir>]
+package-build site build [--out <dir>] [--base-url <url>] [--assets <url>]
 ```
 
 **DESCRIPTION**
@@ -2760,9 +2760,27 @@ run fails before the search index is built.
 
 `--out <dir>` — the directory that is deployed. Defaults to `build/site`.
 
+`--base-url <url>` — the absolute HTTP(S) address of this build. Its pathname
+becomes the effective `site.base`, and must end with `/`; `/` serves the site
+at the origin's root. Pages, local links, theme files, script fonts and search
+all use that prefix. Output lands under `<out>/<pathname>/`.
+
+`--assets <url>` — the absolute HTTP(S) asset root for this build. It may
+include a path; trailing slashes are trimmed.
+
+Both options are optional and independent. Without them, the build uses the
+authored `homepage`, `site.base` and `site.assets`. Overrides apply in memory
+before preflight and rendering; they never rewrite `package.json` or
+`package-build.config.yaml`. The authored homepage must still pass its usual
+validation. Both URLs require plain paths without percent escapes, dot
+segments (`.` or `..`), or doubled slashes, and reject credentials, queries,
+fragments, whitespace and backslashes.
+Invalid overrides fail before output is replaced. A site declaring
+`site.sitemaps` must still be served at `/`.
+
 **EXIT STATUS**
 
-1 if `package.json` declares no `homepage`, or one that does not end
+1 if a runtime URL override is invalid. 1 if `package.json` declares no `homepage`, or one that does not end
 `/<contentPackage>/`; if the site declares no title, description or `assets`
 host; or if the navigation has not been fetched (`package-build deps fetch`
 fills the cache and is named in the message). 1 if any gate fires — no
@@ -2774,6 +2792,15 @@ findings of severity `warning` included.
 
 **EXAMPLES**
 
+```bash
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/pr/thalorna/123/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+```
+
 ```
 $ package-build site build
 […] indexing content

package/docs/configuration.md

@@ -1284,6 +1284,11 @@ site:
   mergeIndexes: [sohl, thalorna, kethira, harnensemble]
 ```
 
+The optional [`site build --base-url` and `--assets` flags](commands.md#package-build-site-build)
+apply runtime overrides to these resolved settings. The base URL supplies the
+effective homepage and `site.base`; the asset URL supplies effective
+`site.assets`. The authored configuration stays unchanged and must be valid.
+
 ### What the site build reads
 
 `package-build site build` composes the site's settings from sources the

package/docs/guides/site.md

@@ -306,6 +306,36 @@ The terminal reports indexing, rendering, writing and search indexing as they
 start, including page counts where available. Progress is on stdout;
 diagnostics retain their file, line and column on stderr.
 
+For an internal main preview, supply the build's address and asset root:
+
+```bash
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+```
+
+For a pull request preview, include the whole prefix:
+
+```bash
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/pr/thalorna/123/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+```
+
+The second build writes to `build/site/pr/thalorna/123/thalorna/`. Its local
+links, theme files, script fonts and search stay under that prefix; its images
+use the supplied asset root. `--out` changes the deployment directory above the
+prefix. Both URL options are optional and independent, and require absolute
+HTTP(S) URLs. The base URL's path ends with `/`; the asset root may include a
+path and has trailing slashes trimmed. Use plain paths without percent escapes,
+dot segments (`.` or `..`), or doubled slashes, credentials, queries or fragments.
+
+The options apply to this build only. Authored `package.json` and YAML stay
+unchanged, and the authored homepage still has to match the configured site.
+Invalid overrides fail before replacing output. A site with `site.sitemaps`
+requires a base URL at the origin's root. See the
+[command reference](../commands.md#package-build-site-build) for URL validation.
+
 ```bash
 package-build site serve
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.6.2",
+    "version": "25.6.3",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -25,6 +25,20 @@ export function siteBase(config: {
         base: string;
     };
 }): string;
+/**
+ * Apply validated runtime site URLs to a resolved configuration, without changing it.
+ * The caller checks the authored homepage before applying these build options.
+ *
+ * @param {ContentBuildConfig} config - The resolved authored configuration.
+ * @param {object} options - Runtime options.
+ * @param {string} [options.baseUrl] - Absolute HTTP(S) site URL ending in `/`.
+ * @param {string} [options.assets] - Absolute HTTP(S) asset root.
+ * @returns {ContentBuildConfig} The effective configuration, frozen.
+ */
+export function siteBuildConfig(config: ContentBuildConfig, { baseUrl, assets }: {
+    baseUrl?: string | undefined;
+    assets?: string | undefined;
+}): ContentBuildConfig;
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *