@heroiclands/package-build 17.1.0 → 18.0.0

package/manifest.mjs

@@ -53,6 +53,7 @@ import fsSync from "node:fs";
 import path from "node:path";
 
 import { emitDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
+import { metadataFileName } from "./engine/metadata-index.mjs";
 
 /**
  * The two package kinds Foundry defines, as the artifact name each one's
@@ -97,7 +98,7 @@ export function normalizeRepoUrl(repository) {
 }
 
 /**
- * The four addresses a Foundry manifest advertises.
+ * The addresses a Foundry manifest advertises.
  *
  * `manifest` deliberately points at **`releases/latest`** rather than at this
  * version: it is the URL an *installed* package re-fetches to discover that a
@@ -120,6 +121,26 @@ export function releaseUrls({ repoUrl, version, artifact }) {
     };
 }
 
+/**
+ * Where this release publishes its content index (#239).
+ *
+ * **Pinned to this version, like `download` and unlike `manifest`.** A
+ * consumer reaches this URL by reading the dependency's manifest, so the
+ * manifest it read and the index it then fetches describe the same release —
+ * which is the whole point of publishing them together. A `releases/latest`
+ * index would silently pair a pinned manifest with a moving index, and the
+ * mismatch would surface as a cross-package link that resolved yesterday.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.version - The version being built.
+ * @param {string} opts.contentPackage - The content package name.
+ * @returns {string} The version-pinned asset URL.
+ */
+export function metadataUrl({ repoUrl, version, contentPackage }) {
+    return `${repoUrl}/releases/download/v${version}/${metadataFileName(contentPackage)}`;
+}
+
 /**
  * The order the manifest's keys are written in.
  *
@@ -455,8 +476,28 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
 
     const merged = { ...declared, ...derived };
 
+    // The index every consumer resolves this package's addresses through
+    // (#239). Written unconditionally, because a package that publishes no
+    // index is one nothing can link into — and the failure of an absent one is
+    // a dead link in somebody else's build, which is exactly the kind of
+    // silence this replaced the vendored manifest to end.
+    //
+    // A flag rather than a top-level key because Foundry's manifest schema is
+    // closed and `flags` is its declared extension point; an unknown key at the
+    // top level is dropped by some readers and rejected by others.
+    if (config.contentPackage) {
+        merged.flags = {
+            ...(declared.flags ?? {}),
+            metadataUrl: metadataUrl({
+                repoUrl,
+                version: packageJson.version,
+                contentPackage: config.contentPackage,
+            }),
+        };
+    }
+
     if (flags && Object.keys(flags).length) {
-        merged.flags = { ...(declared.flags ?? {}) };
+        merged.flags = { ...(merged.flags ?? declared.flags ?? {}) };
         for (const [namespace, values] of Object.entries(flags)) {
             merged.flags[namespace] = {
                 ...(declared.flags?.[namespace] ?? {}),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "17.1.0",
+    "version": "18.0.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",
@@ -27,6 +27,14 @@
             "types": "./types/sohl/*.d.mts",
             "import": "./sohl/*.mjs"
         },
+        "./hm3": {
+            "types": "./types/hm3/index.d.mts",
+            "import": "./hm3/index.mjs"
+        },
+        "./hm3/*": {
+            "types": "./types/hm3/*.d.mts",
+            "import": "./hm3/*.mjs"
+        },
         "./content-config": {
             "types": "./types/content-config.d.mts",
             "import": "./content-config.mjs"
@@ -105,8 +113,10 @@
         "deploy.mjs",
         "e2e.mjs",
         "engine",
+        "hm3",
         "index.mjs",
         "lang.mjs",
+        "labels.mjs",
         "manifest.mjs",
         "markdownlint-config.mjs",
         "prettier-config.mjs",
@@ -117,11 +127,14 @@
         "types"
     ],
     "dependencies": {
+        "@duckdb/node-api": "^1.5.5-r.4",
         "@foundryvtt/foundryvtt-cli": "^3.0.4",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
         "classic-level": "^3.0.0",
         "dotenv": "^17.2.3",
+        "eslint": "^10.10.0",
+        "eslint-plugin-yml": "^3.8.1",
         "fflate": "^0.8.3",
         "glob": "^13.0.6",
         "gray-matter": "^4.0.3",
@@ -149,12 +162,14 @@
         "build:types": "tsc -p tsconfig.dts.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "lint": "npm run format:check && npm run lint:markdown && npm run lint:content-format",
+        "lint": "npm run format:check && npm run lint:markdown && npm run lint:yaml && npm run lint:labels && npm run lint:content-format",
         "lint:markdown": "node bin/content-build.mjs markdown",
+        "lint:yaml": "node bin/package-build.mjs yaml",
+        "lint:labels": "node bin/package-build.mjs labels check",
         "lint:markdown:fix": "node bin/content-build.mjs markdown --fix",
         "lint:content-format": "npm run lint:content-format:schema && npm run lint:content-format:fields",
-        "lint:content-format:schema": "node bin/content-build.mjs content-format schema --schema sohl=tests/fixtures/content-format/schema-sohl.json",
-        "lint:content-format:fields": "node bin/content-build.mjs content-format fields --fields sohl",
+        "lint:content-format:schema": "node bin/content-build.mjs content-format schema --schema sohl=tests/fixtures/content-format/schema-sohl.json --schema hm3=tests/fixtures/content-format/schema-hm3.json",
+        "lint:content-format:fields": "node bin/content-build.mjs content-format fields --fields sohl && node bin/content-build.mjs content-format fields --fields hm3",
         "changeset": "changeset",
         "changeset:check": "changeset status --since=origin/main",
         "changeset:version": "changeset version && npm install --package-lock-only",

package/release.mjs

@@ -16,10 +16,12 @@
  * carries.
  *
  * Foundry installs a package by fetching the `download` URL its manifest
- * advertises, so a release publishes exactly two assets: `<artifact>.zip`, the
- * whole staged tree, and `<artifact>.json` beside it, which is what an already
- * installed package re-fetches to notice a new version. Both names are fixed by
- * what the manifest says, not chosen here — see `manifest.mjs`.
+ * advertises, so a release publishes `<artifact>.zip`, the whole staged tree,
+ * and `<artifact>.json` beside it, which is what an already installed package
+ * re-fetches to notice a new version. A package that ships content publishes a
+ * third: the content index other packages resolve its addresses through (#239),
+ * named by the `flags.metadataUrl` the manifest advertises. Every name is fixed
+ * by what the manifest says, not chosen here — see `manifest.mjs`.
  *
  * Kept apart from `stage.mjs` because this is the only part of assembling a
  * package that needs a dependency. A repository that never cuts a release from
@@ -53,9 +55,12 @@ import { ZipArchive } from "archiver";
  * @param {string} [opts.outDir] - Where the release assets are written.
  * @param {"system"|"module"} [opts.artifact] - Which artifact is shipped.
  *   Determines both asset names.
- * @returns {Promise<{zip: string, manifest: string, bytes: number,
- *   version: string}>} The two paths written, the archive's size, and the
- *   version the manifest declares.
+ * @param {string} [opts.metadataDir] - Where the build writes its content
+ *   index, consulted when the advertised file was not staged.
+ * @returns {Promise<{zip: string, manifest: string, metadata?: string,
+ *   bytes: number, version: string}>} The paths written, the archive's size,
+ *   and the version the manifest declares. `metadata` is absent when the
+ *   manifest advertises no content index.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -63,6 +68,7 @@ export async function packRelease({
     stageDir = "build/stage",
     outDir = "build/dist",
     artifact = "system",
+    metadataDir = "build/content-index",
 } = {}) {
     const stage = path.resolve(stageDir);
     const out = path.resolve(outDir);
@@ -104,10 +110,59 @@ export async function packRelease({
 
     await fsp.copyFile(stagedManifest, path.join(out, manifestName));
 
+    const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
+
     return {
         zip: zipPath,
         manifest: path.join(out, manifestName),
+        ...(metadata ? { metadata } : {}),
         bytes: archive.pointer(),
         version: manifest.version,
     };
 }
+
+/**
+ * Place the content index the manifest advertises beside the archive (#239).
+ *
+ * **The asset's name comes from the manifest, not from here.** `flags.metadataUrl`
+ * is the URL every consumer fetches, so its basename is by definition the name
+ * the file has to be published under — deriving it a second time would let the
+ * two disagree, and a release whose asset is named differently from its
+ * advertised URL fails at the consumer, not here.
+ *
+ * A manifest that advertises no index publishes none: a package with no content
+ * tree has nothing to index, and is perfectly releasable. But a manifest that
+ * *does* advertise one and cannot produce it is a build error. The alternative
+ * is a release that promises an index it does not carry, whose symptom is a
+ * dead cross-package link in somebody else's build weeks later — the silent
+ * failure the vendored manifest was replaced to end.
+ *
+ * @param {object} opts
+ * @param {object} opts.manifest - The parsed staged manifest.
+ * @param {string} opts.stage - The staged tree.
+ * @param {string} opts.out - Where release assets are written.
+ * @param {string} opts.metadataDir - Where the build writes its index, tried
+ *   when the file was not staged.
+ * @returns {Promise<string|undefined>} The published path, or nothing when the
+ *   manifest advertises no index.
+ * @throws {Error} When one is advertised and no file backs it.
+ */
+async function publishMetadataIndex({ manifest, stage, out, metadataDir }) {
+    const url = manifest.flags?.metadataUrl;
+    if (!url) return undefined;
+
+    const name = path.basename(new URL(url, "https://example.invalid").pathname);
+    const candidates = [path.join(stage, name), path.resolve(metadataDir, name)];
+    const found = candidates.find((c) => fs.existsSync(c));
+    if (!found) {
+        throw new Error(
+            `the manifest advertises ${name} as \`flags.metadataUrl\` but no such ` +
+                `file exists — looked in ${candidates.join(" and ")}. Build the ` +
+                `content index before packing the release.`,
+        );
+    }
+
+    const dest = path.join(out, name);
+    await fsp.copyFile(found, dest);
+    return dest;
+}