restic-backups 0.1.1__tar.gz

restic_backups-0.1.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.3
+Name: restic-backups
+Version: 0.1.1
+Summary: Restic backup CLI with optional SOPS configuration.
+Requires-Dist: click>=8.1
+Requires-Dist: mlx-whisper>=0.4.0 ; platform_machine == 'arm64' and sys_platform == 'darwin'
+Requires-Dist: pyannote-audio>=3.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: requests>=2.32
+Requires-Dist: textual>=0.80
+Requires-Dist: torch>=2.0
+Requires-Dist: torchaudio>=2.0
+Requires-Dist: typer>=0.25.1
+Requires-Python: >=3.11
+Project-URL: Documentation, https://jr200-labs.github.io/restic-backups/
+Project-URL: Repository, https://github.com/jr200-labs/restic-backups
+Description-Content-Type: text/markdown
+
+# Restic Backups
+
+YAML configuration and a Python CLI for running multiple restic repositories,
+with optional SOPS decryption. The package currently includes a complete macOS
+Voice Memos workflow for backup, transcription, summarisation, and speaker
+diarization.
+
+Backup payloads, generated metadata, model caches, and restores are excluded
+from Git by a default-deny `.gitignore`.
+
+## Install
+
+```sh
+make install-deps  # Homebrew: restic, sops, uv, ffmpeg, jq, coreutils
+make install       # uv sync, including the dev group and Quarto
+```
+
+`make init` loads the selected configuration, deduplicates enabled
+stores referenced by a backup, and runs `restic init` once per repository. It
+does not back up files and is unnecessary for an existing repository.
+
+## CLI
+
+Use the built-in help for available commands and options:
+
+```sh
+uv run restic-backups --help
+uv run restic-backups generic --help
+uv run restic-backups voice-memos --help
+```
+
+## Configuration
+
+Pass a plain YAML file explicitly:
+
+```sh
+uv run restic-backups --config config.yaml check-config
+```
+
+For SOPS, add `--sops`. The equivalent environment variables are
+`RESTIC_BACKUPS_CONFIG` and `RESTIC_BACKUPS_SOPS=1`; they also configure
+`make config-check` and `make init`.
+
+The configuration separates:
+
+- `credentials`: reusable S3-compatible authentication;
+- `restic-stores`: endpoint, region, bucket, key prefix/password, and optional
+  archive policy;
+- `backups`: jobs linked to a store by `restic-store-id`.
+
+One credential may serve many stores, and multiple backups may share a store.
+Disabled stores may contain `CHANGE_ME`; all placeholders must be replaced
+before enabling one.
+
+## Data and source paths
+
+Managed local artifacts use:
+
+```text
+data/<store-id>/<bucket>/<key-prefix>/<backup-id>/
+```
+
+This is metadata/workspace organization, not a restriction on backup sources.
+Restic may back up absolute paths anywhere on the machine. Resolve a managed
+directory without exposing credentials with:
+
+```sh
+uv run restic-backups generic data-dir voice-memos
+```
+
+## AWS Glacier
+
+Use `GLACIER_IR` with `restore: null` for normal immediate restic access. Cold
+`GLACIER` and `DEEP_ARCHIVE` stores require a configured retrieval tier, days,
+and timeout. Retrieval must also be acknowledged at runtime:
+
+```sh
+ALLOW_ARCHIVE_RETRIEVAL=1 uv run restic-backups generic run \
+  --backup <backup-id> restore latest --target <dir>
+```
+
+Storage-class changes apply only to new objects. Use a new `key_prefix` instead
+of mixing storage policies in one repository.
+
+## Documentation
+
+```sh
+make docs          # render docs/_site
+make docs-preview  # local preview server
+```
+
+Start with [the Quarto guide](docs/index.qmd). Never commit decrypted SOPS
+configuration or anything below `data/`.

restic_backups-0.1.1/README.md

@@ -0,0 +1,93 @@
+# Restic Backups
+
+YAML configuration and a Python CLI for running multiple restic repositories,
+with optional SOPS decryption. The package currently includes a complete macOS
+Voice Memos workflow for backup, transcription, summarisation, and speaker
+diarization.
+
+Backup payloads, generated metadata, model caches, and restores are excluded
+from Git by a default-deny `.gitignore`.
+
+## Install
+
+```sh
+make install-deps  # Homebrew: restic, sops, uv, ffmpeg, jq, coreutils
+make install       # uv sync, including the dev group and Quarto
+```
+
+`make init` loads the selected configuration, deduplicates enabled
+stores referenced by a backup, and runs `restic init` once per repository. It
+does not back up files and is unnecessary for an existing repository.
+
+## CLI
+
+Use the built-in help for available commands and options:
+
+```sh
+uv run restic-backups --help
+uv run restic-backups generic --help
+uv run restic-backups voice-memos --help
+```
+
+## Configuration
+
+Pass a plain YAML file explicitly:
+
+```sh
+uv run restic-backups --config config.yaml check-config
+```
+
+For SOPS, add `--sops`. The equivalent environment variables are
+`RESTIC_BACKUPS_CONFIG` and `RESTIC_BACKUPS_SOPS=1`; they also configure
+`make config-check` and `make init`.
+
+The configuration separates:
+
+- `credentials`: reusable S3-compatible authentication;
+- `restic-stores`: endpoint, region, bucket, key prefix/password, and optional
+  archive policy;
+- `backups`: jobs linked to a store by `restic-store-id`.
+
+One credential may serve many stores, and multiple backups may share a store.
+Disabled stores may contain `CHANGE_ME`; all placeholders must be replaced
+before enabling one.
+
+## Data and source paths
+
+Managed local artifacts use:
+
+```text
+data/<store-id>/<bucket>/<key-prefix>/<backup-id>/
+```
+
+This is metadata/workspace organization, not a restriction on backup sources.
+Restic may back up absolute paths anywhere on the machine. Resolve a managed
+directory without exposing credentials with:
+
+```sh
+uv run restic-backups generic data-dir voice-memos
+```
+
+## AWS Glacier
+
+Use `GLACIER_IR` with `restore: null` for normal immediate restic access. Cold
+`GLACIER` and `DEEP_ARCHIVE` stores require a configured retrieval tier, days,
+and timeout. Retrieval must also be acknowledged at runtime:
+
+```sh
+ALLOW_ARCHIVE_RETRIEVAL=1 uv run restic-backups generic run \
+  --backup <backup-id> restore latest --target <dir>
+```
+
+Storage-class changes apply only to new objects. Use a new `key_prefix` instead
+of mixing storage policies in one repository.
+
+## Documentation
+
+```sh
+make docs          # render docs/_site
+make docs-preview  # local preview server
+```
+
+Start with [the Quarto guide](docs/index.qmd). Never commit decrypted SOPS
+configuration or anything below `data/`.

restic_backups-0.1.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "restic-backups"
+version = "0.1.1"
+description = "Restic backup CLI with optional SOPS configuration."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1",
+    "mlx-whisper>=0.4.0; platform_system == 'Darwin' and platform_machine == 'arm64'",
+    "pyannote.audio>=3.1",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "requests>=2.32",
+    "textual>=0.80",
+    "torch>=2.0",
+    "torchaudio>=2.0",
+    "typer>=0.25.1",
+]
+
+[project.urls]
+Documentation = "https://jr200-labs.github.io/restic-backups/"
+Repository = "https://github.com/jr200-labs/restic-backups"
+
+[project.scripts]
+restic-backups = "restic_backups.cli:app"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "quarto-cli>=1.9.38",
+    "ruff>=0.14.14",
+    "types-pyyaml>=6.0.12.20250915",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+
+[tool.mypy]
+packages = ["restic_backups"]
+
+[[tool.mypy.overrides]]
+module = ["restic_backups.voice_memos.*"]
+ignore_errors = true
+
+[tool.ruff]
+extend = ".shared/ruff.toml"

restic_backups-0.1.1/pyproject.toml.orig

@@ -0,0 +1,52 @@
+[project]
+name = "restic-backups"
+version = "0.1.1"
+description = "Restic backup CLI with optional SOPS configuration."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1",
+    "mlx-whisper>=0.4.0; platform_system == 'Darwin' and platform_machine == 'arm64'",
+    "pyannote.audio>=3.1",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "requests>=2.32",
+    "textual>=0.80",
+    "torch>=2.0",
+    "torchaudio>=2.0",
+    "typer>=0.25.1",
+]
+
+[project.urls]
+Documentation = "https://jr200-labs.github.io/restic-backups/"
+Repository = "https://github.com/jr200-labs/restic-backups"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "quarto-cli>=1.9.38",
+    "ruff>=0.14.14",
+    "types-pyyaml>=6.0.12.20250915",
+]
+
+[project.scripts]
+restic-backups = "restic_backups.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+
+[tool.mypy]
+packages = ["restic_backups"]
+
+# ponytail: the ML/Click workflow is dynamically typed; remove as it gains annotations.
+[[tool.mypy.overrides]]
+module = ["restic_backups.voice_memos.*"]
+ignore_errors = true
+
+[tool.ruff]
+extend = ".shared/ruff.toml"

restic_backups-0.1.1/src/restic_backups/__init__.py

@@ -0,0 +1 @@
+"""Restic backups CLI."""

restic_backups-0.1.1/src/restic_backups/cli.py

@@ -0,0 +1,103 @@
+"""Command-line interface for configured restic backups."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+
+import typer
+
+from . import config as config_module
+from .errors import BackupError
+from .generic import cli as generic_cli
+from .generic import repository
+from .generic import sops as sops_module
+
+app = typer.Typer(
+    help="Configured backup commands.",
+    no_args_is_help=True,
+)
+app.add_typer(generic_cli.app, name="generic")
+
+
+@app.callback()
+def configure(
+    config_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            envvar=config_module.CONFIG_ENV,
+            dir_okay=False,
+            help=f"YAML configuration file. Env: {config_module.CONFIG_ENV}.",
+        ),
+    ] = None,
+    use_sops: Annotated[
+        bool,
+        typer.Option(
+            "--sops",
+            envvar=sops_module.SOPS_ENV,
+            help=f"Decrypt the configuration with SOPS. Env: {sops_module.SOPS_ENV}.",
+        ),
+    ] = False,
+) -> None:
+    """Configure storage before running a command."""
+    if config_file is not None:
+        os.environ[config_module.CONFIG_ENV] = str(config_file)
+    os.environ[sops_module.SOPS_ENV] = "1" if use_sops else "0"
+
+
+def fail(message: str) -> NoReturn:
+    typer.echo(f"restic-backups: {message}", err=True)
+    raise typer.Exit(1)
+
+
+def validated() -> tuple[
+    dict[str, Any],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    try:
+        return config_module.load_validated()
+    except BackupError as exc:
+        fail(str(exc))
+
+
+@app.command("check-config")
+def check_config_command() -> None:
+    """Validate configuration without contacting remote storage."""
+    validated()
+    typer.echo("config ok")
+
+
+@app.command(
+    "voice-memos",
+    context_settings={
+        "allow_extra_args": True,
+        "ignore_unknown_options": True,
+        "help_option_names": [],
+    },
+)
+def voice_memos_command(context: typer.Context) -> None:
+    """Back up, transcribe, summarise, and diarize macOS Voice Memos."""
+    if "SUMMARIES_DIR" not in os.environ and "--help" not in context.args:
+        _, credentials, stores, backups = validated()
+        try:
+            store, _ = repository.resolve("voice-memos", credentials, stores, backups)
+            path = repository.data_dir("voice-memos", store) / "summaries"
+        except BackupError as exc:
+            fail(str(exc))
+        os.environ["SUMMARIES_DIR"] = str(path)
+
+    from .voice_memos.cli import cli
+
+    cli.main(
+        args=list(context.args),
+        prog_name="restic-backups voice-memos",
+        standalone_mode=True,
+    )
+
+
+if __name__ == "__main__":
+    app()

restic_backups-0.1.1/src/restic_backups/config.py

@@ -0,0 +1,152 @@
+"""Load and validate backup configuration."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, NoReturn
+
+import yaml
+
+from .errors import BackupError
+from .generic import sops
+
+CONFIG_ENV = "RESTIC_BACKUPS_CONFIG"
+PLACEHOLDER = "CHANGE_ME"
+
+
+class ConfigError(Exception):
+    pass
+
+
+def fail(message: str) -> NoReturn:
+    raise BackupError(message)
+
+
+def config_path() -> Path:
+    value = os.environ.get(CONFIG_ENV)
+    if not value:
+        fail(f"set --config or {CONFIG_ENV}")
+    return Path(value).expanduser()
+
+
+def load_config(path: Path, use_sops: bool) -> dict[str, Any]:
+    if use_sops:
+        return sops.decrypt(path)
+    try:
+        loaded = yaml.safe_load(path.read_text())
+    except FileNotFoundError:
+        fail(f"config file not found: {path}")
+    except OSError as exc:
+        fail(f"could not read {path}: {exc}")
+    except yaml.YAMLError as exc:
+        fail(f"config is not valid YAML: {exc}")
+    if not isinstance(loaded, dict):
+        fail(f"config in {path} must be a mapping")
+    return loaded
+
+
+def required_text(item: dict[str, Any], field: str, owner: str) -> str:
+    value = item.get(field)
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"{owner}.{field} must be a non-empty string")
+    return value
+
+
+def indexed(config: dict[str, Any], section: str) -> dict[str, dict[str, Any]]:
+    items = config.get(section)
+    if not isinstance(items, list) or not items:
+        raise ConfigError(f"{section} must be a non-empty list")
+    result: dict[str, dict[str, Any]] = {}
+    for item in items:
+        if not isinstance(item, dict):
+            raise ConfigError(f"{section} entries must be mappings")
+        item_id = required_text(item, "id", section)
+        if item_id in result:
+            raise ConfigError(f"duplicate {section} id '{item_id}'")
+        result[item_id] = item
+    return result
+
+
+def validate(
+    config: dict[str, Any],
+) -> tuple[
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    credentials = indexed(config, "credentials")
+    stores = indexed(config, "restic-stores")
+    backups = indexed(config, "backups")
+
+    for credential_id, credential in credentials.items():
+        for field in ("access-key-id", "secret-access-key"):
+            required_text(credential, field, credential_id)
+
+    for store_id, store in stores.items():
+        credential_id = required_text(store, "credentials-id", store_id)
+        store_credential = credentials.get(credential_id)
+        if store_credential is None:
+            raise ConfigError(
+                f"{store_id} references unknown credentials '{credential_id}'"
+            )
+        if not isinstance(store.get("enabled"), bool):
+            raise ConfigError(f"{store_id}.enabled must be true or false")
+        required = [
+            required_text(store, field, store_id)
+            for field in ("endpoint", "region", "bucket", "key_prefix", "password")
+        ]
+        if store["enabled"] and PLACEHOLDER in required:
+            raise ConfigError(f"{store_id} is enabled but contains placeholders")
+        if store["enabled"] and any(
+            store_credential[field] == PLACEHOLDER
+            for field in ("access-key-id", "secret-access-key")
+        ):
+            raise ConfigError(f"{store_id} uses placeholder credentials")
+
+        archive = store.get("archive")
+        if archive is None:
+            continue
+        if not isinstance(archive, dict):
+            raise ConfigError(f"{store_id}.archive must be a mapping")
+        storage_class = required_text(archive, "storage-class", f"{store_id}.archive")
+        restore = archive.get("restore")
+        if storage_class == "GLACIER_IR":
+            if restore is not None:
+                raise ConfigError(f"{store_id}: GLACIER_IR forbids a restore policy")
+            continue
+        tiers = {
+            "GLACIER": {"Standard", "Bulk", "Expedited"},
+            "DEEP_ARCHIVE": {"Standard", "Bulk"},
+        }.get(storage_class)
+        if tiers is None or not isinstance(restore, dict):
+            raise ConfigError(f"{store_id} has an invalid cold-storage policy")
+        if restore.get("tier") not in tiers:
+            raise ConfigError(f"{store_id} has an invalid retrieval tier")
+        if not isinstance(restore.get("days"), int) or restore["days"] <= 0:
+            raise ConfigError(f"{store_id}.archive.restore.days must be positive")
+        required_text(restore, "timeout", f"{store_id}.archive.restore")
+
+    for backup_id, backup in backups.items():
+        store_id = required_text(backup, "restic-store-id", backup_id)
+        if store_id not in stores:
+            raise ConfigError(
+                f"{backup_id} references unknown restic store '{store_id}'"
+            )
+
+    return credentials, stores, backups
+
+
+def load_validated() -> tuple[
+    dict[str, Any],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    path = config_path()
+    loaded = load_config(path, os.environ.get(sops.SOPS_ENV) == "1")
+    try:
+        credentials, stores, backups = validate(loaded)
+    except ConfigError as exc:
+        fail(f"invalid config in {path}: {exc}")
+    return loaded, credentials, stores, backups

restic_backups-0.1.1/src/restic_backups/errors.py

@@ -0,0 +1,5 @@
+"""Shared application errors."""
+
+
+class BackupError(Exception):
+    pass

restic_backups-0.1.1/src/restic_backups/generic/__init__.py

@@ -0,0 +1 @@
+"""Generic restic repository commands."""