# instance-sync

Per-user Minecraft instance sync over the **Timemachine Network**, backed by [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.

> Repo + package + on-disk dir names are still `cloud-sync` / `cloud_sync` / `.cloud-sync/` for now — the rename was at the product / UI / CLI level. A future commit can pick up the file-system rename when it's worth breaking existing installs.

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)

**One-time global wiring.** Settings → Default → Custom commands (NOT per-instance):

```
Pre-launch:  python /path/to/cloud-sync.pyz pull --pack-folder=$INST_MC_DIR
Post-exit:   python /path/to/cloud-sync.pyz push --pack-folder=$INST_MC_DIR
```

That single line works for every existing and future instance. Instances without a `.cloud-sync/sync.json` are no-ops (silent rc=0, MC launches normally) — sync only kicks in for instances you've explicitly opted in.

**Per-instance opt-in:**

```
# interactive — opens Qt login dialog for the token
python /path/to/cloud-sync.pyz setup --pack-folder=/path/to/instance/minecraft

# scripted equivalent
python /path/to/cloud-sync.pyz init \
    --pack-folder=/path/to/instance/minecraft \
    --url=https://cloud.tm.center \
    --token=DISCORD_ID:PASSWORD
```

That mints a fresh `instance_id` (ULID), writes `.cloud-sync/sync.json` (the opt-in marker) and `.cloud-sync/token` (mode 600). Subsequent launches sync automatically via the global hook.

**Opting out / pausing:**

```
python /path/to/cloud-sync.pyz disable --pack-folder=/path/to/instance/minecraft
```

Renames `sync.json` → `sync.json.disabled`. Instance returns to no-op behavior (the opt-in gate only sees a literal `sync.json`). Re-enable later with:

```
python /path/to/cloud-sync.pyz enable  --pack-folder=/path/to/instance/minecraft
```

That rename-back preserves the original `instance_id` so snapshots continue against the same restic repo — no fresh ULID, no orphaned history. For a truly fresh start, `disable` then delete `sync.json.disabled` by hand before re-running `setup`.

Player needs Python 3.10+ AND a Qt binding (`pip install PySide6`). Without Qt the pyz falls back to headless mode for status; the conflict + login dialogs are Qt-only — without them, conflict aborts the launch defensively and `setup` prompts for the token via stdin.

## CLI

```
instance-sync pull / push [--pack-folder=PATH]
                          [--token-file=PATH]
                          [--restic-binary=PATH]
                          [--no-download]
                          [-g | --no-gui]
                          [--instance-label="Friendly Name"]

instance-sync setup       [--url=URL] [--pack-folder=PATH]     # interactive
instance-sync init        --url=URL [--token=ID:PASS] ...      # scripted
instance-sync disable     [--pack-folder=PATH]                 # sync.json → sync.json.disabled
instance-sync enable      [--pack-folder=PATH]                 # sync.json.disabled → sync.json
```

`pull` and `push` don't take `--url` — it's loaded from `sync.json`. `--instance-label` overrides the UI display name (defaults to `$INST_NAME` from Prism, then `$INST_ID`, then the first 8 chars of `instance_id`).

## Programmatic API (for frazclient)

```python
from pathlib import Path
import cloud_sync

cloud_sync.pull(cloud_sync.Args(
    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,
    instance_label=None,       # default to env / id-prefix
))
```

Url is taken from `<pack_folder>/.cloud-sync/sync.json`; the caller is expected to have run `setup` or `init` beforehand (or to write sync.json themselves via `cloud_sync.config.write(...)`).

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. **Qt UI.** PySide6 gives us a real native window with the Prism-dark Steam-style layout. 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+ AND Qt installed. Most Linux/Mac systems ship Python; Windows users install once from the Microsoft Store or python.org. Qt comes via `pip install PySide6`.

## Where the data lives

| Component | Role | Repo |
|---|---|---|
| `instance-sync` (this) | Player-side. Subprocesses restic for pull/push. Surfaces login + conflict + progress dialogs. | `Timemachine/cloud-sync` |
| `cloud-svc` | Operator-side control plane (provisioning + admin). | `Timemachine/cloud-svc` |
| `restic-rest-server` (existing) | Timemachine Network data plane. Player's restic hits it directly with their password. | upstream |
| `discord-bot` | Calls cloud-svc on `/cloud register` to provision a player's Timemachine Network account. | `Timemachine/discord-bot` |

## License

MIT.