@heroiclands/package-build 23.12.7 → 23.12.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @heroiclands/package-build
 
+## 23.12.8
+
+### Patch Changes
+
+A `packageBuild.assets` row that copies files into `icons/` or `images/` now ships them beside the staged pictures instead of having them erased. A shipped picture whose path matches a file a row already staged is an error, and the row's file is left as it was.
+
 ## 23.12.7
 
 ### Patch Changes

package/docs/authoring/assets.md

@@ -47,7 +47,7 @@ role: portrait
 
 ## What the Foundry package ships
 
-The repository keeps every picture; the Foundry package carries a filtered copy, laid out flat. A picture ships when its record says `ai: false` and its licence is one of `LicenseRef-PublicDomain`, `CC0-1.0`, `CC0`, `CC-BY-3.0`, `CC-BY-4.0`, `CC-BY-SA-4.0` or `LicenseRef-NounProject-Pro`, together with any licence the package adds under `packageBuild.shippingLicenses`. A shipped picture sits at `icons/<basename>` or `images/<basename>` at the package root, whatever directories it is kept in here, and the package's asset set, `asset-sets/default.json`, lists what it ships.
+The repository keeps every picture; the Foundry package carries a filtered copy, laid out flat. A picture ships when its record says `ai: false` and its licence is one of `LicenseRef-PublicDomain`, `CC0-1.0`, `CC0`, `CC-BY-3.0`, `CC-BY-4.0`, `CC-BY-SA-4.0` or `LicenseRef-NounProject-Pro`, together with any licence the package adds under `packageBuild.shippingLicenses`. A shipped picture sits at `icons/<basename>` or `images/<basename>` at the package root, whatever directories it is kept in here, and the package's asset set, `asset-sets/default.json`, lists what it ships. A `packageBuild.assets` row may copy other files under `icons/` or `images/`; the shipped pictures are written beside them, and a row's file at the same path as a shipped picture is an error.
 
 A note may still name a picture the package does not ship. Its compiled document draws the package's stand-in instead — `icons/missing.<ext>` or `images/missing.<ext>`, which you provide as an ordinary human-made picture licensed to ship, addressed `<package>-none-icon-missing` and `<package>-none-image-missing` — and keeps the real picture's address, so a world that holds the real file can point back at it. A package that leaves out a picture a note names, and ships no stand-in of that type, fails the build at the note. See [what a package ships](../reference/format-details.md#what-a-package-ships).
 

package/docs/commands.md

@@ -350,9 +350,16 @@ the shipping list (the default list plus `packageBuild.shippingLicenses`) is cop
 at the package root, through the same transform, and the package's asset set,
 `asset-sets/default.json`, lists what was staged. Everything else stays in the repository. See
 [what a package ships](reference/format-details.md#what-a-package-ships).
-A `packageBuild.assets` row that copies a picture root, a directory inside
-one, or a directory holding one is refused, because it would ship every file
-unfiltered.
+
+The pictures are written beside whatever a `packageBuild.assets` row copied
+into `icons/` or `images/`, and nothing there is removed. A picture whose
+deployed path is already a file a row staged is an error, and no picture is
+staged:
+
+> ``build/stage/images/gate.png: error: `images/gate.png` is already in the stage, copied by a `packageBuild.assets` row; the picture `assets/images/places/gate.png` was not staged over it``
+> A `packageBuild.assets` row that copies a picture root, a directory inside
+> one, or a directory holding one is refused, because it would ship every file
+> unfiltered.
 
 **OPTIONS**
 

package/docs/configuration.md

@@ -1905,6 +1905,13 @@ holding one is refused at the row:
 
 > ``package-build.config.yaml:<line>:<column>: error: `packageBuild.assets[<index>]` copies `<from>`, which reaches assets/images/ — the stage copies the icon and image roots itself, flat and filtered by each file's provenance, so a row copying them would ship every file unfiltered. Remove the row``
 
+A row may still copy other files into `icons/` or `images/` — a subdirectory of
+older art, say. The staged pictures are written beside them and remove nothing.
+A picture whose flat path is already a file a row staged is an error, and the
+file the row staged stays as it is:
+
+> ``<stage>/images/<basename>: error: `images/<basename>` is already in the stage, copied by a `packageBuild.assets` row; the picture `<source>` was not staged over it``
+
 | Key                             | Type                       | Required |
 | ------------------------------- | -------------------------- | -------- |
 | `packageBuild.assets[].from`    | string                     | yes      |

package/docs/reference/format-details.md

@@ -2493,6 +2493,12 @@ layout serves Foundry (`modules/thalorna/images/thorn.webp`), the website's CDN
 (`<cdn base>/thalorna/images/thorn.webp`), and every location a world copies
 the pictures to.
 
+**A row's files are kept.** Staging the pictures writes them beside whatever a
+`packageBuild.assets` row copied under `icons/` or `images/`, such as a
+subdirectory of other art, and removes none of it. A picture whose flat path is
+already a file a row staged is an error, and the row's file stays. Clearing an
+earlier build's pictures is the stage reset's work.
+
 **The package's asset set**, `asset-sets/default.json` under the package
 root, lists what it ships. The name is fixed, so a world always finds the
 package's own set there:

package/e2e.mjs

@@ -799,7 +799,7 @@ export function suiteExecutables(command) {
 }
 
 /** The Chrome for Testing build shared by local and CI Cypress runs. */
-export const CHROME_BUILD_ID = "155.0.8059.84";
+export const CHROME_BUILD_ID = "158.0.8110.0";
 
 /**
  * The browser cache survives reseeding and container teardown.

package/engine/asset-shipping.mjs

@@ -270,6 +270,11 @@ export function assetsManifest(staged, stageDir) {
  * stage before a file is copied: a package whose provenance cannot be read is
  * not one whose shipping can be decided.
  *
+ * The pictures are written beside whatever a `packageBuild.assets` row already
+ * put under `icons/` and `images/`; nothing there is removed. A picture whose
+ * deployed path is already a file in the stage is a finding, and no picture is
+ * written. Clearing an earlier run's pictures is the stage reset's work.
+ *
  * @param {object} opts - Options.
  * @param {string} opts.assetsBase - The package's asset directory, the roots'
  *   parent.
@@ -304,15 +309,24 @@ export function stagePackageAssets({
     if (findings.length) return { staged: [], excluded: [], findings, manifest: null };
 
     const { staged, excluded } = selectStagedAssets(records, shippingLicenses);
-    for (const { root } of DEPLOYED_ASSET_TYPES) {
-        fs.rmSync(path.join(stageDir, root), { recursive: true, force: true });
+    const planned = staged.map((record) => ({
+        record,
+        from: path.join(assetsBase, ...record.asset.path.split("/")),
+        to: path.join(stageDir, .../** @type {string} */ (deployedAssetPath(record)).split("/")),
+    }));
+    for (const { record, from, to } of planned) {
+        if (!fs.existsSync(to)) continue;
+        findings.push({
+            file: to,
+            severity: "error",
+            message:
+                `\`${deployedAssetPath(record)}\` is already in the stage, copied by a ` +
+                `\`packageBuild.assets\` row; the picture \`${path.relative(process.cwd(), from)}\` ` +
+                "was not staged over it",
+        });
     }
-    for (const record of staged) {
-        const from = path.join(assetsBase, ...record.asset.path.split("/"));
-        const to = path.join(
-            stageDir,
-            .../** @type {string} */ (deployedAssetPath(record)).split("/"),
-        );
+    if (findings.length) return { staged: [], excluded: [], findings, manifest: null };
+    for (const { from, to } of planned) {
         fs.mkdirSync(path.dirname(to), { recursive: true });
         const transformed = transform ? transform(from) : null;
         if (transformed != null) fs.writeFileSync(to, transformed);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.12.7",
+    "version": "23.12.8",
     "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",
@@ -160,7 +160,7 @@
         "markdown-it": "^15.0.0",
         "markdown-it-deflist": "^4.0.0",
         "markdown-it-footnote": "^4.0.0",
-        "markdownlint": "^0.41.1",
+        "markdownlint": "^0.42.0",
         "minimatch": "^10.2.6",
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",

package/types/e2e.d.mts

@@ -419,7 +419,7 @@ export function suiteCommand(config: object, mode: "run" | "open"): string[];
 export function e2eRun({ config, packageJson, mode, suiteArgs, env, log, }: {
     config: object;
     packageJson: object;
-    mode?: "open" | "run" | undefined;
+    mode?: "run" | "open" | undefined;
     suiteArgs?: string[] | undefined;
     env?: NodeJS.ProcessEnv | undefined;
     log?: ((message: string) => void) | undefined;
@@ -494,7 +494,7 @@ export const E2E_SCENE_ID: "heroiclandsScene";
 /** How the suite may be run. */
 export const E2E_MODES: readonly string[];
 /** The Chrome for Testing build shared by local and CI Cypress runs. */
-export const CHROME_BUILD_ID: "155.0.8059.84";
+export const CHROME_BUILD_ID: "158.0.8110.0";
 /**
  * The disposable world's identity and credentials.
  */

package/types/engine/address-fields.d.mts

@@ -69,7 +69,7 @@ export type AddressPosition = {
      * - Where the Addresses are.
      * Defaults to `value`.
      */
-    holds?: "keys" | "value" | "items" | undefined;
+    holds?: "keys" | "items" | "value" | undefined;
     /**
      * - Resolve each exact target to its published Item UUID.
      */

package/types/engine/address-values.d.mts

@@ -75,7 +75,7 @@ export class AddressLink {
     constructor(target: object, anchor: string, kind?: "prose" | "event" | null);
     target: object;
     anchor: string;
-    kind: "event" | "prose" | null;
+    kind: "prose" | "event" | null;
 }
 /** The keys of an Address as the published index writes it, and no others. */
 export const PUBLISHED_ADDRESS_KEYS: readonly string[];

package/types/engine/asset-shipping.d.mts

@@ -110,6 +110,11 @@ export function assetsManifest(staged: readonly object[], stageDir: string): Ass
  * stage before a file is copied: a package whose provenance cannot be read is
  * not one whose shipping can be decided.
  *
+ * The pictures are written beside whatever a `packageBuild.assets` row already
+ * put under `icons/` and `images/`; nothing there is removed. A picture whose
+ * deployed path is already a file in the stage is a finding, and no picture is
+ * written. Clearing an earlier run's pictures is the stage reset's work.
+ *
  * @param {object} opts - Options.
  * @param {string} opts.assetsBase - The package's asset directory, the roots'
  *   parent.

package/types/engine/content-format-check.d.mts

@@ -117,7 +117,7 @@ export function checkDeclaredFields({ format, itemFields, system, severity }: {
     format: import("./content-format.mjs").ContentFormat;
     itemFields: Record<string, readonly object[]>;
     system: string;
-    severity?: "error" | "warning" | undefined;
+    severity?: "warning" | "error" | undefined;
 }): {
     findings: object[];
     coverage: object[];

package/types/engine/note-vocabulary.d.mts

@@ -423,7 +423,7 @@ export type DataFieldSpec = {
      * - The anchor kinds an
      * Address here may name with `#<anchor>`. Absent, an anchor is refused.
      */
-    anchors?: readonly ("event" | "prose")[] | undefined;
+    anchors?: readonly ("prose" | "event")[] | undefined;
     /**
      * - The Address names exactly one event: an
      * anchor of kind `event`, or a note holding one event and no more.

package/types/engine/pdf-coverage.d.mts

@@ -37,7 +37,7 @@ export function coverage({ books, corpus, unprinted, mode, locate }: {
     }>;
     corpus: object[];
     unprinted?: object[] | undefined;
-    mode?: "error" | "off" | "warning" | undefined;
+    mode?: "warning" | "error" | "off" | undefined;
     locate?: ((record: object) => {
         file?: string;
         line?: number;

package/types/engine/text-maps.d.mts

@@ -126,7 +126,7 @@ export type MapRow = {
     /**
      * - Where the match must sit.
      */
-    at?: "end" | "start" | undefined;
+    at?: "start" | "end" | undefined;
 };
 /**
  * A map ready to apply.

package/types/release.d.mts

@@ -38,7 +38,7 @@
 export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?: {
     stageDir?: string | undefined;
     outDir?: string | undefined;
-    artifact?: "module" | "system" | undefined;
+    artifact?: "system" | "module" | undefined;
     metadataDir?: string | undefined;
     pdf?: boolean | undefined;
 }): Promise<{