@heroiclands/package-build 23.1.0 → 23.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 23.1.1
+
+### Patch Changes
+
+`package-build yaml` accepts an empty trigger such as `workflow_dispatch:` in a Gitea workflow under `.gitea/workflows/`, as it already does under `.github/workflows/`.
+
+Rebuilding a release of the same commit produces an identical `module.zip` or `system.zip`, so a rebuilt archive can be compared with the one already published. Setting `SOURCE_DATE_EPOCH` stamps the archive's files with that time.
+
 ## 23.1.0
 
 ### Minor Changes

package/docs/guides/release-and-deploy.md

@@ -105,12 +105,28 @@ change is minor; an optional command, flag, or key is patch. A major bump
 requires the maintainer's direct decision. `package-build changelog check`
 checks the quality of any pending changeset.
 
-Merging a changeset to `main` makes the **Version Packages** pull request. Its
-generated changelog section is reviewed as the release note. Merging that
-pull request runs the **Publish to npm** workflow: npm Trusted Publishing
-publishes the version, and the workflow creates its version tag and GitHub
-Release. The workflow's manual dispatch can retry publishing a version already
-merged to `main`. The [npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
+The repository's primary forge is Gitea, and GitHub is its push mirror. The
+release runs in two halves, one on each:
+
+1. **Version, on Gitea.** Merging a changeset to `main` runs
+   `.gitea/workflows/release.yml`, which opens or updates the **Version
+   Packages** pull request. Its generated changelog section is reviewed as the
+   release note. Merging that pull request runs the same workflow again, which
+   pushes the tag `v<version>` at the merged version commit. Releasing from
+   Gitea is switched on by the repository variable `HL_RELEASE_ENABLED`.
+2. **Publish, on GitHub.** The push mirror carries the tag to GitHub, where it
+   starts the **Publish to npm** workflow, `.github/workflows/release.yml`. It
+   refuses a tag that names a commit outside `main` or that is not
+   `v<version>` of the tagged `package.json`. When npm does not have the
+   version yet, it runs the tests and publishes through npm Trusted Publishing
+   with provenance. It then creates the GitHub Release from the version's
+   changelog section, unless one exists.
+
+Nothing on Gitea publishes to npm, and nothing on GitHub runs for a branch
+push. Every step of the GitHub half is safe to repeat: re-running it, or
+dispatching it with the tag as its ref, finishes a release whose publish or
+Release step failed and changes nothing for one that completed. The
+[npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
 shows the published version and README.
 
 Two scripts in this repository's own `package.json` run the same steps at a

package/engine/yaml-lint.mjs

@@ -104,10 +104,11 @@ export const frontmatterProcessor = {
  * - `no-empty-key`, `no-empty-document` — a fence or a file that parses to
  *   nothing at all.
  *
- * **GitHub workflows are exempt from `no-empty-mapping-value`**, because an
- * empty value is the language there: `on:` `push:` and `workflow_dispatch:`
- * carry their meaning by being present, and writing `push: null` to satisfy a
- * linter would be worse YAML, not better.
+ * **Workflows are exempt from `no-empty-mapping-value`**, under
+ * `.github/workflows/` and Gitea's `.gitea/workflows/` alike, because an empty
+ * value is the language there: `on:` `push:` and `workflow_dispatch:` carry
+ * their meaning by being present, and writing `push: null` to satisfy a linter
+ * would be worse YAML, not better.
  *
  * @param {object} plugin - The `eslint-plugin-yml` module.
  * @returns {object[]} A complete flat config, for `overrideConfig`.
@@ -128,6 +129,8 @@ export function yamlLintConfig(plugin) {
             files: [
                 "**/.github/workflows/*.yml",
                 "**/.github/workflows/*.yaml",
+                "**/.gitea/workflows/*.yml",
+                "**/.gitea/workflows/*.yaml",
                 "**/action.yml",
                 "**/action.yaml",
             ],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.1.0",
+    "version": "23.1.1",
     "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",

package/release.mjs

@@ -45,6 +45,60 @@ import { ZipArchive } from "archiver";
 
 import { SCHEMA_ARTIFACT_FILE } from "./engine/foreign-catalog.mjs";
 
+/** The earliest instant a zip entry's date field can hold. */
+const ZIP_EPOCH_MS = Date.UTC(1980, 0, 1);
+
+/**
+ * The timestamp stamped on every archive entry: `SOURCE_DATE_EPOCH` (seconds)
+ * when set to a number, otherwise 1980-01-01T00:00:00Z. A value earlier than
+ * 1980 is raised to it, which is as early as a zip can record.
+ *
+ * @returns {Date}
+ */
+function archiveDate() {
+    const seconds = Number(process.env.SOURCE_DATE_EPOCH);
+    const ms =
+        process.env.SOURCE_DATE_EPOCH && Number.isFinite(seconds) ? seconds * 1000 : ZIP_EPOCH_MS;
+    return new Date(Math.max(ms, ZIP_EPOCH_MS));
+}
+
+/**
+ * Append a directory tree to an archive in path order, with a fixed date and
+ * fixed permissions (0755 directories, 0644 files) so the bytes depend only on
+ * the tree's names and contents.
+ *
+ * Entries are appended one at a time from buffers: archiver's own directory
+ * walk stats files concurrently, so its entry order and recorded mtimes follow
+ * the filesystem.
+ *
+ * @param {import("archiver").ZipArchive} archive
+ * @param {string} root - The directory whose contents become the archive.
+ * @param {Date} date - The date recorded on every entry.
+ * @returns {Promise<void>}
+ */
+async function appendTree(archive, root, date) {
+    /** @param {string} rel - Path relative to `root`, `/`-separated, or "". */
+    async function walk(rel) {
+        const entries = await fsp.readdir(path.join(root, rel), { withFileTypes: true });
+        entries.sort((a, b) =>
+            a.name < b.name ? -1
+            : a.name > b.name ? 1
+            : 0,
+        );
+        for (const entry of entries) {
+            const name = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                archive.append(Buffer.alloc(0), { name: `${name}/`, date, mode: 0o755 });
+                await walk(name);
+            } else {
+                const body = await fsp.readFile(path.join(root, name));
+                archive.append(body, { name, date, mode: 0o644 });
+            }
+        }
+    }
+    await walk("");
+}
+
 /**
  * Zip the staged tree and place the manifest beside the archive.
  *
@@ -55,6 +109,10 @@ import { SCHEMA_ARTIFACT_FILE } from "./engine/foreign-catalog.mjs";
  * failure is timing-dependent, so it survives every run that happens to be
  * fast enough, which is what makes it worth being explicit about.
  *
+ * **The archive is reproducible.** Entries are written in path order with one
+ * date (`SOURCE_DATE_EPOCH` when set, otherwise 1980-01-01) and fixed
+ * permissions, so a rebuild of one staged tree is byte-identical.
+ *
  * @param {object} [opts]
  * @param {string} [opts.stageDir] - The staged package tree.
  * @param {string} [opts.outDir] - Where the release assets are written.
@@ -114,10 +172,10 @@ export async function packRelease({
     });
 
     archive.pipe(output);
-    // `false` — no top-level directory inside the zip. Foundry unpacks the
-    // archive *into* the package directory, so an extra level would nest the
-    // manifest one deeper than it looks for it.
-    archive.directory(stage, false);
+    // No top-level directory inside the zip: Foundry unpacks the archive
+    // *into* the package directory, so an extra level would nest the manifest
+    // one deeper than it looks for it.
+    await appendTree(archive, stage, archiveDate());
     await archive.finalize();
     await closed;
 

package/types/engine/yaml-lint.d.mts

@@ -22,10 +22,11 @@
  * - `no-empty-key`, `no-empty-document` — a fence or a file that parses to
  *   nothing at all.
  *
- * **GitHub workflows are exempt from `no-empty-mapping-value`**, because an
- * empty value is the language there: `on:` `push:` and `workflow_dispatch:`
- * carry their meaning by being present, and writing `push: null` to satisfy a
- * linter would be worse YAML, not better.
+ * **Workflows are exempt from `no-empty-mapping-value`**, under
+ * `.github/workflows/` and Gitea's `.gitea/workflows/` alike, because an empty
+ * value is the language there: `on:` `push:` and `workflow_dispatch:` carry
+ * their meaning by being present, and writing `push: null` to satisfy a linter
+ * would be worse YAML, not better.
  *
  * @param {object} plugin - The `eslint-plugin-yml` module.
  * @returns {object[]} A complete flat config, for `overrideConfig`.

package/types/release.d.mts

@@ -8,6 +8,10 @@
  * failure is timing-dependent, so it survives every run that happens to be
  * fast enough, which is what makes it worth being explicit about.
  *
+ * **The archive is reproducible.** Entries are written in path order with one
+ * date (`SOURCE_DATE_EPOCH` when set, otherwise 1980-01-01) and fixed
+ * permissions, so a rebuild of one staged tree is byte-identical.
+ *
  * @param {object} [opts]
  * @param {string} [opts.stageDir] - The staged package tree.
  * @param {string} [opts.outDir] - Where the release assets are written.