#!/usr/bin/env python3 # SPDX-FileCopyrightText: 2025-2026 Kat Suricata # SPDX-License-Identifier: (CC-BY-4.0+ OR Apache-2.0+) """Builds the release files into `.release/dist/`. The release pipeline runs this, and so can you, before a tag exists: python3 scripts/make-archives.py --version 1.3.1 --check-only python3 scripts/make-archives.py --version 1.3.1 Two rules are enforced here: * Every file carries an extension. An extensionless name is a hangover from the retired Pages mirror, where such a path resolved to a directory and answered 404. Keep the convention: `SHA256SUMS` is `SHA256SUMS.txt`. * The version in the specification, the version in `package.json`, and the version on the tag must agree. The site's version badge reads the specification, so a mismatch ships a release that reports the wrong number. A theme version is the exception. A theme manifest is the whole add-on, its version belongs to the add-on rather than to the specification, and a theme listing refuses a number that goes backwards. The check on a manifest is therefore its shape: a version the host accepts, a gecko id of its own, and `theme.colors`. The archives carry no timestamps from the machine that built them, so the same commit produces the same file contents in the same order. The compressed bytes can still differ between machines, because a deflate implementation is free to vary between zlib versions: the release published from v1.3.0 matches a local rebuild entry for entry and CRC for CRC, but its two archives are not byte-identical. Compare the entries, or compare a download against the checksums published beside it. """ from __future__ import annotations import argparse import hashlib import json import pathlib import re import shutil import sys import zipfile ROOT = pathlib.Path(__file__).resolve().parent.parent SPEC = ROOT / 'Digital Rust Syntax Highlighting Specification.md' UI_SPEC = ROOT / 'Digital Rust UI Specification.md' PORTS = ROOT / 'static' / 'ports' SKILL_ZIP = PORTS / 'agentskill.zip' # A theme port keeps one manifest per mode under a host directory. Another port # may ship a `manifest.json` of its own kind, and this check must not judge that # one, so the host has to be named here. THEME_PORTS = ('firefox', 'thunderbird') DIST = ROOT / '.release' / 'dist' # A zip entry needs a date. A fixed one keeps the archive reproducible, and the # release date is on the pages index where a reader looks for it. FIXED_DATE = (1980, 1, 1, 0, 0, 0) def spec_version() -> str: """The first version history entry in the syntax specification.""" match = re.search(r'^- \*\*v(\d+\.\d+\.\d+)\*\*', SPEC.read_text(), re.MULTILINE) if not match: sys.exit(f'no version line in {SPEC.name}; the release cannot be named') return match.group(1) def package_version() -> str: return json.loads((ROOT / 'package.json').read_text())['version'] def check_versions(version: str) -> None: problems = [] if spec_version() != version: problems.append(f'the specification says v{spec_version()}') if package_version() != version: problems.append(f'package.json says {package_version()}') if problems: sys.exit(f'version {version} does not match: ' + '; '.join(problems)) def theme_manifests() -> list[pathlib.Path]: """Every theme manifest in the ports, which a reader installs on its own.""" return sorted( path for port in THEME_PORTS for path in PORTS.glob(f'{port}/*/manifest.json') ) def check_theme_manifests() -> None: """Refuses a theme manifest that a Gecko theme host would reject. A theme is a manifest and nothing else, so nothing else catches a broken one before a reader does. The version of a theme belongs to the add-on rather than to the specification, so this checks the shape of the number and not the value. """ problems: list[str] = [] owners: dict[str, list[str]] = {} for path in theme_manifests(): where = str(path.relative_to(ROOT)) try: manifest = json.loads(path.read_text()) except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error: problems.append(f'{where}: unreadable manifest, {error}') continue if not isinstance(manifest, dict): problems.append(f'{where}: the manifest is not an object') continue for key in ('manifest_version', 'name', 'version'): if key not in manifest: problems.append(f'{where}: no {key}') if manifest.get('manifest_version') not in (2, 3): problems.append(f'{where}: manifest_version must be 2 or 3') version = str(manifest.get('version', '')) if not re.fullmatch(r'\d+(\.\d+){0,3}', version): problems.append(f'{where}: version {version!r} is not a version the host accepts') theme = manifest.get('theme') if not isinstance(theme, dict) or not isinstance(theme.get('colors'), dict): problems.append(f'{where}: theme.colors is mandatory') elif not theme['colors']: problems.append(f'{where}: theme.colors is empty') settings = manifest.get('browser_specific_settings') gecko = settings.get('gecko') if isinstance(settings, dict) else None gecko_id = gecko.get('id') if isinstance(gecko, dict) else None if not gecko_id: problems.append(f'{where}: no gecko id, so the host will not install it') elif not isinstance(gecko_id, str): problems.append(f'{where}: the gecko id is not a string') else: owners.setdefault(gecko_id, []).append(where) # The addons.thunderbird.net upload validator rejects an MV3 theme whose # floor is below 128.0, and the theme guide does not state that rule. The # check turns a store rejection into a local one. if path.parent.parent.name == 'thunderbird' and manifest.get('manifest_version') == 3: floor = gecko.get('strict_min_version') if isinstance(gecko, dict) else None major = str(floor or '').split('.')[0] if not major.isdigit() or int(major) < 128: problems.append( f'{where}: ATN rejects an MV3 theme with strict_min_version ' f'below 128.0, and this one is {floor!r}' ) for gecko_id, claimed in owners.items(): if len(claimed) > 1: problems.append( f'the gecko id {gecko_id} is claimed by {", ".join(claimed)}, ' 'so one add-on would replace the other' ) if problems: sys.exit('a theme manifest would not install:\n ' + '\n '.join(problems)) def write_zip(path: pathlib.Path, entries: list[pathlib.Path]) -> None: """Writes a zip whose entries are sorted, so the bytes do not move.""" with zipfile.ZipFile(path, 'w', zipfile.ZIP_DEFLATED) as archive: for source in sorted(entries): relative = source.relative_to(ROOT / 'static') info = zipfile.ZipInfo(str(relative), date_time=FIXED_DATE) info.compress_type = zipfile.ZIP_DEFLATED info.create_system = 3 # unix, so the container fields do not follow the platform info.external_attr = 0o644 << 16 archive.writestr(info, source.read_bytes()) def build(version: str) -> list[pathlib.Path]: DIST.mkdir(parents=True, exist_ok=True) for stale in DIST.iterdir(): if stale.is_dir(): shutil.rmtree(stale) else: stale.unlink() # The ports, one file per tool. The agent skill ships as its own archive # because it is installed as a directory, not read in place. ports = [p for p in PORTS.rglob('*') if p.is_file() and p != SKILL_ZIP] ports_zip = DIST / f'digital-rust-ports-v{version}.zip' write_zip(ports_zip, ports) skill_zip = DIST / f'digital-rust-agentskill-v{version}.zip' skill_zip.write_bytes(SKILL_ZIP.read_bytes()) # The specifications are the canonical documents, and the release is where a # reader goes to get them without a git client. specs = [ (SPEC, DIST / 'digital-rust-syntax-highlighting-specification.md'), (UI_SPEC, DIST / 'digital-rust-ui-specification.md'), ] for source, target in specs: target.write_bytes(source.read_bytes()) published = sorted([ports_zip, skill_zip, *(target for _, target in specs)]) lines = [ f'{hashlib.sha256(path.read_bytes()).hexdigest()} {path.name}' for path in published ] (DIST / 'SHA256SUMS.txt').write_text('\n'.join(lines) + '\n') return [*published, DIST / 'SHA256SUMS.txt'] def main() -> None: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--version', required=True, help='release version, without the v') parser.add_argument( '--check-only', action='store_true', help='check the versions and stop, for a run before the tag exists' ) args = parser.parse_args() check_versions(args.version) check_theme_manifests() if args.check_only: print(f'version {args.version} agrees in the specification and package.json') print(f'{len(theme_manifests())} theme manifest(s) install') return for path in build(args.version): print(f'{path.relative_to(ROOT)} {path.stat().st_size} bytes') if __name__ == '__main__': main()