kanibako-cli 1.5.0.dev14__py3-none-any.whl

kanibako/settings_seeds.py

@@ -0,0 +1,154 @@
+"""Copy-once-at-init seed resolution (pure, additive).
+
+This module turns settings-framework *seed* config entries into a list of
+``(host_src, guest_dest)`` copy-pairs.  A seed is copied ONCE at box/crab init
+(the CALLER does the copy — this module is **pure**: no file I/O, no copying,
+no global mutable state).  It imports only stdlib and the expression engine in
+:mod:`kanibako.settings_resolve`.  Wiring it into init is a separate increment.
+
+It is the simpler sibling of :mod:`kanibako.settings_shares`: seeds have **no
+``ro``/``rw`` mode**, **no root-join** (``host_src`` is a full expression, not a
+relative path joined under a scope root), and yield plain string pairs instead
+of :class:`~kanibako.targets.base.Mount` objects.
+
+The seed model
+--------------
+A seed is declared with a key of the shape::
+
+    {scope}.path.seeded.{name}
+
+where ``scope`` is one of ``system``/``crab``/``workset``/``box`` and ``name``
+is an arbitrary identifier (it may itself contain dots — everything after
+``seeded.`` is the name).  The value is a ``host_src:guest_dest`` bind
+expression: ``host_src`` resolves in HOST space, ``guest_dest`` in GUEST space
+(a container ``/home/agent/...`` path).
+
+Two orthogonal axes
+~~~~~~~~~~~~~~~~~~~~~
+* **The KEY's scope** is informational (it documents the seed's *reach*).
+* **The LEVEL where the key is SET** decides *precedence*.  These differ on
+  purpose: a box may set ``system.path.seeded.foo = ""`` to **suppress** an
+  inherited system-scoped seed for just that box, or override it with its own
+  ``host_src:guest_dest``.
+
+Suppression / disable
+~~~~~~~~~~~~~~~~~~~~~~~
+A seed is SKIPPED (no copy-pair emitted) when the winning value is either an
+explicit terminal ``""`` (``rv.terminal``) or the sentinel string ``"empty"``
+(mirroring the existing ``resolve_template`` "empty" convention).
+
+Accumulate / apply order
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Distinct seed names accumulate.  For a SINGLE key, the most-specific level that
+set it wins (standard :func:`resolve_value` precedence).  The returned pairs are
+ordered by scope *apply* order ``system, crab, workset, box`` — the REVERSE of
+the precedence list — so a later/more-specific scope's copy overlays an earlier
+one.  Within a scope, pairs are ordered by ``name`` ascending, for full
+determinism.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from kanibako.settings_resolve import (
+    LevelView,
+    ResolveCtx,
+    SettingsError,
+    _Unset,
+    expand_expr,
+    resolve_value,
+    split_bind,
+)
+
+# Matches a seed key: scope . path . seeded . name
+# (name greedily captures the remainder, which may contain dots).
+SEED_KEY_RE = re.compile(
+    r"^(?P<scope>system|crab|workset|box)\.path\.seeded\.(?P<name>.+)$"
+)
+
+# Sentinel value that disables a seed (parallels resolve_template's "empty").
+_DISABLE_SENTINEL = "empty"
+
+
+def is_seed_key(key: str) -> bool:
+    """True if *key* is a seed config key ({scope}.path.seeded.{name})."""
+    return SEED_KEY_RE.match(key) is not None
+
+
+# Apply order: REVERSE of precedence (most-specific scope copies LAST so a
+# later copy overlays an earlier one).
+_SCOPE_APPLY_ORDER = {"system": 0, "crab": 1, "workset": 2, "box": 3}
+
+
+@dataclass(frozen=True)
+class SeedPair:
+    """A resolved copy-once-at-init seed: copy host_src -> guest_dest (guest space)."""
+
+    host_src: str       # resolved host path
+    guest_dest: str     # resolved guest/container path (e.g. /home/agent/...)
+    scope: str          # "system" | "crab" | "workset" | "box"
+    name: str
+
+
+def resolve_seeds(
+    *,
+    levels: list[LevelView],
+    ctx: ResolveCtx,
+    lookup: Callable[[str, tuple[str, ...]], str],
+) -> list[SeedPair]:
+    """Resolve seed config into a deterministic list of copy-pairs.
+
+    *levels* are ordered MOST-SPECIFIC-FIRST (``[box, workset, crab, system]``).
+    *lookup* resolves ``@``-refs (typically a closure over *levels*).  Returns
+    :class:`SeedPair` objects in apply order (see module docstring).  Raises
+    :class:`SettingsError` if a non-suppressed seed value lacks a
+    ``host_src:guest_dest`` colon.
+    """
+    # 1. Discover seed keys across every level's values AND defaults.
+    keys: set[str] = set()
+    for level in levels:
+        for key in level.values:
+            if SEED_KEY_RE.match(key):
+                keys.add(key)
+        for key in level.defaults:
+            if SEED_KEY_RE.match(key):
+                keys.add(key)
+
+    pairs: list[tuple[tuple[int, str], SeedPair]] = []
+    for key in keys:
+        m = SEED_KEY_RE.match(key)
+        assert m is not None  # keys were filtered by the same regex.
+        scope = m.group("scope")
+        name = m.group("name")
+
+        rv = resolve_value(key, levels=levels, ctx=ctx, lookup=lookup)
+        if isinstance(rv, _Unset):
+            # Defensive: the key came from some level, so it must resolve.
+            continue
+        if rv.terminal:
+            # Explicit "" — suppressed; do not copy.
+            continue
+        if rv.value == _DISABLE_SENTINEL:
+            # "empty" sentinel — disabled; do not copy.
+            continue
+
+        host_src_raw, guest_dest_raw = split_bind(rv.value)
+        if guest_dest_raw is None:
+            raise SettingsError(
+                f"Seed '{key}' must specify 'host_src:guest_dest' "
+                f"(no unescaped ':' in value {rv.value!r})."
+            )
+
+        host_src = expand_expr(host_src_raw, space="host", ctx=ctx, lookup=lookup)
+        guest_dest = expand_expr(guest_dest_raw, space="guest", ctx=ctx, lookup=lookup)
+
+        sort_key = (_SCOPE_APPLY_ORDER[scope], name)
+        pairs.append(
+            (sort_key, SeedPair(host_src=host_src, guest_dest=guest_dest, scope=scope, name=name))
+        )
+
+    pairs.sort(key=lambda pair: pair[0])
+    return [seed for _, seed in pairs]

kanibako/settings_shares.py

@@ -0,0 +1,154 @@
+"""Scoped-share resolution (pure, additive).
+
+This module turns settings-framework *scoped-share* config entries into a list
+of :class:`~kanibako.targets.base.Mount` objects.  It is **pure**: no file I/O,
+no global mutable state.  It imports only stdlib, the expression engine in
+:mod:`kanibako.settings_resolve`, and the :class:`Mount` dataclass.  Wiring it
+into container launch is a separate increment.
+
+The share model
+---------------
+A share is declared with a key of the shape::
+
+    {scope}.path.share_{ro|rw}.{name}
+
+where ``scope`` is one of ``system``/``crab``/``workset``/``box``, the mode is
+``ro`` or ``rw``, and ``name`` is an arbitrary identifier (it may itself contain
+dots — everything after ``share_{ro,rw}.`` is the name).  The value is a
+``host_src:guest_dest`` bind expression.
+
+Two orthogonal axes
+~~~~~~~~~~~~~~~~~~~~~
+* **The KEY's scope** decides the *source root* the relative ``host_src`` is
+  joined under (via *scope_roots*) and the *mount mode* (``ro`` → ``"ro"``;
+  ``rw`` → ``"Z,U"``).
+* **The LEVEL where the key is SET** decides *precedence*.  These differ on
+  purpose: a box may set ``system.path.share_rw.foo = ""`` to **suppress** the
+  system-scoped share ``foo`` for just that box (foreign-prefix suppression —
+  an explicit ``""`` is terminal and produces no mount).
+
+Accumulate / apply order
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Distinct share names accumulate.  For a SINGLE key, the most-specific level that
+set it wins (standard :func:`resolve_value` precedence).  The returned mounts
+are ordered by scope *apply* order ``system, crab, workset, box`` — the REVERSE
+of the precedence list — so the most-specific scope comes LAST, letting
+podman's "last ``-v`` wins" dedup honor box over system.  Within a scope, mounts
+are ordered by ``(mode, name)`` ascending, for full determinism.
+
+Root-join rule
+~~~~~~~~~~~~~~~
+*scope_roots* maps a GROUP PREFIX (the key up to and including
+``share_ro``/``share_rw``, e.g. ``"crab.path.share_rw"``) to a host-space root
+expression (e.g. ``"@system.path.crabs/$CRAB/share"``).  When a root exists for
+a key's group AND the resolved ``host_src`` is NOT absolute, the source becomes
+``root / host_src``; otherwise ``host_src`` is used as-is.  A group absent from
+*scope_roots* (or mapped to ``None``/``""``) means no join — this is the ``box``
+case, where ``host_src`` is an arbitrary host path.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from kanibako.settings_resolve import (
+    LevelView,
+    ResolveCtx,
+    SettingsError,
+    _Unset,
+    expand_expr,
+    resolve_value,
+    split_bind,
+)
+from kanibako.targets.base import Mount
+
+# Matches a scoped-share key: scope . path . share_{ro|rw} . name
+# (name greedily captures the remainder, which may contain dots).
+SHARE_KEY_RE = re.compile(
+    r"^(?P<scope>system|crab|workset|box)\.path\.share_(?P<mode>ro|rw)\.(?P<name>.+)$"
+)
+
+
+def is_share_key(key: str) -> bool:
+    """True if *key* is a scoped-share config key ({scope}.path.share_{ro,rw}.{name})."""
+    return SHARE_KEY_RE.match(key) is not None
+
+
+# Apply order: REVERSE of precedence (most-specific scope mounts LAST so
+# podman's last-`-v`-wins dedup honors it).
+_SCOPE_APPLY_ORDER = {"system": 0, "crab": 1, "workset": 2, "box": 3}
+
+
+def resolve_shares(
+    *,
+    levels: list[LevelView],
+    ctx: ResolveCtx,
+    lookup: Callable[[str, tuple[str, ...]], str],
+    scope_roots: Mapping[str, str] | None = None,
+) -> list[Mount]:
+    """Resolve scoped-share config into a deterministic list of mounts.
+
+    *levels* are ordered MOST-SPECIFIC-FIRST (``[box, workset, crab, system]``).
+    *lookup* resolves ``@``-refs (typically a closure over *levels*).
+    *scope_roots* maps a group prefix (``"{scope}.path.share_{ro,rw}"``) to a
+    host-space root expression; absent/empty means no root join.  Returns mounts
+    in apply order (see module docstring).  Raises :class:`SettingsError` if a
+    non-suppressed share value lacks a ``host_src:guest_dest`` colon.
+    """
+    # 1. Discover share keys across every level's values AND defaults.
+    keys: set[str] = set()
+    for level in levels:
+        for key in level.values:
+            if SHARE_KEY_RE.match(key):
+                keys.add(key)
+        for key in level.defaults:
+            if SHARE_KEY_RE.match(key):
+                keys.add(key)
+
+    mounts: list[tuple[tuple[int, str, str], Mount]] = []
+    for key in keys:
+        m = SHARE_KEY_RE.match(key)
+        assert m is not None  # keys were filtered by the same regex.
+        scope = m.group("scope")
+        mode = m.group("mode")
+        name = m.group("name")
+        group = f"{scope}.path.share_{mode}"
+
+        rv = resolve_value(key, levels=levels, ctx=ctx, lookup=lookup)
+        if isinstance(rv, _Unset):
+            # Defensive: the key came from some level, so it must resolve.
+            continue
+        if rv.terminal:
+            # Explicit "" — suppressed; do not mount.
+            continue
+
+        host_src_raw, guest_dest_raw = split_bind(rv.value)
+        if guest_dest_raw is None:
+            raise SettingsError(
+                f"Share '{key}' must specify 'host_src:guest_dest' "
+                f"(no unescaped ':' in value {rv.value!r})."
+            )
+
+        host_src = expand_expr(
+            host_src_raw, space="host", ctx=ctx, lookup=lookup,
+        )
+        guest_dest = expand_expr(
+            guest_dest_raw, space="guest", ctx=ctx, lookup=lookup,
+        )
+
+        # Root join: only for relative host_src under a group that has a root.
+        root_expr = scope_roots.get(group) if scope_roots else None
+        if root_expr and not host_src.startswith("/"):
+            root = expand_expr(root_expr, space="host", ctx=ctx, lookup=lookup)
+            source = Path(root) / host_src
+        else:
+            source = Path(host_src)
+
+        options = "ro" if mode == "ro" else "Z,U"
+        sort_key = (_SCOPE_APPLY_ORDER[scope], mode, name)
+        mounts.append((sort_key, Mount(source=source, destination=guest_dest, options=options)))
+
+    mounts.sort(key=lambda pair: pair[0])
+    return [mount for _, mount in mounts]

kanibako/shellenv.py

@@ -0,0 +1,75 @@
+"""Environment variable file handling for per-project and global env vars."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+    """Read a Docker-style .env file and return key-value pairs.
+
+    - One KEY=VALUE per line
+    - Lines starting with ``#`` are comments
+    - Empty lines are ignored
+    - No shell expansion (values are literal)
+    - Invalid lines are silently skipped
+    """
+    env: dict[str, str] = {}
+    if not path.is_file():
+        return env
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if not _KEY_RE.match(key):
+            continue
+        env[key] = value
+    return env
+
+
+def write_env_file(path: Path, env: dict[str, str]) -> None:
+    """Write a dict of env vars to a Docker-style .env file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    for key, value in sorted(env.items()):
+        lines.append(f"{key}={value}")
+    path.write_text("\n".join(lines) + "\n" if lines else "")
+
+
+def set_env_var(path: Path, key: str, value: str) -> None:
+    """Set a single env var in an env file (read-modify-write)."""
+    if not _KEY_RE.match(key):
+        raise ValueError(f"Invalid environment variable name: {key}")
+    env = read_env_file(path)
+    env[key] = value
+    write_env_file(path, env)
+
+
+def unset_env_var(path: Path, key: str) -> bool:
+    """Remove an env var from an env file. Returns True if it existed."""
+    env = read_env_file(path)
+    if key not in env:
+        return False
+    del env[key]
+    write_env_file(path, env)
+    return True
+
+
+def merge_env(
+    global_path: Path | None,
+    project_path: Path | None,
+) -> dict[str, str]:
+    """Merge global and project env files. Project wins on conflict."""
+    env: dict[str, str] = {}
+    if global_path:
+        env.update(read_env_file(global_path))
+    if project_path:
+        env.update(read_env_file(project_path))
+    return env

kanibako/snapshots.py

@@ -0,0 +1,281 @@
+"""Snapshot engine for vault share-rw directories.
+
+Provides point-in-time backups of ``share-rw/`` stored in a ``.versions/``
+sibling directory.  Three strategies are supported:
+
+* **reflink** -- copy-on-write clone (instant, space-efficient; requires a
+  COW filesystem such as Btrfs or XFS with reflink support).
+* **hardlink** -- ``rsync --link-dest`` so unchanged files share inodes
+  (fast, moderate space; works on any POSIX filesystem).
+* **tarxz** -- compressed tar archive (slow but universally portable; legacy
+  default).
+
+``detect_snapshot_strategy`` probes the filesystem and picks the best option
+automatically.  Automatic snapshots can be triggered before each container
+launch.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tarfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+# Default maximum number of snapshots to retain.
+_DEFAULT_MAX_SNAPSHOTS = 5
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _versions_dir(vault_rw_path: Path) -> Path:
+    """Return the .versions/ directory for a vault share-rw path."""
+    return vault_rw_path.parent / ".versions"
+
+
+def _test_reflink(path: Path) -> bool:
+    """Test if *path*'s filesystem supports reflinks."""
+    if not path.is_dir():
+        return False
+    test_src = path / ".reflink-test-src"
+    test_dst = path / ".reflink-test-dst"
+    try:
+        test_src.write_bytes(b"test")
+        result = subprocess.run(
+            ["cp", "--reflink=always", str(test_src), str(test_dst)],
+            capture_output=True,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+    finally:
+        test_src.unlink(missing_ok=True)
+        test_dst.unlink(missing_ok=True)
+
+
+def detect_snapshot_strategy(vault_path: Path) -> str:
+    """Detect the best snapshot strategy for the given path.
+
+    Returns ``"reflink"``, ``"hardlink"``, or ``"tarxz"``.
+    """
+    if _test_reflink(vault_path):
+        return "reflink"
+    # hardlink is always available on POSIX
+    return "hardlink"
+
+
+# ---------------------------------------------------------------------------
+# Strategy implementations
+# ---------------------------------------------------------------------------
+
+
+def _snapshot_tarxz(vault_rw_path: Path, versions: Path, ts: str) -> Path:
+    """Create a tar.xz snapshot (original behaviour)."""
+    archive = versions / f"{ts}.tar.xz"
+    with tarfile.open(archive, "w:xz") as tar:
+        for item in sorted(vault_rw_path.iterdir()):
+            tar.add(str(item), arcname=item.name)
+    return archive
+
+
+def _snapshot_reflink(vault_rw_path: Path, versions: Path, ts: str) -> Path:
+    """Create a snapshot using reflink (COW) copy."""
+    dest = versions / ts
+    subprocess.run(
+        ["cp", "--reflink=always", "-a", str(vault_rw_path), str(dest)],
+        check=True,
+        capture_output=True,
+    )
+    return dest
+
+
+def _snapshot_hardlink(vault_rw_path: Path, versions: Path, ts: str) -> Path:
+    """Create a snapshot using hardlinks (fast for unchanged files)."""
+    dest = versions / ts
+    # Find the most recent directory snapshot for --link-dest.
+    existing = sorted(
+        (d for d in versions.iterdir() if d.is_dir()),
+        key=lambda p: p.name,
+    )
+    link_dest = existing[-1] if existing else None
+
+    cmd = ["rsync", "-a"]
+    if link_dest:
+        cmd.extend(["--link-dest", str(link_dest)])
+    cmd.extend([str(vault_rw_path) + "/", str(dest) + "/"])
+
+    try:
+        subprocess.run(cmd, check=True, capture_output=True)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        # rsync not available or failed -- fall back to regular copy.
+        shutil.copytree(vault_rw_path, dest)
+    return dest
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def create_snapshot(
+    vault_rw_path: Path, strategy: str = "tarxz",
+) -> Path | None:
+    """Create a snapshot using the given strategy.
+
+    Returns the path to the snapshot (archive or directory), or ``None`` if
+    the directory is empty (nothing to snapshot).
+    """
+    if not vault_rw_path.is_dir():
+        return None
+
+    # Don't snapshot an empty directory.
+    contents = list(vault_rw_path.iterdir())
+    if not contents:
+        return None
+
+    versions = _versions_dir(vault_rw_path)
+    versions.mkdir(parents=True, exist_ok=True)
+
+    ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+    if strategy == "reflink":
+        return _snapshot_reflink(vault_rw_path, versions, ts)
+    elif strategy == "hardlink":
+        return _snapshot_hardlink(vault_rw_path, versions, ts)
+    else:
+        return _snapshot_tarxz(vault_rw_path, versions, ts)
+
+
+def list_snapshots(vault_rw_path: Path) -> list[tuple[str, str, int]]:
+    """List snapshots for *vault_rw_path*.
+
+    Returns a list of ``(name, timestamp_iso, size_bytes)`` sorted by time
+    (oldest first).  Both directory snapshots (reflink / hardlink) and
+    legacy tar.xz archives are included.
+    """
+    versions = _versions_dir(vault_rw_path)
+    if not versions.is_dir():
+        return []
+
+    snapshots: list[tuple[str, str, int]] = []
+    for entry in sorted(versions.iterdir()):
+        name = entry.name
+        if entry.is_dir():
+            # Directory snapshot (reflink or hardlink).
+            try:
+                dt = datetime.strptime(name, "%Y%m%dT%H%M%SZ")
+                ts_iso = dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+            except ValueError:
+                ts_iso = name
+            # Approximate size.
+            try:
+                size = sum(
+                    f.stat().st_size for f in entry.rglob("*") if f.is_file()
+                )
+            except Exception:
+                size = 0
+            snapshots.append((name, ts_iso, size))
+        elif entry.name.endswith(".tar.xz"):
+            # Legacy tar.xz snapshot.
+            stem = name.removesuffix(".tar.xz")
+            try:
+                dt = datetime.strptime(stem, "%Y%m%dT%H%M%SZ")
+                ts_iso = dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+            except ValueError:
+                ts_iso = stem
+            size = entry.stat().st_size
+            snapshots.append((name, ts_iso, size))
+
+    return snapshots
+
+
+def restore_snapshot(vault_rw_path: Path, snapshot_name: str) -> None:
+    """Restore *vault_rw_path* from the named snapshot.
+
+    Handles both directory snapshots and legacy tar.xz archives.  The
+    current contents of share-rw are replaced with the snapshot contents.
+    Raises ``FileNotFoundError`` if the snapshot does not exist.
+    """
+    versions = _versions_dir(vault_rw_path)
+    snapshot = versions / snapshot_name
+
+    if snapshot.is_dir():
+        # Directory snapshot (reflink or hardlink).
+        if vault_rw_path.is_dir():
+            for item in vault_rw_path.iterdir():
+                if item.is_dir():
+                    shutil.rmtree(item)
+                else:
+                    item.unlink()
+        vault_rw_path.mkdir(parents=True, exist_ok=True)
+        # Copy contents.
+        for item in snapshot.iterdir():
+            dest = vault_rw_path / item.name
+            if item.is_dir():
+                shutil.copytree(item, dest)
+            else:
+                shutil.copy2(item, dest)
+    elif snapshot.is_file() and snapshot_name.endswith(".tar.xz"):
+        # Legacy tar.xz.
+        if vault_rw_path.is_dir():
+            for item in vault_rw_path.iterdir():
+                if item.is_dir():
+                    shutil.rmtree(item)
+                else:
+                    item.unlink()
+        with tarfile.open(snapshot, "r:xz") as tar:
+            tar.extractall(path=str(vault_rw_path), filter="data")
+    else:
+        raise FileNotFoundError(f"Snapshot not found: {snapshot_name}")
+
+
+def prune_snapshots(
+    vault_rw_path: Path, max_keep: int = _DEFAULT_MAX_SNAPSHOTS,
+) -> int:
+    """Remove old snapshots, keeping at most *max_keep*.
+
+    Handles both directory snapshots and legacy tar.xz archives.
+    Returns the number of snapshots removed.
+    """
+    versions = _versions_dir(vault_rw_path)
+    if not versions.is_dir():
+        return 0
+
+    # Collect all snapshots (dirs and tar.xz files).
+    all_snapshots = sorted(
+        (
+            f
+            for f in versions.iterdir()
+            if f.is_dir() or f.name.endswith(".tar.xz")
+        ),
+        key=lambda p: p.name.removesuffix(".tar.xz"),
+    )
+    to_remove = all_snapshots[:-max_keep] if len(all_snapshots) > max_keep else []
+    for old in to_remove:
+        if old.is_dir():
+            shutil.rmtree(old)
+        else:
+            old.unlink()
+    return len(to_remove)
+
+
+def auto_snapshot(
+    vault_rw_path: Path,
+    *,
+    strategy: str = "tarxz",
+    max_keep: int = _DEFAULT_MAX_SNAPSHOTS,
+) -> Path | None:
+    """Create a snapshot and prune old ones.
+
+    Convenience wrapper combining ``create_snapshot`` + ``prune_snapshots``.
+    Returns the new snapshot path, or ``None`` if share-rw was empty.
+    """
+    result = create_snapshot(vault_rw_path, strategy=strategy)
+    if result is not None:
+        prune_snapshots(vault_rw_path, max_keep=max_keep)
+    return result