dirark 0.1.0__py3-none-any.whl

dirark/__init__.py

@@ -0,0 +1,17 @@
+"""dirark – directory archival and retrieval tool."""
+
+from .core import archive_dir, restore_ark
+from .reader import ArkReader
+from .sync import add_dir_to_remote_ark, merge_arks, pull_ark, push_ark
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "archive_dir",
+    "restore_ark",
+    "ArkReader",
+    "push_ark",
+    "pull_ark",
+    "merge_arks",
+    "add_dir_to_remote_ark",
+]

dirark/__main__.py

@@ -0,0 +1,124 @@
+"""CLI entry point for dirark."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .core import archive_dir, restore_ark
+from .reader import ArkReader
+from .sync import add_dir_to_remote_ark, merge_arks, pull_ark, push_ark
+
+
+def main() -> None:
+    """Parse arguments and dispatch to the appropriate subcommand."""
+    parser = argparse.ArgumentParser(
+        description="Cold-storage directory archival tool."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("archive", help="Archive a directory.")
+    p.add_argument("source_dir", type=Path)
+    p.set_defaults(func=_archive)
+
+    p = sub.add_parser("restore", help="Restore files from an ark.")
+    p.add_argument("ark_dir", type=Path)
+    p.add_argument("dest_dir", type=Path)
+    p.set_defaults(func=_restore)
+
+    p = sub.add_parser("push", help="Push local ark to remote via rsync.")
+    p.add_argument("local_ark", type=Path)
+    p.add_argument("remote")
+    p.set_defaults(func=_push)
+
+    p = sub.add_parser("pull", help="Pull remote ark to local path via rsync.")
+    p.add_argument("remote")
+    p.add_argument("local_ark", type=Path)
+    p.set_defaults(func=_pull)
+
+    p = sub.add_parser("merge", help="Merge src_ark into dst_ark (local).")
+    p.add_argument("src_ark", type=Path)
+    p.add_argument("dst_ark", type=Path)
+    p.set_defaults(func=_merge)
+
+    p = sub.add_parser("add", help="Archive a directory and add it to a remote ark.")
+    p.add_argument("source_dir", type=Path)
+    p.add_argument("remote_ark")
+    p.set_defaults(func=_add)
+
+    p = sub.add_parser("read", help="Print a file from an ark to stdout.")
+    p.add_argument("ark_dir", type=Path)
+    p.add_argument("file_path")
+    p.set_defaults(func=_read)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+def _archive(args: argparse.Namespace) -> None:
+    try:
+        archive_dir(args.source_dir)
+        print(f"Archived '{args.source_dir}'.")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _restore(args: argparse.Namespace) -> None:
+    try:
+        restore_ark(args.ark_dir, args.dest_dir)
+        print(f"Restored to '{args.dest_dir}'.")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _push(args: argparse.Namespace) -> None:
+    try:
+        push_ark(args.local_ark, args.remote)
+        print(f"Pushed '{args.local_ark}' to '{args.remote}'.")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _pull(args: argparse.Namespace) -> None:
+    try:
+        pull_ark(args.remote, args.local_ark)
+        print(f"Pulled '{args.remote}' to '{args.local_ark}'.")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _merge(args: argparse.Namespace) -> None:
+    try:
+        merge_arks(args.src_ark, args.dst_ark)
+        print(f"Merged '{args.src_ark}' into '{args.dst_ark}'.")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _add(args: argparse.Namespace) -> None:
+    try:
+        add_dir_to_remote_ark(args.source_dir, args.remote_ark)
+        print(f"Added '{args.source_dir}' to '{args.remote_ark}'.")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _read(args: argparse.Namespace) -> None:
+    try:
+        with ArkReader(args.ark_dir) as reader:
+            sys.stdout.buffer.write(reader.read_file(args.file_path))
+    except KeyError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dirark/core.py

@@ -0,0 +1,118 @@
+"""Core archive and restore operations."""
+
+import shutil
+import tempfile
+from pathlib import Path
+
+from .storage import (
+    ARK_DIR_EXT,
+    DB_NAME,
+    b2sum,
+    ensure_clean_outdir,
+    extract_tar_zst,
+    open_db,
+    write_objects_to_tar,
+)
+
+
+def archive_dir(src_dir: Path, ark_out: Path | None = None) -> None:
+    """Archive src_dir into a content-addressed store.
+
+    By default the archive is created at src_dir + ARK_DIR_EXT. Pass ark_out
+    to write into an existing ark directory (useful for merging or remote push).
+
+    Archiving is idempotent: re-running on the same directory is a no-op.
+    Files with duplicate content are deduplicated by BLAKE2b checksum.
+    """
+    if ark_out is None:
+        ark_out = Path(f"{src_dir}{ARK_DIR_EXT}")
+    ark_out.mkdir(exist_ok=True, parents=True)
+    ensure_clean_outdir(ark_out)
+    db = open_db(ark_out / DB_NAME)
+    cur = db.cursor()
+
+    new_objects: dict[str, Path] = {}
+    new_files: list[tuple[str, str]] = []
+
+    for path in sorted(src_dir.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(src_dir).as_posix()
+        checksum = b2sum(path)
+
+        cur.execute("SELECT 1 FROM files WHERE path=?", (rel,))
+        if cur.fetchone():
+            continue
+
+        cur.execute("SELECT tar_name FROM objects WHERE checksum=?", (checksum,))
+        if cur.fetchone() is None:
+            new_objects.setdefault(checksum, path)
+
+        new_files.append((rel, checksum))
+
+    if not new_files:
+        db.close()
+        return
+
+    if new_objects:
+        tar_name = write_objects_to_tar(ark_out, new_objects)
+        for checksum in new_objects:
+            cur.execute("INSERT INTO objects VALUES (?, ?)", (checksum, tar_name))
+
+    for rel, checksum in new_files:
+        cur.execute("INSERT INTO files VALUES (?, ?)", (rel, checksum))
+
+    db.commit()
+    db.close()
+
+
+def restore_ark(ark_dir: Path, dest_dir: Path) -> None:
+    """Restore all files from an ark to dest_dir.
+
+    dest_dir is only created if there are files to restore.
+    Missing tars or objects produce warnings but do not abort the restore.
+    """
+    db = open_db(ark_dir / DB_NAME)
+    cur = db.cursor()
+
+    cur.execute("SELECT path, checksum FROM files")
+    files = cur.fetchall()
+
+    if not files:
+        print("No files found to restore in the archive.")
+        db.close()
+        return
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    cur.execute("SELECT checksum, tar_name FROM objects")
+    checksum_to_tar = dict(cur.fetchall())
+    db.close()
+
+    by_tar: dict[Path, list[tuple[str, str]]] = {}
+    for rel, checksum in files:
+        tar_name = checksum_to_tar.get(checksum)
+        if tar_name:
+            by_tar.setdefault(ark_dir / tar_name, []).append((rel, checksum))
+        else:
+            print(f"Warning: checksum {checksum} for {rel} not in objects.")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        obj_dir = tmp_path / "objects"
+        obj_dir.mkdir()
+
+        for tar_path, tar_files in by_tar.items():
+            if not tar_path.exists():
+                print(f"Warning: {tar_path.name} not found.")
+                continue
+
+            extract_tar_zst(tar_path, tmp_path)
+
+            for rel, checksum in tar_files:
+                dest_file = dest_dir / rel
+                dest_file.parent.mkdir(parents=True, exist_ok=True)
+                src_obj = obj_dir / checksum
+                if src_obj.exists():
+                    shutil.copy2(src_obj, dest_file)
+                else:
+                    print(f"Warning: object {checksum} missing from {tar_path.name}.")

dirark/reader.py

@@ -0,0 +1,67 @@
+"""ArkReader: retrieve individual files from a dirark archive."""
+
+import tempfile
+from pathlib import Path
+
+from .storage import DB_NAME, extract_object_from_tar, open_db
+
+
+class ArkReader:
+    """Read-only access to individual files within a dirark archive.
+
+    Supports context manager usage::
+
+        with ArkReader(ark_dir) as reader:
+            data = reader.read_file("path/to/file.txt")
+    """
+
+    def __init__(self, ark_dir: Path) -> None:
+        """Open an ark for reading."""
+        self._ark_dir = ark_dir
+        self._db = open_db(ark_dir / DB_NAME)
+
+    def __enter__(self) -> "ArkReader":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def list_files(self) -> list[str]:
+        """Return sorted list of all archived file paths."""
+        cur = self._db.cursor()
+        cur.execute("SELECT path FROM files ORDER BY path")
+        return [row[0] for row in cur.fetchall()]
+
+    def get_checksum(self, path: str) -> str:
+        """Return the BLAKE2b checksum of an archived file by relative path."""
+        cur = self._db.cursor()
+        cur.execute("SELECT checksum FROM files WHERE path=?", (path,))
+        row = cur.fetchone()
+        if row is None:
+            raise KeyError(f"File not found in ark: {path}")
+        return row[0]
+
+    def read_file(self, path: str) -> bytes:
+        """Read and return the raw bytes of an archived file.
+
+        Raises KeyError if path is not in the ark.
+        """
+        cur = self._db.cursor()
+        cur.execute(
+            "SELECT f.checksum, o.tar_name "
+            "FROM files f JOIN objects o ON f.checksum = o.checksum "
+            "WHERE f.path=?",
+            (path,),
+        )
+        row = cur.fetchone()
+        if row is None:
+            raise KeyError(f"File not found in ark: {path}")
+        checksum, tar_name = row
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            extract_object_from_tar(self._ark_dir / tar_name, checksum, tmp_path)
+            return (tmp_path / "objects" / checksum).read_bytes()
+
+    def close(self) -> None:
+        """Close the underlying database connection."""
+        self._db.close()

dirark/storage.py

@@ -0,0 +1,143 @@
+"""Low-level storage primitives: checksums, tar I/O, and database access."""
+
+import shutil
+import sqlite3
+import subprocess
+import tempfile
+from pathlib import Path
+
+MAX_TAR_MB = 256
+DB_NAME = "index.sqlite"
+SEP = "-"
+TAR_PREFIX = "data" + SEP
+TAR_EXT = ".tar.zst"
+ARK_DIR_EXT = ".ark.d"
+
+
+def b2sum(path: Path) -> str:
+    """Compute BLAKE2b checksum of a file using the system b2sum utility."""
+    res = subprocess.run(
+        ["b2sum", str(path)],
+        check=True,
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    return res.stdout.split()[0]
+
+
+def open_db(path: Path) -> sqlite3.Connection:
+    """Open or create an ark SQLite database, ensuring the schema exists.
+
+    Tables:
+        files(path TEXT PK, checksum TEXT)       -- relative path → checksum
+        objects(checksum TEXT PK, tar_name TEXT) -- checksum → archive name
+    """
+    db = sqlite3.connect(path)
+    db.execute(
+        "CREATE TABLE IF NOT EXISTS files("
+        "path TEXT PRIMARY KEY, checksum TEXT NOT NULL)"
+    )
+    db.execute(
+        "CREATE TABLE IF NOT EXISTS objects("
+        "checksum TEXT PRIMARY KEY, tar_name TEXT NOT NULL)"
+    )
+    return db
+
+
+def list_tars(ark_dir: Path) -> list[Path]:
+    """Return sorted list of tar archives in an ark directory."""
+    return sorted(ark_dir.glob(f"{TAR_PREFIX}*{TAR_EXT}"))
+
+
+def tar_size_mb(path: Path) -> float:
+    """Return file size in megabytes."""
+    return path.stat().st_size / (1024 * 1024)
+
+
+def next_tar_path(ark_dir: Path, min_idx: int = 0) -> Path:
+    """Return path for the next tar archive in ark_dir.
+
+    Index is max(last_existing + 1, min_idx), guaranteeing no name collision.
+    """
+    tars = list_tars(ark_dir)
+    last_idx = int(tars[-1].name.removesuffix(TAR_EXT).split(SEP)[-1]) if tars else 0
+    idx = max(last_idx + 1, min_idx)
+    return ark_dir / f"{TAR_PREFIX}{idx:05d}{TAR_EXT}"
+
+
+def extract_tar_zst(src: Path, dest: Path) -> None:
+    """Extract a zstd-compressed tar archive into dest."""
+    subprocess.run(
+        ["tar", "-I", "zstd", "-xf", str(src), "-C", str(dest)],
+        check=True,
+    )
+
+
+def extract_object_from_tar(tar: Path, checksum: str, dest: Path) -> None:
+    """Extract a single object by checksum from a tar archive into dest."""
+    subprocess.run(
+        [
+            "tar",
+            "-I",
+            "zstd",
+            "-xf",
+            str(tar),
+            "-C",
+            str(dest),
+            f"./objects/{checksum}",
+        ],
+        check=True,
+    )
+
+
+def create_tar_zst(src_dir: Path, out: Path) -> None:
+    """Create a zstd-compressed tar of src_dir contents at out."""
+    subprocess.run(
+        ["tar", "-C", str(src_dir), "-I", "zstd", "-cf", str(out), "."],
+        check=True,
+    )
+
+
+def ensure_clean_outdir(ark_dir: Path) -> None:
+    """Create ark_dir if needed and raise RuntimeError on unexpected files."""
+    ark_dir.mkdir(parents=True, exist_ok=True)
+    allowed = {DB_NAME} | {p.name for p in ark_dir.glob(f"{TAR_PREFIX}*{TAR_EXT}")}
+    for p in ark_dir.iterdir():
+        if p.name not in allowed:
+            raise RuntimeError(f"Unexpected file in archive dir: {p}")
+
+
+def write_objects_to_tar(
+    ark_dir: Path,
+    objects: dict[str, Path],
+    min_tar_idx: int = 0,
+) -> str:
+    """Append objects (checksum → source path) to a tar archive in ark_dir.
+
+    Reuses the last tar if it is under MAX_TAR_MB, otherwise creates a new
+    one. min_tar_idx can be used to avoid index collisions when merging arks.
+
+    Returns the tar filename written to.
+    """
+    tars = list_tars(ark_dir)
+    if tars and tar_size_mb(tars[-1]) < MAX_TAR_MB:
+        tar_path = tars[-1]
+    else:
+        tar_path = next_tar_path(ark_dir, min_idx=min_tar_idx)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        obj_dir = tmp_dir / "objects"
+        obj_dir.mkdir(parents=True)
+
+        if tar_path.exists():
+            extract_tar_zst(tar_path, tmp_dir)
+
+        for checksum, src in objects.items():
+            dest = obj_dir / checksum
+            if not dest.exists():
+                shutil.copy2(src, dest)
+
+        create_tar_zst(tmp_dir, tar_path)
+
+    return tar_path.name

dirark/sync.py

@@ -0,0 +1,115 @@
+"""Sync operations between local and remote dirark archives."""
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .core import archive_dir
+from .storage import (
+    DB_NAME,
+    extract_tar_zst,
+    open_db,
+    write_objects_to_tar,
+)
+
+
+def push_ark(local_ark: Path, remote: str) -> None:
+    """Push a local ark to a remote location via rsync.
+
+    Uses checksum comparison (not just mtime+size) to ensure all changes are
+    transferred, even when modifications happen within the same second.
+    remote may be a local path string or an SSH target (user@host:/path).
+    """
+    subprocess.run(
+        ["rsync", "-avzc", f"{local_ark}/", remote],
+        check=True,
+    )
+
+
+def pull_ark(remote: str, local_ark: Path) -> None:
+    """Pull a remote ark to a local path via rsync.
+
+    remote may be a local path string or an SSH target (user@host:/path).
+    """
+    local_ark.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["rsync", "-avz", f"{remote}/", str(local_ark)],
+        check=True,
+    )
+
+
+def merge_arks(src_ark: Path, dst_ark: Path) -> None:
+    """Merge all objects and file mappings from src_ark into dst_ark.
+
+    Objects already present in dst by checksum are skipped (deduplication).
+    File path mappings are added with INSERT OR IGNORE, so existing paths
+    in dst take precedence.
+    """
+    dst_ark.mkdir(parents=True, exist_ok=True)
+    src_db = open_db(src_ark / DB_NAME)
+    dst_db = open_db(dst_ark / DB_NAME)
+    src_cur, dst_cur = src_db.cursor(), dst_db.cursor()
+
+    src_cur.execute("SELECT checksum, tar_name FROM objects")
+    src_objects = dict(src_cur.fetchall())
+
+    dst_cur.execute("SELECT checksum FROM objects")
+    dst_known = {row[0] for row in dst_cur.fetchall()}
+
+    missing = {cs: tar for cs, tar in src_objects.items() if cs not in dst_known}
+
+    if missing:
+        by_tar: dict[str, list[str]] = {}
+        for cs, tar_name in missing.items():
+            by_tar.setdefault(tar_name, []).append(cs)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            staging_obj = Path(tmp) / "objects"
+            staging_obj.mkdir()
+
+            for tar_name, checksums in by_tar.items():
+                src_tar = src_ark / tar_name
+                if not src_tar.exists():
+                    continue
+                with tempfile.TemporaryDirectory() as xtmp:
+                    extract_tar_zst(src_tar, Path(xtmp))
+                    for cs in checksums:
+                        obj = Path(xtmp) / "objects" / cs
+                        if obj.exists():
+                            shutil.copy2(obj, staging_obj / cs)
+
+            staged = {
+                cs: staging_obj / cs for cs in missing if (staging_obj / cs).exists()
+            }
+            if staged:
+                tar_name = write_objects_to_tar(dst_ark, staged)
+                for cs in staged:
+                    dst_cur.execute(
+                        "INSERT OR IGNORE INTO objects VALUES (?, ?)",
+                        (cs, tar_name),
+                    )
+
+    src_cur.execute("SELECT path, checksum FROM files")
+    for rel, checksum in src_cur.fetchall():
+        dst_cur.execute("INSERT OR IGNORE INTO files VALUES (?, ?)", (rel, checksum))
+
+    dst_db.commit()
+    src_db.close()
+    dst_db.close()
+
+
+def add_dir_to_remote_ark(src_dir: Path, remote_ark: str) -> None:
+    """Archive src_dir and merge its contents into a remote ark.
+
+    Pulls the remote ark locally, archives src_dir into it, then pushes the
+    updated ark back. Supports SSH remotes (user@host:/path) via rsync.
+
+    The remote ark must already exist (at minimum as an empty directory).
+    For a first push, use archive_dir followed by push_ark instead.
+    """
+    with tempfile.TemporaryDirectory() as tmp:
+        local_ark = Path(tmp) / "remote_ark"
+        pull_ark(remote_ark, local_ark)
+        archive_dir(src_dir, ark_out=local_ark)
+        push_ark(local_ark, remote_ark)

dirark/tests/test_core.py

@@ -0,0 +1,204 @@
+"""Tests for dirark.core: archive_dir and restore_ark."""
+
+import subprocess
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from dirark.core import archive_dir, restore_ark
+from dirark.storage import ARK_DIR_EXT, DB_NAME, TAR_EXT, TAR_PREFIX, open_db
+
+
+class TestArchiveDir(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+        self.src = self.tmp / "source"
+        self.ark = self.tmp / ("source" + ARK_DIR_EXT)
+        self.src.mkdir()
+        (self.src / "file1.txt").write_text("content of file1")
+        (self.src / "subdir").mkdir()
+        (self.src / "subdir" / "file2.txt").write_text("content of file2")
+        (self.src / "empty_file.txt").touch()
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_initial_archive_creates_structure(self) -> None:
+        archive_dir(self.src)
+        self.assertTrue(self.ark.exists())
+        self.assertTrue((self.ark / DB_NAME).exists())
+        tars = list(self.ark.glob(f"{TAR_PREFIX}*{TAR_EXT}"))
+        self.assertGreater(len(tars), 0)
+
+    def test_initial_archive_records_all_files(self) -> None:
+        archive_dir(self.src)
+        db = open_db(self.ark / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT path FROM files ORDER BY path")
+        paths = [row[0] for row in cur.fetchall()]
+        db.close()
+        self.assertEqual(paths, ["empty_file.txt", "file1.txt", "subdir/file2.txt"])
+
+    def test_initial_archive_deduplicates_objects(self) -> None:
+        archive_dir(self.src)
+        db = open_db(self.ark / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM objects")
+        n_objects = cur.fetchone()[0]
+        db.close()
+        self.assertGreaterEqual(n_objects, 2)
+
+    def test_incremental_archive_adds_new_files(self) -> None:
+        archive_dir(self.src)
+        (self.src / "new.txt").write_text("new content")
+        (self.src / "sub2").mkdir()
+        (self.src / "sub2" / "more.txt").write_text("more content")
+        archive_dir(self.src)
+
+        db = open_db(self.ark / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM files")
+        self.assertEqual(cur.fetchone()[0], 5)
+        db.close()
+
+    def test_idempotent_archiving(self) -> None:
+        archive_dir(self.src)
+        archive_dir(self.src)
+        db = open_db(self.ark / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM files")
+        self.assertEqual(cur.fetchone()[0], 3)
+        db.close()
+
+    def test_deduplication_across_paths(self) -> None:
+        (self.src / "dup.txt").write_text("content of file1")
+        archive_dir(self.src)
+        db = open_db(self.ark / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM files")
+        n_files = cur.fetchone()[0]
+        cur.execute("SELECT COUNT(*) FROM objects")
+        n_objects = cur.fetchone()[0]
+        db.close()
+        self.assertEqual(n_files, 4)
+        self.assertLess(n_objects, n_files)
+
+    def test_archive_into_existing_ark(self) -> None:
+        self.ark.mkdir()
+        archive_dir(self.src, ark_out=self.ark)
+        db = open_db(self.ark / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM files")
+        self.assertEqual(cur.fetchone()[0], 3)
+        db.close()
+
+
+class TestRestoreArk(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+        self.src = self.tmp / "source"
+        self.ark = self.tmp / ("source" + ARK_DIR_EXT)
+        self.dest = self.tmp / "restored"
+        self.src.mkdir()
+        (self.src / "file1.txt").write_text("content of file1")
+        (self.src / "subdir").mkdir()
+        (self.src / "subdir" / "file2.txt").write_text("content of file2")
+        (self.src / "empty_file.txt").touch()
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_restore_recreates_files(self) -> None:
+        archive_dir(self.src)
+        restore_ark(self.ark, self.dest)
+        self.assertTrue((self.dest / "file1.txt").exists())
+        self.assertTrue((self.dest / "subdir" / "file2.txt").exists())
+        self.assertTrue((self.dest / "empty_file.txt").exists())
+
+    def test_restore_preserves_content(self) -> None:
+        archive_dir(self.src)
+        restore_ark(self.ark, self.dest)
+        self.assertEqual((self.dest / "file1.txt").read_text(), "content of file1")
+        self.assertEqual(
+            (self.dest / "subdir" / "file2.txt").read_text(),
+            "content of file2",
+        )
+        self.assertEqual((self.dest / "empty_file.txt").read_text(), "")
+
+    def test_restore_includes_incrementally_added_files(self) -> None:
+        archive_dir(self.src)
+        (self.src / "new.txt").write_text("new content")
+        archive_dir(self.src)
+        restore_ark(self.ark, self.dest)
+        self.assertTrue((self.dest / "new.txt").exists())
+        self.assertEqual((self.dest / "new.txt").read_text(), "new content")
+
+    def test_restore_empty_archive_skips_dest_creation(self) -> None:
+        self.ark.mkdir()
+        open_db(self.ark / DB_NAME).close()
+        with open("/dev/null", "w") as f, redirect_stdout(f):
+            restore_ark(self.ark, self.dest)
+        self.assertFalse(self.dest.exists())
+
+
+class TestCLI(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+        self.src = self.tmp / "source"
+        self.ark = self.tmp / ("source" + ARK_DIR_EXT)
+        self.dest = self.tmp / "restored"
+        self.src.mkdir()
+        (self.src / "file1.txt").write_text("content of file1")
+        (self.src / "subdir").mkdir()
+        (self.src / "subdir" / "file2.txt").write_text("content of file2")
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def _run(self, *args: str) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [sys.executable, "-m", "dirark", *args],
+            capture_output=True,
+            text=True,
+        )
+
+    def test_archive_command(self) -> None:
+        result = self._run("archive", str(self.src))
+        self.assertEqual(result.returncode, 0)
+        self.assertIn("Archived", result.stdout)
+        self.assertTrue((self.ark / DB_NAME).exists())
+
+    def test_restore_command(self) -> None:
+        self._run("archive", str(self.src))
+        result = self._run("restore", str(self.ark), str(self.dest))
+        self.assertEqual(result.returncode, 0)
+        self.assertIn("Restored", result.stdout)
+        self.assertTrue((self.dest / "file1.txt").exists())
+        self.assertEqual((self.dest / "file1.txt").read_text(), "content of file1")
+
+    def test_restore_empty_archive(self) -> None:
+        self.ark.mkdir()
+        open_db(self.ark / DB_NAME).close()
+        result = self._run("restore", str(self.ark), str(self.dest))
+        self.assertEqual(result.returncode, 0)
+        self.assertIn("No files found", result.stdout)
+        self.assertFalse(self.dest.exists())
+
+    def test_read_command(self) -> None:
+        self._run("archive", str(self.src))
+        result = subprocess.run(
+            [sys.executable, "-m", "dirark", "read", str(self.ark), "file1.txt"],
+            capture_output=True,
+        )
+        self.assertEqual(result.returncode, 0)
+        self.assertEqual(result.stdout, b"content of file1")
+
+    def test_read_missing_file_exits_nonzero(self) -> None:
+        self._run("archive", str(self.src))
+        result = self._run("read", str(self.ark), "nonexistent.txt")
+        self.assertNotEqual(result.returncode, 0)

dirark/tests/test_init.py

@@ -0,0 +1,5 @@
+from dirark import __version__
+
+
+def test_import():
+    assert isinstance(__version__, str)

dirark/tests/test_reader.py

@@ -0,0 +1,69 @@
+"""Tests for dirark.reader.ArkReader."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from dirark.core import archive_dir
+from dirark.reader import ArkReader
+from dirark.storage import ARK_DIR_EXT
+
+
+class TestArkReader(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+        self.src = self.tmp / "source"
+        self.ark = self.tmp / ("source" + ARK_DIR_EXT)
+        self.src.mkdir()
+        (self.src / "hello.txt").write_text("hello world")
+        (self.src / "sub").mkdir()
+        (self.src / "sub" / "data.bin").write_bytes(b"\x00\x01\x02\x03")
+        (self.src / "empty.txt").touch()
+        archive_dir(self.src)
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_list_files(self) -> None:
+        with ArkReader(self.ark) as r:
+            files = r.list_files()
+        self.assertEqual(files, ["empty.txt", "hello.txt", "sub/data.bin"])
+
+    def test_get_checksum_returns_string(self) -> None:
+        with ArkReader(self.ark) as r:
+            cs = r.get_checksum("hello.txt")
+        self.assertIsInstance(cs, str)
+        self.assertEqual(len(cs), 128)
+
+    def test_read_file_text(self) -> None:
+        with ArkReader(self.ark) as r:
+            data = r.read_file("hello.txt")
+        self.assertEqual(data, b"hello world")
+
+    def test_read_file_binary(self) -> None:
+        with ArkReader(self.ark) as r:
+            data = r.read_file("sub/data.bin")
+        self.assertEqual(data, b"\x00\x01\x02\x03")
+
+    def test_read_empty_file(self) -> None:
+        with ArkReader(self.ark) as r:
+            data = r.read_file("empty.txt")
+        self.assertEqual(data, b"")
+
+    def test_missing_file_raises_key_error(self) -> None:
+        with ArkReader(self.ark) as r:
+            with self.assertRaises(KeyError):
+                r.read_file("does_not_exist.txt")
+
+    def test_get_checksum_missing_raises_key_error(self) -> None:
+        with ArkReader(self.ark) as r:
+            with self.assertRaises(KeyError):
+                r.get_checksum("does_not_exist.txt")
+
+    def test_context_manager_closes(self) -> None:
+        r = ArkReader(self.ark)
+        with r:
+            _ = r.list_files()
+        with self.assertRaises(Exception):
+            r.list_files()

dirark/tests/test_storage.py

@@ -0,0 +1,124 @@
+"""Tests for dirark.storage primitives."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from dirark.storage import (
+    ARK_DIR_EXT,
+    DB_NAME,
+    TAR_EXT,
+    TAR_PREFIX,
+    b2sum,
+    create_tar_zst,
+    ensure_clean_outdir,
+    extract_tar_zst,
+    list_tars,
+    next_tar_path,
+    open_db,
+    tar_size_mb,
+    write_objects_to_tar,
+)
+
+
+class TestStoragePrimitives(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+        self.src = self.tmp / "src"
+        self.src.mkdir()
+        (self.src / "a.txt").write_text("hello")
+        (self.src / "sub").mkdir()
+        (self.src / "sub" / "b.txt").write_text("world")
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_b2sum_returns_128_hex_chars(self) -> None:
+        cs = b2sum(self.src / "a.txt")
+        self.assertIsInstance(cs, str)
+        self.assertEqual(len(cs), 128)
+
+    def test_b2sum_is_deterministic(self) -> None:
+        self.assertEqual(b2sum(self.src / "a.txt"), b2sum(self.src / "a.txt"))
+
+    def test_b2sum_differs_for_different_content(self) -> None:
+        self.assertNotEqual(
+            b2sum(self.src / "a.txt"), b2sum(self.src / "sub" / "b.txt")
+        )
+
+    def test_open_db_creates_schema(self) -> None:
+        db = open_db(self.tmp / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        tables = {row[0] for row in cur.fetchall()}
+        self.assertIn("files", tables)
+        self.assertIn("objects", tables)
+        db.close()
+
+    def test_create_and_extract_tar_zst(self) -> None:
+        tar = self.tmp / f"test{TAR_EXT}"
+        create_tar_zst(self.src, tar)
+        self.assertTrue(tar.exists())
+
+        out = self.tmp / "extracted"
+        out.mkdir()
+        extract_tar_zst(tar, out)
+        self.assertTrue((out / "a.txt").exists())
+        self.assertEqual((out / "a.txt").read_text(), "hello")
+
+    def test_list_tars_sorted(self) -> None:
+        ark = self.tmp / "ark.ark.d"
+        ark.mkdir()
+        (ark / f"{TAR_PREFIX}00002{TAR_EXT}").touch()
+        (ark / f"{TAR_PREFIX}00001{TAR_EXT}").touch()
+        tars = list_tars(ark)
+        names = [t.name for t in tars]
+        self.assertEqual(names, sorted(names))
+
+    def test_tar_size_mb(self) -> None:
+        tar = self.tmp / f"test{TAR_EXT}"
+        create_tar_zst(self.src, tar)
+        self.assertGreater(tar_size_mb(tar), 0)
+
+    def test_next_tar_path_first(self) -> None:
+        ark = self.tmp / "ark.ark.d"
+        ark.mkdir()
+        path = next_tar_path(ark)
+        self.assertEqual(path.name, f"{TAR_PREFIX}00001{TAR_EXT}")
+
+    def test_next_tar_path_increments(self) -> None:
+        ark = self.tmp / "ark.ark.d"
+        ark.mkdir()
+        (ark / f"{TAR_PREFIX}00003{TAR_EXT}").touch()
+        path = next_tar_path(ark)
+        self.assertEqual(path.name, f"{TAR_PREFIX}00004{TAR_EXT}")
+
+    def test_next_tar_path_min_idx(self) -> None:
+        ark = self.tmp / "ark.ark.d"
+        ark.mkdir()
+        path = next_tar_path(ark, min_idx=5)
+        self.assertEqual(path.name, f"{TAR_PREFIX}00005{TAR_EXT}")
+
+    def test_ensure_clean_outdir_passes(self) -> None:
+        ark = self.tmp / f"src{ARK_DIR_EXT}"
+        ark.mkdir()
+        (ark / DB_NAME).touch()
+        (ark / f"{TAR_PREFIX}00001{TAR_EXT}").touch()
+        ensure_clean_outdir(ark)  # should not raise
+
+    def test_ensure_clean_outdir_raises_on_unexpected(self) -> None:
+        ark = self.tmp / f"src{ARK_DIR_EXT}"
+        ark.mkdir()
+        (ark / "unexpected.txt").touch()
+        with self.assertRaises(RuntimeError):
+            ensure_clean_outdir(ark)
+
+    def test_write_objects_to_tar(self) -> None:
+        ark = self.tmp / "ark.ark.d"
+        ark.mkdir()
+        open_db(ark / DB_NAME).close()
+        cs = b2sum(self.src / "a.txt")
+        tar_name = write_objects_to_tar(ark, {cs: self.src / "a.txt"})
+        self.assertTrue((ark / tar_name).exists())
+        self.assertEqual(tar_name, f"{TAR_PREFIX}00001{TAR_EXT}")

dirark/tests/test_sync.py

@@ -0,0 +1,142 @@
+"""Tests for dirark.sync: merge_arks, push_ark, pull_ark, add_dir_to_remote_ark."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from dirark.core import archive_dir, restore_ark
+from dirark.storage import ARK_DIR_EXT, DB_NAME, open_db
+from dirark.sync import add_dir_to_remote_ark, merge_arks, pull_ark, push_ark
+
+
+class TestMergeArks(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+
+        src_a = self.tmp / "a"
+        src_a.mkdir()
+        (src_a / "file_a.txt").write_text("content a")
+        archive_dir(src_a)
+        self.ark_a = self.tmp / ("a" + ARK_DIR_EXT)
+
+        src_b = self.tmp / "b"
+        src_b.mkdir()
+        (src_b / "file_b.txt").write_text("content b")
+        archive_dir(src_b)
+        self.ark_b = self.tmp / ("b" + ARK_DIR_EXT)
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_merge_adds_missing_files(self) -> None:
+        merge_arks(self.ark_b, self.ark_a)
+        db = open_db(self.ark_a / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT path FROM files ORDER BY path")
+        paths = [row[0] for row in cur.fetchall()]
+        db.close()
+        self.assertIn("file_a.txt", paths)
+        self.assertIn("file_b.txt", paths)
+
+    def test_merged_ark_restores_all_files(self) -> None:
+        merge_arks(self.ark_b, self.ark_a)
+        dest = self.tmp / "restored"
+        restore_ark(self.ark_a, dest)
+        self.assertTrue((dest / "file_a.txt").exists())
+        self.assertTrue((dest / "file_b.txt").exists())
+        self.assertEqual((dest / "file_b.txt").read_text(), "content b")
+
+    def test_merge_deduplicates_objects(self) -> None:
+        src_c = self.tmp / "c"
+        src_c.mkdir()
+        (src_c / "dup.txt").write_text("content a")
+        archive_dir(src_c)
+        ark_c = self.tmp / ("c" + ARK_DIR_EXT)
+
+        merge_arks(ark_c, self.ark_a)
+        db = open_db(self.ark_a / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM files")
+        n_files = cur.fetchone()[0]
+        cur.execute("SELECT COUNT(*) FROM objects")
+        n_objects = cur.fetchone()[0]
+        db.close()
+        self.assertEqual(n_files, 2)
+        self.assertEqual(n_objects, 1)
+
+    def test_merge_is_idempotent(self) -> None:
+        merge_arks(self.ark_b, self.ark_a)
+        merge_arks(self.ark_b, self.ark_a)
+        db = open_db(self.ark_a / DB_NAME)
+        cur = db.cursor()
+        cur.execute("SELECT COUNT(*) FROM files")
+        self.assertEqual(cur.fetchone()[0], 2)
+        db.close()
+
+
+class TestPushPullArk(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+        src = self.tmp / "source"
+        src.mkdir()
+        (src / "file1.txt").write_text("pushed content")
+        archive_dir(src)
+        self.local_ark = self.tmp / ("source" + ARK_DIR_EXT)
+        self.remote = self.tmp / "remote_ark"
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_push_copies_files(self) -> None:
+        push_ark(self.local_ark, str(self.remote))
+        self.assertTrue((self.remote / DB_NAME).exists())
+        tars = list(self.remote.glob("*.tar.zst"))
+        self.assertGreater(len(tars), 0)
+
+    def test_pull_copies_files(self) -> None:
+        push_ark(self.local_ark, str(self.remote))
+        dest = self.tmp / "pulled"
+        pull_ark(str(self.remote), dest)
+        self.assertTrue((dest / DB_NAME).exists())
+
+    def test_push_then_restore(self) -> None:
+        push_ark(self.local_ark, str(self.remote))
+        dest = self.tmp / "restored"
+        restore_ark(self.remote, dest)
+        self.assertTrue((dest / "file1.txt").exists())
+        self.assertEqual((dest / "file1.txt").read_text(), "pushed content")
+
+
+class TestAddDirToRemoteArk(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmpdir = tempfile.TemporaryDirectory()
+        self.tmp = Path(self.tmpdir.name)
+
+        remote_src = self.tmp / "remote_src"
+        remote_src.mkdir()
+        (remote_src / "existing.txt").write_text("existing content")
+        archive_dir(remote_src)
+        self.remote_ark = self.tmp / ("remote_src" + ARK_DIR_EXT)
+
+        self.new_src = self.tmp / "new_content"
+        self.new_src.mkdir()
+        (self.new_src / "new.txt").write_text("new content")
+
+    def tearDown(self) -> None:
+        self.tmpdir.cleanup()
+
+    def test_add_dir_merges_into_remote(self) -> None:
+        add_dir_to_remote_ark(self.new_src, str(self.remote_ark))
+        dest = self.tmp / "restored"
+        restore_ark(self.remote_ark, dest)
+        self.assertTrue((dest / "existing.txt").exists())
+        self.assertTrue((dest / "new.txt").exists())
+        self.assertEqual((dest / "new.txt").read_text(), "new content")
+
+    def test_add_dir_preserves_existing_content(self) -> None:
+        add_dir_to_remote_ark(self.new_src, str(self.remote_ark))
+        dest = self.tmp / "restored"
+        restore_ark(self.remote_ark, dest)
+        self.assertEqual((dest / "existing.txt").read_text(), "existing content")

dirark-0.1.0.dist-info/METADATA

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: dirark
+Version: 0.1.0
+Summary: Directory archival
+Project-URL: Homepage, https://github.com/endremborza/dirark
+Author-email: Endre Márk Borza <endremborza@gmail.com>
+License: Copyright 2026 Endre Márk Borza
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# dirark
+
+[![pypi](https://img.shields.io/pypi/v/dirark.svg)](https://pypi.org/project/dirark/)
+
+Directory archival

dirark-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+dirark/__init__.py,sha256=fzqQo7enYCicLXFvn28YdD32nE5bZwbrBMiOFrwIE7E,374
+dirark/__main__.py,sha256=w6QRjnFJEV7N_-wpBNcZTzVmmP3qiRoUdXZLvN7XKtE,3747
+dirark/core.py,sha256=KkHNCATlFm2xkKS13Py3VYhSI9IHUamFaYDR4TZf4xc,3644
+dirark/reader.py,sha256=Awxk-sysH7w8y4ndhKTlU4zSBNSpDOitf48ULxPRoXg,2199
+dirark/storage.py,sha256=9lXXem7qZ5hBDJYY3C-0R4F8DuR6MMf7yAx4AQ7iGNo,4167
+dirark/sync.py,sha256=2UkxBrI0cxoQzpQ89vvqcvv_rb5N0CayWoBPmtDsKJ0,3942
+dirark/tests/test_core.py,sha256=yE6CPYHZ5zpCumFOCfyRphsNmX_NTC1n571IiyEkRSU,7775
+dirark/tests/test_init.py,sha256=9mLvYz3kQNqcrU8URCnfuGrmq7ZO9wFLwUIklyFhdt8,92
+dirark/tests/test_reader.py,sha256=0dbqb-Kbwg7OvCi2VwaWJ3nvbNJTPfGtwRIy0YG0Ydg,2327
+dirark/tests/test_storage.py,sha256=4_BBwaf1B4yO4UrpO_prah52LK-neM_IOtPLtMavMc0,4082
+dirark/tests/test_sync.py,sha256=p2hH9Yc5AYka-3ZVS9fsE7Zw6tonGVp5W2Jkaj60nV8,5153
+dirark-0.1.0.dist-info/METADATA,sha256=8mPfk_QhmehS4zl_fo9eJ_n4YTHsZkFTX5mpIAJntLw,1512
+dirark-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dirark-0.1.0.dist-info/licenses/LICENSE,sha256=NrHeFb1pfm6nQHXGcuumvUALSfJjJv9EZTv4rK-jwR0,1056
+dirark-0.1.0.dist-info/RECORD,,

dirark-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dirark-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Endre Márk Borza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.