claude-timemachine
20cfdf62f2
Reshapes the launcher integration around two ideas:
1. ONE global Prism PreLaunch/PostExit hook is enough for all
instances. Wire it once at Settings > Default > Custom commands:
python /opt/cloud-sync.pyz pull --pack-folder=$INST_MC_DIR
python /opt/cloud-sync.pyz push --pack-folder=$INST_MC_DIR
Instances WITHOUT .cloud-sync/sync.json are silent no-ops (rc=0,
no UI, no banner). The opt-in probe runs BEFORE the UI factory
so Prism's launch log stays clean for non-sync instances.
2. Per-instance opt-in via 'setup' / 'init' subcommands that mint a
fresh ULID-style instance_id + write sync.json (mode 644) and
token (mode 600). 'disable' removes sync.json; cloud data
untouched.
Restic URL gains an /<instance_id>/ subpath under the user's
namespace, so two Prism instances of the same Discord user no longer
share a snapshot timeline. --private-repos still gates on the first
path segment (the username); deeper segments are user-controlled,
so this works without server-side coordination. First-push-on-a-new-
instance probes via 'restic cat config' and 'init's the per-instance
repo if absent.
UI label resolution is runtime-only (NEVER stored in sync.json) so
the user renaming the Prism instance just propagates through on
next launch:
--instance-label > $INST_NAME > $INST_ID > instance_id[:8]
Schema bumps:
state.json schema: 1 -> 2, adds instance_id field. Schema-1 files
are treated as missing (existing test1 user re-pulls fresh).
sync.json schema: 1 (new file).
CLI rework:
pull / push no --url; load everything from sync.json
setup interactive: Qt login dialog for token; URL prompt
if --url omitted; falls back to stdin when headless
init non-interactive setup; for scripted callers
disable rm sync.json
Args dataclass: drops 'url', adds 'instance_label'. cli.parse() now
returns (cmd, Namespace); a separate args_from(ns) builds the Args
so each subcommand can pluck the bits it needs from the Namespace
without forcing a 'one Args fits all subcommands' shape.
73 tests green; pyz 75 KB.
Smoke-verified locally:
- pull/push on a folder without sync.json: silent rc=0, no banner
- init writes sync.json (644) + token (600) with correct contents
- disable removes sync.json, keeps token
- mint produces unique 26-char base32 instance_ids
- label resolution chain (flag > INST_NAME > INST_ID > prefix)
133 lines
5.8 KiB
Markdown
133 lines
5.8 KiB
Markdown
# 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:**
|
|
|
|
```
|
|
python /path/to/cloud-sync.pyz disable --pack-folder=/path/to/instance/minecraft
|
|
```
|
|
|
|
Removes `sync.json` (cloud data untouched). Instance returns to no-op behavior.
|
|
|
|
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]
|
|
```
|
|
|
|
`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.
|