claude-timemachine
ffdfb1f9b6
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.
102 lines
3.9 KiB
Markdown
102 lines
3.9 KiB
Markdown
# cloud-sync
|
|
|
|
Per-user Minecraft state sync via [restic](https://restic.net). Single Python zipapp drops into Prism / MMC / ATLauncher pre-launch and post-exit hooks alongside [packwiz-installer-bootstrap](https://github.com/packwiz/packwiz-installer-bootstrap). Part of the [automc](https://git.timemachine.center/Timemachine/automc) platform.
|
|
|
|
See [`DESIGN.md`](DESIGN.md) for the full architecture (restic backend, two-port cloud-svc control plane, etc.).
|
|
|
|
## Status
|
|
|
|
Working skeleton + sync logic. 33 tests pass. E2E verified against a local `restic-rest-server` (pull empty → push initial → delete local → pull restores → modify+push creates second snapshot → client `forget --prune` correctly blocked by `--append-only`).
|
|
|
|
## Install / build
|
|
|
|
Requires Python ≥ 3.10. No runtime deps (stdlib only).
|
|
|
|
```bash
|
|
# build single-file zipapp
|
|
make build # → cloud-sync.pyz (~53 KB)
|
|
|
|
# or pip-install
|
|
make install # pip install -e .
|
|
```
|
|
|
|
## Usage in Prism (or MMC / ATLauncher)
|
|
|
|
Instance Settings → Custom commands:
|
|
|
|
```
|
|
Pre-launch:
|
|
python /path/to/cloud-sync.pyz pull --url=https://cloud.tm.center --pack-folder=$INST_MC_DIR
|
|
|
|
Post-exit:
|
|
python /path/to/cloud-sync.pyz push --url=https://cloud.tm.center --pack-folder=$INST_MC_DIR
|
|
```
|
|
|
|
Player needs Python 3.10+ on PATH. Token file (`<INST_MC_DIR>/.cloud-sync/token`) gets the `discord_id:password` credentials from their `/register` Discord DM.
|
|
|
|
## CLI
|
|
|
|
```
|
|
python cloud-sync.pyz {pull,push} \
|
|
--url URL cloud-svc data plane URL (required)
|
|
--pack-folder PATH Minecraft instance directory (default: cwd)
|
|
--token-file PATH override default <pack-folder>/.cloud-sync/token
|
|
--restic-binary PATH skip auto-discovery
|
|
--no-download fail if no usable restic; don't fetch from upstream
|
|
-g, --no-gui headless mode
|
|
```
|
|
|
|
## Programmatic API (for frazclient)
|
|
|
|
```python
|
|
from pathlib import Path
|
|
import cloud_sync
|
|
|
|
cloud_sync.pull(cloud_sync.Args(
|
|
url="https://cloud.tm.center",
|
|
pack_folder=Path("/srv/mc/instance"),
|
|
token_file=Path("/srv/mc/instance/.cloud-sync/token"),
|
|
restic_binary=None, # auto-discover
|
|
allow_download=True,
|
|
headless=True,
|
|
))
|
|
```
|
|
|
|
frazclient's `client.py` consumes this directly via `import cloud_sync` instead of subprocessing the pyz.
|
|
|
|
## On-disk layout
|
|
|
|
Per-instance state under `<pack-folder>/.cloud-sync/`:
|
|
|
|
```
|
|
.cloud-sync/
|
|
token # discord_id:password (mode 0600)
|
|
scope.json # optional; defaults baked in if missing
|
|
restic-<RESTIC_VERSION> # auto-downloaded binary
|
|
files-from.txt # restic --files-from
|
|
exclude-from.txt # restic --exclude-from
|
|
```
|
|
|
|
Auto-excluded from sync. Multiple MC instances = multiple `.cloud-sync/` dirs with independent credentials.
|
|
|
|
## Why Python (not a JAR)
|
|
|
|
1. **Antivirus.** Unsigned JARs that auto-download binaries + upload files are textbook Windows Defender false-positive triggers. Python invoked by code-signed `python.exe` mostly sidesteps that.
|
|
2. **Future Qt UI.** PySide6 opens a path to a real Qt UI (matching Prism's look) if richer surfaces are wanted later. JVM Qt bindings are abandoned.
|
|
3. **frazclient already needs Python.** Inlining as an import is zero overhead; the same package serves Prism via the pyz.
|
|
|
|
Cost: players using Prism must have Python 3.10+ installed. Most Linux/Mac systems already do; Windows users install once from the Microsoft Store or python.org.
|
|
|
|
## Where the data lives
|
|
|
|
| Component | Role | Repo |
|
|
|---|---|---|
|
|
| `cloud-sync` (this) | Player-side. Subprocess restic for pull/push. | `Timemachine/cloud-sync` |
|
|
| `cloud-svc` | Operator-side control plane (provisioning + admin). | `Timemachine/cloud-svc` |
|
|
| `restic-rest-server` (existing) | Data plane. Player's restic hits it directly with their password. | upstream |
|
|
| `discord-bot` | Calls cloud-svc on `/register` to provision a player's cloud account. | `Timemachine/discord-bot` |
|
|
|
|
## License
|
|
|
|
MIT.
|