fix: improve offline progress display

CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Added
+- Show stage-level tqdm progress for long-running standalone offline verify and restore operations.
+- Add `--verbose` diagnostics for object roles, BASE/DELTA details, byte counts, state digests, and timings.
+
+### Changed
+- Report object verification progress as an object count instead of summed compressed-plus-logical bytes, avoiding misleading apparent repository sizes.
+
 ## [0.1.4] - 2026-10-06
 
 ### Changed

README.md

@@ -189,6 +189,10 @@ endkeep-offline-env/bin/python endkeep-offline.py --repo /path/to/backups/repo v
 endkeep-offline-env/bin/python endkeep-offline.py --repo /path/to/backups/repo restore /path/to/new-world
 ```
 
+Long-running `verify` and `restore` operations show stage-level tqdm progress by default. Add
+`--verbose` to either command to include object roles, BASE/DELTA details, logical/compressed
+byte counts, state digests, and per-step timings.
+
 To restore a specific recovery point:
 
 ```bash

requirements-offline.txt

@@ -1,2 +1,3 @@
 amulet-leveldb==3.0.7a0
 zstandard>=0.23,<1
+tqdm>=4.70,<5

src/endstone_endkeep/logical/amulet_reader.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Generator, Iterable, Iterator
+from collections.abc import Callable, Generator, Iterable, Iterator
 from contextlib import contextmanager
 from pathlib import Path
 
@@ -33,6 +33,7 @@ def write_fresh_leveldb(
     state: Iterable[tuple[bytes, bytes]],
     *,
     batch_records: int = 4096,
+    progress: Callable[[int], None] | None = None,
 ) -> tuple[int, int]:
     """Build a fresh Bedrock LevelDB from canonical visible state."""
 
@@ -56,10 +57,16 @@ def write_fresh_leveldb(
             value_bytes += len(value)
             previous = key
             if len(batch) >= batch_records:
+                completed = len(batch)
                 db.put_batch(batch)
                 batch.clear()
+                if progress is not None:
+                    progress(completed)
         if batch:
+            completed = len(batch)
             db.put_batch(batch)
+            if progress is not None:
+                progress(completed)
     finally:
         db.close()
     return records, value_bytes

src/endstone_endkeep/logical/merge.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import hashlib
-from collections.abc import Iterable, Iterator
+from collections.abc import Callable, Iterable, Iterator
 from dataclasses import dataclass
 
 from .format import DeltaOperation, encode_uvarint
@@ -61,10 +61,19 @@ class StateStats:
     sha256: str
 
 
-def hash_state(state: Iterable[tuple[bytes, bytes]]) -> StateStats:
+def hash_state(
+    state: Iterable[tuple[bytes, bytes]],
+    *,
+    progress: Callable[[int], None] | None = None,
+    progress_interval: int = 16384,
+) -> StateStats:
+    if progress_interval <= 0:
+        raise ValueError("progress_interval must be positive")
+
     hasher = hashlib.sha256()
     records = 0
     value_bytes = 0
+    pending_progress = 0
     previous: bytes | None = None
     for key, value in state:
         if previous is not None and key <= previous:
@@ -76,4 +85,14 @@ def hash_state(state: Iterable[tuple[bytes, bytes]]) -> StateStats:
         previous = key
         records += 1
         value_bytes += len(value)
+
+        if progress is not None:
+            pending_progress += 1
+            if pending_progress >= progress_interval:
+                progress(pending_progress)
+                pending_progress = 0
+
+    if progress is not None and pending_progress:
+        progress(pending_progress)
+
     return StateStats(records, value_bytes, hasher.hexdigest())