pivot to Python: replace Kotlin/JVM with stdlib zipapp

Reasons stacked up:
  - AV: unsigned JARs that auto-download binaries + upload files trigger
    Windows Defender false-positives more often than Python scripts
    invoked by code-signed python.exe.
  - Qt UI option: PySide6 opens a path to a real Qt UI (matching Prism's
    look) if needed later. JVM Qt bindings are abandoned.
  - frazclient already needs Python; inlining as 'import cloud_sync' is
    zero overhead vs the launcher always shelling out to java.

Implementation:
  - cloud_sync package: cli.py (argparse), creds.py, scope.py,
    restic.py (binary discovery + auto-download + sha256 verify),
    sync.py (pull/push subprocess restic).
  - pyproject.toml with hatchling backend; pip-installable.
  - Makefile builds cloud-sync.pyz via python -m zipapp (~53 KB).
  - 33 pytest tests, stdlib only on runtime.
  - CI workflow runs pytest matrix (3.10/3.11/3.12) + builds pyz.
  - DESIGN.md + README.md updated to reflect Python.

E2E verified against local restic-rest-server:
  pull empty → push initial → rm -rf local → pull restores → modify+push
  creates second snapshot → client forget --prune blocked by --append-only.

Throws away ~565 LOC of Kotlin (and 18 jar tests) committed earlier in
this same session. Net result is ~250 LOC Python + 33 tests = smaller
and more aligned with the rest of the stack.

tests/test_cli.py

@@ -0,0 +1,75 @@
+"""CLI parsing tests — argv → (subcommand, Args)."""
+
+from __future__ import annotations
+
+import pytest
+
+from cloud_sync.cli import Args, parse
+
+
+def test_parses_pull_with_required_url() -> None:
+    cmd, args = parse(["pull", "--url=https://cloud.tm.center"])
+    assert cmd == "pull"
+    assert isinstance(args, Args)
+    assert args.url == "https://cloud.tm.center"
+    assert args.allow_download is True
+    assert args.headless is False
+
+
+def test_default_token_file_under_pack_folder() -> None:
+    _, args = parse(["pull", "--url=https://x", "--pack-folder=/tmp/inst"])
+    assert args.token_file.as_posix().endswith(".cloud-sync/token")
+    assert "/tmp/inst" in args.token_file.as_posix()
+
+
+def test_custom_token_file_overrides_default() -> None:
+    _, args = parse(
+        ["pull", "--url=https://x", "--pack-folder=/tmp/inst",
+         "--token-file=/etc/cloud-creds"]
+    )
+    assert args.token_file.as_posix() == "/etc/cloud-creds"
+
+
+def test_inline_and_space_separated_both_work() -> None:
+    _, a1 = parse(["pull", "--url=https://x", "--pack-folder=/srv"])
+    _, a2 = parse(["pull", "--url", "https://x", "--pack-folder", "/srv"])
+    assert a1.url == a2.url
+    assert a1.pack_folder == a2.pack_folder
+
+
+def test_no_gui_flag() -> None:
+    _, a = parse(["push", "--url=https://x", "-g"])
+    assert a.headless is True
+    _, b = parse(["push", "--url=https://x", "--no-gui"])
+    assert b.headless is True
+
+
+def test_no_download_flag() -> None:
+    _, a = parse(["push", "--url=https://x", "--no-download"])
+    assert a.allow_download is False
+
+
+def test_restic_binary_override() -> None:
+    _, a = parse(["push", "--url=https://x", "--restic-binary=/opt/restic"])
+    assert a.restic_binary is not None
+    assert a.restic_binary.as_posix() == "/opt/restic"
+
+
+def test_missing_url_exits() -> None:
+    with pytest.raises(SystemExit):
+        parse(["pull"])
+
+
+def test_missing_subcommand_exits() -> None:
+    with pytest.raises(SystemExit):
+        parse([])
+
+
+def test_unknown_subcommand_exits() -> None:
+    with pytest.raises(SystemExit):
+        parse(["bogus", "--url=https://x"])
+
+
+def test_pack_folder_is_resolved_to_absolute() -> None:
+    _, a = parse(["pull", "--url=https://x", "--pack-folder=."])
+    assert a.pack_folder.is_absolute()

tests/test_creds.py

@@ -0,0 +1,62 @@
+"""Token file parser tests."""
+
+from __future__ import annotations
+
+import pytest
+
+from cloud_sync.creds import CredentialsError, read_credentials
+
+
+def test_parses_one_liner(tmp_path):
+    t = tmp_path / "token"
+    t.write_text("358881557521498112:s3cret-pass\n")
+    discord_id, password = read_credentials(t)
+    assert discord_id == "358881557521498112"
+    assert password == "s3cret-pass"
+
+
+def test_trims_whitespace(tmp_path):
+    t = tmp_path / "token"
+    t.write_text("  123  :  pw  \n")
+    discord_id, password = read_credentials(t)
+    assert discord_id == "123"
+    assert password == "pw"
+
+
+def test_missing_file_raises_with_actionable_message(tmp_path):
+    missing = tmp_path / "missing-token"
+    with pytest.raises(CredentialsError) as exc:
+        read_credentials(missing)
+    assert "token not found" in str(exc.value)
+    assert "discord_id:password" in str(exc.value)
+
+
+def test_missing_colon_rejected(tmp_path):
+    t = tmp_path / "token"
+    t.write_text("no-colon-here")
+    with pytest.raises(CredentialsError) as exc:
+        read_credentials(t)
+    assert "malformed" in str(exc.value)
+
+
+def test_empty_id_rejected(tmp_path):
+    t = tmp_path / "token"
+    t.write_text(":password")
+    with pytest.raises(CredentialsError):
+        read_credentials(t)
+
+
+def test_empty_password_rejected(tmp_path):
+    t = tmp_path / "token"
+    t.write_text("123:")
+    with pytest.raises(CredentialsError):
+        read_credentials(t)
+
+
+def test_password_with_colon_kept_intact(tmp_path):
+    """Passwords containing : should be kept whole after the first split."""
+    t = tmp_path / "token"
+    t.write_text("123:pw:with:colons")
+    discord_id, password = read_credentials(t)
+    assert discord_id == "123"
+    assert password == "pw:with:colons"

tests/test_repo_url.py

@@ -0,0 +1,54 @@
+"""restic repo URL builder + env tests."""
+
+from __future__ import annotations
+
+import pytest
+
+from cloud_sync.sync import _restic_env, _restic_repo
+
+
+def test_basic_http_url():
+    repo = _restic_repo("http://cloud.tm.center", "12345", "secretpw")
+    assert repo == "rest:http://12345:secretpw@cloud.tm.center/12345/"
+
+
+def test_https_url():
+    repo = _restic_repo("https://cloud.tm.center", "12345", "pw")
+    assert repo == "rest:https://12345:pw@cloud.tm.center/12345/"
+
+
+def test_trailing_slash_stripped():
+    repo = _restic_repo("https://cloud.tm.center/", "12345", "pw")
+    assert repo == "rest:https://12345:pw@cloud.tm.center/12345/"
+
+
+def test_url_with_port():
+    repo = _restic_repo("http://127.0.0.1:8002", "alice", "pw")
+    assert repo == "rest:http://alice:pw@127.0.0.1:8002/alice/"
+
+
+def test_rest_prefix_stripped_if_supplied():
+    repo = _restic_repo("rest:http://x.test", "u", "p")
+    assert repo == "rest:http://u:p@x.test/u/"
+
+
+def test_password_with_special_chars_encoded():
+    repo = _restic_repo("http://x.test", "u", "p@ss/word?!&")
+    # URL-encoded form of "p@ss/word?!&"
+    assert "p%40ss%2Fword%3F%21%26@x.test" in repo
+
+
+def test_user_with_special_chars_encoded():
+    repo = _restic_repo("http://x.test", "u/with@chars", "pw")
+    assert "u%2Fwith%40chars" in repo
+
+
+def test_missing_scheme_rejected():
+    with pytest.raises(ValueError):
+        _restic_repo("cloud.tm.center", "u", "p")
+
+
+def test_env_contains_password():
+    env = _restic_env("hunter2")
+    assert env["RESTIC_PASSWORD"] == "hunter2"
+    assert "RESTIC_PROGRESS_FPS" in env

tests/test_scope.py

@@ -0,0 +1,70 @@
+"""Scope file reader + materializer tests."""
+
+from __future__ import annotations
+
+import json
+
+from cloud_sync.scope import (
+    DEFAULT_EXCLUDE,
+    DEFAULT_INCLUDE,
+    Scope,
+    load,
+    materialize_for_restic,
+)
+
+
+def test_load_missing_returns_defaults(tmp_path):
+    s = load(tmp_path)
+    assert s.include == DEFAULT_INCLUDE
+    assert s.exclude == DEFAULT_EXCLUDE
+
+
+def test_load_valid_overrides_defaults(tmp_path):
+    state = tmp_path / ".cloud-sync"
+    state.mkdir()
+    (state / "scope.json").write_text(json.dumps({
+        "include": ["foo/", "bar.txt"],
+        "exclude": ["**/*.log"],
+    }))
+    s = load(tmp_path)
+    assert s.include == ["foo/", "bar.txt"]
+    assert s.exclude == ["**/*.log"]
+
+
+def test_load_partial_keeps_defaults_for_missing(tmp_path):
+    state = tmp_path / ".cloud-sync"
+    state.mkdir()
+    (state / "scope.json").write_text(json.dumps({"include": ["just-this"]}))
+    s = load(tmp_path)
+    assert s.include == ["just-this"]
+    assert s.exclude == DEFAULT_EXCLUDE
+
+
+def test_load_invalid_falls_back(tmp_path, capsys):
+    state = tmp_path / ".cloud-sync"
+    state.mkdir()
+    (state / "scope.json").write_text("{not valid json")
+    s = load(tmp_path)
+    assert s.include == DEFAULT_INCLUDE
+    captured = capsys.readouterr()
+    assert "invalid" in captured.err.lower()
+
+
+def test_materialize_writes_files(tmp_path):
+    scope = Scope(include=["config/", "options.txt"], exclude=["**/*.log"])
+    files_from, exclude_from = materialize_for_restic(tmp_path, scope)
+    assert files_from.exists()
+    assert exclude_from.exists()
+    body_in = files_from.read_text().splitlines()
+    body_ex = exclude_from.read_text().splitlines()
+    # trailing slash stripped on include entries
+    assert "config" in body_in
+    assert "options.txt" in body_in
+    assert "**/*.log" in body_ex
+
+
+def test_materialize_creates_state_dir(tmp_path):
+    scope = Scope(include=["x"], exclude=["y"])
+    files_from, _ = materialize_for_restic(tmp_path, scope)
+    assert files_from.parent.name == ".cloud-sync"
+    assert files_from.parent.exists()