ci: verify and package documentation builds and releases

.github/scripts/package.py

@@ -0,0 +1,26 @@
+"""Package verified repository contents and build provenance."""
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import tarfile
+
+name = 'Docs'
+version = os.environ.get("BUILD_VERSION") or datetime.now(timezone.utc).strftime("DEV-%Y%m%d-%H%M")
+if not re.fullmatch(r"(?:DEV-\d{8}-\d{4}|\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?)", version) or "SNAPSHOT" in version.upper():
+    raise SystemExit("Invalid archive version")
+dist = Path("dist")
+dist.mkdir(exist_ok=False)
+archive = dist / f"{name}-{version}.tar.gz"
+subprocess.run(["git", "archive", "--format=tar.gz", f"--prefix={name}-{version}/", "-o", str(archive), "HEAD"], check=True)
+with tarfile.open(dist / f"CoreProtect-docs-{version}.tar.gz", "w:gz") as output:
+    output.add(os.environ["SITE_DIR"], arcname=".")
+checksums = {path.name: hashlib.sha256(path.read_bytes()).hexdigest() for path in sorted(dist.glob("*.tar.gz"))}
+(dist / "SHA256SUMS").write_text("".join(f"{sha}  {filename}\n" for filename, sha in checksums.items()))
+metadata = {"repository": os.environ.get("GITHUB_REPOSITORY", name), "commit": subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip(), "version": version, "run_id": os.environ.get("GITHUB_RUN_ID"), "sha256": checksums}
+(dist / "build.json").write_text(json.dumps(metadata, indent=2) + "\n")
+with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+    output.write(f"name={name}-{version}\n")

.github/workflows/build.yml

@@ -0,0 +1,52 @@
+name: Build
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+    outputs:
+      artifact-name:
+        value: ${{ jobs.build.outputs.artifact-name }}
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    outputs:
+      artifact-name: ${{ steps.package.outputs.name }}-${{ github.run_id }}-${{ github.run_attempt }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.10'
+          cache: pip
+          cache-dependency-path: projects/CoreProtect/requirements.txt
+      - name: Check documentation indexes
+        run: python scripts/check-indexes.py
+      - name: Install documentation dependencies
+        run: python -m pip install -r projects/CoreProtect/requirements.txt
+      - name: Build CoreProtect documentation
+        working-directory: projects/CoreProtect
+        run: python -m mkdocs build --strict --site-dir "$RUNNER_TEMP/coreprotect-site"
+      - name: Package documentation
+        id: package
+        env:
+          BUILD_VERSION: ${{ inputs.version }}
+          SITE_DIR: ${{ runner.temp }}/coreprotect-site
+        run: python3 .github/scripts/package.py
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ${{ steps.package.outputs.name }}-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist/
+          if-no-files-found: error

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-24.04
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - id: version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          python3 - <<'PYTHON'
+          import os, re
+          tag = os.environ['TAG']
+          if not re.fullmatch(r'v\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?', tag) or 'SNAPSHOT' in tag.upper():
+              raise SystemExit('Use a numeric v tag, optionally with a prerelease suffix')
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
+              output.write(f'version={tag[1:]}\n')
+          PYTHON
+  build:
+    needs: validate
+    uses: ./.github/workflows/build.yml
+    with:
+      version: ${{ needs.validate.outputs.version }}
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: ${{ needs.build.outputs.artifact-name }}
+          path: release
+      - name: Create draft release
+        working-directory: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          sha256sum --check SHA256SUMS
+          flags=()
+          if [[ "$TAG" == *-* ]]; then flags+=(--prerelease); fi
+          gh release create "$TAG" *.tar.gz SHA256SUMS build.json --verify-tag --draft --generate-notes "${flags[@]}"

.gitignore

@@ -0,0 +1,2 @@
+
+/dist/

PIPELINES.md

@@ -0,0 +1,55 @@
+# Builds and releases
+
+Plugin pull requests into `main` run Maven verification with Java unit tests enabled. CoreProtect also builds pull requests into its default branch, `master`. A failed test fails the build. Test reports are uploaded when present, including after test failures; repositories without test sources report no tests.
+
+Development builds use `DEV-YYYYMMDD-HHmm`, with the date and time in UTC. The runtime JAR filename and embedded plugin version match, for example `armourshop-DEV-20260922-1500.jar` and `DEV-20260922-1500`. The numeric version in the committed POM remains the release version. GitHub artifact names include the run ID and attempt to distinguish builds within the same minute.
+
+## Plugin releases
+
+1. Set the numeric release version in `pom.xml`. Keep the plugin descriptor's version as `${project.version}` so Maven supplies it.
+2. Push a matching tag, such as `v1.2`, `v1.2.3`, or `v1.2.3-rc.1`.
+3. The release workflow checks the tag against the POM, prepares dependencies, and runs `mvn clean verify` with tests enabled and the `deploy-live` profile disabled.
+4. It validates and uploads the exact runtime JAR, `SHA256SUMS`, and `build.json` to a draft GitHub release.
+5. Download and inspect the artifacts, review the generated notes, and publish the draft.
+
+Tags with prerelease suffixes create prereleases. Snapshot versions are rejected. An existing release causes the run to fail; use a new version for corrections. The workflow does not deploy to a Minecraft server.
+
+`build.json` records the source commit, repository, tag, workflow run, JAR name, and checksum. Only the publishing job has repository write permission; the build job has read access.
+
+## Build dependencies
+
+Plugins with file dependencies use `.github/scripts/prepare-release.sh` to download their private build inputs from a pinned commit in [ServerAssets](https://github.com/TF-Minecraft/ServerAssets). The committed `.github/dependencies.sha256` verifies the downloaded bytes. JARs go in `libs/`, outside Maven's cleaned `target/` directory, and are ignored by Git.
+
+`DEPS_TOKEN` is an organisation Actions secret with Contents read access to ServerAssets. Grant the consuming repositories access to this one secret. A separate token for each repository is unnecessary. The workflow passes it only to dependency preparation steps. Fork pull requests do not receive Actions secrets and cannot run builds that require these private inputs.
+
+TLibs consumers declare a checksum-pinned Maven `provided` dependency. Both build workflows run the [shared TLibs installer](https://github.com/TF-Minecraft/TLibs/blob/905a196217471252b96be5ecf8eeb16c9e85e41d/DEPENDENCIES.md), which verifies the selected binary and installs it in Maven's local cache. Local builds run `python3 ../tlibs/tools/install-dependency.py --pom pom.xml` before Maven verification.
+
+ServerAssets' `manifest.json` is authoritative for filenames, hashes, embedded plugin versions, and sources. Keep licensed dependency JARs in that private repository and out of public release assets.
+
+## Workflow configuration
+
+Plugin repositories contain `build.yml`, `release.yml`, and the reusable `maven-release.yml` under `.github/workflows/`. The release caller selects the JDK and exact runtime artifact path; `{version}` expands to the numeric tag without `v`. It passes `DEPS_TOKEN` explicitly where needed. Select the shaded runtime JAR for plugins that use shading.
+
+Workflows use Ubuntu 24.04 and actions with Node.js 24 runtimes. The Java version is chosen for the repository and its compiled dependencies. This does not change the runtime compatibility promised by the plugin's source configuration.
+
+## Documentation and assets
+
+Docs checks relative links in the project indexes and builds CoreProtect's MkDocs site in strict mode. Development artifacts contain the documentation source archive, generated CoreProtect site, and checksums, named with the same UTC timestamp format.
+
+ServerAssets verifies every entry in its file manifest before uploading a timestamped source archive and checksums. Its artifacts retain the private repository's access controls.
+
+Both repositories accept numeric `v*` tags for archive releases. The same verification runs before packaging the tagged source, checksums, and `build.json` into a draft release. Archive versions come from the tag; these repositories do not have Maven versions to match.
+
+## ProvinceSystem
+
+PRs run frontend Vitest and backend pytest suites, upload JUnit reports, and build the Next.js frontend. CI uses Node 22 and Python 3.12; the backend tests use SQLite's connection-limit testing API. A failed suite prevents application artifact publication.
+
+Development artifacts include timestamped source and frontend archives, checksums, and build metadata. Both archives share the same root directory; extracting the frontend archive over the source archive supplies the compiled `.next` output and generated public assets. Dependencies and configuration must be installed separately to run the application.
+
+The frontend bundle uses `NEXT_PUBLIC_API_URL=http://127.0.0.1:8000` at build time. Build with the intended URL for a deployment that needs a different API endpoint. The pipeline does not deploy the application.
+
+Numeric `v*` tags must match `frontend/package.json`. The release workflow runs the same tests and build, then creates a draft archive release.
+
+## Verification scope
+
+A successful pull request build verifies compilation, available unit tests, and packaging. Check the downloaded JAR's embedded version as well as its filename. A tagged release run additionally verifies draft publication and release assets. Minecraft runtime and integration tests are separate checks.

README.md

@@ -4,6 +4,8 @@ The canonical technical documentation for every TF-Minecraft repository: setup,
 
 ## Start here
 
+- [Builds and releases](PIPELINES.md)
+
 - [Minecraft 1.21.10 test lab](projects/ServerAssets/docs/LAB.md)
 - [VehicleFramework and integration learnings](projects/VehicleFramework/README.md)
 - [Website and backend](projects/ProvinceSystem/docs/README.md)

projects/AACommandsFiller/README.md

@@ -5,3 +5,7 @@
 Technical documentation is maintained here. Run commands from the source checkout unless a guide says otherwise.
 
 - [README.md](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/ActivityTF/README.md

@@ -5,3 +5,7 @@
 Technical documentation is maintained here. Run commands from the source checkout unless a guide says otherwise.
 
 - [REWARD-POOLS.md](REWARD-POOLS.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/AdvancedGunpowder/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/AdvancedGunpowder) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/AdvancedResearch/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/AdvancedResearch) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/ArmourShop/README.md

@@ -8,3 +8,7 @@ Add setup, architecture, integration and operations guides for this project here
 
 - [Web integration and pack generation](../ProvinceSystem/docs/integrations/armourshop.md)
 - [Skins workflow](../ProvinceSystem/docs/cosmetics/skins.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/BarterShops/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/BarterShops) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/BirdMessenger/README.md

@@ -5,3 +5,7 @@
 Technical documentation is maintained here. Run commands from the source checkout unless a guide says otherwise.
 
 - [README.md](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/Cooking/README.md

@@ -6,3 +6,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 
 - [docs/crops.md](docs/crops.md)
 - [docs/husbandry.md](docs/husbandry.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/CoreProtect/README.md

@@ -22,3 +22,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 - [docs/languages.md](docs/languages.md)
 - [docs/permissions.md](docs/permissions.md)
 - [docs/tools-integrations.md](docs/tools-integrations.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/DenarEconomy/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/DenarEconomy) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/DrinkBuilder/README.md

@@ -10,3 +10,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 ## Related integration guides
 
 - [Drinks workflow and integration](../ProvinceSystem/docs/cosmetics/drinks.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/Games/README.md

@@ -13,3 +13,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 - [docs/SYSTEM.md](docs/SYSTEM.md)
 - [docs/TEST_MATRIX.md](docs/TEST_MATRIX.md)
 - [docs/WAGER_ENGINE.md](docs/WAGER_ENGINE.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/GeigerCounters/README.md

@@ -5,3 +5,7 @@
 Technical documentation is maintained here. Run commands from the source checkout unless a guide says otherwise.
 
 - [README.md](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/GemInfusion/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/GemInfusion) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/Goldsmithing/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/Goldsmithing) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/GunsAndGadgets/README.md

@@ -6,3 +6,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 
 - [docs/REVISION_SYSTEM.md](docs/REVISION_SYSTEM.md)
 - [mvn-package-out.txt](mvn-package-out.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/InteractibleFurniture/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/InteractibleFurniture) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/Magic/README.md

@@ -8,3 +8,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 - [docs/MAGE_GEAR_BATCHES.md](docs/MAGE_GEAR_BATCHES.md)
 - [docs/SYSTEM.md](docs/SYSTEM.md)
 - [docs/TEST_MATRIX.md](docs/TEST_MATRIX.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/MarketBlock/README.md

@@ -5,3 +5,7 @@
 Technical documentation is maintained here. Run commands from the source checkout unless a guide says otherwise.
 
 - [README.md](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/MusicalInstruments/README.md

@@ -5,3 +5,7 @@
 Technical documentation is maintained here. Run commands from the source checkout unless a guide says otherwise.
 
 - [README.md](overview.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/Nutrition/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/Nutrition) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/PermCleaner/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/PermCleaner) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/PointShop/README.md

@@ -3,3 +3,7 @@
 [Source repository](https://github.com/TF-Minecraft/PointShop) · [All projects](../../README.md)
 
 Add setup, architecture, integration and operations guides for this project here.
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.

projects/ProvinceSystem/README.md

@@ -62,3 +62,7 @@ Technical documentation is maintained here. Run commands from the source checkou
 - [docs/wiki-research/validation/wiki-tests.txt](docs/wiki-research/validation/wiki-tests.md)
 - [docs/wiki-research/validation/wiki-tsc-final.txt](docs/wiki-research/validation/wiki-tsc-final.md)
 - [docs/wiki-research/validation/wiki-tsc.txt](docs/wiki-research/validation/wiki-tsc.md)
+
+## Builds and releases
+
+See the [shared pipeline guide](../../PIPELINES.md) for development artifacts, release tags, and dependency access.