ci: add patch-set integrity linter, SDK unit tests, and CI pipeline

Adds the first build-free safety net for the repo:
- tools/check_patches.py: enforces series-sync, numbering, single-surface,
  well-formed diffs, the uxr- switch prefix, and no brand string literals.
- sdk/python/tests/test_sdk.py: 21 tests for platform resolution, persona
  flag mapping, and SHA256SUMS verification (no network / no browser).
- .github/workflows/ci.yml: runs the linter, pytest on 3.9/3.12,
  shellcheck --severity=error, and node --check on every push and PR.

Author: abtonmoy

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: ci
+
+# Fast, build-free gates that run on every push and PR. None of these compile Chromium
+# (that is a multi-hour job) — they guard the patch set's invariants and the SDK logic,
+# which is where cheap mistakes actually happen.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  patch-integrity:
+    name: patch-set integrity
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Lint the patch series
+        run: python tools/check_patches.py
+
+  sdk-python:
+    name: python sdk tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install pytest
+        run: python -m pip install --upgrade pip pytest
+      - name: Import smoke test
+        run: python -c "import sys; sys.path.insert(0, 'sdk/python'); import tilion_fortress; print(tilion_fortress.__version__)"
+      - name: Run unit tests
+        run: python -m pytest sdk/python/tests -q
+
+  shell:
+    name: shellcheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Shellcheck build + packaging scripts
+        # --severity=error: fail only on real bugs, not pre-existing style nits.
+        run: |
+          shopt -s globstar nullglob
+          shellcheck --severity=error build/**/*.sh packaging/**/*.sh
+
+  node-sdk:
+    name: node sdk syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Syntax-check the CLI + library
+        run: |
+          node --check sdk/node/index.js
+          node --check sdk/node/cli.js

sdk/python/tests/test_sdk.py

@@ -0,0 +1,135 @@
+"""
+Unit tests for the tilion_fortress SDK.
+
+These cover the pure, release-critical logic that decides *which* bundle a user gets and
+whether it is trusted — the platform resolver, the persona->flag mapping, and the
+SHA256SUMS parser — with no network and no browser launch. A regression here silently
+ships the wrong binary or skips checksum verification, so it is worth gating in CI.
+
+Run:  pytest sdk/python/tests -q
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+
+import pytest
+
+# Make `import tilion_fortress` work when tests run from the repo root or from sdk/python.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import tilion_fortress as tf  # noqa: E402
+
+
+# --------------------------------------------------------------------------- platform
+@pytest.mark.parametrize("sysname,machine,expected", [
+    ("Linux",   "x86_64", "linux-x64"),
+    ("Linux",   "amd64",  "linux-x64"),
+    ("Windows", "AMD64",  "win-x64"),
+    ("Windows", "x86_64", "win-x64"),
+    ("Darwin",  "arm64",  "mac-arm64"),
+    ("Darwin",  "aarch64","mac-arm64"),
+    ("Darwin",  "x86_64", "mac-x64"),
+    ("Linux",   "aarch64", None),   # no arm64 Linux bundle yet -> unsupported
+    ("Linux",   "armv7l",  None),
+    ("FreeBSD", "amd64",   None),
+])
+def test_resolve_platform(monkeypatch, sysname, machine, expected):
+    monkeypatch.setattr(tf.platform, "system", lambda: sysname)
+    monkeypatch.setattr(tf.platform, "machine", lambda: machine)
+    assert tf.resolve_platform() == expected
+
+
+def test_every_resolvable_platform_has_an_asset():
+    # Any key resolve_platform() can return must exist in the _ASSETS table, and every
+    # launcher path must live under the bundle dir so extraction lands where _download expects.
+    resolvable = {"linux-x64", "win-x64", "mac-arm64", "mac-x64"}
+    assert resolvable <= set(tf._ASSETS)
+    for plat, (asset, kind, launcher) in tf._ASSETS.items():
+        assert asset.startswith("tilion-fortress-") and plat in asset
+        assert kind in ("tar", "zip")
+        assert launcher.startswith("tilion-fortress/")
+
+
+# --------------------------------------------------------------------------- persona
+def test_persona_args_empty():
+    assert tf._persona_args(None) == []
+    assert tf._persona_args({}) == []
+
+
+def test_persona_args_known_keys_map_to_uxr_flags():
+    args = tf._persona_args({"timezone": "America/New_York", "hw_concurrency": 16})
+    assert "--uxr-timezone=America/New_York" in args
+    assert "--uxr-hw-concurrency=16" in args
+
+
+def test_persona_args_unknown_key_falls_back_to_uxr_prefix():
+    # Unknown keys still become --uxr-<key-with-dashes>, never a bare or branded flag.
+    args = tf._persona_args({"some_new_surface": "v"})
+    assert args == ["--uxr-some-new-surface=v"]
+
+
+def test_persona_args_are_all_uxr_prefixed():
+    persona = {"platform": "Win32", "timezone": "UTC", "webgl_renderer": "ANGLE",
+               "device_memory": 8, "screen_width": 1920, "canvas_seed": 42, "weird_key": "x"}
+    for a in tf._persona_args(persona):
+        assert a.startswith("--uxr-"), a
+
+
+# --------------------------------------------------------------------------- checksums
+def test_sha256_matches_hashlib(tmp_path):
+    import hashlib
+    f = tmp_path / "blob.bin"
+    data = b"fortress" * 4096
+    f.write_bytes(data)
+    assert tf._sha256(f) == hashlib.sha256(data).hexdigest()
+
+
+class _FakeResp:
+    def __init__(self, body: bytes):
+        self._body = body
+    def read(self) -> bytes:
+        return self._body
+    def __enter__(self):
+        return self
+    def __exit__(self, *exc):
+        return False
+
+
+def test_expected_sha_parses_matching_asset(monkeypatch):
+    asset = tf._ASSETS["linux-x64"][0]
+    body = (
+        f"aa11bb22  {asset}\n"
+        f"deadbeef  tilion-fortress-win-x64.zip\n"
+    ).encode()
+    monkeypatch.setattr(tf.urllib.request, "urlopen", lambda *a, **k: _FakeResp(body))
+    assert tf._expected_sha(asset) == "aa11bb22"
+
+
+def test_expected_sha_handles_starred_binary_marker(monkeypatch):
+    # `sha256sum` writes "<hash> *<file>" in binary mode; the parser strips the leading '*'.
+    asset = tf._ASSETS["linux-x64"][0]
+    body = f"cafef00d *{asset}\n".encode()
+    monkeypatch.setattr(tf.urllib.request, "urlopen", lambda *a, **k: _FakeResp(body))
+    assert tf._expected_sha(asset) == "cafef00d"
+
+
+def test_expected_sha_returns_none_when_absent(monkeypatch):
+    body = b"aa11bb22  some-other-asset.tar.gz\n"
+    monkeypatch.setattr(tf.urllib.request, "urlopen", lambda *a, **k: _FakeResp(body))
+    assert tf._expected_sha(tf._ASSETS["linux-x64"][0]) is None
+
+
+def test_expected_sha_swallows_network_error(monkeypatch):
+    def boom(*a, **k):
+        raise OSError("network down")
+    monkeypatch.setattr(tf.urllib.request, "urlopen", boom)
+    # Must degrade to None (caller then warns + skips), never raise.
+    assert tf._expected_sha("anything") is None
+
+
+# --------------------------------------------------------------------------- release wiring
+def test_version_and_tag_are_coherent():
+    import re
+    assert re.fullmatch(r"\d+\.\d+\.\d+.*", tf.__version__)
+    assert re.fullmatch(r"v\d+\.\d+\.\d+\.\d+", tf._TAG)
+    assert tf._REPO == "tiliondev/fortress"
+    assert tf._DOCKER_IMAGE.startswith("tilion/fortress")

tools/check_patches.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+check_patches.py - integrity linter for the Fortress patch set.
+
+Fortress is a set of source patches applied to a pinned Chromium checkout
+(see build/apply-patches.sh + patches/series). Several invariants are load-bearing
+but were only ever enforced by human review. This linter enforces them mechanically
+so CI can gate every PR:
+
+  1. series-sync    - patches/series lists exactly the patches/*.patch files, once each,
+                      in ascending numeric order. A patch that is not in series is silently
+                      skipped by apply-patches.sh; an entry with no file breaks the build.
+  2. numbering      - files are NNNN-*.patch, contiguous from 0001, no gaps, no duplicates.
+  3. single-surface - each patch touches exactly ONE file (one `diff --git`). The project
+                      rule is one patch per file so rebases stay legible.
+  4. well-formed    - each patch has a `diff --git` header, ---/+++ file headers, and >=1 hunk.
+  5. uxr-only       - any command-line switch a patch introduces uses the de-branded `uxr-`
+                      prefix. A `--fortress-*` / `--tilion-*` switch would bake a brand token
+                      into the binary and is forbidden.
+  6. no-brand       - no added line introduces a quoted string literal containing a brand
+                      token (tilion/tillion/fortress/phoron/swarm). Such a literal ships in
+                      the binary's string table and is fingerprintable. (Comments are fine.)
+
+Exit code 0 if every check passes, 1 otherwise. Pure standard library; no build tree needed.
+
+    python tools/check_patches.py            # from the repo root
+    python tools/check_patches.py --verbose
+"""
+from __future__ import annotations
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+PATCHES = REPO / "patches"
+SERIES = PATCHES / "series"
+
+# Brand tokens that must never appear as a compiled-in string literal.
+BRAND_RE = re.compile(r'"[^"\n]*(tilion|tillion|fortress|phoron|swarm)[^"\n]*"', re.IGNORECASE)
+# Command-line switch lookups a patch may add.
+SWITCH_RE = re.compile(r'(?:HasSwitch|GetSwitchValueASCII|GetSwitchValueNative)\(\s*"([^"]+)"')
+PATCH_NAME_RE = re.compile(r"^(\d{4})-.*\.patch$")
+
+
+class Report:
+    def __init__(self) -> None:
+        self.failures: list[str] = []
+
+    def check(self, name: str, ok: bool, detail: str = "") -> None:
+        mark = "PASS" if ok else "FAIL"
+        line = f"  [{mark}] {name}"
+        if detail:
+            line += f" - {detail}"
+        print(line)
+        if not ok:
+            self.failures.append(name)
+
+
+def _patch_files() -> list[Path]:
+    return sorted(p for p in PATCHES.glob("*.patch"))
+
+
+def _strip_comment(added: str) -> str:
+    """Drop a trailing // line comment so comments never trip the string checks."""
+    i = added.find("//")
+    return added[:i] if i != -1 else added
+
+
+def check_series_sync(rep: Report, verbose: bool) -> None:
+    if not SERIES.exists():
+        rep.check("series-sync", False, "patches/series is missing")
+        return
+    listed = [ln.strip() for ln in SERIES.read_text().splitlines()
+              if ln.strip() and not ln.strip().startswith("#")]
+    listed_names = [Path(x).name for x in listed]
+    actual = [p.name for p in _patch_files()]
+
+    dupes = sorted({n for n in listed_names if listed_names.count(n) > 1})
+    missing_file = [n for n in listed_names if n not in actual]        # in series, no file
+    missing_entry = [n for n in actual if n not in listed_names]       # file, not in series
+    ordered = listed_names == sorted(listed_names)
+
+    ok = not dupes and not missing_file and not missing_entry and ordered
+    detail = f"{len(listed_names)} entries / {len(actual)} files"
+    if dupes:
+        detail = f"duplicate series entries: {dupes}"
+    elif missing_file:
+        detail = f"series lists patches with no file: {missing_file}"
+    elif missing_entry:
+        detail = f"patch files not listed in series (would be skipped by apply-patches.sh): {missing_entry}"
+    elif not ordered:
+        detail = "series is not in ascending order"
+    rep.check("series-sync", ok, detail)
+
+
+def check_numbering(rep: Report, verbose: bool) -> None:
+    nums: list[int] = []
+    bad_names: list[str] = []
+    for p in _patch_files():
+        m = PATCH_NAME_RE.match(p.name)
+        if not m:
+            bad_names.append(p.name)
+        else:
+            nums.append(int(m.group(1)))
+    dupes = sorted({n for n in nums if nums.count(n) > 1})
+    expected = list(range(1, len(nums) + 1)) if nums else []
+    gaps = sorted(set(expected) - set(nums))
+    ok = not bad_names and not dupes and not gaps
+    if bad_names:
+        detail = f"non-conforming names: {bad_names}"
+    elif dupes:
+        detail = f"duplicate numbers: {[f'{n:04d}' for n in dupes]}"
+    elif gaps:
+        detail = f"missing numbers: {[f'{n:04d}' for n in gaps]}"
+    else:
+        detail = f"0001..{max(nums):04d} contiguous" if nums else "no patches"
+    rep.check("numbering", ok, detail)
+
+
+def check_bodies(rep: Report, verbose: bool) -> None:
+    """single-surface + well-formed + uxr-only + no-brand, per patch."""
+    multi_file: list[str] = []
+    malformed: list[str] = []
+    bad_switch: list[str] = []
+    brand_hits: list[str] = []
+
+    for p in _patch_files():
+        text = p.read_text(encoding="utf-8", errors="replace")
+        lines = text.splitlines()
+        diff_headers = [ln for ln in lines if ln.startswith("diff --git ")]
+        has_minus = any(ln.startswith("--- ") for ln in lines)
+        has_plus = any(ln.startswith("+++ ") for ln in lines)
+        has_hunk = any(ln.startswith("@@") for ln in lines)
+
+        if len(diff_headers) != 1:
+            multi_file.append(f"{p.name} ({len(diff_headers)} files)")
+        if not (diff_headers and has_minus and has_plus and has_hunk):
+            malformed.append(p.name)
+
+        for ln in lines:
+            if not ln.startswith("+") or ln.startswith("+++"):
+                continue
+            added = _strip_comment(ln[1:])
+            for sw in SWITCH_RE.findall(added):
+                if not sw.startswith("uxr-"):
+                    bad_switch.append(f"{p.name}: --{sw}")
+            if BRAND_RE.search(added):
+                brand_hits.append(f"{p.name}: {ln.strip()[:70]}")
+
+    rep.check("single-surface", not multi_file,
+              f"all patches touch one file" if not multi_file else f"multi-file: {multi_file}")
+    rep.check("well-formed", not malformed,
+              "all patches parse" if not malformed else f"malformed: {malformed}")
+    rep.check("uxr-only-switches", not bad_switch,
+              "all switches use the uxr- prefix" if not bad_switch else f"non-uxr: {bad_switch}")
+    rep.check("no-brand-literals", not brand_hits,
+              "no brand string literals in added code" if not brand_hits
+              else f"brand literal would ship in binary: {brand_hits}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Integrity linter for the Fortress patch set.")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    args = ap.parse_args()
+
+    if not PATCHES.is_dir():
+        print(f"error: {PATCHES} not found (run from the repo root)", file=sys.stderr)
+        return 1
+
+    print(f"Fortress patch-set linter - {len(_patch_files())} patches in {PATCHES.relative_to(REPO)}/")
+    rep = Report()
+    check_series_sync(rep, args.verbose)
+    check_numbering(rep, args.verbose)
+    check_bodies(rep, args.verbose)
+
+    print("-" * 60)
+    if rep.failures:
+        print(f"FAILED: {len(rep.failures)} check(s): {', '.join(rep.failures)}")
+        return 1
+    print("OK: all patch-set checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())