Build and publish XML-only customsets.zip for manual installation
Cockatrice assets CI Checks passed and artifacts archived. Stable publication was skipped for this branch.
Gitea/cockatrice-custom-tokens/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-10 16:59:06 +01:00
parent 1e4cfcb428
commit c239c159c4
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 99 additions and 14 deletions

View File

@ -48,6 +48,16 @@ installer does not change or bypass it. Windows execution still needs testing on
a Windows machine. See the [Windows installation chapter](docs/advanced_concept.md#windows-installation-powershell)
for custom paths, local execution, prerequisites, and limitations.
## Manual installation
Download [customsets.zip](https://assets.dandaedre.com/mtg/customsets.zip) after CI
publishes it. Close Cockatrice, back up your `customsets/` folder, then extract the
XML files directly into that folder, replacing matching files. Keep unrelated
custom sets. Restart Cockatrice afterward.
The archive contains XML only; artwork uses online URLs. For offline artwork,
use the installer. See [manual replacement details](docs/advanced_concept.md#manual-customsetszip-replacement).
## Advanced documentation
[Advanced concepts and maintenance](docs/advanced_concept.md) covers creating sets,

View File

@ -14,13 +14,14 @@ from the repository root; source and output paths below are relative to that roo
4. [Topic files and alternative artwork](#topic-files-and-alternative-artwork)
5. [Add a set](#add-a-set)
6. [Generate XML and build packages](#generate-xml-and-build-packages)
7. [One-line installation and updates (Linux/macOS)](#one-line-installation-and-updates-linuxmacos)
8. [Windows installation (PowerShell)](#windows-installation-powershell)
9. [Mock deployment](#mock-deployment)
10. [Jenkins CI and publication](#jenkins-ci-and-publication)
11. [Check your deck collection](#check-your-deck-collection)
12. [Servatrice configuration backup](#servatrice-configuration-backup)
13. [License](#license)
7. [Manual customsets.zip replacement](#manual-customsetszip-replacement)
8. [One-line installation and updates (Linux/macOS)](#one-line-installation-and-updates-linuxmacos)
9. [Windows installation (PowerShell)](#windows-installation-powershell)
10. [Mock deployment](#mock-deployment)
11. [Jenkins CI and publication](#jenkins-ci-and-publication)
12. [Check your deck collection](#check-your-deck-collection)
13. [Servatrice configuration backup](#servatrice-configuration-backup)
14. [License](#license)
## Layout
@ -306,6 +307,39 @@ manifest. Publication preparation/verification also rejects stale generated XML.
The existing `archives/customtokens.zip` is a legacy snapshot, not a source or a
current release artifact. New builds and the installer use the generated output.
## Manual customsets.zip replacement
The build also creates `dist/customsets.zip`, archived by Jenkins and published at
[https://assets.dandaedre.com/mtg/customsets.zip](https://assets.dandaedre.com/mtg/customsets.zip).
It contains all generated set XML files **at the archive root**, currently
`01.customtokens.xml`. It contains no artwork, TOML, installer, or extra `TKR/`
folder. The build and publisher verify its contents against generated XML.
1. Close Cockatrice and make a backup copy of your existing `customsets/` folder.
2. Download and extract the archive into the existing `customsets/` directory.
Replace matching XML filenames; do not keep an old renamed copy in the same
folder, since Cockatrice may load both. Keep unrelated custom-set XML files.
3. Restart Cockatrice. For the named Command Zone migration, replace old
`Command Zone` deck entries with your chosen `Command Zone - <subject>` token.
Typical destinations:
- Linux: `~/.local/share/Cockatrice/Cockatrice/customsets/`
- Flatpak: `~/.var/app/io.github.Cockatrice.cockatrice/data/Cockatrice/Cockatrice/customsets/`
- Windows: `%LOCALAPPDATA%\Cockatrice\Cockatrice\customsets\`
Use your configured custom-set location if it differs. The final path should be
`customsets/01.customtokens.xml`, not `customsets/customsets/01.customtokens.xml`
or `customsets/TKR/01.customtokens.xml`. If the folder is missing, create it in
an already initialized Cockatrice data directory (containing `settings/` or
`cards.xml`).
Manual extraction does not perform the installer's checks, confirmations, backups,
or rollback. XML references the published artwork URLs, so image downloading must
be enabled and online access available; use the installer to preinstall artwork
for offline use. Old artwork files are not removed. The existing per-set ZIPs
remain available as build artifacts with XML and artwork, in their original layout.
## One-line installation and updates (Linux/macOS)
After Jenkins successfully publishes `main`, run as your normal user from an
@ -538,7 +572,8 @@ against the sources. It fingerprints and archives `dist/*.zip`,
`dist/publish/manifest.json` on every successful branch. The launchers and manifest are published at
`https://assets.dandaedre.com/mtg/install.sh`,
`https://assets.dandaedre.com/mtg/install.ps1`, and
`https://assets.dandaedre.com/mtg/manifest.json`. The manifest is generated from the
`https://assets.dandaedre.com/mtg/manifest.json`. The XML-only `customsets.zip`
is also published at the `mtg/` root. The manifest is generated from the
XML and local artwork, including hashes and Cockatrice destination filenames, and
is published last. An XML reference outside the assets host or missing local
artwork causes the build to fail.

View File

@ -2,6 +2,7 @@
"""Validate and reproducibly package the repository's custom sets."""
from pathlib import Path
from generate_xml import generate
from publish import customsets_archive, sources
import xml.etree.ElementTree as ET
from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
@ -14,6 +15,8 @@ def main():
sets = sorted(path for path in generated.iterdir() if path.is_dir())
if not sets:
raise SystemExit("No set directories found.")
if any(folder.name.casefold() == 'customsets' for folder in sets):
raise SystemExit('Set code customsets conflicts with the manual customsets.zip archive.')
# Validate all sets before writing packages.
for folder in sets:
xml_files = sorted(folder.glob("*.xml"))
@ -27,7 +30,7 @@ def main():
output = ROOT / "dist"
output.mkdir(exist_ok=True)
for stale in output.glob("*.zip"):
if stale.name not in {f"{folder.name}.zip" for folder in sets}:
if stale.name not in ({f"{folder.name}.zip" for folder in sets} | {"customsets.zip"}):
stale.unlink()
for folder in sets:
target = output / f"{folder.name}.zip"
@ -41,6 +44,10 @@ def main():
archive.writestr(entry, source.read_bytes())
print(f"Built {target.relative_to(ROOT)}")
target = output / 'customsets.zip'
target.write_bytes(customsets_archive(sources(generated)))
print(f"Built {target.relative_to(ROOT)} (XML only, extract into customsets/)")
if __name__ == "__main__":
main()

View File

@ -4,13 +4,14 @@ import argparse
import base64
import hashlib
import json
import io
from urllib.parse import unquote, urlsplit
import os
from pathlib import Path
import shutil
import tempfile
import xml.etree.ElementTree as ET
from zipfile import ZipFile
from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
ROOT = Path(__file__).resolve().parents[1]
IMAGE_SUFFIXES = {'.png', '.jpg', '.jpeg', '.webp', '.gif'}
@ -50,6 +51,21 @@ def sources(sets):
def customsets_archive(entries):
"""XML files at archive root, ready to extract into Cockatrice customsets/."""
buffer = io.BytesIO()
with ZipFile(buffer, 'w', compression=ZIP_DEFLATED) as archive:
for relative, source in sorted(entries.items()):
if relative.parts[0] != 'xml':
continue
entry = ZipInfo(relative.name)
entry.compress_type = ZIP_DEFLATED
entry.create_system = 3
entry.external_attr = 0o100644 << 16
archive.writestr(entry, source.read_bytes())
return buffer.getvalue()
def installer_files(entries):
files = []
destinations = set()
@ -102,7 +118,8 @@ def installer_files(entries):
powershell = (ROOT / 'install.ps1').read_text().replace(
'__COCKATRICE_PYTHON_BASE64__', base64.b64encode(code.encode()).decode())
return {Path('manifest.json'): manifest, Path('install.sh'): wrapper.encode(),
Path('install.ps1'): powershell.encode()}
Path('install.ps1'): powershell.encode(),
Path('customsets.zip'): customsets_archive(entries)}
def prepare(sets, output):
@ -132,8 +149,11 @@ def verify(sets, output):
if expected[relative].read_bytes() != actual[relative].read_bytes():
raise ValueError(f'Payload differs from source: {relative}')
folders = sorted(path for path in sets.iterdir() if path.is_dir())
if {p.name for p in output.glob('*.zip')} != {f'{p.name}.zip' for p in folders}:
if {p.name for p in output.glob('*.zip')} != ({f'{p.name}.zip' for p in folders} | {'customsets.zip'}):
raise ValueError('ZIP outputs do not match the set directories')
manual = output / 'customsets.zip'
if manual.is_symlink() or manual.read_bytes() != controls[Path('customsets.zip')]:
raise ValueError('customsets.zip differs from generated XML')
for folder in folders:
bundle = output / f'{folder.name}.zip'
if bundle.is_symlink() or not bundle.is_file() or bundle.stat().st_size == 0:
@ -166,7 +186,7 @@ def payload_files(payload):
elif path.suffix.lower() not in IMAGE_SUFFIXES:
raise ValueError(f'Unsupported image: {path}')
entries[Path(category) / path.name] = path
for name in ('install.sh', 'install.ps1', 'manifest.json'):
for name in ('install.sh', 'install.ps1', 'manifest.json', 'customsets.zip'):
path = payload / name
if path.is_symlink() or not path.is_file() or path.stat().st_size == 0:
raise ValueError(f'Missing or unsafe installer output: {path}')

View File

@ -48,7 +48,7 @@ class PublicationTests(unittest.TestCase):
publish.publish(self.payload, self.mount)
(self.payload / 'cards/card.png').write_bytes(b'updated image')
publish.publish(self.payload, self.mount)
self.assertEqual(len(replaced), 10)
self.assertEqual(len(replaced), 12)
self.assertEqual((self.mount / 'mtg/cards/card.png').read_bytes(), b'updated image')
self.assertEqual((self.mount / 'mtg/xml/tokens.xml').read_bytes(), XML)
self.assertEqual((self.mount / 'unrelated.txt').read_text(), 'keep')
@ -66,11 +66,24 @@ class PublicationTests(unittest.TestCase):
for source in (self.sets / 'TKR').rglob('*'):
if source.is_file():
archive.write(source, source.relative_to(self.sets).as_posix())
(output / 'customsets.zip').write_bytes((self.payload / 'customsets.zip').read_bytes())
publish.verify(self.sets, output)
(output / 'customsets.zip').write_bytes(b'corrupt')
with self.assertRaisesRegex(ValueError, 'customsets.zip differs'):
publish.verify(self.sets, output)
(output / 'customsets.zip').write_bytes((self.payload / 'customsets.zip').read_bytes())
(self.payload / 'cards/card.png').write_bytes(b'tampered')
with self.assertRaisesRegex(ValueError, 'differs from source'):
publish.verify(self.sets, output)
def test_manual_archive_is_flat_xml_only_and_reproducible(self):
self.prepare()
path = self.payload / 'customsets.zip'
with ZipFile(path) as archive:
self.assertEqual(archive.namelist(), ['tokens.xml'])
self.assertEqual(archive.read('tokens.xml'), XML)
self.assertEqual(path.read_bytes(), publish.customsets_archive(publish.sources(self.sets)))
def test_existing_destination_symlink_rejected_before_any_copy(self):
self.prepare()
directory = self.mount / 'mtg/xml'