design: lock client on-disk layout under <pack-folder>/.cloud-sync/

Per-instance isolation (different Discord accounts for different MC instances), auto-excluded from cloud sync, single 'rm -rf' reset. Restic binary discovery probes pinned path → $PATH → upstream download.
2026-06-02 22:33:25 +02:00
parent 14a6c5004b
commit df02f8a441
1 changed files with 34 additions and 0 deletions
@@ -113,6 +113,40 @@ discord-bot's `/register` flow extends to call `POST cloud-svc:9091/admin/users`

 Revocation = operator runs `automc-setup cloud revoke <discord_id>` which hits the loopback admin port. No token store, no scope checks, no auth-service involvement.

+## On-disk layout (client)
+
+cloud-sync.jar stores its state under `<pack-folder>/.cloud-sync/` — per-instance, hidden by leading dot. Auto-excluded from cloud sync so a player can't accidentally upload their own credentials.
+
+```
+<pack-folder>/
+  mods/                              # managed by packwiz
+  config/                            # mixed: pack-shipped + player-modified
+  options.txt
+  journeymap/data/
+  .cloud-sync/                       # cloud-sync owns this
+    token                            # "discord_id:password" (mode 0600)
+    scope.json                       # per-distribution include/exclude rules
+    restic-<version>                 # auto-downloaded binary
+    state.json                       # last-pull snapshot ID, last-push time
+    logs/                            # rolling, capped ~5 MB
+```
+
+Per-instance isolation matters: a player running a cracked instance + a premium instance gets two separate `.cloud-sync/` dirs with different Discord credentials. `rm -rf .cloud-sync/` resets one instance entirely.
+
+### Restic binary discovery
+
+Probed in order:
+
+1. `<pack-folder>/.cloud-sync/restic-<version>` — pinned copy from first run
+2. `$PATH` (`which restic` + version match) — honor existing system install
+3. Download from `github.com/restic/restic/releases/download/v<version>/restic_<version>_<os>_<arch>.bz2`, cache to `<pack-folder>/.cloud-sync/`
+
+`--restic-binary <path>` flag overrides discovery for air-gapped operators.
+
+### Jar placement
+
+Stateless. Lives wherever the operator put it. Prism / MMC config references absolute path. One jar can serve N instances; each gets its own `.cloud-sync/` underneath its own `--pack-folder`.
+
 ## Client flow

 ### `cloud-sync.jar pull`