hbkit 0.4.0__tar.gz → 0.4.2__tar.gz

{hbkit-0.4.0 → hbkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hbkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Recover files from Synology Hyper Backup (.hbk) archives without Synology software
 Project-URL: Homepage, https://github.com/YordiLorenzo/hbkit
 Project-URL: Source, https://github.com/YordiLorenzo/hbkit
@@ -83,7 +83,11 @@ case is a loud failure naming the file.
  a All  n Clear  d Destination  r Recover  / Search  q Quit       │
 ```
 
-`space` tick · `a` all · `n` clear · `/` search · `d` destination · `r` recover.
+`space` tick · `a` all · `n` clear · `/` search · `d` destination · `r` recover ·
+`ctrl+q` quit (plain `q` types into whichever field has focus, so quit is ctrl+q).
+
+During a restore it shows live throughput, ETA, a rolling list of recently completed files,
+and a log of any failures.
 
 Folders show subtree size and file count. Ticking a folder takes its whole subtree; the
 destination panel warns before you start if the selection will not fit. Recovery shows a
@@ -92,12 +96,18 @@ live progress bar, throughput, ETA and a failure log.
 ## Commands
 
 ```sh
-hbk <archive> doctor                     # probe an unknown archive, prove it's readable
-hbk <archive> info                       # task name, codec, shares, encryption
-hbk <archive> list [pattern]             # search the file index
-hbk <archive> get <glob> <dest> [-j N]   # extract, preserving tree and mtimes
-hbk <archive> verify <glob> [-j N]       # integrity-check, write nothing
-hbk <archive> tui                        # same as hbk-tui
+hbk <archive> doctor                            # probe an archive, prove it's readable
+hbk <archive> info                              # task name, codec, shares, encryption
+hbk <archive> list [pattern]                    # search the file index
+hbk <archive> get <glob> <dest> [-j N]          # extract, preserving tree and mtimes
+hbk <archive> get <glob> <dest> --strict        # ...re-verifying checksums on resume
+hbk <archive> verify <glob> [-j N]              # integrity-check, write nothing
+hbk <archive> tui                               # same as hbk-tui
+
+hbk mount <remote:bucket> <dir> [--for browse|restore]   # mount object storage
+hbk warm <dir>                                  # pre-cache directory listings
+hbk unmount <dir>
+hbk remotes                                     # list configured rclone remotes
 ```
 
 For encrypted archives pass `-p/--password`, set `HBK_PASSWORD`, or let it prompt. The TUI
@@ -138,8 +148,9 @@ readable by rebuilding a random sample of real files with full checksum verifica
 - **Sidecars skipped.** `@eaDir`, `@SynoEAStream` and `@SynoResource` are Synology
   metadata — thumbnails and xattr streams, not your data. In one real archive they were
   half of all entries but under 1% of the bytes.
-- **Index cached** per archive in `~/.cache/hbkit`, rebuilt automatically when the archive
-  changes. Browsing 1.1M files is instant after the first open.
+- **Index cached** per archive in `~/.cache/hbkit` (override with `HBK_CACHE`), rebuilt
+  automatically when the archive changes. Browsing 1.1M files is instant after the first
+  open; building it takes ~10s locally, ~48s over a network mount.
 
 ## Network mounts (rclone / S3 / R2)
 
@@ -256,8 +267,9 @@ Read this before trusting it with the only copy of anything.
 - **The index cache stores decrypted filenames.** Browsing an encrypted archive requires
   the password because the directory tree itself is ciphertext, so `~/.cache/hbkit` will
   contain plaintext names (not file contents). Delete it if that matters to you.
-- **Proven against a limited set of archives.** The reference archive is DSM 7,
-  Hyper Backup 4.1.2, unencrypted, LZ4, single version, single pool. Older record layouts
+- **Proven against a limited set of archives.** A 3 TB DSM 7 / Hyper Backup 4.1.2
+  archive (unencrypted, LZ4, single version, single pool) and a small encrypted one from
+  the same DSM version, both verified byte-exact. Older record layouts
   (16-byte `chunk_index`, 28-byte bucket records), zlib chunks and multi-version archives
   are implemented from disassembly but have not met a real archive of that kind. `doctor`
   exists precisely so you can find out in seconds rather than mid-restore.

{hbkit-0.4.0 → hbkit-0.4.2}/README.md

@@ -54,7 +54,11 @@ case is a loud failure naming the file.
  a All  n Clear  d Destination  r Recover  / Search  q Quit       │
 ```
 
-`space` tick · `a` all · `n` clear · `/` search · `d` destination · `r` recover.
+`space` tick · `a` all · `n` clear · `/` search · `d` destination · `r` recover ·
+`ctrl+q` quit (plain `q` types into whichever field has focus, so quit is ctrl+q).
+
+During a restore it shows live throughput, ETA, a rolling list of recently completed files,
+and a log of any failures.
 
 Folders show subtree size and file count. Ticking a folder takes its whole subtree; the
 destination panel warns before you start if the selection will not fit. Recovery shows a
@@ -63,12 +67,18 @@ live progress bar, throughput, ETA and a failure log.
 ## Commands
 
 ```sh
-hbk <archive> doctor                     # probe an unknown archive, prove it's readable
-hbk <archive> info                       # task name, codec, shares, encryption
-hbk <archive> list [pattern]             # search the file index
-hbk <archive> get <glob> <dest> [-j N]   # extract, preserving tree and mtimes
-hbk <archive> verify <glob> [-j N]       # integrity-check, write nothing
-hbk <archive> tui                        # same as hbk-tui
+hbk <archive> doctor                            # probe an archive, prove it's readable
+hbk <archive> info                              # task name, codec, shares, encryption
+hbk <archive> list [pattern]                    # search the file index
+hbk <archive> get <glob> <dest> [-j N]          # extract, preserving tree and mtimes
+hbk <archive> get <glob> <dest> --strict        # ...re-verifying checksums on resume
+hbk <archive> verify <glob> [-j N]              # integrity-check, write nothing
+hbk <archive> tui                               # same as hbk-tui
+
+hbk mount <remote:bucket> <dir> [--for browse|restore]   # mount object storage
+hbk warm <dir>                                  # pre-cache directory listings
+hbk unmount <dir>
+hbk remotes                                     # list configured rclone remotes
 ```
 
 For encrypted archives pass `-p/--password`, set `HBK_PASSWORD`, or let it prompt. The TUI
@@ -109,8 +119,9 @@ readable by rebuilding a random sample of real files with full checksum verifica
 - **Sidecars skipped.** `@eaDir`, `@SynoEAStream` and `@SynoResource` are Synology
   metadata — thumbnails and xattr streams, not your data. In one real archive they were
   half of all entries but under 1% of the bytes.
-- **Index cached** per archive in `~/.cache/hbkit`, rebuilt automatically when the archive
-  changes. Browsing 1.1M files is instant after the first open.
+- **Index cached** per archive in `~/.cache/hbkit` (override with `HBK_CACHE`), rebuilt
+  automatically when the archive changes. Browsing 1.1M files is instant after the first
+  open; building it takes ~10s locally, ~48s over a network mount.
 
 ## Network mounts (rclone / S3 / R2)
 
@@ -227,8 +238,9 @@ Read this before trusting it with the only copy of anything.
 - **The index cache stores decrypted filenames.** Browsing an encrypted archive requires
   the password because the directory tree itself is ciphertext, so `~/.cache/hbkit` will
   contain plaintext names (not file contents). Delete it if that matters to you.
-- **Proven against a limited set of archives.** The reference archive is DSM 7,
-  Hyper Backup 4.1.2, unencrypted, LZ4, single version, single pool. Older record layouts
+- **Proven against a limited set of archives.** A 3 TB DSM 7 / Hyper Backup 4.1.2
+  archive (unencrypted, LZ4, single version, single pool) and a small encrypted one from
+  the same DSM version, both verified byte-exact. Older record layouts
   (16-byte `chunk_index`, 28-byte bucket records), zlib chunks and multi-version archives
   are implemented from disassembly but have not met a real archive of that kind. `doctor`
   exists precisely so you can find out in seconds rather than mid-restore.

{hbkit-0.4.0 → hbkit-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hbkit"
-version = "0.4.0"
+version = "0.4.2"
 description = "Recover files from Synology Hyper Backup (.hbk) archives without Synology software"
 readme = "README.md"
 requires-python = ">=3.10"

{hbkit-0.4.0 → hbkit-0.4.2}/src/hbkit/__init__.py

@@ -1,6 +1,6 @@
 """hbkit - recover files from Synology Hyper Backup (.hbk) archives without Synology software."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 from .archive import (Archive, NeedPassword, UnsupportedArchive,  # noqa: F401
                       find_archive_root, is_archive)

{hbkit-0.4.0 → hbkit-0.4.2}/src/hbkit/cli.py

@@ -4,14 +4,15 @@
   hbk <archive> doctor                               check whether it can be recovered
   hbk <archive> info                                 show task, shares, codec
   hbk <archive> list  [pattern]                      search the file index
-  hbk <archive> get   <glob> <dest> [-j N] [--strict]  extract (keeps tree + mtimes)
+  hbk <archive> get   <glob> <dest> [-j N] [--strict] extract (keeps tree + mtimes)
   hbk <archive> verify <glob>      [-j N]            integrity-check, write nothing
   hbk <archive> tui                                  browse in the full-screen UI
 
   hbk mount   <remote:bucket> <dir> [--for browse|restore] [--no-warm]
-  hbk warm    <dir>                                  pre-cache dir listings
-  hbk unmount <dir>                                          unmount it
-  hbk remotes                                                list configured rclone remotes
+  hbk warm    <dir>                                  pre-cache directory listings
+  hbk unmount <dir>                                  unmount it
+  hbk remotes                                        list configured rclone remotes
+  hbk --version                                      print the installed version
 
 Encrypted archives: add -p/--password, or set HBK_PASSWORD, or you'll be prompted.
 
@@ -162,6 +163,10 @@ def run(arc, sel, dest, jobs, check, password=None, strict=False):
 
 def main() -> int:
     a = sys.argv[1:]
+    if a and a[0] in ("--version", "-V"):
+        from . import __version__
+        print(f"hbkit {__version__}")
+        return 0
     jobs = 8
     password = None
     if "-j" in a:

{hbkit-0.4.0 → hbkit-0.4.2}/src/hbkit/index.py

@@ -7,7 +7,7 @@ where a directory's `size`/`nfiles` are SUBTREE totals, so a UI can show folder
 without walking children. Synology sidecar metadata (@eaDir, @SynoEAStream,
 @SynoResource) is pruned - it is not user data.
 
-Indexes are cached per archive under ~/.cache/hbk-recovery/ and rebuilt automatically
+Indexes are cached per archive under ~/.cache/hbkit/ and rebuilt automatically
 when the archive's share databases change.
 """
 from __future__ import annotations
@@ -21,7 +21,17 @@ import time
 
 from . import archive as hbk
 
-CACHE = os.path.expanduser(os.environ.get("HBK_CACHE", "~/.cache/hbk-recovery"))
+def _default_cache() -> str:
+    """~/.cache/hbkit, falling back to the pre-0.4.1 name if that is what exists locally
+    so an upgrade does not silently orphan an index someone waited minutes to build."""
+    new = os.path.expanduser("~/.cache/hbkit")
+    old = os.path.expanduser("~/.cache/hbk-recovery")
+    if not os.path.isdir(new) and os.path.isdir(old):
+        return old
+    return new
+
+
+CACHE = os.path.expanduser(os.environ.get("HBK_CACHE", "")) or _default_cache()
 SCHEMA = 2
 
 

{hbkit-0.4.0 → hbkit-0.4.2}/tests/test_hbkit.py

@@ -401,3 +401,17 @@ def test_sweep_parts_removes_only_part_files(tmp_path):
 def test_missing_file_is_never_complete(tmp_path):
     from hbkit import manifest as mf
     assert not mf.is_complete(str(tmp_path), "nope.bin", 10, {})
+
+
+def test_cache_dir_prefers_new_name_but_honours_the_old_one(tmp_path, monkeypatch):
+    """Renaming the cache must not orphan an index someone waited minutes to build."""
+    from hbkit import index as hbki
+    home = tmp_path
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setattr(os.path, "expanduser",
+                        lambda p: p.replace("~", str(home)) if p.startswith("~") else p)
+    assert hbki._default_cache().endswith("/.cache/hbkit")          # nothing exists yet
+    (home / ".cache" / "hbk-recovery").mkdir(parents=True)
+    assert hbki._default_cache().endswith("/.cache/hbk-recovery")   # legacy honoured
+    (home / ".cache" / "hbkit").mkdir(parents=True)
+    assert hbki._default_cache().endswith("/.cache/hbkit")          # new wins once present